feat: operationalize Superpowers phase map

- install all upstream Superpowers companion skill files
- add a real brainstorming/spec gate before implementation planning
- preserve executable modes for companion support scripts
- expand workflow docs, examples, validation, and smoke coverage

Author: damienen

README.md

@@ -16,16 +16,24 @@ Telegram / mobile request
   -> Hermes gateway or OpenClaw workspace skill
   -> classify task
   -> choose worker-routing: Codex / Claude / split
+  -> Brainstorming Gate when scope is broad or risky
   -> spec gate
   -> implementation-plan gate
   -> implementation
-  -> subagent review
+  -> independent review and review intake
   -> verification
+  -> branch closeout option
   -> report
 ```
 
 ![basd-coding-dispatch workflow](assets/flow-diagram.svg)
 
+## Superpowers Phase Map
+
+`basd-coding-dispatch` integrates Superpowers phase-by-phase. `brainstorming` is a real gate before implementation planning for broad, ambiguous, user-facing, workflow, architecture, UI/design, public-doc, or public-claim work; exact low-risk tiny fixes stay lightweight and use only a micro-brainstorm when ambiguity exists.
+
+Hermes and OpenClaw installs include the complete pinned upstream directories for all 14 Superpowers skills by default as companion skills: session activation, brainstorming, worktrees, planning, execution, parallel dispatch, TDD, systematic debugging, review request, review intake, verification, branch closeout, and skill-writing. Use `--skip-companion-skills` or `--no-companion-skills` for core-only or offline installs.
+
 ## Prerequisites
 
 - Hermes or OpenClaw is already installed and authenticated for the runtime you plan to use.
@@ -75,7 +83,7 @@ npx basd-coding-dispatch validate
 
 ## What gets installed
 
-Hermes and OpenClaw targets install `skills/basd-coding-dispatch/` as a self-contained skill, including `SKILL.md` and skill-local `references/`. By default, they also install pinned companion skills from `integrations/companion-skills.json` when those skills are missing: Hermes Codex/Claude Code worker guides plus the Superpowers process skills used for planning, review, TDD, debugging, and verification. Default companion installs fetch from `raw.githubusercontent.com`, so they require network access to GitHub raw content.
+Hermes and OpenClaw targets install `skills/basd-coding-dispatch/` as a self-contained skill, including `SKILL.md` and skill-local `references/`. By default, they also install pinned companion skills from `integrations/companion-skills.json` when those skills are missing: Hermes Codex/Claude Code worker guides plus complete upstream Superpowers skill directories used for activation, brainstorming, worktrees, planning, execution, parallel dispatch, review request, review intake, TDD, systematic debugging, verification, branch closeout, and skill-writing. Default companion installs fetch from `raw.githubusercontent.com`, so they require network access to GitHub raw content.
 
 Existing companion skills are skipped unless `--force` is provided. Existing core `basd-coding-dispatch` files still block the install unless `--force` is provided. Use `--skip-companion-skills` or `--no-companion-skills` for the offline/core-only path.
 
@@ -91,7 +99,7 @@ For OpenClaw, `--dir <path>` writes to that workspace root under `<path>/skills/
 
 ## Adaptation Status
 
-Hermes is the flagship install path for v0.1. OpenClaw support is based on the verified local workspace-skill layout: `openclaw skills info aeo-geo` reports source `openclaw-workspace` and a path under `~/openclaw-workspace/skills/...`. Other harnesses remain manual or experimental adapters until their native install paths are validated.
+Hermes is the flagship install path for v0.1. OpenClaw support is based on the verified local workspace-skill layout: `openclaw skills info <skill-name>` reports source `openclaw-workspace` and a path under `~/openclaw-workspace/skills/...` for workspace-installed skills. Other harnesses remain manual or experimental adapters until their native install paths are validated.
 
 | Target | Status | Install notes |
 | --- | --- | --- |
@@ -106,16 +114,21 @@ Hermes is the flagship install path for v0.1. OpenClaw support is based on the v
 ## Quality Gates
 
 - Classify the request before choosing a worker-routing shape.
+- Declare the Superpowers Activation Map for the work shape.
 - Select one of the quality profiles (`tiny-fix`, `standard-feature`, `risky-release`, `mobile-ui`, `backend-api`, `cli-package`, or `public-docs`) and auto-escalate gates when the work reveals more risk.
 - Produce a spec gate for ambiguous work.
+- Run the Brainstorming Gate before implementation planning for broad, ambiguous, user-facing, workflow, architecture, UI/design, public-doc, or public-claim work.
 - Produce an implementation-plan gate before feature code.
 - Run the human plan-lint checklist for feature, risky, public, cross-module, or ambiguous work.
+- Use `executing-plans`, `subagent-driven-development`, or `dispatching-parallel-agents` according to task shape.
 - Keep worker-routing mechanics in `references/` and `integrations/`, not in the portable skill body.
 - Use lightweight independent review for tiny fixes and fuller independent review for meaningful implementation work.
+- Run review intake before fix loops.
 - Include untracked files and verification output in reviewer packets.
 - Preserve valid bonus findings as backlog/input instead of discarding them.
 - Record Superpowers evidence when those skills are used, or state the compensation gates when a required skill/reference is unavailable.
 - Verify with concrete commands, transcripts, examples, or screenshots before reporting done.
+- Present explicit branch closeout options and respect no-push/no-publish/no-PR branch policy unless approval is granted.
 - Keep public repo files free of private paths, credentials, private client data, and unvalidated provider metadata.
 - A2 run manifest / gate ledger is intentionally not introduced as a v0.1 requirement.
 
@@ -129,7 +142,7 @@ The deterministic workflow evals assert process guarantees without calling an LL
 npm run workflow-evals
 ```
 
-They check that quality profiles require review, ambiguous features use a spec gate before planning, reviewer packets include untracked files, reviewer output is markdown/YAML rather than strict JSON-only, bonus findings go to backlog/input, Superpowers evidence or compensation is required, and A2 is not introduced as a required artifact.
+They check that quality profiles require review, broad/ambiguous work uses a Brainstorming Gate before implementation planning, reviewer packets include untracked files, reviewer output is markdown/YAML rather than strict JSON-only, review intake precedes fix loops, bonus findings go to backlog/input, Superpowers evidence or compensation is required, and A2 is not introduced as a required artifact.
 
 ## Examples
 

bin/basd-coding-dispatch.mjs

@@ -2,7 +2,7 @@
 
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -335,6 +335,20 @@ function companionFixturePath(skill, file) {
   return path.join(fixtureRoot, skill.sourceRepo, file.sourcePath);
 }
 
+function companionFileMode(skill, file) {
+  if (file.mode === undefined) {
+    return undefined;
+  }
+
+  if (file.mode !== "755") {
+    throw new Error(
+      `unsupported companion file mode for ${skill.name} ${file.sourcePath}: ${file.mode}`
+    );
+  }
+
+  return 0o755;
+}
+
 async function fetchCompanionFile(skill, file) {
   if (process.env.BASD_COMPANION_SKILLS_FIXTURE_DIR) {
     return readFile(companionFixturePath(skill, file), "utf8");
@@ -371,7 +385,8 @@ async function prepareCompanionSkillInstall(root, options) {
         sourcePath: file.sourcePath,
         outputFile,
         destinationPath: path.join(root, outputFile),
-        rawUrl: file.rawUrl
+        rawUrl: file.rawUrl,
+        mode: companionFileMode(skill, file)
       };
     });
     const existingFiles = plannedFiles.filter((file) => existsSync(file.destinationPath));
@@ -417,6 +432,9 @@ async function writeCompanionSkillInstall(plan) {
     for (const file of skillPlan.files) {
       await mkdir(path.dirname(file.destinationPath), { recursive: true });
       await writeFile(file.destinationPath, file.content, "utf8");
+      if (file.mode !== undefined) {
+        await chmod(file.destinationPath, file.mode);
+      }
     }
   }
 }

examples/dual-provider-review.md

@@ -14,6 +14,8 @@ Release and packaging task. Higher risk because incorrect claims or unsafe publi
 
 Worker A implements the workflow. Worker B reviews the diff and checks whether the workflow is safe, conventional, and honest.
 
+Use `subagent-driven-development` if implementation has 3+ owned task slices. Use `dispatching-parallel-agents` only for independent domains, such as read-only docs claim review while workflow edits continue elsewhere.
+
 ## Implementer Brief
 
 ```text
