@drunkcoding/agents-and-skills 0.0.25 → 0.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/.claude-plugin/marketplace.json +14 -33
  2. package/README.md +1 -0
  3. package/package.json +1 -1
  4. package/plugins/html-effectiveness/.claude-plugin/plugin.json +1 -1
  5. package/plugins/plugin-validator/.claude-plugin/plugin.json +1 -1
  6. package/plugins/team-share/.claude-plugin/plugin.json +17 -0
  7. package/plugins/team-share/README.md +30 -0
  8. package/plugins/team-share/agents/team-share.md +140 -0
  9. package/plugins/team-share/commands/team-share.md +4 -0
  10. package/plugins/tech-graph/.claude-plugin/plugin.json +1 -1
  11. package/plugins/auto-power/.claude-plugin/plugin.json +0 -17
  12. package/plugins/auto-power/README.md +0 -80
  13. package/plugins/auto-power/assets/CHECKPOINT_SCHEMA.md +0 -69
  14. package/plugins/auto-power/assets/ESCALATION_TEMPLATE.md +0 -67
  15. package/plugins/auto-power/commands/auto-power-resume.md +0 -32
  16. package/plugins/auto-power/commands/auto-power.md +0 -46
  17. package/plugins/auto-power/skills/auto-power-runtime/SKILL.md +0 -220
  18. package/plugins/team-superpower/.claude-plugin/plugin.json +0 -21
  19. package/plugins/team-superpower/README.md +0 -294
  20. package/plugins/team-superpower/agents/backend-developer.md +0 -221
  21. package/plugins/team-superpower/agents/feature-planner.md +0 -66
  22. package/plugins/team-superpower/agents/frontend-developer.md +0 -242
  23. package/plugins/team-superpower/agents/qc-engineer.md +0 -84
  24. package/plugins/team-superpower/agents/security-engineer.md +0 -175
  25. package/plugins/team-superpower/agents/solution-architect.md +0 -80
  26. package/plugins/team-superpower/agents/team-leader.md +0 -100
  27. package/plugins/team-superpower/assets/AGENTS.md.template +0 -23
  28. package/plugins/team-superpower/assets/CLAUDE.md.template +0 -117
  29. package/plugins/team-superpower/assets/ESCALATION.md +0 -142
  30. package/plugins/team-superpower/assets/SESSION_README.md +0 -337
  31. package/plugins/team-superpower/commands/team-cleanup.md +0 -70
  32. package/plugins/team-superpower/commands/team-feature.md +0 -319
  33. package/plugins/team-superpower/hooks/hooks.json +0 -25
  34. package/plugins/team-superpower/hooks/task-completed.sh +0 -254
  35. package/plugins/team-superpower/hooks/task-created.sh +0 -174
  36. package/plugins/team-superpower/hooks/teammate-idle.sh +0 -142
  37. package/plugins/team-superpower/scripts/assess-complexity.sh +0 -194
  38. package/plugins/team-superpower/scripts/detect-stack.sh +0 -473
  39. package/plugins/team-superpower/scripts/parse-claudemd.sh +0 -194
  40. package/plugins/team-superpower/scripts/team-state.sh +0 -313
  41. package/plugins/team-superpower/scripts/wave-collision-check.sh +0 -60
