AGENTS.md git:20260912.a990f71A

Immutable. This exact content is served forever at /api/v1/blob/bdcfd89ed4272b40.

# Agent instructions

`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

- 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).

## Commands and completion

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

| 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>` |

- 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).

## Contracts and boundaries

- 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.

## Commit attribution

- 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).

## Install or use SAF

- 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).