@luizsantiago/spec-guardrails 3.0.1

package/skills/references/validate.md

@@ -0,0 +1,210 @@
+# Validate
+
+Independent verification of the delivered feature. Always required, never prompted.
+
+## When to Use
+
+- After the last task of a feature is committed
+- After any fix round that follows a FAIL verdict
+
+## Who Runs It
+
+A **fresh verifier context that never wrote the code**. Author ≠ verifier is non-negotiable. The verifier re-derives coverage from the spec instead of inheriting the author's mental model.
+
+When sub-agents are available, dispatch the verifier as a separate agent (see `task-graph-engineering.md`). Without sub-agents, start a clean context and run this file as a fresh-eyes pass.
+
+## Inputs
+
+- `spec.md` acceptance criteria, `context.md` when it exists
+- The diff range for the feature
+- `security-review.md` for the security checklist
+- `appsec.md` only when Complex or an attack-surface trigger fires — then **drop** it before QA
+- `qa-strategy.md` only when Complex, multi-step UI, or an explicit regression ask — never together with `appsec.md`
+- Do **not** load `ship-ready.md` or `code-simplify.md` during Verify (ship is owner-triggered after PASS; simplify is Execute-side)
+- `context-limits.md` — load the spec, the diff, and the tests the spec names; do not load the author's chat; at most one conditional sister at a time
+
+## Output
+
+`.specs/features/[feature]/validation.md`
+
+## Procedure
+
+### 1. Spec-anchored outcome check
+
+For each acceptance criterion, confirm that a test asserts the **spec-defined outcome** — not merely that the code runs. Flag criteria where the test asserts an implementation detail, and flag spec text too imprecise to test.
+
+### 2. Discrimination sensor
+
+Confirm the tests can actually fail:
+
+1. Inject behavior-level faults one at a time in an **isolated scratch copy** — a temp worktree or file copies. Never use `git stash` and never mutate the working tree.
+2. Confirm the relevant test fails for each mutant.
+3. Discard the scratch and verify the real tree is unchanged (`git status --porcelain` matches the pre-sensor baseline).
+4. Any mutant that survives becomes a fix task — the tests do not discriminate.
+
+### 3. Security review
+
+Run the checklist in `security-review.md`. Features with no auth, API, input, payment, or infrastructure surface may take the documented lightweight path — with the justification written into the report.
+
+### 4. Evidence-or-zero
+
+A requirement is satisfied only with a `file:line` reference to an assertive test that passes. No reference means not done, regardless of how the code looks.
+
+### 5. Conditional AppSec (optional)
+
+If the hub AppSec trigger fires, load **only** `appsec.md`, write `## AppSec` (or `skipped — reason`), then **drop** that skill from context. Do not load `qa-strategy.md` yet. If the trigger does not fire, record a one-line skip. Judgment only — not gated.
+
+### 6. Conditional QA (optional)
+
+If the hub QA trigger fires, load **only** `qa-strategy.md` (after AppSec is done or skipped), write `## QA`, then continue. Judgment only — not gated.
+
+### 7. Verdict
+
+Write `validation.md`, then run the completion gate.
+
+## Mutant catalog
+
+Pick mutants from the kind of code that landed, not from a generic list. One killed mutant per risky behavior is the minimum; surviving mutants are fix tasks.
+
+| Code kind | Mutant | Expected killer |
+| --- | --- | --- |
+| Auth / session | Skip the expiry check; accept an empty token; invert role comparison | Test that names the denied case |
+| HTTP handler | Return 200 on the error path; swap 401/403; drop the error code body | Status + code assertion |
+| Validation | Remove an upper/lower bound; accept the empty string; skip a required field | Boundary test |
+| Persistence | Skip the unique constraint; write without a transaction; ignore not-found | Duplicate / rollback / 404 test |
+| Payments / money | Off-by-one on minor units; skip idempotency key; apply a refund twice | Amount and replay tests |
+| Concurrency | Drop a lock or compare-and-swap; process the same event twice | Idempotency or conflict test |
+| State machine | Allow a backward transition; skip the terminal-state guard | Illegal-transition test |
+
+A mutant that the compiler or typechecker rejects before a test runs does not count. Change behavior, not syntax.
+
+**Weak assertion tells.** Treat the test as weak when it asserts any of: `toBeDefined()`, a 2xx status with no body, "the function was called", or a snapshot of an entire module. The spec names an outcome; the test must name it too (status + error code, exact field, exact transition).
+
+Do not inject mutants that the spec does not constrain. A surviving mutant of unspecified behavior is a spec gap, not a test gap — send it back to Specify.
+
+## Gap catalog
+
+Every FAIL names a gap type so the author knows which loop to re-enter.
+
+| Gap | Meaning | Return to |
+| --- | --- | --- |
+| Missing evidence | No `file:line` for a criterion | Execute — add the assertion |
+| Weak assertion | Test checks that code ran, not the spec outcome | Execute — rewrite the test |
+| Surviving mutant | Discriminating test is absent | Execute — add the killer test, then the production fix if needed |
+| Imprecise criterion | Spec cannot be tested as written | Specify — rewrite with `SHALL`/`MUST` and a trigger |
+| Spec deviation | Implementation does something the spec forbids, or omits something it requires | Specify + Execute |
+| Security finding | Checklist item failed | Execute — fix, then re-verify |
+| Open task | `tasks.md` still has `- [ ]` | Execute — finish or drop the task with owner approval |
+| Sensor skipped | No mutant outcome in the report | Verify — run the sensor. On **Medium+** (`design.md` with content, 4+ tasks, or 2+ phases) do not pass — the completion gate blocks. Below Medium+ the gate warns (`--strict` promotes); still run the sensor when risk warrants it |
+
+Rank gaps: security and spec deviation first, then surviving mutants, then missing evidence, then imprecise criteria. The author fixes in that order.
+
+## Evidence format
+
+The completion gate searches for `file:line` (for example `test/routes/login.test.ts:24`). A URL, a CI job name, or "covered by the suite" is not evidence.
+
+- Cite the assertive test, not the production file
+- One evidence line per criterion; reuse a test only when it truly asserts both outcomes
+- After a fix round, cite the new line numbers — stale citations fail the reader even if they pass the regex
+
+## Gate
+
+```bash
+python3 .specs/guardrails/scripts/validate_state.py .specs/features/[feature]
+python3 .specs/guardrails/scripts/validate_state.py [feature]
+python3 .specs/guardrails/scripts/validate_state.py          # single-feature projects
+```
+
+Checks that the report exists, the verdict is exactly PASS in the **preamble** (before the first `##` section) or under a dedicated `## Verdict` / `## Result` / `## Status` heading, every spec requirement ID shares a line with test `file:line` evidence, and no task remains open. A `- Verdict: PASS` buried under Discrimination Sensor or Coverage does not count. Preamble and `## Verdict` must not disagree. Evidence inside fenced samples or HTML comments does not count. `PASS` with any surviving mutant on a sensor/mutant line fails. `PASS` with open `Gaps` bullets or Security Review `Result: fail` fails. On Medium+ features (`design.md` with content, 4+ tasks, or 2+ phases) a discrimination-sensor **outcome** is **blocking** — the section heading alone is not enough — and a Medium+ `PASS` requires at least one `killed` mutant in the sensor focus (`injected` alone, or `killed` only under Gaps, is not enough). Below Medium+ a missing outcome is a warning (`--strict` still promotes warnings). Non-zero exit means the feature is not done.
+
+The gate cannot judge whether a cited test actually asserts the criterion. That judgment is the verifier's; a green gate with a weak assertion is still a FAIL in the report.
+
+**Gate-enforced vs verifier judgment.** `validate_state.py` enforces form: verdict scope, test-path evidence, REQ↔evidence lines, sensor outcomes on Medium+, open Gaps, Security `Result: fail`, open tasks. The following stay **verifier judgment** (not structural gates): whether each coverage row's test truly asserts the outcome, whether a lightweight Security path is justified, Interactive UAT / walkthrough success, and optional `## AppSec` / `## QA` sections. See the [gate stability contract](https://github.com/luizssantiago92/spec-guardrails/blob/main/prd/gate-stability.md).
+
+**Red flags before PASS (judgment):** evidence only in fences/comments; open Gaps with PASS; soft `PASS WITH GAPS`; verdict buried under Sensor/Coverage; config path as evidence; surviving mutant or Medium+ without a kill — these already fail the gate or the reader.
+
+## Template
+
+```markdown
+# Validation: [Feature]
+
+- Verifier: independent agent (clean context)
+- Date: [ISO date]
+- Diff range: [base..head]
+- Verdict: PASS
+
+## Coverage
+
+| Requirement | Test evidence | Result |
+| --- | --- | --- |
+| REQ-001 | test/routes/login.test.ts:24 | pass |
+| REQ-002 | test/auth/token.test.ts:41 | pass |
+
+## Discrimination Sensor
+
+| Mutant | Expected killer | Result |
+| --- | --- | --- |
+| Removed expiry check | test/auth/token.test.ts:41 | killed |
+
+## Security Review
+[Full checklist result, or the justified lightweight path.]
+
+## AppSec
+- Applied: yes | skipped — [reason]
+- Boundaries: ...
+- Top risks: ...
+- Result: pass | fail | escalate | skipped
+
+## QA
+- Applied: yes | skipped — [reason]
+- Smoke: ...
+- Regression focus: ...
+- Result: pass | fail | skipped
+
+## Gaps
+[Ranked list, or "none".]
+
+## Interactive UAT
+- Applied: yes | skipped — [reason]
+- Steps:
+  1. [action] → expect [observable]
+  2. [action] → expect [observable]
+- Result: pass | fail | skipped
+```
+
+Lightweight security path (only when the feature has no auth, API, input, payment, or infrastructure surface):
+
+```markdown
+## Security Review
+- Path: lightweight
+- Justification: copy change in docs/README.md, no input or trust boundary
+- Result: not applicable
+```
+
+An unjustified lightweight path is a gap.
+
+## Failure Handling
+
+**PASS requirements.** Write `Verdict: PASS` only when every coverage row passes (verifier judgment); no surviving mutant appears on a sensor/mutant line (gate blocks that); on Medium+ a sensor **outcome** is present and at least one mutant is `killed` (below Medium+ a missing outcome is a gate warning unless `--strict`); Security is pass or a justified lightweight path (gate blocks `Result: fail`; justification quality is verifier judgment); Gaps is `none` (gate blocks open Gaps bullets); AppSec/QA/Interactive UAT are pass or correctly skipped when their triggers apply (verifier judgment; not gated); and `validate_state.py` exits 0. Anything else is FAIL — do not write PASS and list gaps underneath.
+
+- FAIL verdict → gaps become fix tasks; return to `implement.md`.
+- The fix → re-verify loop is bounded to **3 iterations**, then escalate to the owner with the blocking gap.
+- Every grounded failure — surviving mutant, imprecise spec, failed criterion — is recorded with `lessons.py add --source` pointing at this `validation.md`. A clean PASS records nothing. See `lessons.md`.
+
+## Interactive UAT
+
+Lean walkthrough for **Complex-tier user-facing** work (UI or a human-observable flow). Backend-only, infra, or library changes: skip and record one line in the report (`Interactive UAT: skipped — no user-facing surface`). Not Complex, or not user-facing: skip the same way. Prefer running UAT **after** conditional AppSec/QA steps when those ran.
+
+**When applied**
+
+1. After the automated coverage / sensor / security pass, write a numbered script: each step is `action → expected observable outcome`.
+2. If the owner is in the session, run **one step at a time** and wait for a reply. Otherwise hand them the script.
+3. Interpret replies as: **pass** (“yes” / “works” / “next”), **skip** (“can’t test” / “n/a”), or **issue** (anything else — log the words, add a Gaps bullet, open a fix task).
+
+**FAIL rule.** Automated structural PASS with a failed walkthrough is still a FAIL for the verifier: do not leave `Verdict: PASS` while UAT Result is fail. Put the issue under Gaps and return to Execute. **Interactive UAT is verifier judgment; `validate_state.py` does not require this section and does not run the walkthrough.**
+
+## Next
+
+After `validate_state.py` passes → `archive.md` to fold the feature into domain truth and reset STATE.
+
+Otherwise → `memory.md` and `git-handoff.md` — record decisions, commit `.specs/`, hand off.