@@ -42,6 +44,17 @@ findings:
     disposition: must-fix-now | ask-human | bonus-backlog | reject-if-wrong
 ```
 
+## Review Intake
+
+Before any fix loop, use `receiving-code-review`:
+
+1. Read the complete feedback.
+2. Restate unclear findings.
+3. Verify each finding against the workflow, package scripts, and approved scope.
+4. Evaluate whether the finding is technically sound.
+5. Disposition it as `must-fix-now`, `ask-human`, `bonus-backlog`, or `reject-if-wrong`.
+6. Fix only accepted in-scope findings.
+
 ## Dispatcher Reconciliation
 
 The dispatcher accepts concrete findings, rejects incorrect findings with evidence, preserves valid out-of-scope bonus findings as backlog/input, applies narrow in-scope fixes, and reruns:

examples/feature-build.md

@@ -10,19 +10,33 @@ Add a new worker adapter target for a coding harness.
 
 Feature build using the `cli-package` quality profile and CLI/tooling/package edge-case pack. It changes installer behavior, docs, validation, examples, and public claims.
 
+## Brainstorming Gate
+
+```text
+Goal: provide a scaffold target for the harness without implying native marketplace support.
+Non-goals: no hidden metadata, no credential handling, no publish/release action.
+Approaches:
+- Manual scaffold only: lower risk, honest status, covered by smoke tests.
+- Native adapter claim: rejected until install path is validated.
+Acceptance: init supports --target <new-target>, copies only validated public files, refuses overwrite without --force, docs include tested/experimental status.
+Decision: proceed with manual or experimental adapter only, then write an implementation plan.
+```
+
+No implementation plan is written before this brainstorming/spec direction is accepted.
+
 ## Spec Gate
 
 ```text
 Problem: users need a scaffold target for the harness.
 Non-goals: no native marketplace package, no hidden metadata, no credential handling.
 Behavior: init supports --target <new-target>, copies only validated public files, refuses overwrite without --force.
 Docs: integration page includes status label and tested scope.
-Acceptance: validate, smoke-test, and pack dry-run pass.
+Acceptance: validate, smoke-test, workflow-evals, and pack dry-run pass.
 ```
 
 No code is written before the spec gate is accepted.
 
-## Implementation-Plan Gate
+## Implementation Plan Only
 
 ```text
 Files:
@@ -39,7 +53,8 @@ Steps:
 4. Add validation coverage for the integration doc.
 5. Add install docs with an honest status label.
 6. Escalate tests if package files, force/overwrite behavior, JSON/text output, or public support claims change.
-7. Run npm run validate, npm run smoke-test, npm run workflow-evals, npm pack --dry-run.
+7. Execute with subagent-driven-development if the work splits into 3+ owned task slices; use executing-plans if it stays at 1-2 tasks.
+8. Run review intake for accepted findings, then final verification.
 ```
 
 No feature code is written before the implementation plan is accepted.

examples/small-fix.md

@@ -10,6 +10,16 @@ The CLI exits zero for an unknown command. Make unknown commands print help and
 
 Small fix using the `tiny-fix` quality profile. User-visible CLI behavior. No spec gate needed beyond the stated behavior.
 
+## Micro-Brainstorm
+
+The request is exact, so no full Brainstorming Gate is needed. If ambiguity appeared, use a micro-brainstorm such as:
+
+```text
+Question: should unknown command output go to stdout or stderr?
+Tradeoff: stdout preserves current help behavior; stderr may be more conventional for errors.
+Decision needed before implementation if existing tests do not settle it.
+```
+
 ## Worker Routing
 
 Codex implements. Independent review is lightweight because tiny fixes still get a separate reviewer check.
@@ -25,7 +35,7 @@ Codex implements. Independent review is lightweight because tiny fixes still get
 
 Reviewer checks that known commands still work, unknown commands fail, and help text remains accurate.
 
-Review packet includes `git status --short --branch`, the focused diff, untracked files if any, and the smoke-test output.
+Review packet includes `git status --short --branch`, the focused diff, untracked files if any, and the smoke-test output. Review intake dispositions any finding before a fix loop.
 
 ## Verification
 

examples/telegram-agent-workflow.md

@@ -17,20 +17,28 @@ Patch the install flow so Hermes is the default skill path and OpenClaw users ge
 
 ```text
 Classification: install and public docs feature; public repo risk.
