К основному содержанию
скилл CX Codex

ns-spec-driven — скилл для Claude Code: формальная спецификация и доставка фич

Скилл ns-spec-driven для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode, который ведёт доставку фичи по формальной спецификации.

Apache-2.0 208 установок обновлён 2026-10-24

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add nextstage-brasil/skills --skill ns-spec-driven -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/ns-spec-driven/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/ns-spec-driven/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
spec-driven-workflow Alireza Rezvani Скилл spec-driven-workflow для Claude Code, который требует написать спецификацию до первой строки кода: требования, критерии приёмки, границы задачи. Останавливает разработку, пока спека не одобрена человеком. CX Codex +1 600установок spec-driven habib0x Плагин spec-driven ведёт фичу через три фазы: требования в нотации EARS, дизайн и список задач. Дальше реализацию выполняет агент. CX Codex ★ 1 596звёзд репо spec-driven-development addyosmani Скилл spec-driven-development для Claude Code готовит спецификацию до начала разработки. Он включается, когда нужно разобрать расплывчатые требования, спланировать функцию или оформить изменения к уже выпущенной спецификации. CX Codex +1 81 900установок spec-driven-workflow-v1 официальный github Правило spec-driven-workflow-v1 для GitHub Copilot ведёт разработку от требований к реализации и проверке, фиксируя решения и ход работы в отдельных файлах. CX Codex +1 ★ 41 430звёзд репо spec-driven-eval Waldemar Neto - github.com/waldemarnt Скилл spec-driven-eval сверяет реализацию и тесты с PRD по критериям и выдаёт итоговую оценку. Запускайте его для аудита фичи или сравнения реализаций одной спецификации. CX Codex +1 ★ 7 191звёзд репо tlc-spec-driven Felipe Rodrigues - github.com/felipfr Скилл tlc-spec-driven для Claude Code организует разработку фич через спецификацию, дизайн, задачи и исполнение. Работа идёт пошагово, с атомарными коммитами и проверкой требований тестами. CX Codex +1 1 300установок

Из того же набора20

Весь набор →
ns-gitlab-board-sync Скилл ns-gitlab-board-sync для Claude Code синхронизирует существующие задачи GitLab с локальным планом и ходом работ. Запускается при реализации задач, связанных с issue, или после синхронизации плана из GitLab. CX Codex +1 899установок ns-harness Разбирает существующий код и создаёт для агента правила работы с проектом. Запускается по /ns-harness prepare this repo или architecture-rules.md. CX Codex +1 249установок ns-gitlab-ci-generator Скилл ns-gitlab-ci-generator генерирует и настраивает пайплайн .gitlab-ci.yml для SaaS-монорепозиториев со структурой бэкенда и фронтенда. CX Codex +1 200установок ns-project-manager Скилл ns-project-manager для Claude Code превращает заметки и PRD в проектные артефакты, оценки сроков и отчёты. CX Codex +1 185установок ns-langgraph-agents Скилл ns-langgraph-agents для Claude Code, Codex, Cursor и других платформ, который ведёт разработку LangGraph.js agent-api от начального развёртывания до синхронизации graph-spec. CX Codex +1 171установок ns-execution-gitlab-issue Скилл ns-execution-gitlab-issue автоматизирует закрытие задач GitLab: изолирует работу в Git worktree, переключает статусы, запускает кодинг и создаёт Merge Request. CX Codex +1 165установок ns-requirements-enricher Скилл ns-requirements-enricher собирает бриф по реализации для одной задачи GitLab или вставленного описания: сначала смотрит код проекта, потом задаёт блокирующие вопросы в чате. CX Codex +1 163установок ns-best-practices Скилл ns-best-practices проверяет заголовки безопасности, базовую доступность интерфейса и правила Web Interface Guidelines. Находит уязвимости и готовит отчёт. CX Codex +1 154установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой