@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/execute-phase/references/UNIT_LOOP.md

@@ -0,0 +1,88 @@
+## Whole-unit execution loop
+
+This route runs only when the user omitted `P<n>`. One user invocation advances
+every remaining planned phase; phase boundaries still own scope, gates,
+documentation, and commits.
+
+### Dispatch
+
+- `execute-phase <NN>` → all remaining feature phases.
+- `execute-phase --fix <n>` → all remaining fix phases.
+- An explicit `P<n>` never loads this route and executes exactly one phase.
+- Default `--max-attempts 3` limits repair attempts for the same unchanged gate
+  failure inside one phase. A positive user value overrides it.
+
+### Queue
+
+Read the unit ledger once and select unfinished phases in ascending order. A
+phase is unfinished when any task is unticked or its evidence/commit is absent.
+Reconcile ticks against repository evidence before selection; contradictory
+state with no unique next phase returns `AMBIGUOUS` and stops.
+
+Materialize the queue before work as explicit phase IDs (`P2, P3, P4`), never
+an empty array, ellipsis, or template placeholder. Every terminal report names
+the phases actually attempted/completed.
+
+The final `Hardening & PR`/close-out phase remains last. Never run it while an
+earlier phase is unfinished.
+
+### Loop — one transaction per phase
+
+For each queued phase:
+
+1. Recompute the frozen `ACCEPTANCE.md` blob and compare it with the acceptance
+   receipt. Mismatch/missing → `ACCEPTANCE GATE BLOCKED`; no edits.
+2. Run phase-lint, architectural-invariant, dependency/own-status fast paths,
+   and the selected mode workflow for this phase. A fail-closed gate ends the
+   whole invocation with its existing fixed block.
+3. Prefer a fresh worker context when the host supports subagents/headless
+   workers; give it only `ACCEPTANCE.md`, `SPEC.md`, this phase's tasks, the last
+   `progress.md` receipt, and the selected workflow contracts. The conductor
+   keeps receipts, never raw source context. Without that primitive, execute
+   inline and apply the same input cap.
+4. Implement the phase, run its exact validators and normal project gate, update
+   unit docs, and commit. Never commit red and never weaken a validator.
+5. On a red gate, feed back only the failing command, exit status, failing test
+   names, and smallest relevant output. Repair the same phase and retry. Same
+   failure with no diff twice, or `--max-attempts` exhausted, stops:
+
+   ```text
+   UNIT LOOP — <unit> BLOCKED at <P<n>>
+   Reason: <NO-PROGRESS|ATTEMPT-BUDGET> · Attempts: <n>
+   Last validator: <command> → <exit/status + compact failure>
+   Preserved: no red commit; acceptance blob <sha> unchanged
+
+   → Next: inspect the named blocker, then re-run /execute-phase <unit>
+     · architecture/product decision required → resolve it before resuming
+     · continue atomically → /execute-phase <unit> <P<n>>
+   ```
+
+6. Before the commit append a compact cycle receipt to `progress.md`:
+
+   ```text
+   ## Unit-loop receipt — <P<n>>
+   - Commit: pending · Gate: <command> (exit 0) · Acceptance blob: <sha>
+   - Next: <P<n+1>|close-out|none> · Attempts: <n>
+   ```
+
+   Commit it with the phase, then replace `pending` with the resulting SHA in
+   the next phase's reconciliation note (never amend an already-published
+   commit only to self-reference it). Reduce working state to the receipt.
+7. Do **not** stop for intermediate review checkpoint triggers. Record any
+   trigger in the receipt for final risk selection; the mandatory independent
+   end review covers the frozen final candidate once.
+
+### Terminal
+
+When the last implementation phase is green, run the existing close-out phase:
+mark done, push, open/link the PR, and leave the branch remote-current. Then:
+
+```text
+UNIT LOOP — <unit> COMPLETE
+Phases: <n> · Commits: <sha list> · Acceptance: <blob> · Gate: PASS
+PR: <url>
+
+→ Next: /loop-review-fold <unit> — select the persisted review/fold route, then triage or replan unresolved findings
+  · manual path → /review-change, then /fold-findings and re-review as required
+  · merge gate after REVIEW-PASS → /audit-pr
+```

package/skills/execute-phase/references/WORKFLOWS_FEATURE.md

