Production Grade Guide

This guide documents the production-grade improvements to AIWG based on academic research analysis.

Production-Grade AIWG Guide

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

This guide documents the production-grade improvements to AIWG based on academic research analysis.

Research Foundation

AIWG production-grade features are grounded in peer-reviewed research:

REF-001: Bandara et al. (2024) "Production-Grade Agentic AI Workflows" (arxiv 2512.08769)
REF-002: Roig (2025) "How Do LLMs Fail In Agentic Scenarios?" (arxiv 2512.07497v2)

Agent Design Bible

The Agent Design Bible defines 10 Golden Rules for building production-grade agents.

Quick Reference

Rule	Name	Key Principle
1	Single Responsibility	One agent, one job
2	Minimal Tools	0-3 tools per agent
3	Explicit I/O	Clear inputs and outputs
4	Grounding First	Verify before acting
5	Escalate Uncertainty	Never guess silently
6	Scoped Context	Filter irrelevant data
7	Recovery-First	Design for failure
8	Model Tier	Match complexity to task
9	Parallel-Ready	Enable concurrent execution
10	Observable	Emit structured logs

Agent Linting

Validate agents against the 10 rules:

Use AIWG to complete this documented outcome: Validate agents against the 10 rules
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Agent Scaffolding

Create new agents using validated templates:

Use AIWG to complete this documented outcome: Create new agents using validated templates
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

LLM Failure Mode Mitigations

REF-002 identifies four failure archetypes. AIWG provides specific mitigations:

Archetype 1: Premature Action Without Grounding

Problem: Agent guesses database schema instead of inspecting it.

Mitigation: Rule 4 (Grounding First)

## Grounding Protocol

Before external operations:
1. List available resources (files, tables, APIs)
2. Verify target exists
3. Inspect structure before manipulation
4. NEVER assume schema from similar names

Archetype 2: Over-Helpfulness Under Uncertainty

Problem: Agent substitutes similar entity when target not found.

Mitigation: Rule 5 (Escalate Uncertainty)

## Uncertainty Protocol

When input cannot be resolved:
1. List candidates with confidence scores
2. Explain why no exact match
3. Ask user to select or provide more context
4. NEVER silently substitute

Archetype 3: Distractor-Induced Context Pollution

Problem: Irrelevant data in context causes errors ("Chekhov's gun" effect).

Mitigation: Context Curator Addon

Use AIWG to complete this documented outcome: Mitigation: Context Curator Addon
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The Context Curator agent scores context as:

RELEVANT: Directly needed for current task
PERIPHERAL: May be useful, keep accessible
DISTRACTOR: Remove from active context

Archetype 4: Fragile Execution Under Load

Problem: Agent enters loops, loses coherence, or makes malformed tool calls.

Mitigation: Resilience Protocol

## PAUSE→DIAGNOSE→ADAPT→RETRY→ESCALATE

1. **PAUSE**: Stop, preserve state
2. **DIAGNOSE**: Classify error type
3. **ADAPT**: Choose different approach
4. **RETRY**: Max 3 adapted attempts
5. **ESCALATE**: Structured report to user

Loop detection triggers when:

Same tool called 3+ times consecutively
Same error occurs 2+ times
Identical outputs from different attempts

@-Mention Traceability

Claude Code 2.0.43 fixed @-mention loading for nested files. AIWG leverages this for live traceability.

Conventions

# Requirements
@.aiwg/requirements/UC-{NNN}-{slug}.md        # Use cases
@.aiwg/requirements/NFR-{CAT}-{NNN}.md        # Non-functional

# Architecture
@.aiwg/architecture/adrs/ADR-{NNN}-{slug}.md  # Decisions

# Security
@.aiwg/security/TM-{NNN}.md                   # Threats
@.aiwg/security/controls/{id}.md              # Controls

# Code
@$AIWG_ROOT/src/{path}                                    # Source
@test/{path}                                   # Tests

Code Integration

Add @-mentions to file headers:

/**
 * @file Authentication Service
 * @implements @.aiwg/requirements/UC-003-user-auth.md
 * @architecture @.aiwg/architecture/adrs/ADR-005-jwt-strategy.md
 * @security @.aiwg/security/controls/authn-001.md
 * @tests @test/integration/auth.test.ts
 */

Wiring Utilities

Use AIWG to complete this documented outcome: Wiring Utilities
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Hooks

AIWG hooks integrate with Claude Code 2.0.43+ lifecycle events.

Trace Hook

Captures agent execution history for debugging and recovery.

// .claude/hooks/aiwg-trace.cjs
// Automatically logs:
// - SubagentStart: agent_id, type, timestamp
// - SubagentStop: agent_id, transcript_path, duration

View traces:

# Tree view
node ~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-hooks/scripts/trace-viewer.mjs tree

# Timeline view
node ~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-hooks/scripts/trace-viewer.mjs timeline

Permission Hook

Auto-approve trusted operations to reduce prompts:

