Autocraft

Autocraft

Five agents. Strict roles. No self-grading. Human in the loop.

The Analyst talks to the human, writes/updates spec.md, and routes feedback. → analyst.md The Builder implements features. Cannot write tests or grade itself. → builder.md The Tester implements the Orchestrator's artifact — State mode writes assertion-based integration tests; Screen mode sharpens a journey.md and spawns a separate Claude instance to run it with vision. Cannot touch production code. → tester.md The Inspector audits both modes — forensic scans for State mode, structural scans + screenshot-evidence review for Screen mode. Only the Inspector sets polished. → inspector.md The Orchestrator routes each criterion by mode, drafts the artifacts, and commits only when the Inspector approves. → orchestrator.md

Separation exists because a builder who writes their own tests optimizes for tests that pass, not tests that prove the feature works.

When to Use

• Building from a spec with acceptance criteria that need independent proof per criterion
• UI projects (screenshot-verified) or pipeline/CLI/library projects (assertion-verified) — or both
• Consolidating/refactoring existing tests into scenario-based integration tests

When NOT to Use

• Single-file bug fix — just fix it directly
• Quick prototyping where stubs are acceptable
• No spec yet — write one (or launch the Analyst) first

Criterion Mode

The Orchestrator routes each acceptance criterion (see orchestrator.md Step 6):

• State mode (integration-test-contract.md) — verification is observable state: API payloads, file contents, DB rows, exit codes
• Screen mode (journey.md) — verification needs eyes on screen: layout, toasts, modals, visual regressions, crash-free interactions
• Hybrid — both artifacts, both must pass

If no criterion routes to a mode, that artifact isn't drafted. If the task has no production code changes, the Builder is skipped. The Inspector runs only the scans matching existing artifacts.

Inputs

$ARGUMENTS is a local spec path, a gist URL/ID, continue, or init.

init — copy {skill-base-dir}/claude-md-template.md to CLAUDE.md at project root (append under a # Autocraft Analyst heading if CLAUDE.md already exists), create autocraft/ if missing, tell the user "Analyst is now always-on in this project; just talk naturally." Do not start the build loop.

Two Analyst files, different jobs. claude-md-template.md is the lightweight always-on Analyst that lives in the user's CLAUDE.md and classifies every casual message. analyst.md is the full role spec the Orchestrator injects when it spawns an Analyst agent during the build loop.

Spec source. Local path → read directly. Gist URL (https://gist.github.com/...) or bare 20+ hex ID → fetch via gh gist view <id> -f spec.md. See orchestrator.md Step 1 for detection rules, gist error handling, and resume logic. Only the Analyst writes to the spec (local file or gist).

Shared State Files

Path resolution. autocraft/ is resolved relative to the spec file's parent directory, not repo root. Single-spec projects (spec.md at root) behave as before. Multi-spec projects can put specs under subdirs — e.g. specs/feature-a/spec.md gets its own specs/feature-a/autocraft/, isolated from other specs. AGENTS.md is the one exception: always at repo root, shared project-wide.

Playbooks

Platform-specific knowledge bases inside this skill at skills/autocraft/playbooks/. The Orchestrator loads them at invocation time and injects the content directly into each agent's prompt (see orchestrator.md Step 2). No network, no gist.

Projects can override via autocraft/config.json ("playbooks_path": "tools/my-playbooks/"). See playbooks.md.

Orchestrator Protocol

The 12-step protocol — launch directives, mode routing, journey drafting, integration contract generation, compliance validation, and loop — is in orchestrator.md.

Common Mistakes

Optional External Skills

These enhance autocraft; none are required.