convez.ai
PluginDesenvolvimento WebIntermediário
tranquocthong

Spec Flow

tranquocthong/claude-spec-flow

SRS → Design → Implementação rastreável e adaptativa para Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin para Claude Code que implementa desenvolvimento orientado por especificações (spec-driven). Transforma uma SRS ou ideia bagunçada em um Design de Solução revisado e rastreável, depois em implementação adaptativa que vincula cada linha ao requisito de origem. Sem chaves de API obrigatórias e totalmente portável.

Instalação

$npx convez-ai tranquocthong/claude-spec-flow

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v0.20.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Converter ideias vagas em especificações estruturadas e designs de solução
  • Rastrear mudanças de requisitos e sincronizar código com especificações atualizadas
  • Implementar features complexas com ciclos adaptativos (rápido/expandido/profundo)

Veredito

Ferramenta sólida para times que precisam de rastreabilidade entre especificações e código. O modelo adaptativo reduz overhead em mudanças pequenas, enquanto mantém rigor em grandes. Requer disciplina do usuário, mas entrega portabilidade real (markdown/json no repo, sem servidor).

README

A tradução para o português deste README ainda está na fila.

spec-flow

Turn a messy SRS — or just an idea — into a reviewed Solution Design, then implementation that traces back to every line of it. Spec-driven, but adaptive: small changes skip the ceremony, big ones get the rigor. A standalone Claude Code plugin.

SRS / idea  →  SD  →  (adaptive) implement  →  manual-test verify  →  ship
 │             ▲                                                       │
 │             └──────── /sf:resync  (Product changed the SRS) ────────┘
 └─────────────────────  /sf:change  (you change your mind) ───────────

v0.3.6 — Spec-driven dev for Claude Code: a messy SRS (or just an idea) → a reviewed Solution Design → adaptive implementation that traces back to every line.

What you get

  • SRS or just an idea → a clean SD, AI-shaped and gated on your approval. The SD is the single source of truth; everything downstream traces to it.
  • Adaptive implement — each requirement is scored and routed fast / expand / deep by complexity. No fixed phase tax on small work.
  • Real traceability — SRS§ → SD → FR/TC → task → source file. Change one thing and see everything it touches.
  • Change-driven loops — Product edits the SRS → resync; you change your mind → change; a bug → bug (works even with no SD, for brownfield).
  • Local-first verification — the bundled manual-test harness (curl/Kafka + DB/Redis) gates every task; nothing reaches done unverified.
  • Yours, portable — per-project state is plain markdown/json committed with your repo. No DB, no server, no lock-in. Keyless by default (runs through your Claude Code session).

Install

/plugin marketplace add <path-to-or-git-url>/claude-spec-flow
/plugin install sf@claude-spec-flow

Reload Claude Code, then verify: /sf:doctor. Prereqs: node ≥ 18 + npm. No API key — /sf:init sets Task Master to the keyless claude-code provider (auto-fetched via npx).

# Team (private marketplace)
/plugin marketplace add git@<your-git-host>:<org>/claude-spec-flow.git
/plugin install sf

# Zero-install — the engine is plain Node, runnable without the plugin:
node <path>/claude-spec-flow/bin/flow-tools.cjs doctor
node <path>/claude-spec-flow/bin/flow-tools.cjs sd-skeleton --srs <your-srs.md> --feature demo

ANTHROPIC_API_KEY / PERPLEXITY_API_KEY are optional — only if you prefer your own provider.

Which command do I run?

