@chankov/agent-skills 0.2.0 → 0.3.2

package/.claude/commands/{doctor.md → doctor-agent-skills.md}

@@ -2,7 +2,7 @@
 description: Scan agent-skills install targets for broken symlinks and stale persona references, then offer repairs
 ---
 
-Invoke the Doctor scan from the `agent-skills:guided-workspace-setup` skill — Step 5 (the preflight scan) — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup` flow runs the same scan automatically as soon as it detects prior install state.
+Invoke the Doctor scan from the `agent-skills:guided-workspace-setup` skill — Step 5 (the preflight scan) — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup-agent-skills` flow runs the same scan automatically as soon as it detects prior install state.
 
 Walk every install-target directory the chosen coding agent uses (`agents/`, `.claude/agents/`, `.opencode/agents/`, `.codex/agents/`, `.gemini/agents/`, `.github/agents/`, `.pi/agents/` and `pi-pi/`, `.claude/skills/`, `.opencode/skills/`, `.pi/skills/`, `.agents/skills`, `.claude/commands/`, `.opencode/commands/`, `.pi/prompts/`, `.claude/references/`, `.claude/hooks/`). For each broken symlink, resolve where it pointed, look for a canonical replacement in the source `agents/` and `skills/` trees, and offer to repoint or delete. Common stale names from the pre-merge persona layout: `reviewer` → `code-reviewer`, `red-team` → `security-auditor`.
 

package/.pi/extensions/agent-skills-update-check/README.md

@@ -6,7 +6,7 @@ A pi extension that surfaces an "update available" banner once per session when
 
 On the first `agent_start` event of a pi session, the extension:
 
-1. Reads `version:` from `.ai/agent-skills-setup.md` in the current working directory. If the record is missing (workspace was never set up via `/setup`), the check is skipped.
+1. Reads `version:` from `.ai/agent-skills-setup.md` in the current working directory. If the record is missing (workspace was never set up via `/setup-agent-skills`), the check is skipped.
 2. Reads the cached latest version from `$XDG_CACHE_HOME/agent-skills/latest-version.json` (falling back to `~/.cache/agent-skills/`).
 3. If the cache is older than 24 hours or absent, fetches the latest version from the npm registry with a 3-second timeout.
 4. If the published version is greater than the recorded version, emits an `info`-level notification via `ctx.ui.notify`.
@@ -16,7 +16,7 @@ The check runs **once per session** and is bounded to a single network call. It
 ## When the banner fires
 
 ```
-agent-skills update available: 0.1.0 → 0.2.0. Run "npx @chankov/agent-skills@latest update" then /setup to apply.
+agent-skills update available: 0.1.0 → 0.2.0. Run "npx @chankov/agent-skills@latest update" then /setup-agent-skills to apply.
 ```
 
 The banner appears in pi's UI notification area — the same surface used by other extensions for non-fatal status. It does not block, prompt, or modify any file. The user decides when to act on it.
@@ -33,7 +33,7 @@ Every error path silently aborts. Update checks must never disrupt a session.
 
 ## Install
 
-Installed via `/setup` as part of Group 10 — pi extensions. Or symlink manually:
+Installed via `/setup-agent-skills` as part of Group 10 — pi extensions. Or symlink manually:
 
 ```bash
 ln -s /path/to/@chankov/agent-skills/.pi/extensions/agent-skills-update-check \
@@ -54,5 +54,5 @@ The check honours three environment variables (any of them disables it):
 
 - The check runs once per pi session; restarting pi triggers a new check.
 - The cache file is shared with the CLI (`agent-skills check-update`) so both update paths benefit from a single fetch per 24h window.
-- If the install record is *pre-versioning* (no `version:` line), the check is skipped — there's no recorded baseline to compare against. Run `/setup` once to stamp the current version.
+- If the install record is *pre-versioning* (no `version:` line), the check is skipped — there's no recorded baseline to compare against. Run `/setup-agent-skills` once to stamp the current version.
 - The extension only reads; it never writes the install record itself.

package/.pi/prompts/{doctor.md → doctor-agent-skills.md}

@@ -2,7 +2,7 @@
 description: Scan agent-skills install targets for broken symlinks and stale persona references, then offer repairs
 ---
 
-Load and follow Step 5 (Doctor preflight) of the `guided-workspace-setup` skill — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup` flow runs the same scan automatically as soon as it detects prior install state.
+Load and follow Step 5 (Doctor preflight) of the `guided-workspace-setup` skill — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup-agent-skills` flow runs the same scan automatically as soon as it detects prior install state.
 
 Walk every install-target directory the chosen coding agent uses (`agents/`, `.claude/agents/`, `.opencode/agents/`, `.codex/agents/`, `.gemini/agents/`, `.github/agents/`, `.pi/agents/` and `pi-pi/`, `.claude/skills/`, `.opencode/skills/`, `.pi/skills/`, `.agents/skills`, `.claude/commands/`, `.opencode/commands/`, `.pi/prompts/`, `.claude/references/`, `.claude/hooks/`). For each broken symlink, resolve where it pointed, look for a canonical replacement in the source `agents/` and `skills/` trees, and offer to repoint or delete. Common stale names from the pre-merge persona layout: `reviewer` → `code-reviewer`, `red-team` → `security-auditor`.
 

package/.versions/0.2.0/.claude/commands/{doctor.md → doctor-agent-skills.md}

@@ -2,7 +2,7 @@
 description: Scan agent-skills install targets for broken symlinks and stale persona references, then offer repairs
 ---
 
-Invoke the Doctor scan from the `agent-skills:guided-workspace-setup` skill — Step 5 (the preflight scan) — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup` flow runs the same scan automatically as soon as it detects prior install state.
+Invoke the Doctor scan from the `agent-skills:guided-workspace-setup` skill — Step 5 (the preflight scan) — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup-agent-skills` flow runs the same scan automatically as soon as it detects prior install state.
 
 Walk every install-target directory the chosen coding agent uses (`agents/`, `.claude/agents/`, `.opencode/agents/`, `.codex/agents/`, `.gemini/agents/`, `.github/agents/`, `.pi/agents/` and `pi-pi/`, `.claude/skills/`, `.opencode/skills/`, `.pi/skills/`, `.agents/skills`, `.claude/commands/`, `.opencode/commands/`, `.pi/prompts/`, `.claude/references/`, `.claude/hooks/`). For each broken symlink, resolve where it pointed, look for a canonical replacement in the source `agents/` and `skills/` trees, and offer to repoint or delete. Common stale names from the pre-merge persona layout: `reviewer` → `code-reviewer`, `red-team` → `security-auditor`.
 

package/.versions/0.2.0/.pi/extensions/agent-skills-update-check/README.md

@@ -6,7 +6,7 @@ A pi extension that surfaces an "update available" banner once per session when
 
 On the first `agent_start` event of a pi session, the extension:
 
-1. Reads `version:` from `.ai/agent-skills-setup.md` in the current working directory. If the record is missing (workspace was never set up via `/setup`), the check is skipped.
+1. Reads `version:` from `.ai/agent-skills-setup.md` in the current working directory. If the record is missing (workspace was never set up via `/setup-agent-skills`), the check is skipped.
 2. Reads the cached latest version from `$XDG_CACHE_HOME/agent-skills/latest-version.json` (falling back to `~/.cache/agent-skills/`).
 3. If the cache is older than 24 hours or absent, fetches the latest version from the npm registry with a 3-second timeout.
 4. If the published version is greater than the recorded version, emits an `info`-level notification via `ctx.ui.notify`.
@@ -16,7 +16,7 @@ The check runs **once per session** and is bounded to a single network call. It
 ## When the banner fires
 
 ```
