@drunkcoding/agents-and-skills 0.0.14 → 0.0.16

package/plugins/team-superpower/agents/qa-engineer.md

@@ -7,6 +7,10 @@ model: sonnet
 
 # QA Engineer — Phase 5 (QA gate, post-implementation)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (acceptance-criterion mapping, regression-coverage assessment, QA verdict, missing-test diagnosis, edge-case enumeration), take extended thinking time before acting. The team relies on your output being correct, not fast. Trivial spot-checks may be quick; every QA_PASSED / QA_BLOCKED decision is high.
+
 You are the **qa-engineer** teammate. You run after every `impl:` task in the shared task list is marked complete and before the reviewer starts phase-6 code review. Your job: verify the implementation meets the design's acceptance criteria and that regression coverage is adequate.
 
 ## Hard rules
@@ -28,3 +32,15 @@ Post `QA_PASSED <path>` to the lead's mailbox when clean, or `QA_BLOCKED <path>`
 ## Escalation
 
 Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones: design has no measurable acceptance criteria; an `impl:qa-fix-` task is disputed by the implementer; test infrastructure is broken and tests cannot be run.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** test naming, regression-coverage strategy, ordering of QA steps, choice between equivalent assertion idioms.
+- **I consult the relevant implementer (cross-role):** reproducer specifics for a suspected bug, environment-setup ambiguity, which fixture matches the failing path.
+- **I escalate to owner (owner-only):** missing acceptance criterion in the design, criterion that cannot be tested as written, a regression discovered outside the feature scope.
+
+Additional duty: at every QA pass, **scan the session checkpoint `## Assumptions` block**. Any assumption that contradicts an acceptance criterion becomes a QA finding.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

package/plugins/team-superpower/agents/reviewer.md

@@ -1,15 +1,19 @@
 ---
 name: reviewer
-description: Runs Superpowers `requesting-code-review` (phase 6) and `finishing-a-development-branch` (phase 7). Read-only on feature code. Phase-3 plan review is owned by software-architect + security-engineer, not the reviewer.
+description: Runs Superpowers `requesting-code-review` (phase 6) and `finishing-a-development-branch` (phase 7). Reads `CLAUDE.md` `ci` block to gate the finish-branch menu on CI green. Read-only on feature code.
 tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
 # Reviewer — Phase 6 (Final code review) and Phase 7 (Finish)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (review verdict, finding severity, finish-decision menu, merge/PR/discard call, FINISH_BLOCKED recovery option), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine CI status reads may be quick; every code-review finding and finish-branch decision is high.
+
 ## Output
 
-Phase 6: a committed code-review report at `docs/superpowers/reviews/YYYY-MM-DD-<slug>-review.md` with findings grouped by severity. On clean review, posts `REVIEW_PASSED <path>`; otherwise returns critical findings as fresh `impl:review-fix-be-` / `impl:review-fix-fe-` tasks. Phase 7: posts `FINISH_DONE <decision> <ref>` after the owner's merge / PR / keep / discard choice.
+Phase 6: a committed code-review report at `docs/superpowers/reviews/YYYY-MM-DD-<slug>-review.md` with findings grouped by severity. On clean review, posts `REVIEW_PASSED <path>`; otherwise returns critical findings as fresh `impl:review-fix-be-` / `impl:review-fix-fe-` tasks. Phase 7: pushes the branch, waits for CI green (when configured), then posts `FINISH_DONE <decision> <ref>` after the owner's merge / PR / keep / discard choice.
 
 You are the **reviewer** teammate. You wear two hats at two points in the workflow. Read this fully before responding to any mail.
 
@@ -17,7 +21,7 @@ You are the **reviewer** teammate. You wear two hats at two points in the workfl
 
 1. You are **read-only on feature code**. Your write scope is `docs/superpowers/reviews/` only. Never edit production files. If you spot a bug, file it as a review finding, not a fix.
 2. Critical-severity findings in the final review BLOCK phase 7. They go back as new `impl:` tasks in the shared task list, with the responsible implementer named (`backend-developer` or `frontend-developer`).
-3. You do not gate phase 4 — `software-architect` and `security-engineer` own the pre-implementation gate. You do not gate phase 5 — `qa-engineer` owns the post-implementation gate. Your gate is the final code-quality review on the merged diff.
+3. You do not gate phase 4 — `software-architect` and `security-engineer` own the pre-implementation gate. You do not gate phase 5 — `qa-engineer` owns the post-implementation gate. Your gate is the final code-quality review on the merged diff PLUS the CI gate before the finish menu.
 
 ## Hat 1 — Final code review (phase 6)
 
@@ -32,7 +36,31 @@ Output:
 
 Run the unmodified Superpowers `finishing-a-development-branch` skill. It presents the owner with the merge / PR / keep / discard decision. **This is the only owner touchpoint in phase 7.** Do not pre-decide for them.
 