package/skills/security-review.md

@@ -0,0 +1,120 @@
+# Security Review
+
+Independent security checklist for the **Verify** phase.
+Use alongside `agent-architecture.md` and `engineering-standards.md`.
+
+## When to Use
+
+- Running `/verify` on any feature touching auth, data, APIs, or infrastructure
+- Before merging PRs that handle user input, payments, or sensitive data
+- After dependency updates (supply chain review)
+
+## Lightweight Path (non-security changes)
+
+For changes with **no** auth, API, user input, payments, or infrastructure impact (e.g. copy, docs, pure UI styling):
+
+1. Verifier still uses clean context (Author ≠ verifier)
+2. Run discrimination sensor on affected tests
+3. Document in `validation.md`:
+
+```markdown
+## Security Review — Skipped (justified)
+- Reason: [no auth/API/input surface touched]
+- Mutants tested: [list]
+- Evidence: [file:line references]
+```
+
+Full OWASP checklist remains mandatory for anything touching auth, data, APIs, or infra.
+
+## Pre-Review Setup
+
+- Verifier must have **clean context** (not the code author).
+- Read `.specs/features/[feature]/spec.md` acceptance criteria.
+- Identify attack surface: inputs, outputs, auth boundaries, data stores.
+
+## OWASP-Oriented Checklist
+
+### Injection
+- [ ] SQL/NoSQL queries use parameterization or ORM safely
+- [ ] Shell commands avoid unsanitized user input
+- [ ] Template rendering escapes user content (XSS prevention)
+
+### Broken Authentication
+- [ ] Sessions/tokens expire appropriately
+- [ ] Passwords hashed with modern algorithms (bcrypt, argon2)
+- [ ] No credentials in URLs, logs, or client-side storage
+
+### Sensitive Data Exposure
+- [ ] Secrets in environment variables, not source code
+- [ ] TLS for data in transit; encryption at rest where required
+- [ ] PII minimized and masked in logs/responses
+
+### Access Control
+- [ ] Authorization checked on every protected endpoint
+- [ ] IDOR prevented — users cannot access others' resources by ID manipulation
+- [ ] Role/permission checks server-side, not client-only
+
+### Security Misconfiguration
+- [ ] Default credentials removed
+- [ ] Error messages do not leak stack traces or internals in production
+- [ ] CORS configured restrictively (not `*` with credentials)
+
+### Vulnerable Components
+- [ ] `npm audit` / equivalent run; critical/high addressed or documented
+- [ ] No known-vulnerable dependencies without mitigation
+
+### SSRF / External Requests
+- [ ] URL fetchers validate allowed domains/schemes
+- [ ] Internal network not reachable from user-controlled URLs
+
+## Discrimination Sensor (Mutants)
+
+Confirm tests catch intentional failures:
+
+1. Remove or bypass an auth check → test must fail
+2. Skip input validation → test must fail
+3. Return wrong status code on error → test must fail
+
+Inject mutants in an **isolated scratch copy** — a temp worktree or file copies. Never use `git stash` and never mutate the working tree. Discard the scratch afterwards and confirm `git status --porcelain` matches the pre-sensor baseline.
+
+Document mutants tested in `.specs/features/[feature]/validation.md`.
+
+## Evidence-or-Zero
+
+Each security requirement from spec must have:
+- Test file and line proving the control works
+- Or explicit documented exception with owner approval
+
+## Output
+
+Write findings into the verifier's report at `.specs/features/[feature]/validation.md`, under the Security Review section defined in `references/validate.md`:
+
+```markdown
+## Security Review
+- Reviewer: independent agent (clean context)
+- Date: [ISO date]
+- Mutants tested: [list]
+- Findings: [pass/fail per checklist item]
+- Evidence: [file:line references]
+```
+
+The completion gate reads this file:
+
+```bash
+python3 .specs/guardrails/scripts/validate_state.py .specs/features/[feature]
+```
+
+## Escalation
+
+If critical vulnerability found:
+1. Do not merge
+2. Record the lesson with `lessons.py add --source` pointing at `validation.md`
+3. Notify the project owner with severity and remediation steps
+
+## Related Skills
+
+- `agent-architecture.md` — SDD hub, execution contract, gates
+- `references/validate.md` — verifier procedure and report schema
+- `engineering-standards.md` — secure coding, commit format, artifact language
+- `git-handoff.md` — git sync and session handoff for `.specs/`
+- `task-graph-engineering.md` — verify node in diamond pattern