-agent-skills update available: 0.1.0 → 0.2.0. Run "npx @chankov/agent-skills@latest update" then /setup to apply.
+agent-skills update available: 0.1.0 → 0.2.0. Run "npx @chankov/agent-skills@latest update" then /setup-agent-skills to apply.
 ```
 
 The banner appears in pi's UI notification area — the same surface used by other extensions for non-fatal status. It does not block, prompt, or modify any file. The user decides when to act on it.
@@ -33,7 +33,7 @@ Every error path silently aborts. Update checks must never disrupt a session.
 
 ## Install
 
-Installed via `/setup` as part of Group 10 — pi extensions. Or symlink manually:
+Installed via `/setup-agent-skills` as part of Group 10 — pi extensions. Or symlink manually:
 
 ```bash
 ln -s /path/to/@chankov/agent-skills/.pi/extensions/agent-skills-update-check \
@@ -54,5 +54,5 @@ The check honours three environment variables (any of them disables it):
 
 - The check runs once per pi session; restarting pi triggers a new check.
 - The cache file is shared with the CLI (`agent-skills check-update`) so both update paths benefit from a single fetch per 24h window.
-- If the install record is *pre-versioning* (no `version:` line), the check is skipped — there's no recorded baseline to compare against. Run `/setup` once to stamp the current version.
+- If the install record is *pre-versioning* (no `version:` line), the check is skipped — there's no recorded baseline to compare against. Run `/setup-agent-skills` once to stamp the current version.
 - The extension only reads; it never writes the install record itself.

package/.versions/0.2.0/.pi/prompts/{doctor.md → doctor-agent-skills.md}

@@ -2,7 +2,7 @@
 description: Scan agent-skills install targets for broken symlinks and stale persona references, then offer repairs
 ---
 
-Load and follow Step 5 (Doctor preflight) of the `guided-workspace-setup` skill — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup` flow runs the same scan automatically as soon as it detects prior install state.
+Load and follow Step 5 (Doctor preflight) of the `guided-workspace-setup` skill — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup-agent-skills` flow runs the same scan automatically as soon as it detects prior install state.
 
 Walk every install-target directory the chosen coding agent uses (`agents/`, `.claude/agents/`, `.opencode/agents/`, `.codex/agents/`, `.gemini/agents/`, `.github/agents/`, `.pi/agents/` and `pi-pi/`, `.claude/skills/`, `.opencode/skills/`, `.pi/skills/`, `.agents/skills`, `.claude/commands/`, `.opencode/commands/`, `.pi/prompts/`, `.claude/references/`, `.claude/hooks/`). For each broken symlink, resolve where it pointed, look for a canonical replacement in the source `agents/` and `skills/` trees, and offer to repoint or delete. Common stale names from the pre-merge persona layout: `reviewer` → `code-reviewer`, `red-team` → `security-auditor`.
 

package/.versions/0.2.0/skills/guided-workspace-setup/SKILL.md

@@ -108,7 +108,7 @@ Present findings in a single table:
 
 Then ask, multi-select: which fixes to apply now. Apply only the picked ones; record skipped items so the install menu can surface them again. Append a `## doctor-runs` line to `.ai/agent-skills-setup.md` with the date, agent, phase (`preflight`), and `repaired` / `deleted` / `skipped` counts.
 
