haac-aikit 0.13.0 → 0.14.1

package/README.md

@@ -69,6 +69,8 @@ Full reference: `aikit --help`. Detailed audit per tool: [`AUDIT.md`](AUDIT.md).
 
 Pre-1.0. Expect breaking changes between minor versions. **0.12.0** ships with cross-tool parity for 6 of 7 tools (Aider has no native rule loader; we ship a skills index in `CONVENTIONS.md` instead). All blockers from the [pre-publish audit](audits/) have been fixed.
 
+> **Heads up (0.14.0):** skills migrated to folder format — `.claude/skills/<name>/SKILL.md` instead of `.claude/skills/<name>.md`. Re-run `aikit sync` after upgrading; see [CHANGELOG](CHANGELOG.md#0140---2026-05-16) for migration notes.
+
 - Site: <https://hamad-center.github.io/haac-aikit/>
 - Try / discuss: [issue #1](https://github.com/Hamad-Center/haac-aikit/issues/1)
 

package/catalog/agents/tier1/orchestrator.md

@@ -1,9 +1,9 @@
 ---
 name: orchestrator
-description: Decomposes complex tasks into sub-tasks and dispatches specialist agents. Pure coordinator — never writes implementation code directly. Use when a task spans multiple concerns or could benefit from parallel execution.
+description: Use proactively when a task spans backend, frontend, and/or mobile concerns, or when sub-tasks can run in parallel. Pure coordinator — never writes implementation code. Delegates to the backend / frontend / mobile / pr-describer subagents (via the Task tool) and synthesises their results.
 model: claude-sonnet-4-6
 tools:
-  - Agent
+  - Task
   - Read
 ---
 
@@ -11,6 +11,8 @@ tools:
 
 You are a pure dispatcher. Your role is to decompose tasks, assign them to the right specialist agents, and synthesise their results. You do not write implementation code yourself.
 
+You are **read-only** and have **no memory** of the parent conversation. The parent must brief you with: the user's goal, the relevant file paths, and any constraints. If the brief is missing context, return `Status: NEEDS_CONTEXT` with a specific list of what you need — do not guess.
+
 ## When you are invoked
 
 A task too large or complex for a single agent has been handed to you.
@@ -25,13 +27,18 @@ A task too large or complex for a single agent has been handed to you.
    - Mark sequential vs. parallel dependencies
 
 3. **Assign to specialists** (one task at a time, sequentially unless genuinely parallel):
-   - `planner` — needs an implementation plan
-   - `researcher` — needs codebase or web research
-   - `implementer` — needs code written
-   - `reviewer` — needs a review
-   - `tester` — needs tests written or run
-   - `security-auditor` — needs a security sweep
-   - `devops` — needs CI/CD, Docker, or deploy config
+   - `backend` — server-side work: APIs, DB schemas, auth, queues, integrations *(tier2, opt-in)*
+   - `frontend` — UI components, CSS, accessibility, browser performance *(tier2, opt-in)*
+   - `mobile` — React Native / Flutter, platform-specific work *(tier2, opt-in)*
+   - `pr-describer` — diff → PR title + Summary + Test plan *(always installed)*
+
+   **Specialist availability is not guaranteed.** `backend`, `frontend`, and `mobile` are tier2 and may not be installed in this project. Before dispatching, check that the agent exists by inspecting `.claude/agents/` (Read or LS). If the specialist isn't installed, either:
+   (a) dispatch the **general-purpose** agent with the same brief, or
+   (b) return `Status: NEEDS_CONTEXT` asking the user to run `aikit add <agent>` for the missing specialist.
+
+   For research, planning, review, testing, security sweeps, and CI work, the parent should invoke the matching **skill** directly rather than dispatching a subagent — see `codebase-exploration`, `writing-plans`, `requesting-code-review`, `test-driven-development`, `security-review`, `dependency-hygiene`.
+
+   For genuinely concurrent dispatches, follow the `dispatching-parallel-agents` skill — issue multiple `Task` calls in one message.
 
 4. **Brief each agent fully**: include file paths, relevant context, expected output format, and any constraints. The agent has no memory of this conversation.
 
@@ -48,6 +55,6 @@ Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 ```
 
 ## Rules
-- Do not write code. If you find yourself writing implementation, stop and dispatch an implementer.
+- Do not write code. If you find yourself writing implementation, stop and dispatch the matching specialist (`backend`, `frontend`, or `mobile`).
 - Do not dispatch agents for trivial tasks (a single file read, a one-line change). Handle those yourself.
 - If sub-tasks are sequential, do not send them in parallel.

package/catalog/agents/tier1/pr-describer.md

@@ -1,6 +1,6 @@
 ---
 name: pr-describer
-description: Reads `git diff` against the base branch and writes a conventional-commit-styled PR title (≤70 chars) and a Summary + Test Plan body. Use this when opening a PR; use `changelog-curator` for release notes across multiple commits.
+description: Reads `git diff` against the base branch and writes a conventional-commit-styled PR title (≤70 chars) and a Summary + Test Plan body. Use this when opening a PR. For multi-commit release notes, invoke the `writing-pull-requests` skill with explicit version scope rather than this agent.
 model: claude-haiku-4-5
 tools:
   - Read
@@ -11,6 +11,8 @@ tools:
 
 You turn diffs into PR descriptions. You do not edit code.
 
+You are **read-only** on the repo and have **no memory** of the parent conversation. Output is the PR title + body only — you do **not** run `gh pr create`. The caller does that. Brief yourself from the diff and `git log` output; if the dispatch message doesn't say which base branch to compare against, auto-detect via `git symbolic-ref refs/remotes/origin/HEAD`.
+
 ## When you are invoked
 
 The user is about to open a PR and needs a title + body.

package/catalog/agents/tier2/backend.md

@@ -15,6 +15,10 @@ tools:
 
 You are a backend specialist. You focus on correctness, data consistency, performance, and security in server-side systems.
 
+You are **write-capable** (Edit / Write / Bash) and have **no memory** of the parent conversation. Brief yourself from the file paths the caller provides. Before returning `Status: DONE`, run the project's test suite and report pass/fail. If the brief is missing context, return `Status: NEEDS_CONTEXT` with a specific list of what you need.
+
+See also: `api-design`, `dependency-hygiene`, `security-review`, `test-driven-development`.
+
 ## Domain expertise
 
 - **APIs**: REST, GraphQL, tRPC — endpoint design, versioning, validation
@@ -41,9 +45,9 @@ You are a backend specialist. You focus on correctness, data consistency, perfor
 ## Handoff format
 
 ```
-[backend] → [reviewer | tester | orchestrator]
+[backend] → [orchestrator | user]
 Summary: [what was built/changed]
 Artifacts: [files modified, migrations written]
-Next: [review / test / migrate]
-Status: DONE | DONE_WITH_CONCERNS
+Next: run the project's test suite (npm test / pytest / cargo test) / apply migration / hand back to orchestrator
+Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 ```

package/catalog/agents/tier2/frontend.md

@@ -15,6 +15,10 @@ tools:
 
 You are a frontend specialist. You focus on UI components, accessibility, performance, and browser-specific behaviour.
 
+You are **write-capable** (Edit / Write / Bash) and have **no memory** of the parent conversation. Brief yourself from the component / route paths the caller provides. Before returning `Status: DONE`, run the project's test suite and report pass/fail. If the brief is missing context, return `Status: NEEDS_CONTEXT` with a specific list of what you need.
+
+See also: `directions`, `decide`, `dependency-hygiene`, `test-driven-development`.
+
 ## Domain expertise
 
 - **React/Next.js**: hooks, server/client components, RSC patterns
@@ -29,7 +33,7 @@ You are a frontend specialist. You focus on UI components, accessibility, perfor
 - Components are presentation-only when possible
 - Use `const` function components, not class components
 - No inline styles for anything that can be expressed as a class
-- Images: always specify `width` and `height`; use `next/image` or equivalent
+- Images: always specify `width` and `height`; use the framework's image-optimisation primitive (`next/image`, `@astrojs/image`, `nuxt/image`, etc.) — never raw `<img>` for non-decorative content
 
 ## When you receive a task
 
@@ -41,9 +45,9 @@ You are a frontend specialist. You focus on UI components, accessibility, perfor
 ## Handoff format
 
 ```
-[frontend] → [reviewer | tester | orchestrator]
+[frontend] → [orchestrator | user]
 Summary: [what was built/changed]
 Artifacts: [files modified]
-Next: [review / test / deploy]
-Status: DONE | DONE_WITH_CONCERNS
+Next: run the project's test suite / visual review / hand back to orchestrator
+Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 ```

package/catalog/agents/tier2/mobile.md

@@ -15,6 +15,10 @@ tools:
 
 You are a mobile specialist. You focus on platform differences, performance on constrained devices, and the app store submission requirements.
 
+You are **write-capable** (Edit / Write / Bash) and have **no memory** of the parent conversation. Brief yourself from the platform / module paths the caller provides. Before returning `Status: DONE`, verify the build succeeds on both targets and request the user device-test before sign-off. If the brief is missing context, return `Status: NEEDS_CONTEXT` with a specific list of what you need.
+
+See also: `dependency-hygiene`, `test-driven-development`.
+
 ## Domain expertise
 
 - **React Native**: navigation, native modules, Expo vs bare workflow
@@ -25,9 +29,9 @@ You are a mobile specialist. You focus on platform differences, performance on c
 
 ## Constraints
 
-- Test on both iOS and Android before marking done
+- Verify the build succeeds on both iOS and Android targets; request the user device-test before sign-off
 - Consider: low-bandwidth network conditions (3G, intermittent)
-- Consider: older OS versions (iOS 15+, Android 10+) unless told otherwise
+- Honour the project's declared minimums in `Info.plist` / `build.gradle` — never assume baseline OS versions
 - App store guidelines: no undocumented private API usage
 
 ## When you receive a task
@@ -40,9 +44,9 @@ You are a mobile specialist. You focus on platform differences, performance on c
 ## Handoff format
 
 ```
-[mobile] → [reviewer | tester | orchestrator]
+[mobile] → [orchestrator | user]
 Summary: [what was built/changed]
 Artifacts: [files modified]
-Next: [review / test on device / submit]
-Status: DONE | DONE_WITH_CONCERNS
+Next: verify build on both targets / request device test / hand back to orchestrator
+Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
 ```

package/catalog/commands/commit-push-pr.md

@@ -1,10 +1,17 @@
 Commit all staged changes, push to the current branch, and open a pull request.
 
-1. Run the `/commit` flow (stage, draft message, commit).
-2. Push: `git push -u origin HEAD`
-3. Open a PR using the writing-pull-requests skill:
-   - Title: ≤70 chars, Conventional Commits format
-   - Body: Summary bullets + Test plan checklist
+Uses the `writing-commits` and `writing-pull-requests` skills; gated by `verification-before-completion`. `$ARGUMENTS` may supply the PR title; otherwise draft one from the diff.
+
+0. **Verification gate** — invoke the `verification-before-completion` skill. Detect the test command from the project manifest (`package.json` → `npm test` / `pnpm test`, `Cargo.toml` → `cargo test`, `pyproject.toml` → `pytest`, `go.mod` → `go test ./...`). If tests fail, **STOP** and report — do not commit broken code.
+
+1. **Branch guard** — if `git branch --show-current` returns `main` / `master`, refuse and ask the user to create a feature branch first (naming convention: `type/short-description`).
+
+2. **Commit** — run the `/commit` flow (stage, draft message via `writing-commits` skill, commit).
+
+3. **Push** — `git push -u origin HEAD` (no `--force`; if the remote already has commits, stop and surface the conflict).
+
+4. **Open PR** — invoke the `writing-pull-requests` skill. Title is `$ARGUMENTS` if provided, otherwise drafted from the diff (≤70 chars, Conventional Commits format). Body:
+
 ```bash
 gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
 ## Summary
@@ -12,10 +19,9 @@ gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
 
 ## Test plan
 - [ ] [how to verify]
-- [ ] Full suite passes: `npm test`
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
+- [ ] Full suite passes: <detected test command>
 EOF
 )"
 ```
-4. Report the PR URL.
+
+5. **Report** the PR URL.

package/catalog/commands/commit.md

@@ -1,17 +1,7 @@
-Stage changed files, draft a Conventional Commits message, and commit using the writing-commits skill.
+Stage changed files and commit using the `writing-commits` skill. `$ARGUMENTS` may supply the commit message; otherwise draft one from the diff.
 
-1. Run `git status` to see what's changed.
-2. Run `git diff --staged` — confirm no secrets, debug logs, or `.env*` files.
-3. Draft the commit message in this format: `type(scope): description` (≤72 chars, imperative mood).
-4. Commit using HEREDOC format:
-```bash
-git commit -m "$(cat <<'EOF'
-type(scope): description
-
-[optional body explaining WHY]
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-EOF
-)"
-```
-5. Report: commit hash + message.
+1. Run `git status` + `git diff --staged`; confirm no secrets, debug logs, or `.env*` files.
+2. Apply `writing-commits` skill rules (Conventional Commits, ≤72 chars, imperative, body explains WHY).
+3. If the change touches `src/` or `test/`, recommend `verification-before-completion` (run the project's test command) before committing.
+4. Commit via HEREDOC; co-author = current Claude model name.
+5. Report commit hash + message.

package/catalog/commands/decide.md

@@ -1,24 +1,15 @@
 Generate a single rich HTML decision page using the `decide` skill.
 
 ## Usage
-`/decide <topic>`
+`/decide $ARGUMENTS`
 
-Example: `/decide auth strategy: session cookies vs JWT vs Clerk`.
+`$ARGUMENTS` is the decision topic + options (e.g. `auth strategy: session cookies vs JWT vs Clerk`).
 
 ## Steps
-
 1. **Confirm the options** with the user before writing. Say back: *"Decision page on `<topic>` with options `A`, `B`, `C` — okay? My pick will be `<X>` because `<one-sentence reason>`."* Wait for yes.
-
-2. **Read the template** at `.aikit/templates/decide/template.html`. Copy its structure verbatim — design tokens, layout grid, callout patterns, voice + a11y conventions.
-
-3. **Gather concrete inputs** for each option: real cost numbers, real performance figures, real code snippets if relevant. Don't fill cards with hand-waved pros/cons — use facts.
-
-4. **Apply the voice rule** when writing prose: plain-language verb + concrete object, jargon in `<code>` chips not the reading path. Explain the technical bit like the reader is 15.
-
-5. **Write the file** to `docs/decisions/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug).
-
-6. **Report.** Print the file path and suggest `open docs/decisions/YYYY-MM-DD-<slug>.html` (macOS) / `xdg-open` (Linux).
+2. **Invoke the `decide` skill** — it loads `.aikit/templates/decide/template.html`, design tokens, voice rules, and a11y baseline.
+3. **Write** to `docs/decisions/YYYY-MM-DD-<slug>.html` (use `date +%Y-%m-%d` for local-zone date).
+4. **Report** the file path; suggest `open` (macOS) / `xdg-open` (Linux).
 
 ## Fallback
-
 If `.aikit/templates/decide/template.html` is missing, run `aikit sync` first.

package/catalog/commands/design.md

@@ -1,44 +1,32 @@
-Codify the project's visual language as a `DESIGN.md` contract + interactive HTML showroom using the `design` skill.
+Codify the project's visual language as a marker-bounded `DESIGN.md` and render an interactive HTML showroom, using the `design` skill.
 
 ## Usage
 
-`/design` — bootstrap `DESIGN.md` at the project root (asks for screenshot / HTML / URL / brief).
-`/design refine <change>` — update one marker-bounded section without touching the rest.
-
-Example:
-- `/design` → AI asks for input, then writes `DESIGN.md` + `docs/design/index.html`.
-- `/design refine make primary brighter, around #FF8800` → AI touches only the `colors` section.
-
-## Steps — bootstrap (`/design`)
-
-1. **Ask which input the user has.** Screenshot, HTML paste/path, live URL, or pure design brief. Wait for an answer.
-
-2. **Read the starter** at `.aikit/templates/design/starter-DESIGN.md`. It already has the 5 marker-bounded sections in the right shape.
-
-3. **Fill each section** from the user's input. Use the skill's voice rules — descriptive natural language + precise hex codes in `code` ticks, physical descriptions over Tailwind jargon, value + functional role together.
-
-4. **Confirm before writing.** One sentence in chat: *"I'll write `DESIGN.md` at the project root and render the showroom at `docs/design/index.html`. Okay?"* Wait for explicit yes.
-
-5. **Write `DESIGN.md`** at the project root with stable BEGIN/END markers around each of the 5 sections (`atmosphere`, `colors`, `typography`, `components`, `layout`).
-
-6. **Render the showroom.** Read `.aikit/templates/design/template.html`, substitute the project's tokens into `--project-*` CSS custom properties and the `data-aikit-section="<id>"` content blocks, and write to `docs/design/index.html`.
-
-7. **Report.** Print both file paths. Suggest `open docs/design/index.html` (macOS) / `xdg-open` (Linux).
-
-## Steps — refine (`/design refine <change>`)
-
-1. **Pick exactly one section.** From `<change>`, identify which of the 5 section IDs it affects. If it spans more than one, ask which to start with.
-
-2. **Read only that section** via `readSection(content, "<id>", "DESIGN.md")` from `src/render/markers` — never load the whole file.
-
-3. **Propose the rewrite** in chat: show the new section body. Wait for yes.
-
-4. **Write through the marker engine.** `writeSection(content, "<id>", newBody, "DESIGN.md")`. Anything outside the markers is preserved verbatim.
-
-5. **Regenerate the showroom** from the updated `DESIGN.md`.
-
-6. **Report.** Print the section ID that changed and the two file paths.
+`/design $ARGUMENTS`
+
+- **No args** → bootstrap mode. Look at the conversation context for input: a pasted screenshot, an HTML paste, a URL, or a verbal brief. If multiple input modes are present, ask which to use. Creates `DESIGN.md` at the project root and the showroom at `docs/design/index.html`.
+- **`refine "<change>"`** → surgical edit mode. Identify which of the five sections (`atmosphere`, `colors`, `typography`, `components`, `layout`) the change belongs to, then update only that section via the marker engine. Examples:
+  - `/design refine "muted accent, like #C2664D"` → updates `colors`
+  - `/design refine "switch headlines to a slab serif"` → updates `typography`
+  - `/design refine "tighter 600px content column"` → updates `layout`
+
+## Steps
+
+1. **Detect mode.** If args start with `refine`, route to refine. Otherwise bootstrap.
+2. **Invoke the `design` skill** — it owns the voice rules, section structure, and marker engine wiring.
+3. **For bootstrap:**
+   - Confirm input mode (screenshot, HTML, URL, brief) before writing.
+   - Copy `.aikit/templates/design/starter-DESIGN.md` to `DESIGN.md` at project root.
+   - Fill each of the five sections via `writeSection` from `src/render/markers.ts`, respecting voice rules (hex codes in `code` ticks; descriptive language; no Tailwind jargon).
+   - Copy `.aikit/templates/design/template.html` to `docs/design/index.html`.
+   - Report both paths.
+4. **For refine:**
+   - Read the targeted section with `readSection(content, "<id>", "DESIGN.md")`.
+   - Synthesize the new body; apply voice rules.
+   - Write back with `writeSection`. Do not touch the other four sections.
+   - Confirm which section changed; report the diff.
+5. **Refuse cleanly** if `DESIGN.md` exists but has no markers (offer to re-bootstrap with `AskUserQuestion`), or if refine is called and no `DESIGN.md` exists yet.
 
 ## Fallback
 
-If `.aikit/templates/design/template.html` or `.aikit/templates/design/starter-DESIGN.md` is missing, run `aikit add design` first. The skill refuses to scaffold without the template.
+If `.aikit/templates/design/` is missing (project synced before this kit version), run `aikit add design` to install companion artifacts, or `aikit sync` if the skill is already opted in.

package/catalog/commands/directions.md

@@ -1,29 +1,16 @@
 Render 2-4 visual design directions on a single self-contained HTML page using the `directions` skill.
 
 ## Usage
-`/directions <surface>`
+`/directions $ARGUMENTS`
 
-Examples:
-- `/directions empty state for the projects view`
-- `/directions hero section for the marketing landing`
-- `/directions dashboard card — three density options`
+`$ARGUMENTS` is the surface to design (e.g. `empty state for the projects view`, `hero section for the marketing landing`).
 
 ## Steps
-
 1. **Confirm the brief** with the user before writing. Say back: *"Directions page for `<surface>` with `<N>` variants emphasizing `<axes>` (e.g. minimal · illustrated · instructional). I'll render each live on light and dark stages. Okay?"* Wait for yes.
-
-2. **Read the template** at `.aikit/templates/directions/template.html`. Copy its structure verbatim — design tokens, sticky toolbar, artboard grid, light/dark stage flip.
-
-3. **Pick variants that differ in strategy, not detail.** Each direction should have a one-word personality (`Minimal`, `Illustrated`, `Playful`, `Instructional`, `Editorial`, `Technical`). A 1px font tweak isn't a direction.
-
-4. **Render, don't describe.** Each variant's stage must contain real HTML/CSS that actually displays the design. A wall of bullet points describing the variant defeats the skill.
-
-5. **Use the user's domain language.** Real copy ("New task", "No projects yet"), not lorem ipsum.
-
-6. **Write the file** to `docs/directions/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug from the surface).
-
-7. **Report.** Print the file path and suggest `open docs/directions/YYYY-MM-DD-<slug>.html` (macOS) / `xdg-open` (Linux). One-sentence summary of what each variant emphasizes.
+2. **Invoke the `directions` skill** — it owns template loading, the one-word personality vocabulary, the variant-strategy rules, and the domain-language requirement.
+3. **Preserve dark-mode tokens.** The template ships light + dark CSS — do not strip the `:where(:root[data-theme="dark"])` rules.
+4. **Write** to `docs/directions/YYYY-MM-DD-<slug>.html` (use `date +%Y-%m-%d` for local-zone date).
+5. **Report** the file path + one-sentence summary of what each variant emphasizes.
 
 ## Fallback
-
 If `.aikit/templates/directions/template.html` is missing, run `aikit sync` first.

package/catalog/commands/docs.md

@@ -1,27 +1,19 @@
 Update the project's HTML documentation in `docs/` using the `docs` skill.
 
 ## Usage
-`/docs [optional intent]`
+`/docs $ARGUMENTS`
 
-With args: use them as the change to document (e.g. `/docs the new auth refresh flow`).
-Without args: infer from the last 5-10 turns of conversation what's worth documenting.
+`$ARGUMENTS` is the change to document (e.g. `the new auth refresh flow`). Without args, infer from the last 5-10 turns of conversation.
 
 ## Steps
-
 1. **Decide what changed.** Identify (a) the doc file (`docs/<slug>.html`) and (b) the section id inside it (`overview`, `flow`, `gotchas`, etc). If no doc fits, propose creating one.
-
-2. **Read only the affected section.** Use `readSection(content, id, filePath)` from `src/render/markers` — never load the whole file.
-
+2. **Invoke the `docs` skill** — it owns the section-scoped read/write helpers, theme prompts, diagram taxonomy, and starter-template fallback.
 3. **Propose before writing.** One sentence in chat:
    > *"I'll update `<section>` in `docs/<file>.html` to reflect <change>. Okay?"*
    Wait for explicit yes. No silent edits.
-
-4. **Write through the marker engine.** `writeSection` to replace, `appendSection` for new sections. Anything outside markers is preserved verbatim.
-
-5. **Update `docs/index.html`** if you created a new doc or materially changed an existing one — refresh the matching `summary-<slug>` section.
-
-6. **Report.** Print the modified file paths and one-line summary of what changed.
+4. **Write through the marker engine** — anything outside `<!-- BEGIN:haac-aikit:section:<id> -->` markers is preserved verbatim.
+5. **Update `docs/index.html`** if you changed any `summary-<slug>` section content or created a new `docs/<slug>.html` file.
+6. **Report** modified file paths + one-line summary of what changed.
 
 ## Fallback
-
 If `.aikit/templates/docs/starter.html` is missing (project synced before this kit version), run `aikit sync` first.

package/catalog/commands/roadmap.md

@@ -1,31 +1,20 @@
 Generate a thorough single-page implementation roadmap as HTML using the `roadmap` skill.
 
 ## Usage
-`/roadmap <feature>`
+`/roadmap $ARGUMENTS`
 
-Examples:
-- `/roadmap comment threads on task cards`
-- `/roadmap migrate session store from cookies to Redis`
-- `/roadmap add real-time presence to the editor`
+`$ARGUMENTS` is the feature (e.g. `comment threads on task cards`, `migrate session store from cookies to Redis`).
 
 ## Steps
-
-1. **Confirm the shape** with the user before writing. Say back: *"Roadmap for `<feature>`. I'll lay out ~`<N>` milestones, a data-flow diagram, mockups of `<surfaces>`, code for the migration and the `<key piece>`, and a risk table. Anything I should change before I write?"* Wait for yes.
-
-2. **Read the template** at `.aikit/templates/roadmap/template.html`. Copy its structure verbatim — design tokens, summary strip, milestone timeline, SVG diagram pattern, mockup grid, code panel, risk table, open-questions callouts.
-
+1. **Confirm the shape** with the user before writing. Say back:
+   - *Roadmap for `<feature>`.*
+   - *I'll lay out `~<N>` milestones, a data-flow diagram, mockups of `<surfaces>`, code for the migration and the `<key piece>`, and a risk table.*
+   - *Anything to change before I write?*
+   Wait for yes.
+2. **Invoke the `roadmap` skill** — it owns template loading, the eight-section structure, mockup-as-HTML rules, code-block sizing, and open-questions enforcement.
 3. **Gather concrete inputs**: real package/file names, real effort estimates, real risks. If you don't know a number, ask — don't invent one.
-
-4. **Render mockups as HTML**, not screenshots. Use the project's real domain language and component names.
-
-5. **Code blocks are illustrative.** 15-30 lines of the load-bearing logic per block (migration + the optimistic mutation, say). Don't dump entire files.
-
-6. **Every roadmap needs at least one open question.** If you genuinely can't think of one, state explicitly *why* the design is fully settled in a one-sentence aside.
-
-7. **Write the file** to `docs/roadmaps/YYYY-MM-DD-<slug>.html` (today's date, kebab-case slug from the feature).
-
-8. **Report.** Print the file path and suggest `open docs/roadmaps/YYYY-MM-DD-<slug>.html` (macOS) / `xdg-open` (Linux). One-sentence summary of milestone count, surfaces touched, and severity-high risks.
+4. **Write** to `docs/roadmaps/YYYY-MM-DD-<slug>.html` (use `date +%Y-%m-%d` for local-zone date).
+5. **Report** the file path + one-sentence summary of milestone count, surfaces touched, and severity-high risks.
 
 ## Fallback
-
 If `.aikit/templates/roadmap/template.html` is missing, run `aikit sync` first.

package/catalog/commands/security-review.md

@@ -1,33 +1,14 @@
-Run an OWASP-aligned security sweep using the security-review skill.
+Run an OWASP-aligned security sweep using the `security-review` skill.
 
-Check the recent changes (or the specified scope) for:
+## Usage
+`/security-review $ARGUMENTS`
 
-**Injection (A03)**
-- SQL queries use parameterised statements — no string concatenation
-- Shell commands use execFile with arg arrays — no user data in shell strings
-- Template rendering sanitises HTML output
+`$ARGUMENTS` is the scope (file path / glob) if provided, otherwise the diff vs the merge base.
 
-**Auth & session (A07)**
-- Tokens not in logs or error responses
-- Session IDs regenerated on privilege escalation
+## Steps
+1. Invoke the `security-review` skill — it owns the OWASP A01/A02/A03/A06/A07 checklist, severity mapping, and ✓/⚠/✗ report format.
+2. For supply-chain findings (A06), defer to the `dependency-hygiene` skill rather than duplicating the rule here.
+3. Report the ✓/⚠/✗ summary. Any ✗ (critical) is a blocker for `/ship` and `/commit-push-pr`.
 
-**Sensitive data (A02)**
-- No hardcoded secrets, API keys, or credentials
-- Env vars validated at startup
-- No sensitive fields in console.log output
-
-**Access control (A01)**
-- Every route checks authorisation, not just authentication
-- Resource ownership verified
-
-**Supply chain (A06)**
-- No new dependencies without hygiene check
-- `npm audit` passes
-
-Output:
-```
-Security sweep: [scope]
-✓ No issues in [category]
-⚠ [category]: [finding] at [file:line] — [fix]
-✗ [critical] — MUST fix before merge
-```
+## Note
+This command is the dispatch shim. The full checklist lives in the skill so the two cannot drift.

package/catalog/commands/ship.md

@@ -1,21 +1,27 @@
-Run the full release checklist before tagging a release.
+Run the full release checklist before tagging a release. `$ARGUMENTS` is the version tag (e.g. `v1.2.3`); prompt if missing.
 
-1. **Tests**: `npm test` — all pass, 0 failures.
-2. **Types**: `tsc --noEmit` — clean.
-3. **Lint**: `npm run lint` — clean.
-4. **Security sweep**: run the `/security-review` command on changed files.
+0. **Verification gate** — invoke the `verification-before-completion` skill. It sets the bar that every numbered step below must clear.
+
+1. **Tests**: project test command — all pass, 0 failures. (`npm test` / `pnpm test` / `cargo test` / `pytest` / `go test ./...` — detect from manifest.)
+2. **Types**: project typechecker — clean. (`tsc --noEmit` / `mypy` / `cargo check`.)
+3. **Lint**: project linter — clean. (`npm run lint` / `ruff check` / `cargo clippy`.)
+4. **Security sweep**: run the `/security-review` command on changed files. Any ✗ (critical) **blocks** the ship.
 5. **Changelog**: confirm CHANGELOG.md or release notes are updated.
-6. **Version bump**: update `package.json` version, commit with `chore(release): vX.Y.Z`.
+6. **Version bump**: update the project's manifest (`package.json` for npm, `Cargo.toml` for Cargo, `pyproject.toml` for Poetry/PDM, `go.mod` for Go modules). Commit with `chore(release): vX.Y.Z`.
 7. **Tag**:
 ```bash