+Superpowers Activation Map: using-superpowers, brainstorming, writing-plans, subagent-driven-development, requesting-code-review, receiving-code-review, verification-before-completion, finishing-a-development-branch.
 Worker routing: Codex implements CLI/docs changes; independent reviewer checks claims and tests.
-Spec gate: native Hermes install must copy the full skill directory under the Hermes home. OpenClaw install may be documented only as workspace-skill compatible. Other harness adapters stay experimental/manual unless validated.
+Brainstorming/spec gate: native Hermes install must copy the full skill directory under the Hermes home. OpenClaw install may be documented only as workspace-skill compatible. Other harness adapters stay experimental/manual unless validated.
 Implementation-plan gate: add failing smoke coverage, update CLI install target resolution, copy skill-local references, rewrite README/integration docs, then run package validation.
 ```
 
-## Phone Approval
+## Phone Approval 1: Brainstorming / Spec
 
 ```text
-Approved. Do not push, publish, or claim native marketplace support.
+Approved direction. Do not claim native marketplace support.
+```
+
+## Phone Approval 2: Implementation Plan
+
+```text
+Approved implementation plan. Local edits and local verification only.
+Do not push, publish, release, deploy, create a PR, or delete branches.
 ```
 
 ## Agent Work
 
-Hermes routes the approved work to a coding backend. The worker edits inside the repository, avoids real `~/.hermes` mutation by using temp dirs in tests, and reports evidence back through Hermes:
+Hermes routes the approved work to a coding backend. The worker edits inside the repository, avoids real home-directory mutation by using temp dirs in tests, and reports evidence back through Hermes:
 
 ```text
 Changed:
@@ -43,35 +51,56 @@ Changed:
 Verification:
 - npm run validate: passed
 - npm run smoke-test: passed
+- npm run workflow-evals: passed
 - npm pack --dry-run: passed
 
 Remaining risk:
 - Cursor, OpenCode, and native Codex/Claude harness adapters remain experimental/manual until their install paths are validated.
 ```
 
+## Phone Approval 3: Implementation Findings
+
+```text
+Proceed with narrow in-scope review fixes.
+Do not broaden provider claims or add release behavior.
+```
+
 ## Superpowers Evidence Or Compensation
 
 ```text
 Superpowers evidence:
 - using-superpowers loaded before work.
+- Brainstorming Gate completed before implementation planning.
 - implementation-plan gate followed.
 - independent review requested with a packet that included untracked files.
+- receiving-code-review intake dispositioned findings before fix loops.
 - verification-before-completion satisfied with fresh command output.
+- finishing-a-development-branch used for closeout options.
 
 Compensation if a required skill/reference is missing:
 - state the missing skill/reference.
 - use the public quality profile and edge-case pack.
+- use brainstorming/spec gates where required.
 - use independent review and final verification before reporting completion.
 ```
 
+## Phone Approval 4: Closeout Option
+
+```text
+Keep the branch/worktree local for controller verification.
+No push, PR, merge, publish, release, deploy, or branch deletion.
+```
+
 ## Final Verification Report
 
 ```text
 Profile:
 Provider/split:
+Superpowers evidence or compensation:
 Files changed:
 Commands and exit statuses:
 Independent review verdict:
+Review-intake dispositions:
 Fixed findings:
 Skipped checks:
 Remaining risks: