# v2024.12.1 - Production-Grade Reliability & Extensibility

**Released**: December 10, 2025

Major release introducing **production-grade reliability patterns** based on academic research, the **AIWG Development Kit** for framework extensibility, **MCP Server** for Model Context Protocol integration, and **CLAUDE.md modernization** with path-scoped rules. Context loading reduced by 87% for base sessions.

## Highlights

| What Changed | Why You Care |
|--------------|--------------|
| Research-backed reliability | 10 Golden Rules from peer-reviewed papers |
| Development Kit | Build your own addons, extensions, frameworks |
| MCP Server | Model Context Protocol integration |
| Modular CLAUDE.md | 87% context reduction (1,018 → 134 lines) |
| npm package | `npm install -g aiwg` |
| 8 new addons | Hooks, evals, context curator, and more |
| @-mention traceability | Wire requirements to code to tests |

## Research Foundation

Integrated findings from two peer-reviewed papers:

### REF-001: Production-Grade Agentic AI Workflows
Bandara et al. (2025) - 9 best practices:
- BP-1: Direct tool calls over MCP for determinism
- BP-3: One agent, one responsibility principle
- BP-4: Single-responsibility agents
- BP-5: Externalized prompts in version control
- BP-6: Multi-model consortium for high-stakes outputs

### REF-002: How Do LLMs Fail In Agentic Scenarios?
Roig (2025) - 4 failure archetypes:
- Archetype 1: Premature Action Without Grounding
- Archetype 2: Over-Helpfulness Under Uncertainty
- Archetype 3: Distractor-Induced Context Pollution
- Archetype 4: Fragile Execution Under Load

**Key finding**: Recovery capability > model size for success

## Development Kit

Three-tier plugin taxonomy for extensibility:

| Type | Scale | Use Case |
|------|-------|----------|
| Framework | 50+ agents | Complete domain (SDLC, Marketing) |
| Extension | 5-20 agents | Framework enhancement (GitHub, Python) |
| Addon | 1-10 agents | Focused capability (Voice, Hooks) |

### CLI Scaffolding

```bash
# Create addon
aiwg scaffold-addon my-utils --description "My utilities"

# Add components
aiwg add-agent code-helper --to my-utils --template simple
aiwg add-command analyze --to my-utils --template utility

# Validate
aiwg validate my-utils --fix
```

### In-Session Commands

```text
/devkit-create-addon my-utils --interactive
/devkit-create-agent code-helper --to my-utils
/devkit-validate my-utils
```

## MCP Server

Complete Model Context Protocol implementation:

### Tools
- `workflow-run` - Execute AIWG workflows
- `artifact-read` / `artifact-write` - Manage .aiwg/ artifacts
- `template-render` - Render templates with variables
- `agent-list` - List available agents

### Resources
- `aiwg://prompts/catalog` - Prompts catalog
- `aiwg://templates/catalog` - Templates catalog
- `aiwg://agents/catalog` - Agents catalog

### Usage

```bash
# Start server
aiwg mcp serve

# Install for client
aiwg mcp install claude   # Claude Desktop
aiwg mcp install cursor   # Cursor IDE

# View info
aiwg mcp info
```

## CLAUDE.md Modernization

New modular structure reduces context by 87%:

| Context | Lines | When Loaded |
|---------|-------|-------------|
| Base | 134 | Always |
| SDLC | +180 | Working in .aiwg/ |
| Voice | +75 | Working in *.md |
| Dev | +85 | Working in src/, test/ |

### Path-Scoped Rules

Rules in `.claude/rules/` load automatically based on file paths:
- `sdlc-orchestration.md` - Loaded for `.aiwg/**`
- `voice-framework.md` - Loaded for `**/*.md`
- `development.md` - Loaded for `src/**`, `test/**`

## New Addons

| Addon | Purpose |
|-------|---------|
| aiwg-hooks | Workflow tracing (SubagentStart/Stop events) |
| aiwg-evals | Automated agent quality assessment |
| context-curator | Distractor filtering (Archetype 3) |
| aiwg-utils | Reliability prompts, workspace commands |

### aiwg-hooks

```javascript
// .claude/hooks/aiwg-trace.js
// Captures SubagentStart/SubagentStop events
// JSONL trace format for debugging
```

View traces:
```bash
node trace-viewer.mjs tree
node trace-viewer.mjs timeline
```

### aiwg-evals

Automated testing against failure archetypes:

```bash
/eval-agent my-agent --category archetype --scenario grounding-test
/eval-agent my-agent --category archetype --scenario distractor-test
/eval-agent my-agent --category archetype --scenario recovery-test
```

## @-Mention Traceability

Wire artifacts together with @-mentions:

```bash
# Analyze and inject @-mentions
/mention-wire --target .aiwg/requirements/

# Validate all mentions resolve
/mention-validate

# Generate traceability report
/mention-report
```

### Patterns

```text
@.aiwg/requirements/UC-{NNN}-{slug}.md    # Use cases
@.aiwg/architecture/adrs/ADR-{NNN}.md     # Decisions
@.aiwg/security/TM-{NNN}.md               # Threats
@.aiwg/testing/test-cases/TC-{NNN}.md     # Tests
```

## npm Package

Now available on npm:

```bash
npm install -g aiwg
aiwg -version
```

## Migration

### CLAUDE.md Modernization

```bash
# Backup created automatically
/aiwg-regenerate-claude

# Review .claude/rules/ files
ls .claude/rules/

# Add custom content below marker
<!-- TEAM DIRECTIVES -->
```

### Reliability Prompts

Import in your CLAUDE.md:
```markdown
See @~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-utils/prompts/reliability/resilience.md
```

## Resources

- [Quick Start](#quickstart)
- [Agent Design](#ref-agent-design) - 10 Golden Rules
- [Production-Grade Guide](#ref-production-grade)
- [CLI Reference](#ref-cli)
- [GitHub Release](https://github.com/jmagly/aiwg/releases/tag/v2024.12.1)