-The doctor scan is also exposed standalone as `/doctor` — running it outside a setup pass is this same scan-and-repair flow without the rest of the install menu.
+The doctor scan is also exposed standalone as `/doctor-agent-skills` — running it outside a setup pass is this same scan-and-repair flow without the rest of the install menu.
 
 ### 6. Present the install menu
 
@@ -207,6 +207,8 @@ Ask `copy` or `symlink` for this run.
 
 Present the full set as one summary table — artifacts to add, update, and remove; their resolved target paths; the chosen install method; and the changes to both `.ai/` files. When the version delta from Step 4 is non-empty, lead the summary with a one-line "Changes since `v<recorded>` → `v<current>`" block sourced from `CHANGELOG.md` (only the entries between the two versions, not the full file). Ask the user to confirm, and write nothing until they do.
 
+**Installer cleanup line.** The summary always ends with one line stating that the installer slash commands (`/setup-agent-skills`, `/doctor-agent-skills` — or `/as-*-agent-skills` for OpenCode — plus the `guided-workspace-setup` skill body) will be removed after apply, so they do not pollute the user's slash-command list. Add the verbatim suffix: *"Reply `keep` to leave them in place; re-run `npx @chankov/agent-skills init` later if removed."* If the user replies `keep`, record `keep-installer: true` in `## workspace-summary` and skip Step 10b. Otherwise the default is to remove them.
+
 ### 10. Apply the setup
 
 Apply the changes: create directories, add or update selected artifacts, and remove deselected ones — **bound by the removal-scope rule from Step 6**. Before deleting any target, verify both conditions: (a) the name is in the agent-skills inventory and (b) the item is either listed in `## install-status` or is a symlink resolving into the source repo. If either check fails, skip the deletion silently and log the path under a "Skipped — not owned by agent-skills" line in the final report.
@@ -217,10 +219,36 @@ For settings files (`.claude/settings.json` and equivalents), edit only the agen
 
 Then write both `.ai/` files: the agreed override sections from Step 7 into `.ai/agent-skills-overrides.md`, and the install record — artifacts, target paths, method, **package version**, date — into `.ai/agent-skills-setup.md`. The `version:` line in `## workspace-summary` is set to the package version from Step 2; this is what the next re-run will compare against to compute the version delta.
 
+### 10b. Remove the installer artifacts (unless the user said `keep`)
+
+After Step 10 has written the catalogue + the `.ai/` files, the installer files dropped by `npx @chankov/agent-skills init` — the `setup-agent-skills` / `doctor-agent-skills` slash commands and the `guided-workspace-setup` skill body itself — are no longer needed in the workspace. They were bootstrap plumbing, not part of the user's permanent install. Leaving them in place pollutes the agent's slash-command list and confuses re-runs (which should always go through `init`, not a stale local copy).
+
+Default behaviour:
+
+- **`keep-installer: true` in `## workspace-summary`** → skip this step. The files stay.
+- **Otherwise** → run the cleanup. Delete every file the bootstrap wrote for the chosen agent:
+
+| Agent | Files removed |
+|---|---|
+| `claude-code` | `.claude/commands/setup-agent-skills.md`, `.claude/commands/doctor-agent-skills.md`, `.claude/skills/guided-workspace-setup/SKILL.md` |
+| `pi` | `.pi/prompts/setup-agent-skills.md`, `.pi/prompts/doctor-agent-skills.md`, `.pi/skills/guided-workspace-setup/SKILL.md` |
+| `opencode` | `.opencode/commands/as-setup-agent-skills.md`, `.opencode/commands/as-doctor-agent-skills.md`, `.opencode/skills/guided-workspace-setup/SKILL.md` |
+
+After deleting, prune any directories that were created solely for these files (e.g. `.claude/skills/guided-workspace-setup/`) — never prune a directory that contains other files.
+
+Note: the skill body file you are removing here is the same file the agent is *currently executing*. Filesystem removal does not interrupt the in-memory copy — finish this step, then Step 11, then return as normal.
+
+If `cleanupInstaller` is available via the CLI (`npx @chankov/agent-skills cleanup-installer --agent <agent> --workspace <path>`), invoking it is equivalent to the manual deletions above; either path is acceptable. Failures (permission denied, file already gone) are logged but do not abort the apply.
+
 ### 11. Verify and report
 
 Re-scan the install-target directories one more time and confirm: every selected artifact exists at its target path, every deselected one is gone, and zero broken symlinks remain. Also re-read `.ai/agent-skills-setup.md` and verify the `version:` line matches the package version from Step 2 — a mismatch here means the apply pass did not stamp the new version, and must be corrected before the next re-run computes the wrong delta. If the post-apply scan surfaces any new breakage, treat it as a doctor finding and offer the same repair options as Step 5, then append a second `## doctor-runs` line with `phase: postflight`. List what changed, point the user at `.ai/agent-skills-overrides.md` and `.ai/agent-skills-setup.md`, and suggest loading `using-agent-skills` first in their next session.
 
+Close the report with one line explaining the installer-cleanup outcome:
+
+- If Step 10b ran: *"Installer slash commands removed from your workspace. Re-run `npx @chankov/agent-skills init` if you need `/setup-agent-skills` back."*
+- If Step 10b was skipped (`keep-installer: true`): *"Installer slash commands kept in place per your choice. `/setup-agent-skills` and `/doctor-agent-skills` remain available."*
+
 ## Common Rationalizations
 
 | Rationalization | Reality |