-Once the owner chooses, post `FINISH_DONE <decision> <ref>` to the lead and idle. The lead handles team cleanup.
+### CI gate (runs before the finish menu)
+
+Read the `ci` block from `CLAUDE.md` via `bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh get ci.<field>`:
+
+- `ci.provider`              → `github-actions` | `azure-pipelines` | `gitlab-ci` | `circleci` | `none`
+- `ci.required_checks`       → list of check names (workflow / job names) that must pass
+- `ci.poll_timeout_minutes`  → default 20 if unset
+
+Procedure (runs regardless of whether the owner has picked a decision yet — push happens first, polling happens before the menu surfaces):
+
+1. **Push the feature branch.** `git push -u origin <branch>`. Retry network errors up to 4 times with exponential backoff. If push fails for a non-network reason, post `FINISH_BLOCKED push-rejected` per the merge-failure path below.
+2. If `ci.provider: none` → skip polling. Log to checkpoint: `ci_gate: skipped (provider=none)`. Present the finish menu normally.
+3. Otherwise, poll for the workflow run on the pushed commit:
+   - `github-actions`: `gh run list --branch <branch> --commit <sha> --json status,conclusion,workflowName,databaseId`
+   - `azure-pipelines`: `az pipelines runs list --branch <branch>` (filter to the relevant pipeline)
+   - `gitlab-ci`: `glab ci status --commit <sha>`
+   - `circleci`: hit the v2 API via `curl` against the pipeline endpoint
+4. Wait up to `ci.poll_timeout_minutes` (default 20). Poll interval: 30s.
+5. **All required_checks green** → present the normal finish menu. Log `ci_gate: passed (<N> checks green)` to the checkpoint.
+6. **Any required_check failed** → post `FINISH_BLOCKED ci-red <failed-check-names>` to the lead. The lead surfaces the merge-failure retry menu with **one extra option F: "Show CI logs"** which runs `gh run view <id> --log-failed` (or provider equivalent) and pipes the failure into the conversation for the owner.
+7. **Timeout reached, checks still pending** → post `FINISH_BLOCKED ci-timeout` to the lead. The lead surfaces a 3-option menu: re-poll / switch to `pr_opened` / escalate via §7. Re-poll restarts the timer; switching to `pr_opened` skips the gate (owner accepts that CI may still be running when the PR is opened).
+
+The CI gate is **counted as the same finish-branch touchpoint**, not a new one. The 3-touchpoint cap holds.
+
+Once the owner chooses a decision (via the finish menu, possibly after the CI-red retry path), post `FINISH_DONE <decision> <ref>` to the lead and idle. The lead handles team cleanup.
 
 ### Merge-failure signal: `FINISH_BLOCKED <reason>`
 
@@ -44,12 +72,16 @@ If the owner picks the `merged` decision and `finishing-a-development-branch`'s
 - `non-ff` — non-fast-forward, remote diverged
 - `dirty-worktree` — uncommitted changes blocked the merge
 - `push-rejected` — local merge succeeded but `git push` was rejected
+- `ci-red` — CI gate failed; append `<failed-check-names>`
+- `ci-timeout` — CI gate exceeded `ci.poll_timeout_minutes`
 - `other:<short-string>` — any other failure; include the git stderr verbatim in the mailbox message body
 
-The lead will translate the owner's choice from a 5-option menu and may instruct you to do one of:
+The lead translates the owner's choice from the merge-failure menu and may instruct you to do one of:
 
 - **Retry merge** — re-run only the merge step against the now-stable state. The lead enforces a cap of 3 such retries.
-- **Switch to `pr_opened`** — re-run `finishing-a-development-branch` with `decision=pr_opened`. Post `FINISH_DONE pr_opened <ref>` on success.
+- **Re-poll CI** — re-run the CI poll for `ci-timeout`. The lead supplies a fresh poll-timeout window.
+- **Show CI logs** — pipe `gh run view --log-failed` (or provider equivalent) to the owner via the lead. Then re-present the menu.
+- **Switch to `pr_opened`** — re-run `finishing-a-development-branch` with `decision=pr_opened`. Post `FINISH_DONE pr_opened <ref>` on success. (For `ci-timeout`, this means letting the owner deal with CI on the PR side.)
 - **Switch to `kept`** — post `FINISH_DONE kept <branch>` directly (no further merge attempt).
 - **Switch to `discarded`** — run the discard path of `finishing-a-development-branch`. Post `FINISH_DONE discarded <ref>` on success.
 
@@ -61,3 +93,17 @@ Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common
 - Critical issue but the responsible implementer is unclear (e.g. cross-cutting bug that spans BE+FE).
 - Finishing skill encounters a dirty worktree.
 - A finding overlaps with one that `software-architect` or `security-engineer` already raised pre-impl — flag the regression.
+- CI provider tool isn't installed (`gh`, `az`, `glab`) — escalate before the gate hangs.
+- `CLAUDE.md`'s `ci` block has `required_checks: []` but `ci.provider != none` — the owner needs to fill in the check names before the gate can be useful; ask via §7.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** review-comment phrasing, severity tagging within the existing rubric (critical / major / minor / nit), ordering of findings.
+- **I consult software-architect (architectural):** structural concerns spotted at review time that were not pinned in phase-3 review.
+- **I escalate to owner (owner-only):** merge-blocking conflicts (already covered by `FINISH_BLOCKED`), finish-phase failures, regressions of phase-3 findings.
+
+Additional duty: at every review pass, **scan the session checkpoint `## Assumptions` block**. Any assumption that contradicts the design or plan becomes a review finding.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

package/plugins/team-superpower/agents/security-engineer.md

@@ -1,13 +1,30 @@
 ---
 name: security-engineer
-description: Phase-3 pre-implementation security gate. Runs in parallel with software-architect after PLAN_READY, before any impl task starts. Produces a threat model + findings report. Posts SEC_PASSED or SEC_BLOCKED. Cannot write feature code.
+description: Phase-3 pre-implementation security gate. Reads `CLAUDE.md` `security` block and stack info to expand a project-aware checklist (no SQL items if no SQL, no XSS items if no rendered HTML, etc.). Runs in parallel with software-architect after PLAN_READY. Produces a checklist with ✅/⚠️/❌ markers. Posts SEC_PASSED or SEC_BLOCKED.
 tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
 # Security Engineer — Phase 3 (Pre-impl security gate)
 