@@ -1,220 +0,0 @@
1
- ---
2
- name: auto-power-runtime
3
- description: Use when running /auto-power or /auto-power-resume. Drives the obra/superpowers skill chain as a single-session, hands-off pipeline with auto-answered clarifying questions, auto-approved mid-impl touchpoints, checkpoint-based resume, retry+escalation policy, and ff-merge finish.
4
- ---
5
-
6
- # auto-power-runtime
7
-
8
- You are the driver for the `/auto-power` and `/auto-power-resume` commands. You invoke `obra/superpowers` skills in order and apply the policies in this file at each touchpoint. You never improvise — every decision is either a deterministic rule below or an explicit escalation to the user.
9
-
10
- **Reference assets** (read once at start):
11
- - `assets/CHECKPOINT_SCHEMA.md` — checkpoint format and write triggers
12
- - `assets/ESCALATION_TEMPLATE.md` — escalation file structure and signal reference
13
-
14
- ## Pipeline
15
-
16
- Phases run serially. Write the checkpoint before advancing.
17
-
18
- 1. `spec` — invoke `superpowers:brainstorming` with the auto-answer interceptor (see §1).
19
- 2. `plan` — invoke `superpowers:writing-plans`.
20
- 3. `arch_sec` — run the inline architecture + security self-review checklist (see §3).
21
- 4. `worktree` — detect or create per §4.
22
- 5. `impl` — invoke `superpowers:subagent-driven-development` (preferred) or `superpowers:executing-plans`; intercept touchpoints per §5.
23
- 6. `verify` — invoke `superpowers:verification-before-completion`.
24
- 7. `review` — invoke `superpowers:requesting-code-review` (self-review pass).
25
- 8. `finish` — invoke `superpowers:finishing-a-development-branch`; ff-merge per §7.
26
-
27
- The **only** interactive owner touchpoint is the spec approval gate at the end of phase 1. Every other Claude-Code-side prompt is auto-resolved or escalated.
28
-
29
- ## §1. Clarifying-question auto-answer
30
-
31
- While phase 1 runs, intercept every clarifying question the brainstorming skill asks. Classify it against the whitelist below. Auto-answer only if the question matches a category **and** the repo signal is present **and** unambiguous. Otherwise forward verbatim to the user.
32
-
33
- ### Whitelist
34
-
35
- | Category | Signal source |
36
- |---|---|
37
- | Test framework | `package.json` devDependencies (`jest`, `vitest`, `mocha`, `node:test`); `pyproject.toml`; existing test files under `tests/`, `__tests__/`, `*_test.py` |
38
- | Build / lint / format command | `CLAUDE.md` `team-superpower` block; `package.json` `scripts`; `Makefile`; `pyproject.toml` `[tool.*]` |
39
- | File naming convention | Nearest sibling files in target dir (kebab vs snake vs camel by majority vote) |
40
- | Code style | `.prettierrc*`, `ruff.toml`, `pyproject.toml [tool.ruff]`, `.editorconfig`, `eslint.config.*` |
41
- | Target directory | Module structure of the nearest comparable feature |
42
- | Language / runtime version | `package.json` `engines`, `.tool-versions`, `.nvmrc`, `pyproject.toml` `requires-python` |
43
- | Plugin location convention | `plugins/<name>/` (per repo CLAUDE.md) |
44
- | Visual companion offer | Always decline (run is non-interactive after spec approval) |
45
-
46
- ### Always raise
47
-
48
- - Purpose / success criteria when the idea is ambiguous.
49
- - Trade-off choices with no clear repo signal.
50
- - Multi-subsystem scope decomposition prompts.
51
- - The "propose 2-3 approaches" prompt — user picks.
52
- - Anything not on the whitelist.
53
-
54
- ### Audit log
55
-
56
- For every auto-answered question, append a row to `docs/superpowers/specs/<slug>-auto-decisions.md`:
57
-
58
- ```markdown
59
- | <UTC time> | spec | <question verbatim> | <category> | <signal source> | <answer> |
60
- ```
61
-
62
- Create the file with this header on first write:
63
-
64
- ```markdown
65
- # Auto-power auto-decisions — <slug>
66
-
67
- | When (UTC) | Phase | Question | Category | Signal | Answer |
68
- |---|---|---|---|---|---|
69
- ```
70
-
71
- ### Spec approval gate
72
-
73
- After brainstorming finishes and the spec doc is written + self-reviewed, surface the standard message:
74
-
75
- > "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before I continue with the rest of the pipeline."
76
-
77
- Wait for the user's reply. Revise on request, otherwise advance to phase 2. **This is the only owner touchpoint by design.**
78
-
79
- ## §2. Checkpoint
80
-
81
- Create the checkpoint at pipeline start. See `assets/CHECKPOINT_SCHEMA.md` for the schema and write triggers. Hard rules:
82
-
83
- - Always bump `updated_at` on every write.
84
- - Never advance `phase` without writing first.
85
- - On every retry, increment `retries.<phase>` and write.
86
- - On phase advance, reset that phase's retry counter to 0.
87
- - On successful merge, set `status: done` and write a final time.
88
-
89
- ## §3. Arch + sec self-review (phase 3)
90
-
91
- Run this inline against the plan from phase 2. Treat each as ✅ / ⚠️ / ❌. Any ❌ ⇒ escalate with signal `ARCH_BLOCKED` or `SEC_BLOCKED`.
92
-
93
- ### Architecture checklist
94
-
95
- - Single-responsibility per file? Any file expected > ~300 lines?
96
- - Module boundaries match plan task scope?
97
- - New code touches files only inside scopes declared by plan tasks?
98
- - Dependencies on external services declared?
99
- - Failure modes documented (timeouts, partial writes, retries)?
100
- - Backward compatibility considered if modifying public interfaces?
101
-
102
- ### Security checklist (project-aware — skip items that don't apply)
103
-
104
- - Input validation on user-supplied data?
105
- - No secrets / tokens committed?
106
- - SQL strings parameterized (if any SQL)?
107
- - HTML output escaped (if rendering HTML)?
108
- - AuthN/AuthZ enforced on new endpoints (if any endpoints)?
109
- - File I/O paths sanitized (no `../` traversal)?
110
- - Shell exec uses argv form, not string concat (if any shell-out)?
111
-
112
- Append the result table to the plan file under a `## Auto-power arch+sec review` heading.
113
-
114
- ## §4. Worktree detection (phase 4)
115
-
116
- ```
117
- top=$(git rev-parse --show-toplevel)
118
- main_top=$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')
119
- ```
120
-
121
- - `$top == $main_top` ⇒ running in main repo. Invoke `superpowers:using-git-worktrees` to create `../<repo>-<slug>/` on branch `auto-power/<slug>`. Set `worktree_path` and `worktree_created_by_us: true`.
122
- - `$top != $main_top` ⇒ already in a worktree. Skip creation. Use the current branch. Set `worktree_path = $top` and `worktree_created_by_us: false`.
123
- - Flag overrides: `--no-worktree` forces in-place work on the current branch; `--worktree` forces creation even if already inside one.
124
-
125
- ## §5. Mid-impl auto-approve (phase 5)
126
-
127
- When `superpowers:subagent-driven-development` or `superpowers:executing-plans` surfaces a touchpoint, decide per the table below. Log every auto-decision to the auto-decisions file:
128
-
129
- ```markdown
130
- | <UTC time> | impl | <touchpoint> | auto-approve | <reason> |
131
- ```
132
-
133
- | Touchpoint | Auto-decision |
134
- |---|---|
135
- | "Continue to next task?" | yes |
136
- | "Code review checkpoint?" | run self-review pass; treat findings per §6 |
137
- | "Run tests now?" | yes |
138
- | "Commit this work?" | yes (per-task commit) |
139
- | Force push | escalate (`FINISH_BLOCKED` / refuse) |
140
- | Branch delete on dirty tree | escalate |
141
- | `git reset --hard` | escalate |
142
- | Any history rewrite (`rebase -i`, `commit --amend` to pushed history) | escalate |
143
- | File deletion outside declared task scope | escalate |
144
-
145
- ## §6. Retry + escalation policy
146
-
147
- ### Transient (auto-retry, up to `limits.max_retries`, default 3)
148
-
149
- - Test failures with a clear stack trace ⇒ apply fix indicated by the error, re-run.
150
- - Lint / format errors ⇒ auto-fix, re-run.
151
- - CI flake (timeout, 5xx) ⇒ re-trigger.
152
- - Simple merge conflicts (whitespace, import order, non-semantic) ⇒ auto-resolve, re-run.
153
-
154
- Increment `retries.<phase>` on every retry. Write the checkpoint.
155
-
156
- ### Substantive (escalate, no retry)
157
-
158
- | Trigger | Signal |
159
- |---|---|
160
- | Security self-review ❌ | `SEC_BLOCKED` |
161
- | Architecture self-review ❌ | `ARCH_BLOCKED` |
162
- | QA fail still red after `max_retries` | `QA_FAIL_EXHAUSTED` |
163
- | Semantic merge conflict | `SEMANTIC_CONFLICT` |
164
- | CI red after `max_retries` same signature | `CI_RED_PERSISTENT` |
165
- | Non-ff merge required | `FINISH_BLOCKED` |
166
- | Push rejected | `FINISH_BLOCKED` |
167
- | Dirty worktree at finish | `FINISH_BLOCKED` |
168
- | Test suite missing | `TEST_SUITE_MISSING` |
169
- | Plan task references missing file | `PLAN_FILE_MISSING` |
170
-
171
- ### Escalation procedure
172
-
173
- 1. Set `status: blocked`, `last_error`, and write checkpoint.
174
- 2. Render `assets/ESCALATION_TEMPLATE.md` into `docs/superpowers/specs/<slug>-ESCALATION.md` with the fields filled in.
175
- 3. Print one line to stdout: `BLOCKED <signal>: see docs/superpowers/specs/<slug>-ESCALATION.md`.
176
- 4. Exit. The pipeline does not continue without `/auto-power-resume <slug> --cleared`.
177
-
178
- ## §7. Finish (phase 8)
179
-
180
- Pre-merge: poll CI for the branch up to `limits.ci_wait_minutes` (default 30) using `gh pr checks <branch>` or `gh run list --branch <branch> --limit 1 --json status,conclusion`. Green ⇒ merge. Red ⇒ retry policy.
181
-
182
- Merge sequence:
183
-
184
- ```bash
185
- git checkout main
186
- git pull --ff-only origin main
187
- git merge --ff-only <branch>
188
- git push origin main
189
- git branch -d <branch>
190
- ```
191
-
192
- If `worktree_created_by_us == true`:
193
-
194
- ```bash
195
- git worktree remove <worktree-path>
196
- ```
197
-
198
- Never remove a worktree where `worktree_created_by_us == false`.
199
-
200
- Any failure in the above ⇒ `FINISH_BLOCKED`.
201
-
202
- On success: set `status: done`, write checkpoint a final time, print:
203
-
204
- ```
205
- DONE <slug>: merged to main, branch <branch> deleted[, worktree <path> removed]
206
- ```
207
-
208
- ## §8. Resume semantics
209
-
210
- When invoked via `/auto-power-resume`:
211
-
212
- 1. Load `docs/superpowers/specs/<slug>-checkpoint.json` (or the explicit path argument).
213
- 2. Verify the recorded `branch` exists and (if `worktree_path` set) the path exists.
214
- 3. Reject if HEAD has uncommitted churn outside files the pipeline itself wrote.
215
- 4. `status: done` ⇒ no-op, print summary, exit.
216
- 5. `status: blocked` and `--cleared` flag absent ⇒ re-print the escalation summary, exit.
217
- 6. `status: blocked` and `--cleared` flag present ⇒ clear `last_error`, set `status: running`, re-enter the recorded `phase` with retry counters preserved.
218
- 7. `status: running` (e.g. session was killed) ⇒ re-enter the recorded `phase` with retry counters preserved.
219
-
220
- Never resume into a different branch than the one recorded in the checkpoint.
@@ -1,21 +0,0 @@
1
- {
2
- "name": "team-superpower",
3
- "displayName": "Team Superpower",
4
- "version": "0.0.25",
5
- "description": "Shape-adaptive coordination layer that runs the obra/superpowers skill chain across a Claude Code agent team — one /team-feature command takes an idea through design, plan, pre-impl architecture+security gate, BE/FE implementation, QA gate, code review, CI gate, and finish with at most 3 owner touchpoints. Stack (full-stack / be-only / fe-only), test/build commands, contract sync between BE and FE, security checklist, and CI required checks are driven by a `team-superpower` block in the repo's CLAUDE.md.",
6
- "author": {
7
- "name": "Steven Hoang"
8
- },
9
- "keywords": [
10
- "agent-teams",
11
- "superpowers",
12
- "tdd",
13
- "orchestration",
14
- "workflow",
15
- "brainstorming",
16
- "code-review",
17
- "architecture",
18
- "security",
19
- "qa"
20
- ]
21
- }
@@ -1,294 +0,0 @@
1
- # team-superpower
2
-
3
- Coordination layer that runs the [obra/superpowers](https://github.com/obra/superpowers)
4
- skill chain on top of **Claude Code Agent Teams**. One `/team-feature` command
5
- takes an idea through analysis → planning → implementation → end-of-plan QC →
6
- finish, with at most **3 owner touchpoints**.
7
-
8
- This plugin is *not* a fork of Superpowers. It consumes Superpowers skills
9
- as-installed and adds the orchestration: who runs which skill, when, and how
10
- teammates talk without bothering the owner.
11
-
12
- ## Overview (v6)
13
-
14
- team-superpower runs **one Agent Teams team** per feature across all phases.
15
- The main session is the sole spawner; a coordinating teammate (team-leader)
16
- requests spawns via `SPAWN_REQUEST`.
17
-
18
- **Modes:**
19
-
20
- - **Solo** (1 touchpoint, no team) — bug fixes, typos, single-file changes.
21
- - **Single-agent** (1 touchpoint, 1 team) — small enhancements.
22
- - **Team** (2 phase-A touchpoints + 1 phase-H finish touchpoint, 1 team
23
- across phases A–H) — full features.
24
-
25
- **Pipeline (team mode):**
26
- Phase A (solution-architect + feature-planner [+ security-engineer]) →
27
- handover → Phases B–F (team-leader + implementers, per-plan-phase wave
28
- dispatch + phase-end SOLID/DRY review) → Phase G (qc-engineer, end-of-plan
29
- QC, max 3 rounds) → Phase H (lead push + finish-branch decision + cleanup).
30
-
31
- **Restart-on-stuck:** mid-implementation architectural questions trigger a
32
- full cycle restart (max 2). No architect standby — phase-A roles shut down
33
- at handover.
34
-
35
- See `docs/superpowers/team-superpower-v5-spec.md` for the canonical spec,
36
- `docs/superpowers/agent-team-flows-v5.md` for diagrams, and
37
- `docs/superpowers/agent-team-checklist.md` for acceptance criteria.
38
-
39
- ## Project-aware via CLAUDE.md
40
-
41
- The plugin reads a `team-superpower` YAML block from your repo-root `CLAUDE.md`
42
- to drive every stack decision: BE-only repos do not spawn a frontend
43
- teammate, FE-only repos do not spawn a backend teammate, full-stack repos
44
- get both plus a contract-publish gate. Test/build/lint/typecheck/format
45
- commands come from `CLAUDE.md` — no hard-coded toolchain. The
46
- security-engineer is only spawned when `security.domain ∈
47
- {payments, healthcare}` or `security.pii: yes`. See
48
- `assets/CLAUDE.md.template` for the schema.
49
-
50
- ## What you get
51
-
52
- - Two slash commands: `/team-feature` and `/team-cleanup`. There is **no
53
- separate resume command in v5** — `/team-feature` auto-detects in-progress
54
- features.
55
- - **Seven agent roles** (v6 — the main session itself runs the lifecycle),
56
- each with a tightly-scoped system prompt:
57
-
58
- ## Agents
59
-
60
- | Agent | Lifetime | Role |
61
- |---|---|---|
62
- | _main session_ (the `/team-feature` invocation itself) | Whole feature | Sole spawner; mode pick, TeamCreate, SPAWN_REQUEST + RESTART_REQUEST handler, cleanup + push. |
63
- | `solution-architect` | Phase A only | Spec + arch-map. |
64
- | `feature-planner` | Phase A only | Plan (plan-phase grouped, waves). |
65
- | `security-engineer` | Phase A only (regulated domains only) | Regulatory + threat-model review. |
66
- | `team-leader` | Phases B–F | Coordinator; composes spawn briefs; runs phase-end SOLID/DRY/domain review. |
67
- | `backend-developer` / `frontend-developer` | Per wave | TDD implementation, static-check log capture, commit. |
68
- | `qc-engineer` | Phase G only | End-of-plan 5-step QC; rework dispatch if blocking. |
69
-
70
- - **Three guardrail hooks** (registered automatically via `hooks/hooks.json`):
71
- - `TeammateIdle` — role-aware idle routing (refuses idle when the role's
72
- outstanding obligation is open).
73
- - `TaskCreated` — enforces `impl:` / `review:` / `meta:` / `block:` task
74
- title prefixes, v5 wave shape, and shape-marker scope.
75
- - `TaskCompleted` — gates `impl:` completions on the static-check log
76
- (`.team-superpower/static-check-<task-id>.log`) and rework-reference
77
- (`Reworks: <orig-id>` for `impl:rework-*`).
78
- - `scripts/team-state.sh` — inspection + cleanup helper; new `members <slug>`
79
- subcommand lists role / id / status per teammate.
80
- - Robustness primitives baked into the workflow:
81
- - **Preflight scan** in `/team-feature` — detects orphaned team config and
82
- in-flight runs before doing anything destructive.
83
- - **Auto-resume** in `/team-feature` — detects in-progress handovers
84
- without a matching qc-report and offers to continue.
85
- - **Phase-end leader review** — team-leader scans every plan-phase's diff
86
- against the arch-map for SOLID/DRY/domain violations and dispatches
87
- `impl:rework-*` tasks.
88
- - **End-of-plan QC** — qc-engineer runs once after `PLAN_COMPLETE`; up to 3
89
- rework rounds.
90
- - **Heartbeat file** at `docs/superpowers/sessions/<slug>.heartbeat` —
91
- touched at every phase boundary; cleanup refuses to wipe state while the
92
- heartbeat is fresh.
93
- - **Automatic cleanup after `FINISH_DONE`** — the main session verifies all
94
- phases complete, all commits in place, teammates idle, then runs the
95
- canonical "clean up the team" primitive followed by a verification scan.
96
- - **`/team-cleanup [slug]`** for the case where a previous main session crashed.
97
- - Templates seeded into your project on first use:
98
- `docs/superpowers/ESCALATION.md` (template + three worked examples),
99
- `docs/superpowers/README.md` (onboarding + troubleshooting), and
100
- `docs/superpowers/handovers/README.md` (handover artefact contract).
101
-
102
- ## Phase chain at a glance
103
-
104
- | Phase | Role(s) | Output | Gate? |
105
- |---|---|---|---|
106
- | A — Analysis | `solution-architect` + `feature-planner` [+ `security-engineer`] | Spec, arch-map, plan, handover | Spec sign-off + plan approval (2 touchpoints) |
107
- | B–F — Implementation (one per plan-phase) | `team-leader` + `backend-developer` / `frontend-developer` | TDD commits per wave + phase-end leader review | `PHASE_COMPLETE` per plan-phase |
108
- | G — End-of-plan QC | `qc-engineer` | `<date>-<slug>-qc-report.md` | `QC_PASS` (max 3 rework rounds) |
109
- | H — Finish | _main session_ | Push + merge/PR/keep/discard | Owner decision (finish touchpoint) |
110
-
111
- ## Requirements
112
-
113
- - Claude Code `2.1.32` or later.
114
- - `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your environment (the slash
115
- command halts if absent).
116
- - The Superpowers plugin installed:
117
- `/plugin install superpowers@claude-plugins-official`.
118
- - `jq` on `$PATH` (hooks degrade to log-only when missing, but you want them
119
- enforcing).
120
- - **Run the lead session on Opus.** Teammates are pinned via their agent
121
- frontmatter, so they always spawn on their pinned model. The lead carries
122
- the cross-phase reasoning load (gate decisions, SPAWN_REQUEST handling,
123
- RESTART_REQUEST approval, FINISH_BLOCKED recovery), so Opus is the right
124
- tier. The command performs a self-attestation check at preflight and halts
125
- if the lead reports it is running on Sonnet/Haiku.
126
-
127
- ## Install
128
-
129
- ```text
130
- /plugin marketplace add baoduy/agents-and-skills
131
- /plugin install team-superpower@drunkcoding
132
- ```
133
-
134
- Then make sure the agent-teams env flag is set in `~/.claude/settings.json`:
135
-
136
- ```json
137
- {
138
- "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
139
- "teammateMode": "in-process"
140
- }
141
- ```
142
-
143
- ## Use
144
-
145
- ```text
146
- /team-feature add a /healthcheck endpoint that returns 200 OK
147
- ```
148
-
149
- You will be interrupted at most three times in team mode:
150
-
151
- 1. Spec sign-off (mid phase A).
152
- 2. Plan approval (end phase A).
153
- 3. Finish-branch decision — merge / PR / keep / discard (phase H).
154
-
155
- Anything else that reaches you uses the escalation template in
156
- `docs/superpowers/ESCALATION.md`. If a teammate pings you without using the
157
- template, that's a bug — file it.
158
-
159
- ## Task prefix routing
160
-
161
- The planner assigns every `impl:` task one of these sub-prefixes; the lead
162
- routes by prefix:
163
-
164
- | Prefix | Routed to | Scope |
165
- |---|---|---|
166
- | `impl:be-*` | `backend-developer` | Server-side code, APIs, data, schemas, infra |
167
- | `impl:be-migration-*` | `backend-developer` | Schema migrations (serialised by hook) |
168
- | `impl:be-contract-publish-*` | `backend-developer` | Publishes contract; gates FE tasks |
169
- | `impl:fe-*` | `frontend-developer` | UI components, pages, client-side state, styles |
170
- | `impl:contract-update-*` | `backend-developer` | Contract drift fix (scope-neutral) |
171
- | `impl:rework-*` | inherits originating task's role | Phase-end leader review or QC rework |
172
-
173
- Wave metadata must be one of: `<plan-phase>.<wave>` (e.g. `1.1`),
174
- `<plan-phase>.rework`, or `qc-rework`.
175
-
176
- ## Resume after `/resume` drops the team
177
-
178
- Re-run `/team-feature` from the same worktree. The lead detects:
179
-
180
- 1. Existing `~/.claude/teams/superpower-<slug>/` directory.
181
- 2. In-progress feature artefacts (handover without matching qc-report).
182
- 3. Partial commits ahead of the base branch.
183
-
184
- …and presents a single resume prompt. On continue, completed phases are not
185
- redone.
186
-
187
- ## Clean up after a crashed lead
188
-
189
- ```text
190
- /team-cleanup <slug>
191
- /team-cleanup --all
192
- ```
193
-
194
- Use this when a previous lead died (terminal closed, `/resume` lost the team,
195
- OS killed the process) and left `~/.claude/teams/superpower-<slug>/` behind.
196
- Project-side artefacts under `docs/superpowers/{specs,plans,handovers,reviews}`
197
- are preserved; only platform-side state plus per-feature scratch
198
- (`.team-superpower/spawn-briefs/`, `.team-superpower/static-check-*.log`) is
199
- removed.
200
-
201
- The slash command dry-runs first, prints what would be removed, and asks for
202
- confirmation. The heartbeat file at
203
- `docs/superpowers/sessions/<slug>.heartbeat` is checked — if it was touched
204
- in the last 10 minutes, cleanup refuses unless the owner explicitly confirms
205
- with `--ignore-heartbeat` that the previous lead is dead.
206
-
207
- The helper script is also runnable directly:
208
-
209
- ```bash
210
- bash plugins/team-superpower/scripts/team-state.sh scan # list all teams
211
- bash plugins/team-superpower/scripts/team-state.sh scan <slug> # inspect one
212
- bash plugins/team-superpower/scripts/team-state.sh members <slug> # list role/id/status
213
- bash plugins/team-superpower/scripts/team-state.sh cleanup <slug> # dry-run
214
- bash plugins/team-superpower/scripts/team-state.sh cleanup <slug> --force # apply
215
- ```
216
-
217
- ## Layout
218
-
219
- ```
220
- plugins/team-superpower/
221
- ├── .claude-plugin/plugin.json
222
- ├── README.md
223
- ├── agents/
224
- │ ├── solution-architect.md
225
- │ ├── feature-planner.md
226
- │ ├── security-engineer.md
227
- │ ├── team-leader.md
228
- │ ├── backend-developer.md
229
- │ ├── frontend-developer.md
230
- │ └── qc-engineer.md
231
- ├── commands/
232
- │ ├── team-feature.md # v6 single-session lifecycle + auto-resume
233
- │ └── team-cleanup.md
234
- ├── hooks/
235
- │ ├── hooks.json
236
- │ ├── teammate-idle.sh # role-aware idle routing
237
- │ ├── task-created.sh # impl:/review:/meta:/block: + v5 wave shape
238
- │ └── task-completed.sh # static-check log + rework reference gate
239
- ├── scripts/
240
- │ ├── team-state.sh # inspection + cleanup helper + members subcommand
241
- │ ├── detect-stack.sh
242
- │ └── parse-claudemd.sh
243
- └── assets/
244
- ├── ESCALATION.md # seeded to docs/superpowers/ESCALATION.md on first run
245
- ├── SESSION_README.md # seeded to docs/superpowers/README.md on first run
246
- └── CLAUDE.md.template # copy to repo root if no CLAUDE.md exists
247
- ```
248
-
249
- ## Clarification routing
250
-
251
- Teammates resolve as many clarifications as possible without involving the
252
- owner. Every clarification is classified into one of three classes —
253
- `tactical`, `cross-role`, `architectural` — per `assets/ESCALATION.md`.
254
-
255
- - **Tactical** (naming, wording, thresholds in range) — decided by the
256
- originator and logged in the checkpoint's `## Assumptions` block. No
257
- SendMessage, no escalation.
258
- - **Cross-role** — to the relevant peer via SendMessage; consensus on first
259
- reply → log + proceed; no consensus → escalate citing attempts.
260
- - **Architectural** — implementers send `ESCALATE class=architectural` to
261
- team-leader. If team-leader cannot resolve from arch-map, team-leader posts
262
- `RESTART_REQUEST` to the main session (recovery touchpoint, not counted
263
- against the 3-budget).
264
-
265
- Per-role rubrics live in each agent file under `agents/<role>.md`.
266
-
267
- ## Design
268
-
269
- - The **lead** is a conductor. It never runs a Superpowers skill itself.
270
- - Teammates run **canonical, unmodified** Superpowers skills. They are
271
- forbidden from paraphrasing or replacing them.
272
- - TDD is enforced by `subagent-driven-development` +
273
- `test-driven-development` per implementer task. Static checks (lint +
274
- format + typecheck) are captured to a log and gated by the `TaskCompleted`
275
- hook.
276
- - **Phase-end leader review** + **end-of-plan QC** keep architectural drift
277
- in check without a per-task QA loop.
278
- - All cross-team chatter that needs an owner decision goes through the §7
279
- escalation template.
280
- - Every phase boundary writes a checkpoint to
281
- `docs/superpowers/sessions/<slug>.md`.
282
-
283
- ## Out of scope
284
-
285
- - Token-usage metrics per teammate per phase.
286
- - Per-role permission allowlists.
287
- - Standalone devops, technical-writer, or minimal-change-engineer roles —
288
- infra/CI folds into `backend-developer`; documentation lands in PR
289
- descriptions and inline; minimal-change patterns are scoped per task by
290
- the planner.
291
-
292
- ## License
293
-
294
- MIT.