@gtrabanco/pi-agentic-workflow 0.13.2 → 0.13.3

package/dist/routing/catalogue.d.ts

@@ -10,7 +10,7 @@ export interface SkillMeta {
  * Minimal frontmatter reader: `name`, `description`, `user-invocable` only.
  *
  * `user-invocable` must say `true` to count: this repository's own rule
- * (CLAUDE.md — the key "REQUIRED for it to appear in the agent's /command menu")
+ * (AGENTS.md — the key "REQUIRED for it to appear in the agent's /command menu")
  * makes absence mean internal, and `scripts/bundle-skills.mjs` reads it the same
  * way. The two scanners agree because the rule is stated once per scanner and
  * pinned by `test/alias-coverage.test.mjs`, not because either default is safe.

package/dist/routing/catalogue.js

@@ -16,7 +16,7 @@ const SKILL_FILE = "SKILL.md";
  * Minimal frontmatter reader: `name`, `description`, `user-invocable` only.
  *
  * `user-invocable` must say `true` to count: this repository's own rule
- * (CLAUDE.md — the key "REQUIRED for it to appear in the agent's /command menu")
+ * (AGENTS.md — the key "REQUIRED for it to appear in the agent's /command menu")
  * makes absence mean internal, and `scripts/bundle-skills.mjs` reads it the same
  * way. The two scanners agree because the rule is stated once per scanner and
  * pinned by `test/alias-coverage.test.mjs`, not because either default is safe.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -44,12 +44,13 @@
   "scripts": {
     "build": "tsc",
     "bundle:skills": "bun scripts/bundle-skills.mjs",
-    "bundle:skills:check": "bun scripts/bundle-skills.mjs --check",
-    "test": "tsc && bun test test/*.test.mjs",
-    "test:node": "tsc && node --test test/*.test.mjs",
-    "prepublishOnly": "bun run build && bun run test",
-    "mutation": "bun scripts/mutation-check.mjs",
-    "prepare": "bun run build"
+    "clean:skills": "bun scripts/bundle-skills.mjs --clean",
+    "test": "bun run bundle:skills && tsc && bun test test/*.test.mjs",
+    "test:node": "bun run bundle:skills && tsc && node --test test/*.test.mjs",
+    "prepublishOnly": "bun run build && bun run bundle:skills && bun run test",
+    "postpack": "bun run clean:skills",
+    "mutation": "bun run bundle:skills && bun scripts/mutation-check.mjs",
+    "prepare": "bun run build && bun run bundle:skills"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.87.0"

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 4.7.0
+version: 4.7.1
 argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"

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

@@ -75,4 +75,4 @@ re-review, while the schedule keeps the late write from being planned at all.
 Each project keeps its own **normalizer inventory** in one place, naming every mutating
 step, its check-only mode where it has one, and the side of the freeze it sits on. In
 this repository that list is in the `## Verification` section of the project guide
-(`CLAUDE.md`), which a plan snapshot already binds as its `project-guide` context row.
+(`AGENTS.md`), which a plan snapshot already binds as its `project-guide` context row.

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 2.9.0
+version: 3.0.0
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -34,7 +34,7 @@ first on purpose).
 ## When to use
 
 - Setting up a repo to use these skills and you want the documentation substrate
-  (`CLAUDE.md` + `docs/` map + templates) adapted to the project, not just copied.
+  (`AGENTS.md` + `docs/` map + templates) adapted to the project, not just copied.
 - Prefer this over a static `npx degit gtrabanco/agentic-workflow/template` when you
   want the gate commands, architecture, and doc domains filled in by interview.
 
@@ -42,14 +42,14 @@ first on purpose).
 
 Inspect the target dir (`[target-dir]`, default cwd) before touching anything:
 