-git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git tag -a vX.Y.Z -m "Release vX.Y.Z"   # use -s instead of -a if commit.gpgsign=true
 git push origin vX.Y.Z
 ```
-8. **Publish** (if npm package):
+8. **Publish** (matches package manager):
 ```bash
-npm publish --dry-run   # inspect first
-npm publish
+# npm:    npm publish --dry-run && npm publish
+# Cargo:  cargo publish --dry-run && cargo publish
+# PyPI:   python -m build && twine upload dist/*
+# Go:     publishing happens via tag push — step 7 already did it
 ```
 9. **Post-release**: create a GitHub release with the changelog entry.
 
-Only mark shipped when all 9 steps are complete.
+10. **Smoke test**: install the published artifact in a temp dir and verify `--version` matches the tagged version.
+
+Only mark shipped when all 10 steps are complete.

package/catalog/skills/tier1/{brainstorming.md → brainstorming/SKILL.md}

@@ -1,9 +1,11 @@
 ---
 name: brainstorming
-description: Use when a request is ambiguous, has multiple valid approaches, or involves a product/design decision. Clarifies requirements before writing any code or making irreversible changes. Prevents wasted implementation work caused by misunderstood intent.
+description: Use when a request is ambiguous or has multiple valid approaches — phrases like "make this better", "add auth", "refactor this", "clean this up", or any vague ask. Surfaces assumptions and presents 2-3 concrete options before writing code, so you don't burn implementation time on the wrong interpretation.
 version: "1.0.0"
 source: obra/superpowers
 license: MIT
+allowed-tools:
+  - AskUserQuestion
 ---
 
 ## When to use

package/catalog/skills/tier1/{codebase-exploration.md → codebase-exploration/SKILL.md}

@@ -1,9 +1,16 @@
 ---
 name: codebase-exploration
-description: Use when starting work in an unfamiliar codebase or module, before editing any code, or when asked to understand how something works. Read-only reconnaissance before any editing prevents breaking changes caused by misunderstood dependencies.
+description: Use when starting work in an unfamiliar codebase or module, or when the user says "how does X work?", "explain this repo", "I'm new here", or "let me understand before touching it". Read-only reconnaissance — entry points, critical path, dependencies, tests — before any edit, so you don't break code you don't understand.
 version: "1.0.0"
 source: haac-aikit
 license: MIT
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash(ls:*)
+  - Bash(find:*)
+  - Bash(rg:*)
 ---
 
 ## When to use
@@ -51,5 +58,10 @@ Understanding:
 → Ready to proceed / Need to clarify: [question]
 ```
 
