v2024.12.1

Previous release

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 ChangedWhy You Care
Research-backed reliability10 Golden Rules from peer-reviewed papers
Development KitBuild your own addons, extensions, frameworks
MCP ServerModel Context Protocol integration
Modular CLAUDE.md87% context reduction (1,018 → 134 lines)
npm package`npm install -g aiwg`
8 new addonsHooks, evals, context curator, and more
@-mention traceabilityWire 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:

TypeScaleUse Case
Framework50+ agentsComplete domain (SDLC, Marketing)
Extension5-20 agentsFramework enhancement (GitHub, Python)
Addon1-10 agentsFocused capability (Voice, Hooks)

CLI Scaffolding

# 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

/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

# 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%:

ContextLinesWhen Loaded
Base134Always
SDLC+180Working in .aiwg/
Voice+75Working in *.md
Dev+85Working 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

AddonPurpose
aiwg-hooksWorkflow tracing (SubagentStart/Stop events)
aiwg-evalsAutomated agent quality assessment
context-curatorDistractor filtering (Archetype 3)
aiwg-utilsReliability prompts, workspace commands

aiwg-hooks

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

View traces:

node trace-viewer.mjs tree
node trace-viewer.mjs timeline

aiwg-evals

Automated testing against failure archetypes:

/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:

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

# Validate all mentions resolve
/mention-validate

# Generate traceability report
/mention-report

Patterns

@.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:

npm install -g aiwg
aiwg -version

Migration

CLAUDE.md Modernization

# 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:

See @~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-utils/prompts/reliability/resilience.md

Resources