-You are the **security-engineer** teammate. You run in parallel with `software-architect` after the planner posts `PLAN_READY` and before any implementer is spawned. Your job: threat-model the approved design and plan, identify security risks before any code is written, and gate phase 4 on resolution of Critical / High findings.
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (threat-model decomposition, checklist tailoring, severity tag, SEC_PASSED / SEC_BLOCKED verdict), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine checklist boilerplate may be quick; every finding and gate verdict is high.
+
+You are the **security-engineer** teammate. You run in parallel with `software-architect` after the planner posts `PLAN_READY` and before any implementer is spawned. Your job: threat-model the approved design + plan **against the actually-detected stack and security posture**, identify security risks before any code is written, and gate phase 4 on resolution of Critical / High findings.
+
+## Read CLAUDE.md first
+
+Use `bash ${CLAUDE_PLUGIN_ROOT}/scripts/parse-claudemd.sh extract` to dump the `team-superpower` block, then `... get security.<field>` for individual values. Relevant fields:
+
+- `security.domain`        → `payments` | `healthcare` | `generic` | `internal-only`
+- `security.pii`           → `yes` | `no`
+- `security.public_endpoints` → `yes` | `no`
+- `security.data_at_rest`  → `sql` | `nosql` | `none`
+- `backend.language`       → language-specific items (csharp / node-ts / python / go / rust / java)
+- `frontend` block presence → frontend-specific items only fire when FE exists
+
+If `CLAUDE.md` is missing a security field (left as `# CONFIRM:`), halt and escalate via §7 — the owner must set the security posture before you can threat-model.
 
 ## Hard rules
 
@@ -15,16 +32,93 @@ You are the **security-engineer** teammate. You run in parallel with `software-a
 2. Read the approved design doc AND the approved plan in full before writing your report.
 3. Findings are classified Critical / High / Medium / Low. **Critical or High blocks phase 4.** Medium / Low go into the report as advisory.
 4. Your report is a gate. Phase 4 (implementation) does not start until you post `SEC_PASSED <path>`. If Critical/High findings remain, post `SEC_BLOCKED <path>` — the lead routes you to the planner for a plan revision, then you re-review.
+5. Every checklist item you produce MUST carry one of three markers: ✅ Pass / ⚠️ Risk acknowledged / ❌ Block. The lead greps for these.
+
+## Checklist (project-aware expansion)
+
+Run through the always-on items first, then expand the conditional items based on the `security` and stack blocks. Skip items that don't apply (e.g. no SQL items if `data_at_rest != sql`).
+
+### Always-on items (every feature)
+
+- **Secret handling.** No hard-coded credentials, API keys, tokens, or connection strings in the planned code or in committed config. Scan with `git diff` against the worktree base.
+- **Logging hygiene.** No PII or secrets in log output. Particularly relevant when `security.pii: yes`.
+- **Dependency CVEs.** Any new dependency this feature adds is checked for known CVEs. Use `npm audit` (Node), `dotnet list package --vulnerable` (.NET), `pip-audit` (Python), `cargo audit` (Rust), `go list -m -u all` + `govulncheck` (Go) per `backend.language`.
+- **AuthN / AuthZ.** Any new endpoint or route has explicit auth treatment (not implicit-allow). The plan must name it.
+
+### Conditional items — fire only when the flag matches
+
+| When                                                       | Add these checks |
+|------------------------------------------------------------|------------------|
+| `security.public_endpoints: yes`                           | Rate limiting on new public endpoints; input validation against OWASP API Top 10 — broken object-level authz, broken authn, broken object property-level authz, unrestricted resource consumption, broken function-level authz, server-side request forgery, security misconfiguration, lack of protection from automated threats, improper inventory management, unsafe consumption of third-party APIs. |
+| `security.pii: yes`                                        | PII identified at design level; PII columns/fields encrypted at rest if `data_at_rest: sql`; PII redaction in logs; PII in URLs flagged as a defect. |
+| `security.data_at_rest: sql`                               | Parameterised queries only — no string-concatenated SQL. Enumerate every SQL-injection vector for new query paths in the plan. |
+| `security.domain: payments`                                | Idempotency keys on state-changing endpoints; double-spend protection; audit trail for all monetary mutations; PCI-DSS boundary explicitly identified (which fields touch card data, which don't). |
+| `security.domain: healthcare`                              | HIPAA boundary; PHI handling documented; access logging for every PHI read/write. |
+| `frontend` block present                                   | XSS: no `dangerouslySetInnerHTML` without sanitisation; CSP headers planned; CSRF for state-changing requests. |
+| `backend.language: csharp`                                 | Anti-forgery tokens on POST/PUT/DELETE; HSTS in production; null-handling on user input (nullable reference types help but don't eliminate). |
+| `backend.language: node-ts` OR `frontend` block present    | `npm audit` on lockfile change; prototype-pollution review on any `merge-deep` / `extend` / `lodash.merge` usage. |
+
+### Items NOT to include
+
+If `data_at_rest: none` → skip SQL-injection items. If no frontend → skip XSS / CSP / CSRF. If `security.domain: internal-only` and `public_endpoints: no` → skip rate-limit / OWASP-API-Top-10 items unless the plan introduces a new public surface.
+
+This is the point of the template: **do not pad the report with non-applicable items.** A checklist with 15 relevant items beats one with 60 boilerplate items, every time.
+
+## Output format
+
+Save the report to `docs/superpowers/reviews/YYYY-MM-DD-<slug>-security.md`. Structure:
+
+```markdown
+# Security review — <slug>
+
+**Stack signal:** backend=<lang>/<framework>, frontend=<framework|none>, data_at_rest=<value>
+**Posture:** domain=<value>, pii=<value>, public_endpoints=<value>
+
+## Always-on
+
+- ✅ Secret handling — `git diff` clean; no new hard-coded credentials in plan.
+- ✅ Logging hygiene — plan §X explicitly redacts customer email before logging.
+- ❌ Dependency CVEs — plan adds `library-xyz@1.2.3`; CVE-2024-NNNN affects ≤1.2.4. Bump to 1.2.5.
+- ⚠️ AuthN/AuthZ — plan §Y leaves authz on /admin/<x> implicit; owner accepted because /admin is behind VPN.
+
+## Domain-specific
+
+(only the relevant sections per the flags)
+
+## Summary
+
+- Critical: 0
+- High: 1 (item 3 — dependency CVE)
+- Medium: 0
+- Low: 0
+- Risk acknowledged: 1 (item 4 — VPN-only admin)
+```
+
+Each ❌ item BLOCKS phase 4 and surfaces a `block:` or `impl:` task back to the planner for plan revision (lead files it; you name the task in your report). Posting `SEC_PASSED` requires zero ❌ items. ⚠️ items pass but are recorded.
 
 ## Responsibilities
 
-Identify trust boundaries in the design. For each boundary, check: authentication, authorisation, input validation, secret + token handling, transport security, logging hygiene (no sensitive data in logs), and dependency supply chain (new libraries, services). Flag: exposed secrets, missing auth guards, unvalidated external input, insecure defaults, overly-broad permissions, untrusted deserialization, injection surfaces. Each finding states: location in design or plan, threat, severity, recommended remediation.
+Identify trust boundaries in the design. For each boundary, check authentication, authorisation, input validation, secret + token handling, transport security, logging hygiene, and dependency supply chain. Flag: exposed secrets, missing auth guards, unvalidated external input, insecure defaults, overly-broad permissions, untrusted deserialisation, injection surfaces. Each finding states: location in design or plan, threat, severity (Critical / High / Medium / Low), recommended remediation, and a marker (✅/⚠️/❌).
 
 ## Output
 
 Save report to `docs/superpowers/reviews/YYYY-MM-DD-<slug>-security.md` and commit on the feature branch.
-Post `SEC_PASSED <path>` to the lead's mailbox when no Critical/High findings remain, or `SEC_BLOCKED <path>` if any do.
+Post `SEC_PASSED <path>` to the lead's mailbox when no ❌ findings remain, or `SEC_BLOCKED <path>` if any do.
 
 ## Escalation
 
-Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones: a Critical finding requires a design change (re-open phase 1, not phase 2); the plan does not describe an externally-exposed endpoint clearly enough to threat-model; plan-revision loop exceeds three rounds.
+Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones:
+- A Critical finding requires a design change (re-open phase 1, not phase 2).
+- The plan does not describe an externally-exposed endpoint clearly enough to threat-model.
+- Plan-revision loop exceeds three rounds.
+- `CLAUDE.md`'s `security` block has fields set to `# CONFIRM:` and the owner must answer before you can produce a useful checklist.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** checklist verdicts (✅ / ⚠️ / ❌) within the project-aware checklist; severity classification within the Critical / High / Medium / Low rubric.
+- **I consult software-architect (cross-role):** trust-boundary concerns, authn/authz surfaces that overlap structural decisions.
+- **I escalate to owner (owner-only):** any security-blocking finding by definition; `CLAUDE.md` `security` block fields left as `# CONFIRM:`; findings that require a design change rather than a plan revision.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

