ns-spec-driven — скилл для Claude Code: формальная спецификация и доставка фич
Скилл ns-spec-driven для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode, который ведёт доставку фичи по формальной спецификации.
Apache-2.0 208 установок обновлён 2026-10-24
npx skills add nextstage-brasil/skills --skill ns-spec-driven -a claude-codeЧто делает ns-spec-driven
Проводит фичу через фазы: приём требований (intake), уточнение (clarify-strict), спецификация, проверка целостности, разбивка на задачи, генерация юнит- и e2e-тестов, передача исполнителю. Хранит состояние на диске в docs/versions/ и docs/context/, а не в истории чата — версию можно возобновить в новой сессии. Оркестрирует другие скиллы: ns-coder для простой реализации в сессии, ns-harness для структуры проекта, ns-reviewer и ns-judge для ревью, ns-living-spec для обновления документации. Для генерации задач запускает субагент task-writer-agent, для тяжёлой реализации — coder-agent.
Требует установленные зависимости: ns-harness, ns-coder, ns-autonomous, ns-reviewer, ns-judge, ns-living-spec. Для быстрых правок без контекста спецификации перенаправляет на ns-coder (приоритет 5). Никогда не запускает /ns-harness prepare автоматически — это ручная команда.
Какие задачи решает
- собрать формальные требования перед кодом
- разбить крупную фичу на задачи с тестами
- возобновить многодневную работу из файлов на диске
- проверить целостность спецификации перед реализацией
- передать версию субагенту с полным контекстом
Примеры запросов агенту
- Напиши спецификацию для модуля экспорта отчётов в PDF и разбей на задачи
- Продолжи версию v2.1 из
docs/versions/v2-1/ - Уточни требования и создай задачи для интеграции с API платёжной системы
Как установить ns-spec-driven
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-spec-driven -a claude-code2Вручную: положить файлы
~/.claude/skills/ns-spec-driven/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/ns-spec-driven/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-spec-driven -a codex2Вручную: положить файлы
.agents/skills/ns-spec-driven/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-spec-driven -a cursor2Вручную: положить файлы
.cursor/skills/ns-spec-driven/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-spec-driven2Вручную: положить файлы
.github/skills/ns-spec-driven/SKILL.md1Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-spec-driven -a gemini-cli2Командой платформы
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-spec-drivenВручную: положить файлы
.devin/skills/ns-spec-driven/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-spec-driven -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о ns-spec-driven
Как установить ns-spec-driven в Claude Code?
Выполни npx skills add nextstage-brasil/skills --skill ns-spec-driven -a claude-code. Скилл появится в ~/.claude/skills/ns-spec-driven/SKILL.md.
Что делает ns-spec-driven?
Ведёт доставку фичи по формальной спецификации: уточняет требования, проверяет целостность, генерирует задачи и тесты, передаёт реализацию субагентам. Хранит состояние в docs/versions/ — версию можно возобновить позже.
Когда ns-spec-driven не нужен?
Для быстрых правок без спецификации используй ns-coder. Скилл сам перенаправит туда, если контекст доставки версии отсутствует. Не запускает brownfield onboarding и /ns-harness prepare — это ручные команды.
Исходный текст
SKILL.md · Apache-2.0
---
name: ns-spec-driven
description: '(NS) Spec-driven delivery — clarify, requirements, tasks (incl. unit/e2e), implement, resume/continue version from disk. Entry priority 2: feature specs, version work, multi-day scope, or "continue" / "resume version" when docs/versions/ has partial artifacts. Bare quick fixes: ns-coder. Do NOT: brownfield onboarding, architecture rules, /ns-harness prepare (never auto-run Prepare).'
license: Apache-2.0
metadata:
author: nextstage-brasil
version: "1.8.8"
depends:
- ns-harness
- ns-coder
- ns-autonomous
- ns-reviewer
- ns-judge
- ns-living-spec
---
# NextStage Spec-Driven
**Delivery face** for spec-driven journey: intake, clarify-strict, specify, (consistency / partition), tasks, execute, close.
Completeness before fidelity, both by construction. Clarify-Strict **grill** = Gate 0 only. Confirm gates **1–4** and brownfield Step 0.4 stay (auto-continue when map fresh vs app tree; wait when freshness unproven). Version Clarify-Strict ≠ per-issue enricher (`ns-requirements-enricher`). `ns-project-manager` stays decoupled.
**Orchestrate** — **not** implement phase bodies inline. **Read** phase reference at delegation time. State on **disk** (`docs/versions/`, `docs/context/`, handoff files), not chat history.
Entry priority **2** (feature / version / SDD / multi-day / resume). Harness table: `../../ns-harness/references/code-skill-routing.md`. Trigger phrases: `references/entry-triggers.md`. Bare quick fix, no SDD context → redirect `ns-coder` (priority 5) unless user explicitly invoked this skill.
## Routing (read first)
| Handoff | Target |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Small / quick inside SDD | In-session `ns-coder` (cheap execute — **MUST NOT** spawn `coder-agent`; `../../ns-harness/references/subagent-dispatch.md`) |
| Version + handoff | `references/execution-handoff.md` + `../ns-coder/references/run-implementation.md` + `coder-agent` (**MUST** when available — heavy) |
| Task file generation | **MUST** spawn project agent `task-writer-agent` (exact name; adapter `model`) → `references/task-generator.md`. **FORBIDDEN** Task `inherit` / `coder` / `generalPurpose` (`../../ns-harness/references/subagent-dispatch.md`) |
| Bare quick fix, no SDD context | Redirect `ns-coder` (priority 5) — cheap; in-session; **MUST NOT** spawn `coder-agent` |
## Harness
See `../../ns-harness/references/session-boot.md`, `../../ns-harness/references/artifact-layout.md`, `references/gates.md`.
| Variable | Resolve via |
| --------------- | ---------------------------------------------------- |
| `{version_san}` | User scope or existing folder under `docs/versions/` |
## Out of band (not this skill)
**Brownfield onboarding** manual — never auto-run, never pipeline phase:
| Need | Skill |
| --------------------------------- | -------------------------------------------------------------------------- |
| Full prepare after `harness init` | `/ns-harness prepare this repo` or `npx @nextstage-brasil/harness prepare` |
| Per-issue GitLab grill-me | `/ns-requirements-enricher` — not version Clarify-Strict |
`architecture-rules.md` still stub or `docs/context/brownfield-map.md` missing and task needs them: **tell user run `/ns-harness prepare this repo`**, then stop — or continue SDD **only if they insist** after warning.
## Journey (delivery only)
```mermaid
flowchart LR
user[User request]
size[Auto-size]
intake[Intake]
clarify[Clarify-Strict]
specify[Specify]
consist[Consistency]
part[Partition]
tasks[Tasks]
units[Delivery units]
handoff[Handoff]
exec[Execute]
close[Close]
quick[Quick mode]
user --> size
size -->|Small| quick
size -->|Medium+| intake
intake --> clarify
clarify --> specify
specify --> consist
specify --> part
specify --> tasks
tasks --> handoff
tasks -.->|Gate 4 opt-in| units
units --> handoff
handoff --> exec
quick --> exec
exec --> close
```
| Phase | When | Reference |
| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Intake | Dense / pasted source | `references/source-registry.md` — persist `source/{slug}.md`, anchors, classify |
| Clarify | Medium+ mandatory | `references/clarify-requirements.md` then `references/clarify-strict.md`: checklist, D1–D4, Gate 0 (in-session) |
| Specify | Always for Medium+ | `references/requirements-generator.md` — also writes `ui-contract.md` when `ui-screen` in source (in-session — no v1 bridge) |
| Consistency | Before tasks (Large+) | `references/analyze-consistency.md` (in-session — no v1 bridge) |
| Partition | Multi-slice versions | `references/version-partitioner.md` (in-session — no v1 bridge) |
| Tasks | Medium+ formal tasks | **MUST** spawn `task-writer-agent` by exact name (adapter `model`; no Task `inherit`) → `task-generator.md` then unit/e2e generators |
| Delivery units | After all tasks (optional) | Gate 4 when GitLab possible; `references/delivery-units.md` only when publish, parallel, or resume file |
| Handoff | After tasks (or Gate 4 when run) | `references/execution-handoff.md` |
| Execute | Always | See execute routing below |
| Close | After delivery | `reviewer-agent` → `ns-reviewer` (**MUST** when available); `ns-judge` in-session only if `Code Review: Approved`; `ns-living-spec` after `Delivery Review: Approved` only (`../ns-reviewer/references/review-gate-workflow.md`). Skip second pair if Step 5 already ran both. |
| Quick | ≤3 files, one-sentence scope | In-session `ns-coder` (cheap — **MUST NOT** spawn `coder-agent`) |
Details: `references/auto-sizing.md`, `references/router.md`.
## Boot (mandatory, once per session)
1. Classify request → **Small / Medium / Large** (`references/auto-sizing.md`). Dense source (contract/schema tables or ~8+ sections) → Large min.
2. **Source detection:** list `docs/versions/{version_san}/sdd/source/` first; else legacy `docs/versions/{version_san}/source/` if unmigrated (`artifact-layout.md` **Legacy path resolution**). User-pasted specs → Intake (`source-registry.md`) before Clarify.
3. Check **resume** signals (`execution-handoff.md`, `version-roadmap.md`, partial version, open unknowns) → `references/session-continuity.md`.
4. **Agent runtime gate** — agent-api / intelligent SaaS (`references/agent-runtime-integration.md`): **MUST** load `ns-langgraph-agents` in session before any phase; **stop** if skill not installed.
5. Scan installed complements (soft) → `references/skill-integrations.md`.
6. Confirm **once** when needed: target version id, language for markdown artifacts — **natural chat** (`references/human-communication.md`). Never open with telegraphic status dump or phase jargon.
## Human communication
Chat short, natural language. **Read `references/human-communication.md` before any human gate or boot confirm.**
- Name next **deliverable** ("requirements document", "task files") — not internal phases ("Specify", "Clarify").
- Chat stand alone: highlights in plain language; document IDs only after meaning (**Gate 1 highlights** in that file). Gate 0: **numbered** asks (`1.` `2.` …); human may reply by number **or** `Tudo sim` / `all yes` on remaining yes/no confirms (not open questions). Behavior (when, HTTP, copy). Product error codes: `clarify-strict.md` Chat questions.
- Never use `Reply:`, `Premise:`, or "go for Specify".
- Caveman / artifact-compress = **files only** — never chat.
## Orchestration mandate
- **Delegate** = spawn gate in `../../ns-harness/references/subagent-dispatch.md`. Cheap execute / Quick = in-session `ns-coder`. Heavy / Tasks / Review = spawn bridge when available.
- **Read** phase reference before that phase — never improvise from memory.
- **Do not** ask "continue to next phase?" between phases in same sized pipeline.
- **Do not** invoke `/ns-harness prepare` or brownfield prepare references.
- **Do not** load multiple version specs into context — see `references/context-budget.md`.
- After each phase, verify expected artifact paths exist before advancing.
## Auto-size summary
| Size | Pipeline |
| ---------- | --------------------------------------------------------------------------------------------------------------- |
| **Small** | In-session `ns-coder` (quick mode — `references/quick-mode.md`; cheap execute) |
| **Medium** | Intake (if source) → Clarify-Strict → Specify → Tasks (**MUST** spawn `task-writer-agent` exact name) → optional Gate 4 + units → handoff → Execute → Close |
| **Large** | Full chain including Consistency and/or Partition when scope warrants |
**Safety valve:** scope exceeds ~3 files or explodes mid-session → stop, formalize via Medium+ pipeline (requirements + tasks).
## Execute routing
Worker dispatch: spawn gate — `../../ns-harness/references/subagent-dispatch.md`. Cheap = in-session; heavy / review / tasks = named bridge when available.
| Context | Worker |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ad-hoc / quick / single task | In-session `ns-coder` (cheap — **MUST NOT** spawn `coder-agent`) |
| Version with `delivery-units.md` | Dispatch **by unit** (wave order); parallel only if Gate 4 parallel + `A ∥ B`. GitLab: `delivery-units.md` **GitLab status/spent (SSoT)**. Published + G present → `ns-execution-gitlab-issue` SDD unit mode; else local unit batches in `run-implementation.md` |
| Version with `execution-handoff.md` only (no units file) | `../ns-coder/references/run-implementation.md` — classic **batched** dispatch (same-layer consecutive `pending`, prefer 4–7, hard max 7; size 1 = single task) + `coder-agent` (**MUST** when available — heavy) / `ns-coder` or `ns-autonomous`; handoff rows stay per task; Progress **Next task** = first id of next batch |
| Partitioned version (`version-roadmap.md`) | `references/orchestrator.md` — **by unit** when `delivery-units.md` exists (commit/MR per unit); else slice workers via `coder-agent` (**MUST** when available — heavy) |
| External GitLab `ISSUE_URL` + MCP available | `ns-execution-gitlab-issue` (priority 1 — not SDD unit mode) |
| Autonomous multi-step local plan | `ns-autonomous` |
**Face = orchestrator** (`ns-spec-driven`); does not implement — drives `run-implementation.md` (classic) or `orchestrator.md` (units when `delivery-units.md`; else slices).
**Tests while executing version tasks:** unit/integration only. **Forbidden** for agents to run E2E during task/batch loop; human runs E2E at version end (`../ns-coder/references/run-implementation.md`).
## Trigger → reference
| User says | Read first |
| ------------------------------------------------------ | --------------------------------------------------------------------------------- |
| "specify", "requirements for vX" | `references/router.md` → `requirements-generator.md` |
| "clarify", vague scope, reopen clarification | `references/router.md` → `clarify-strict.md` via `clarify-requirements.md` |
| Intake / persist source / coverage | `references/source-registry.md` + `references/spec-coverage.md` |
| "implement", "build version", tasks exist | `references/session-continuity.md` + Execute |
| "quick fix", "just change X" | `references/quick-mode.md` |
| "resume", "continue version", partial `docs/versions/` | `references/session-continuity.md` |
| "orchestrate slices", partitioned roadmap | `references/orchestrator.md` (hot path); all units/slices done → `references/orchestrator-closure.md` |
| UI / design work (no Layout SSoT for screen) | `references/skill-integrations.md` → `ns-frontend-design` |
| UI with Layout SSoT registered (`role: ui-layout`, cited `*-visual.md`) | `ns-coder` Complement delegation — read SSoT; skip `ns-frontend-design` |
| README / docs | `references/skill-integrations.md` → `ns-docs-writer` |
| security headers / modernize | `references/skill-integrations.md` → `ns-best-practices` |
| agent-api / intelligent SaaS / LangGraph scope | `references/agent-runtime-integration.md` → `ns-langgraph-agents` (**mandatory**) |
| MR / PR review | `ns-reviewer` directly (not this face) |
## Agent runtime (mandatory when detected)
Non-negotiable for agent-api and intelligent SaaS products. See `references/agent-runtime-integration.md`. Greenfield with no `agent-api/`: Feature 001 = langgraph bootstrap, then version deltas.
## Complement integrations
`spec-driven` / `gitlab` / `agents` ship `ns-frontend-design`, `ns-docs-writer`, and `ns-best-practices` via `ns-coder` `depends`. Check `.agents/skills/` once per session; if present → **delegate** (`references/skill-integrations.md`). If absent (minimal install) → continue and recommend install once per session (agent runtime **not** optional — see above):
```bash
npx @nextstage-brasil/harness --skill ns-frontend-design --skill ns-docs-writer --skill ns-best-practices --no-scaffold -y
```
## Completion summary
When version or quick fix closes, report:
1. Artifacts written or updated (paths).
2. Handoff status if applicable.
3. Suggested next step (living spec done → next version clarify; quick fix → optional review).
## Forbidden
- Auto-run or chain `/ns-harness prepare`.
- List Prepare as SDD phase.
- Hard-require complement skills when missing from `.agents/skills/` (delegate when present; see **Complement integrations**).
- Plan or execute agent-api / intelligent SaaS work without loading `ns-langgraph-agents` when detection signals match.
- Generate requirements/tasks yourself without reading phase references / delegating task files via `task-writer-agent`.
- Skip `execution-handoff.md` when formal tasks exist for version.
- Skip `delivery-units.md` + Gate 4 when human chose publish or parallel.
- Generate `delivery-units.md` on default local sequential path (no GitLab capability, no human ask).
- Create GitLab issue per `task-NNN` or one issue for whole version.
- Parallel unit execution without `A ∥ B` or without Gate 4 parallel choice.
- Address human with internal phase names ("Specify", "Clarify") or bot chrome (`Reply:`, `Premise:`).
- Specify with open critical unknown (no `skip clarify` waiver).
- Silent assumption from unanswered critical.
- Edit `docs/versions/{version_san}/sdd/source/` after Gate 1.
- Task cards for unmapped mappable source sections.
- UI implementation task without `ui-contract.md` when UI in scope.
## Invocation examples
```
/ns-spec-driven
```
```
Specify and implement user notifications for version 2.1
```
```
Quick fix: add nullable email field to the signup form
```
```
Resume implementation — handoff exists for docs/versions/1.0.0/sdd/
```
```
Continue partitioned version 3.8.0 — run pending slices from version-roadmap.md
```
© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills