git:20260826.655710e to git:20260912.a990f71

33 added, 16 removed. Audit A to A.

# Agent instructions

- `sdd-agentic-flow` ships Markdown skills and a local CLI for Spec-Driven Development with coding agents. Pick the branch that matches your task.

+ `sdd-agentic-flow` ships Markdown skills and a local CLI for Spec-Driven Development. This file is the canonical source of repository agent instructions; `CLAUDE.md` imports it.

## Maintain this repository

- You change the toolkit itself (CLI, skills, docs, tests). Read [CLAUDE.md](CLAUDE.md) first for commit rules. Then read [CONTRIBUTING.md](CONTRIBUTING.md) for the validation loop (`npm run check`), local CLI sandboxes, and policy constraints. Consumer-facing skills under `skills/` stay agent-neutral; repo-specific rules live here and in CLAUDE.md.

- ## Install the toolkit in a project

- Run `npx sdd-agentic-flow install`, then `init`, then `doctor`. Start at [docs/installation.md](docs/installation.md) for the official bundle and lifecycle. Read [docs/installation-scope.md](docs/installation-scope.md) before choosing `--scope user` (default, no project skill footprint) or `--scope project`. See [docs/configuration.md](docs/configuration.md) for optional `.sdd-agentic-flow/config.yml` overrides.

+ - Before changing CLI, skills, docs, or tests, read [CONTRIBUTING.md](CONTRIBUTING.md) for the development loop, sandboxes, and policy constraints.

+ - Use Node.js >=22 and npm. Edit CLI source in `src/`; `dist/` is generated by the build.

+ - Before adding CLI logic, consult the [source layout](docs/architecture.md#maintainer-source-layout) and use the existing owning module. Keep the CLI entrypoint a thin router.

+ - Before proposing new scope, verify the gap in the current repository and read recent decisions in [ROADMAP.md](ROADMAP.md).

- ## Run an SDD workflow

+ ## Commands and completion

- Read [docs/sdd-methodology.md](docs/sdd-methodology.md) for what Spec-Driven Development means in this toolkit. Follow [docs/saf-skills-usage-guide.md](docs/saf-skills-usage-guide.md) for the Plan → Prompt → Implement → Check → PR → Review → Fix → Validate chain. When the next step is unclear, invoke `saf-route`. Read [docs/invocation-model.md](docs/invocation-model.md) for how skills are selected, not chained automatically. Agent-specific setup: [docs/using-with-cursor.md](docs/using-with-cursor.md), [docs/using-with-claude-code.md](docs/using-with-claude-code.md), [docs/using-with-codex.md](docs/using-with-codex.md), [docs/using-with-vscode-copilot.md](docs/using-with-vscode-copilot.md).

+ Run commands from the repository root. Use focused checks while editing; run both completion gates before reporting a change as validated.

- ## Trust and safety boundaries

+ | Task | Command |

+ | --- | --- |

+ | Install development dependencies | `npm ci` |

+ | Check documentation while editing | `npm run docs:check` |

+ | Full validation gate | `npm run check` |

+ | Private-context gate | `npm run sanitize` |

+ | Try the built CLI in a persistent isolated sandbox | `npm run build`, then `npm run cli:dev -- <args>` |

+ | Test the packed CLI in a fresh isolated sandbox | `npm run cli:sandbox -- <args>` |

- Read [docs/trust-model.md](docs/trust-model.md) for what the CLI does and does not do (local-first, no telemetry, no automatic Git). Read [docs/safety-model.md](docs/safety-model.md) for how agents should treat external content and safety policy. For autonomy levels and guardrails, read [docs/autonomy-levels.md](docs/autonomy-levels.md) and [docs/autonomy-guardrails.md](docs/autonomy-guardrails.md).

+ - Use these sandboxes for CLI development; see [CONTRIBUTING.md](CONTRIBUTING.md#testing-cli-changes-locally-without-publishing) for lifecycle and certification checks.

+ - Report the checks run, their results, and any checks that could not complete. Release procedures and gates are in [docs/publishing.md](docs/publishing.md).

- ## Shared references vs docs

+ ## Contracts and boundaries

- Skills are the public capability layer; the coding-agent host owns runtime execution. SAF defines workflow constraints and admissible transitions, while current evidence supports verification before work can advance. Skills load canonical rules from `shared/references/` at install time (TDD baseline, safety, routing, evidence, handoffs). Human-oriented explanations and CLI surfaces live under [docs/](docs/README.md). When a doc points at a shared reference, treat the shared file as the skill contract and the doc as the reader's guide.

+ - Keep consumer-facing `skills/` agent-neutral. The coding-agent host owns execution, concurrency, branches, and worktrees; SAF supplies workflow constraints and evidence requirements.

+ - Treat `shared/references/` as canonical skill contracts and `docs/` as human-oriented explanations. Change the shared source when changing a contract.

+ - Before authoring a skill, read [skill-authoring-standard.md](shared/references/skill-authoring-standard.md); for readiness or pass/fail outcomes, also read [evidence-standard.md](shared/references/evidence-standard.md).

+ - Preserve zero external runtime npm dependencies, local-first behavior, and safety defaults. Policy exceptions require an explicit project decision under [CONTRIBUTING.md](CONTRIBUTING.md#policy-constraints).

+ - For network, telemetry, or Git behavior, read [trust-model.md](docs/trust-model.md); for external content and safety policy, read [safety-model.md](docs/safety-model.md).

+ - For autonomy changes, read [autonomy-levels.md](docs/autonomy-levels.md) and [autonomy-guardrails.md](docs/autonomy-guardrails.md). For compatibility changes, read [compatibility-promise.md](docs/compatibility-promise.md).

+ - Keep private context out of docs, fixtures, examples, and tests. English is canonical for commands, paths, skill names, and technical tokens; consult [i18n.md](docs/i18n.md) for translations.

- ## Language

+ ## Commit attribution

- English is canonical for commands, paths, skill names, and technical tokens. Brazilian Portuguese introductions: [README.pt-BR.md](README.pt-BR.md), [docs/saf-skills-usage-guide.pt-BR.md](docs/saf-skills-usage-guide.pt-BR.md), [docs/language-profiles.pt-BR.md](docs/language-profiles.pt-BR.md). See [docs/i18n.md](docs/i18n.md).

+ - Every commit's sole author and contributor must be the human maintainer: `gmartins-dev <guilhermemm.dev@gmail.com>`.

+ - Never add `Co-Authored-By`, `Signed-off-by`, `Helped-by`, or other trailers crediting an AI agent or vendor. This overrides agent-client attribution defaults; the contributor graph must not attribute agents or vendors.

+ - The [commit-msg hook](.githooks/commit-msg) is a backstop; enable it as described in [CONTRIBUTING.md](CONTRIBUTING.md#git-hooks).

- ## Troubleshooting

+ ## Install or use SAF

- If `doctor` reports a `WARN` or `FAIL` you do not understand, read [docs/troubleshooting.md](docs/troubleshooting.md).

+ - To install in a consumer project, follow [installation.md](docs/installation.md): `install`, then `init`, then `doctor`. Read [installation-scope.md](docs/installation-scope.md) before choosing user or project scope; optional overrides are in [configuration.md](docs/configuration.md).

+ - To run SDD, read [sdd-methodology.md](docs/sdd-methodology.md) and follow [saf-skills-usage-guide.md](docs/saf-skills-usage-guide.md). Use `saf-route` when the next step is unclear; [invocation-model.md](docs/invocation-model.md) explains selection without automatic chaining.

+ - For unexplained `doctor` warnings or failures, read [troubleshooting.md](docs/troubleshooting.md).