You have / want…Run
First time in this repo/sf:init
A new feature from an SRS/sf:ingest <srs.md>
Just an idea, no SRS file/sf:ingest — it interviews you and writes the SRS
Product changed the SRS/sf:resync <srs_v2.md>
You want to change / enhance an implemented feature/sf:change "<desc>"
A bug to fix (even on legacy / no-SD code)/sf:bug "<desc>"
A refactor / cleanupNormal pipeline, adaptive by size — /sf:ingest if substantial, just do it if trivial (details)
An SRS too big for one SD (>25 FRs)/sf:split <srs.md>
Where am I? / is the install healthy?/sf:status · /sf:doctor
Coming back (new session) — pick up in-progress work/sf:status — reads the disk and hands you the exact next step: open bugs/changes (/sf:bug --resume <id> · /sf:change --resume <id>), pending tasks (/sf:phase), or an interrupted ingest (the missing sd-author / trace-build step). Re-running /sf:ingest is safe — it skips done steps and won't clobber an authored SD.

Quickstart

# 1. once per project (repo root)
/sf:init --stack java-spring        # node | python | go | dotnet | (omit for generic)
#   → seeds .spec-flow/ and asks: commit it, or keep local?

# 2. per feature
/sf:ingest <path/to/srs.md>     # (or bare /sf:ingest to be interviewed) → SD draft + trace + snapshot
#   → review the SD, clear TODO:MANUAL-REVIEW, get leader approval   ← your only control point
#   → after you approve, the agent drives the rest — you don't type the steps below
/sf:checklist <feature>         # SD §13.2 Test Cases → manual-test CHECKLIST.yaml (agent fills request + assertion)
#   → agent seeds tasks: parse-prd --tag <feature> + analyze-complexity --tag <feature>   (only after 0 TODO; keyless CLI)
/sf:phase <feature>             # adaptive implement → manual-test → done
#   → ship: commit + git push (surfaces the MR/PR link)

How it works

Why the SD is the control point

SRS is uncontrolled — product writes it however they want, every time different. SD is your only control point.

So: deterministic code only harvests raw material from the SRS (accepts "dirty" output); the sd-author AI agent does the shape-robust SRS→SD mapping; all deterministic rigor (routing, checklist, traceability, tasks) lives downstream of the SD, which follows a template you control and a human approves. An SD that doesn't match reality is worse than none — so spec-flow never fakes one (see Brownfield below).

Flow 1 — New feature from an SRS (the main path)

No SRS — just an idea / your own description? That's the normal case. Easiest: run /sf:ingest with no file (or /sf:ingest --idea "<seed>") — it interviews you and writes .spec-flow/srs/<feature>.md for you (AI-elicited structure beats hand-typed prose), then ingests. Prefer to write it yourself? Drop a rough .md (prose/bullets fine) at .spec-flow/srs/<feature>.md and /sf:ingest it. Either way sd-author shapes it and you review the SD at the gate. The doc the interview targets / you fill:

# <feature name>
## What & why        — 1–2 lines: what it does, problem it solves
## Actor             — who / what system calls it
## Behaviors         — happy-path bullets        → become FRs
## Rules / errors    — validations, failure cases → become TCs + error codes
## Done when         — acceptance criteria        → become TCs

List the behaviors + error cases well — that's the part the AI can't invent. Everything else (architecture, sequences) sd-author infers and you correct at the SD gate. Tiny idea with no real contract? Skip the flow — edit + commit. Idea too big (>25 FRs)? /sf:ingest flags epicScale → /sf:split.

[Product gives you SRS — or your own idea doc]
        │
        ▼