// .claude/hooks/aiwg-permissions.cjs
// Auto-approves:
// - Write to .aiwg/**
// - Read from ai-writing-guide/**
// - Git operations on AIWG branches

Session Hook

Manage named sessions for workflow persistence:

# Generate session name
node aiwg-session.cjs suggest inception-to-elaboration
# Output: aiwg-inception-to-elaboration-2025-01-15-1030

# Record session
node aiwg-session.cjs record aiwg-my-session the workflow option security-review

# List recent sessions
node aiwg-session.cjs list

Prompt Registry

Import prompts directly into CLAUDE.md using @-imports.

Available Prompts

Path	Purpose
`prompts/core/orchestrator.md`	Claude orchestrator guidance
`prompts/core/multi-agent-pattern.md`	Primary→Reviewers→Synthesizer
`prompts/core/consortium-pattern.md`	Multi-expert coordination
`prompts/agents/design-rules.md`	Condensed 10 Golden Rules
`prompts/reliability/decomposition.md`	Task decomposition templates
`prompts/reliability/parallel-hints.md`	Parallel execution patterns
`prompts/reliability/resilience.md`	Recovery protocol

Usage

In your project's CLAUDE.md:

## Orchestration Guidelines

@~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-utils/prompts/core/orchestrator.md

## Multi-Agent Pattern

@~/.local/share/ai-writing-guide/agentic/code/addons/aiwg-utils/prompts/core/multi-agent-pattern.md

Deploy Generators

Generate production-ready deployment configurations.

# Docker (multi-stage, non-root, health checks)
/deploy-gen docker the app-name option myapp the port option 3000

# Kubernetes (SecurityContext, probes, resources)
/deploy-gen k8s the app-name option myapp the port option 3000

# Docker Compose
/deploy-gen compose the app-name option myapp the port option 3000

Generated configurations include:

Multi-stage builds (deps → builder → runner)
Non-root user execution
Health check endpoints
Resource limits
Security contexts
Anti-affinity rules (K8s)

Evals Framework

Automated testing for agent behavior against failure archetypes.

Running Evals

# Test agent against grounding scenario
/eval-agent my-agent the category option archetype the scenario option grounding-test

# Test agent against distractor scenario
/eval-agent my-agent the category option archetype the scenario option distractor-test

# Test recovery behavior
/eval-agent my-agent the category option archetype the scenario option recovery-test

Scenario Types

Scenario	Tests	Pass Criteria
grounding-test	Archetype 1	Agent inspects before acting
distractor-test	Archetype 3	Agent ignores irrelevant data
recovery-test	Archetype 4	Agent recovers from errors

Creating Custom Scenarios

# .aiwg/evals/my-scenario.yaml
name: custom-validation
category: archetype
description: Test custom validation behavior

setup:
  files:
    - path: target.md
      content: |
        # Target Document
        This is the correct target.

validation:
  type: output_contains
  expected: "target.md"
  pass_threshold: 1.0

Agent Personas

Pre-configured agents for common workflows.

Available Personas

Persona	Focus	Model	Permissions
`aiwg-orchestrator`	Full SDLC orchestration	opus	full
`aiwg-reviewer`	Code review	sonnet	write-artifacts
`aiwg-security`	Security audit	sonnet	read-only
`aiwg-writer`	Documentation	sonnet	write-artifacts

Usage

Use AIWG to complete this documented outcome: | Persona | Focus | Model | Permissions | |---------|-------|-------|-------------| | aiwg-orchestrator | Full SDLC orchestration | opus | full | | aiwg-reviewer | Code review | sonnet | write-artifacts | | aiwg-security | Security audit | 
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Multi-Agent Patterns

Primary → Reviewers → Synthesizer

Standard pattern for document generation with review:

Primary Author (opus) → Creates draft
        ↓
Parallel Reviewers (sonnet) → Independent reviews
        ↓
Synthesizer (sonnet) → Merges feedback
        ↓
Archive → .aiwg/[category]/

Key: Launch reviewers in SINGLE message for true parallelism.

Consortium Pattern

Multi-expert coordination with trade-off documentation:

Coordinator (opus)
    ↓
Parallel Experts (sonnet) → Independent analysis
    ↓
Trade-off Matrix → Document disagreements
    ↓
Synthesis → Majority + dissent record

Metrics & Targets

Based on REF-002 benchmarks:

Metric	Target	Source
Grounding compliance	>90%	Archetype 1
Entity substitution rate	<5%	Archetype 2
Distractor error reduction	≥50%	Archetype 3
Recovery success rate	≥80%	Archetype 4
Parallel utilization	>60%	REF-001 BP-9

Quick Start

New Project

Use AIWG to complete this documented outcome: New Project
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Existing Project

Use AIWG to complete this documented outcome: Existing Project
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

References

Agent Design Bible - 10 Golden Rules
REF-001 - Production-Grade Research
REF-002 - LLM Failure Modes
SDLC Framework - Complete lifecycle