docs: add skill manager documentation

README.md

@@ -122,15 +122,31 @@ Use the repository skill manager to install, update/reinstall, or remove skills
 node scripts/manage-skills.mjs
 ```
 
-Useful non-interactive modes:
+Useful non-interactive modes and examples:
 
 ```bash
+# Preview detected clients and planned changes without writing files
 node scripts/manage-skills.mjs --dry-run
+
+# Emit a machine-readable operation plan from an answers file
 node scripts/manage-skills.mjs --plan-only --answers answers.json
+
+# Install/update a skill for a specific client
+node scripts/manage-skills.mjs --client codex --scope global --skill create-plan --action install --yes
+node scripts/manage-skills.mjs --client codex --scope global --skill create-plan --action update --yes
+
+# Remove a skill from a specific client
+node scripts/manage-skills.mjs --client claude-code --scope global --skill do-task --action remove --yes
+
+# Install the Pi package globally or project-locally through the manager
+node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --action install --yes
+node scripts/manage-skills.mjs --client pi --scope packageLocal --pi-package --action install --yes
 ```
 
 The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks Superpowers dependencies for workflow skills, and prints a final operation report.
 
+`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill manager does not install, sync, or publish `ai_plan/` contents.
+
 ## Pi Package
 
 The repo root now includes a pi package manifest that ships only the pi-specific surface:

docs/CLAUDE-CODE.md

@@ -0,0 +1,57 @@
+# Claude Code Manual Install
+
+## Skill Root
+
+Claude Code's Skill tool auto-discovers skills installed under:
+
+```bash
+~/.claude/skills/<skill-name>/
+```
+
+Manual install example:
+
+```bash
+mkdir -p ~/.claude/skills/do-task
+cp -R skills/do-task/claude-code/* ~/.claude/skills/do-task/
+```
+
+Use `skills/<skill>/claude-code/*` for each supported skill.
+
+## Reviewer Runtime
+
+```bash
+mkdir -p ~/.claude/skills/reviewer-runtime
+cp skills/reviewer-runtime/run-review.sh ~/.claude/skills/reviewer-runtime/
+cp skills/reviewer-runtime/notify-telegram.sh ~/.claude/skills/reviewer-runtime/
+chmod +x ~/.claude/skills/reviewer-runtime/*.sh
+```
+
+## Superpowers
+
+Workflow skills invoke Superpowers through Claude Code's skill system. Install or link the Obra Superpowers skills under:
+
+```bash
+~/.claude/skills/superpowers/
+```
+
+Example:
+
+```bash
+ln -s /absolute/path/to/obra/superpowers/skills ~/.claude/skills/superpowers
+```
+
+Verify:
+
+```bash
+test -f ~/.claude/skills/superpowers/brainstorming/SKILL.md
+test -f ~/.claude/skills/superpowers/test-driven-development/SKILL.md
+test -f ~/.claude/skills/superpowers/verification-before-completion/SKILL.md
+```
+
+## Verify
+
+```bash
+claude --version
+test -f ~/.claude/skills/do-task/SKILL.md
+test -x ~/.claude/skills/reviewer-runtime/run-review.sh
+```

docs/CODEX.md