-- Existing `CLAUDE.md` / `AGENTS.md` / `docs/` / `.github/`? If so, **do not
-  clobber** — check first whether it's an **agentic-workflow scaffold**
-  (marker: `CLAUDE.md` present *and* either `docs/features/ROADMAP.md` or a
-  `docs/workflow/` dir). If both markers are present, offer **upgrade** as the
-  default action, alongside merge / adapt-in-place / abort — see **Upgrade
-  mode** below. If `CLAUDE.md`/`docs/` exist but the markers are absent (a
-  foreign scaffold), stay in bootstrap and ask merge / adapt in place / abort
-  as before.
+- An existing **agent guide** (`AGENTS.md`, or a legacy `CLAUDE.md`), `docs/`,
+  `.github/`? If so, **do not clobber** — check first whether it's an
+  **agentic-workflow scaffold** (marker: an agent guide present *and* either
+  `docs/features/ROADMAP.md` or a `docs/workflow/` dir). If both markers are
+  present, offer **upgrade** as the default action, alongside merge /
+  adapt-in-place / abort — see **Upgrade mode** below. If an agent guide or
+  `docs/` exists but the markers are absent (a foreign scaffold), stay in
+  bootstrap and ask merge / adapt in place / abort as before.
 - Detect the stack from manifests (`package.json`, `pyproject.toml`, `go.mod`,
   `Cargo.toml`, `Gemfile`, …) to *propose* gate commands and naming conventions.
 - Note the git state (is it a repo, what's the default branch, and the **remote
@@ -84,7 +84,13 @@ loads exactly upgrade and skips bootstrap plus portability.
 
 ## Guardrails
 
-- **Never overwrite an existing `CLAUDE.md` or `docs/` without explicit consent.**
+- **Never overwrite an existing agent guide (`AGENTS.md`, or a legacy
+  `CLAUDE.md`) or `docs/` without explicit consent.**
+- **One guide, one name.** `AGENTS.md` is the guide; a legacy `CLAUDE.md` is
+  retired only in upgrade mode, only with an explicit yes, and only after any
+  content unique to it is folded into `AGENTS.md` first. A user whose Claude
+  Code release predates `AGENTS.md` support may keep it — that choice is
+  reported as a residual, never treated as drift to repair.
 - **Additive-only, never clobber (upgrade mode).** Upgrade mode only adds
   blocks the project lacks and fills raw placeholders — it never rewrites or
   deletes a block the project already tailored, even if the current template
@@ -136,7 +142,7 @@ OpenCode adapter does not load this fallback.
 
 ## Done when
 
-- A tailored `CLAUDE.md` + `docs/` scaffold + `.github/` templates exist in the
+- A tailored `AGENTS.md` + `docs/` scaffold + `.github/` templates exist in the
   target, unused folders pruned, residual placeholders flagged, the platform's
   companion review skills are recorded (and offered), and the `urgent`/
   `fix-next` labels are seeded (scaffold) or additively reconciled (upgrade),

package/skills/init-workspace/references/BOOTSTRAP_DISCOVERY.md

@@ -61,7 +61,7 @@
      so `review-perf` can measure instead of guess.
    - **Docs site** — does the project have (or want) a developer docs website
      the `generate-docs` skill can write into? If yes, fill the template's
-     `Docs site` block in `CLAUDE.md` (format: starlight/docusaurus/markdown,
+     `Docs site` block in `AGENTS.md` (format: starlight/docusaurus/markdown,
      content dir, build command, optional knowledge-map command — proposed
      from discovery: an `astro.config.*` + `@astrojs/starlight` dependency
      means Starlight). If no, leave the block commented out — `generate-docs`

package/skills/init-workspace/references/BOOTSTRAP_WRITE.md

@@ -1,7 +1,7 @@
 ## Write and verify the bootstrap
 
-4. **Write the adapted scaffold.** Fill the `CLAUDE.md` placeholders (commands,
-   the documentation map rows, architecture); keep `AGENTS.md`, the
+4. **Write the adapted scaffold.** Fill the `AGENTS.md` placeholders (commands,
+   the documentation map rows, architecture); keep the
    `features/_TEMPLATE` + `ROADMAP`, the `fix/_TEMPLATE` + `README`, and the
    `.github/` templates; keep `.agentic-workflow/hooks/` and activate only the
    adapters explicitly accepted in the interview; prune unused doc folders and
@@ -41,7 +41,7 @@
    `review-a11y`, `review-brand`, `review-perf`, `review-seo`) — it installs
    with the skills and covers every review axis, so **no external review skill
    is required on any agent**. If the user wants platform-specific extras (a
-   framework skill, a stack-specific security skill), record them in `CLAUDE.md`
+   framework skill, a stack-specific security skill), record them in `AGENTS.md`
    under a short "Optional review extras" note so `review-change` and
    `product-audit` run them **in addition** — never as a dependency. Don't
    install anything without a yes.

