**sdd-agentic-flow** is a local-first, zero-dependency **Spec-Driven Agentic Workflow Harness** for coding agents.
Your agent can produce a diff and still leave you guessing whether it matched the intent. This toolkit closes that gap: **spec first, evidence before done, you approve the merge.**
## What is sdd-agentic-flow?
**sdd-agentic-flow is an Agentic Workflow Harness: a repository-native engineering control plane that turns specification-driven development into bounded, verifiable coding-agent workflows.**
It is not just a collection of Agent Skills. Skills are the public **capability layer**; the coding-agent host owns runtime execution. Around them sit the methodology, artifact contracts, condensed TLC and TDD baselines, evidence model, configuration, CLI, and lifecycle.
The goal is bounded, structured, traceable, verifiable agent-assisted engineering. Autonomous mode
owns local completion inside delegated authority; humans retain authority at safety, external,
irreversible, and release boundaries.
*The agent does the work. The specification defines what should be true. Sensors provide evidence.
Autonomous resolves ordinary engineering work and escalates only at an authority boundary.*
Sources that inform this design, tagged by epistemic role rather than treated as
specifications, are listed in [inspirations](docs/inspirations.md).
Structured specs, clear boundaries, and human governance:
- **Capability layer:** capability-contracted Markdown skills on condensed TLC and TDD baselines.
- **Adaptive sizing:** Feature-profile sizing with optional auto-discovered project context.
- **Zero footprint by default:** User-local skill install; `.sdd-agentic-flow/config.yml` only when you create it.
- **Human-in-the-loop:** The toolkit structures agent work; you keep final review authority.
- **Language-agnostic:** The CLI runs on Node.js >= 22; your project does not have to.
For teams that use coding agents, this split keeps reviewable engineering work in view:
humans define intent and verify results; agents execute within the harness. The project does
not claim token or speed improvements without measured data.
📦 Install and run with `npx sdd-agentic-flow`: [get started](#get-started) · 📖 [Skills usage guide](docs/saf-skills-usage-guide.md) · 🏗 [Architecture](docs/architecture.md)
---
🇧🇷 *[DisponĂvel tambĂ©m em portuguĂŞs](README.pt-BR.md)*
## The problem
You delegate a task. The agent jumps to code, blurs boundaries, and marks work done without executable proof. Review time goes to reconstructing intent from the diff instead of validating behavior.
| Common failure | Local response |
| --- | --- |
| Implementation starts before requirements are understood | `saf-create-spec` and `saf-create-prompts` |
| A task is too large for one controlled change | `saf-implement` or `saf-implement-multi` |
| Output is accepted without evidence | `saf-check-task` and `saf-validate` |
| A PR loses traceability to the feature | `saf-create-pr`, `saf-review-pr`, and `saf-fix-pr` |
See [why this exists](docs/why-this-exists.md) for the short form. For the control-plane mental model, see [sdd-agentic-flow model](docs/sdd-agentic-flow-model.md) and the [engineering model](docs/engineering-model.md).
## Beyond prompts
Most agent tooling stops at better prompts. **sdd-agentic-flow** makes the engineering boundary explicit:
| Concern | One-line role |
| --- | --- |
| Prompt | Task instructions per skill |
| Context | Specs + project context + config |
| Harness | Modes, contracts, safety, evidence rules |
| Host execution | Loops, sessions, and workers chosen by the host |
**SDD** defines done before implementation starts. SAF defines constraints and admissible transitions; the host executes. Evidence Graph is a read-only traceability projection, not an execution graph. Read the [engineering model](docs/engineering-model.md) for the full map.
## The solution
Write the spec first. The spec is the contract between you and the agent: behavior, scope, and acceptance criteria live in `.specs/features/` before anyone edits production code.
You delegate a bounded outcome; the toolkit holds the workflow contracts and evidence gates. Manual,
supervised, and autonomous modes determine how much progression the agent owns. Each phase has a
Markdown skill, local safety defaults, and evidence artifacts you can inspect. Read [SDD methodology](docs/sdd-methodology.md) for the full picture.
## What changes for you
| Outcome | How this toolkit delivers it |
| --- | --- |
| Task boundaries | Specs, task prompts, and `saf-check-task` per slice |
| Traceability | Spec → prompt → code → PR package in one chain |
| Evidence before done | TDD baseline, check reports, validation reports |
| Clearer agent input | Written specs and `.sdd-agentic-flow/config.yml` replace repeated chat context |
| Async teamwork | Versioned artifacts in `.specs/` and `.sdd-agentic-flow/` |
| Reversible setup | `uninstall --plan`, explicit install scope, [trust model](docs/trust-model.md) |
> [!NOTE]
> Token economics benchmark: planned for a future release ([ROADMAP.md](ROADMAP.md)). This README does not quote token or speed multipliers without measured data.
## Get started
Requires Node.js >= 22 for the CLI only. Your project does not need Node.js. See [environment compatibility](docs/environment-compatibility.md).
```bash
npx sdd-agentic-flow
```
That is the canonical human entry point: it routes first use, existing setup, partial setup, and
recovery. The explicit lifecycle is install the official bundle once, initialize each Git
workspace, and configure policy only when overrides are needed. The CLI is a **control plane** for setup, inspection, guidance, and maintenance. It does
not invoke skills. See [What is SDD?](docs/what-is-sdd.md), the [engineering model](docs/engineering-model.md),
and the [commands reference](docs/commands.md).
For scripted or advanced flows, use `npx sdd-agentic-flow install`, then
`npx sdd-agentic-flow init`, then `npx sdd-agentic-flow doctor`.
The built-in policy is **Supervised** (`apply` + `supervised`). Use `config policy` to persist
explicit overrides; `init` never creates policy configuration merely because it ran.
| Preset | Writes | How the path runs |
| --- | --- | --- |
| `supervised` (recommended in guided TTY; aliases `assist`, `assisted`) | `apply` + `supervised` | Propose next skill; you confirm |
| `manual` (fail-safe non-interactive default; alias `man`) | `guided` + `manual` | Stop after each skill |
| `autonomous` (alias `auto`) | `full` + `autonomous` | Owns local planning, repair, and validation until verified completion within delegated authority |
See [configuration](docs/configuration.md) for explicit policy overrides.
**Autonomous does not mean unlimited authority.** It resolves ordinary failures and repair cycles
without intermediate questions, while commit, push, merge, tag, publish, deploy, and other external
or irreversible actions stay outside the delegation. The CLI does not run skills.
Next: invoke `saf-route` or open the [skills usage guide](docs/saf-skills-usage-guide.md). Copy a prompt from [prompt recipes](docs/prompt-recipes.md) when you delegate to an agent.
For the guided path, customization options, and non-interactive setup rules, see
[getting started](docs/getting-started.md).
## How it works
**Canonical workflow path:** Plan → Prompt → Implement → Check → PR → Review → Fix → Validate
```mermaid
flowchart TD
route[saf-route] --> brainstorm[saf-brainstorm]
brainstorm -->|converged| specs[saf-create-spec]
route --> specs
specs -.->|on demand| explain[saf-explain]
specs --> prompts[saf-create-prompts]
prompts --> implement[saf-implement]
prompts -->|dependent tasks| implementmulti[saf-implement-multi]
implementmulti -->|delegates per task| implement
implement --> check[saf-check-task]
check --> pr[saf-create-pr]
pr --> review[saf-review-pr]
review -->|findings accepted| fix[saf-fix-pr]
fix --> review
review -->|ready| validate[saf-validate]
```
Invoke `saf-route` when the next step is unclear. It recommends a skill and points to that skill's `SKILL.md`; it does not invoke skills or change files.
## Example workflows
These walkthroughs illustrate artifact shapes and expected CLI behavior. They are
not live agent execution evidence. Executable CLI journeys are maintained in
`scripts/cli-exhaustive.ts` and `scripts/cli-certification.ts`.
| Flow | What it illustrates | Walkthrough |
| --- | --- | --- |
| Greenfield feature | Source item through validation | [task-management](examples/golden/task-management/walkthrough.md) |
| Existing code | Specs from undocumented code | [existing-code mode](examples/golden/existing-code-mode/walkthrough.md) |
| Project context | `context status` / `context refresh` lifecycle | [project-context lifecycle](examples/golden/project-context-lifecycle/walkthrough.md) |
| PR loop | Create → review → fix → review | [pr-flow](examples/golden/pr-flow/walkthrough.md) |
| Autonomy AUTO-001 | Idea → spec under autonomous config | [autonomy-idea-to-spec](examples/golden/autonomy-idea-to-spec/walkthrough.md) |
| Autonomy AUTO-002 | Spec → validate chain | [autonomy-spec-to-validate](examples/golden/autonomy-spec-to-validate/walkthrough.md) |
| Autonomy AUTO-003 | Guardrail pause → resume | [autonomy-guardrail-pause-resume](examples/golden/autonomy-guardrail-pause-resume/walkthrough.md) |
| Autonomy AUTO-004 | Human override (guardrail 3) | [autonomy-human-override](examples/golden/autonomy-human-override/walkthrough.md) |
| Autonomy AUTO-005 | Budget exhaustion (guardrail 6) | [autonomy-budget-exhaustion](examples/golden/autonomy-budget-exhaustion/walkthrough.md) |
The generic [task-management example](examples/golden/task-management/) shows one feature end to end. Autonomy fixtures illustrate recorded continuation and repair state; only executed checks provide evidence for a particular behavior.
## Learn more
| Topic | Doc |
| --- | --- |
| Engineering model and product identity | [docs/engineering-model.md](docs/engineering-model.md) |
| Illustrative developer journey | [docs/developer-journey.md](docs/developer-journey.md) |
| SDD methodology | [docs/sdd-methodology.md](docs/sdd-methodology.md) |
| Architecture | [docs/architecture.md](docs/architecture.md) |
| All 12 skills | [docs/skills-catalog.md](docs/skills-catalog.md) |
| Agent setup | [Codex](docs/using-with-codex.md), [Cursor](docs/using-with-cursor.md), [Claude Code](docs/using-with-claude-code.md), [VS Code + Copilot](docs/using-with-vscode-copilot.md) |
| Language policy | [docs/i18n.md](docs/i18n.md) · [README em português](README.pt-BR.md) |
| Contribute | [CONTRIBUTING.md](CONTRIBUTING.md) |
## Who is this for?
You are a good fit if you adopt Spec-Driven Development, run sprint delivery with review gates, split work into specs and tasks as a tech lead, delegate traceable slices to agents, practice TDD-first delivery, or coordinate multi-agent or multi-task work under human control.
## Not optimized for
Quick one-off scripts, fully autonomous no-review agents, automatic deploy/release pipelines, or workflows that reject specs, task boundaries, and validation checkpoints.
Technical reference (CLI, official bundle, skill map, trust, safety)
## Why trust this toolkit?
- The source, CLI, docs, skills, and checks are open source and inspectable.
- The CLI is small, local-first, and has zero external runtime npm dependencies. Build-time
libraries used by the human-rich terminal UI are bundled into the published artifact.
- It has no telemetry, postinstall script, or outbound CLI network access by default. Network
access is limited to three explicit entry points: `doctor --check-updates`, `upgrade` (and
`--check`/`--plan`), and an interactive bare-welcome ask (human-rich TTY, default N). See
[the trust model](docs/trust-model.md).
- It does not automatically commit, push, merge, deploy, or publish.
- Installation is explicit; by default (`--scope user`) it writes only to per-agent global skill directories and creates zero files in your project. Configuration is explicit in `.sdd-agentic-flow/config.yml`. See [installation scope](docs/installation-scope.md).
- `doctor` and `doctor --smoke` validate local setup, while publishable files are checked for blocked private-context markers.
- Licensing and TLC attribution are documented in [NOTICE](NOTICE) and [LICENSING.md](LICENSING.md).
- Human review remains the final authority.
See [the trust model](docs/trust-model.md) for scope and limits.
## Commands
```text
init [--plan] [--json] [--quiet] [--ascii] [--yes] Initialize the exact current Git workspace
config installation [--scope user|project] [--target ...] [--adoption-mode personal|specs-shared|team] [--plan|--yes] Save intent
context refresh Refresh project context
context [status|refresh|autonomy-state] Show or refresh project context provenance, or autonomy loop state
install [--scope user|project] [--target ...] [--plan|--yes] [--quiet] Install the official bundle
doctor [--json] [--harness] [--smoke] [--contracts] [--autonomy] [--verbose] [--check-updates] Validate package or project setup
upgrade [--check|--plan|--skills-only] Check for / apply CLI and skills updates (confirm-gated)
autonomous-resume [--force] [--override-guard=N --reason=...] Resume an autonomous workflow paused at a guardrail
uninstall --plan Show only toolkit assets that would be removed
uninstall --yes [--purge] [--scope user|project|all] [--target ...] [--verbose] [--quiet] Remove managed assets
learn-sdd Show a one-screen SDD summary
version Show the package identity
completion bash|zsh|fish Print shell completion
help [command] Show the command reference, or one command's usage
```
`doctor --json` writes parseable JSON only. `doctor --smoke` validates init, install, preservation, and doctor in an isolated temporary directory. `doctor --check-updates` is a diagnostic update check; `upgrade --check` is the upgrade-specific read-only check; `upgrade` confirms before mutating. A confirmed upgrade runs the verified package version and reconciles only missing or changed skill/shared files. See [the trust model](docs/trust-model.md) and [the compatibility policy](docs/compatibility-promise.md).
`install` defaults to `--scope user` (writes only to global skill directories). Pass `--scope project --adoption-mode team` to install into `.agents/skills/` inside the project; project scope requires persisted or explicit Team adoption. Use `config installation --plan` to preview target paths. See [installation scope](docs/installation-scope.md).
If `doctor` reports a `WARN`/`FAIL` you do not understand, see [troubleshooting](docs/troubleshooting.md). Every command also accepts `--help` (equivalent to `help `) for its full usage and examples. Add `--quiet` to `init`/`install`/`uninstall` to suppress decorative success output.
Running `npx sdd-agentic-flow` with no command shows a contextual status screen (what's already set up, and one suggested next command) instead of the full reference. It never runs anything on its own. At a genuinely interactive terminal (a real TTY, and no `CI` env var set), it also offers a numbered menu below the status screen; selecting an entry runs the exact same command the equivalent typed invocation would, and the uninstall entry only ever previews (`--plan`), never applies. Piped output, scripts, CI, and agent invocations always see just the status screen, unchanged. Run `npx sdd-agentic-flow help` for the full command reference, or `help ` / ` --help` for one command's usage and examples.
Unknown commands and agent names get a "Did you mean ``?" suggestion under a structured `Try:` block. Colored status output (`PASS`/`WARN`/`FAIL`/...) appears automatically on a real terminal; set `NO_COLOR=1` to force plain text, or pipe/redirect output, which disables color automatically. A pipe or CI run remains deterministic human-readable text; `doctor --json` is the explicit machine contract. `FORCE_COLOR` is honored only on a real TTY; `--ascii` / `SDD_ASCII=1` forces ASCII symbols. Exit codes: `0` success, `1` a handled/validation failure, `2` an unexpected/internal error. See [CLI interaction](docs/cli-interaction.md).
The official bundle contains 12 skills and the shared layer. Language and
policy overrides are optional project configuration; use `config policy` when
an explicit override is needed. See [configuration](docs/configuration.md).
## Execution modes
The toolkit documents five local operating modes: `plan`, `guided`, `apply`, `review`, and `full`. `full` means a coordinated local workflow, not unrestricted autonomy. See [execution modes](docs/execution-modes.md).
## Autonomy levels
`workflow.autonomy_level` (`manual`/`supervised`/`autonomous`, default
`supervised`) is a second, orthogonal axis: `execution_mode` says what a skill
may do, and `autonomy_level` says whether it needs a human before the next one
runs. Missing config resolves to `apply + supervised`; use `config policy` for
an explicit override. Audit it with `doctor --autonomy`, and inspect an
in-flight run with `context autonomy-state` / `autonomous-resume`. See
[autonomy levels](docs/autonomy-levels.md) and [autonomy guardrails](docs/autonomy-guardrails.md).
## TDD baseline
`sdd-agentic-flow` uses a TLC baseline for planning and specifications and a TDD baseline for implementation. The TDD baseline requires adequate behavioral sensors at a contractual seam and recorded current evidence. Test-first is recommended when it sharpens the spec. Full RED → GREEN → REFACTOR is optional and is never treated as harness proof. A passing sensor is evidence, not a correctness verdict. Self-report is not evidence. Specs are living control artifacts; rigor follows uncertainty and risk, not only diff size. See [TDD baseline](docs/tdd-baseline.md) and [baselines](docs/baselines.md) for what this package ships versus the external skills it adapts from.
## Uninstall and rollback
```bash
npx sdd-agentic-flow uninstall --plan
npx sdd-agentic-flow uninstall --yes
```
Uninstall removes only recognized current managed assets, from both scopes by default. It preserves specs, source code, and unknown paths. Use `--scope`/`--target` to select an installation. For a recognized project-state reset, use
`uninstall --yes --purge`. It also removes regenerable toolkit state;
`.specs/features` is never removed by any flag. Add `--quiet` to suppress the trailing
"preserves ..." explanatory line. Use `--purge` for the documented cross-scope reset. See
[uninstall](docs/uninstall.md) and
[compatibility policy](docs/compatibility-promise.md).
## Skill map
For the long-form version of this table, see the [skills catalog](docs/skills-catalog.md).
| Skill | Purpose | Input | Output | Mutates files? | Default mode | Recommended when |
| --- | --- | --- | --- | --- | --- | --- |
| `saf-route` | Recommend next local skill | Request/artifacts | Route recommendation | No | plan | The next step is unclear |
| `saf-brainstorm` | Shape a vague idea | Rough idea | Spec-ready brief | Yes, when converged | guided | The idea isn't spec-ready yet |
| `saf-create-spec` | Plan feature specs | Source item OR existing codebase | Feature spec set | Yes, when authorized | plan | Requirements need structure, or undocumented code needs specs |
| `saf-explain` | Explain a specified feature | Spec package | Plain-language explanation | Yes, when authorized | guided | Someone needs context without reading every artifact |
| `saf-create-prompts` | Generate task prompts | Specs/tasks | Agent-ready prompts | Yes, when authorized | plan | Work must be delegated |
| `saf-implement` | Implement one task | Approved task | Code and evidence | Yes, when authorized | apply | One bounded task is ready |
| `saf-implement-multi` | Plan multi-task execution | Task set | Execution plan | Yes, when authorized | guided | Tasks have dependencies |
| `saf-check-task` | Independent task check | Task evidence | Check report | No | review | Before accepting a task |
| `saf-create-pr` | Prepare PR | Completed change | PR package | Yes, when authorized | guided | Review package is needed |
| `saf-review-pr` | Review PR | PR/change set | Findings | No | review | Reviewing a change |
| `saf-fix-pr` | Fix PR findings | Findings | Corrected local change | Yes, when authorized | apply | Findings are accepted |
| `saf-validate` | Validate feature | Feature evidence | Validation report | No | review | Before completion |
## Agent workflows
Read the [skills usage guide](docs/saf-skills-usage-guide.md), [developer journey](docs/developer-journey.md), [Codex CLI](docs/using-with-codex.md), [Cursor](docs/using-with-cursor.md), [Claude Code](docs/using-with-claude-code.md), [VS Code + GitHub Copilot](docs/using-with-vscode-copilot.md), and [prompt recipes](docs/prompt-recipes.md). For optional companion tooling, see the [recommended companion stack](docs/recommended-harness.md).
The skills are Markdown-first and installed locally. See [agent compatibility](docs/agent-compatibility.md) for validated workflows and limits.
## Domain vocabulary
Language profiles select human-facing output language; a domain glossary records product terms. The glossary is optional, never created by `init`, and may be proposed or written only with explicit authorization. See [domain vocabulary](docs/domain-vocabulary.md).
## Inspiration and guides
The toolkit adapts TLC and TDD baselines and combines Spec-Driven Development, Markdown-first skills, and local safety practices. Those inspirations now include epistemic roles; project contracts remain authoritative. See [inspirations](docs/inspirations.md), [NOTICE](NOTICE), [LICENSING.md](LICENSING.md), the [compatibility promise](docs/compatibility-promise.md), the [compatibility matrix](docs/compatibility-matrix.md), and the [Portuguese skills guide](docs/saf-skills-usage-guide.pt-BR.md).
For decision help, see [choosing a feature profile](docs/guides/choosing-a-feature-profile.md), [adopting in a brownfield repo](docs/guides/adopting-in-a-brownfield-repo.md), and [condensed vs. full TLC/TDD](docs/guides/condensed-vs-full-tlc-tdd.md).
## Safety boundaries
The CLI does not call external APIs, require a tracker, sync remotely, or perform Git/release operations by default. Opt-in update paths (`doctor --check-updates`, `upgrade`, welcome ask) never mutate without confirmation. A confirmed `upgrade` uses the exact registry version it checked, updates the global package only when the current installation is global, and reconciles only missing or changed managed skill/shared files. Divergent local files remain protected unless you explicitly confirm overwriting them. This toolkit is not a compliance, security, or production-readiness guarantee. Review outputs and local changes before accepting them. See [safety model](docs/safety-model.md).
## Publishing
Maintainers: see [publishing](docs/publishing.md).