@@ -237,10 +265,13 @@ Re-scan the install-target directories one more time and confirm: every selected
 | "I'll record the full install detail in the overrides file too — one place is simpler." | Other skills load the overrides file on every run. Install detail belongs only in `agent-skills-setup.md`; padding the overrides file taxes every later session. |
 | "There's an unfamiliar skill in `.claude/skills/` — the user must have forgotten to uncheck it, I'll remove it." | The removal scope rule exists exactly to prevent this. If the name is not in the agent-skills inventory or not in `## install-status`, it is user-owned; leave it alone and log it as skipped. |
 | "The user wants a clean workspace — I'll prune custom hooks and unrelated MCP entries from `settings.json` too." | Setting-file edits are limited to agent-skills' own hook registrations. Touching anything else silently deletes work that does not belong to this skill. |
-| "`/setup` and `/doctor` are useful — I'll install them into the workspace so the user can re-run them locally." | They are installer commands; they ship with the source agent-skills repo and act on workspaces from there. Installing them into a target duplicates the install surface and gives the target a path to manipulate itself. |
+| "`/setup-agent-skills` and `/doctor-agent-skills` are useful — I'll re-install them at the end of apply so the user can re-run them locally." | They are installer commands that the CLI bootstraps and the skill itself cleans up in Step 10b by default. Keeping them is opt-in via `keep` in Step 9. Re-installing them silently undoes the cleanup the user implicitly chose. |
 | "The recorded version differs from the current — I'll just refresh everything to the new source without showing the diff." | Conflicting upgrades (user-modified copy + source changed upstream) require the three-way diff to be shown in Step 6, with the row pre-unchecked. Refreshing silently overwrites work the user did between versions. |
 | "The `.versions/<recorded>/` snapshot is missing — I'll pretend the installed copy matches the recorded source and refresh anyway." | A missing snapshot means we cannot compute the three-way diff. The skill must fall back to "treat installed copy as canonical" and surface the missing snapshot in the row's status so the user can decide — never pretend a diff exists. |
 | "The workspace has no `version:` line — I'll silently stamp the current version and move on." | A pre-versioning workspace must be flagged in Step 4 and the user prompted: stamp the current version (assume copies match) or wipe and reinstall. Silent stamping hides a real decision. |
+| "The user didn't say anything about the installer cleanup line — I'll leave the installer files in place to be safe." | The default is to remove. Step 9's confirmation line explicitly states the cleanup will happen unless the user replies `keep`. Silence is consent for the default, not opt-out from it. |
+| "I'll add `setup-agent-skills` and `doctor-agent-skills` to the install menu so the user can pick whether to keep them." | They are still installer-only and excluded from the menu. The keep-vs-remove choice is the single Step 9 line, not a menu group — adding them to the menu re-opens the pollution we just fixed. |
+| "The skill is currently executing; deleting its own file in Step 10b will crash mid-run." | The agent loads the skill into memory at the start of execution. Removing the file on disk does not unload the in-memory copy — Steps 10b and 11 complete normally before control returns. |
 
 ## Red Flags
 
@@ -265,6 +296,10 @@ Re-scan the install-target directories one more time and confirm: every selected
 - A `conflicting upgrade` row pre-checked, or the three-way diff omitted for it.
 - A pre-versioning workspace stamped with the current version without prompting the user first.
 - The post-apply `version:` line not matching the package version from Step 2.
+- Step 9 summary missing the installer-cleanup line, or the line stated `keep` as the default.
+- Installer files (`setup-agent-skills`, `doctor-agent-skills`, the `guided-workspace-setup` skill body) left in place without a recorded `keep-installer: true`.
+- `setup-agent-skills` or `doctor-agent-skills` shown as install-menu rows.
+- Step 11 report omitting the one-line installer-cleanup outcome.
 
 ## Verification
 
@@ -287,6 +322,9 @@ After completing the workflow, confirm:
 - [ ] When the version delta was non-empty, Step 9's summary led with the "Changes since v<recorded> → v<current>" block sourced from `CHANGELOG.md`.
 - [ ] Every `conflicting upgrade` row was rendered with its three-way diff in Step 6 and was not pre-checked.
 - [ ] A pre-versioning workspace was flagged in Step 4 and the user was prompted to stamp or wipe — not silently stamped.
+- [ ] Step 9 summary ended with the installer-cleanup line: states remove-by-default and offers `keep` as the opt-out.
+- [ ] Step 10b ran (or was explicitly skipped because `keep-installer: true`); the installer files are absent from the workspace unless the user opted to keep them.
+- [ ] Step 11 report includes the one-line installer-cleanup outcome.
 - [ ] No broken symlinks remain in any of the scanned install-target directories.
 - [ ] No YAML config references a removed persona name.
 - [ ] No secrets were written to either `.ai/` file.

package/.versions/0.3.0/.claude/commands/build.md

@@ -0,0 +1,18 @@
+---
+description: Implement the next task incrementally — build, test, verify, commit
+---
+
+Invoke the agent-skills:incremental-implementation skill alongside agent-skills:test-driven-development.
+
+Pick the next pending task from the plan. For each task:
+
+1. Read the task's acceptance criteria
+2. Load relevant context (existing code, patterns, types)
+3. Write a failing test for the expected behavior (RED)
+4. Implement the minimum code to pass the test (GREEN)
+5. Run the full test suite to check for regressions
+6. Run the build to verify compilation
+7. Commit with a descriptive message
+8. Mark the task complete and move to the next one
+
+If any step fails, follow the agent-skills:debugging-and-error-recovery skill.

package/.versions/0.3.0/.claude/commands/code-simplify.md

@@ -0,0 +1,22 @@
+---
+description: Simplify code for clarity and maintainability — reduce complexity without changing behavior
+---
+
+Invoke the agent-skills:code-simplification skill.
+
+Simplify recently changed code (or the specified scope) while preserving exact behavior:
+
+1. Read CLAUDE.md and study project conventions
+2. Identify the target code — recent changes unless a broader scope is specified
+3. Understand the code's purpose, callers, edge cases, and test coverage before touching it
+4. Scan for simplification opportunities:
+   - Deep nesting → guard clauses or extracted helpers
+   - Long functions → split by responsibility
+   - Nested ternaries → if/else or switch
+   - Generic names → descriptive names
+   - Duplicated logic → shared functions
+   - Dead code → remove after confirming
+5. Apply each simplification incrementally — run tests after each change
+6. Verify all tests pass, the build succeeds, and the diff is clean
+
+If tests fail after a simplification, revert that change and reconsider. Use `code-review-and-quality` to review the result.

package/.versions/0.3.0/.claude/commands/design-agent.md

@@ -0,0 +1,14 @@
+---
+description: Design and write a new agent persona (agents/), workflow skill (skills/), or pi harness (.pi/harnesses/)
+---
+
+Invoke the agent-skills:designing-agents skill.
+
+Begin by understanding what the user wants to author:
+1. Is this a **persona** (a role/lens the agent adopts, e.g. a reviewer or auditor), a **skill** (a repeatable workflow with gated steps and verification), or a **pi harness** (a TypeScript pi extension that reshapes the session — footer, tool-call gate, new command, or orchestrator)?
+2. The one-sentence purpose and when it should be invoked
+3. The framework or steps — dimensions evaluated (persona), ordered workflow (skill), or session surface and events hooked (harness)
+4. Explicit non-goals and scope limits
+5. Output shape — what a typical invocation should produce
+
+Then scan the target location (`agents/`, `skills/`, or `.pi/harnesses/`) for overlap, draft the artifact using the matching template — four-block persona structure, the section order from `docs/skill-anatomy.md`, or the harness pattern in `skills/designing-agents/pi-harness-authoring.md` — verify the draft against `references/prompting-patterns.md`, and confirm with the user before writing the file(s).

package/.versions/0.3.0/.claude/commands/doctor-agent-skills.md

@@ -0,0 +1,13 @@
+---
+description: Scan agent-skills install targets for broken symlinks and stale persona references, then offer repairs
+---
+
+Invoke the Doctor scan from the `agent-skills:guided-workspace-setup` skill — Step 5 (the preflight scan) — without running the rest of the install flow. Use this when the user wants the repair pass on its own; the full `/setup-agent-skills` flow runs the same scan automatically as soon as it detects prior install state.
+
+Walk every install-target directory the chosen coding agent uses (`agents/`, `.claude/agents/`, `.opencode/agents/`, `.codex/agents/`, `.gemini/agents/`, `.github/agents/`, `.pi/agents/` and `pi-pi/`, `.claude/skills/`, `.opencode/skills/`, `.pi/skills/`, `.agents/skills`, `.claude/commands/`, `.opencode/commands/`, `.pi/prompts/`, `.claude/references/`, `.claude/hooks/`). For each broken symlink, resolve where it pointed, look for a canonical replacement in the source `agents/` and `skills/` trees, and offer to repoint or delete. Common stale names from the pre-merge persona layout: `reviewer` → `code-reviewer`, `red-team` → `security-auditor`.
+
+Also flag and offer to rewrite any YAML configs (`teams.yaml`, `agent-chain.yaml`, etc.) that still reference removed persona names.
+
+Present findings as a `# | Path | Issue | Suggested fix` table and ask the user to pick which fixes to apply.
+
+Never overwrite a regular file — only act on symlinks whose target is missing. Report `repaired`, `deleted`, and `skipped` counts, and append a `## doctor-runs` line to `.ai/agent-skills-setup.md` with the date, agent, phase (`standalone`), and counts.

package/.versions/0.3.0/.claude/commands/plan.md

@@ -0,0 +1,16 @@
+---
+description: Break work into small verifiable tasks with acceptance criteria and dependency ordering
+---
+
+Invoke the agent-skills:planning-and-task-breakdown skill.
+
+Read the existing spec (SPEC.md or equivalent) and the relevant codebase sections. Then:
+
+1. Enter plan mode — read only, no code changes
+2. Identify the dependency graph between components
+3. Slice work vertically (one complete path per task, not horizontal layers)
+4. Write tasks with acceptance criteria and verification steps
+5. Add checkpoints between phases
+6. Present the plan for human review
+
+Save the plan to the location the `planning-and-task-breakdown` skill defines (default `docs/plans/{area}/PLAN-{prd-name}-{phase}.md`, with the task list embedded — no separate todo file; overridable per project via `.ai/agent-skills-overrides.md`). Match the project's existing `docs`/`Docs` capitalization.

package/.versions/0.3.0/.claude/commands/prime.md

