@gtrabanco/pi-agentic-workflow 0.13.2 → 0.14.0

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

@@ -1,21 +0,0 @@
-## Phase handoff record (`progress.md` — fixed schema)
-
-Every phase ends by APPENDING one entry to the unit's `progress.md`. Feature
-mode: the file `plan-feature-scaffold` created. Phased XS/S single-pass and
-`--fix` units: create `progress.md` beside the SPEC on P1 (the SPEC's
-checkboxes stay the task ledger; this file is the **handoff channel**).
-Fixed schema — all five lines present, `none` is valid, free prose is not:
-
-```
-## P<k> — <YYYY-MM-DD>
-- Done: <the phase's delivered tasks, one line>
-- Remains: <in-unit work still open, or none>
-- Gotchas: <surprises, workarounds, or decisions the NEXT phase must know, or none>
-- Files: <paths touched>
-- Next: P<k+1> — <its title> | unit finished
-```
-
-The entry rides the phase commit (no sha in the entry — the carrying commit is
-the phase sha; `git log` resolves it). The next phase starts in a fresh
-conversation and reads only `SPEC.md`, its phase's `TASKS.md` section (or SPEC
-`## Phases`), and `progress.md`. Never rely on prior-session memory.

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

@@ -1,45 +0,0 @@
-## Opportunistic finding policy
-
-Use this only for genuinely out-of-scope work discovered while implementing the
-current unit. Missing acceptance, correctness, security, accessibility, required
-UX/error behavior, or a phase task remains current-unit work — fix/replan/decide
-inside the unit; it is never a proposal or issue.
-
-### Closed decision ladder
-
-Evaluate rows in order; every box in a selected row must pass. Estimates include
-tests and docs.
-
-| Decision | Pass only if every box is true | Action |
-|---|---|---|
-| **Autofix** | ≤15 lines; ≤2 files; files already touched; low risk; no public API/schema/migration/dependency/permission/architecture/user-visible change; objective unchanged | Fix in the current phase commit and run its gate. |
-| **Opportunistic Fix** | ≤40 lines; ≤3 files; files touched or directly covered by the phase test; supports touched behavior/consistency; low risk; no public API/schema/migration/dependency/permission/architecture/acceptance change; objective unchanged | Fix in the phase commit, add focused behavior coverage, run the gate. |
-| **Proposal** | Either fix row fails, evidence is uncertain, work is independent, or product/risk judgment is needed | Do not edit or create an issue. Record a compact proposal with evidence and trigger for explicit user batch triage. |
-
-`≤` is inclusive. Check Opportunistic Fix even after a non-size Autofix failure.
-More than 40 lines/3 files is a Proposal unless it is current-unit work, in
-which case it is `replan-in-unit` and stays on the same branch/PR.
-
-### Record before acting
-
-Append one row to `decisions.md` before editing/recording:
-
-```markdown
-| Date | Finding | Evidence | Estimate | Risk | Local files | Decision | Why | Trigger | Record |
-|---|---|---|---|---|---|---|---|---|---|
-| <date> | <finding> | <file:line/command> | <lines/files> | <low/med/high> | <yes/no + paths> | <Autofix/Opportunistic Fix/Proposal> | <boxes> | <when to reconsider> | <commit sha|proposal> |
-```
-
-For a Proposal, `Record` stays `proposal`; no forge operation runs. Batch the
-proposal in the unit's final report. Only an explicit user invocation of
-`triage-issue`/the project's backlog intake may create tracked work, where it
-must dedupe against existing issues first.
-
-### Guardrails
-
-- No automatic `gh issue create` or equivalent from execution, review, fold,
-  audit, or their loops.
-- Never use Proposal to move unfinished SPEC/task scope out of the unit.
-- An uncertain classification becomes Proposal and may stop for user judgment;
-  it never authorizes adjacent edits.
-- `known-issues.md` records blockers, not a substitute backlog.

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

@@ -1,88 +0,0 @@
-## 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: /review-change on the changed HEAD — the mandatory end review (fold-findings only after a REVIEW-FAIL)
-  · findings → /fold-findings (only on a REVIEW-FAIL), then re-run /review-change — triage or replan unresolved findings
-  · merge gate after REVIEW-PASS → /audit-pr
-```

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

@@ -1,37 +0,0 @@
-## 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

@@ -1,43 +0,0 @@
-## 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

@@ -1,26 +0,0 @@
-## 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

@@ -1,38 +0,0 @@
-## 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/generate-docs/SKILL.md

@@ -1,145 +0,0 @@
----
-name: generate-docs
-user-invocable: true
-version: 2.0.1
-argument-hint: "[NN-slug | fix-n | path/glob] [--review]"
-author: "Gabriel Trabanco <1969593+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

@@ -1,15 +0,0 @@
-## 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

@@ -1,33 +0,0 @@
-## 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`).

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

@@ -1,90 +0,0 @@
-## Process
-
-1. **Resolve the scope** — exactly one of, in this order:
-   - an explicit argument (`NN-slug`, `fix-n`, or a path/glob) → that unit's
-     branch diff vs the default branch, or the given paths;
-   - no argument → the current branch's diff vs the default branch;
-   - on the default branch with a clean tree → the last merged unit's diff
-     (`git log --merges -1` → its diff). State the resolved scope in the
-     report.
-
-2. **Select pages with the incrementality checklist.** A guide page is
-   (re)written only if at least one holds — otherwise it is not touched:
-   - ✓ the diff changes files under the page's subject paths (page exists →
-     update it);
-   - ✓ the diff introduces a public entry point (exported API, event, command,
-     route, port) that no existing guide covers (→ create the page).
-
-   **Whole-tree regeneration is Forbidden** — an empty selection is a valid,
-   reportable outcome (`0 pages`, `Decision: PASS`).
-
-3. **Write the pages** into the adapter's guides location (see the adapter
-   table). Fixed page shape, identical on every agent:
-   - **Title** — task-oriented ("Create a domain event"), not file-oriented.
-   - **Frontmatter** — the adapter's required keys **plus the provenance
-     keys** (mandatory, exactly these names):
-
-     ```yaml
-     generated-by: agentic-workflow/generate-docs
-     source-unit: <NN-slug | fix-n>
-     updated: <ISO date>
-     ```
-
-   - **Body sections, in order**: *What this is* (1 paragraph) · *How to do
-     it* (numbered steps citing real paths — `src/...`, clickable) · *Where
-     the pieces live* (table: role → path) · *Related* (links to sibling
-     guide pages that share subject paths).
-   - **File name**: kebab-case derived from the subject module path
-     (`src/domain/events/` → `guides/domain/events.mdx`) — never a
-     model-invented name.
-   - Facts come from the diff and the code — a claim that cannot cite a path
-     does not go in the page.
-
-4. **Knowledge map** (only when the documentation map declares a `map`
-   command). The map is the navigable call/module graph that lets a reader
-   trace an error doc-to-doc to its origin. Rules — no interpretation:
-   - **Run the declared command** (a project script wrapping deterministic
-     tooling — dependency-cruiser, madge, TypeDoc, tree-sitter, an LSP dump…).
-     The model **never infers graph nodes or edges** — zero-token structural
-     truth, or no map at all.
-   - **Validate the output**: JSON with `nodes[]` (each
-     `{"id", "path"}` minimum) and `edges[]` (each `{"from", "to"}`), any
-     extra keys allowed. Invalid → write nothing, report
-     `Map: invalid output — <first mismatch>` and count it as a FAIL.
-   - Valid → write it to the adapter's map location as `graph.json`, then
-     write/refresh one wrapper page per top-level module **the scope
-     touched** (incrementality applies to wrapper pages, not to the JSON):
-     the page lists the module's nodes with source paths, direct callers,
-     direct callees, and links to guide pages sharing subject paths — the
-     stack-trace walk. Wrapper pages carry the provenance frontmatter.
-   - No `map` command declared → `Map: n/a — no map command declared` in the
-     report. Never substitute model inference.
-
-   Per-tool recipes (the mapping each tool needs to emit the shape above):
-   `dependency-cruiser --output-type json` → modules⇒nodes, dependencies⇒edges;
-   `madge --json` → adjacency object⇒edges; TypeDoc JSON → reflections⇒nodes,
-   references⇒edges; tree-sitter/LSP call hierarchy → definitions⇒nodes,
-   calls⇒edges. The project's script owns the mapping; these recipes are
-   documentation for writing that script, not something this skill executes ad
-   hoc.
-
-5. **Review export** (only with the explicit `--review` flag — never
-   automatic; findings may predate their fixes and a public site is a
-   publishing decision). Take the most recent `review-change` report available
-   in the invoking context (or the path the user names), convert its
-   fixed-format blocks verbatim into one page at the adapter's reviews
-   location (`reviews/<unit>-<ISO-date>.mdx` or `.md`), provenance frontmatter
-   included, findings tables intact — no summarizing, no re-judging (that is
-   `review-change`'s output, frozen). No report available → state it in the
-   report block and write nothing.
-
-6. **Verify.** Run the declared docs build command (e.g. `npx astro check`)
-   when the adapter declares one; otherwise check that every intra-docs link
-   in the written pages resolves. Paste the command + exit code (or the link
-   count) in the report. A red build → fix the written pages or revert them;
-   never leave the docs site broken.
-
-7. **Report** (fixed block), then the closing `→ Next:` block as the
-   ABSOLUTE last output. This skill does **not** commit — the pages ride the
-   unit's workflow (the executor or the user commits them with the unit's
-   close-out).