write-code

name	write-code
description	Delegated implementation primitive used by /implement for broader changes. Writes a brief, runs implementer/reviewer relay, cleanup, and completion report.
argument-hint	<ticket-path or inline description> [--ticket <stem>]

Write Code

Target: $ARGUMENTS

Invariants

• Operates on the current branch — branch creation is the caller's responsibility.
• Implementer reads only the brief — never the ticket directly.
• Fit reviewer may reference the ticket for architectural headroom checks; correctness and test reviewers do not.
• When skeleton exists, its contracts and integration tests are the acceptance criteria.
• Ancestor loading: when implementer reads mental-model/<domain>/<sub>.md, it reads mental-model/<domain>/index.md first. Lead propagates this rule in the implementer spawn prompt.
• Reviewers write findings to files; lead reads summaries only; implementer reads files directly when non-clean.
• Implementer and reviewer sessions persist via ws-call-named-agent auto-resume throughout the review loop.
• Review cycle cap: 3 relays maximum. Lead adjudicates at cycle 2; caller escalation at cycle 3.
• Self-cleanup: review path files are deleted before returning.
• On completion, output the commit range, test status, and brief path in the format defined in Templates.

On: invoke

0. Orient

1. Read target

Parse $ARGUMENTS: extract ticket path or inline description, and optional --ticket <stem>. If ticket-driven: read the ticket. Extract scope, stem, and phase context.

Register and call project-survey:

ws-new-named-agent project-survey -p project-survey --no-doc-system

ws-call-named-agent project-survey - <<'PROMPT'
<ticket path or inline description>
PROMPT

Capture the returned [Must|Maybe] reference list — it informs the brief's ## References section.

2. Write brief

Write ai-docs/.plans/YYYY-MM/DD-<stem>.brief.md using the brief template (see Templates). Strip ticket noise — this file is the implementer's sole context source. Populate ## References from the project-survey output.

Commit the brief file before proceeding to plan depth.

3. Plan depth

Apply judge: plan-depth. Default to survey when uncertain between as-is and survey.

as-is — proceed to step 4.

survey — register and call plan surveyor (sonnet):

ws-new-named-agent plan-surveyor -p plan-populator-survey

ws-call-named-agent plan-surveyor - <<'PROMPT'
Brief path: <brief-path>
Plan path: ai-docs/.plans/YYYY-MM/DD-<stem>.md
PROMPT

research — register and call plan researcher (opus):

ws-new-named-agent plan-researcher -p plan-populator-research

ws-call-named-agent plan-researcher - <<'PROMPT'
Brief path: <brief-path>
Plan path: ai-docs/.plans/YYYY-MM/DD-<stem>.md
PROMPT

After the population agent returns, commit the plan file before proceeding.

4. Prepare

1. Collect existing skeleton references from ticket frontmatter, todo!()/unimplemented/NotImplementedError stubs, or integration tests referencing target contracts.
2. Collect integration test context: identify test file paths and the run command. Include skeleton tests only when skeleton references exist.
3. Register all agent slots:

   ws-new-named-agent implementer -p implementer
   ws-new-named-agent reviewer-correctness -p code-reviewer -p code-review-correctness
   ws-new-named-agent reviewer-fit -p code-reviewer -p code-review-fit
   ws-new-named-agent reviewer-test -p code-reviewer -p code-review-test
   

4. Allocate review path slots (separate Bash call); capture all output lines as literals:

   ws-review-path correctness fit test
   

   Store as <correctness-path>, <fit-path>, <test-path>.

5. Spawn implementer

Issue the Bash call with run_in_background: true. Read output after notification.

ws-call-named-agent implementer - <<'PROMPT'
Brief path: <brief-path>
<if plan exists:> Plan path: <plan-path>

Read only the brief (and plan if provided). Do not read the ticket directly.

Acceptance criteria:
<if skeleton exists:> Existing skeleton contracts must be satisfied, and skeleton integration tests must pass.
<if no skeleton exists:> Brief-scoped implementation tests must pass.
- Test files: <integration test paths>
- Run: <command to execute them>

Ancestor loading: when you read `ai-docs/mental-model/<domain>/<sub>.md`,
read `ai-docs/mental-model/<domain>/index.md` first.

Instructions:
- Verify integration tests pass before reporting completion or after each fix.
- Report completion in plain text. Include test results.
- For fix cycles, a follow-up call will arrive with review findings — fix and report back.
- Commit at logical checkpoints on the current branch.
PROMPT

After notification:

ws-print-named-agent-output implementer

Note the commit range from the report.

6. Review

6a. Partition allocation

Apply judge: partition-allocation based on the implementer's report and the nature of changes. Choose the smallest reviewer set that covers material risk. Record skipped partitions with one-line rationale. Prepare 2-4 review focus bullets for each selected partition.

6b. Spawn reviewers

Spawn one reviewer per selected partition in parallel (run_in_background: true each). After all notifications, read each summary via ws-print-named-agent-output <name>.

ws-call-named-agent reviewer-correctness - <<'PROMPT'
Diff range: <first-commit>..<last-commit>

Instructions:
- Review focus: <2-4 correctness invariants to verify>.
- Ignore outside this partition unless directly broken by the diff.
- Write your full findings to: <correctness-path>
- Return only: [clean|non-clean]: <one-line summary of most significant issues>
PROMPT

ws-call-named-agent reviewer-fit - <<'PROMPT'
Diff range: <first-commit>..<last-commit>
Brief path: <brief-path>