@@ -0,0 +1,61 @@
+# Codex Manual Install
+
+## Skill Root
+
+Codex skills are installed under:
+
+```bash
+~/.codex/skills/<skill-name>/
+```
+
+Manual install example:
+
+```bash
+mkdir -p ~/.codex/skills/create-plan
+cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/
+```
+
+Repeat with `skills/<skill>/codex/*` for `atlassian`, `create-plan`, `do-task`, `implement-plan`, and `web-automation`.
+
+## Reviewer Runtime
+
+Workflow skills need the shared runtime helpers:
+
+```bash
+mkdir -p ~/.codex/skills/reviewer-runtime
+cp skills/reviewer-runtime/run-review.sh ~/.codex/skills/reviewer-runtime/
+cp skills/reviewer-runtime/notify-telegram.sh ~/.codex/skills/reviewer-runtime/
+chmod +x ~/.codex/skills/reviewer-runtime/*.sh
+```
+
+## Superpowers
+
+Workflow skills require Obra Superpowers. Codex variants expect the shared root:
+
+```bash
+mkdir -p ~/.agents/skills
+ln -s /absolute/path/to/obra/superpowers/skills ~/.agents/skills/superpowers
+```
+
+Verify planning skills:
+
+```bash
+test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md
+test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md
+```
+
+Verify execution skills:
+
+```bash
+test -f ~/.agents/skills/superpowers/test-driven-development/SKILL.md
+test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md
+test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md
+```
+
+## Verify
+
+```bash
+test -f ~/.codex/skills/create-plan/SKILL.md
+test -x ~/.codex/skills/reviewer-runtime/run-review.sh
+codex --version
+```

docs/CURSOR.md

@@ -0,0 +1,84 @@
+# Cursor Manual Install
+
+## Skill Roots
+
+Cursor supports repo-local and global skills:
+
+```bash
+.cursor/skills/<skill-name>/
+~/.cursor/skills/<skill-name>/
+```
+
+Manual repo-local install example:
+
+```bash
+mkdir -p .cursor/skills/create-plan
+cp -R skills/create-plan/cursor/* .cursor/skills/create-plan/
+```
+
+Global install example:
+
+```bash
+mkdir -p ~/.cursor/skills/create-plan
+cp -R skills/create-plan/cursor/* ~/.cursor/skills/create-plan/
+```
+
+Cursor variants exist for `atlassian`, `create-plan`, `do-task`, and `implement-plan`. `web-automation` currently has no Cursor variant.
+
+## Reviewer Runtime
+
+Repo-local:
+
+```bash
+mkdir -p .cursor/skills/reviewer-runtime
+cp skills/reviewer-runtime/run-review.sh .cursor/skills/reviewer-runtime/
+cp skills/reviewer-runtime/notify-telegram.sh .cursor/skills/reviewer-runtime/
+chmod +x .cursor/skills/reviewer-runtime/*.sh
+```
+
+Global uses `~/.cursor/skills/reviewer-runtime/` instead.
+
+## Superpowers
+
+Cursor variants expect the nested Superpowers layout:
+
+```bash
+.cursor/skills/superpowers/skills/<superpower>/SKILL.md
+~/.cursor/skills/superpowers/skills/<superpower>/SKILL.md
+```
+
+Recommended symlink:
+
+```bash
+mkdir -p .cursor/skills/superpowers
+ln -s /absolute/path/to/obra/superpowers/skills .cursor/skills/superpowers/skills
+```
+
+## Cursor Reviewer Notes
+
+Cursor reviewer calls use JSON output and require `jq` where the skill variant parses reviewer responses:
+
+```bash
+cursor-agent --version
+jq --version
+```
+
+Reviewer calls must use `--mode=ask --trust --output-format json`, never write-capable modes.
+
+## Verify
+
+Repo-local scope:
+
+```bash
+cursor-agent --version
+test -f .cursor/skills/create-plan/SKILL.md
+test -f .cursor/skills/superpowers/skills/brainstorming/SKILL.md
+```
+
+Global scope:
+
+```bash
+cursor-agent --version
+test -f ~/.cursor/skills/create-plan/SKILL.md
+test -f ~/.cursor/skills/superpowers/skills/brainstorming/SKILL.md
+```

docs/INSTALLER.md

