Merge pull request #33 from AndreJorgeLopes/feat/wrappers-and-spawn-prompt-fix

feat(skills): brainstorming + executing-plans wrappers; spawn prompt leads with slash command

Author: AndreJorgeLopes

devflow-plugin/.claude-plugin/plugin.json

@@ -24,6 +24,8 @@
     "./skills/visualizations-config/SKILL.md",
     "./skills/dependency-update/SKILL.md",
     "./skills/writing-plans/SKILL.md",
+    "./skills/brainstorming/SKILL.md",
+    "./skills/executing-plans/SKILL.md",
     "./skills/lock-tests/SKILL.md",
     "./skills/phase-handoff/SKILL.md",
     "./skills/best-roi-task/SKILL.md",

devflow-plugin/commands/brainstorming.md

@@ -0,0 +1,40 @@
+---
+description: Devflow wrapper for the upstream brainstorming skill. Use when starting any creative work — creating features, building components, adding functionality, or modifying behavior — to explore user intent, requirements, and design before implementation. Always invoke `/devflow:brainstorming` rather than the upstream skill directly so devflow can layer in project-specific behavior (recall hooks, phase-handoff entry points) without callers ever needing to know about the upstream.
+---
+
+You are the devflow wrapper for the upstream brainstorming workflow. The wrapper exists so the rest of the devflow pipeline (new-feature, spec-feature, etc.) has a single canonical entry point (`/devflow:brainstorming`) and never reaches past it to the upstream skill directly.
+
+## Steps
+
+1. **Delegate to the upstream brainstorming skill.** Invoke `superpowers:brainstorming` via the Skill tool. Pass through `$ARGUMENTS` verbatim so the upstream skill receives the user's original input.
+
+2. **Let the upstream skill drive.** Do NOT layer additional questions, gates, or prompts on top of the upstream flow inside this wrapper — the upstream skill already runs the full requirements/design/approach exploration loop with `AskUserQuestion` gates. Your job is to be a transparent pass-through.
+
+3. **Override the upstream terminal handoff.** The upstream brainstorming skill's documented terminal state is to invoke `superpowers:writing-plans` directly. **Devflow OVERRIDES that** — devflow's pipeline is `brainstorming → spec-feature → writing-plans` (spec lives BETWEEN brainstorming and writing-plans, not skipped). When the upstream brainstorming flow reaches its terminal state (user has approved the design + the spec doc has been written + the user has approved the written spec file), do NOT invoke `superpowers:writing-plans` or any `/writing-plans` slash command. Instead, surface this message and return control:
+
+   ```
+   Brainstorming complete — design approved + spec written and approved.
+
+   Next step in devflow's pipeline: invoke `/devflow:spec-feature` to formalize the spec into the structured devflow spec doc (this is where the spec-feature skill takes the brainstormed design and produces `docs/specs/<feature>.md` + extracts ordered tasks). After that completes, `spec-feature` invokes `devflow:phase-handoff` which spawns a new session for the `/devflow:writing-plans` phase.
+
+   Do NOT run `/writing-plans` or `superpowers:writing-plans` directly — devflow inserts `spec-feature` between brainstorming and writing-plans.
+   ```
+
+   Then exit. Brainstorming → spec-feature happens in the SAME session (no `phase-handoff` between them — phase-handoff fires only at spec → plan, plan → lock-tests, and lock-tests → impl boundaries). The user invokes `/devflow:spec-feature` next.
+
+## Why this wrapper exists
+
+- **Single canonical entry point.** All devflow callers (new-feature.md, future skills) invoke `/devflow:brainstorming` instead of `/brainstorming` or `superpowers:brainstorming`. If devflow ever needs to layer in project context (Hindsight recall, prior-feature memory) before brainstorming starts, that layering happens here without touching call sites.
+- **Consistency with the rest of the devflow pipeline.** Other devflow phases (`writing-plans`, `executing-plans`, `lock-tests`, `phase-handoff`) all have explicit devflow surface. Brainstorming gets the same treatment for symmetry.
+- **Decoupling from upstream API changes.** If `superpowers:brainstorming` is renamed/moved/replaced, only this wrapper needs to update — call sites stay stable.
+
+## Fallback if upstream is unavailable
+
+If `superpowers:brainstorming` is not loaded in the current session (older Claude Code, plugin disabled, etc.), search the available-skills list for variants matching `*brainstorm*`. If none found, surface a clear error: `Upstream brainstorming skill not found. Verify the superpowers plugin is installed (re-run the OMC setup flow or check ~/.claude/plugins/).` Then exit — do NOT attempt to re-implement the brainstorming logic inline.
+
+## Important
+
+- This wrapper is intentionally thin. Resist the temptation to add custom phases here — that lives in the upstream skill, or in dedicated devflow skills (`spec-feature`, `writing-plans`, etc.).
+- Do NOT auto-invoke `/devflow:spec-feature` from inside the brainstorming flow — the upstream skill's HARD-GATE forbids invoking implementation skills before user-approved design exists, and devflow respects that.
+
+$ARGUMENTS