package/skills/init-workspace/references/UPGRADE.md

@@ -4,13 +4,14 @@ Entered when Step 0 finds an existing **agentic-workflow scaffold** (not a
 bare or foreign repo). Bootstrap mode (the Process section above) never
 engages here — upgrade mode reuses the same discovery + interview machinery,
 scoped to **only the blocks the current template has that this project
-lacks**. Seven ordered steps:
+lacks**. Eight ordered steps:
 
 1. **Locate the current template.** Fetch the current `template/` the same
    way bootstrap does — `npx degit gtrabanco/agentic-workflow/template <temp-dir>`
    (always into a temp dir here, never into the target); the SSH/local-path
    variant applies verbatim for a private source.
-2. **Diff the substrate.** Compare the project's `CLAUDE.md` (and the `docs/`
+2. **Diff the substrate.** Compare the project's agent guide (`AGENTS.md`,
+   or a legacy `CLAUDE.md`) (and the `docs/`
    blocks its documentation map references) against the fetched template.
    Produce the list of blocks/conventions the template carries that this
    project's substrate lacks, or still holds as a raw, unfilled placeholder —
@@ -50,16 +51,39 @@ lacks**. Seven ordered steps:
    `path-protection.md` page are proposed from the template; an existing
    owner-written `path-policy.json` is never clobbered and is listed as a
    residual instead. Leave honest placeholders where the user skipped.
