AI-Assisted Development Workflow for Claude, Codex, and Copilot
The kit ships an opinionated AI-assisted development workflow, described tool-neutrally in AGENTS.md so any assistant can execute it.
The six phases
Section titled “The six phases”- Functional refinement (analyst) — user verbs, flows, auth gates, gaps, adversarial pass
- Architectural review (architect) — placement, server/client split, invariant compliance
- Technical design (tech-lead) — design doc: contracts, data model, implementation order
- Implementation (database-admin → api-developer → ux-developer, or full-stack for small work; mobile-developer owns shell + mobile)
- Test verification (qa) — unit + e2e + auth audit; PASS / FAIL / BLOCKED
- Shipped-vs-intent (analyst) — the SHIP IT verdict
Every feature gets a work-log file before code (docs/work-log/), classified Trivial / Polish / Feature / Spike. Loop-backs return to the earliest phase where the failure originated.
Which model runs which role
Section titled “Which model runs which role”In Claude Code each role is a subagent under .claude/agents/, and each agent pins both a model and a reasoning effort in its frontmatter. The tier follows the cost of a wrong answer, not the size of the task (DECISION-008):
| Tier | Agents | Why |
|---|---|---|
| opus | architect, database-admin, qa | Invariant compliance and code review; schema and migrations, where the source of truth is the schema and -- VERIFY: predicates run against the deploy target; and the last verdict before ship. |
| sonnet | analyst, tech-lead, api-developer, mobile-developer, ux-developer, full-stack-developer, deployment-engineer | Everything else: work that is contract-driven, lands in a work-log the next phase independently re-derives, and is re-verified by qa and the UX audit checklist. |
Reasoning effort is pinned too — high everywhere except deployment-engineer (medium, since build diagnosis and env-var work is command-and-read).
Rejected alternatives: keeping the previous roster’s fable tier on the two verdict gates (at effort: high its cost ran out of proportion to the judgment it bought, and rubber-stamping is a discipline problem the evidence rules address rather than one a premium model reliably fixes); effort: medium roster-wide (the phases on cheaper models are exactly the ones that need the thinking budget); haiku for any role (no roster agent is a bulk-search role); and inherit (phase quality would drift with whichever model the operator launched the session on). The per-invocation model override remains the escape hatch in both directions — the right tool for a one-off hard task, rather than re-tiering the roster. Other assistants play the roles sequentially with whatever model they run; the phase contract is what’s binding, not the tiering.
Evidence discipline
Section titled “Evidence discipline”A completed phase carries evidence, not checkmarks: claims are either Verified (the implementation was read, file and line range cited) or Indicative (everything else — grep hits, filenames, comments, prior docs). Indicative can motivate a claim and can never support one. Each phase re-derives its predecessor’s load-bearing claims before reading the claimed answers, then diffs — trust is earned per handoff, not assumed. Work-log entries include a “What was NOT verified” section; honesty about the gaps is what makes the ledger useful.
Two honest caveats, stated here because “enforced” invites over-reading. The work-log gate verifies that citations are present; no mechanical check can verify they are true — the derive-then-diff entry check is what does that, and it is a discipline, not a script. And a claim that asserts its own verification (“confirmed by direct search”) is still Indicative: the assertion is not the verification.
Work-logs should be sized to the work. A small feature’s log runs about a hundred lines — see the worked example shipped in the kit — while the kit’s own multi-thousand-line bootstrap logs documented whole construction phases and are the ceiling, not the norm.
Enforcement stack
Section titled “Enforcement stack”| Layer | What enforces it |
|---|---|
Commit grammar + Caught-By/Discovered-In trailers on fixes |
commit-msg git hook + CI range validator |
| No code before the work-log | pre-commit git hook + Claude PreToolUse hook |
| Pre-push verification (typecheck, lint, tests, tripwires) | pre-push git hook running pnpm kit:verify |
| Instruction freshness, symbol drift, secrets, SQL date safety, brand scope | pnpm check tripwire suite, run in CI |
| Escape-rate telemetry | pnpm stats:escape feeds the retrospective |
Assistant-specific hooks (.claude/settings.json) give fast in-session feedback, but the git hooks and CI are the binding layer. The workflow holds no matter which tool wrote the code.