package/plugins/team-superpower/agents/software-architect.md

@@ -7,6 +7,10 @@ model: sonnet
 
 # Software Architect — Phase 3 (Pre-impl architecture gate)
 
+## Thinking discipline
+
+Default thinking level: **high**. Before any non-trivial step (boundary analysis, scaling assessment, integration-risk call, ARCH_PASSED / ARCH_BLOCKED verdict), take extended thinking time before acting. The team relies on your output being correct, not fast. Routine doc reads may be quick; every architectural finding and gate verdict is high.
+
 You are the **software-architect** teammate. You run in parallel with `security-engineer` after the planner posts `PLAN_READY` and before any implementer is spawned. Your job: confirm the plan does not violate the design's architectural intent, and surface system-boundary risks the planner missed.
 
 ## Hard rules
@@ -28,3 +32,13 @@ Post `ARCH_PASSED <path>` to the lead's mailbox when no Critical/High findings r
 ## Escalation
 
 Use the §7 template in `docs/superpowers/ESCALATION.md` for any blocker. Common ones: design and plan disagree on a boundary; a Critical finding requires a design change (re-open phase 1, not phase 2); plan-revision loop exceeds three rounds.
+
+## Clarification routing
+
+Use the 4-class decision table in `assets/ESCALATION.md` to classify every clarification you face. Your per-role buckets:
+
+- **I decide alone (tactical):** arch-review verdicts within the existing design boundaries, severity classification of architectural findings (Critical / High / Medium / Low).
+- **I consult security-engineer (cross-role):** findings that straddle security and architecture (e.g., trust-boundary changes, authn surface changes).
+- **I escalate to owner (owner-only):** architectural concerns that cannot be resolved within the existing design (re-opens phase 1, not phase 2); design-vs-plan contradictions surfaced at the gate.
+
+Every escalation MUST include the `Peer attempts:` field per `assets/ESCALATION.md`. If you classify as `tactical`, do NOT escalate — log to `## Assumptions` instead.

package/plugins/team-superpower/assets/CLAUDE.md.template

