@drunkcoding/agents-and-skills 0.0.24 → 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.
- package/.claude-plugin/marketplace.json +14 -33
- package/README.md +1 -0
- package/package.json +1 -1
- package/plugins/html-effectiveness/.claude-plugin/plugin.json +1 -1
- package/plugins/plugin-validator/.claude-plugin/plugin.json +1 -1
- package/plugins/team-share/.claude-plugin/plugin.json +17 -0
- package/plugins/team-share/README.md +30 -0
- package/plugins/team-share/agents/team-share.md +140 -0
- package/plugins/team-share/commands/team-share.md +4 -0
- package/plugins/tech-graph/.claude-plugin/plugin.json +1 -1
- package/plugins/auto-power/.claude-plugin/plugin.json +0 -17
- package/plugins/auto-power/README.md +0 -80
- package/plugins/auto-power/assets/CHECKPOINT_SCHEMA.md +0 -69
- package/plugins/auto-power/assets/ESCALATION_TEMPLATE.md +0 -67
- package/plugins/auto-power/commands/auto-power-resume.md +0 -32
- package/plugins/auto-power/commands/auto-power.md +0 -46
- package/plugins/auto-power/skills/auto-power-runtime/SKILL.md +0 -220
- package/plugins/team-superpower/.claude-plugin/plugin.json +0 -21
- package/plugins/team-superpower/README.md +0 -294
- package/plugins/team-superpower/agents/backend-developer.md +0 -221
- package/plugins/team-superpower/agents/feature-planner.md +0 -66
- package/plugins/team-superpower/agents/frontend-developer.md +0 -242
- package/plugins/team-superpower/agents/orchestrator.md +0 -83
- package/plugins/team-superpower/agents/qc-engineer.md +0 -84
- package/plugins/team-superpower/agents/security-engineer.md +0 -175
- package/plugins/team-superpower/agents/solution-architect.md +0 -80
- package/plugins/team-superpower/agents/team-leader.md +0 -100
- package/plugins/team-superpower/assets/AGENTS.md.template +0 -23
- package/plugins/team-superpower/assets/CLAUDE.md.template +0 -117
- package/plugins/team-superpower/assets/ESCALATION.md +0 -142
- package/plugins/team-superpower/assets/SESSION_README.md +0 -338
- package/plugins/team-superpower/commands/team-cleanup.md +0 -70
- package/plugins/team-superpower/commands/team-feature.md +0 -317
- package/plugins/team-superpower/hooks/hooks.json +0 -25
- package/plugins/team-superpower/hooks/task-completed.sh +0 -254
- package/plugins/team-superpower/hooks/task-created.sh +0 -174
- package/plugins/team-superpower/hooks/teammate-idle.sh +0 -149
- package/plugins/team-superpower/scripts/assess-complexity.sh +0 -194
- package/plugins/team-superpower/scripts/detect-stack.sh +0 -473
- package/plugins/team-superpower/scripts/parse-claudemd.sh +0 -194
- package/plugins/team-superpower/scripts/team-state.sh +0 -313
- 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.24",
|
|
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 (v5)
|
|
13
|
-
|
|
14
|
-
team-superpower runs **one Agent Teams team** per feature across all phases.
|
|
15
|
-
The lead (orchestrator) is the sole spawner; a coordinating teammate
|
|
16
|
-
(team-leader) 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
|
-
- **Eight agent roles**, each with a tightly-scoped system prompt:
|
|
56
|
-
|
|
57
|
-
## Agents
|
|
58
|
-
|
|
59
|
-
| Agent | Lifetime | Role |
|
|
60
|
-
|---|---|---|
|
|
61
|
-
| `orchestrator` | Whole feature | Lead session; sole spawner; SPAWN_REQUEST + RESTART_REQUEST handler; cleanup + push. |
|
|
62
|
-
| `solution-architect` | Phase A only | Spec + arch-map. |
|
|
63
|
-
| `feature-planner` | Phase A only | Plan (plan-phase grouped, waves). |
|
|
64
|
-
| `security-engineer` | Phase A only (regulated domains only) | Regulatory + threat-model review. |
|
|
65
|
-
| `team-leader` | Phases B–F | Coordinator; composes spawn briefs; runs phase-end SOLID/DRY/domain review. |
|
|
66
|
-
| `backend-developer` / `frontend-developer` | Per wave | TDD implementation, static-check log capture, commit. |
|
|
67
|
-
| `qc-engineer` | Phase G only | End-of-plan 5-step QC; rework dispatch if blocking. |
|
|
68
|
-
|
|
69
|
-
- **Three guardrail hooks** (registered automatically via `hooks/hooks.json`):
|
|
70
|
-
- `TeammateIdle` — role-aware idle routing (refuses idle when the role's
|
|
71
|
-
outstanding obligation is open).
|
|
72
|
-
- `TaskCreated` — enforces `impl:` / `review:` / `meta:` / `block:` task
|
|
73
|
-
title prefixes, v5 wave shape, and shape-marker scope.
|
|
74
|
-
- `TaskCompleted` — gates `impl:` completions on the static-check log
|
|
75
|
-
(`.team-superpower/static-check-<task-id>.log`) and rework-reference
|
|
76
|
-
(`Reworks: <orig-id>` for `impl:rework-*`).
|
|
77
|
-
- `scripts/team-state.sh` — inspection + cleanup helper; new `members <slug>`
|
|
78
|
-
subcommand lists role / id / status per teammate.
|
|
79
|
-
- Robustness primitives baked into the workflow:
|
|
80
|
-
- **Preflight scan** in `/team-feature` — detects orphaned team config and
|
|
81
|
-
in-flight runs before doing anything destructive.
|
|
82
|
-
- **Auto-resume** in `/team-feature` — detects in-progress handovers
|
|
83
|
-
without a matching qc-report and offers to continue.
|
|
84
|
-
- **Phase-end leader review** — team-leader scans every plan-phase's diff
|
|
85
|
-
against the arch-map for SOLID/DRY/domain violations and dispatches
|
|
86
|
-
`impl:rework-*` tasks.
|
|
87
|
-
- **End-of-plan QC** — qc-engineer runs once after `PLAN_COMPLETE`; up to 3
|
|
88
|
-
rework rounds.
|
|
89
|
-
- **Heartbeat file** at `docs/superpowers/sessions/<slug>.heartbeat` —
|
|
90
|
-
touched at every phase boundary; cleanup refuses to wipe state while the
|
|
91
|
-
heartbeat is fresh.
|
|
92
|
-
- **Automatic cleanup after `FINISH_DONE`** — the lead verifies all phases
|
|
93
|
-
complete, all commits in place, teammates idle, then runs the canonical
|
|
94
|
-
"clean up the team" primitive followed by a verification scan.
|
|
95
|
-
- **`/team-cleanup [slug]`** for the case where a previous lead crashed.
|
|
96
|
-
- Templates seeded into your project on first use:
|
|
97
|
-
`docs/superpowers/ESCALATION.md` (template + three worked examples),
|
|
98
|
-
`docs/superpowers/README.md` (onboarding + troubleshooting), and
|
|
99
|
-
`docs/superpowers/handovers/README.md` (handover artefact contract).
|
|
100
|
-
|
|
101
|
-
## Phase chain at a glance
|
|
102
|
-
|
|
103
|
-
| Phase | Role(s) | Output | Gate? |
|
|
104
|
-
|---|---|---|---|
|
|
105
|
-
| A — Analysis | `solution-architect` + `feature-planner` [+ `security-engineer`] | Spec, arch-map, plan, handover | Spec sign-off + plan approval (2 touchpoints) |
|
|
106
|
-
| 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 |
|
|
107
|
-
| G — End-of-plan QC | `qc-engineer` | `<date>-<slug>-qc-report.md` | `QC_PASS` (max 3 rework rounds) |
|
|
108
|
-
| H — Finish | `orchestrator` | Push + merge/PR/keep/discard | Owner decision (finish touchpoint) |
|
|
109
|
-
|
|
110
|
-
## Requirements
|
|
111
|
-
|
|
112
|
-
- Claude Code `2.1.32` or later.
|
|
113
|
-
- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your environment (the slash
|
|
114
|
-
command halts if absent).
|
|
115
|
-
- The Superpowers plugin installed:
|
|
116
|
-
`/plugin install superpowers@claude-plugins-official`.
|
|
117
|
-
- `jq` on `$PATH` (hooks degrade to log-only when missing, but you want them
|
|
118
|
-
enforcing).
|
|
119
|
-
- **Run the lead session on Opus.** Teammates are pinned via their agent
|
|
120
|
-
frontmatter, so they always spawn on their pinned model. The lead carries
|
|
121
|
-
the cross-phase reasoning load (gate decisions, SPAWN_REQUEST handling,
|
|
122
|
-
RESTART_REQUEST approval, FINISH_BLOCKED recovery), so Opus is the right
|
|
123
|
-
tier. The command performs a self-attestation check at preflight and halts
|
|
124
|
-
if the lead reports it is running on Sonnet/Haiku.
|
|
125
|
-
|
|
126
|
-
## Install
|
|
127
|
-
|
|
128
|
-
```text
|
|
129
|
-
/plugin marketplace add baoduy/agents-and-skills
|
|
130
|
-
/plugin install team-superpower@drunkcoding
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Then make sure the agent-teams env flag is set in `~/.claude/settings.json`:
|
|
134
|
-
|
|
135
|
-
```json
|
|
136
|
-
{
|
|
137
|
-
"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
|
|
138
|
-
"teammateMode": "in-process"
|
|
139
|
-
}
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
## Use
|
|
143
|
-
|
|
144
|
-
```text
|
|
145
|
-
/team-feature add a /healthcheck endpoint that returns 200 OK
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
You will be interrupted at most three times in team mode:
|
|
149
|
-
|
|
150
|
-
1. Spec sign-off (mid phase A).
|
|
151
|
-
2. Plan approval (end phase A).
|
|
152
|
-
3. Finish-branch decision — merge / PR / keep / discard (phase H).
|
|
153
|
-
|
|
154
|
-
Anything else that reaches you uses the escalation template in
|
|
155
|
-
`docs/superpowers/ESCALATION.md`. If a teammate pings you without using the
|
|
156
|
-
template, that's a bug — file it.
|
|
157
|
-
|
|
158
|
-
## Task prefix routing
|
|
159
|
-
|
|
160
|
-
The planner assigns every `impl:` task one of these sub-prefixes; the lead
|
|
161
|
-
routes by prefix:
|
|
162
|
-
|
|
163
|
-
| Prefix | Routed to | Scope |
|
|
164
|
-
|---|---|---|
|
|
165
|
-
| `impl:be-*` | `backend-developer` | Server-side code, APIs, data, schemas, infra |
|
|
166
|
-
| `impl:be-migration-*` | `backend-developer` | Schema migrations (serialised by hook) |
|
|
167
|
-
| `impl:be-contract-publish-*` | `backend-developer` | Publishes contract; gates FE tasks |
|
|
168
|
-
| `impl:fe-*` | `frontend-developer` | UI components, pages, client-side state, styles |
|
|
169
|
-
| `impl:contract-update-*` | `backend-developer` | Contract drift fix (scope-neutral) |
|
|
170
|
-
| `impl:rework-*` | inherits originating task's role | Phase-end leader review or QC rework |
|
|
171
|
-
|
|
172
|
-
Wave metadata must be one of: `<plan-phase>.<wave>` (e.g. `1.1`),
|
|
173
|
-
`<plan-phase>.rework`, or `qc-rework`.
|
|
174
|
-
|
|
175
|
-
## Resume after `/resume` drops the team
|
|
176
|
-
|
|
177
|
-
Re-run `/team-feature` from the same worktree. The lead detects:
|
|
178
|
-
|
|
179
|
-
1. Existing `~/.claude/teams/superpower-<slug>/` directory.
|
|
180
|
-
2. In-progress feature artefacts (handover without matching qc-report).
|
|
181
|
-
3. Partial commits ahead of the base branch.
|
|
182
|
-
|
|
183
|
-
…and presents a single resume prompt. On continue, completed phases are not
|
|
184
|
-
redone.
|
|
185
|
-
|
|
186
|
-
## Clean up after a crashed lead
|
|
187
|
-
|
|
188
|
-
```text
|
|
189
|
-
/team-cleanup <slug>
|
|
190
|
-
/team-cleanup --all
|
|
191
|
-
```
|
|
192
|
-
|
|
193
|
-
Use this when a previous lead died (terminal closed, `/resume` lost the team,
|
|
194
|
-
OS killed the process) and left `~/.claude/teams/superpower-<slug>/` behind.
|
|
195
|
-
Project-side artefacts under `docs/superpowers/{specs,plans,handovers,reviews}`
|
|
196
|
-
are preserved; only platform-side state plus per-feature scratch
|
|
197
|
-
(`.team-superpower/spawn-briefs/`, `.team-superpower/static-check-*.log`) is
|
|
198
|
-
removed.
|
|
199
|
-
|
|
200
|
-
The slash command dry-runs first, prints what would be removed, and asks for
|
|
201
|
-
confirmation. The heartbeat file at
|
|
202
|
-
`docs/superpowers/sessions/<slug>.heartbeat` is checked — if it was touched
|
|
203
|
-
in the last 10 minutes, cleanup refuses unless the owner explicitly confirms
|
|
204
|
-
with `--ignore-heartbeat` that the previous lead is dead.
|
|
205
|
-
|
|
206
|
-
The helper script is also runnable directly:
|
|
207
|
-
|
|
208
|
-
```bash
|
|
209
|
-
bash plugins/team-superpower/scripts/team-state.sh scan # list all teams
|
|
210
|
-
bash plugins/team-superpower/scripts/team-state.sh scan <slug> # inspect one
|
|
211
|
-
bash plugins/team-superpower/scripts/team-state.sh members <slug> # list role/id/status
|
|
212
|
-
bash plugins/team-superpower/scripts/team-state.sh cleanup <slug> # dry-run
|
|
213
|
-
bash plugins/team-superpower/scripts/team-state.sh cleanup <slug> --force # apply
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
## Layout
|
|
217
|
-
|
|
218
|
-
```
|
|
219
|
-
plugins/team-superpower/
|
|
220
|
-
├── .claude-plugin/plugin.json
|
|
221
|
-
├── README.md
|
|
222
|
-
├── agents/
|
|
223
|
-
│ ├── orchestrator.md
|
|
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 # v5 single-team 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 orchestrator (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.
|