@@ -0,0 +1,134 @@
+# Skill Manager Installer
+
+Use the skill manager wizard to install, update/reinstall, or remove skills from this repository for supported local coding clients.
+
+## Quick Start
+
+```bash
+./scripts/manage-skills.sh
+# or
+node scripts/manage-skills.mjs
+```
+
+Preview without changing files:
+
+```bash
+node scripts/manage-skills.mjs --dry-run
+```
+
+Drive the planner non-interactively:
+
+```bash
+node scripts/manage-skills.mjs --plan-only --answers answers.json
+```
+
+## Supported Clients
+
+The wizard detects these clients by CLI and known skill directories:
+
+| Client | CLI check | Default skill root |
+|---|---|---|
+| Codex | `codex --version` | `~/.codex/skills` |
+| Claude Code | `claude --version` | `~/.claude/skills` |
+| Cursor | `cursor-agent --version` then `cursor agent --version` | `.cursor/skills` or `~/.cursor/skills` |
+| OpenCode | `opencode --version` | `~/.config/opencode/skills` |
+| Pi | `pi --version` | package mode or `.pi/skills` / `~/.pi/agent/skills` |
+
+## Actions
+
+For each selected client/scope, the wizard lists repository skills and offers actions based on installed state:
+
+- missing skill: `install` or `skip`
+- installed/stale/unknown skill: `update`, `reinstall`, `remove`, or `skip`
+- unsupported variant: reported as `unsupported` and skipped
+
+The current skill matrix is:
+
+| Skill | Codex | Claude Code | Cursor | OpenCode | Pi |
+|---|---:|---:|---:|---:|---:|
+| `atlassian` | yes | yes | yes | yes | yes |
+| `create-plan` | yes | yes | yes | yes | yes |
+| `do-task` | yes | yes | yes | yes | yes |
+| `implement-plan` | yes | yes | yes | yes | yes |
+| `web-automation` | yes | yes | no | yes | yes |
+
+## Superpowers Handling
+
+Workflow skills require Obra Superpowers:
+
+- `create-plan`: `brainstorming`, `writing-plans`
+- `implement-plan`: `executing-plans`, `using-git-worktrees`, `verification-before-completion`, `finishing-a-development-branch`
+- `do-task`: `brainstorming`, `test-driven-development`, `verification-before-completion`, `finishing-a-development-branch` plus conditional `using-git-worktrees`
+
+When a selected install/update needs Superpowers and none are detected for the target client/scope, the wizard asks whether to install them. It asks for an absolute path to an Obra Superpowers `skills` directory and lets you choose symlink or copy:
+
+- symlink is recommended because updates to the source checkout are immediately visible
+- copy is more self-contained but must be updated manually
+
+For Cursor, the wizard installs Superpowers at `<scope>/superpowers/skills` because Cursor variants expect `superpowers/skills/<skill>/SKILL.md`. Codex commonly reuses the shared `~/.agents/skills/superpowers` convention documented in [CODEX.md](./CODEX.md).
+
+When removing the last repository workflow skill from a client/scope, the wizard asks whether to remove Superpowers for that variant too.
+
+## Reviewer Runtime Helpers
+
+Workflow skills install/update the reviewer-runtime helper bundle automatically when needed:
+
+- non-Pi clients receive `run-review.sh` and `notify-telegram.sh` from `skills/reviewer-runtime/`
+- Pi receives `run-review.sh` and `notify-telegram.sh` from `skills/reviewer-runtime/pi/`
+- diagnostics tests and nested Pi helper directories are not copied into non-Pi installs
+
+## Pi Package Mode
+
+Pi can be managed as a package install or by manual skill copy. Package mode installs the full Pi bundle and bootstraps packaged runtimes:
+
+```bash
+node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --action install --yes
+node scripts/manage-skills.mjs --client pi --scope packageLocal --pi-package --action install --yes
+```
+
+The compatibility script remains available:
+
+```bash
+./scripts/install-pi-package.sh --global
+./scripts/install-pi-package.sh --local
+```
+
+## Answers JSON
+
+`--plan-only --answers` accepts this shape:
+
+```json
+{
+  "selections": [
+    {
+      "clientId": "codex",
+      "scope": "global",
+      "actions": {
+        "create-plan": "install",
+        "web-automation": "skip"
+      }
+    }
+  ]
+}
+```
+
+The output is JSON containing planned operations, dependency prompts, and final-report rows. No filesystem changes are made.
+
+## Final Report
+
+The final report uses these columns:
+
+| Column | Meaning |
+|---|---|
+| client | client id |
+| scope | selected target scope |
+| skill/helper | skill name or helper bundle |
+| action | install, update, reinstall, remove, sync, bootstrap, etc. |
+| status | `ok`, `skipped`, `failed`, or `warning` |
+| details | target path or error detail |
+
+Exit code is non-zero if any selected operation fails.
+
+Dangling symlink warnings are surfaced as `warning` rows. For example, if a previously symlinked Superpowers source has moved or been deleted, the final report keeps the operation non-destructive and shows the dangling symlink target in `details` so you can repair or remove it deliberately.
+
+See [PI.md](./PI.md) for Pi package layout details and mirror maintenance.