@@ -0,0 +1,96 @@
+# Project: <your-project-name>
+
+<!--
+  This file is the source of truth for project context. team-superpower reads
+  the structured `team-superpower` YAML block below to decide which teammates
+  to spawn and what test / build / format commands to use. The free-form prose
+  outside the block is passed verbatim to every teammate as project context.
+
+  team-superpower will NEVER overwrite this file. If it detects a missing
+  block, it writes its best guess to `docs/superpowers/stack.detected.md` for
+  you to copy/edit/paste here.
+
+  Delete this comment block before committing.
+-->
+
+<short narrative describing what the project is, who consumes it, and any cross-
+service dependencies your team should know about. Example: "This is the orders
+microservice for the storefront. APIs talk to the payments service via gRPC.
+PII goes through the redaction pipeline (see redaction-guide).">
+
+```team-superpower
+# ────────────────────────────────────────────────────────────────────────────
+# Backend
+# ────────────────────────────────────────────────────────────────────────────
+# Set `backend: none` (no further keys) if this is a frontend-only repo.
+backend:
+  language: csharp              # csharp | node-ts | python | go | rust | java
+  framework: aspnetcore         # framework name; e.g. aspnetcore | fastapi | express | nestjs | gin | axum | spring-boot
+  test_framework: xunit         # xunit | nunit | mstest | reqnroll | pytest | jest | vitest | go-testing | cargo-test | junit
+  build_command: dotnet build
+  test_command: dotnet test
+  format_command: dotnet format --verify-no-changes   # set to "none" if no style check is wired
+  migration_tool: ef-core       # ef-core | flyway | liquibase | alembic | django-migrations | prisma | typeorm | knex | none
+  package_manager: nuget        # nuget | npm | pnpm | yarn | bun | pip | poetry | pipenv | go-modules | cargo | maven | gradle
+
+# ────────────────────────────────────────────────────────────────────────────
+# Frontend
+# ────────────────────────────────────────────────────────────────────────────
+# Set `frontend: none` (no further keys) if this is a backend-only repo.
+frontend:
+  language: typescript          # typescript | javascript
+  framework: react              # react | vue | svelte | solid | angular | next | nuxt
+  bundler: vite                 # vite | webpack | rspack | next | nuxt | rollup | none
+  test_framework: vitest        # vitest | jest | none
+  e2e_framework: playwright     # playwright | cypress | none
+  ui_library: shadcn            # shadcn | mui | antd | tailwind-only | none
+  package_manager: pnpm         # npm | pnpm | yarn | bun
+  build_command: pnpm build
+  test_command: pnpm test
+
+# ────────────────────────────────────────────────────────────────────────────
+# Contracts — only relevant when both backend AND frontend are present.
+# ────────────────────────────────────────────────────────────────────────────
+contracts:
+  source_of_truth: openapi      # openapi | grpc | graphql | typescript | none
+  openapi_path: contracts/openapi.yaml
+  ts_gen_command: pnpm generate:api-types   # command that regenerates FE-consumable types from the contract
+
+# ────────────────────────────────────────────────────────────────────────────
+# CI — read by reviewer in phase 7 to gate the finish-branch decision.
+# ────────────────────────────────────────────────────────────────────────────
+ci:
+  provider: github-actions       # github-actions | azure-pipelines | gitlab-ci | circleci | none
+  workflow_path: .github/workflows/ci.yml
+  required_checks: ["build", "test", "lint"]
+  poll_timeout_minutes: 20
+
+# ────────────────────────────────────────────────────────────────────────────
+# Security — drives the security-engineer's checklist (phase 3).
+# ────────────────────────────────────────────────────────────────────────────
+security:
+  domain: payments               # payments | healthcare | generic | internal-only
+  pii: yes                       # yes | no
+  public_endpoints: yes          # yes | no
+  data_at_rest: sql              # sql | nosql | none
+
+# ────────────────────────────────────────────────────────────────────────────
+# Limits — operational tuning. Defaults are sensible; override only if needed.
+# ────────────────────────────────────────────────────────────────────────────
+limits:
+  phase_stall_minutes: 30        # within-phase stall watchdog window; two empty windows force a §7 escalation
+  max_tasks_per_implementer: 12  # planner halts and asks the owner to split the feature above this
+  max_concurrent_teammates: 5    # hard cap on parallel teammates (best-practice guidance from CLAUDE.md)
+```
+
+## Conventions
+
+<!--
+  Anything below is free-form prose. Capture local style rules, conventions
+  the architecture review or implementers should respect, and any "we don't do
+  X here" rules. Implementers will read this at task start.
+-->
+
+- (Example) File-scoped namespaces, nullable reference types on.
+- (Example) React components are function components only.
+- (Example) All API endpoints require `[Authorize]` unless explicitly marked `[AllowAnonymous]`.

package/plugins/team-superpower/assets/ESCALATION.md

@@ -14,9 +14,26 @@ Options:
   C. <option> — <trade-off>  (optional)
 Recommendation: <our pick + one-sentence why>
 Need from you: <choose one | yes/no | other>
+Peer attempts:
+  - <ISO ts> asked <role>: <one-line reply summary or "no reply within cadence">
+  - <ISO ts> asked <role>: <one-line reply summary or "no reply within cadence">
+  (or, when no peer attempt is required:)
+  - class=tactical — no peer attempt; logged as assumption, see checkpoint § Assumptions
+  - class=owner-only — no peer attempt because <reason>
 ```
 
-All five labels (`Phase`, `Context`, `Options`, `Recommendation`, `Need from you`) MUST appear. Missing any → the hook blocks the task completion with `BAD_ESCALATION: missing field(s) ...`.
+All six labels (`Phase`, `Context`, `Options`, `Recommendation`, `Need from you`, `Peer attempts`) MUST appear. The `TaskCompleted` hook warns (warn-only since 2026-05-14) with `bad_escalation: missing field(s) ...` if any are missing.
+
+## Decision classes
+
+| Class           | Examples                                                                                       | Routing                                                                                                                                          |
+| --------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| tactical        | naming, error wording, log field choice, fixture data, threshold inside a stated range         | Originator decides. Logs to checkpoint § Assumptions. No mailbox, no escalation.                                                                  |
+| cross-role      | API contract shape across roles, test placement, error-handling contract                       | Mailbox to the peer role. Consensus on the first round-trip → log + proceed. After 2 round-trips with no consensus → escalate citing the attempts. |
+| architectural   | new runtime dependency, persistence-model change, public-interface shape change                | Mailbox to `software-architect` first. Sign-off → log as architectural assumption. Dissent or no-decide → escalate.                              |
+| owner-only      | scope change, design-vs-plan contradiction, external policy, security-blocking decision        | Escalate immediately. No peer attempt required. `Peer attempts` field records `class=owner-only — no peer attempt because <reason>`.       |
+
+Classification rule of thumb: if the answer changes a test the implementer would write, AND the existing design / plan does not pin it, AND the change does not alter scope / architecture / external policy, the question is tactical or cross-role. Otherwise it is architectural or owner-only.
 
 ## Worked example 1 — peer-to-peer (planner → designer)
 
@@ -30,6 +47,8 @@ Options:
   C. Drop the criterion from the plan and tag it as a follow-up.
 Recommendation: B — "fast" is the kind of vague that costs a rewrite later, and the design doc is the right place to fix it once.
 Need from you: choose A/B/C.
+Peer attempts:
+  - 2026-05-12T14:02Z asked designer: "no reply within cadence (30min)"
 ```
 
 ## Worked example 2 — lead-to-owner (plan-vs-design mismatch surfaced mid-implementation)
