continuous-improvement 3.1.0 → 3.9.1

package/plugins/continuous-improvement/commands/proceed-with-the-recommendation.md

@@ -0,0 +1,62 @@
+---
+name: proceed-with-the-recommendation
+description: "Execute the agent's prior recommendation list under the 7 Laws — walk in order, route per item, verify, reflect. Standalone companion skill with inline fallbacks when other skills are not installed."
+---
+
+# /proceed-with-the-recommendation
+
+Walk an agent-generated recommendation list top-to-bottom under the continuous-improvement 7 Laws. Each item is routed to the best specialist skill when available, falls back to concrete inline behavior when it is not.
+
+Invoke immediately after the agent has offered a numbered list of recommendations, next steps, or suggested actions.
+
+## Trigger phrases
+
+- `/proceed-with-the-recommendation`
+- "proceed with your recommendation"
+- "do all of it"
+- "go ahead with the plan"
+- "execute the recommendations"
+- "yes do it" / "all of them"
+
+## What happens
+
+1. **Pre-flight (Law 1)** — restate the recommendation list in original order, tag each `safe` / `caution` / `needs-approval`
+2. **Plan (Law 2)** — inline restatement if ≤3 items, call `superpowers:writing-plans` if larger
+3. **Execute (Law 3)** — route each item to the preferred skill; apply inline fallback if the skill is not installed
+4. **Verify (Law 4)** — smallest check per item, non-transitive (no later item retroactively verifies an earlier one)
+5. **Iterate (Law 6)** — one change → verify → next; never carry a failure forward
+6. **Reflect (Laws 5 + 7)** — end-of-run Reflection block appended to `observations.jsonl`
+7. **Close** — three-section user-facing block: **What has been done → What is next → Recommendation** (tiered tables + one decisive "My recommendation" paragraph + a binary "Want me to: A or B?" closer)
+
+## Hard halts (never silently proceed)
+
+- Any `needs-approval` item: deploy, force-push, DB drop, secret change, shared-state mutation
+- Verification failure with non-obvious fix
+- Drive-by temptation outside the original list
+- Context budget above 80%
+
+## Pairs best with
+
+| Preferred skill | Used for |
+|---|---|
+| `workspace-surface-audit` | Law 1 pre-flight when the list touches unknown surface area |
+| `superpowers:writing-plans` | Plan breakdown when the list >3 items or >150 LOC |
+| `superpowers:*` | Per-item specialist routing (TDD, debugging, review, verification, parallel) |
+| `ralph` | Long-running PRD-style autonomous execution |
+| `simplify`, `security-review`, `documentation-lookup`, `schedule`, `loop`, `update-config`, `commit-commands:*` | continuous-improvement helpers |
+
+If none of those are installed, the skill still works — every routing row has an inline fallback and every item still gets a verification step.
+
+## Skill file
+
+Full behavior is defined in [`skills/proceed-with-the-recommendation.md`](../skills/proceed-with-the-recommendation.md).
+
+## Install standalone
+
+```bash
+mkdir -p ~/.claude/skills/proceed-with-the-recommendation
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/proceed-with-the-recommendation.md \
+  -o ~/.claude/skills/proceed-with-the-recommendation/SKILL.md
+```
+
+Restart the Claude Code session so the registry picks it up.

package/plugins/continuous-improvement/commands/ralph.md

