Development

External / Ask review

Implement the specification through code

Hats
3
Review Agents
5 +3
Review
External, ask
Unit Types
Backend, Frontend, Fullstack
Inputs
Inception, Design, Design, Design, Product, Product

Dependencies

Inceptiondiscovery
Designdesign-brief
Designdesign-tokens
Designdesign-artifacts
Productbehavioral-spec
Productdata-contracts

Hat Sequence

1

Builder

Focus: Implement code to satisfy completion criteria, working in small verifiable increments. Quality gates (tests, lint, typecheck) provide continuous feedback — treat failures as guidance, not obstacles.

Produces: Working code committed to the branch in incremental commits.

Reads: Planner's tactical plan, unit spec via the unit's ## References section.

Anti-patterns (RFC 2119):

  • The agent MUST NOT build without reading the completion criteria first
  • The agent MUST NOT disable lint, type checks, or test suites to make code pass
  • The agent MUST NOT continue past 3 failed attempts without documenting a blocker
  • The agent MUST commit working increments — large uncommitted changes get lost on context reset
  • The agent MUST NOT attempt to remove or weaken quality gates

When stuck, the agent MUST apply the node repair operator in order: retry (transient failure, max 2 attempts) then decompose (break into smaller subtasks) then prune (try alternative approach) then escalate (document blocker for human intervention). The agent MUST NOT skip levels.

2

Planner

Focus: Read the unit spec and prior stage outputs, plan the implementation approach, identify files to modify, assess risks, and search for relevant learnings. The plan is a tactical document — specific enough for the builder to execute without guessing.

Produces: Tactical plan saved as state, including files to modify, implementation steps, verification commands, and risk assessment.

Reads: Unit spec, behavioral-spec, and data-contracts via the unit's ## References section.

Anti-patterns (RFC 2119):

  • The agent MUST NOT plan without reading the completion criteria
  • The agent MUST NOT copy a previous failed plan without changes
  • The agent MUST identify risks or potential blockers up front
  • The agent MUST NOT skip verification steps in the plan
  • The agent MUST NOT plan more work than can be completed in one bolt

Informed by git history analysis — high-churn files need extra care, stable files need communication, recent refactors indicate directional intent. Use relevance-ranked learning search to find applicable patterns from past work. Apply rule-based decision filtering to evaluate candidate approaches against project constraints.

3

Reviewer

Focus: Verify implementation satisfies completion criteria through multi-stage review. Stage 1: spec compliance (does it do what the criteria say?). Stage 2: code quality (is it well-written?). Stage 3: operational readiness (conditional — only when deployment/monitoring/operations blocks are present).

Produces: Structured review decision — APPROVED or REQUEST CHANGES — with confidence-scored findings.

Reads: Unit criteria, implementation code, quality gate results.

Anti-patterns (RFC 2119):

  • The agent MUST NOT approve without running verification commands
  • The agent MUST NOT trust claims ("I tested it") over evidence (actual test output)
  • The agent MUST NOT block on low-confidence style issues
  • The agent MUST check all three artifact levels: existence, substance, and wiring
  • The agent MUST NOT approve code that lacks tests for new functionality

The agent MUST apply chain-of-verification (CoVe) for each criterion: form initial judgment, generate verification questions, answer with evidence, revise if needed. For non-trivial units, the agent MUST delegate to specialized review agents (correctness, security, performance, etc.) and consolidate findings.

Review Agents

Architecture

Mandate: The agent MUST verify the implementation follows the project's architectural patterns and does not introduce structural debt.

Check:

  • The agent MUST verify that new code follows existing module boundaries and dependency directions
  • The agent MUST verify that no circular dependencies introduced
  • The agent MUST verify that public APIs are minimal — implementation details are encapsulated
  • The agent MUST verify that naming conventions match the codebase (not the agent's preference)
  • The agent MUST verify that no unnecessary abstractions or premature generalizations
  • The agent MUST verify that changes to shared code consider all consumers

Correctness

Mandate: The agent MUST verify the implementation correctly satisfies the behavioral specification and completion criteria.

Check:

  • The agent MUST verify that all acceptance criteria from the behavioral spec are implemented, not approximated
  • The agent MUST verify that error handling covers the specified error states, not just the happy path
  • The agent MUST verify that data validation matches the data contracts exactly (types, nullability, ranges)
  • The agent MUST verify that no logic errors, off-by-one mistakes, or silent failures
  • The agent MUST verify that edge cases specified in the product stage are handled

Performance

Mandate: The agent MUST identify performance regressions or inefficiencies in the implementation.

Check:

  • The agent MUST verify that no N+1 query patterns or unbounded data fetches
  • The agent MUST verify that database queries use appropriate indexes (check against schema)
  • The agent MUST verify that large collections are paginated, not loaded entirely into memory
  • The agent MUST verify that no blocking operations on hot paths
  • The agent MUST verify that caching is used where specified, with correct invalidation
  • The agent MUST verify that bundle size impact is reasonable for frontend changes

Security

Mandate: The agent MUST identify security vulnerabilities introduced by the implementation.

Check:

  • The agent MUST verify that no injection vectors (SQL, command, XSS, template injection)
  • The agent MUST verify that authentication and authorization checks are present on all protected paths
  • The agent MUST verify that secrets are not hardcoded or logged
  • The agent MUST verify that input validation occurs at system boundaries
  • The agent MUST verify that no insecure defaults (permissive CORS, debug mode, disabled TLS verification)
  • The agent MUST verify that dependencies do not have known critical vulnerabilities

Test Quality

Mandate: The agent MUST verify tests actually validate behavior, not just exercise code paths.

Check:

  • The agent MUST verify that tests assert on behavior and outcomes, not implementation details
  • The agent MUST verify that test names describe the scenario and expected result
  • The agent MUST verify that edge cases from the behavioral spec have corresponding tests
  • The agent MUST verify that no tests that always pass (tautological assertions, mocked everything)
  • The agent MUST verify that integration tests cover system boundaries (API, database, external services)
  • The agent MUST verify that test data is realistic, not minimal placeholder values

Development

Criteria Guidance

Good criteria examples:

  • "All API endpoints return correct status codes for success (200/201), validation errors (400), auth failures (401/403), and not-found (404)"
  • "Test coverage is at least 80% for new code, with unit tests for business logic and integration tests for API boundaries"
  • "No TypeScript any types in new code without a documented justification comment"

Bad criteria examples:

  • "API works correctly"
  • "Tests are written"
  • "Types are correct"

Completion Signal (RFC 2119)

All completion criteria MUST pass verification (tests, lint, typecheck). Code MUST be committed to the branch. Reviewer MUST have approved. All quality gates MUST pass. No high-confidence blocking issues SHALL remain.