-6. **Seed missing urgency labels, additively (feature 15).** Independent of
-   the `CLAUDE.md`/`docs/` block diff above (this is forge-repo state, not a
+6. **Retire the legacy `CLAUDE.md` — only with an explicit yes, never as a side
+   effect.** Older releases of this workflow wrote the guide as `CLAUDE.md`;
+   current ones write `AGENTS.md`, and current Claude Code reads `AGENTS.md`.
+   When the project has a `CLAUDE.md`, three ordered moves — never skip (a):
+   a. **Reconcile first.** Diff `CLAUDE.md` against `AGENTS.md` and fold every
+      block, rule, or value that exists only in `CLAUDE.md` into `AGENTS.md`,
+      keeping the project's own wording and values. Name each folded item in the
+      report; when nothing is unique, say that plainly instead of implying a
+      merge happened.
+   b. **Then ask once, stating the risk.** A user may deliberately be on a Claude
+      Code release that reads only `CLAUDE.md`, and deleting the file would stop
+      their agent from seeing the guide at all. Present the choice as remove
+      (one guide, nothing left to drift) or keep (older client), and take the
+      answer. Never delete a tailored `CLAUDE.md` because "the template moved
+      on".
+   c. **On yes:** delete `CLAUDE.md`, keeping the reconciliation from (a) already
+      written. **On keep:** leave the file byte-identical and list it as a
+      residual naming the reason (the user's client still reads it) — a kept
+      legacy guide is a decision, not drift.
+
+   This step is the only writer of `CLAUDE.md` in upgrade mode, and it is never
+   reached without the answer from (b).
+7. **Seed missing urgency labels, additively (feature 15).** Independent of
+   the agent-guide/`docs/` block diff above (this is forge-repo state, not a
    doc block): check whether the target repo already has the `urgent` and
    `fix-next` labels (`gh label list`); create whichever is missing with the
    same `gh label create` calls bootstrap mode uses (see Process step 9) —
    never touch a label that already exists (additive-only, same never-clobber
    rule as the doc blocks; a pre-existing `urgent`/`fix-next` label the
    project recolored or redescribed is left exactly as-is).
-7. **Report + hand off.** Summarize blocks added, filled, and skipped
-   (residuals), the urgency labels seeded (or already present), then print the
+8. **Report + hand off.** Summarize blocks added, filled, and skipped
+   (residuals), the legacy `CLAUDE.md` outcome (folded items and removed, or kept
+   with the reason), the urgency labels seeded (or already present), then print the
    recommendation to run `product-audit` next to see which newly-available
    *capabilities* apply to the code (upgrade mode migrates the substrate only,
    never the code).
@@ -81,8 +105,9 @@ lacks**. Seven ordered steps:
   separately, via an explicit bootstrap adapt-in-place run, whether to
   re-tailor it.
 - **Bootstrap stays unchanged on a bare or foreign repo.** If Step 0's
-  scaffold markers (`CLAUDE.md` + `docs/features/ROADMAP.md` or
-  `docs/workflow/`) are absent — no repo, an empty repo, or a `CLAUDE.md`
+  scaffold markers (an agent guide — `AGENTS.md` or a legacy `CLAUDE.md` — plus
+  `docs/features/ROADMAP.md` or
+  `docs/workflow/`) are absent — no repo, an empty repo, or a guide
   that isn't this workflow's — upgrade mode never engages; the existing
   bootstrap Process (merge/adapt/abort) runs exactly as before this mode was
   added.

package/skills/plan-fix/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plan-fix
 user-invocable: true
-version: 3.3.0
+version: 3.3.1
 argument-hint: <issue-number> [<issue-number> …]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT

package/skills/plan-fix/references/PLANNING_PROCESS.md

@@ -14,7 +14,7 @@ inferred around.
    (use the declared forge equivalent). Any failure stops the whole set. Translate
    issue text to the artifact language; ask only on material ambiguity. Derive a
    kebab-case topic (≤40 chars, no leading verb) from the primary issue title.
-2. **Read the docs map.** Read `CLAUDE.md`, then relevant mapped docs; every SPEC
+2. **Read the docs map.** Read `AGENTS.md`, then relevant mapped docs; every SPEC
    claim cites a path/section.
 3. **Locate affected code.** Name per issue the layers, modules/files, ports,
    adapters, and entities.

package/skills/plan-fix/references/SPEC_CONTRACT.md

@@ -7,7 +7,7 @@ Follow the project's **Workflow conventions** question protocol (what / scope /
 The base template at `docs/fix/_TEMPLATE/SPEC.md` is mandatory. Add these sections in order, after the existing ones:
 
 - **Impact** — layers touched (per the architecture doc); modules and files (paths); blast radius; detection lead time.
-- **Rules that must never be violated** — project-wide invariants the fix must preserve, from CLAUDE.md "Hard rules" + the cited docs. E.g. "Domain value-object rules hold", "Inner layers cannot import outer layers".
+- **Rules that must never be violated** — project-wide invariants the fix must preserve, from AGENTS.md "Hard rules" + the cited docs. E.g. "Domain value-object rules hold", "Inner layers cannot import outer layers".
 - **Operational risks** — scheduled-job / queue / cache / schema / external-adapter interactions; concurrency or eventual-consistency hazards.
 - **Security risks** — auth, secrets, PII, webhooks, rate-limits.
 - **Compliance touchpoints** — any domain/compliance rules; note "n/a" explicitly if none.

package/skills/product-audit/SKILL.md

@@ -2,7 +2,7 @@
 name: product-audit
 user-invocable: true
 disable-model-invocation: true
-version: 3.2.0
+version: 3.2.1
 metadata:
   opencode/autoinvoke: false
 argument-hint: <path-or-area> (optional — defaults to the whole product)
@@ -125,7 +125,7 @@ Verdict: <one-line honest health verdict>
   (none — <why>)
 
 ### Tooling — register / re-design
-  - <skill|MCP> — register in CLAUDE.md (Optional review extras): <why> — route: user edits CLAUDE.md
+  - <skill|MCP> — register in AGENTS.md (Optional review extras): <why> — route: user edits AGENTS.md
   - <skill|MCP> — would change <feature> scope: <why> — route: /design-feature <slug>
   (none — <why>)
 
@@ -161,7 +161,7 @@ security items to track first").
   lineage lives only in Delta mappings as `<audit-id> F<k>`, never global slugs or
   replaced ids. When the user accepts, route: `triage-issue` files/classifies,
   `plan-feature` adds roadmap work, `plan-fix` scopes a concrete fix.
-- **Never registers tooling or edits `CLAUDE.md`.** The tooling sweep proposes a
+- **Never registers tooling or edits `AGENTS.md`.** The tooling sweep proposes a
   skill/MCP to register, but the user (or a routed `design-feature` run)
   performs the edit; a scope-affecting discovery routes to
   `/design-feature <slug>`, which the user approves.
@@ -201,7 +201,7 @@ product-audit (whole product, all axes, periodic)
    └─ proposes ─┬─ Issues to open ........ ▶ triage-issue / plan-fix
                 ├─ Roadmap: add .......... ▶ plan-feature
                 ├─ Roadmap: remove/revise  ▶ triage-issue / roadmap edit   (user decides)
-                └─ Tooling: register/re-design ▶ user edits CLAUDE.md / design-feature
+                └─ Tooling: register/re-design ▶ user edits AGENTS.md / design-feature
 ```
 
 - Broader than `review-change` (one change) and `audit-pr` (one PR); subsumes

package/skills/product-audit/references/AUDIT_PROCESS.md

@@ -41,9 +41,9 @@ step (2–5). Each item ends with exactly one fallback; never pick another one m
 5. **Sweep installed tooling** — (a) inventory the installed skills and
    connected MCP servers available to the agent; (b) cross-reference each
    against the applicable review axes and the roadmap features; (c) classify
-   each as **register** (useful, not yet named in the project's `CLAUDE.md`),
+   each as **register** (useful, not yet named in the project's `AGENTS.md`),
    **re-design** (would change a feature's definition/scope), or
-   **not-relevant**; (d) dedupe against what `CLAUDE.md` already registers —
+   **not-relevant**; (d) dedupe against what `AGENTS.md` already registers —
    only unregistered/relevant items survive into proposals. If the agent
    cannot enumerate its installed skills / connected MCPs, say so plainly
    (no silent caps) rather than inventing an inventory.
@@ -54,7 +54,7 @@ step (2–5). Each item ends with exactly one fallback; never pick another one m
    - **Roadmap: remove or revise** — features that are obsolete, superseded, or no
      longer make sense.
    - **Tooling: register or re-design** — unregistered-but-useful tooling to add
-     to `CLAUDE.md`, or a discovered skill/MCP that would rescope a feature.
+     to `AGENTS.md`, or a discovered skill/MCP that would rescope a feature.
 7. **Number the findings.** Assign every finding in the severity-ranked list a
    sequential id `F1, F2, …` — **one single `F` sequence for the whole audit**,
    in ranked order, regardless of dimension. Never use a different letter per

package/skills/ship-roadmap/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ship-roadmap
 user-invocable: true
-version: 5.2.2
+version: 5.2.3
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--fullauto] | --continue [--fullauto]"
@@ -44,7 +44,7 @@ one bug, or exploratory work use the manual planning/execution flow instead.
 
 ## Step 0 — Discover the project (always first)
 
-Read before acting: `CLAUDE.md`/`AGENTS.md` Workflow conventions, documentation
+Read before acting: `AGENTS.md` Workflow conventions, documentation
 map, `docs/features/ROADMAP.md`, fix index, architecture doc, and `.github/`
 templates. Then establish:
 

package/skills/ship-roadmap/references/FOUNDING.md

@@ -20,7 +20,7 @@ every later decision is made silently and logged with a one-line rationale.
 in-turn (both opus/high — within the ≥ rule), **pre-fed with the interview
 answers** so it asks nothing. Branch discipline:
 
-- **Empty repo:** the scaffold (CLAUDE.md, docs/, .github/, completed
+- **Empty repo:** the scaffold (AGENTS.md, docs/, .github/, completed
   ROADMAP.md, decision record) is the repo's **initial commit on the default
   branch** — there is no history to protect and no base for a PR yet.
 - **Existing repo:** founding goes on a `docs/ship-founding` branch as a PR.