Code Coder

Central execution worker for ad-hoc diffs (and C2 under ns-autonomous). Not front door — host picks entry per ../../ns-harness/references/code-skill-routing.md.

Workflow mode (mandatory)

Fixed workflow, not loose checklist. Steps in order; handoffs = named skills or harness bridges (coder-agent / reviewer-agent per ../../ns-harness/references/subagent-dispatch.md). No platform Task personas or improvised review.

Canonical review gate: ../ns-reviewer/references/review-gate-workflow.md — steps 7–9 ad-hoc / C2 only. Code review only via reviewer-agent then ns-reviewer (MUST bridge when available; else direct); then ns-judge in-session only if Code Review: Approved. Max 3 rounds per gate; Approved = score 10 only. Score 9 = Rejected (Lift + mandatory re-review). No success without both Approved or blocked. After Delivery Review: Approved: Living specs (8) if match, then Final report (9).

Exception — SDD handoff mode: caller run-implementation / execution-handoff.md (or dispatch says SDD task mode): skip review gate + living specs. Parent owns review at version closure. See When invoked under execution-handoff.

Routing (read first)

Entry priority 5 (default). Harness table: ../../ns-harness/references/code-skill-routing.md. Trigger phrases: references/entry-triggers.md.

When to use (entry)

• Bug fixes / hotfixes outside planned version
• Isolated component, hook, service, or utility
• Small refactors (≤ 1 file or tight group)
• Scripts, migrations, seeds outside version lifecycle
• "Just implement this" without execution-handoff.md

When invoked as C2 (engine mode)

ns-autonomous dispatches as work-unit subagent in existing worktree: unit scope only. Do not re-route to ns-execution-gitlab-issue on ISSUE_URL in code/comments — context, not routing. Escalate destructive doubts to caller (A), not GitLab skills. No living-spec consolidator as C2 — version closure/caller owns. Engine / multi-unit C2: implement only — defer review to G Phase 4 or A standalone closure (same as SDD handoff). Complete ad-hoc Review loop only when caller is ad-hoc face and did not say defer review.

When invoked under execution-handoff (SDD task mode)

Parent run-implementation (classic SDD) or dispatch SDD handoff / execution-handoff:

1. Scope: classic = one batch (same-layer consecutive pending, prefer 4–7, hard max 7; size 1 = single task) per references/run-implementation.md. Partitioned slice = that slice's tasks. Parent owns handoff file updates.
2. Read each task card (header through Validation criteria); open Detailed description on demand (ambiguity or blocked) — ../ns-spec-driven/references/task-schema.md.
3. Implement + unit/integration only. No E2E.
4. Forbidden: reviewer-agent / ns-reviewer / ns-judge, living-spec consolidator, Code Review: / Delivery Review: verdict lines.
5. Before report complete: public-export grep (Pre-review). Still no reviewer.
6. Report to parent per task: files changed, tests run, blockers, tokens (split or ~N), Layout SSoT: {path} read | none registered, Skipped / not checked / risk: (format: ../ns-reviewer/references/review-gate-workflow.md Final report). Parent marks rows. Version closure (steps 4–6): references/run-implementation-closure.md — not the per-batch file. Session boot: cold start this agent = full boot per session-boot.md; same agent continuing = no full re-read unless agents.local.md / harness rules changed.

Session boot

See ../../ns-harness/references/session-boot.md. Complete Session boot (blocking) before any other step — cold start only; mid-session skip if already booted and files unchanged. Never tool-Read AGENTS.md.

After session-boot steps 1–6:

