@chankov/agent-skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,58 @@
+# agent-skills-update-check
+
+A pi extension that surfaces an "update available" banner once per session when `@chankov/agent-skills` has a newer published version than the one recorded in `.ai/agent-skills-setup.md`.
+
+## What it does
+
+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-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`.
+
+The check runs **once per session** and is bounded to a single network call. It shares its cache file with the CLI update-notifier so the two never double-fetch.
+
+## When the banner fires
+
+```
+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.
+
+## When the banner does NOT fire
+
+- The workspace has no `.ai/agent-skills-setup.md` install record.
+- The published version equals or is older than the recorded version.
+- The cache shows the published version is current (≤24h since last fetch).
+- The registry is unreachable, returns non-200, or times out.
+- `AGENT_SKILLS_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1`, or `CI=true` is set in the environment.
+
+Every error path silently aborts. Update checks must never disrupt a session.
+
+## Install
+
+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 \
+      .pi/extensions/agent-skills-update-check
+```
+
+No runtime deps beyond pi's own `@mariozechner/pi-coding-agent` types and Node built-ins (`fs`, `os`, `path`, `https`).
+
+## Opt-out
+
+The check honours three environment variables (any of them disables it):
+
+- `AGENT_SKILLS_NO_UPDATE_CHECK=1` — agent-skills-specific opt-out
+- `NO_UPDATE_NOTIFIER=1` — the conventional opt-out used by many CLI tools
+- `CI=true` — auto-disabled in CI so the banner never spams build logs
+
+## Behavior notes
+
+- 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-agent-skills` once to stamp the current version.
+- The extension only reads; it never writes the install record itself.

package/.pi/extensions/agent-skills-update-check/index.ts

@@ -0,0 +1,161 @@
+// agent-skills-update-check — pi extension that surfaces an "update available"
+// banner once per session when @chankov/agent-skills has a newer published
+// version than the one recorded in .ai/agent-skills-setup.md.
+//
+// Design constraints:
+//   - Never blocks pi startup. The check runs once on the first agent_start
+//     event with a soft 3s timeout.
+//   - Shares the same XDG cache file as the CLI (~/.cache/agent-skills/
+//     latest-version.json) so the CLI and pi don't double-fetch.
+//   - Honors AGENT_SKILLS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER / CI opt-outs.
+//   - Network errors, missing record files, and missing node-fetch all fall
+//     through to "do nothing" — never an error notification.
+
+import type { ExtensionAPI, ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { request } from 'node:https';
+
+const PACKAGE_NAME = '@chankov/agent-skills';
+const REGISTRY = 'https://registry.npmjs.org';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+
+const CACHE_DIR = join(
+	process.env.XDG_CACHE_HOME || join(homedir(), '.cache'),
+	'agent-skills',
+);
+const CACHE_FILE = join(CACHE_DIR, 'latest-version.json');
+
+interface CachePayload {
+	latest: string;
+	checkedAt: number;
+}
+
+export default function updateCheckExtension(pi: ExtensionAPI) {
+	let checked = false;
+
+	pi.on('agent_start', async (_event, ctx) => {
+		if (checked) return;
+		checked = true;
+
+		try {
+			await runCheck(ctx);
+		} catch {
+			// Update checks must never disrupt a session — swallow everything.
+		}
+	});
+}
+
+async function runCheck(ctx: ExtensionContext): Promise<void> {
+	if (isDisabled()) return;
+
+	const recorded = readRecordedVersion();
+	if (!recorded) return; // workspace was never set up via /setup — nothing to compare
+
+	let latest = readCacheFresh();
+	if (!latest) {
+		latest = await fetchLatest(FETCH_TIMEOUT_MS);
+		if (latest) writeCache({ latest, checkedAt: Date.now() });
+	}
+	if (!latest) return;
+
+	if (!isGreater(latest, recorded)) return;
+
+	ctx.ui.notify(
+		`agent-skills update available: ${recorded} → ${latest}. ` +
+		`Run "npx ${PACKAGE_NAME}@latest update" then /setup to apply.`,
+		'info',
+	);
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function isDisabled(): boolean {
+	return process.env.AGENT_SKILLS_NO_UPDATE_CHECK === '1'
+		|| process.env.NO_UPDATE_NOTIFIER === '1'
+		|| process.env.CI === 'true';
+}
+
+function readRecordedVersion(): string | null {
+	// pi runs from the workspace root; the install record lives at .ai/...
+	const recordPath = join(process.cwd(), '.ai', 'agent-skills-setup.md');
+	if (!existsSync(recordPath)) return null;
+	try {
+		const text = readFileSync(recordPath, 'utf8');
+		const m = text.match(/^version:\s*([^\s#]+)/m);
+		return m ? m[1].trim() : null;
+	} catch {
+		return null;
+	}
+}
+
+function readCacheFresh(): string | null {
+	try {
+		if (!existsSync(CACHE_FILE)) return null;
+		const payload = JSON.parse(readFileSync(CACHE_FILE, 'utf8')) as CachePayload;
+		if (Date.now() - payload.checkedAt >= CACHE_TTL_MS) return null;
+		return payload.latest;
+	} catch {
+		return null;
+	}
+}
+
+function writeCache(payload: CachePayload): void {
+	try {
+		mkdirSync(CACHE_DIR, { recursive: true });
+		writeFileSync(CACHE_FILE, JSON.stringify(payload, null, 2), 'utf8');
+	} catch {
+		// Cache write failed — fine, we'll re-fetch next session.
+	}
+}
+
+function fetchLatest(timeoutMs: number): Promise<string | null> {
+	return new Promise((resolve) => {
+		const url = `${REGISTRY}/${encodeURIComponent(PACKAGE_NAME).replace('%40', '@')}/latest`;
+		const req = request(
+			url,
+			{ method: 'GET', headers: { accept: 'application/json' } },
+			(res) => {
+				if (res.statusCode !== 200) {
+					res.resume();
+					resolve(null);
+					return;
+				}
+				let body = '';
+				res.setEncoding('utf8');
+				res.on('data', (chunk) => { body += chunk; });
+				res.on('end', () => {
+					try {
+						const parsed = JSON.parse(body);
+						resolve(typeof parsed.version === 'string' ? parsed.version : null);
+					} catch {
+						resolve(null);
+					}
+				});
+			},
+		);
+		req.on('error', () => resolve(null));
+		req.setTimeout(timeoutMs, () => {
+			req.destroy();
+			resolve(null);
+		});
+		req.end();
+	});
+}
+
+function isGreater(a: string, b: string): boolean {
+	const [aMain, aPre = ''] = a.split('-', 2);
+	const [bMain, bPre = ''] = b.split('-', 2);
+	const aParts = aMain.split('.').map(Number);
+	const bParts = bMain.split('.').map(Number);
+	for (let i = 0; i < 3; i++) {
+		const ai = aParts[i] ?? 0;
+		const bi = bParts[i] ?? 0;
+		if (ai !== bi) return ai > bi;
+	}
+	if (!aPre && bPre) return true;
+	if (aPre && !bPre) return false;
+	return aPre > bPre;
+}

package/.pi/extensions/agent-skills-update-check/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-skills-pi-update-check",
+  "private": true,
+  "type": "module",
+  "main": "index.ts"
+}

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/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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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`).