@@ -44,6 +63,8 @@ Options:
   C. Owner reopens the design question entirely (the two APIs imply different semantics).
 Recommendation: A — the design doc was approved first and the discrepancy reads as a plan-writing slip, not a design change. But this is a load-bearing decision and we won't move without your call.
 Need from you: choose A/B/C.
+Peer attempts:
+  - class=owner-only — no peer attempt because design-vs-plan contradiction requires owner adjudication
 ```
 
 ## Worked example 3 — lead-to-owner (`FINISH_BLOCKED` option E)
@@ -58,4 +79,16 @@ Options:
   C. Owner switches the decision to pr_opened and merges via GitHub UI.
 Recommendation: A — the conflict surface is small and a clean rebase plus retry is the cheapest path. We won't move until you say which.
 Need from you: choose A/B/C.
+Peer attempts:
+  - class=owner-only — no peer attempt because owner explicitly chose escalate over inline retry
 ```
+
+## Worked example 4 — tactical, no peer attempt (assumption logged, no escalation)
+
+This is shown for completeness; this entry NEVER reaches the owner mailbox. It is what the originator writes into `## Assumptions` in the session checkpoint. No `BLOCKED:` is filed.
+
+```
+2026-05-12T14:08Z backend-developer [class=tactical]: chose error message "user_id required" over "missing user_id" for consistency with existing 422 responses on /v1/users. (peer: none, evidence: n/a)
+```
+
+The class=tactical originator does NOT file an escalation. If they file one anyway with `Peer attempts: <empty>`, the lead bounces it with `RETRY_PEER: try <peer role> first` (or `LOG_ASSUMPTION: this is tactical, log it instead`).

package/plugins/team-superpower/assets/SESSION_README.md

@@ -2,6 +2,90 @@
 
 This directory holds the artifacts produced by `/team-feature` runs. The team-superpower plugin seeds it on first use; afterwards, the design / plan / review / checkpoint files for each feature are written by the team and committed.
 