@@ -0,0 +1,103 @@
+---
+name: ralph
+description: "Convert PRD to executable JSON and run autonomous agent loop until all stories complete"
+---
+
+# /ralph
+
+Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete.
+
+## Subcommands
+
+### `/ralph init`
+
+Initialize Ralph in your project:
+
+1. Create `scripts/ralph/` directory
+2. Add `ralph.sh` loop script
+3. Add prompt templates for Amp and Claude Code
+4. Create example `prd.json`
+
+### `/ralph convert <prd-file>`
+
+Convert a markdown PRD to Ralph's executable JSON format:
+
+```
+/ralph convert tasks/prd-auth-feature.md
+```
+
+Output: `prd.json` with structured user stories
+
+### `/ralph run [iterations]`
+
+Run the autonomous loop:
+
+```
+/ralph run 10
+```
+
+Default: 10 iterations. Stops early if all stories complete.
+
+## Ralph Loop Behavior
+
+1. **Create branch** from PRD `branchName`
+2. **Pick highest priority** story where `passes: false`
+3. **Implement story** — fresh context, no pollution
+4. **Run quality checks** — typecheck, tests, lint
+5. **Commit if passing** — atomic commits per story
+6. **Update prd.json** — mark `passes: true`
+7. **Log learnings** — append to `progress.txt`
+8. **Repeat** until done or max iterations
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `prd.json` | Executable PRD with user stories |
+| `progress.txt` | Accumulated learnings |
+| `ralph.sh` | The loop script |
+| `AGENTS.md` | Iteration memory (auto-updated) |
+
+## Workflow Integration
+
+Ralph works best with:
+- **Superpowers** — for structured development stages
+- **continuous-improvement** — for reflection and learning between iterations
+- **workspace-surface-audit** — to verify capabilities before starting
+
+## Critical Concepts
+
+### Fresh Context Per Iteration
+Each story runs in isolation. Previous work is visible only via git history and `prd.json`.
+
+### AGENTS.md Updates
+Ralph updates `AGENTS.md` after each story so subsequent iterations know what's already done.
+
+### Browser Verification
+For UI stories, Ralph starts a dev server and uses Playwright to verify rendering.
+
+### Stop Conditions
+- All stories pass
+- Max iterations reached
+- Critical failure (requires human intervention)
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Ralph stuck | Check `prd.json` for malformed stories |
+| Tests failing | Run `npm test` independently to isolate |
+| Uncommitted changes | Check git status, commit or stash |
+| Wrong tool | Use `--tool amp` or `--tool claude` flag |
+
+## Example Session
+
+```
+User: /ralph convert tasks/prd-checkout.md
+[Creates prd.json with 8 stories]
+
+User: /ralph run 15
+[Ralph creates branch, implements stories 1-8 over 12 iterations]
+
+[All tests pass, branch ready for PR]
+```

package/plugins/continuous-improvement/commands/release-train.md