@@ -0,0 +1,22 @@
+---
+description: Load foundational context for the agent-skills repository
+---
+
+# Purpose
+
+Orient yourself in **agent-skills** — a collection of production-grade engineering skills
+for AI coding agents, plus pi extensions, specialist agent personas, and lifecycle
+commands that map to the software development lifecycle.
+
+## Workflow
+
+1. Run `git ls-files` to see the full project file tree
+2. Read `README.md` and `CLAUDE.md` for the project overview and conventions
+3. Read `docs/skill-anatomy.md` to learn the required skill format
+4. Skim `skills/*/SKILL.md` — the core skills, grouped by lifecycle phase
+   (Define → Plan → Build → Verify → Review → Ship)
+5. Read `agents/*.md` — the specialist review personas
+6. Read `docs/pi-extensions.md`, `.pi/extensions/*/README.md` (always-on utilities), and `.pi/harnesses/*/README.md` (selectable session harnesses)
+7. Summarize your understanding: purpose, structure, key files, and entry points
+
+Do this directly — read the files yourself rather than delegating to subagents.

package/.versions/0.3.0/.claude/commands/review.md

@@ -0,0 +1,16 @@
+---
+description: Conduct a five-axis code review — correctness, readability, architecture, security, performance
+---
+
+Invoke the agent-skills:code-review-and-quality skill.
+
+Review the current changes (staged or recent commits) across all five axes:
+
+1. **Correctness** — Does it match the spec? Edge cases handled? Tests adequate?
+2. **Readability** — Clear names? Straightforward logic? Well-organized?
+3. **Architecture** — Follows existing patterns? Clean boundaries? Right abstraction level?
+4. **Security** — Input validated? Secrets safe? Auth checked? (Use security-and-hardening skill)
+5. **Performance** — No N+1 queries? No unbounded ops? (Use performance-optimization skill)
+
+Categorize findings as Critical, Important, or Suggestion.
+Output a structured review with specific file:line references and fix recommendations.

package/.versions/0.3.0/.claude/commands/setup-agent-skills.md