package/skills/ship-ready.md

@@ -0,0 +1,50 @@
+# Ship Ready
+
+Lean pre-launch checklist when the owner asks to **ship, deploy, or go live**. Complements Verify — it does **not** replace `/verify` or authorize remote actions.
+
+**Judgment only.** Not gated by `validate_state.py`. Blast radius still applies: `git push`, deploy, and destructive ops need an **explicit** go-ahead for that action.
+
+## When to Use
+
+Load only when the owner explicitly asks for ship / deploy / launch / go-live checklist **after** (or alongside a completed) Verify PASS for the feature in scope.
+
+## When NOT to Use
+
+- Normal Execute or Verify loops
+- “Are we done coding?” — that is `/verify`, not this skill
+- Never load with `appsec.md`, `qa-strategy.md`, or `code-simplify.md` in the same window
+
+## Checklist
+
+Confirm each item or record N/A with reason:
+
+| Item | Ask |
+| --- | --- |
+| Verify | Feature `validation.md` is PASS; `validate_state.py` exits 0 |
+| Tests / CI | Project suite or CI green for this change |
+| Secrets | No secrets in the diff; env/config documented |
+| Migrations | Backward-compatible or rollback noted |
+| Observability | Critical path has log/metric/trace if the project expects it |
+| Rollback | How to undo the release if it fails |
+| Owner go-ahead | Explicit approval for push/deploy named in chat |
+
+## Output shape
+
+```markdown
+## Ship ready
+- Applied: yes | skipped — [reason]
+- Verify: PASS | blocked — [why]
+- CI/tests: pass | fail | n/a
+- Secrets/migrations/obs/rollback: [ok or gap]
+- Push/deploy: waiting for explicit go-ahead | approved — [quote]
+- Result: ready | not ready
+```
+
+`not ready` → Gaps or blockers in `STATE.md`; do not push.
+
+## Related
+
+- `references/validate.md` — Verify first; do not auto-load this on Verify
+- `git-handoff.md` — commit `.specs/`; push still needs go-ahead
+- `agent-architecture.md` — blast radius
+- `references/context-limits.md` — at most one conditional sister