@@ -0,0 +1,81 @@
+---
+name: release-train
+description: "Autonomous multi-PR release train — plan stacked single-concern PRs, open each on its own branch, monitor CI, rebase on conflicts, and ship in dependency order while you sleep. Driven by report.html horizon item 'Autonomous Multi-PR Release Trains'."
+---
+
+# /release-train
+
+Long-running autonomous orchestrator for stacked-PR rollouts. Driven by the user's session report (1,218 messages, 178 sessions): the audit-then-execute pattern landed at `fully_achieved` when sessions opened with a stacked-PR plan; sessions that started as big-bang multi-file edits landed at `partially_achieved`.
+
+This command formalizes the pattern. It does NOT bypass branch protection, force-push, or merge unreviewed PRs.
+
+## Preconditions
+
+Before invoking this command:
+
+1. A `RELEASE_PLAN.md` (or `docs/plans/YYYY-MM-DD-<slug>.md`) exists in the repo with a per-PR table, dependency graph, worktree-per-PR, and out-of-scope list. Per the Stacked-PR Plan Precondition in the unified `/superpowers` dispatcher.
+2. The plan was reviewed and explicitly approved by the operator.
+3. The base branch (`main`) is clean and up to date with `origin/main`.
+4. CI is green on `origin/main`.
+
+If any precondition fails, this command halts and reports what is missing rather than improvising.
+
+## Behavior
+
+For each PR in the plan, in dependency order:
+
+1. **Worktree** — `git worktree add -b <branch> ../<branch> origin/main` (or off the previous PR's branch when the dependency requires it).
+2. **Implement** — TDD-first per `superpowers:test-driven-development`: failing test, watch it fail, write minimal code, watch it pass, commit.
+3. **Verify** — `superpowers:verification-before-completion` before claiming done. Smallest check that proves correctness.
+4. **Review** — dispatch a fresh subagent for spec-compliance + code-quality two-stage review per `superpowers:subagent-driven-development`. Critical findings block progress.
+5. **Open PR** — `gh pr create --base <base-of-this-PR> --head <branch>` with single-concern description that cites the plan doc.
+6. **Wait for CI** — poll until green. Auto-rebase on conflicts (max 2 attempts; halt on third).
+7. **Address review** — `superpowers:receiving-code-review` to walk reviewer comments. Critical findings produce a fix commit; non-critical are logged on the PR.
+8. **Merge when green and approved** — never bypass branch protection. If branch protection blocks, post a status comment and continue with the next independent PR.
+9. **Deploy receipt** — when the merged branch is on an auto-deploy target, run `deploy-receipt` to verify deployed SHA matches merge SHA + healthcheck 200 before reporting the PR as done.
+
+Logs every state transition to `release-train.log` in the repo root.
+
+## Stop conditions
+
+Halt and surface to the operator if any of these occur:
+
+- A `CRITICAL` reviewer finding cannot be auto-resolved.
+- Two consecutive auto-rebase attempts fail on the same PR.
+- A PR has been waiting on CI for more than 30 minutes.
+- A required check (branch protection, status check, required reviewer) blocks merge.
+- A deploy-receipt times out or returns non-200.
+- The plan's dependency graph becomes unsatisfiable (e.g. a dependency PR was closed unmerged).
+
+When halted, write a state file to `release-train.halt.md` describing exactly which PR halted, why, and what the operator needs to decide before resuming.
+
+## Resuming
+
+Re-invoke `/release-train` after the halt is resolved. The orchestrator reads `release-train.log` and `release-train.halt.md` to skip already-merged PRs and resume from the halt point.
+
+## Composition
+
+This command activates the unified `/superpowers` dispatcher and routes through:
+
+- `superpowers:writing-plans` (or its inline fallback) to validate the plan
+- `superpowers:using-git-worktrees` for isolation per PR
+- `superpowers:test-driven-development` for implementation
+- `superpowers:subagent-driven-development` for two-stage review
+- `superpowers:finishing-a-development-branch` for merge decisions
+- `deploy-receipt` (CI-bundled) for production verification
+- `proceed-with-the-recommendation` orchestrator to walk the plan's PR list
+
+## Anti-patterns this command refuses
+
+- **Big-bang merge.** Will not merge a PR that touches more than 15 non-generated files.
+- **Bypass.** Will not use `--admin`, `--force`, or `--no-verify`.
+- **Speculative fix during CI wait.** Will not push speculative fixes during the first-time-contributor workflow-approval gate.
+- **Drive-by scope.** Will not add a fix outside the plan's scope; logs as deferred follow-up instead.
+
+## Example
+
+```
+/release-train docs/plans/2026-05-07-unified-five-plugin-dispatcher.md
+```
+
+Reads the plan, opens worktrees in dependency order, ships each PR through the full discipline, halts only at policy gates.

package/plugins/continuous-improvement/commands/seven-laws.md

@@ -0,0 +1,16 @@
+---
+name: seven-laws
+description: "Brand-aligned alias for /continuous-improvement. Reflect on the current session, analyze observations for patterns, and show instinct status under the 7 Laws of AI Agent Discipline."
+---
+
+# /seven-laws
+
+Brand-aligned alias for [`/continuous-improvement`](continuous-improvement.md). Both commands run the exact same three-step workflow under the 7 Laws of AI Agent Discipline:
+
+1. **Reflect** (Law 5) — generate a reflection block for this session.
+2. **Analyze** (Law 7) — process pending observations into instincts.
+3. **Status** — show all instincts for the project + global with confidence and current level.
+
+Run the workflow defined in [`continuous-improvement.md`](continuous-improvement.md). Subcommands `weekly` and `always-on` work identically.
+
+`/continuous-improvement` remains supported indefinitely for backward compatibility. Prefer `/seven-laws` going forward — it matches the brand and the SKILL.md spec.

package/plugins/continuous-improvement/commands/superpowers.md

@@ -0,0 +1,180 @@
+---
+name: superpowers
+description: "Law activator and dispatcher — route the task to the right Law-aligned specialist across continuous-improvement and four vendored upstream skill libraries (Obra superpowers, addy-agent-skills, ruflo-swarm, oh-my-claudecode)."
+---
+
+# /superpowers
+
+`/superpowers` is **the dispatcher**, not a peer skill. It does not do work itself; it routes each user task to the correct Law-aligned specialist so the right discipline fires automatically instead of the agent skipping a step.
+
+The 7 Laws define *what* discipline must be applied. `/superpowers` decides *which specialist* enforces it for this specific task, across five sources installed from this marketplace.
+
+## Routing surface (five sources)
+
+| Source | Where it lives | Examples of what it routes to |
+|---|---|---|
+| `continuous-improvement` (this plugin) | bundled — always present | `gateguard` (Law 1), `tdd-workflow` (Law 3+4), `verification-loop` (Law 4), `wild-risa-balance` (Law 2), `safety-guard` (Law 3), `proceed-with-the-recommendation` (all 7), `ralph` (Law 6), `workspace-surface-audit` (Law 1) |
+| `obra/superpowers` (Jesse Vincent) | vendored at `third-party/superpowers/`, pinned SHA `f2cbfbe` (v5.1.0) | `superpowers:brainstorming`, `:writing-plans`, `:executing-plans`, `:test-driven-development`, `:systematic-debugging`, `:requesting-code-review`, `:receiving-code-review`, `:verification-before-completion`, `:dispatching-parallel-agents`, `:using-git-worktrees`, `:finishing-a-development-branch`, `:subagent-driven-development`, `:writing-skills`, `:using-superpowers` |
+| `addyosmani/agent-skills` | vendored at `third-party/addy-agent-skills/`, pinned SHA `742dca5` (v1.0.0) | `spec-driven-development`, `source-driven-development`, `context-engineering`, `idea-refine`, `incremental-implementation`, `code-review-and-quality`, `code-simplification`, `security-and-hardening`, `debugging-and-error-recovery`, `performance-optimization`, `api-and-interface-design`, `frontend-ui-engineering`, `browser-testing-with-devtools`, `ci-cd-and-automation`, `deprecation-and-migration`, `documentation-and-adrs`, `git-workflow-and-versioning`, `planning-and-task-breakdown`, `shipping-and-launch` |
+| `ruflo-swarm` (ruvnet) | vendored at `third-party/ruflo-swarm/`, pinned SHA `addb5cd` (v0.2.0) | `swarm-init`, `monitor-stream`; `swarm_*` and `agent_*` MCP tools; `/swarm`, `/watch` |
+| `oh-my-claudecode` (Yeachan-Heo) | vendored at `third-party/oh-my-claudecode/`, pinned SHA `aacde3e` (v4.13.6) | 39 skills + 19 agents — `release`, `ultrawork`, `ultraqa`, `team`, `trace`, `visual-verdict`, `debug`, `deep-dive`, `deep-interview`, `autopilot`, `autoresearch`, plus a separate `ralph` (overlaps with our `/ralph` — see "Distinct variants" below) |
+
+PM coverage (product-management skills) lives **outside** this marketplace. If you need it, install [`phuryn/pm-skills`](https://github.com/phuryn/pm-skills) separately via Claude Code's host marketplace; the dispatcher names it as a routing target without pre-resolving the namespace. See [docs/THIRD_PARTY.md § Routing in /superpowers](../docs/THIRD_PARTY.md#routing-in-superpowers).
+
+## Distinct variants — never collapse them
+
+Two routing targets carry the same short name across sources. Treat them as distinct; do not silently substitute one for the other.
+
+| Short name | `obra/superpowers` (Obra) | `continuous-improvement` (CI fork) |
+|---|---|---|
+| `superpowers` (skill) | activator routing into Obra skills | `superpowers` skill in this repo: Law-aligned activator wrapping the dispatcher commitments below |
+| `ralph` | not present in Obra | bundled here; `oh-my-claudecode` ships its own `ralph` — pick deliberately, do not auto-merge |
+
+If both Obra `superpowers` and continuous-improvement are loaded, you can call either explicitly: `superpowers:test-driven-development` (Obra) or `tdd-workflow` (CI). Same Law (3+4), different implementation depth.
+
+## Dispatcher commitments (override looser global defaults when `/superpowers` is in scope)
+
+When this dispatcher is active for a task, these six rules apply over any looser convention:
+
+1. **Subagent-driven development is the default for non-trivial tasks.** Two-stage spec + quality review per [obra/superpowers § subagent-driven-development](https://github.com/obra/superpowers).
+2. **Parallel fan-out goes through `superpowers:dispatching-parallel-agents`** (or `/swarm`), not hand-rolled `Task` calls.
+3. **TDD runs RED → GREEN → REFACTOR.** Code written before its test is **deleted**, not retrofitted. Routes to `tdd-workflow` (CI) or `superpowers:test-driven-development` (Obra) — pick by depth, never both for the same task.
+4. **Branch isolation is `using-git-worktrees`** by default for any task that touches more than one file.
+5. **`finishing-a-development-branch` runs before any push.** No bypass via `--no-verify`, `--force`, or direct push to `main`.
+6. **Obra `superpowers` and `continuous-improvement:superpowers` stay distinct.** Both can be installed; neither shadows the other; the dispatcher names which one is firing.
+
+## Routing rules (which source wins)
+
+| User intent | Preferred routing target | Source |
+|---|---|---|
+| New feature, vague requirements | `superpowers:brainstorming` → `:writing-plans` | `obra/superpowers` |
+| Fix this bug | `superpowers:systematic-debugging` → `tdd-workflow` (RED first) → `verification-loop` | Obra → CI → CI |
+| Walk an agent's recommendation list | `proceed-with-the-recommendation` | CI |
+| Write tests for new code | `tdd-workflow` (CI default) or `superpowers:test-driven-development` (Obra, deeper) | CI / Obra |
+| Verify before reporting "done" | `verification-loop` | CI |
+| Refactor, multi-file | `superpowers:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `:finishing-a-development-branch` | Obra → Obra → CI → Obra |
+| Long autonomous PRD execution | `/ralph` (CI variant) | CI |
+| Parallel sub-agent fan-out | `superpowers:dispatching-parallel-agents` or `/swarm` | Obra / ruflo-swarm |
+| Spec-first, contract-first feature | `spec-driven-development` | addy-agent-skills |
+| Frontend / UI generation | `frontend-design` (external plugin) | external |
+| Diff walk + severity tagging | `code-review` (external plugin) or `superpowers:requesting-code-review` | external / Obra |
+| Library / framework docs lookup | `documentation-lookup` (Context7 MCP) | external |
+| Compliance / security gate | `security-and-hardening` (addy) → `security-review` (host built-in) | addy → host |
+| Release coordination across PRs | `/release-train` | CI |
+
+## Missing-companion detection
+
+If `/superpowers` is asked to route to a source that is not installed, it does not silently fall back to the inline placeholder. It must:
+
+1. **Name the missing source** explicitly (e.g. `obra/superpowers` not loaded).
+2. **Quote the exact install line** for it from the marketplace already added in setup, e.g. `/plugin install superpowers@continuous-improvement`.
+3. **State the inline-fallback equivalent** that will run if the user declines to install (and which Law that fallback enforces).
+4. **Stop and ask** before continuing. Do not silently downgrade.
+
+This is the same hard-halt discipline used by `proceed-with-the-recommendation` for `needs-approval` items.
+
+## Subcommands
+
+### `/superpowers status`
+
+Show which routing sources are loaded, which workflow stages are active for the current task, and which sources are **missing**:
+
+```
+=== Superpowers Status ===
+
+Sources:
+  [x] continuous-improvement       (bundled)
+  [x] obra/superpowers              v5.1.0 (vendored)
+  [ ] addyosmani/agent-skills       MISSING — /plugin install agent-skills@continuous-improvement
+  [x] ruflo-swarm                   v0.2.0 (vendored)
+  [ ] oh-my-claudecode              MISSING — /plugin install oh-my-claudecode@continuous-improvement
+
+Active for current task:
+  [x] brainstorming (trigger: new feature request)
+  [ ] using-git-worktrees (waiting: design approval)
+  [ ] writing-plans (waiting: worktree ready)
+  [ ] test-driven-development (waiting: plan approved)
+  [ ] requesting-code-review (waiting: implementation)
+  [ ] finishing-a-development-branch (waiting: completion)
+```
+
+### `/superpowers enable <skill>`
+
+Explicitly enable a skill for the current session — useful when the dispatcher's intent detection guesses wrong:
+
+```
+/superpowers enable test-driven-development
+/superpowers enable superpowers:writing-plans   # namespaced form for Obra
+```
+
+### `/superpowers workflow <type>`
+
+Activate a complete workflow preset:
+
+| Preset | Skills activated (in order) |
+|---|---|
+| `new-feature` | `superpowers:brainstorming` → `:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `verification-loop` → `:requesting-code-review` → `:finishing-a-development-branch` |
+| `bug-fix` | `superpowers:systematic-debugging` → `verification-loop` → `tdd-workflow` (regression test first) → `:requesting-code-review` |
+| `refactor` | `superpowers:using-git-worktrees` → `:writing-plans` → `tdd-workflow` → `:requesting-code-review` → `:finishing-a-development-branch` |
+| `review` | `superpowers:requesting-code-review` → `:receiving-code-review` |
+| `release` | `/release-train` → `verification-loop` → `superpowers:finishing-a-development-branch` |
+
+Example:
+```
+/superpowers workflow new-feature
+```
+
+## Verification protocol (Law 4)
+
+Every routed skill must verify before reporting completion. The dispatcher refuses to advance to the next stage until the current one shows:
+
+1. Code runs without errors
+2. Output matches expected result
+3. Actual result checked — not assumed
+4. Build passes
+5. Change explainable in one sentence
+
+This is `verification-loop` from `continuous-improvement`. It runs after every workflow stage, not just at the end.
+
+## Integration
+
+`/superpowers` integrates with:
+
+- **`/seven-laws`** — runs after each stage to capture the reflection block and update instincts (Laws 5 + 7)
+- **`/proceed-with-the-recommendation`** — orchestrates a list of recommendations end-to-end, using `/superpowers` per item
+- **`/workspace-surface-audit`** — runs at task start to confirm the right routing surface is actually present (Law 1 pre-flight)
+- **`/ralph`** — autonomous variant; takes a PRD and walks it story-by-story under the same routing table
+
+## Example session
+
+```
+User: "Build a checkout flow"
+
+[/superpowers status] →
+  Sources: continuous-improvement [x], obra/superpowers [x], others [ ]
+  Routing intent: new-feature
+
+[brainstorming activates — obra/superpowers]
+AI: "Clarifying questions: 1) Payment provider? 2) Guest checkout?"
+
+User: "Stripe, yes guest checkout"
+
+[using-git-worktrees activates — obra/superpowers]
+AI: "Created worktree at ../checkout-feature"
+
+[writing-plans activates — obra/superpowers]
+AI: "Plan created with 6 tasks. Approve?"
+
+User: "Approved"
+
+[tdd-workflow activates — continuous-improvement]
+AI: "Task 1 RED: write failing test for cart validation..."
+AI: "Task 1 GREEN: minimal handler. Verifying with `npm test cart.test.ts`..."
+AI: "Task 1 REFACTOR: extract validator, tests still green. Committing."
+
+[verification-loop activates — continuous-improvement]
+AI: "Build [x] Types [x] Lint [x] Tests 42/42 [x] Security scan clean [x]"
+
+[finishing-a-development-branch activates — obra/superpowers]
+AI: "Options: merge / PR / keep / discard?"
+```

package/plugins/continuous-improvement/commands/swarm.md

@@ -0,0 +1,101 @@
+---
+name: swarm
+description: "Fan out N parallel sub-agents on isolated worktrees with a shared contract test, produce a comparison report. Driven by report.html horizon item 'Parallel Provider-Migration Agents' — pick winners from real evidence instead of discovering tier limits in production."
+---
+
+# /swarm
+
+Parallel-agent fan-out for evidence-based decision-making. Driven by the user's session report: provider-swap epics (Trading Economics → Forex Factory, ETF → CFD, Finnhub → R StocksTrader, Stooq removal) each took multiple sessions and hit fallback bugs in production because alternatives were not vetted upfront.
+
+This command does not replace the `superpowers:dispatching-parallel-agents` skill — it builds on top of it with a contract-pinned, worktree-isolated, comparison-report shape.
+
+## When to use
+
+The right trigger is "I need to pick between N options and I have a contract test that defines what 'works' means." Examples:
+
+- Evaluating N candidate providers behind a shared interface (the report's recurring need)
+- Trying N candidate refactors against the same test suite
+- Prototyping N candidate library upgrades and measuring which breaks the fewest tests
+- Generating N candidate UI designs that all pass the same accessibility + performance budget
+
+Do NOT use this command for:
+
+- Open-ended exploration without a contract — use `superpowers:brainstorming` instead
+- Single-implementation tasks — use the `superpowers:dispatching-parallel-agents` skill directly
+- Tasks where the candidates have different contracts — that is N separate jobs, not a swarm
+
+## Preconditions
+
+1. A shared contract test exists at a path the agents can reference (e.g. `tests/contracts/<name>.test.ts`).
+2. Candidates are listed up front (3-6 typical; 8 max). Letting agents propose candidates is allowed but the list freezes before fan-out.
+3. The base branch is clean.
+4. Each candidate has a clear evaluation rubric: PASS/FAIL per contract test, plus per-candidate measurements (latency, coverage, cost, free-tier limits, etc. — domain-specific).
+
+## Behavior
+
+1. **Plan** — restate the objective, list candidates, confirm contract test path. If unclear, halt and ask.
+2. **Bootstrap** — for each candidate, create an isolated worktree off `origin/main`: `git worktree add -b swarm/<objective>-<candidate> ../<candidate>`. Pin the base SHA in the swarm log.
+3. **Fan out** — dispatch one fresh sub-agent per candidate via the `Agent` tool, in a single message (parallel, not serial). Each agent receives the contract test path, the candidate name, the rubric, and the worktree path.
+4. **Run** — each agent implements the candidate behind the shared interface, runs the contract test against it, captures measurements per the rubric, and writes findings to `reports/<objective>/<candidate>.md`.
+5. **Synthesize** — when all agents complete, this command produces a decision matrix (candidates × rubric metrics) and recommends a winner with citations to the per-candidate reports.
+6. **Stop** — does NOT merge any candidate's worktree. Does NOT modify production. Output is evidence; the operator decides which candidate to advance.
+
+## Topology
+
+The default topology is **flat fan-out** — all agents run in parallel, no inter-agent communication. This matches the report's actual gap (provider migrations were each independent prototypes).
+
+When `ruflo-swarm` is installed (`/plugin install ruflo-swarm@continuous-improvement`), an alternate topology becomes available: `hierarchical-mesh` with a coordinator role brokering stage hand-off. Activate via `/swarm --topology hierarchical-mesh`.
+
+Available topologies (when ruflo-swarm installed):
+
+| Topology | When to use |
+|---|---|
+| `flat` (default) | Independent prototypes, no shared state |
+| `hierarchical` | One coordinator + N workers; workers report to coordinator only |
+| `mesh` | Workers can share intermediate findings |
+| `hierarchical-mesh` | Coordinator plus worker-to-worker chat |
+| `ring` | Each worker hands off to the next; sequential within a parallel start |
+| `star` | All workers report to a central evaluator that filters before synthesis |
+| `adaptive` | Topology selected per-step based on intermediate findings |
+
+## Stop conditions
+
+Halt and surface to the operator if:
+
+- Any agent reports the contract test is itself broken (test suite is the source of truth; if it is wrong, no candidate can win).
+- A candidate's evaluation reveals the rubric is incomplete (a metric the rubric doesn't measure changes the answer).
+- More than 50% of agents fail to produce a report (likely environment or harness issue, not candidate quality).
+- The winner-by-rubric and the reports' qualitative findings disagree (surface the conflict; do not paper over it).
+
+## Stream observation
+
+Long swarm runs feel opaque. When `ruflo-swarm:monitor-stream` is installed, this command emits live progress events to a stream the operator can tail. Without it, this command writes per-step lines to `reports/<objective>/swarm.log` that can be tailed with `tail -f`.
+
+## Composition
+
+This command activates the unified `/superpowers` dispatcher and routes through:
+
+- `superpowers:dispatching-parallel-agents` for the fan-out shape
+- `ruflo-swarm:swarm-init` (when installed) for contract-pinned bootstrap
+- `ruflo-swarm:monitor-stream` (when installed) for stream observation
+- `superpowers:writing-plans` (or inline fallback) for the candidate list + rubric
+- `proceed-with-the-recommendation` for walking the synthesis output as a recommendation list
+
+## Anti-patterns this command refuses
+
+- **Letting one candidate run before others start.** All worktrees and agents bootstrap together; no early-bird advantage.
+- **Modifying the contract test mid-run.** Test is source of truth; halt instead.
+- **Picking a winner without measurements.** The synthesis must cite the rubric, not just the agents' summaries.
+- **Merging any worktree.** Output is evidence; operator decides advancement.
+
+## Example
+
+```
+/swarm "Pick the next market data provider"
+
+Candidates: Swissquote, R StocksTrader, Twelve Data, Finnhub
+Contract: tests/contracts/provider-contract.test.ts
+Rubric: PASS/FAIL per contract test, p50/p99 latency, symbol coverage for 50 tracked instruments, free-tier limits, monthly cost at expected volume
+```
+
+The orchestrator opens four worktrees, runs four agents in parallel, produces `reports/market-data-provider/{swissquote,rstockstrader,twelve-data,finnhub}.md`, and a `decision-matrix.md` with the recommended winner cited from the rubric.

package/plugins/continuous-improvement/commands/workspace-surface-audit.md

@@ -0,0 +1,77 @@
+---
+name: workspace-surface-audit
+description: "Audit workspace capabilities and recommend continuous-improvement-native skills, hooks, and workflows"
+---
+
+# /workspace-surface-audit
+
+Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup. Returns a 5-section report with specific next moves.
+
+## Usage
+
+```
+/workspace-surface-audit
+```
+
+## What It Checks
+
+1. **Repo surface** — `package.json`, lockfiles, framework config, `.mcp.json`, `.claude/settings*.json`, `AGENTS.md`
+2. **Environment surface** — `.env*` files (key names only, no secrets)
+3. **Connected tools** — installed plugins, MCP servers, LSPs, app integrations
+4. **continuous-improvement surface** — existing skills, commands, hooks, agents
+
+## Output Format
+
+```
+=== Workspace Surface Audit ===
+
+## Current Surface
+- [What is usable right now]
+
+## Parity
+- [Where continuous-improvement matches or exceeds benchmarks]
+
+## Primitive-Only Gaps
+- [Tools exist, but continuous-improvement lacks clean operator skills]
+
+## Missing Integrations
+- [Capabilities not available yet]
+
+## Top 3-5 Next Moves
+1. [Concrete continuous-improvement-native addition]
+2. [Ordered by impact]
+```
+
+## Rules
+
+- **Never print secrets** — only provider names, capability names, file paths
+- **Prefer continuous-improvement** over generic "install another plugin" advice
+- **Organize by workflows**, not API brands
+- **Specific recommendations** — concrete enough to implement without another discovery pass
+
+## Example Output
+
+```
+## Current Surface
+- MCP: filesystem, github, playwright
+- Plugins: beginner, expert (continuous-improvement)
+- Env: STRIPE_API_KEY, FAL_KEY configured
+- Framework: Next.js 15, React 19, TypeScript
+
+## Parity
+- Continuous improvement: covered (native)
+- Testing discipline: covered (TDD workflows)
+
+## Primitive-Only Gaps
+- Stripe connected but no billing-operator skill
+- GitHub MCP available but no issue-triage workflow
+
+## Missing Integrations
+- No Linear connector detected
+- No Slack webhook configured
+
+## Top 3-5 Next Moves
+1. Create billing-operator skill (Stripe integration)
+2. Create github-ops workflow for issue triage
+3. Add Linear connector skill for project management
+```