@@ -0,0 +1,19 @@
+---
+description: Guided setup — install agent-skills artifacts into a workspace for a chosen coding agent
+---
+
+Invoke the agent-skills:guided-workspace-setup skill.
+
+Run the guided install for a target workspace. If the user passed a workspace path, use it; otherwise ask for it. Detect the running coding agent and confirm it with the user.
+
+Analyse the workspace. If prior install state is found (`.ai/agent-skills-setup.md` or a populated agent directory), run the **Doctor preflight** first (Step 5) — scan for broken symlinks and stale persona references, present findings as a table, and apply the fixes the user picks before continuing.
+
+Then present the install menu as **one multi-select per group** (18 groups across skills, personas, commands, pi extensions/harnesses, references, hooks) with `★` marking recommendations. Each group renders as a `Pick | Item | Status | Rec | Purpose` table; every row carries an explicit status text — `installed · up to date`, `installed · outdated`, `installed · modified`, `not installed`, or `broken · skipped in preflight`. Installed items are **pre-checked `[x]`** so unchecking = remove; not-installed items start `[ ]`. Per-group reply shortcuts: `all`, `recommended` (adds `★` items on top of the pre-selection — never unticks installed ones), `none`, `keep` (accept the pre-selection unchanged), or a list of picks. Never offer `setup`, `doctor`, or `guided-workspace-setup` — those are installer-only and live in the source agent-skills repo.
+
+Unchecking an installed item means *remove it*, but **removal is scoped**: only act on items whose name is in the agent-skills inventory **and** that are recorded in `## install-status` (or are symlinks resolving into the source repo). User-authored skills, custom commands, third-party plugins, and unrelated settings/env keys are left untouched and logged as "Skipped — not owned by agent-skills".
+
+**No cross-tool substitution.** Each row is offered only when the source file the chosen agent needs already exists — for `pi`, that means `.pi/prompts/<name>.md`, `.pi/extensions/<name>/`, etc. Never fall back to `.claude/commands/` (or another agent's tree) to satisfy a pi prompt request; items missing their per-agent source are filtered out of the menu entirely.
+
+**No mid-apply overwrite prompts.** The Step 6 status text already warns that `installed · modified` rows will have local edits overwritten if kept ticked. The user's tick is the consent; the Step 9 confirmation is the single gate. During apply, refresh ticked items unconditionally — never pause to ask "should I overwrite this file?". Genuine errors (permission denied, missing source) still stop and report.
+
+Offer override sections for the workspace's `.ai/agent-skills-overrides.md` based on the analysis, and record what was installed in `.ai/agent-skills-setup.md`. Summarise the full plan and wait for explicit confirmation before writing anything, then perform the setup, re-scan for any new breakage, and report what changed.

package/.versions/0.3.0/.claude/commands/ship.md

@@ -0,0 +1,17 @@
+---
+description: Run the pre-launch checklist and prepare for production deployment
+---
+
+Invoke the agent-skills:shipping-and-launch skill.
+
+Run through the complete pre-launch checklist:
+
+1. **Code Quality** — Tests pass, build clean, lint clean, no TODOs, no console.logs
+2. **Security** — npm audit clean, no secrets in code, auth in place, headers configured
+3. **Performance** — Core Web Vitals good, no N+1 queries, images optimized, bundle sized
+4. **Accessibility** — Keyboard nav works, screen reader compatible, contrast adequate
+5. **Infrastructure** — Env vars set, migrations ready, monitoring configured
+6. **Documentation** — README current, ADRs written, changelog updated
+
+Report any failing checks and help resolve them before deployment.
+Define the rollback plan before proceeding.

package/.versions/0.3.0/.claude/commands/spec.md

@@ -0,0 +1,15 @@
+---
+description: Start spec-driven development — write a structured specification before writing code
+---
+
+Invoke the agent-skills:spec-driven-development skill.
+
+Begin by understanding what the user wants to build. Ask clarifying questions about:
+1. The objective and target users
+2. Core features and acceptance criteria
+3. Tech stack preferences and constraints
+4. Known boundaries (what to always do, ask first about, and never do)
+
+Then generate a structured spec covering all six core areas: objective, commands, project structure, code style, testing strategy, and boundaries.
+
+Save the spec to the location the `spec-driven-development` skill defines (default `docs/prds/{area}/PRD{n}-{topic}.md`; overridable per project via `.ai/agent-skills-overrides.md`). Confirm with the user before proceeding.

package/.versions/0.3.0/.claude/commands/test.md

@@ -0,0 +1,19 @@
+---
+description: Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern.
+---
+
+Invoke the agent-skills:test-driven-development skill.
+
+For new features:
+1. Write tests that describe the expected behavior (they should FAIL)
+2. Implement the code to make them pass
+3. Refactor while keeping tests green
+
+For bug fixes (Prove-It pattern):
+1. Write a test that reproduces the bug (must FAIL)
+2. Confirm the test fails
+3. Implement the fix
+4. Confirm the test passes
+5. Run the full test suite for regressions
+
+For browser-related issues, also invoke agent-skills:browser-testing-with-devtools to verify with Chrome DevTools MCP.

package/.versions/0.3.0/.opencode/commands/as-build.md

@@ -0,0 +1,17 @@
+---
+description: Implement the next task incrementally - build, test, verify, commit
+---
+
+Invoke the `incremental-implementation` skill and the `test-driven-development` skill via the `skill` tool.
+
+Pick the next pending task from the plan. For each task:
+
+1. Read the task's acceptance criteria.
+2. Load relevant context: existing code, patterns, and types.
+3. Write a failing test for the expected behavior.
+4. Implement the minimum code to pass the test.
+5. Run the relevant test suite to check for regressions.
+6. Run the build to verify compilation.
+7. Mark the task complete and move to the next one.
+
+If any step fails, invoke the `debugging-and-error-recovery` skill via the `skill` tool.

package/.versions/0.3.0/.opencode/commands/as-code-simplify.md

@@ -0,0 +1,16 @@
+---
+description: Simplify code for clarity and maintainability without changing behavior
+---
+
+Invoke the `code-simplification` skill via the `skill` tool.
+
+Simplify recently changed code, or the scope specified in `$ARGUMENTS`, while preserving exact behavior:
+
+1. Read the project's agent instructions and study project conventions.
+2. Identify the target code: recent changes unless a broader scope is specified.
+3. Understand the code's purpose, callers, edge cases, and test coverage before touching it.
+4. Scan for simplification opportunities: deep nesting, long functions, nested ternaries, generic names, duplicated logic, or dead code.
+5. Apply each simplification incrementally and run relevant tests after each change.
+6. Verify tests pass, the build succeeds, and the diff is clean.
+
+If tests fail after a simplification, revert only that simplification and reconsider. Invoke `code-review-and-quality` via the `skill` tool to review the result.

package/.versions/0.3.0/.opencode/commands/as-design-agent.md

@@ -0,0 +1,15 @@
+---
+description: Design and write a new agent persona, workflow skill, or pi harness
+---
+
+Invoke the `designing-agents` skill via the `skill` tool.
+
+Begin by understanding what the user wants to author:
+
+1. Is this a persona (a role or lens the agent adopts), a skill (a repeatable workflow with gated steps and verification), or a pi harness (a TypeScript pi extension that reshapes the session)?
+2. What is the one-sentence purpose and when should it be invoked?
+3. What framework or steps should it follow?
+4. What are the explicit non-goals and scope limits?
+5. What output shape should a typical invocation produce?
+
+Then scan the target location — `agents/`, `skills/`, or `.pi/harnesses/` — for overlap. Draft the artifact using the matching template, verify the draft against prompting guidance when available, and confirm with the user before writing the file(s).

package/.versions/0.3.0/.opencode/commands/as-doctor-agent-skills.md

@@ -0,0 +1,11 @@
+---
+description: Scan agent-skills install targets for broken symlinks and stale persona references, then offer repairs
+---
+
+Invoke the Doctor step from the `guided-workspace-setup` skill (Step 10) via the `skill` tool — without running the rest of the install flow.
+
+Walk every install-target directory the chosen coding agent uses (`agents/`, `.claude/agents/`, `.opencode/agents/`, `.codex/agents/`, `.gemini/agents/`, `.github/agents/`, `.pi/agents/` and `pi-pi/`, `.claude/skills/`, `.opencode/skills/`, `.pi/skills/`, `.agents/skills`, `.claude/commands/`, `.opencode/commands/`, `.pi/prompts/`, `.claude/references/`, `.claude/hooks/`). For each broken symlink, resolve where it pointed, look for a canonical replacement in the source `agents/` and `skills/` trees, and offer to repoint or delete. Common stale names from the pre-merge persona layout: `reviewer` → `code-reviewer`, `red-team` → `security-auditor`.
+
+Also flag and offer to rewrite any YAML configs (`teams.yaml`, `agent-chain.yaml`, etc.) that still reference removed persona names.
+
+Never overwrite a regular file — only act on symlinks whose target is missing. Report `repaired`, `deleted`, and `skipped` counts, and append a `## doctor-runs` line to `.ai/agent-skills-setup.md` with the date and counts.

package/.versions/0.3.0/.opencode/commands/as-plan.md

@@ -0,0 +1,16 @@
+---
+description: Break work into small verifiable tasks with acceptance criteria and dependency ordering
+---
+
+Invoke the `planning-and-task-breakdown` skill via the `skill` tool.
+
+Read the existing spec, such as `SPEC.md`, and relevant codebase sections. Then:
+
+1. Enter planning mode: read only, no code changes.
+2. Identify the dependency graph between components.
+3. Slice work vertically, with one complete path per task rather than horizontal layers.
+4. Write tasks with acceptance criteria and verification steps.
+5. Add checkpoints between phases.
+6. Present the plan for human review.
+
+Save the plan to the location the `planning-and-task-breakdown` skill defines (default `docs/plans/{area}/PLAN-{prd-name}-{phase}.md`, with the task list embedded — no separate todo file; overridable per project via `.ai/agent-skills-overrides.md`), only after the user confirms the plan should be written.

package/.versions/0.3.0/.opencode/commands/as-prime.md

@@ -0,0 +1,22 @@
+---
+description: Load foundational context for the agent-skills repository
+---
+
+# Purpose
+
+Orient yourself in **agent-skills** — a collection of production-grade engineering skills
+for AI coding agents, plus pi extensions, specialist agent personas, and lifecycle
+commands that map to the software development lifecycle.
+
+## Workflow
+
+1. Run `git ls-files` to see the full project file tree
+2. Read `README.md` and `CLAUDE.md` for the project overview and conventions
+3. Read `docs/skill-anatomy.md` to learn the required skill format
+4. Skim `skills/*/SKILL.md` — the core skills, grouped by lifecycle phase
+   (Define → Plan → Build → Verify → Review → Ship)
+5. Read `agents/*.md` — the specialist review personas
+6. Read `docs/pi-extensions.md`, `.pi/extensions/*/README.md` (always-on utilities), and `.pi/harnesses/*/README.md` (selectable session harnesses)
+7. Summarize your understanding: purpose, structure, key files, and entry points
+
+Do this directly — read the files yourself rather than delegating to subagents.

package/.versions/0.3.0/.opencode/commands/as-review.md

@@ -0,0 +1,15 @@
+---
+description: Conduct a five-axis code review - correctness, readability, architecture, security, performance
+---
+
+Invoke the `code-review-and-quality` skill via the `skill` tool.
+
+Review the current changes, staged changes, or scope specified in `$ARGUMENTS` across these axes:
+
+1. Correctness: Does it match the spec? Are edge cases handled? Are tests adequate?
+2. Readability: Are names clear? Is the logic straightforward and well organized?
+3. Architecture: Does it follow existing patterns? Are boundaries clean? Is the abstraction level right?
+4. Security: Is input validated? Are secrets safe? Is authorization checked? Invoke `security-and-hardening` via the `skill` tool when relevant.
+5. Performance: Are there N+1 queries, unbounded operations, or avoidable frontend regressions? Invoke `performance-optimization` via the `skill` tool when relevant.
+
+Categorize findings as Critical, Important, or Suggestion. Output a structured review with specific file and line references plus fix recommendations.

package/.versions/0.3.0/.opencode/commands/as-setup-agent-skills.md

@@ -0,0 +1,11 @@
+---
+description: Guided setup — install agent-skills artifacts into a workspace for a chosen coding agent
+---
+
+Invoke the `guided-workspace-setup` skill via the `skill` tool.
+
+Run the guided install for a target workspace. If the user passed a workspace path, use it; otherwise ask for it. Detect the running coding agent and confirm it with the user.
+
+Analyse the workspace, then present a checklist of installable artifacts — skills, agent personas, commands/prompts, pi extensions and harnesses, references, and hooks — marking what is already installed.
+
+Offer override sections for the workspace's `.ai/agent-skills-overrides.md` based on a brief analysis of the project, and record what was installed in `.ai/agent-skills-setup.md`. Summarise the full plan and wait for explicit confirmation before writing anything, then perform the setup and report what changed.

package/.versions/0.3.0/.opencode/commands/as-ship.md

@@ -0,0 +1,16 @@
+---
+description: Run the pre-launch checklist and prepare for production deployment
+---
+
+Invoke the `shipping-and-launch` skill via the `skill` tool.
+
+Run through the complete pre-launch checklist:
+
+1. Code quality: tests pass, build clean, lint clean, no stray TODOs or console logs.
+2. Security: dependency audit checked, no secrets in code, auth in place, headers configured where applicable.
+3. Performance: Core Web Vitals or relevant performance checks are acceptable, no N+1 queries, images and bundles are reasonable.
+4. Accessibility: keyboard navigation works, screen reader semantics are acceptable, contrast is adequate.
+5. Infrastructure: environment variables are set, migrations are ready, monitoring is configured.
+6. Documentation: README is current, ADRs are written when needed, changelog is updated when relevant.
+
+Report any failing checks and help resolve them before deployment. Define the rollback plan before proceeding.

package/.versions/0.3.0/.opencode/commands/as-spec.md

@@ -0,0 +1,16 @@
+---
+description: Start spec-driven development by writing a structured specification before code
+---
+
+Invoke the `spec-driven-development` skill via the `skill` tool.
+
+Begin by understanding what the user wants to build. Ask clarifying questions about:
+
+1. The objective and target users.
+2. Core features and acceptance criteria.
+3. Tech stack preferences and constraints.
+4. Known boundaries: what to always do, ask first about, and never do.
+
+Then generate a structured spec covering objective, commands, project structure, code style, testing strategy, and boundaries.
+
+Confirm with the user before saving, then save the spec to the location the `spec-driven-development` skill defines (default `docs/prds/{area}/PRD{n}-{topic}.md`; overridable per project via `.ai/agent-skills-overrides.md`).