0.3.0 • Published 3d agoCLI

flow-sdd

Licence

—

Version

0.3.0

Deps

Size

336 kB

Vulns

Weekly

Summary Dependency Versions

flow-sdd

Installable flow-* skills package for a governed Spec-Driven Development workflow.

Created and maintained by Rafael Messias.

SDD First

flow-sdd is an SDD workflow, not a loose prompt bundle.

Artifact chain:

Initiative -> Explore -> PRD -> TechSpec -> Tasks -> Execute -> Review -> Fix -> Validation

Operational loop:

plan before implementation
keep artifacts in sync with code
review and remediate explicitly
separate preliminary validation from final validation
verify artifact coherence before claiming completion

What It Adds

installable flow-* skills package for Codex, Claude, and custom LLM/agent targets
project-local sync driven by flow.config.yaml
single-project and multi-project workspace support
flow-initiative for an optional initiative hierarchy above independently executable features
CLI introspection for status, next, verify, impact, projects, and contracts
task-aware next-step resolution with dependency checks
multi-project verification for project ownership, cross-project dependencies, and recommended release artifacts
optional UX aliases such as plan, review, and verify

Install

npm i -D flow-sdd

Initialize in a repository:

npx flow-sdd init --project . --tools codex,claude --profile strict

CLI

npx flow-sdd list --json
npx flow-sdd init --project . --tools codex,claude --profile strict
npx flow-sdd update --project .
npx flow-sdd doctor --project . --strict
npx flow-sdd status --project . --feature shopping-cart
npx flow-sdd next --project . --feature shopping-cart
npx flow-sdd verify --project . --feature shopping-cart
npx flow-sdd impact --project . --feature shopping-cart
npx flow-sdd projects --project . --feature shopping-cart
npx flow-sdd contracts --project . --feature shopping-cart
npx flow-sdd status --project . --initiative commerce
npx flow-sdd status --project . --feature commerce/checkout
npx flow-sdd verify --project . --feature commerce/checkout

Workspace Modes

Single project

Default mode. Existing repositories do not need extra metadata.

profile: strict
defaultLanguage: en-US
workspace:
  mode: single

Typical structure:

tasks/
  shopping-cart/
    _prd.md
    _techspec.md
    _tasks.md
    task_01.md
    task_02.md

Initiatives and nested features

Use flow-initiative when a demand is broad enough to require a roadmap of independently planned features. The existing flat layout remains supported and can coexist with nested features:

tasks/
  shopping-cart/
    _prd.md
    ...
  commerce/
    _initiative_prd.md
    _roadmap.md
    _design.md
    features/
      checkout/
        _prd.md
        _techspec.md
        _tasks.md
        task_01.md

For a flat feature, id, qualifiedId, and name are all shopping-cart, and initiative is null. For a nested feature, id and qualifiedId are both commerce/checkout, name is checkout, and initiative is commerce.

--feature accepts a path such as tasks/commerce/features/checkout, a qualified ID such as commerce/checkout, or a simple name such as checkout when that name is unique. If the same simple name exists in multiple initiatives, the CLI rejects it as ambiguous and lists the qualified IDs to use. --initiative commerce filters status, next, verify, impact, projects, and contracts; when combined with --feature, both selectors must refer to the same initiative.

JSON compatibility is additive: every feature representation gains id, qualifiedId, and initiative without losing existing fields. Full feature reports from status and verify also expose deterministic parentDocuments; flat features use an empty array.

Multi-project

Use one workflow feature across multiple repositories or services.

profile: strict
defaultLanguage: en-US

workspace:
  mode: multi-project

projects:
  storefront:
    path: ../storefront
    type: frontend
    stack: nextjs
  catalog-api:
    path: ../catalog-api
    type: api
    stack: node
  carts-api:
    path: ../carts-api
    type: api
    stack: node
  database:
    path: ../database
    type: database
    stack: postgres

Recommended feature structure:

tasks/
  shopping-cart/
    _prd.md
    _techspec.md
    _tasks.md
    _impact-map.md
    _contracts.md
    _release-plan.md
    _rollback-plan.md
    task_001.md
    task_002.md
    task_003.md

Task files may include multi-project metadata:

---
id: task_002
title: Implement cart API endpoint
status: pending
type: backend
complexity: medium
project: carts-api
repository: ../carts-api
area: backend
dependencies:
  - task_001
---

Tasks may also include optional hierarchy and coordination metadata:

initiative: commerce
feature: checkout
workstream: api
owner_team: platform
external_issue: https://tracker.example/items/123
design_refs:
  - docs/design/checkout.md

All six fields are optional and are validated only when present. initiative and feature must match the nested path when applicable; workstream, owner_team, and external_issue accept non-empty project conventions without requiring a provider; and each design_refs item must be an HTTP(S) URL or a safe workspace-relative path.

Example: Shopping Cart Feature

1. Bootstrap the repo

npm i -D flow-sdd
npx flow-sdd init --project . --tools codex --profile strict
npx flow-sdd status --project .

2. Plan the feature in the LLM client

Use `flow-plan` for a feature named `shopping-cart`.

Context:
- this is a product catalog website
- product listing and product detail pages already exist
- users can browse as guests
- the cart must support add item, remove item, change quantity, subtotal, and empty state
- checkout is out of scope for this feature