/sf:ingest <path/to/srs.md>
   • srs-snapshot      → .spec-flow/snapshots/<feature>-001.md (baseline for future diffs)
   • sd-skeleton       → .spec-flow/specs/<feature>/SD.md  (deterministic HARVEST — dirty, that's fine)
   • sd-author (AI)    → cleans harvest into atomic FR/TC, fills architecture/API/state
   • trace-build       → .spec-flow/trace.json (FR↔TC↔error↔state links)
   • state-update      → .spec-flow/STATE.md
        │
        ▼  GATE: SD still has TODO:MANUAL-REVIEW?  → you fill the few ambiguous spots
[You review SD  +  leader approves]            ← your only control point; after this the agent drives
        │
        ▼
/sf:checklist <feature>            → .spec-flow/specs/<feature>/CHECKLIST.yaml  (co-located with the SD)
   • agent fills request + assertion per test: `expect.body` for read/transform (e.g. masking), `verify` SQL for mutations
        │
        ▼
agent seeds tasks: parse-prd --tag <feature> + analyze-complexity --tag <feature>   ← per-feature tag = isolated task space; only AFTER 0 TODO (keyless CLI, not MCP — agent runs it, not you)
        │
        ▼
/sf:phase <feature>            ← adaptive implement loop
   route --sd .spec-flow/specs/<feature>/SD.md      → each FR scored 1–10:
        1-3 fast    → straight to executor
        4-7 expand  → expand_task → subtasks
        8-10 deep   → research first, executor with planning notes
   per task:  next_task → hybrid-executor writes code → update_subtask
              → set_status(review) → run-checklist smoke
              → PASS: set_status(done) + state-update   |   FAIL: halt, surface
        │
        ▼
run-checklist <feature> --tag regression
   → checklist-to-verification hook writes .spec-flow/VERIFICATION.md (status: passed only if 0 fail)
        │
        ▼
ship:  commit + git push → open MR/PR
       (GitLab prints the MR link on push · GitHub: gh pr create or the compare URL)

Flow 1b — Epic split (when Flow 1 returns epicScale: true)

Use this when the SRS is too large for a single reviewable SD (>25 FRs or >800 generated lines).

/sf:split <path/to/srs.md>
      │
      ▼
PROPOSE   sd-author reads the full SRS and proposes a grouping
          (2–5 sub-features, grouped by User Story range / bounded-context)
      │
      ▼
 GATE     HUMAN reviews + approves (or adjusts) the grouping
          ← never auto-committed: this is a design decision
      │
      ▼
REGISTER  epic-new --name <epic> --subs "<approved sub names>"
          → .spec-flow/epics/<slug>.md
      │
      ▼
SUB-SDs   for each approved sub-feature:
          sd-author (scoped to ONLY that sub's FRs/US) → .spec-flow/specs/<epic>-<sub>/SD.md
          trace-build → linked via trace.json
      │
      ▼
Each sub-feature then runs the normal pipeline independently:
  /sf:checklist → /sf:phase → regression → ship
/sf:resync later: trace-impact scopes to affected sub-feature(s) only

Flow 2 — Product changed the SRS (top-down resync, surgical)

[Product sends SRS v2]
        ▼
/sf:resync <path/to/srs_v2.md>
   • srs-diff           → diff vs last snapshot → CHANGESET (added/changed/removed)
   • trace-impact       → exact FR / TC / error / task IDs touched (via trace.json)
   • sd-author          → updates ONLY impacted SD sections (not a full regen)
        │ GATE: review the delta + leader approves
        ▼
   • (Task Master CLI) update --from=<task> --prompt="<changeset>"   → cascade downstream tasks
   • re-open impacted done tasks → review
   • regenerate impacted CHECKLIST rows
   • srs-snapshot (new baseline) + trace-build + state-update
        ▼
/sf:phase <feature>            → re-implement the review tasks → manual-test → done

Defends "fix one place, forget three": trace.json finds every impacted node; cascade propagates; every touched task must pass manual-test again.

Flow 3 — You want to change the spec / enhance after impl (bottom-up loop)

/sf:change "<description>" --type fix|enhance
   1. open .spec-flow/changes/<NNN>-change-<slug>.md  (audit trail; id: change-NNN)
   2. edit the SD section (or sd-author proposes a diff)   ← SD first, never patch code blind
   3. trace-impact (--ids / --keywords) → impacted tasks
   4. re-open tasks → review  (+ add_task if net-new work)
   5. /sf:phase → executor edits code → run-checklist
   6. PASS + satisfied → change done + verify-collect → VERIFICATION.md
      not satisfied / still failing → loop back to step 2
   repeat until every open change is done

fix vs enhance differ only in MoSCoW weight + test tag (smoke vs regression). Wrong command? /sf:change needs an existing SD; if there's no SD or the code just misbehaves vs a correct SD → it's a code-bug → /sf:bug. Fast path: if trace-impact hits one FR/TC + one task (e.g. status→statuses, reformat a field), the change record is one line, edit the SD row directly (no sd-author), and verify only that TC — full regression runs at close.

Flow 4 — Bug report / fix bug

A bug is NOT always a spec change. There are 3 kinds, each routed differently:

KindCriteriaRoute
CODE bugSD is correct; code behaves wrongFix code to match SD. Never edit SD. Add permanent regression test.
SPEC bugSD itself is wrong or incompleteHand off to /sf:change "<desc>" --type fix (SD-first edit).
SRS-levelProduct/requirement misunderstandingHand off to /sf:resync <srs.md>.

SD-optional (brownfield): on a project with no SD (spec-flow adopted mid-stream, feature never ingested), /sf:bug skips triage and treats it as a code-bug — the repro test + expected/actual are the contract. Legacy features get tracked fixes without forcing a full SD on them.

Key technique — REPRO-FIRST: write a CHECKLIST.yaml entry that fails (reproduces the bug) before touching any code. After the fix it turns green and stays as permanent regression coverage.

/sf:bug "<desc>" [--severity low|med|high|critical] [--repro "..."] [--expected "..."] [--actual "..."] [--feature <f>]
        │
        ▼
INTAKE       flow-tools bug-new → .spec-flow/bugs/<NNN>-bug-<slug>.md
        │
        ▼
REPRO-FIRST  add CHECKLIST entry → run → confirm FAILS before fixing
        │
        ▼
TRIAGE       trace-impact → SD section → decide: code-bug | spec-bug | srs-level
        │
        ├─ spec-bug  ──→  /sf:change (SD-first)
        ├─ srs-level ──→  /sf:resync
        │
        └─ code-bug → hybrid-executor (code only, SD unchanged)
                │
                ▼
           VERIFY   repro test must PASS; if FAIL → loop back to fix
                │
                ▼
           REGRESS  test stays permanently; bug status=done; VERIFICATION updated

Refactor / cleanup

A refactor is just work — it runs through the normal pipeline, adaptive by size, like any feature. There's nothing special and no separate /sf:refactor:

  • Substantial (split a service, restructure a module, migrate a pattern) → /sf:ingest an SRS whose goal is the restructure and whose requirements are the behaviors that must stay identical. The SD's body is the target architecture (§6) plus those preservation tests; /sf:phase implements the restructure steps; the checklist then verifies behavior is unchanged — which, for a refactor, is exactly the acceptance criterion.
  • Trivial (rename, drop a dead method) → skip the ceremony and just do it. The adaptive charter applies to all small work, not only refactors.

One nuance: a refactor's tests assert "same as before," and before lives in the running code — capture them as characterization tests from the real system (real responses / golden output), not from prose you might misremember.

Brownfield — adopting spec-flow into an existing codebase

spec-flow is forward (SRS → SD → build). For features built before you adopt it — code exists, no SD — do not retro-generate a full SD. The SRS describes as-specified; the code has drifted to as-built; an SD from either won't match the running code — and an SD that doesn't match code is worse than none (it lies, and the whole model trusts the SD as truth). So:

  • Bug on legacy code → /sf:bug — SD-optional: no SD needed, the repro test + expected/actual are the contract.
  • Change / enhance legacy → forward-spec only the delta: /sf:ingest a focused SRS/idea for the new behavior, then build + verify just that. The surrounding legacy code is context, not something to reverse-spec.
  • Really want a full, accurate SD for a legacy feature? You must reconcile it to the code yourself — spec-flow won't fake one. Usually only worth it right before a heavy rewrite.

New features (post-adoption) get the full flow from day one. Adopt forward, not backward — never reverse-spec working code into an SD you then can't trust.

Command reference

CommandPurposeType
/sf:initOne-time project init — writes .spec-flow/ committed profile (config, project-author, .gitignore)flow
/sf:ingest <srs>SRS → SD draft (harvest + AI clean) + CONTEXT.md + trace + snapshot. Bare = interview modeflow
/sf:checklist <feature>SD §13.2 Test Cases → manual-test CHECKLIST.yaml scaffoldflow
/sf:phase <feature>Adaptive implement loop (fast / expand / deep by complexity)flow
/sf:resync <srs_v2>Flow 2 — propagate an SRS change as a surgical deltaflow
/sf:change "<desc>" · --resume <id>Flow 3 — dev fix/enhance loop, SD-first, until done. --resume continues an open change (id from /sf:status)flow
/sf:bug "<desc>" · --resume <id>Flow 4 — bug report/fix: repro-first → triage → code-fix → regress (SD-optional). --resume continues an open bug instead of duplicatingflow
/sf:split <srs-or-feature>Epic decomposition: propose → approve → generate per-sub-feature SDs linked via traceflow
/sf:statusProject status / resume: feature, phase, tasks, trace, open bugs/changes (with ids), next step — and hands you the exact resume command. Orient + pick up in-progress work in any sessionutility
/sf:doctorHealth check: env, install, project, SD/trace consistency — the single health surfaceutility
CmdDoes
initbootstrap .spec-flow/ dirs + read config
init-project [--name] [--stack] [--design-type]idempotent per-project init: write config.json + project-author.md + .gitignore
learn --note "<rule>" [--category writing|always|pitfall]evolve write-back: append timestamped rule to project-author.md
srs-snapshot --srssave SRS baseline for diffing
sd-skeleton --srs --feature [--type] [--out]harvest SRS → SD skeleton (dirty, by design)
route --sdscore each FR 1–10 → fast/expand/deep
checklist-gen --sd --featureSD §13.2 → CHECKLIST.yaml scaffold
trace-link --task <id> --feature <f> [--fr <FR-id>] --files "p1,p2,..."record task→file (and optionally FR→file) links into .spec-flow/specs/<feature>/file-links.json (per-feature; falls back to the active feature in trace.json if --feature omitted); deduplicated, persistent across trace-build rebuilds
trace-build --sd [--feature] [--tasks]build .spec-flow/trace.json; merges that feature's file-links.json → adds nodes.files + task-file/fr-file links
trace-impact --ids/--keywords/--changesetresolve impacted FR/TC/error/task nodes + impacted.files (files touched by any impacted task or FR)
srs-diff --new [--old]best-effort CHANGESET between two SRS versions
verify-collect --resultsparse run-checklist output → VERIFICATION truths[]
state-update --feature [--note]refresh .spec-flow/STATE.md (<100 lines) — incl. a deterministic Next Step
wave-plan [--max <n>]dependency-aware visibility: the ready-set of pending tasks whose deps are all done (what's workable now); reads .taskmaster/tasks/tasks.json (tagged or flat)
bug-new --desc [--severity] [--repro] [--expected] [--actual] [--feature]create .spec-flow/bugs/<NNN>-bug-<slug>.md bug record (id: bug-NNN); returns { id, path, severity }
bug-listlist .spec-flow/bugs/*.md with { id, status, severity, feature, desc }
branch-ensure --kind sd|bug|change [--name|--id|--slug|--type]create/switch the work branch from config.json → branching templates; only acts when on the base branch (safe no-op otherwise); mode: off → skipped
epic-new --name <epic> [--subs "subA,subB,subC"]create .spec-flow/epics/<slug>.md with sub-feature list; idempotent (reports alreadyExists if run twice)
epic-listlist .spec-flow/epics/*.md with { id, name, status, subCount }
verify-code [--feature <f>]generic quality gate: run tests, check coverage threshold, scan for forbidden patterns, scan for secrets — all driven by .spec-flow/config.json → verify; skips gracefully when unconfigured
doctor [--sd <SD.md>] [--feature <f>]health check: env · plugin files · install state · project init · trace health · SD gate · tasks info

Under the hood

spec-flow uses a two-tier overlay model. The global plugin is the engine — it never changes per project. The project's .spec-flow/ directory is the living, committed profile that evolves with the project.

GLOBAL plugin (installed in Claude Code)
  = flow-tools.cjs engine + default templates + base agent prompts
  = updated via /plugin update  →  shared across every project
  = NEVER project-specific

PROJECT .spec-flow/  (committed by default — your spec history travels with the repo)
  = config.json          project profile: stack, conventions, design type
  = project-author.md    SD-authoring overrides — where learnings accumulate
  = specs/<feature>/SD.md  the Solution Design — follows your commit choice
  = srs/<feature>.md (live inputs — idea or SRS), trace.json, STATE.md, VERIFICATION.md, snapshots/, bugs/, changes/
  Resolution: project-local overrides win; global plugin is the fallback

One-time setup (run once per project):

/sf:init [--name <n>] [--stack java-spring|node|python|go|dotnet] [--design-type auto|api|internal|hybrid]

Writes .spec-flow/config.json + .spec-flow/project-author.md, then asks how to track it:

  • Commit (default) — .spec-flow/ is tracked; its git log is the spec-evolution history. Then git add .spec-flow/ && git commit.
  • Keep local — adds .spec-flow/ to the project .gitignore; nothing committed. (Flag: /sf:init --no-commit-docs.)

Evolve via learn — when sd-author hits a reusable rule (team convention, pitfall, always-include section):

node ${CLAUDE_PLUGIN_ROOT}/bin/flow-tools.cjs learn --note "Always include audit_log table in §7 DB Design" --category always

Categories: writing · always · pitfall · learned. Each rule is timestamped and appended under the matching section in .spec-flow/project-author.md; commit it → the whole team inherits the learning. sd-author reads this file at the start of every run and treats its rules as authoritative overlays on the base prompt.

spec-flow is branch-aware and VCS-agnostic (GitHub + GitLab). The policy lives as DATA in .spec-flow/config.json → branching (seeded by /sf:init); the engine just substitutes templates.

"branching": {
  "mode": "per-sd",                                   // per-sd | per-sd+bug | off
  "base": "main",                                     // your integration branch (auto-detected at init)
  "templates": { "sd": "feat/{feature}", "bug": "fix/{id}-{slug}", "change": "{type}/{id}-{slug}" }
}
  • 1 SD = 1 branch. /sf:ingest calls branch-ensure --kind sd → feat/<feature>; the whole SD → implement → ship lifecycle lives on that one branch (a clean, reviewable PR).
  • Bugs / changes get fix/<id>-<slug> and <type>/<id>-<slug> via the same engine command.
  • No commit on base. branch-ensure only creates/switches when you're on base; on a work branch it's a safe no-op (never switches a dirty tree). The bundled commit skill refuses to commit on base while mode != off, generates the conventional-commit message, pushes, and surfaces the MR/PR link. Set mode: off to opt out (commit on current branch).

Merge-conflict note. trace.json and STATE.md are single global files describing the active feature (regenerated by trace-build). Sequential work (one SD at a time) never conflicts. Parallel branches can collide on merge — but the conflict is benign: both are derived artifacts, so take either side and re-run trace-build. (Heavy-parallel teams can gitignore these volatile files and commit only the durable ones.)

  1. /sf:ingest never implements — ingest (incl. interview mode) outputs only the SRS + SD + trace, then STOPS at the SD review gate. Discussing a feature is not permission to code it; implementation is /sf:phase, after the SD is approved.
  2. No parse_prd while the SD has any TODO:MANUAL-REVIEW marker (SD-mismatch defense, layer 1).
  3. CHECKLIST.yaml exists before the first task is implemented.
  4. verify-code gate runs before every manual-test smoke run (generic config-driven: tests, coverage, forbidden patterns, secret scan; stack specifics live in .spec-flow/config.json → verify; unconfigured → skips without blocking).
  5. review → done only after manual-test smoke passes; a phase ships only when regression passes (VERIFICATION.md status: passed).
  6. SD is the source of truth — change the SD first, then propagate via trace + cascade. Never patch code without patching the SD.

Plugin layout

.claude-plugin/   plugin.json, marketplace.json
commands/         ingest · checklist · phase · resync · change · bug · init · doctor · status · split
skills/srs-to-sd/ entry-point skill (intent routing + gates)
skills/manual-test/ bundled local-test harness (CHECKLIST.yaml, run-checklist.sh, ...)
skills/commit/     bundled conventional-commit + push skill (VCS-agnostic, base-branch guard)
agents/           sd-author (SRS→clean SD) · hybrid-executor (impl one task)
hooks/            checklist-to-verification (PostToolUse) · sd-drift-detect (PreToolUse) · spec-flow-anchor (UserPromptSubmit re-anchor)
bin/flow-tools.cjs  deterministic engine (pure, testable, Result contract)
templates/        sd-template.md · srs-template.md
.mcp.json         wires Task Master via npx

Created in the target project

  • .spec-flow/srs/<feature>.md — the live, editable input (a formal SRS or just your idea). Its home; you edit this, /sf:resync diffs it. Convention, not enforced — ingest accepts any path.
  • .spec-flow/specs/<feature>/SD.md — the Solution Design (your control point).
  • .spec-flow/specs/<feature>/CHECKLIST.yaml — manual-test checklist, co-located with the SD; persistent regression coverage. (Driven via the bundled manual-test skill, which spec-flow calls with this explicit path; the skill itself stays generic.)
  • .spec-flow/specs/<feature>/file-links.json — per-feature task→file and FR→file mappings (written by trace-link); scoped per feature so traces stay bounded + unambiguous; survives trace-build rebuilds.
  • .spec-flow/trace.json — traceability matrix for the active feature: SRS§ → SD§ → FR/TC/NFR → error → state → task → source FILE. Backbone of the change loops.
  • .spec-flow/snapshots/ — immutable SRS baselines frozen at each ingest/resync, for diffing (never hand-edit).
  • .spec-flow/changes/ — dev fix/enhance loop audit trail · .spec-flow/bugs/ — bug records (triage, resolution log, regression-test link).
  • .spec-flow/STATE.md — <100-line living index (resume after /clear) · .spec-flow/VERIFICATION.md — goal-backward verification, fed by manual-test results.
  • CONTEXT.md — locked decisions, fed to every agent.

All dependencies are pinned — updates are deliberate and tested, never automatic.

DependencyHowPinned version
task-master-aiRuntime MCP via npx (.mcp.json)0.43.1
manual-testBundled (vendored in skills/manual-test/)this plugin's version
nodeEnvironment prereq>= 18

Bump policy: update the pin in .mcp.json, re-run /sf:doctor (dep-lock check), smoke test, then commit. See DEPENDENCIES.md for rationale.

Status & known limits

  • Engine (22 flow-tools cmds) + hooks + commands + agents: built & verified.
  • Contributing / dev setup: the engine LOC ceiling (charter §0b #8) is enforced by a pre-commit hook in .githooks/. After cloning, activate it once: git config core.hooksPath .githooks (git does not run committed hooks without this).
  • In active dogfooding — used on real projects; the v0.0.2x fixes (rename /sf:change, brownfield /sf:bug, interview-mode ingest, per-feature task tags, co-located CHECKLIST) all came from live-use feedback. Not yet a confident team-wide release.
  • SRS harvest is intentionally dirty; sd-author (AI) cleans it — don't judge the harvest output directly.
  • Needs 1–2 finetune loops on a real SRS (adjust the sd-author prompt to your team's writing) before a confident team release.
  • Large features: SDs with >25 FRs or >800 generated lines are flagged epic-scale — sd-skeleton returns an advisory (never blocking) to /sf:split.
Ver o original no GitHub

Bom para

Relacionados