write-code

What this skill does

# Write Code

Orchestrates the complete TDD lifecycle by composing atomic skills into a sequential pipeline, taking a feature instruction and driving it through project setup, design discovery, skeleton drafting, implementation, test fixing, optimization, and refactoring to produce production-ready, fully tested code. **Coherence Mandate.** Every edit must produce one continuous, deliberate work. Rewrite over restructure, restructure over integrate, never append. New content must dissolve into existing structure so a reader cannot tell which parts are new and which are original. Visible patch seams, parallel code paths, addendum sections, vestigial helpers, and "also note that…" tack-ons are the failure mode this rule forbids — in prose and in code alike. Because this orchestrator threads work through skeleton, implementation, fix, and refactor in turn, each downstream pass must absorb the previous one rather than sit beside it — the finished module should read as if a single author had written it in one sitting, with no archaeology of the staged passes visible in its surface.

## Purpose & Scope

**What this command does NOT do**:

- Create only a skeleton without implementation (use `/coding:draft-code`)
- Complete only TODO-marked placeholders (use `/coding:complete-code`)
- Fix only test/lint/type issues (use `/coding:fix`)
- Refactor without the full lifecycle (use `/coding:refactor`)
- Perform code review (use `/coding:review`)

**When to REJECT**:

- If the user only wants a scaffold/skeleton -> tell them to use `/coding:draft-code`
- If the user only wants to complete existing TODOs -> tell them to use `/coding:complete-code`
- If the user only wants to fix failing tests/lint/types -> tell them to use `/coding:fix`
- If the user has explicitly asked for a stack and only a stack (no implementation) -> redirect them to `/coding:commit --create-pr` directly
- If the instruction is too vague to define acceptance criteria
- If the target project has no testing framework configured

## Composition Structure

This is a **composite skill** that orchestrates the following atomic skills in sequence. Each child skill runs in `context: fork` and receives the `--from-composite` flag to suppress redundant confirmation gates.

```
write-code (this orchestrator)
  |
  |-- 1. Skill: coding:setup-project   (conditional: only if no project exists)
  |-- 2. Skill: coding:draft-code      (Steps 0-1: design discovery + skeleton)
  |-- 3. Skill: coding:complete-code   (Step 2: implementation / green phase)
  |-- 4. Skill: coding:fix             (Steps 3-4: fix issues + optimize fixtures)
  |-- 5. Skill: coding:refactor        (Step 5: refactor + documentation)
  |-- 6. Skill: coding:commit --create-pr  (conditional: only if change is large or upstream stack exists)
```

### State Handover Between Steps

State is passed between child skills via handover documents (CONTEXT.md, NOTES.md, PLAN.md). Each child skill reads these documents for context and updates them upon completion.

### Resume Support

When `--resume` is provided, the orchestrator reads handover documents to determine which step to resume from:
- Files with `need-draft` -> resume from `coding:draft-code`
- Files with `need-completion` -> resume from `coding:complete-code`
- Files with `need-fixing` -> resume from `coding:fix`
- Files with `need-refactoring` -> resume from `coding:refactor`

### Composite Convention

When calling child skills, this orchestrator passes `--from-composite` as an argument. Child skills receiving this flag suppress their own confirmation gates and trust the orchestrator to handle user interaction.

## Workflow

ultrathink: you'd perform the following steps

### Step 1: Parse Arguments

1. **Extract Instruction**
   - Parse `<instruction>` from $ARGUMENTS
   - Identify feature requirements, scope, and acceptance criteria
   - If instruction is ambiguous, ask for clarification before proceeding

2. **Detect Resume Mode**
   - Check if `--resume` flag is present in $ARGUMENTS
   - If `--resume`:
     - Search for handover documents (CONTEXT.md, NOTES.md, PLAN.md) in the working directory
     - Parse file substates from CONTEXT.md to determine which skill to resume from
     - Extract change direction from PLAN.md next steps or NOTES.md open questions
     - If handover files are missing, reject with: "No handover files found. Create them first with `/coding:handover`"

### Step 2: Conditional Project Setup

Check if the target project has essential structure (package.json, source directories, test framework).

- **If project is NOT set up**: Invoke `coding:setup-project` with the target path and `--from-composite`
- **If project IS set up**: Skip this step

### Step 3: Draft Code Skeleton (design + skeleton)

Invoke `coding:draft-code` with the parsed instruction and `--from-composite`.

This skill handles:
- Design direction discovery (searching for DESIGN.md, handover docs)
- Code skeleton creation with TODO placeholders
- Test structure creation with describe.todo/it.todo patterns
- TypeScript and lint validation of the skeleton

**Interactive gate**: After this skill completes, present the user with options:
1. Proceed to implementation
2. Request changes to the skeleton (re-run draft-code with change direction)
3. Resume from a different step
4. Pause and create handover documentation

### Step 4: Implementation (green phase)

Invoke `coding:complete-code` with the target area and `--from-composite`.

This skill handles:
- Replacing TODO placeholders with minimal working implementations
- TDD Green phase: implementing just enough code to make tests pass
- Continuous test execution to verify progress

**Interactive gate**: After this skill completes, present the user with options:
1. Proceed to fixing
2. Request changes to implementation (re-run complete-code with direction)
3. Resume from a different step
4. Pause and create handover documentation

### Step 5: Fix Issues and Optimize (fix + optimize)

Invoke `coding:fix` with the target area and `--from-composite`.

This skill handles:
- Fixing test issues and standards compliance
- Critical root cause analysis for test failures
- Optimizing test fixtures and mocks
- Batch processing for large file sets (>25 files)

**Interactive gate**: After this skill completes, present the user with options:
1. Proceed to refactoring
2. Request changes to fixes (re-run fix with specific notes)
3. Resume from a different step
4. Pause and create handover documentation

### Step 6: Refactor and Document

Invoke `coding:refactor` with the target area and `--from-composite`.

This skill handles:
- Code structure improvements without changing functionality
- Naming convention enforcement
- Comprehensive JSDoc documentation
- Final quality validation (tests, lint, types, coverage)

**Interactive gate**: After this skill completes, present the user with options:
1. Complete the workflow
2. Request changes to refactoring (re-run refactor with focus)
3. Resume from a different step
4. Pause and create handover documentation

### Step 7: Conditional Stack Split

After refactor lands and BEFORE reporting, decide whether the resulting change should be sliced into a stack of ordered draft PRs, or whether an existing open stack needs restacking. The orchestrator NEVER invokes `jj split` / `gh pr create` directly -- it always delegates to `coding:commit --create-pr`.

1. **Compute change size** via `jj diff --summary --stat` (preferred when the working copy is jj-colocated) or `git diff --shortstat HEAD` as fallback. Capture: changed-file count and LOC diff.

2. **Detect open stack**: scan for bookmarks matching `<branch-prefix>/NN-<scope>` (e.g. `jj bookmark list` / `git branch --list '*/[0-9][0-9]-*'`).

3. **Apply triggers**:
   - **Large change** -- `>5 changed files OR >300 LOC diff OR multiple loosely-coupled domains`. Dispatch `coding:commit --create-pr --from-composite` (split + stacked-PR flow) to slice the working copy into reviewable,