-## Constraint
-No file edits during exploration. If you discover something that needs fixing while exploring, note it but do not fix it yet — complete the exploration first.
+## Anti-patterns
+- **Editing during exploration.** Every fix-while-exploring discovers another unrelated "while I'm here" edit; the exploration never finishes. Note issues, fix them after.
+- **Reading source before tests.** Tests show intent in one screen; source forces you to infer it across many files.
+- **Skipping the dependency map** (who imports this?). Most refactor regressions come from hidden consumers.
+- **Spending >5 minutes on `ls`/`cat` orientation** before naming the specific file you need to touch. Re-scope: explore *to answer a question*, not exhaustively.
+
+When exploration ends in a bug, invoke `systematic-debugging`. When it ends in a build task, invoke `writing-plans`.

package/catalog/skills/tier1/{decide.md → decide/SKILL.md}

@@ -1,9 +1,14 @@
 ---
 name: decide
-description: Use when the user is about to make a non-trivial choice with 2-4 viable options and wants the tradeoffs visualized as a single rich HTML page they can scan, share, and commit to the project's decision log. Generates one self-contained HTML file per decision under `docs/decisions/YYYY-MM-DD-<slug>.html`. Opt-in only — do not invoke without user request.
+description: Use when the user types "/decide <topic>", "use the decide skill", or "make me a decision page on X" — a non-trivial choice with 2-4 viable options that needs tradeoffs visualized as one rich HTML page. Generates a self-contained file at `docs/decisions/YYYY-MM-DD-<slug>.html`. Opt-in: do not invoke proactively.
 version: "1.0.0"
 source: haac-aikit
 license: MIT
+allowed-tools:
+  - Read
+  - Write
+  - Bash(date:*)
+  - AskUserQuestion
 ---
 
 ## When to use