fix(skills): consistent /devflow:* invocation in phase-handoff + lock-tests attribution + brainstorming terminal-override (Copilot)

Author: AndreJorgeLopes

devflow-plugin/commands/brainstorming.md

@@ -10,7 +10,17 @@ You are the devflow wrapper for the upstream brainstorming workflow. The wrapper
 
 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. **On completion, return control.** The upstream brainstorming skill's terminal state is invoking `superpowers:writing-plans`. Devflow does NOT short-circuit that — when the user is ready to spec, they invoke `/devflow:spec-feature` (devflow's spec-writing wrapper) directly. Brainstorming → spec-feature happens in the SAME session (no `phase-handoff` between them — the phase handoff fires only at spec → plan, plan → lock-tests, and lock-tests → impl boundaries).
+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
 

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.
 

devflow-plugin/commands/phase-handoff.md

@@ -197,6 +197,6 @@ If `--no-handoff` is present, print "phase-handoff skipped" and exit.
 - The CURRENT session stays open after the handoff — `spawn_task` does NOT close it. The user can keep it as an archive/reference and switch to the new session for the next phase.
 - `spawn_task` is a one-shot spawn — it does NOT auto-resume the new session or auto-invoke the next skill. The new session waits in the sidebar for the user to open it; on first open, the agent there sees the `prompt` and acts on it.
 - Group placement is NOT supported by `spawn_task` (no `group`/`groupId` parameter on the MCP tool, and groups are Claude Desktop UI-only metadata). Manual drag-into-group required after spawn.
-- Invocation form per next-phase: `devflow:*` skills use `/devflow:<name>` slash commands; `executing-plans` uses Claude Code's auto-exposed `/executing-plans` slash command (resolves to superpowers' skill) with a natural-language fallback.
+- Invocation form per next-phase: ALL three next-phases use a `/devflow:<name>` slash command (`/devflow:writing-plans`, `/devflow:lock-tests`, `/devflow:executing-plans`). The `executing-plans` slot points at devflow's wrapper, which internally delegates to upstream `superpowers:executing-plans` and forces the post-implementation handoff to `/devflow:finish-feature`. Never hand the spawned session a `/superpowers:*` slash or a natural-language skill trigger — the devflow wrapper is the canonical entry point for every phase.
 
 $ARGUMENTS

devflow-plugin/skills/brainstorming/SKILL.md

@@ -11,7 +11,17 @@ You are the devflow wrapper for the upstream brainstorming workflow. The wrapper
 
 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. **On completion, return control.** The upstream brainstorming skill's terminal state is invoking `superpowers:writing-plans`. Devflow does NOT short-circuit that — when the user is ready to spec, they invoke `/devflow:spec-feature` (devflow's spec-writing wrapper) directly. Brainstorming → spec-feature happens in the SAME session (no `phase-handoff` between them — the phase handoff fires only at spec → plan, plan → lock-tests, and lock-tests → impl boundaries).
+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
 

devflow-plugin/skills/lock-tests/SKILL.md

@@ -3,7 +3,7 @@ name: lock-tests
 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.
 

devflow-plugin/skills/phase-handoff/SKILL.md

@@ -198,6 +198,6 @@ If `--no-handoff` is present, print "phase-handoff skipped" and exit.
 - The CURRENT session stays open after the handoff — `spawn_task` does NOT close it. The user can keep it as an archive/reference and switch to the new session for the next phase.
 - `spawn_task` is a one-shot spawn — it does NOT auto-resume the new session or auto-invoke the next skill. The new session waits in the sidebar for the user to open it; on first open, the agent there sees the `prompt` and acts on it.
 - Group placement is NOT supported by `spawn_task` (no `group`/`groupId` parameter on the MCP tool, and groups are Claude Desktop UI-only metadata). Manual drag-into-group required after spawn.
-- Invocation form per next-phase: `devflow:*` skills use `/devflow:<name>` slash commands; `executing-plans` uses Claude Code's auto-exposed `/executing-plans` slash command (resolves to superpowers' skill) with a natural-language fallback.
+- Invocation form per next-phase: ALL three next-phases use a `/devflow:<name>` slash command (`/devflow:writing-plans`, `/devflow:lock-tests`, `/devflow:executing-plans`). The `executing-plans` slot points at devflow's wrapper, which internally delegates to upstream `superpowers:executing-plans` and forces the post-implementation handoff to `/devflow:finish-feature`. Never hand the spawned session a `/superpowers:*` slash or a natural-language skill trigger — the devflow wrapper is the canonical entry point for every phase.
 
 $ARGUMENTS

skills/brainstorming/SKILL.md

@@ -11,7 +11,17 @@ You are the devflow wrapper for the upstream brainstorming workflow. The wrapper
 
 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. **On completion, return control.** The upstream brainstorming skill's terminal state is invoking `superpowers:writing-plans`. Devflow does NOT short-circuit that — when the user is ready to spec, they invoke `/devflow:spec-feature` (devflow's spec-writing wrapper) directly. Brainstorming → spec-feature happens in the SAME session (no `phase-handoff` between them — the phase handoff fires only at spec → plan, plan → lock-tests, and lock-tests → impl boundaries).
+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
 

skills/lock-tests/SKILL.md

@@ -3,7 +3,7 @@ name: lock-tests
 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.
 

skills/phase-handoff/SKILL.md

@@ -198,6 +198,6 @@ If `--no-handoff` is present, print "phase-handoff skipped" and exit.
 - The CURRENT session stays open after the handoff — `spawn_task` does NOT close it. The user can keep it as an archive/reference and switch to the new session for the next phase.
 - `spawn_task` is a one-shot spawn — it does NOT auto-resume the new session or auto-invoke the next skill. The new session waits in the sidebar for the user to open it; on first open, the agent there sees the `prompt` and acts on it.
 - Group placement is NOT supported by `spawn_task` (no `group`/`groupId` parameter on the MCP tool, and groups are Claude Desktop UI-only metadata). Manual drag-into-group required after spawn.
-- Invocation form per next-phase: `devflow:*` skills use `/devflow:<name>` slash commands; `executing-plans` uses Claude Code's auto-exposed `/executing-plans` slash command (resolves to superpowers' skill) with a natural-language fallback.
+- Invocation form per next-phase: ALL three next-phases use a `/devflow:<name>` slash command (`/devflow:writing-plans`, `/devflow:lock-tests`, `/devflow:executing-plans`). The `executing-plans` slot points at devflow's wrapper, which internally delegates to upstream `superpowers:executing-plans` and forces the post-implementation handoff to `/devflow:finish-feature`. Never hand the spawned session a `/superpowers:*` slash or a natural-language skill trigger — the devflow wrapper is the canonical entry point for every phase.
 
 $ARGUMENTS