@gtrabanco/pi-agentic-workflow 0.13.3 → 0.14.0

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

package/skills/implementation-discovery/SKILL.md

@@ -1,209 +0,0 @@
----
-name: implementation-discovery
-user-invocable: false
-version: 1.1.0
-author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
-license: MIT
-description: >
-  Internal contract: the single owner of the bounded pre-write implementation
-  discovery step. One read-only mapper that closes seven evidence questions,
-  emits one fixed compact map, and routes READY | REPLAN | NEEDS-DESIGN |
-  BLOCKED before any branch, planning, or source write. Consumed only by
-  execute-phase on the pre-write route. Not a menu entry.
----
-
-# Implementation Discovery (internal)
-
-The one authoritative owner of the bounded, read-only pre-write mapper consumed
-by `execute-phase`. A phase does not touch the repository until this step has
-closed its questions and said `READY`. Nothing else may define what a valid
-pre-write discovery pass is.
-
-## When to use
-
-- `execute-phase` — before any branch/planning/source write, after the read-only
-  dependency/status/acceptance/phase/feature-28 receipt checks.
-- The step runs only on the pre-write route; it is never a general-purpose
-  orientation pass and never a substitute for planning.
-
-## Inputs (exact, only these)
-
-The mapper receives only:
-
-- the governing SPEC/fix obligations for the current phase;
-- the current feature-28 SPEC and Plan receipt digests;
-- the phase-relevant rows from frozen planning evidence, with source revision,
-  affected decision/obligation, freshness, and declared unknowns;
-- the phase fingerprint, ordered tasks, acceptance/obligation ids, and the last
-  progress receipt;
-- source HEAD plus clean-source / allowed-planning-path evidence;
-- applicable NRS / decision / invariant evidence;
-- the repository discovery tools available in this environment.
-
-## Advisory locators
-
-Semantic/symbol navigation and Engram/memory tools are optional adapters that may
-locate evidence faster; they are never authority. Direct repository/Git/search/
-read/test fallback must satisfy the identical evidence contract, and only
-repository bytes answer a map field. The tool that found a citation does not
-excuse a missing `path:line` or a contradictory claim.
-
-## Seven evidence questions
-
-Every pass must answer — each answer citing repository-relative `path:line`,
-symbol, or test plus exact source revision / content identity:
-
-1. Which entry points and public/internal interfaces own current behaviour?
-2. Which callers, adapters, roles, compatibility surfaces, and failure paths
-   can this phase affect?
-3. Which helpers, patterns, decisions, and invariants constrain the change?
-4. Which tests, fixtures, probes, and production-like scenarios establish
-   current behaviour?
-5. Which exact writes are expected, and which reviewed obligation does each
-   serve?
-6. Which carried planning-evidence claims and Plan assumptions are directly
-   confirmed, refined, stale, missing, or contradicted by source?
-7. Which relevant unknowns remain, who owns them, and what evidence resolves
-   them?
-
-The mapper records conclusions, not every search. Repeating a search/read
-requires a new question, changed source, or insufficient cited evidence;
-otherwise it stops (no-progress).
-
-## Inline and fresh routing
-
-**Inline** is permitted only when behaviour is localized/familiar, targeted
-evidence answers every question, no public/persistence/security/recovery/
-compatibility boundary may change, and the executor can finish the map before
-writing.
-
-**A fresh read-only mapper** is required for cross-module/layer or unfamiliar
-work, public/persistence/security/recovery/compatibility impact, competing
-project patterns, an unproven material Plan assumption, prior failed
-attempts/review bias, or any case where editing would begin before the map
-closes. Same-model fresh context is useful but is not model diversity. Manual
-sequential fresh conversations are the portable fallback.
-
-No file-count threshold participates in the route or the verdict.
-
-## Fixed implementation map
-
-```text
-IMPLEMENTATION MAP — unit-id phase-id
-Map revision: opaque single-consumption id
-Source identity: HEAD + clean-source proof + cited-evidence manifest digest
-Authority: SPEC receipt + Plan receipt + phase fingerprint
-Planning evidence: carried row ids + current confirmation/refinement/conflict
-Obligations: ordered acceptance/fix/obligation ids
-Entry points: path:line or symbol + role + exact evidence
-Affected surfaces: callers/adapters/roles/compatibility/failure paths + evidence
-Current behaviour: evidence-backed summary
-Reuse and constraints: helper/pattern/decision/invariant/fixture + evidence
-Expected writes: ordered path + obligation served + reason
-Validation: falsification probe + TDD target + phase gate
-Plan assumptions: confirmed items + evidence
-Contradictions: none or exact Plan/source conflict
-Unknowns: none or exact missing fact + owner + resolution evidence
-Decision: READY | REPLAN | NEEDS-DESIGN | BLOCKED
-```
-
-## Verdicts
-
-`READY` requires every field, question, and owned obligation covered, no
-material contradiction/unknown, an observed falsification probe, and expected
-writes inside phase authority. It also requires every carried planning-evidence
-row to be confirmed or narrowly refined.
-
-`REPLAN` means source disproves Engineering assumptions while Product remains
-stable, or Plan-level topology/architecture/obligation/validator evidence is
-absent.
-
-`NEEDS-DESIGN` means Product, acceptance, authority, or architecture intent is
-missing or conflicting.
-
-`BLOCKED` names evidence that cannot currently be obtained.
-
-No other verdict exists.
-
-## Routes and upstream owners
-
-A verdict routes, it never repairs. Missing/contradicted Plan-level topology,
-architecture, obligations, validators, or assumptions return to
-`plan-feature`/`plan-fix` plus a fresh `review-plan`. Product/acceptance/
-authority/architecture gaps return to `design-feature` then `review-spec`. A
-verdict with unavailable evidence is one exact `BLOCKED` prerequisite. Mapping
-does not decide code correctness — candidate review, verification, and audit
-authority are unchanged, and a second repair/re-review cycle inherits feature
-28's `CONVERGENCE-ANOMALY` diagnosis.
-
-Source-local findings stay local; Plan/Product defects return upstream. A
-missing current-unit behaviour entailed by reviewed scope joins the obligation
-map and routes upstream; it is never a follow-up issue and never calls the
-forge.
-
-## Legacy and manual routes
-
-The portable fallback uses sequential fresh conversations with exact
-artifact/source bindings. It may not claim a machine receipt or a durable
-guarantee it cannot produce; it says plainly what was observed and what was
-not.
-
-## Early falsification
-
-Before READY, run the cheapest relevant read-only probe: a focused existing
-test, current parser/CLI output, public type/schema inspection, symbol callers,
-or an existing fixture. Record the command/query, the observed result, and the
-evidence. A failed probe informs REPLAN/NEEDS-DESIGN; unavailable high-risk
-evidence is BLOCKED, never rewritten as confident evidence. This does not
-replace TDD or later verification.
-
-## No-progress
-
-Conclusion once. Do not re-read or re-search to reconfirm the same conclusion
-without a new question, changed source, or insufficient cited evidence. On
-repetition, stop with `BLOCKED` and name what is still missing. Re-read is
-allowed only for a changed source revision, a new question, insufficient
-evidence, or a contradiction.
-
-## Read-only boundary
-
-The mapper reads; it may not write. It creates no forge issue, no committed
-map, no planning unit, no schema, no source edit, and no test edit. It emits the
-map and reuses `SkillOutcome v1`. A missing current-unit behaviour entailed by
-reviewed scope joins the obligation map and routes upstream; it is not a
-follow-up issue. Discovery never calls the forge.
-
-## Writer handoff
-
-The writer receives frozen phase authority plus the fixed compact map. It does
-not receive raw files, repeated summaries, raw planning discovery, raw
-exploration history, or the authoring conversation unless a cited claim cannot
-be interpreted without a focused excerpt. The map preserves the phase-relevant planning-evidence ids and
-their current confirmation. The writer may only touch expected paths /
-obligations; a newly discovered path or contradiction stops and remaps/routes
-rather than expanding silently.
-
-## Source identity
-
-Source identity is exact pre-map HEAD, proof that tracked/untracked changes
-outside the allowed planning paths are absent, an ordered manifest digest of
-every cited evidence path/content plus the current phase/receipt bindings, and
-an opaque `mappingRevisionId` created for this mapping event.
-
-## Preparation continuity
-
-After READY, deterministic setup may create the branch and commit only the
-already-reviewed planning paths. Before the first source/test edit the executor
-proves either HEAD is unchanged or the new commit is a direct descendant whose
-entire diff is the allowed planning set and whose authority/content digests
-match. Any other path, parent, receipt, phase, or evidence change invalidates
-the map and routes again.
-
-## Consumption and recovery
-
-READY is single-consumption: the first implementation write consumes it. A crash
-before the write may resume only after freshness/no-consumption proof. A crash
-after any partial write remaps current source during recovery. A new map
-revision plus changed Git causal identity prevents reuse after revert; direct
-out-of-protocol state manipulation cannot be claimed detectable without runtime
-history.