package/skills/task-graph-engineering.md

@@ -0,0 +1,180 @@
+# Task Graph Engineering
+
+Design the **topology** of agent work — which jobs run, in what order, and what can run in parallel.
+Sister skill to `agent-architecture.md` — SDD defines *when* (phases); this skill defines *how jobs connect* within Execute and Verify.
+
+Adapted from task-graph orchestration patterns (MIT). Knowledge-graph content intentionally omitted — this skill covers agent orchestration only.
+
+## When to Use
+
+- Breaking down `/tasks` for multi-step or multi-file features
+- Planning parallel subagent work before `/loop`
+- Deciding whether to spawn multiple agents or keep one sequential context
+- Structuring `/verify` with separate verifier contexts (diamond pattern)
+- Any feature where tasks have real dependencies — or look independent but aren't
+
+## Sister Skills (use together)
+
+| Skill | Role |
+| --- | --- |
+| `agent-architecture.md` | Process — hub, contract, complexity router |
+| `engineering-standards.md` | Quality — one writer per file, commit format |
+| `security-review.md` | Verification — OWASP checklist for `/verify` |
+| `git-handoff.md` | Persistence — git sync for `.specs/` |
+| **`task-graph-engineering.md`** | **Topology — DAG of jobs, parallelism, verify separation** |
+
+## Core Model
+
+A **task graph** is a DAG (directed acyclic graph):
+
+- **Nodes** = jobs (one unit of work you'd hand to a single agent)
+- **Edges** = real dependencies (job B needs job A's *output*, not just "comes after")
+
+Draw the graph in `.specs/features/[feature]/task-graph.md` before `/loop` when the feature has 3+ tasks or any parallel work.
+
+```markdown
+## Task Graph: [feature]
+
+| Node | Depends on | Parallel group | Owner |
+| --- | --- | --- | --- |
+| Task 1: schema | — | A | agent-1 |
+| Task 2: types | — | A | agent-2 |
+| Task 3: API | 1, 2 | — | agent-1 |
+| Verify | 3 | — | verifier (clean context) |
+| Merge + handoff | Verify | — | merge owner |
+```
+
+## The Stop Rule
+
+Before parallelizing, ask: *where does work split into pieces that never read each other's results?*
+
+| Work shape | Strategy |
+| --- | --- |
+| **Splittable** — independent files, modules, or research angles | Parallel workers → separate verify → one merge owner |
+| **Sequential** — each step needs the full picture from the previous step | Single agent, no fan-out |
+
+Multi-agent setups win on splittable work and **lose** on sequential work. More agents is not a strategy — the shape of the work decides.
+
+## Fake Edges
+
+For every "and then" in a task list, ask: does the next job actually read the previous job's output?
+
+- **Real edge**: Task B imports or depends on artifacts from Task A → keep the dependency
+- **Fake edge**: "Write tests and then update README" when README doesn't use test output → delete the edge; run in parallel or reorder
+
+Most hand-built task lists contain 2–3 fake edges. Removing them unlocks safe parallelism.
+
+## The Diamond Pattern
+
+The shape serious systems converge to for splittable work:
+
+| Stage | What runs | Notes |
+| --- | --- | --- |
+| Plan | Single planner | Produces `tasks.md` + `task-graph.md` |
+| Workers | 1–3 parallel agents | Disjoint file ownership only |
+| Verify | Fresh verifier context | Never the code author |
+| Merge | One merge owner | Resolves conflicts, runs harness |
+| Result | Commits + evidence | Handoff to `/archive` when done |
+
+Rules:
+
+1. **Split** only at real boundaries (see Stop Rule)
+2. **Workers** run in parallel with disjoint file ownership (see engineering-standards)
+3. **Verify** in a **separate context** — never the code author; ask diverse questions (correct? current? tested?)
+4. **Merge** has one owner who resolves conflicts and runs the project harness
+
+Maps to SDD: `/tasks` → `/loop` (workers) → `/verify` (diamond verify node) → `/handoff` (merge + persist).
+
+## Sub-Agent Delegation
+
+**Trigger** — Count the tasks. Roughly **8 or fewer** fits one batch: execute inline. More than that: offer sub-agents.
+
+**Offer-then-confirm** — Never auto-spawn. Present the proposed split and wait for the owner to accept.
+
+**Batching**
+
+- A **batch** is the execution unit: one or more consecutive whole phases packed to about **7 tasks**.
+- Phases stay the semantic unit — never split a phase across workers.
+- Batches run **sequentially**; a batch starts only after the previous one reports every task complete.
+- Each worker implements → gates → commits each of its tasks in order, then reports a compact summary: tasks done, commit hashes, test counts, deviations.
+- Workers never spawn further sub-agents.
+
+Full operational contract (worker payload, compact summary template, failure table, merge owner steps): `references/sub-agents.md`.
+
+**Verifier** — After the final task, dispatch a fresh verifier regardless of batch count. It is the closing step of Execute, never prompted. See `references/validate.md`.
+
+**Model tier per role** — When Spec Guardrails allows choosing a model per sub-agent:
+
+| Role | Tier |
+| --- | --- |
+| Mechanical batch (config, wiring, CRUD) | Fast / cost-effective |
+| Core-domain or ambiguous batch | High reasoning |
+| Design phase | High reasoning |
+| Verifier | Mid-to-high — adversarial reasoning, mutant design |
+
+If Spec Guardrails cannot set a per-agent model, ignore this and invest more care on the heavy steps.
+
+## Human Gate
+
+Route **irreversible** actions through explicit human approval:
+
+- Deploy, publish, push to shared branch
+- Delete data, refund, send external communications
+- Merge to main/production
+
+**Placement rule**: gate where a mistake is expensive to undo — not on every step.
+
+| Action | Gate? |
+| --- | --- |
+| Local commit | No (handoff handles this) |
+| `git push` | Yes — human or explicit instruction |
+| Deploy / release | Yes — always |
+| Continue after 3 failed correction loops | Yes — escalate to human |
+
+## Guardrails
+
+1. **Max correction loops** — 3 per task, then escalate (see `agent-architecture.md`)
+2. **One writer per file** — no two jobs mutate the same file in the same round
+3. **Plan in writing** — routing lives in `task-graph.md` and `tasks.md`; agents fill jobs, not the plan
+4. **Cap subagents** — hard limit on parallel agents (default: 3 workers + 1 verifier)
+5. **Evidence over self-report** — judge on harness output (tests ran, linter passed), not agent claims
+
+## Integration with SDD Phases
+
+| SDD Phase | Task graph action |
+| --- | --- |
+| `/tasks` | Identify fake edges; mark parallel groups; link to REQ IDs |
+| `/task-graph` | Draw or revise the DAG in `task-graph.md` |
+| `/loop` | Execute graph — `loop-plan` each round; parallel sub-agents when files are disjoint |
+| `/verify` | Diamond verify node — clean context, diverse checks |
+| `/handoff` | Commit `task-graph.md` with other `.specs/` artifacts |
+
+## When NOT to Use
+
+Skip the task graph for:
+
+- Single-file bug fixes
+- Copy or config-only changes
+- Trivial changes covered by the complexity router in `agent-architecture.md`
+
+## Available Commands
+
+| Command | Action |
+| --- | --- |
+| `/task-graph` | Draw or revise DAG in `.specs/features/[feature]/task-graph.md` |
+| `/tasks` | Atomic breakdown — apply fake-edge and stop-rule checks |
+| `/loop` | Execute graph respecting parallelism and one-writer-per-file |
+| `/verify` | Independent verification (diamond verify node) |
+
+## Related Skills
+
+- `agent-architecture.md` — SDD hub, contract, complexity router
+- `references/tasks.md` — task schema and the `validate_tasks.py` gate
+- `references/validate.md` — verifier procedure for the diamond verify node
+- `engineering-standards.md` — one writer per file, git hygiene
+- `security-review.md` — security checklist for verify node
+- `git-handoff.md` — commit `task-graph.md` at phase boundaries
+
+## Credits
+
+Task-graph patterns adapted under MIT license from [graph-engineering](https://github.com/codejunkie99/graph-engineering) (task-graph half only).

package/templates/GETTING_STARTED.md

@@ -0,0 +1,61 @@
+# Getting started
+
+You installed the **Spec Guardrails**. You do **not** need to memorize CLI commands.
+
+## What to do now
+
+1. Open **Cursor** or **Claude Code** in this project.
+2. Start with **Specify** (an **agent command** — chat, not terminal):
+
+   ```
+   /specify
+
+   Add CSV export to the reports page. Users pick a date range.
+   Out of scope: PDF export.
+   ```
+
+3. Review `.specs/features/…/spec.md` and **approve** before implementation.
+
+---
+
+## Agent commands (chat — not terminal)
+
+Type these in **Cursor or Claude Code**. They load phase procedures from `.cursor/skills/references/`. The agent runs gates for you.
+
+| Command | When |
+| --- | --- |
+| `/specify` | **Start here** — written requirements |
+| `/tasks` | Break into jobs after spec approval |
+| `/loop` | Implement — agent runs `loop-plan` each wave |
+| `/verify` | Fresh-context proof after last task |
+| `/quick` | Tiny fix only (≤3 files) |
+
+**Typical order:** `/specify` → `/tasks` → `/analyze` → `/loop` → `/verify` → `/archive`
+
+**Full reference** (every command, examples, CLI): [Agent commands](https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide/agent-commands.md)
+
+---
+
+## CLI you might run yourself (terminal)
+
+| Command | When |
+| --- | --- |
+| `install` | First time or upgrade |
+| `project-init` | Brownfield repo (optional) |
+| `doctor` | Install looks broken |
+| `validate-spec` / `validate-state` | Double-check gates manually |
+
+Everything else (`loop-plan`, `validate-tasks`, `check-commit`, …) is normally run **by the agent**.
+
+---
+
+## Where things live
+
+| Path | Purpose |
+| --- | --- |
+| `.cursor/skills/agent-architecture.md` | Hub — phase map |
+| `.specs/STATE.md` | Where you left off |
+| `.specs/features/` | One folder per feature |
+| `.specs/guardrails/scripts/` | Automatic gates |
+
+More guides: [docs/guide/Home.md](https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide/Home.md)

package/templates/config.yaml.example

@@ -0,0 +1,28 @@
+# Project guardrails config (optional). Copy to .specs/config.yaml and edit.
+# Or run: npx @luizsantiago/spec-guardrails init-config --preset node-ts
+# Injected into phase procedures via phase-context.
+
+schema: spec-driven
+
+# Extend a built-in preset (default | node-ts | python):
+# extends: node-ts
+
+context: |
+  Tech stack: (fill in)
+  Test command: npm test
+  Branch prefix: feat
+
+rules:
+  specify:
+    - Prefer EARS acceptance criteria
+    - Mark unknowns with [NEEDS CLARIFICATION: question]
+  tasks:
+    - Every REQ must appear in the Test Coverage Matrix
+  verify:
+    - Evidence must cite test file:line paths
+
+# Project-specific overrides (appended on top of preset + rules above):
+# overrides:
+#   rules:
+#     verify:
+#       - Also run playwright e2e before PASS

package/templates/presets/default.yaml

@@ -0,0 +1,16 @@
+# Default preset — general-purpose projects
+schema: spec-driven
+
+context: |
+  Tech stack: (fill in)
+  Test command: npm test
+  Branch prefix: feat
+
+rules:
+  specify:
+    - Prefer EARS acceptance criteria
+    - Mark unknowns with [NEEDS CLARIFICATION: question]
+  tasks:
+    - Every REQ must appear in the Test Coverage Matrix
+  verify:
+    - Evidence must cite test file:line paths