docs/OPENCODE.md

@@ -0,0 +1,65 @@
+# OpenCode Manual Install
+
+## Skill Root
+
+OpenCode skills are installed under:
+
+```bash
+~/.config/opencode/skills/<skill-name>/
+```
+
+Manual install example:
+
+```bash
+mkdir -p ~/.config/opencode/skills/implement-plan
+cp -R skills/implement-plan/opencode/* ~/.config/opencode/skills/implement-plan/
+```
+
+Use `skills/<skill>/opencode/*` for each supported skill.
+
+## Reviewer Runtime
+
+```bash
+mkdir -p ~/.config/opencode/skills/reviewer-runtime
+cp skills/reviewer-runtime/run-review.sh ~/.config/opencode/skills/reviewer-runtime/
+cp skills/reviewer-runtime/notify-telegram.sh ~/.config/opencode/skills/reviewer-runtime/
+chmod +x ~/.config/opencode/skills/reviewer-runtime/*.sh
+```
+
+## Superpowers
+
+OpenCode variants expect Superpowers at:
+
+```bash
+~/.config/opencode/skills/superpowers
+```
+
+Example:
+
+```bash
+ln -s /absolute/path/to/obra/superpowers/skills ~/.config/opencode/skills/superpowers
+```
+
+Verify:
+
+```bash
+ls -l ~/.config/opencode/skills/superpowers
+test -f ~/.config/opencode/skills/superpowers/brainstorming/SKILL.md
+test -f ~/.config/opencode/skills/superpowers/verification-before-completion/SKILL.md
+```
+
+## OpenCode Reviewer Notes
+
+OpenCode reviewer calls use the built-in read-oriented plan agent:
+
+```bash
+opencode run -m <provider>/<model> --agent plan --format json "review prompt"
+```
+
+## Verify
+
+```bash
+opencode --version
+test -f ~/.config/opencode/skills/implement-plan/SKILL.md
+test -x ~/.config/opencode/skills/reviewer-runtime/run-review.sh
+```

docs/README.md

@@ -4,6 +4,11 @@ This directory contains user-facing docs for each skill.
 
 ## Index
 
+- [INSTALLER.md](./INSTALLER.md) — Skill manager wizard for installing, updating/reinstalling, and removing repo skills across supported clients.
+- [CODEX.md](./CODEX.md) — Manual install instructions for Codex variants.
+- [CLAUDE-CODE.md](./CLAUDE-CODE.md) — Manual install instructions for Claude Code variants.
+- [CURSOR.md](./CURSOR.md) — Manual install instructions for Cursor variants.
+- [OPENCODE.md](./OPENCODE.md) — Manual install instructions for OpenCode variants.
 - [ATLASSIAN.md](./ATLASSIAN.md) — Includes requirements, generated bundle sync, install, auth, safety rules, and usage examples for the Atlassian skill.
 - [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan.
 - [DO-TASK.md](./DO-TASK.md) — Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit. Sibling of create-plan/implement-plan scoped to ad-hoc tasks.