Code Factory Overview

The Code Factory harness is a drop-in scaffolding system that adds AI-native development to any codebase. It provides composable AI Developer Workflows (ADWs), Claude Code hooks, slash commands, and closed-loop feedback systems.

Four Core Principles

Core Four — Every ADW call is tuned on four axes:

• Context — What the agent needs to know
• Model — Claude Sonnet (default) or Opus for complex tasks
• Prompt — Slash commands in .claude/commands/
• Tools — Which Claude Code tools the agent can use

PITER Loop — The execution cycle:

flowchart LR
    P[Plan] --> I[Implement]
    I --> T[Trigger]
    T --> E[Execute]
    E --> R[Review]
    R --> P

Closed-loop feedback — Execute → validate → correct until positive. No PR opens without passing validation.

Context engineering — Reduce and delegate. A focused agent outperforms a general one. Each phase receives only what it needs.

What's Included

.claude/
  settings.json         — permissions + hooks
  commands/             — 15+ slash command templates
  hooks/                — safety + observability scripts

adws/
  adw_modules/          — 8-module ADW engine
  adw_plan.py           — planning phase
  adw_build.py          — build phase
  adw_test.py           — test phase
  adw_plan_build.py     — plan + build combined
  adw_sdlc.py           — full SDLC pipeline
  adw_triggers/
    trigger_cron.py     — polls GitHub every 20s
    trigger_webhook.py  — webhook server (port 8001)

specs/                  — generated implementation plans
agents/                 — ADW runtime state per run
logs/                   — hook execution logs
scripts/                — project start/stop/reset scripts

The ADW Pipeline

flowchart TD
    A[GitHub Issue] --> B[classify_issue]
    B --> C{Type?}
    C -->|feature| D[/feature command]
    C -->|bug| E[/bug command]
    C -->|chore| F[/chore command]
    D --> G[build_plan → specs/]
    E --> G
    F --> G
    G --> H[implement_plan → code changes + commits]
    H --> I[run_tests → unit + E2E validation]
    I --> J[create_pr → PR with description]

State persists across all phases via agents/{adw_id}/adw_state.json, so any phase can be retried independently.

Principles in Practice

One Agent, One Prompt, One Purpose — Every slash command does one job. The planner doesn't implement. The implementor doesn't review. Their prompts live in .claude/commands/ and can be version-controlled and improved individually.

The Plan IS the Prompt — The spec written by /feature, /bug, or /chore is not documentation — it is the prompt the implementor reads. Better issues produce better specs, which produce better implementations.

Reduce and Delegate Context — Every agent call passes only what that phase needs. The planner gets the issue title and body. The implementor gets the spec file path. Nothing more.

Review vs Testing — adw_test.py asks "does it work?" adw_review.py asks "is what we built what we asked for?" Different questions, different information, different agents.

Always Add Feedback Loops — The system will not open a PR without passing validation. The review phase auto-generates patches for blockers and re-implements. The test phase auto-resolves failures.

Fix the System, Not the Issue — When an agent fails repeatedly on a type of task, fix the slash command prompt in .claude/commands/, not the individual run. Every improvement propagates to all future runs.

Docs Are Agent Memory — app_docs/ is written by adw_document.py and read by future planning agents. It is persistent context — not for humans first.