Generate the PRD, TechSpec, task breakdown, and a preliminary validation draft.

Expected artifacts:

tasks/shopping-cart/_prd.md
tasks/shopping-cart/_techspec.md
tasks/shopping-cart/_tasks.md
tasks/shopping-cart/task_*.md

3. Inspect the plan from the terminal

npx flow-sdd status --project . --feature shopping-cart
npx flow-sdd next --project . --feature shopping-cart
npx flow-sdd verify --project . --feature shopping-cart

4. Execute in the LLM client

Use `flow-run` for feature `shopping-cart`.

Implement the planned tasks end to end, keep task tracking updated, and stop when the feature is ready for structured review.

When you want to execute a single next task explicitly:

Use `flow-run-task` for feature `shopping-cart` and task `task_02`.

Implement only this task, update task tracking, and stop after verification.

5. Review and fix

Use `flow-review` for feature `shopping-cart`.

Review the implementation against the PRD, TechSpec, task files, and current code. Create a review round with concrete issues if problems are found.

If issues exist:

Use `flow-fix-review` for feature `shopping-cart`.

Resolve the latest review issues, update the review files, and verify the result before closure.

6. Final validation

Use `flow-validation-plan` for feature `shopping-cart`.

Generate the final validation package with scenarios for:
- add to cart from listing page
- add to cart from product detail page
- remove item
- change item quantity
- subtotal update
- empty-cart state
- stock-limit rejection

7. Final audit

npx flow-sdd status --project . --feature shopping-cart
npx flow-sdd verify --project . --feature shopping-cart

Command Behavior

status

detects the current workflow phase
shows artifacts, blockers, dependency-blocked tasks, and next step
groups work by project in multi-project mode

next

recommends the next executable task
does not suggest dependency-blocked tasks
includes project ownership in multi-project mode

verify

audits workflow artifacts by completeness, correctness, and coherence
validates multi-project task ownership and configured projects
flags cross-project dependencies and recommended release artifacts
validates referenced code paths only when workspace.validateCodePaths: true

impact

reads _impact-map.md when present
falls back to derived impacted-project data from task metadata

projects

groups workflow progress by project
useful for orchestration-heavy features

contracts

checks _contracts.md for service contract sections
useful when APIs, workers, or services integrate across projects

Profiles

strict

full governed workflow
installs initiative planning, exploration, generic docs, feature planning, execution, review, verification, validation, and memory skills

quick

lean workflow for faster adoption
installs exploration, planning, execution, review, and verification skills

workspace

planning-centric profile
installs initiative planning, exploration, generic docs, feature planning, task design, verification, and memory skills

Targets

Built-in targets:

codex -> .agents/skills/
claude -> .claude/skills/

Custom targets:

tools:
  - codex
  - claude
  - gemini
  - cursor
toolTargets:
  gemini: .gemini/skills
  cursor: .cursor/skills

This lets the same package serve more than one LLM client without hardcoding provider-specific behavior into the repo.

Config

flow.config.yaml

profile: strict
tools:
  - codex
skills:
  - flow-explore
  - flow-initiative
  - flow-plan
  - flow-prd
  - flow-techspec
  - flow-tasks
  - flow-validate-tasks
  - flow-run-task
  - flow-run
  - flow-review
  - flow-fix-review
  - flow-verify
delivery: skills
aliases: true
defaultLanguage: en-US
workspace:
  mode: single
  validateCodePaths: false
projects: {}
context: |
  Product catalog platform with strict feature-level reviews.
rules:
  review:
    - Compare task files against _tasks.md before review.
    - Prefer flow-sdd verify before flow-review.
  testing:
    - Run focused tests before broad suites.

Notes:

workspace.mode defaults to single
workspace.validateCodePaths defaults to false; enable it explicitly to verify code and review file references
defaultLanguage defines the fallback language for generated artifacts
explicit user language requests still win
context and rules are injected into installed SKILL.md files as a managed overlay
extra agent/LLM targets can be added through toolTargets

Installed Names

Canonical skills:

flow-explore
flow-doc-workshop
flow-initiative
flow-plan
flow-prd
flow-techspec
flow-tasks
flow-validate-tasks
flow-run-task
flow-run
flow-review
flow-fix-review
flow-verify
flow-validation-plan
flow-memory

flow-initiative has no alias and is installed by the strict and workspace profiles, but not by quick.

Draft Lifecycle

flow-prd, flow-techspec, and flow-plan preserve _prd.draft.md and _techspec.draft.md while review is pending, paused, or rejected. The last approved canonical document remains active until explicit approval, successful promotion, a full reread, and removal of only the corresponding draft. Drafts never satisfy prdPresent or techspecPresent in status and verify.

Aliases:

explore
docs
plan
prd
propose
techspec
design
tasks
breakdown
run
review
verify

Verification Model

Use both layers:

flow-sdd verify: workflow and artifact audit
flow-verify: in-agent completion guard with fresh evidence expectations

Generic Documents

Use flow-doc-workshop for repository documents outside the specialized SDD chain, such as:

README
runbook
migration guide
onboarding doc
short RFC
standalone ADR