Skip to main content
skill CX Codex

ns-coder — Claude Code skill: what it does, how to install

ns-coder handles focused code changes such as fixes, small refactors, scripts, and migrations. Use it for ad-hoc work outside a multi-stage SDD handoff.

Apache-2.0 151 installs updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nextstage-brasil/skills --skill ns-coder -a claude-code
Open on GitHub

What ns-coder does

The skill takes a bounded coding task, checks repository guidance and target files, then makes the change. Its scope includes fixes outside a planned release, isolated components or utilities, small refactors, scripts, and migrations. It is not the route for work that arrives with execution-handoff.md.

On a cold start, ns-coder loads the project rules for the target layer, checks Git state, and reads the files it will edit. Ad-hoc work follows a review cycle; in SDD handoff mode, the parent handles review and receives a per-task report instead. An ISSUE_URL routes the work to ns-execution-gitlab-issue, while an unclear stack or CI failure goes to ns-investigator.

The task description and repository context are needed to begin. If a stack signal points to a rule that is missing, the skill asks for clarification or marks the task as needing it. Missing mandatory rules mean the boot is incomplete, so the skill does not guess a framework default.

What it helps with

  • Fix an isolated bug outside a planned release
  • Refactor a small, tightly scoped code area
  • Write a migration or script outside a version cycle
  • Implement a change to a component, hook, service, or utility

Example prompts for the agent

  • Fix the bug in this service, read the relevant files first, and report the checks you ran.
  • Refactor this component without creating SDD tasks or a handoff.
  • Write a migration script for this change and list any blockers.

How to install ns-coder

1Skills CLI (Vercel)

npx skills add nextstage-brasil/skills --skill ns-coder -a claude-code

2Manually: put the files in place

~/.claude/skills/ns-coder/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ns-coder/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ns-coder

How do I install ns-coder in Claude Code?

Run npx skills add nextstage-brasil/skills --skill ns-coder -a claude-code. The skill file is at ~/.claude/skills/ns-coder/SKILL.md.

What does ns-coder do?

It makes focused code changes, including bug fixes, small refactors, scripts, and migrations. Multi-stage SDD work and tasks with execution-handoff.md use a different mode.

What happens if a required stack rule is missing?

The skill asks for clarification or marks the task as needing it. It will not assume a framework default.

Source text

SKILL.md · Apache-2.0
---
name: ns-coder
description: "(NS) Ad-hoc coding — bug fixes, refactors, scripts, migrations — without full SDD. Entry priority 5: \"just implement this\", \"quick fix\", or coding without execution-handoff (C2 under ns-autonomous). Do NOT: ISSUE_URL (ns-execution-gitlab-issue), multi-day/version (ns-spec-driven), product bug report / screen expected-vs-actual **without** diagnosis_complete (ns-bug-report-diagnosis), diagnosis-only stack/CI (ns-investigator), when execution-handoff.md exists. Do NOT generate requirements/tasks/handoff."
license: Apache-2.0
metadata:
  author: nextstage-brasil
  version: "2.5"
depends:
  - ns-harness
  - ns-investigator
  - ns-bug-report-diagnosis
  - ns-frontend-design
  - ns-best-practices
  - ns-backend-tests
  - ns-e2e-tests
  - ns-docs-writer
  - ns-reviewer
  - ns-judge
  - ns-autonomous
  - ns-living-spec
---

# 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)

| Signal | Redirect |
| ------ | -------- |
| GitLab `ISSUE_URL` detected | **Stop** — `ns-execution-gitlab-issue` |
| Multi-day / version / SDD scope | `ns-spec-driven` |
| Product bug report / screen expected vs actual **without** `diagnosis_complete` | `ns-bug-report-diagnosis` |
| BRD handoff with `diagnosis_complete: true` | Implement — **do not** return to `ns-bug-report-diagnosis` |
| Obscure bug, root cause unclear (stack/CI) | `ns-investigator` |
| Ad-hoc diff ready | `reviewer-agent` then `ns-reviewer`; `ns-judge` only if `Code Review: Approved` |

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

| Variable | Required |
| -------- | -------- |
| `{task_description}` | Yes |
| `{target_layer}` | Infer when possible: frontend, backend, infra, tests, fullstack |

## 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:

| Agent state | Action |
| ----------- | ------ |
| Cold start (this agent/subagent just started) | Full Session boot (steps 1–6). Bridge may have done local + architecture/project rules — finish layer rules + context |
| Same agent continuing; steps 1–6 done; files unchanged | Do **not** re-read rule corpus |
| `agents.local.md` or harness rules changed since last boot | Re-boot |

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.

| Signal | Skill | When |
| ------ | ----- | ---- |
| Frontend UI **without** Layout SSoT registered for screen being built (`reference-sources.md` `role: ui-layout`, or card cites `*-visual.md`) | `ns-frontend-design` | Before large UI diff (step 4–5) or when task is primarily visual |
| Layout SSoT **registered** for screen being built | *(none — read SSoT)* | Open cited guide/prototype **before** diff; match registered pattern + project UI approach; **do not** invoke `ns-frontend-design` anti-slop |
| Security headers, CSP/CORS, dep CVE sweep, a11y/Web Interface Guidelines audit | `ns-best-practices` | On explicit request, or after frontend work before review when hygiene was in scope |
| README / `docs/` guides (not code comments) | `ns-docs-writer` | On explicit request or version/doc closure — not every ad-hoc fix |

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

| Condition | Action |
| --------- | ------ |
| Large change gate | Plan + wait |
| Public contract change | Stop, explain, ask |
| Ask-before gate (dep / abstraction / schema / CI / cross-package move) | Stop, ask |
| Protected-test change would weaken coverage | Stop; fix behavior or ask |
| Library API ≠ docs/rules | Follow library; report drift |
| Task needs multi-day SDD planning | Redirect to `ns-spec-driven` |

## 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)

© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills

Similar skills

All skills for Code review and refactoring →

From the same set20

The whole set →
ns-autonomous ns-autonomous — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that takes a local plan or pasted text and runs it autonomously inside an isolated worktree. CX Codex +1 152installs ns-e2e-tests The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs. CX Codex +1 151installs ns-backend-tests ns-backend-tests — a skill for writing and running PHPUnit unit and integration tests directly in your IDE. Runs only in Docker containers, helping you quickly test a new Laravel project or rewrite existing tests. CX Codex +1 151installs ns-docs-writer ns-docs-writer — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that produces human-facing project docs: README files, docs/ guides, runbooks, and contributor markdown. CX Codex +1 151installs ns-reviewer ns-reviewer grades code changes against SOLID principles, clean code patterns, performance, security, and testability. Approves only at score 10; score 9 triggers rejection. CX Codex +1 140installs ns-living-spec ns-living-spec maintains domain specifications in docs/specs/ after version releases or approved reviews. Turns diffs and release artifacts into functional truth. CX Codex +1 140installs ns-proto-visual-guide The ns-proto-visual-guide Claude Code skill documents the required appearance of cards, forms, shells, and overlays. It activates for normative visual guides and visual QA checklists. CX Codex +1 106installs ns-proto-creator ns-proto-creator — a Claude Code skill that captures live interfaces with Playwright and builds or updates a prototype. It runs for URL-based prototyping, screen reconstruction, and changes to an existing prototype/. CX Codex +1 106installs

Project sponsors

Companies that keep this analytics open