• Load all .nextstage-harness/rules/*.md marked always-applicable in harness manifest.json, plus layer rules for target layer.
• Load agent-requested rules when manifest.json description matches task scope (persistence, auth, tenancy, build). No manifest: scan rules/*.md; read files whose scope matches.
• Unread mandatory rules = incomplete boot. Do not pick stack default to fill gap.
• Stack signals: detected stack implies expected sibling rule — ../../ns-harness/references/architecture-rules/stack-signals.md. Rule present: load. Absent: ask or mark needs-clarification — never assume framework default.

Session inputs

Scope isolation

Operate only inside the repo + harness docs.

Boot (mandatory)

Session boot (../../ns-harness/references/session-boot.md) — one rule for ad-hoc, C2, SDD handoff:

Then:

1. Obey AGENTS.md orders (already in context) — no invented paths
2. git status and git diff
3. Read target files before writing

Success: AGENTS.md orders + project rules + task scope. Invented paths or SDD artifacts (except handoff updates when parent owns them) = failure.

Implementation rules

• Constitution over card: card prescribes persistence/API/gate/pattern rules forbid — implement rules path; annotate card deviation: {card} -> {rules} in ## Execution notes. Large/ambiguous deviation: blocked.
• Grounding check before diff: card names class/command absent from repo and rules — stop and report. Do not implement.
• Persistence source: persistence path from architecture-rules.md + mandatory project rules (Session boot). Forbidden to assume ORM or upsert default when rules silent — ask or blocked.
• Rules + code same turn: rule request + code delivers diff same turn, not harness text only.
• Diff-first — only required lines; no unrelated formatting
• Prefer editing existing files over new files
• Minimal change — reuse ladder, no speculative code, root-cause fix at shared callers: references/minimal-change.md
• Large change gate: >1 file simultaneously, >20 lines in one file, or public contract change: one-line plan, wait for approval
• No commits unless human explicitly asks — when committing, see ../../ns-harness/references/agent-git-identity.md
• No SDD version artifacts — no task-NNN.md, requirements.md, execution-handoff.md, or docs/versions/ writes. Conditional living-spec updates under docs/specs/ via ns-living-spec allowed (see Living specs).
• No gratuitous comments unless requested
• Tests per AGENTS.md Docker + testing; container/commands in architecture-rules.md
• Ask before (gate — stop, ask): new dependency; abstraction without 2 concrete uses; DB schema or shared contract change; CI/deploy/infra config; moving files across packages
• Protected tests: paths listed as Domain invariants / protected tests in architecture-rules.md — keep green; never weaken, delete, or skip to pass
• Library divergence: docs/rules disagree with real library API → follow library, report drift
• Under execution-handoff.md / run-implementation: unit/integration only — no E2E (human at version end); no review gate (parent Step 5)

Complement delegation

spec-driven / gitlab presets install complements via depends (check .agents/skills/ once per session). Delegate — do not duplicate their workflows inline.

MR/SOLID review stays ns-reviewer only. Missing complement: continue with harness rules; recommend install once per session (../ns-spec-driven/references/skill-integrations.md).

Per-task cycle

SDD handoff mode: one dispatch may cover a batch; still stop after step 6; report per task to parent; skip 7–9.

1. Understand task
2. Load rules — obey AGENTS.md already booted; Session boot again only if cold start this agent or files changed
3. Explore (grep/head large fixtures — no full test dumps)
4. Identify minimal diff — apply references/minimal-change.md
5. Apply (or plan if large-change gate)
6. Run tests if in scope + public-export grep (Pre-review)
7. Review loop — ad-hoc only: MUST reviewer-agent when available (else ns-reviewer); then ns-judge in-session only if Code Review: Approved; ../ns-reviewer/references/review-gate-workflow.md. Skip when SDD handoff / engine defer.
8. Living specs (conditional) — see below
9. Final report — mandatory fields; never skip verdict or round count

Pre-review (before step 7; also before SDD report complete)

• Run default tier only (unit/integration / default test — see Test tiers in ../../ns-harness/references/docker-and-testing.md). Never run live tier unless human asks this run.
• New tests needing real LLM or live third-party → put in live group/marker; report how to trigger; do not run them.
• Diff removes exports/constants/env flags/public symbols: search remaining call sites; resolve before review.
• List new or newly exported public names (return { }, module.exports, export, public/public static, window/global attach).
• Grep each: no caller outside defining module — keep private/unexported. Continue (ad-hoc: review; SDD: report parent). Forbidden reviewer in SDD handoff.
• Internal/private/nested helpers: keep.

Review loop (mandatory ad-hoc; skip SDD handoff / engine defer)

After step 6, run ../ns-reviewer/references/review-gate-workflow.md before done — except SDD handoff or caller says defer review / engine C2 / G single-unit dispatch (return to parent; no reviewer, no judge). Rejected map/fix/re-review path: that workflow only (exhaustive → one coder → delta + prior IDs) — no restated rubric here.

• MUST invoke reviewer-agent when available (else ns-reviewer) on working-tree diff (git diff) — reviewer bridge/skill begins Session boot at cold start then reviewer workflow; no ISSUE_URL, no version-closure path. Ad-hoc diff only. Reviewer MUST NOT dispatch judge.
• Max 3 code rounds. Code Review: Approved = score 10 only. Rejected/Blocked: do not run ns-judge.
  • Pass: Code Review: Approved (score = 10, zero Criticals). Then read ../ns-judge/SKILL.md in-session (adhoc). Skip AC proof unless --requirements / --ac-file. Max 3 judge rounds. Delivery Review: Approved only at 10. Product files changed after judge Rejected: code review again (must Approved) then judge again.
  • Rejected with rounds left: apply map per review-gate-workflow.md Code rounds (one coder, map verbatim, re-review prompt = delta + prior map IDs). reviewer-agent / ns-reviewer / ns-judge read-only — this skill applies fixes. MUST reviewer-agent when available; else ns-reviewer.
  • Stop: Blocked or call 3 not score 10 or 3 rounds exhausted → report blocked. No coder on Blocked. List unresolved Criticals and/or last score. No success. Skip step 8.
• Fixes within original task scope. Critical (or score-blocking Warning) needs changes outside scope (public contract, cross-product, multi-day): stop, escalate per Stop conditions.
• Suggestions (P2) alone do not block when code Approved. Score 9 still Lift even if only P2.

Living specs (step 8, conditional)

Only after Delivery Review: Approved (not as C2). Invoke ns-living-spec ad-hoc when all true:

1. docs/specs/ exists
2. Diff behavioral (API, schema, UX, or domain behavior) — skip cosmetic / rename-only / pure refactor
3. Skill available (installed via depends)

Pass: mode ad-hoc, {task_description}, approved git diff. Read consolidator SKILL.md, follow it. No invent {version_san} or write under docs/versions/.

Skip (note reason in final report) when any condition fails, delivery not Approved, or consolidator reports skipped.

Final report (step 9)

No success language until both gates pass or blocked (review-gate-workflow.md). SDD handoff: report implement status to parent; no Code Review: / Delivery Review: lines — version closure owns verdict.

Every ad-hoc / C2 closure response must include fields in ../ns-reviewer/references/review-gate-workflow.md Final report, including exact Code Review: and Delivery Review: lines (n/a on delivery if code never Approved).

Then: what changed, follow-ups, blocked Criticals if applicable.

Stop conditions

Related skills

• ns-reviewer — code quality gate after implementation (Review loop)
• ns-judge — delivery proof in-session after Code Review: Approved
• ns-living-spec — conditional ad-hoc living-spec update after Delivery Review: Approved (Living specs)
• ns-investigator — blocked by unclear stack/CI bug
• ns-bug-report-diagnosis — product report / screen story; bounce only if no diagnosis_complete
• ns-autonomous — autonomous multi-agent execution (GitLab issue or local plan); GitLab issue use ns-execution-gitlab-issue instead
• ns-frontend-design — UI/design work (Complement delegation)
• ns-best-practices — security/CSP/a11y hygiene pass (Complement delegation)
• ns-docs-writer — README / docs/ guides on request (Complement delegation)

Forbidden

• SDD version artifact generation (docs/versions/, handoff, requirements/tasks)
• Living-spec consolidator before Delivery Review: Approved, or when docs/specs/ missing
• Out-of-repo access without scope
• Secrets/keys/connection strings in versioned files
• Commits without explicit request
• Refactors outside task scope
• Review substitutes — Cursor Task subagents (senior-tech-lead-reviewer, bugbot, security-review) or any review not via reviewer-agent / ns-reviewer SKILL.md. Harness reviewer-agent allowed. Judge = in-session ns-judge after Approved; no judge-agent in v1
• Judge before code Approved — ns-judge while last Code Review: is not Approved
• Skipping re-review — success after Rejected (including score 9) without a new Approved round on that gate (ad-hoc / C2)
• Success without verdict — ad-hoc / C2 closure without mandatory Final report fields and parseable Code Review: + Delivery Review: lines
• Per-task / mid-batch review under handoff — reviewer-agent / ns-reviewer / ns-judge during run-implementation task or batch (parent owns Step 5)