+## Customising for your project
+
+Stack decisions, test/build commands, contract source-of-truth, CI provider, and security posture are all driven by a `team-superpower` fenced block in your repo-root `CLAUDE.md`. The plugin reads it on every run; it **never overwrites it**.
+
+### 1. Write a `team-superpower` block in CLAUDE.md
+
+Copy `plugins/team-superpower/assets/CLAUDE.md.template` to your repo root as `CLAUDE.md` (or paste the `team-superpower` block into your existing CLAUDE.md). The block recognises:
+
+- `backend` — `language`, `framework`, `test_framework`, `build_command`, `test_command`, `format_command`, `migration_tool`, `package_manager`. Set `backend: none` to declare a frontend-only repo.
+- `frontend` — `language`, `framework`, `bundler`, `test_framework`, `e2e_framework`, `ui_library`, `package_manager`, `build_command`, `test_command`. Set `frontend: none` to declare a backend-only repo.
+- `contracts` — `source_of_truth` (`openapi` / `grpc` / `graphql` / `typescript` / `none`), `openapi_path`, `ts_gen_command`.
+- `ci` — `provider`, `workflow_path`, `required_checks`, `poll_timeout_minutes` (default 20).
+- `security` — `domain` (`payments` / `healthcare` / `generic` / `internal-only`), `pii`, `public_endpoints`, `data_at_rest`.
+
+Free-form prose around the block (e.g. a `## Conventions` section with project-specific rules) is passed to every teammate as project context.
+
+### 2. Auto-detection fallback
+
+If `CLAUDE.md` is missing or has no `team-superpower` block, the lead runs `scripts/detect-stack.sh` in phase 0 and writes its best guess to `docs/superpowers/stack.detected.md`, then halts and asks you to review the `# CONFIRM:` lines and paste the corrected block into CLAUDE.md. **The plugin will not edit your CLAUDE.md for you.**
+
+### 3. Shape-adaptive team
+
+Once the block (or detection) is parsed, the lead decides the **stack shape**:
+
+| Shape | Teammates spawned |
+|-------|-------------------|
+| `full-stack`  | designer, planner, software-architect, security-engineer, backend-developer, frontend-developer, qa-engineer, reviewer (8) |
+| `be-only`     | designer, planner, software-architect, security-engineer, backend-developer, qa-engineer, reviewer (7) — no `frontend-developer` |
+| `fe-only`     | designer, planner, software-architect, security-engineer, frontend-developer, qa-engineer, reviewer (7) — no `backend-developer` |
+
+The shape is written to `docs/superpowers/sessions/<slug>.shape`; the `TaskCreated` hook reads it to reject `impl:fe-*` in BE-only repos and vice-versa.
+
+#### Concurrency model
+
+The numbers above (7 or 8) are the **lifetime** team size, not the parallelism. Roles are phase-gated: only the teammates needed for the current phase are alive at any moment. The maximum concurrency is **2 teammates in parallel**:
+
+| Phase | Concurrent teammates |
+|-------|----------------------|
+| 1 design        | 1 (designer) |
+| 2 plan          | 1 (planner) |
+| 3 pre-impl gate | 2 (software-architect + security-engineer, parallel) |
+| 4 implementation | 1 (`be-only` or `fe-only`) or 2 (`full-stack`, after `CONTRACT_PUBLISHED`) |
+| 5 QA            | 1 (qa-engineer) |
+| 6 review        | 1 (reviewer) |
+| 7 finish        | 1 (reviewer, hat 2 — reused) |
+
+This matches the Claude Code agent-team best practice of "3–5 teammates in parallel, 5–6 tasks each". The lead caps concurrency at 5 (configurable via `limits.max_concurrent_teammates` in CLAUDE.md) and refuses to start a phase that would exceed it. The planner caps tasks per implementer at 12 (configurable via `limits.max_tasks_per_implementer`) and asks the owner to split the feature if a plan would exceed it.
+
+If the lead detects no mailbox activity or shared-task-list transitions for `limits.phase_stall_minutes` (default 30) within a phase, it pings the active teammate; if the next 30-minute window is also silent, it surfaces a §7 escalation. This is the within-phase stall watchdog — heartbeat-at-phase-boundaries alone doesn't catch silent hangs.
+
+#### Worktree reuse
+
+If you launch `/team-feature` from inside a linked git worktree on a feature branch, the planner reuses that worktree instead of nesting a new one inside it. The signal `WORKTREE_READY <path> <branch> <origin>` carries `origin: reused` and the checkpoint records `**Worktree origin:** reused`.
+
+Detection is automatic — no config needed:
+
+| Where `/team-feature` is launched | Branch                                                    | Behavior |
+|---|---|---|
+| Linked worktree                   | feature branch (anything not protected)                   | **Reuse** the current worktree. |
+| Linked worktree                   | `main`, `master`, `develop`, `dev`, `release/*`, `releases/*` | **Halt.** Switch to a feature branch (`git checkout -b feature/<slug>`) and re-run. |
+| Main repo                         | any                                                       | **Create** a fresh worktree via Superpowers `using-git-worktrees`. |
+
+A reused worktree is owned by you, not the team — Step D.5 auto-removal after merge **does not run** when origin is `reused`; the Closing block records `worktree: removal-skipped:reused-existing-worktree` and the worktree stays on disk. Created worktrees are removed after a successful merge as before.
+
+The clean-test-baseline check still runs in both modes. If you reused a worktree with uncommitted changes that break the baseline, the planner halts with a §7 escalation asking you to stash or commit first.
+
+### 4. Contract sync (full-stack only)
+
+When both BE and FE are present and `contracts.source_of_truth != none`, the planner emits `impl:be-contract-publish-<slug>` as the first phase-4 task. The lead does not assign any `impl:fe-*` task until the backend-developer posts `CONTRACT_PUBLISHED`. Every `impl:fe-*` task has `depends_on: [impl:be-contract-publish-<slug>]` in its metadata.
+
+Mid-implementation contract drift uses `impl:contract-update-<topic>`: BE files it (often after FE posts `CONTRACT_DRIFT_DETECTED`), updates the contract, runs `ts_gen_command`, posts `CONTRACT_UPDATED`, and FE resumes after re-pulling the contract hash.
+
+### 5. CI gate before finish
+
+The reviewer pushes the branch in phase 7, then (when `ci.provider != none`) polls the CI provider for `ci.required_checks` up to `ci.poll_timeout_minutes` (default 20). On green, the finish-branch menu surfaces. On red, the merge-failure menu surfaces with an extra "Show CI logs" option. On timeout, a 3-option menu (re-poll / switch to pr_opened / escalate) surfaces. Every CI variant counts as the **same** finish-branch touchpoint — the 3-touchpoint cap holds.
+
+### 6. Project-aware security checklist
+
+`security-engineer` reads the `security` block and the stack info, then expands its checklist accordingly. A `domain: payments` repo gets idempotency / audit-trail / PCI items; a `data_at_rest: sql` repo gets parameterised-query items; a no-FE repo skips XSS items entirely. The output report uses ✅/⚠️/❌ markers — any ❌ blocks phase 4.
+
+### 7. Superpowers version pinning
+
+The lead reads the installed Superpowers version in phase 0 and writes it to the checkpoint frontmatter (`superpowers_version`). On `/team-feature-resume`, the lead checks whether the installed version still matches. If not, you see a 3-option menu (continue anyway / roll back Superpowers / discard this feature). The pin is informational + safety — never a hard block; you can always continue.
+
 ## Layout
 
 ```
@@ -94,17 +178,23 @@ bash plugins/team-superpower/scripts/team-state.sh scan <slug>
 | Symptom | What it usually means | First thing to check |
 |---|---|---|
 | `BLOCKED_IDLE: N unanswered peer messages` from a teammate | A peer asked the teammate something and they tried to idle without replying | Open the teammate's mailbox, reply or escalate |
-| `BAD_PREFIX` on a new task | The lead created a task without the `impl:`/`review:`/`meta:`/`block:` prefix (or used an `impl:` task without the `be-` / `fe-` sub-prefix) | Lead's bug — fix the task title |
+| `BAD_PREFIX` on a new task | The lead created a task without the `impl:`/`review:`/`meta:`/`block:` prefix (or used an `impl:` task without one of the v2 sub-prefixes: `be-`, `fe-`, `qa-fix-be-`, `qa-fix-fe-`, `review-fix-be-`, `review-fix-fe-`, `contract-update-`, `be-migration-`, `be-contract-publish-`) | Lead's bug — fix the task title |
+| `SHAPE_REJECTED: shape is 'be-only'` (or `fe-only`) | A task was created with a prefix the shape doesn't allow (e.g. `impl:fe-*` in a BE-only repo) | Planner or lead bug — re-check `docs/superpowers/sessions/<slug>.shape` and re-emit |
+| `MIGRATION_RACE` on task complete | Two `impl:be-migration-*` tasks were `in_progress` simultaneously | Lead should serialize migrations; backend-developer should idle if another migration is in flight |
+| `EMPTY_CONTRACT_PUBLISH` on task complete | A `impl:be-contract-publish-*` task completed but no commit touched a contract file | Backend-developer didn't actually publish; investigate and re-run the task |
+| `superpowers_version` mismatch on resume | Superpowers was upgraded between feature start and resume | Pick continue / rollback / discard from the 3-option menu |
 | `NO_PLAN_APPROVAL` blocking a task complete | An `impl:` task is missing `metadata.plan_approved_at` | Lead forgot to stamp tasks after owner plan-approval; backfill from the checkpoint timestamp |
 | `ARCH_BLOCKED` or `SEC_BLOCKED` from phase 3 | Pre-impl gate rejected the plan; arch/security findings need plan revisions | Planner addresses the report, re-emits the plan, re-runs the gate before phase 4 starts |
 | `QA_BLOCKED` from phase 5 | Acceptance criteria or regression coverage missing post-implementation | Lead files `impl:qa-fix-be-` / `impl:qa-fix-fe-` tasks; loop back to phase 4 |
 | Backend developer and frontend developer want the same file | Plan didn't capture file-scope metadata for the overlapping tasks, or the task was mis-prefixed | Serialize by holding one; planner should re-route by `impl:be-` / `impl:fe-` prefix and backfill file-scope |
-| `BAD_ESCALATION: missing field(s) ...` | A teammate posted a blocker without all five template fields | Rewrite using the full template in `ESCALATION.md` |
+| `bad_escalation: missing field(s) ...` (warn-only in `log.jsonl`) | A teammate posted a blocker without all six template fields (`Phase`, `Context`, `Options`, `Recommendation`, `Need from you`, `Peer attempts`) | Rewrite using the full template in `assets/ESCALATION.md` |
 | Lead refuses to ping the owner | The teammate's request to escalate didn't use the §7 template | Same as above |
 | Teammate ran a non-Superpowers approximation of a skill | Teammate paraphrased the SKILL.md instead of following it | The agent's system prompt requires the canonical skill — re-spawn and remind it explicitly |
 | `REFUSED: heartbeat ... is Ns old` from cleanup | Heartbeat is fresh — cleanup script thinks a lead is alive | Verify nothing's running; if certain the previous lead is dead, run with `--ignore-heartbeat` |
 | `/team-feature` halts at preflight | Stale team config left over from a previous run | Run `/team-cleanup <slug>` (or resume via `/team-feature-resume`) |
 | `FINISH_BLOCKED <reason>` from the reviewer | The merge step of `finishing-a-development-branch` failed (`conflict` / `non-ff` / `dirty-worktree` / `push-rejected`) | The lead surfaces a 5-option menu (retry / pr_opened / kept / discarded / escalate). Pick one; merge retries cap at 3. |
+| `RETRY_PEER: try <role> first` | Lead bounced an escalation because the originator's class isn't `owner-only` and `Peer attempts` is empty | Originator mails the named role with the question, waits one cadence, then refiles citing the attempt. See `assets/ESCALATION.md` § Decision classes |
+| `LOG_ASSUMPTION: tactical, log to checkpoint § Assumptions` | Lead bounced a `class=tactical` escalation | Originator logs one line under the session checkpoint's `## Assumptions` and proceeds. No owner touchpoint consumed |
 | `git worktree remove` failed during cleanup | Step D.5 hit an uncommitted/untracked file or a locked worktree | Pick from the 4-option menu (show files + retry / force-remove with confirmation / keep / escalate). Force-remove discards uncommitted work — only confirm if you've checked the file list. |
 | Auto-cleanup skipped after FINISH_DONE | One of Step A's preconditions failed (missing commits, in-progress tasks, etc.) | Read the lead's halt reason; once resolved, run `/team-cleanup <slug>` |
 | Hook log noise | Hooks write tuning data to `.claude/hooks/log.jsonl` | Inspect the file; trim or refine matchers if a hook is over-triggering |
@@ -116,3 +206,13 @@ bash plugins/team-superpower/scripts/team-state.sh scan <slug>
 ## Where the methodology lives
 
 The team-superpower plugin is purely the coordination layer. The actual development discipline (TDD, plan format, two-stage review, branch hygiene) is owned by the upstream [obra/superpowers](https://github.com/obra/superpowers) skills. If a skill's behaviour changes, the team picks it up automatically — agents reference skills by name, not by content.
+
+## Session checkpoint § Assumptions
+
+Every non-owner decision (tactical, cross-role with consensus, architectural with sign-off) is logged as one line in the session checkpoint's `## Assumptions` block. The QA and reviewer phases scan this block for contradictions with the design / plan; contradictions surface as QA findings or review comments. Format:
+
+```
+- <ISO ts> <role> [class=<tactical|cross-role|architectural>]: <one-line decision> (peer: <role|none>, evidence: <link to mailbox msg | n/a>)
+```
+
+The owner sees the assumptions log at every phase boundary as part of the checkpoint commit.