devflow-plugin/commands/executing-plans.md

@@ -0,0 +1,53 @@
+---
+description: Devflow wrapper for the upstream executing-plans skill. Use when you have a written implementation plan to execute task-by-task. ALWAYS invoke `/devflow:executing-plans` rather than the upstream skill directly — this wrapper guarantees that the post-implementation handoff goes to `/devflow:finish-feature` (devflow's verification + PR/MR creation flow) instead of `superpowers:finishing-a-development-branch` (the upstream default, which doesn't integrate with devflow's VCS-coherent finish flow).
+---
+
+You are the devflow wrapper for the upstream executing-plans workflow. The wrapper exists for TWO reasons:
+
+1. **Forced finish-feature handoff.** Upstream `executing-plans` natively chains to `superpowers:finishing-a-development-branch` after the last task. Devflow has its own `/devflow:finish-feature` flow that runs verification, creates a PR/MR via devflow's VCS-coherent logic, and retains learnings to Hindsight. This wrapper intercepts the terminal handoff so the devflow finish flow runs instead.
+2. **Single canonical entry point.** All devflow callers (`lock-tests.md` Phase 2, `phase-handoff.md`'s impl-phase invocation, the resume prompt in a spawned implementation session) invoke `/devflow:executing-plans` instead of `/executing-plans` or `superpowers:executing-plans`. If the upstream skill is renamed/moved/replaced, only this wrapper updates.
+
+## Phase 0 — Locate the upstream skill
+
+1. Try invoking `superpowers:executing-plans` via the Skill tool. If it loads, proceed to Phase 1.
+
+2. **If the upstream skill is missing**, search the available-skills list for variants matching `*executing*plans*` or `*implementing*plans*`. If a variant matches (rename case), use it and warn the user inline: `Note: superpowers:executing-plans renamed to <variant>. Update devflow:executing-plans skill body to point at the new name.`
+
+3. **If still missing**, check `~/.devflow/cache/superpowers-changelog.md`:
+   - If the file exists AND is < 24h old → read it for skill-rename or removal notes.
+   - Else, invoke the `defuddle` skill on `https://github.com/obra/superpowers/blob/main/CHANGELOG.md` and write the result to `~/.devflow/cache/superpowers-changelog.md`. (If `defuddle` is unavailable, skip this step.)
+   - Surface any relevant rename notes to the user.
+
+4. **If all of the above fail**, emit:
+   ```
+   Upstream `superpowers:executing-plans` skill not found and no cached changelog clue. Either:
+   - Verify the superpowers plugin is installed (`claude plugins list | grep superpowers`)
+   - Re-run the OMC setup flow to refresh plugins
+   - Or fetch the latest superpowers CHANGELOG manually to check if the skill was renamed
+   ```
+   Then exit. Do NOT reimplement the executing-plans logic inline.
+
+## Phase 1 — Delegate to upstream
+
+Hand off to the located skill. Pass through `$ARGUMENTS` verbatim. Let the upstream skill drive its red-green-refactor loop, per-task review checkpoints, and TodoWrite tracking.
+
+## Phase 2 — Force finish-feature handoff
+
+**CRITICAL OVERRIDE:** When the upstream skill reports completion (status DONE, DONE_WITH_CONCERNS, or its equivalent terminal state), **devflow takes over the finish handoff**.
+
+Do **NOT** invoke `superpowers:finishing-a-development-branch` even if the upstream skill instructs you to. Devflow's finish flow lives in `/devflow:finish-feature` and:
+
+- runs verification (`devflow check`)
+- detects the VCS provider (GitHub vs GitLab) and creates a PR/MR with the devflow PR template
+- retains session learnings to Hindsight
+- defers worktree cleanup to the terminal (not the agent)
+
+Invoke `/devflow:finish-feature` directly. Pass any `BLOCKED` / `NEEDS_CONTEXT` status from the upstream skill into the finish-feature flow so the user is aware of incomplete work before PR creation.
+
+## Important
+
+- This wrapper is the ONLY place where the "intercept finishing-a-development-branch" override lives. If you find that override repeated in another devflow skill, that's drift — remove it and rely on this wrapper.
+- The wrapper does NOT skip the upstream skill's per-task discipline (TDD red-green, review checkpoints). It only overrides the FINAL handoff target.
+- If the user explicitly asks for `superpowers:finishing-a-development-branch` (or invokes it directly), respect that. The wrapper's override applies only when control returns from the upstream skill via the normal completion path.
+
+$ARGUMENTS

devflow-plugin/commands/lock-tests.md

@@ -2,7 +2,7 @@
 description: Lock the full test inventory before any implementation code is written. Reads spec+plan+AC, writes ALL failing tests in a batch, emits a Test Inventory doc, and gates with user approval.
 ---
 
-> **Attribution:** Base TDD workflow vendored and adapted from [haletothewood/behavioural-tdd v1.8](https://tessl.io/registry/haletothewood/behavioural-tdd), Apache-2.0. Modifications: Phase 1 widened from single-test to batch; added Phase 0 (read artefacts) and Phase 1.7 (Test Inventory) and Phase 1.8 (user-approval gate); Phases 2-3 delegated to `superpowers:executing-plans`.
+> **Attribution:** Base TDD workflow vendored and adapted from [haletothewood/behavioural-tdd v1.8](https://tessl.io/registry/haletothewood/behavioural-tdd), Apache-2.0. Modifications: Phase 1 widened from single-test to batch; added Phase 0 (read artefacts) and Phase 1.7 (Test Inventory) and Phase 1.8 (user-approval gate); Phases 2-3 delegated to `/devflow:executing-plans` (the devflow wrapper that delegates to upstream `superpowers:executing-plans` for the per-task red/green/refactor loop AND forces the post-implementation handoff to `/devflow:finish-feature`).
 
 You are at the test-locking phase of devflow's new-feature pipeline. Your job is to write the full failing-test inventory from the locked spec + plan + AC, then gate on user approval before any production code is written.
 
@@ -48,7 +48,7 @@ You are at the test-locking phase of devflow's new-feature pipeline. Your job is
    - If user skips: invoke `devflow:phase-handoff --phase lock-tests --next-phase impl --no-handoff`. Then print:
 
    ```
-   Trivial change — lock-tests gate skipped. Context is already small; no new session needed for the implementation phase. Invoke `/executing-plans` here (Claude Code auto-exposes the superpowers skill as a slash command; if the picker doesn't surface it on older installs, use the natural-language trigger `Use the superpowers:executing-plans skill to implement the plan task by task` instead).
+   Trivial change — lock-tests gate skipped. Context is already small; no new session needed for the implementation phase. Invoke `/devflow:executing-plans` here (devflow's wrapper around the upstream executing-plans skill; the wrapper forces the post-implementation handoff to go to `/devflow:finish-feature` instead of the upstream's `finishing-a-development-branch`).
    ```
 
    Then exit.
@@ -155,11 +155,11 @@ Use `AskUserQuestion` with:
 
 ## Phase 2 — GREEN (delegated)
 
-After approval, invoke `devflow:phase-handoff --phase lock-tests --next-phase impl`. The handoff skill writes the frozen-state file, gates on a one-click `AskUserQuestion`, then spawns a new Claude Desktop session via `mcp__ccd_session__spawn_task` titled `[<TICKET>] [MR#<N>] Implementation` (visible in the sidebar). The spawned session starts cold; its initial prompt points at the frozen-state file plus absolute artefact paths and instructs it to invoke `/executing-plans` (the superpowers skill auto-exposed as a slash command by Claude Code's plugin runtime), which drives per-task red/green against the tests already locked in this phase.
+After approval, invoke `devflow:phase-handoff --phase lock-tests --next-phase impl`. The handoff skill writes the frozen-state file, gates on a one-click `AskUserQuestion`, then spawns a new Claude Desktop session via `mcp__ccd_session__spawn_task` titled `[<TICKET>] [MR#<N>] Implementation` (visible in the sidebar). The spawned session starts cold; its initial prompt leads with the slash-command invocation `/devflow:executing-plans` (devflow's wrapper around the upstream executing-plans skill — guarantees the post-implementation handoff goes to `/devflow:finish-feature`) and hands it absolute paths to the frozen-state file plus the locked test inventory, which drives per-task red/green against the tests already locked in this phase.
 
 ## Phase 3 — REFACTOR (delegated)
 
-Handled per-task inside `superpowers:executing-plans`, not centrally.
+Handled per-task inside `/devflow:executing-plans` (the devflow wrapper, which delegates to the upstream executing-plans flow), not centrally.
 
 ## Important
 

devflow-plugin/commands/new-feature.md

@@ -65,7 +65,7 @@ You have been launched inside a feature worktree. Your job is to orient yourself
 
    If yes, invoke the `codebase-walkthrough` skill with the feature context. After the walkthrough completes, continue to brainstorming.
 
-6. **Transition to brainstorming.** Once you understand the feature (and optionally completed the walkthrough), invoke the `brainstorming` skill to explore requirements, design, and approach before writing any code.
+6. **Transition to brainstorming.** Once you understand the feature (and optionally completed the walkthrough), invoke `/devflow:brainstorming` (devflow's thin wrapper around the upstream brainstorming skill — always use the devflow surface, never `/brainstorming` or the upstream skill directly) to explore requirements, design, and approach before writing any code.
 
    The full pipeline from here is:
    ```