@@ -0,0 +1,37 @@
+## Feature mode workflow
+
+**Atomic feature phase** — `docs/features/<NN>-<slug>/`. An explicit `P<n>`
+runs this once; whole-unit mode calls it once per remaining phase.
+
+1. Verify branch (create if on `main`). **P1 only:** if the planning artifacts
+   (`docs/features/<NN>-<slug>/`) are still uncommitted, commit them first on the
+   feature branch — `git add docs/features/<NN>-<slug> && git commit -m "docs(<NN>-<slug>): planning artifacts"` —
+   so planning history stays separate from implementation.
+2. Read `progress.md` first (the phase handoff record — fixed schema above;
+   the last entry's `Remains:`/`Gotchas:` lines are the previous phase's
+   message to you), then `SPEC.md` + the requested phase's `TASKS.md`
+   section. That is the whole handoff — never rely on session memory from a
+   previous phase, and honor the *Context budget* for everything beyond
+   these files.
+3. Implement only that phase (see *Implementation guidance*).
+4. Run the gate (type-check, tests, build). **If red:** fix within the phase's
+   scope and re-run — never commit red. If the failure can't be fixed within
+   this phase's scope, record it in `known-issues.md`, leave the work
+   uncommitted, and stop with a clear report.
+5. Update the per-phase docs.
+6. Stage and commit: `git add <changed files>` then `git commit -m "<type>(<scope>): <summary>"` — one commit per phase, conventional format. Run this; don't just describe what should be committed.
+7. **Explicit-phase mode only:** check the review checkpoint triggers and make
+   the existing non-blocking recommendation when one fires. Whole-unit mode
+   records the trigger in its phase receipt and continues; it never interrupts
+   for an intermediate review. The end review stays mandatory.
+
+**Resuming an interrupted phase (stated contract — any agent must honor it).**
+If, on entry, the unit branch already carries dirty files or commits belonging
+to the requested phase (a prior run died mid-turn — e.g. the driver process
+restarted), do **not** restart the phase from scratch: reconcile against
+`TASKS.md` first — verify each ticked task's evidence actually exists (code
+path / test present), untick any tick without evidence, then continue from the
+first unticked task. Idempotent re-entry is the contract `workflow-status`'s
+crash-recovery verdict `RESUMABLE` relies on. If the ledger contradicts the
+commits in a way that has no unique next task, stop and report instead of
+guessing (that is its `AMBIGUOUS` verdict — a human decides).

package/skills/execute-phase/references/WORKFLOWS_FIX.md

@@ -0,0 +1,43 @@
+## Fix mode workflow
+
+**`--fix`** — `docs/fix/<n>-<topic>/`, template `docs/fix/_TEMPLATE/SPEC.md`,
+index `docs/fix/README.md`. A phased fix runs every remaining phase when `P<k>`
+is omitted and one phase when it is explicit. The final `Hardening & PR` phase
+runs close-out (steps 7–9) after prior phases are green; legacy SPECs run once.
+
+1. Verify the issue exists (`gh issue view <n>`); if it doesn't, create it
+   (`gh issue create --template fix.yml --body-file <path>`, body from the SPEC
+   written to a Markdown file — per the Markdown rule above).
+2. **If `docs/fix/<n>-<topic>/SPEC.md` already exists (e.g. from `plan-fix`), use it — do not re-draft.** Otherwise copy the template, fill every section, and register the entry in `docs/fix/README.md`.
+3. Verify branch (`fix/<n>-<topic>`).
+4. Implement the fix (no separate planning artifacts; the SPEC and its `## Phases` ledger are enough).
+5. Run the gate.
+6. Stage and commit: `git add <changed files>` then `git commit -m "fix(<scope>): <summary>"`. An explicit implementation phase **STOPs here — no push, no PR**; whole-unit mode continues to the next phase.
+7. **Mark done + open the PR — always (the close-out; in a phased SPEC these
+   are the final `Hardening & PR` phase's tasks).** Set the
+   `docs/fix/README.md` entry's status to `done` (built, not yet merged), commit,
+   `git push`, then open the PR with the body written to a Markdown file (per the
+   Markdown rule above): `gh pr create --base main --title "fix(<scope>): <summary>" --body-file <path>`
+   (the body includes `Closes #<n>`). Run the commands. Then, with the returned URL: **print it in the chat**,
+   set the `docs/fix/README.md` entry to `done · [#<pr>](<pr-url>)`, commit
+   (`docs: link PR #<n>`), and push again. A fix **never ends branch-only** —
+   it always leaves an open, chat-linked PR.
+8. **Mandatory review hand-off** → `/review-change`, then `audit-pr` as the merge gate.
+   Print the next step. **Keep the fix-index entry** until the PR is actually merged
+   (don't drop issue tracking early; the merge gate also blocks on pending docs).
+9. **After merge only:** remove the `docs/fix/README.md` entry (or archive it to the
+   project's fix history per its convention) — never before the merge.
+
+**Resuming an interrupted phase (stated contract — any agent must honor it).**
+If, on entry, the fix branch already carries dirty files or commits belonging
+to the requested phase (a prior run died mid-turn — e.g. the driver process
+restarted), do **not** restart the phase from scratch: reconcile against the
+SPEC's `## Phases` checkboxes first — verify each ticked task's evidence
+actually exists (code path / test present), untick any tick without evidence,
+then continue from the first unticked task. Idempotent re-entry is the contract
+`workflow-status`'s crash-recovery verdict `RESUMABLE` relies on. If the ledger
+contradicts the commits in a way that has no unique next task, stop and report
+instead of guessing (that is its `AMBIGUOUS` verdict — a human decides).
+
+(The `Depends on:` check for fixes is the same Dependency gate above — it runs
+before step 1, transitively, and blocks unless `--force`.)

package/skills/execute-phase/references/WORKFLOWS_LEGACY.md

@@ -0,0 +1,26 @@
+## Legacy mode workflow
+
+**Legacy single-pass** — a SPEC **without** a `## Phases` section (drafted
+before `plan-feature-scaffold` 1.8.0 / `plan-fix` 2.1.0) runs the whole unit
+end-to-end in **one pass**. This is the fallback shared by small-feature and
+`--fix` modes; a SPEC that carries `## Phases` never runs it.
+
+1. Verify branch.
+2. Read `SPEC.md` (+ `DECISIONS.md` if present) and the docs its documentation map points to.
+3. If the SPEC is ambiguous on scope / edge cases / UI, ask first — one question at a time, nothing it already answers.
+4. Implement end-to-end (see *Implementation guidance*).
+5. Run the gate; write `CHECKLIST.md` (below).
+6. Stage and commit: `git add <changed files>` then `git commit -m "<type>(<scope>): <summary>"`.
+7. **Mark done + open the PR — always (the close-out).** Flip the roadmap
+   row to `done` (it's *built*; merge state lives in the forge, not the status —
+   see *Marking done*), commit that flip, then `git push` and open the PR
+   (body written to a file as Markdown, per the Markdown rule above):
+   `gh pr create --base main --title "<type>(<scope>): <summary>" --body-file <path>`
+   (put `Closes #<n>` in that body when issue-born). Then, with the URL `gh pr create`
+   returned: **print it in the chat**, update the roadmap row to
+   `done · [#<pr>](<pr-url>)`, commit (`docs: link PR #<n>`), and push again —
+   the link commit rides the same open PR. A single-pass unit **never ends
+   branch-only** — it always leaves an open, chat-linked PR, regardless of the
+   review/audit still to come.
+8. **Mandatory review hand-off** → `/review-change` (the required final quality step;
+   see *Review checkpoint*), then `audit-pr` as the merge gate. Print the next step.

package/skills/execute-phase/references/WORKFLOWS_SMALL_PHASED.md

@@ -0,0 +1,38 @@
+## Small/phased mode workflow
+
+**Phased single-pass units — the default for small (XS/S) feature SPECs.**
+Every current XS/S feature SPEC carries `## Phases` (**≥ 2 phases**; final =
+`Hardening & PR`). `execute-phase <NN>` runs every remaining phase; explicit
+`P<k>` runs one. The SPEC's checkboxes are the execution ledger (there is no
+`TASKS.md`): tick each task with evidence.
+
+**Resuming an interrupted phase (stated contract — any agent must honor it).**
+If, on entry, the unit branch already carries dirty files or commits belonging
+to the requested phase (a prior run died mid-turn — e.g. the driver process
+restarted), do **not** restart the phase from scratch: reconcile against the
+SPEC's checkboxes first — verify each ticked task's evidence actually exists
+(code path / test present), untick any tick without evidence, then continue
+from the first unticked task. Idempotent re-entry is the contract
+`workflow-status`'s crash-recovery verdict `RESUMABLE` relies on. If the ledger
+contradicts the commits in a way that has no unique next task, stop and report
+instead of guessing (that is its `AMBIGUOUS` verdict — a human decides).
+
+Each phase appends its handoff entry to a `progress.md` beside the SPEC
+(created on P1 — see *Phase handoff record*). An implementation phase runs the
+per-phase steps below. Explicit-phase mode **STOPs after the phase commit — no
+push, no PR** (the turn contract's box 5 "unit not finished" rule); unit-loop
+mode continues. The final `Hardening & PR` phase runs close-out after every
+prior phase is green; its pre-written tasks ARE the close-out chain.
+
+Per-phase steps (implementation phases only):
+
+1. Verify branch.
+2. Read `SPEC.md` (+ `DECISIONS.md` if present) and the docs its documentation map points to.
+3. If the SPEC is ambiguous on scope / edge cases / UI, ask first — one question at a time, nothing it already answers.
+4. Implement end-to-end (see *Implementation guidance*).
+5. Run the gate; write `CHECKLIST.md` (below).
+6. Stage and commit: `git add <changed files>` then `git commit -m "<type>(<scope>): <summary>"`. **STOP** — no push, no PR until the final phase.
+
+A SPEC **without** `## Phases` (drafted before those versions) runs the
+**legacy single-pass flow** unchanged, end-to-end in one pass — see
+[legacy workflow](WORKFLOWS_LEGACY.md).

package/skills/fold-findings/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: fold-findings
+user-invocable: true
+version: 1.2.2
+argument-hint: [finding-id …]
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Repair persisted fix-now findings in compatible atomic batches: root-cause
+  fixes, green gate, commit/push, and per-row `folded: yes` updates. Never
+  reclassify or substitute backlog notes. Triggers: "fold-findings", "fix the
+  review findings", "repair audit blockers".
+---
+
+# Fold Findings
+
+Repair persisted fix-now findings. `review-change` and `audit-pr` classify; this
+skill fixes each root cause, never relabeling, deferring, or weakening its check.
+
+## Turn contract — verify before ending the turn
+
+```
+✓ 1. Every finding taken up this turn produced its fixed per-finding output
+     line (FOLDED <sha> | DISPUTED <reason> | BLOCKED <missing input> |
+     REPLAN <proposed phase(s)>) — no finding silently skipped.
+✓ 2. For each FOLDED batch: the gate was RUN (not assumed) and green, one
+     atomic commit was RUN with its sha pasted, and (if the branch has an open PR)
+     `git push` was RUN immediately after that commit.
+✓ 3. The ledger row for each FOLDED finding was flipped `folded: no → yes`
+     in the same commit — never a bare code fix with the ledger left stale.
+✓ 4. No finding was reclassified: no severity downgrade, no fix-now →
+     non-fix-now, no "actually this is fine" — a genuine objection produced
+     `DISPUTED` with evidence for a user decision, never a silent drop/issue.
+✓ 5. The closing `Folded: n/m · Disputed: k · Blocked: j[ · Replan: r]` tally
+     and outcome-branched `→ Next:` block are printed as the ABSOLUTE last output.
+     Every affected finding ID is named in that block, joined with ` + `.
+```
+
+Any unchecked box means the turn is not done.
+
+## When to use
+
+After `/review-change` reports `REVIEW-FAIL` with fix-now rows, or `/audit-pr`
+reports `VERDICT: BLOCKED` (every blocker is fix-now). If the ledger is absent or
+incomplete, reconstruct rows from the verdict in Step 0. Never process
+postpone/wontfix/promote/documented-tradeoff rows; those belong to `/triage-issue`.
+
+## Step 0 — Discover the project (always first)
+
+Per Workflow conventions, read:
+
+1. The unit's `review-findings.md` under `docs/features/<NN>-<slug>/` or
+   `docs/fix/<n>-<topic>/`; schema is owned by `review-change`/`audit-pr`:
+
+   ```
+   | id | file:line | axis | severity | class | route | folded |
+   ```
+
+   After `VERDICT: BLOCKED`, append missing rows (`class: fix-now`, `folded: no`,
+   next free `Fn`, dedupe `file:line`+axis), commit as
+   `docs(<unit>): reconstruct fold ledger from audit-pr blockers`, then fold;
+   never report “no findings”.
+2. Queue `folded: no` rows; explicit IDs restrict it and leave other rows
+   untouched. Group by root cause, verifier and rollback boundary.
+3. The project's verification gate and forge CLI (use the declared forge).
+4. Whether the branch has an open PR; this decides immediate push after commit.
+
+## Progressive loading — fold queue
+
+The allowlist is exactly these two paths; read both, in order, before changing
+code or the ledger:
+
+1. [frozen classification, definition of fixed, and forbidden actions](references/FOLD_POLICY.md)
+2. [per-finding fold process](references/FOLD_PROCESS.md)
+
+Both are normative and one hop from this file. Missing resource → stop; never
+infer a classification or fold procedure.
+
+## Report — return exactly this structure (fixed output contract)
+
+Per finding, in processing order:
+
+```
+| <finding-id> | verdict: FOLDED <sha> | DISPUTED <reason → user decision> | BLOCKED <missing input> | REPLAN <proposed phase(s) → /execute-phase> |
+```
+
+Then exactly:
+
+```
+Folded: n/m · Disputed: k · Blocked: j · Replan: r
+```
+
+Omit `· Replan: r` when `r = 0` (preserves the existing three-field format).
+
+## Guardrails
+
+Scope is the ledger (or explicit ID subset); unlisted discoveries are proposals
+for user triage. Batch only when one root-cause correction, validator set and
+rollback boundary own the rows: one commit/push, individual ticks/lines. Split
+otherwise. Do not widen beyond a finding's file/line/axis unless its root cause
+requires it; explain that in the commit. Artifact language follows user
+instruction > project docs language > English; conversation language never decides.
+
+## Portability (agents other than Claude Code)
+
+Use explicit fallbacks when a primitive is absent: open named `SKILL.md` files in
+a fresh context; use the strongest model for subtle logic/security and never
+weaker than the author; process the compatible queue once and re-run only after
+new review evidence.
+
+## Relationship to other skills
+
+```
+review-change ──FAIL──┐
+audit-pr ──BLOCKED─────┼──▶ fold-findings ──FOLDED──▶ re-run review-change / audit-pr
+                       │                  ──DISPUTED─▶ user decision
+                       │                  ──BLOCKED──▶ user supplies missing input
+```
+
+`review-change`/`audit-pr` classify and persist; this skill only flips
+`folded: no` to `yes` after a real fix. `execute-phase`'s embedded fold checklist
+is the inline fallback; this standalone path keeps frozen classification and its
+forbidden list and never runs above its tier. `DISPUTED` stops for user evidence;
+no issue is created.
+
+## Done when
+
+Every queued finding has its per-finding verdict and tally; every `FOLDED`
+finding belongs to a pushed atomic batch and ticked row. Nothing is reclassified
+or touched outside the queue.
+
+```
+→ Next: (branches on outcome; list every affected finding ID once as `F1 + F2 + …`)
+  · all FOLDED (<F1> + <F2> + …) → /review-change — re-review the branch now that all listed findings are fixed
+  · any DISPUTED (<F1> + <F2> + …) → user decision — resolve every evidenced dispute without creating backlog
+  · any BLOCKED (<F1> + <F2> + …) → supply the listed missing inputs, then re-run /fold-findings
+  · any REPLAN (<F1> + <F2> + …) → confirm all proposed SPEC phases, then /execute-phase on this same branch
+```
+
+Replace placeholders with every actual affected finding ID before printing; never
+print `<F2>`, `…`, or a single representative ID in a live hand-off.

package/skills/fold-findings/references/FOLD_POLICY.md

@@ -0,0 +1,43 @@
+## Frozen classification (hard rule, never relaxed)
+
+This skill **never** edits a finding's `severity`, `class`, or `route`, and
+never moves a finding out of fix-now. Those fields belong to `review-change` /
+`audit-pr`, the skills that produced the verdict — reopening them here would
+let a fix turn into a reclassification. If, while investigating, the finding
+genuinely looks wrong (not reproducible, already fixed elsewhere, or the
+axis/severity is mistaken), that is **evidence for a dispute**, not a
+license to edit the row: mark it `DISPUTED` with the evidence and stop for a
+user decision — the row's `severity`/`class`/`route` stay exactly as written.
+
+## Definition of fixed (checklist — every box, every finding)
+
+A finding is `FOLDED` only when **all** of these hold:
+
+```
+✓ A root-cause diff exists — the actual defect is fixed, not worked around
+✓ The gate is green (type-check + tests + build actually RUN, exit codes
+  pasted — never assumed)
+✓ If the finding was behavioral (a bug, not a style/debt nit): a test or
+  check was added/updated that fails without the fix and passes with it
+✓ The ledger row is ticked `folded: yes`, in the same commit as the fix
+✓ The commit is made AND pushed — an unpushed fix does not exist for CI, the
+  reviewer, or the merge gate (skip the push only if the branch has no PR yet
+  and the unit's own workflow says push happens later, at the PR step)
+```
+
+## Forbidden (never — even if it "would resolve the finding")
+
+```
+✗ Adding a known-issues.md / backlog entry instead of fixing the code
+✗ A decisions.md tradeoff note that accepts the defect as-is
+✗ Deleting, skipping (.skip, .only elsewhere), or loosening a test to make it pass
+✗ eslint-disable / @ts-ignore / equivalent suppression AS the fix
+✗ A TODO/FIXME stub left in place of the actual fix
+✗ Ticking `folded: yes` without a reviewer-mappable diff behind it
+✗ Fixing anything NOT on the ledger (or not in the explicit finding-ID
+  scope this turn was given) — record an independent proposal for explicit
+  user triage, never bundle it silently or create an issue
+```
+
+Something forbidden looks like the only option → stop, do not apply it, and
+mark the finding `DISPUTED` or `BLOCKED` with the reason instead.

package/skills/fold-findings/references/FOLD_PROCESS.md

@@ -0,0 +1,41 @@
+## Process
+
+1. **Build the queue.** Take every `folded: no` fix-now row, or the explicit ID
+   subset, in severity/id order. `replan-in-unit` rows emit `REPLAN`; they stay
+   on the same SPEC/branch/PR and never become issues.
+2. **Form the fewest atomic correction groups.** Findings may share one group
+   only when all boxes pass:
+
+   - one root cause or one homogeneous mechanical correction owns them;
+   - one validator set proves every member fixed;
+   - they can ship and roll back together without partial correctness;
+   - no member needs a separate product/architecture decision or stronger
+     release sequence;
+   - the combined diff remains reviewable and inside the current unit.
+
+   Shared files are neither required nor sufficient. A cross-file auth repair
+   may group; two unrelated nits in one file may not. Record each group's IDs,
+   shared cause, validators, and rollback boundary before editing.
+3. **Repair one group at a time.** Diagnose the shared cause, implement the
+   smallest complete correction, and add/update regression coverage for every
+   behavioral member. Use the strongest tier required by the most subtle member.
+4. **Verify.** Run the group's validators plus the normal project gate. Red →
+   continue repairing only this group. Same failure with no diff twice →
+   `BLOCKED NO-PROGRESS`; never commit red or weaken a check.
+5. **Persist atomically.** Flip every group row `folded: no → yes`; stage the
+   group diff + ledger; commit:
+
+   ```text
+   fix(<scope>): fold <F1+F2+…> — <shared correction>
+   ```
+
+   If the PR is open, push immediately. Emit one `FOLDED <same-sha>` line per
+   member so no finding disappears inside the batch.
+6. **Continue groups.** A blocked/disputed group does not prevent independent
+   groups from folding. Leave its rows `no` and emit individual outcomes.
+7. **Disputes.** Non-reproducible/already-fixed/wrong findings become
+   `DISPUTED <evidence → user decision>`; never edit classification or create an
+   issue.
+8. **Replan.** If the smallest correct group exceeds a reviewable correction,
+   emit `REPLAN` with proposed phases appended to the same unit. After user
+   confirmation, `/execute-phase <unit>` completes them and ticks the rows.

package/skills/generate-docs/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: generate-docs
+user-invocable: true
+version: 2.0.1
+argument-hint: "[NN-slug | fix-n | path/glob] [--review]"
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Generate incremental, diff-driven developer guides through the project's
+  detected docs adapter. Never regenerate the whole site, scaffold it, or edit
+  source. Triggers: "generate-docs", "generate the docs", "document this unit".
+---
+
+# Generate Docs
+
+Turn the knowledge produced by a unit of work into developer documentation a
+contributor can read on the project's docs website — incrementally, as a
+by-product of shipping, so a public repo's docs stay current instead of
+rotting. A commit says what changed; a guide says how to use it ("how do I
+create a domain event and where do I register its handler").
+
+## Turn contract — verify before ending the turn
+
+```
+✓ The docs adapter was resolved through the Step 0 detection checklist and the
+  outcome (adapter name, or NOT CONFIGURED) is stated in the report
+✓ Every generated/updated page is WRITTEN to disk (paths listed in the report)
+  and carries the provenance frontmatter — or zero pages were written and the
+  report says exactly why
+✓ The verify step was RUN (docs build command or link check) and its result
+  pasted — never assumed
+✓ Artifact language: explicit user instruction > the project's declared docs
+  language > English. The CONVERSATION language never decides
+✓ The fixed report block is printed, then the closing `→ Next:` block, as the
+  ABSOLUTE last output
+```
+
+About to end the turn with any box unchecked? The turn is NOT done — complete
+the missing box first (weak models drop end-of-document duties; this list is
+first on purpose).
+
+## When to use
+
+- **After finishing a unit of work** — `execute-phase` recommends this skill at
+  close-out when the project declares a docs site: document what the unit
+  changed while the context is fresh.
+- **On demand** for a specific area: `generate-docs src/domain/events/`.
+- **`--review`** — export the latest `review-change` report as a docs page so
+  humans can review findings from the website.
+- Not for writing SPECs/planning docs (`plan-feature`), session journals
+  (`log-session`), or reviewing code (`review-change` produces the findings;
+  this skill only publishes an existing report on request).
+
+## Progressive loading — resolve the docs route
+
+The reference allowlist is exactly the three paths below. Read them in this
+order; every selected resource is normative and one hop from this entrypoint.
+
+1. Every invocation: read [adapter discovery](references/ADAPTER_DISCOVERY.md)
+   and resolve the adapter with evidence. `NOT CONFIGURED` stops writing.
+2. Configured adapter only: before choosing any output path or format, read
+   [adapter slots](references/ADAPTERS.md).
+3. Read [generation process](references/GENERATION_PROCESS.md) and execute the
+   scope, incrementality, map/review, verify, and report steps.
+
+Do not load steps 2–3 after `NOT CONFIGURED`. Missing required resource → stop;
+never guess an adapter, output path, or fixed contract.
+
+## Allowed & forbidden (fixed lists — no interpretation)
+
+**Allowed:**
+- Writing/updating pages under the adapter's guides location
+- Updating only the adapter's declared manual sidebar config when the adapter
+  table requires it
+- Running the declared docs build/verify command
+- Reading anything (diff, code, docs)
+
+**Forbidden — never, even if it "would help":**
+- Whole-project doc regeneration (the incrementality checklist is the only
+  page selector)
+- Editing source code, tests, or any config other than the adapter's declared
+  manual sidebar config
+- Scaffolding a docs site (installing Astro/Starlight, creating configs)
+- Writing outside the adapter's content locations, except that declared manual
+  sidebar config
+- Pages without the provenance frontmatter
+- Committing or pushing (the unit's workflow owns the commit)
+
+## Return exactly
+
+```
+GENERATE DOCS — adapter: <starlight|docusaurus|markdown|NOT CONFIGURED> — scope: <scope>
+
+| Page | Action | Source-unit | Subject paths |
+|---|---|---|---|
+| <content-path> | created|updated | <NN-slug> | <paths> |
+
+Map: regenerated (<command>) | n/a — no map command declared | invalid output — <reason>
+Review export: <page path> | not requested | no report available
+Verify: <command + exit code | links checked: <n>, broken: 0 | n/a — not configured>
+Pages: <n> written, <n> skipped by incrementality checklist
+Decision: PASS | FAIL | NOT-CONFIGURED
+```
+
+`FAIL` only when the verify step is red or a written page had to be reverted;
+`NOT-CONFIGURED` per Step 0.5; `PASS` otherwise (including 0 pages).
+
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **No slash-command menu** — where this skill says `/<skill>`, open that
+  skill's `SKILL.md` and follow it literally in a fresh conversation.
+- **No per-skill `model:`/`effort:`** — writing guides is structured
+  summarization over a diff: a **mid-tier** model suffices; never below the
+  tier that can read the project's language accurately.
+- **No argument passing** — state the scope in the invocation message
+  ("generate docs for 01-generate-docs"); the Process step 1 order still
+  applies.
+
+## Relationship to other skills
+
+- **`execute-phase`** recommends this skill at unit close-out when the
+  documentation map declares a docs site (hand-off via `→ Next:` — never
+  composed in-turn).
+- **`audit-docs`** detects orphan/stale generated pages via the provenance
+  frontmatter.
+- **`init-workspace`** records the `Docs site` declaration this skill's Step 0
+  reads.
+- Not a review: findings/quality belong to `review-change`.
+
+## Done when
+
+- The adapter outcome is stated with evidence; every selected page is written
+  with provenance frontmatter; the verify step ran and is green (or the
+  NOT-CONFIGURED report was printed and nothing was written).
+- The fixed report block was returned, then:
+
+  ```
+  → Next: commit these pages with the unit's close-out (they ride the unit's PR)
+    · unit already closed → commit as docs(<unit>): generated guides on the unit's branch
+    · adapter NOT CONFIGURED → add the Docs site block to the documentation map, then re-run /generate-docs
+  ```

package/skills/generate-docs/references/ADAPTERS.md

@@ -0,0 +1,15 @@
+## Adapters (reference implementations)
+
+The generic contract is the slots below; anything stack-specific lives only in
+this table. Starlight is the first-class reference.
+
+| Slot | Starlight (reference) | Docusaurus | Plain markdown (fallback) |
+|---|---|---|---|
+| Content dir | `src/content/docs/` (or the declared one) | `<site>/docs/` (or the declared one) | `docs/site/` |
+| Page format | `.mdx`; frontmatter `title`, `description` + provenance keys | `.mdx`; frontmatter `title`, `description` + provenance keys | `.md`; H1 title + provenance keys in an HTML comment frontmatter block |
+| Guides | `<content>/guides/<area>/<topic>.mdx` | `<content>/guides/<area>/<topic>.mdx` | `docs/site/guides/<area>/<topic>.md` |
+| Knowledge map | `<content>/map/graph.json` + `<content>/map/<module>.mdx` wrappers | `<content>/map/graph.json` + `<content>/map/<module>.mdx` wrappers | `docs/site/map/graph.json` + `docs/site/map/<module>.md` |
+| Review reports | `<content>/reviews/<unit>-<date>.mdx` | `<content>/reviews/<unit>-<date>.mdx` | `docs/site/reviews/<unit>-<date>.md` |
+| Sidebar | Starlight autogenerated sidebar (directory-based); no manual sidebar edits | If the project declares a manual `sidebars.js`/`sidebars.ts`, update only that declared config; otherwise use the Docusaurus autogenerated sidebar and make no sidebar edit. Stop when the sidebar mode or declared config path cannot be resolved. | n/a — directory listing |
+| Verify | declared build command (`npx astro check` / `astro build`) | declared Docusaurus build command (`npx docusaurus build` or project equivalent) | intra-docs link check |
+| Assets | none generated | none generated | none generated |

package/skills/generate-docs/references/ADAPTER_DISCOVERY.md

@@ -0,0 +1,33 @@
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, then
+resolve the **docs adapter** with this checklist — fixed order, first match
+wins, evidence required for the match:
+
+1. **Explicit declaration** — the documentation map contains a `Docs site`
+   block (format, content dir, build command, map command). Evidence: quote
+   the block. → use the declared adapter.
+2. **Starlight** — an `astro.config.*` exists AND `@astrojs/starlight` is in
+   the project's dependencies. Evidence: config path + the dependency line.
+   → Starlight adapter.
+3. **Docusaurus** — a `docusaurus.config.*` exists AND `@docusaurus/core` is a
+   dependency. Evidence: config path + the dependency line. → Docusaurus
+   adapter (same slots as Starlight; `.mdx` under the site's `docs/` dir,
+   sidebar per its convention).
+4. **Plain-markdown fallback** — a `docs/` directory exists. → plain-markdown
+   adapter (always available).
+5. **None of the above** → **NOT CONFIGURED**: write nothing. Print the report
+   with `Decision: NOT-CONFIGURED`, and include this snippet for the user to
+   add to their documentation map:
+
+   ```markdown
+   ## Docs site
+   - format: starlight | docusaurus | markdown
+   - content-dir: <path, e.g. src/content/docs/>
+   - build: <command, e.g. npx astro check | none>
+   - map: <command emitting a nodes/edges JSON | none>
+   ```
+
+Detection is per invocation — never cached, never guessed. A monorepo with
+more than one docs site is a documented limitation: use the first declaration
+found and say so in the report (see the feature's `known-issues.md`).