Instructions:
- Review focus: <2-4 fit or architecture concerns to verify>.
- Ignore outside this partition unless directly broken by the diff.
- Judge whether the implementation achieves what the brief intended and leaves room for future phases.
- You may reference the ticket at <ticket-path> for architectural headroom checks (optional).
- Write your full findings to: <fit-path>
- Return only: [clean|non-clean]: <one-line summary of most significant issues>
PROMPT

ws-call-named-agent reviewer-test - <<'PROMPT'
Diff range: <first-commit>..<last-commit>

Instructions:
- Review focus: <2-4 coverage or assertion risks to verify>.
- Ignore outside this partition unless directly broken by the diff.
- Write your full findings to: <test-path>
- Return only: [clean|non-clean]: <one-line summary of most significant issues>
PROMPT

6c. Relay and loop

Track relay cycle count starting at 0. Maximum 3 relay cycles.

Entry: All [clean] → exit loop, proceed to cleanup.

Relay (run_in_background: true). Increment cycle counter before each relay.

ws-call-named-agent implementer - <<'PROMPT'
Review cycle <N>: <non-clean review paths only>. Read each file directly.
For each finding respond with a disposition: [fixed], [won't fix: <reason>], or [deferred: <reason>].
Won't-fix allowed: style suggestions conflicting with established codebase patterns; suggestions that expand scope beyond the brief.
Won't-fix not allowed: correctness, security, or contract violations — fix or escalate these.
PROMPT

After notification: ws-print-named-agent-output implementer. Extract the won't-fix list.

Re-review only partitions that returned [non-clean]; clean partitions remain accepted unless the fix commit touched their owned surface. Reviewers overwrite their own files.

ws-call-named-agent reviewer-correctness - <<'PROMPT'
Re-review. Updated diff: <diff>
Implementer won't-fix items: <list with reasons>
For each won't-fix item: respond [accepted] or [maintained: <brief reason>].
PROMPT

ws-call-named-agent reviewer-fit - <<'PROMPT'
Re-review. Updated diff: <diff>
Implementer won't-fix items: <list with reasons>
For each won't-fix item: respond [accepted] or [maintained: <brief reason>].
PROMPT

ws-call-named-agent reviewer-test - <<'PROMPT'
Re-review. Updated diff: <diff>
Implementer won't-fix items: <list with reasons>
For each won't-fix item: respond [accepted] or [maintained: <brief reason>].
PROMPT

After all notifications, read summaries.

Branch on cycle and result:

• All [clean] → exit loop, proceed to cleanup.
• Cycle ≤ 2 and non-clean → go to relay.
• Cycle = 2 and maintained items exist: lead reads review files directly. For each maintained dispute: accept the won't-fix or override it. If any overrides: relay override list to implementer (counts as cycle 3 relay). Otherwise advance to cycle 3 re-review directly.
• Cycle = 3 and non-clean remain: collect unresolved findings. Proceed to cleanup, surface escalation in output.

7. Cleanup

rm -f <correctness-path> <fit-path> <test-path>

Agent registry entries need no teardown — created fresh per run via ws-new-named-agent.

Output the completion report (see Templates).

Judgments

judge: plan-depth

Soft judgment. Default to survey when uncertain between as-is and survey.

Signal	Suggests
Brief names concrete change points; single-file or single-function scope	as-is
Multi-module span; cold implementer; reuse points likely but unconfirmed	survey
Multiple viable strategies; non-obvious cross-module side effects	research

judge: partition-allocation

Soft judgment. Prefer the smallest partition set that covers material risk. When uncertain, add one secondary partition rather than defaulting to all three. Full review is reserved for risks spanning correctness, fit, and tests.

Partition	Assign when
Correctness	New logic introduced, error paths modified, contracts or security surface touched
Fit	Existing components reused or modified, new patterns others will follow
Test	Test files added or modified, or new code paths added without existing coverage
Correctness + Test	Executable behavior changed and coverage is material
Correctness + Fit	Workflow/API semantics changed without a meaningful test surface
Full	Cross-cutting behavior plus runtime/tooling plus test surface, or release/security/data-loss boundary
Floor	Purely mechanical change → lead-only or one reviewer with rationale

Templates

Brief format

Path: ai-docs/.plans/YYYY-MM/DD-<stem>.brief.md

# Brief: <stem>

## Intent
<what this achieves — one paragraph>

## Approach
<macro-level how — bullets>

## Constraints
<must-hold conditions>

## Out of scope
<explicitly excluded from this implementation>

## Details
<interface specs, data types, public contracts at ticket-level resolution>
<required when no skeleton references exist; may be omitted when skeleton provides contracts>

## References
<!-- Populated from project-survey [Must/Maybe] output. -->
<!-- [Must] entries: read before starting. [Maybe] entries: consult if uncertain. -->
- `ai-docs/mental-model/<path>` — <relevance>

Completion report format

Implementation complete.
Commit range: <first>..<last>
Brief: <brief-path>
Test status: pass | fail | skipped
<if escalated:> Escalation: <list of unresolved disputes>

Doctrine

Write-code optimizes for brief-to-commit throughput within a branch — every step exists to move a target from intent (brief) to verified code (commits) without the caller managing internal agent state. Self-cleanup of review paths keeps the caller's context clean. When a rule is ambiguous, apply whichever interpretation advances the commit without widening the caller's coordination surface.