@tgoodington/intuition 5.0.0 → 6.0.0

package/skills/intuition-handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: intuition-handoff
-description: Universal phase transition orchestrator. Processes phase outputs, updates project memory, generates fresh briefs for next agent.
+description: Universal phase transition orchestrator. Processes phase outputs, updates project memory, generates fresh briefs for next agent. Manages the design loop for multi-item design cycles.
 model: haiku
 tools: Read, Write, Glob, Grep, AskUserQuestion
 allowed-tools: Read, Write, Glob, Grep
@@ -20,9 +20,10 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 4. You MUST generate a brief for the next agent.
 5. You MUST update `.project-memory-state.json` — you are the ONLY skill that writes to this file.
 6. You MUST NOT evaluate or critique phase outputs. Process and document, never judge.
-7. You MUST NOT skip the user profile merge step during discovery→planning transitions.
+7. You MUST NOT skip the user profile merge step during prompt→planning transitions.
 8. You MUST suggest the correct next skill after completing the transition.
-9. You MUST NOT modify discovery_brief.md, plan.md, or other phase output files — they are read-only inputs.
+9. You MUST NOT modify discovery_brief.md, plan.md, design_spec_*.md, or other phase output files — they are read-only inputs.
+10. You MUST manage the design loop: track which items are designed, route to next item or to execute when all are done.
 
 ## PROTOCOL: COMPLETE FLOW
 
@@ -33,7 +34,7 @@ Step 1: Read .project-memory-state.json and detect transition type
 Step 2: Read phase output files
 Step 3: Extract insights and structure findings
 Step 4: Update memory files (key_facts.md, decisions.md, issues.md)
-Step 5: Merge user profile learnings (discovery→planning only)
+Step 5: Merge user profile learnings (prompt→planning only)
 Step 6: Generate brief for next agent
 Step 7: Update .project-memory-state.json
 Step 8: Report what was processed and suggest next skill
@@ -44,13 +45,20 @@ Step 8: Report what was processed and suggest next skill
 Read `docs/project_notes/.project-memory-state.json` and determine:
 
 ```
-IF workflow.status == "discovery" AND discovery.completed == true
+IF workflow.status == "prompt" AND prompt.completed == true
    AND planning.started == false:
-   → TRANSITION: Discovery → Planning
+   → TRANSITION: Prompt → Planning
 
 IF workflow.status == "planning" AND planning.completed == true
-   AND execution.started == false:
-   → TRANSITION: Planning → Execution
+   AND design.started == false:
+   → TRANSITION: Planning → Design (initial setup)
+
+IF workflow.status == "design":
+   → Check design.items array
+   → IF current item just completed AND more items remain:
+      → TRANSITION: Design → Design (next item)
+   → IF all items completed:
+      → TRANSITION: Design → Execution
 
 IF workflow.status == "executing" AND execution.completed == true:
    → TRANSITION: Execution → Complete
@@ -65,11 +73,14 @@ This is the authoritative schema for `.project-memory-state.json`:
 
 ```json
 {
+  "initialized": true,
+  "version": "3.0",
   "workflow": {
-    "status": "discovery | planning | executing | complete",
-    "discovery": {
+    "status": "none | prompt | planning | design | executing | complete",
+    "prompt": {
       "started": false,
       "completed": false,
+      "started_at": null,
       "completed_at": null,
       "output_files": []
     },
@@ -79,6 +90,13 @@ This is the authoritative schema for `.project-memory-state.json`:
       "completed_at": null,
       "approved": false
     },
+    "design": {
+      "started": false,
+      "completed": false,
+      "completed_at": null,
+      "items": [],
+      "current_item": null
+    },
     "execution": {
       "started": false,
       "completed": false,
@@ -90,9 +108,24 @@ This is the authoritative schema for `.project-memory-state.json`:
 }
 ```
 
-When updating state, preserve all existing fields and only modify the relevant ones. Always set `last_handoff` to the current ISO timestamp and `last_handoff_transition` to the transition name (e.g., "discovery→planning").
+### Design Items Schema
 
-## TRANSITION 1: DISCOVERY → PLANNING
+Each item in `design.items` has this structure:
+
+```json
+{
+  "name": "item_name_snake_case",
+  "display_name": "Human Readable Item Name",
+  "status": "pending | in_progress | completed | skipped",
+  "plan_tasks": [3, 4, 5],
+  "spec_file": null,
+  "flagged_reason": "Why plan flagged this for design"
+}
+```
+
+When updating state, preserve all existing fields and only modify the relevant ones. Always set `last_handoff` to the current ISO timestamp and `last_handoff_transition` to the transition name.
+
+## TRANSITION 1: PROMPT → PLANNING
 
 ### Read Outputs
 
@@ -122,7 +155,7 @@ If `docs/project_notes/discovery_output.json` contains `user_profile_learnings`
    - Always update `metadata.last_updated`
 3. Save updated profile
 
-If USER_PROFILE.json does NOT exist, skip this step. Do NOT create it from scratch — that's the user's responsibility.
+If USER_PROFILE.json does NOT exist, skip this step. Do NOT create it from scratch.
 
 ### Generate Planning Brief
 
@@ -162,7 +195,7 @@ Write `docs/project_notes/planning_brief.md`:
 {
   "workflow": {
     "status": "planning",
-    "discovery": { "completed": true, "completed_at": "[ISO timestamp]" },
+    "prompt": { "completed": true, "completed_at": "[ISO timestamp]" },
     "planning": { "started": true }
   }
 }
@@ -172,22 +205,203 @@ Write `docs/project_notes/planning_brief.md`:
 
 Tell the user: "Discovery processed. Planning brief saved to `docs/project_notes/planning_brief.md`. Run `/intuition-plan` to create a structured plan."
 
-## TRANSITION 2: PLANNING → EXECUTION
+## TRANSITION 2: PLANNING → DESIGN (Initial Setup)
 
 ### Read Outputs
 
 Read: `docs/project_notes/plan.md`
 
+### Extract Design Items
+
+From the plan, find the "Design Recommendations" section. Extract all items flagged for design, along with their rationale and associated task numbers.
+
+If no "Design Recommendations" section exists in the plan, check each task: if any task lacks sufficient detail for execution (ambiguous implementation path, multiple valid approaches, user-facing decisions needed), flag it yourself. Present your assessment to the user.
+
 ### Extract and Structure
 
-From the plan, identify:
-- **Task structure** → reference in execution brief
+From the plan, also identify:
 - **New architectural decisions** → create ADRs in `decisions.md`
-- **Risks and dependencies** → include in execution brief
+- **Risks and dependencies** → include in design brief
 - **Planning work completed** → log in `issues.md`
 
-Do NOT update `key_facts.md` — planning doesn't discover new facts.
-Do NOT update `bugs.md` — execution finds bugs, not planning.
+### Present Design Items to User
+
+Use AskUserQuestion to present the flagged items and get user confirmation:
+
+```
+Question: "Plan recommends design exploration for these items:
+
+[For each flagged item:]
+- **[Item Name]** (Tasks [N, M]): [Rationale from plan]
+
+Which items need design? You can also add items not listed."
+
+Header: "Design Items"
+Options:
+- "All recommended items need design"
+- "Some items — let me specify"
+- "None — skip design, go straight to execution"
+```
+
+If user selects "Some items," ask a follow-up to identify which ones.
+If user selects "None," skip to generating an execution brief instead (use Transition 4B below).
+
+### Generate Design Brief
+
+Write `docs/project_notes/design_brief.md` for the FIRST item:
+
+```markdown
+# Design Brief: [First Item Name]
+
+## Current Item
+**[Item Name]** — [Brief description from plan]
+
+## Plan Context
+[1-2 paragraph summary of what the plan says about this item]
+
+## Task Details
+- **Plan Tasks**: [Task numbers]
+- **Description**: [From plan.md]
+- **Acceptance Criteria**: [From plan.md]
+- **Dependencies**: [From plan.md]
+
+## Design Rationale
+[Why plan flagged this for design — what needs elaboration before execution]
+
+## Constraints
+- [From plan's architectural decisions]
+- [From discovery constraints]
+
+## Design Queue
+[For each item, show status:]
+- **[Item 1 Name] (current)**
+- [Item 2 Name] (pending)
+- [Item 3 Name] (pending)
+
+## References
+- Plan: docs/project_notes/plan.md
+- Discovery: docs/project_notes/discovery_brief.md
+```
+
+### Update State
+
+```json
+{
+  "workflow": {
+    "status": "design",
+    "planning": { "completed": true, "completed_at": "[ISO timestamp]", "approved": true },
+    "design": {
+      "started": true,
+      "items": [
+        {
+          "name": "[snake_case_name]",
+          "display_name": "[Human Name]",
+          "status": "pending",
+          "plan_tasks": [3, 4, 5],
+          "spec_file": null,
+          "flagged_reason": "[reason]"
+        }
+      ],
+      "current_item": "[first_item_snake_case_name]"
+    }
+  }
+}
+```
+
+Mark the first item's status as `"in_progress"`.
+
+### Route User
+
+Tell the user: "Plan processed. Design brief prepared for **[First Item Name]**. Run `/intuition-design` to begin design exploration."
+
+## TRANSITION 3: DESIGN → DESIGN (Next Item)
+
+### Read Outputs
+
+Read:
+- The design spec that was just saved: `docs/project_notes/design_spec_[completed_item].md`
+- Current `.project-memory-state.json`
+
+### Extract and Structure
+
+From the completed design spec:
+- **New architectural decisions** → create ADRs in `decisions.md`
+- **Key technical facts** → add to `key_facts.md`
+- **Design work completed** → log in `issues.md`
+
+### Determine Next Item
+
+Read `design.items` from state. Find the next item with status `"pending"`. If no pending items remain, this is actually Transition 4 — proceed to Design → Execution.
+
+### Update Design Brief
+
+Overwrite `docs/project_notes/design_brief.md` with the next item's context:
+
+```markdown
+# Design Brief: [Next Item Name]
+
+## Current Item
+**[Next Item Name]** — [Brief description from plan]
+
+## Plan Context
+[1-2 paragraph summary for this item]
+
+## Task Details
+[Same structure as Transition 2]
+
+## Design Rationale
+[Why this item needs design]
+
+## Prior Design Context
+[1-2 sentences about what was designed in previous items that may be relevant]
+
+## Constraints
+[Updated constraints including any decisions from prior design items]
+
+## Design Queue
+- [x] [Item 1 Name] (completed) → design_spec_[item1].md
+- **[Item 2 Name] (current)**
+- [ ] [Item 3 Name] (pending)
+
+## References
+- Plan: docs/project_notes/plan.md
+- Prior design specs: [list completed spec files]
+```
+
+### Update State
+
+```json
+{
+  "design": {
+    "items": [
+      { "name": "item_1", "status": "completed", "spec_file": "design_spec_item_1.md" },
+      { "name": "item_2", "status": "in_progress", "spec_file": null },
+      { "name": "item_3", "status": "pending", "spec_file": null }
+    ],
+    "current_item": "item_2"
+  }
+}
+```
+
+### Route User
+
+Tell the user: "[Previous Item] design complete. Design brief updated for **[Next Item Name]** ([N] of [total], [remaining] remaining). Run `/intuition-design` to continue."
+
+## TRANSITION 4: DESIGN → EXECUTION
+
+Triggers when ALL design items have status `"completed"` (or `"skipped"`).
+
+### Read Outputs
+
+Read all design specs: `docs/project_notes/design_spec_*.md`
+Read: `docs/project_notes/plan.md`
+
+### Extract and Structure
+
+From the design specs:
+- **All architectural decisions** → ensure they're in `decisions.md`
+- **Key facts discovered during design** → add to `key_facts.md`
+- **All design work** → log in `issues.md`
 
 ### Generate Execution Brief
 
@@ -205,8 +419,16 @@ Write `docs/project_notes/execution_brief.md`:
 ## Discovery Context
 [Brief reminder of why this matters]
 
+## Design Specifications
+[List all design specs produced, with one-line summary of each:]
+- design_spec_[item1].md — [summary]
+- design_spec_[item2].md — [summary]
+
+**IMPORTANT:** Execute agents MUST read these specs before implementing flagged tasks. Implement exactly what's specified. If ambiguity is found, escalate to user — do not make design decisions autonomously.
+
 ## Task Summary
 [List tasks in execution order with brief descriptions]
+[Mark which tasks have associated design specs]
 
 ## Quality Gates
 - Security review: MANDATORY
@@ -219,15 +441,41 @@ Write `docs/project_notes/execution_brief.md`:
 ## References
 - Full Plan: docs/project_notes/plan.md
 - Discovery Brief: docs/project_notes/discovery_brief.md
+- Design Specs: docs/project_notes/design_spec_*.md
 ```
 
 ### Update State
 
+```json
+{
+  "workflow": {
+    "status": "executing",
+    "design": { "completed": true, "completed_at": "[ISO timestamp]" },
+    "execution": { "started": true }
+  }
+}
+```
+
+### Route User
+
+Tell the user: "All design specs processed. Execution brief saved to `docs/project_notes/execution_brief.md`. Run `/intuition-execute` to begin implementation."
+
+## TRANSITION 4B: PLANNING → EXECUTION (Skip Design)
+
+Used when the user confirms NO items need design at the Planning → Design transition.
+
+### Generate Execution Brief
+
+Same format as Transition 4 but without the "Design Specifications" section.
+
+### Update State
+
 ```json
 {
   "workflow": {
     "status": "executing",
     "planning": { "completed": true, "completed_at": "[ISO timestamp]", "approved": true },
+    "design": { "started": false, "completed": false, "items": [] },
     "execution": { "started": true }
   }
 }
@@ -235,9 +483,9 @@ Write `docs/project_notes/execution_brief.md`:
 
 ### Route User
 
-Tell the user: "Plan processed. Execution brief saved to `docs/project_notes/execution_brief.md`. Run `/intuition-execute` to begin implementation."
+Tell the user: "Plan processed. No design items flagged. Execution brief saved to `docs/project_notes/execution_brief.md`. Run `/intuition-execute` to begin implementation."
 
-## TRANSITION 3: EXECUTION → COMPLETE
+## TRANSITION 5: EXECUTION → COMPLETE
 
 ### Read Outputs
 
@@ -262,7 +510,7 @@ Read execution results from any files the execution phase produced. Check `docs/
 
 ### Route User
 
-Tell the user: "Workflow cycle complete. Run `/intuition-prompt` or `/intuition-discovery` to start a new cycle, or `/intuition-start` to review project status."
+Tell the user: "Workflow cycle complete. Run `/intuition-prompt` to start a new cycle, or `/intuition-start` to review project status."
 
 ## MEMORY FILE FORMATS
 
@@ -303,13 +551,17 @@ Add new categories as needed. Add facts under existing categories. Do not remove
 
 - **Missing discovery_output.json**: Extract insights manually from discovery_brief.md. Less structured but handoff still works.
 - **Poor output quality**: Process as-is. Note concerns in the brief: "Output quality was limited — next agent may need more exploration." Do NOT try to fix or improve outputs.
-- **Planning revealed new constraints**: Update key_facts.md, create ADR if architectural, note in execution brief.
+- **Planning revealed new constraints**: Update key_facts.md, create ADR if architectural, note in design/execution brief.
 - **Interrupted handoff**: Check what's been updated in memory files. Continue from where you left off. Don't duplicate entries.
-- **Corrupted state**: If .project-memory-state.json is malformed, infer phase from which output files exist (discovery_brief.md → discovery complete, plan.md → planning complete). Ask user to confirm.
+- **Corrupted state**: If .project-memory-state.json is malformed, infer phase from which output files exist (discovery_brief.md → prompt complete, plan.md → planning complete, design_spec_*.md → design in progress). Ask user to confirm.
+- **Design item skipped mid-loop**: If user asks to skip a design item during the loop, mark it as `"skipped"` in state. Do not block the loop — proceed to next item. Note the skip in the execution brief.
+- **No Design Recommendations in plan**: If plan.md has no flagged items, present the plan tasks to the user and ask if any need design. If none, proceed with Transition 4B.
+- **Plan revision after design started**: If plan.md has been modified after design began, alert the user. Ask whether to continue with current design items or re-evaluate.
 
 ## VOICE
 
-- Administrative and transparent — "I've processed the discovery output"
+- Administrative and transparent — "I've processed the design output"
 - Structured — specific about what was updated and where
 - Never evaluative — process and document, don't judge quality
 - Forward-looking — always suggest the next step
+- Loop-aware — always show design queue progress when in design loop

package/skills/intuition-initialize/SKILL.md

@@ -32,6 +32,7 @@ Step 1: Detect existing setup
 Step 2: Create memory directory and files from templates
 Step 3: Create .project-memory-state.json with v2.0 workflow schema
 Step 4: Update CLAUDE.md with workflow protocols
+Step 4.5: Create INTUITION.md framework overview
 Step 5: Offer optional components (AGENTS.md, settings, user profile)
 Step 6: Report completion and suggest next step
 ```
@@ -84,13 +85,15 @@ Do NOT create workflow output files (discovery_brief.md, plan.md, execution_brie
 
 Read `references/state_template.json` and write to `docs/project_notes/.project-memory-state.json`.
 
-The state file uses the v2.0 WORKFLOW schema:
+The state file uses the v3.0 WORKFLOW schema:
 
 ```json
 {
+  "initialized": true,
+  "version": "3.0",
   "workflow": {
     "status": "none",
-    "discovery": {
+    "prompt": {
       "started": false,
       "completed": false,
       "started_at": null,
@@ -104,19 +107,28 @@ The state file uses the v2.0 WORKFLOW schema:
       "completed_at": null,
       "approved": false
     },
+    "design": {
+      "started": false,
+      "completed": false,
+      "completed_at": null,
+      "items": [],
+      "current_item": null
+    },
     "execution": {
       "started": false,
       "completed": false,
       "started_at": null,
       "completed_at": null
     }
-  }
+  },
+  "last_handoff": null,
+  "last_handoff_transition": null
 }
 ```
 
 **CRITICAL**: This is the authoritative schema. Handoff is the ONLY skill that updates this file after initialization. All other skills read it but NEVER write to it.
 
-Do NOT use the old v1.0 schema that had `personalization`, `waldo_greeted`, `plan_created`, or `plan_status` fields. That schema is obsolete.
+Do NOT use older schemas (v1.0 with `personalization` fields, or v2.0 with `discovery` instead of `prompt`). Those schemas are obsolete.
 
 ## STEP 4: UPDATE CLAUDE.MD
 
@@ -133,10 +145,25 @@ IF CLAUDE.md does NOT exist:
 ```
 
 The template includes:
-- Three-phase workflow description (discovery → handoff → plan → handoff → execute)
+- Four-phase workflow description (prompt → plan → design → execute with handoffs)
 - Memory file descriptions and locations
 - Memory-aware protocols (check decisions before changes, search bugs before debugging)
-- Smart skill suggestions (when to suggest /intuition-discovery, /intuition-plan, etc.)
+- Smart skill suggestions (when to suggest /intuition-prompt, /intuition-plan, /intuition-design, etc.)
+
+## STEP 4.5: CREATE INTUITION.MD
+
+Read `references/intuition_readme_template.md` and write to `INTUITION.md` at the project root (same level as CLAUDE.md).
+
+```
+IF INTUITION.md already exists:
+  → Ask user: "INTUITION.md already exists. Overwrite with current version?"
+  → If no, skip
+
+IF INTUITION.md does NOT exist:
+  → Create it from template
+```
+
+This is a brief, human-readable overview of the Intuition workflow. It helps anyone on the project understand what the skills do and how to use them.
 
 ## STEP 5: OPTIONAL COMPONENTS
 
@@ -199,12 +226,13 @@ Created:
 - docs/project_notes/decisions.md
 - docs/project_notes/key_facts.md
 - docs/project_notes/issues.md
-- docs/project_notes/.project-memory-state.json (v2.0 workflow schema)
+- docs/project_notes/.project-memory-state.json (v3.0 workflow schema)
 - CLAUDE.md workflow protocols
+- INTUITION.md framework overview
 
 [List any optional components created]
 
-Next step: Run /intuition-discovery to start exploring your problem,
+Next step: Run /intuition-prompt to describe what you want to build,
 or /intuition-start to check project status.
 ```
 
@@ -228,6 +256,9 @@ These template files are in the `references/` directory. Use Read tool to access
 **State template** (used in Step 3):
 - `state_template.json` — v2.0 workflow schema
 
+**Framework overview** (used in Step 4.5):
+- `intuition_readme_template.md` — high-level workflow overview for INTUITION.md
+
 **Configuration templates** (used in Steps 4-5):
 - `claude_template.md` — workflow protocols for CLAUDE.md
 - `agents_template.md` — agent registry for AGENTS.md
@@ -237,6 +268,7 @@ These template files are in the `references/` directory. Use Read tool to access
 **Workflow output templates** (NOT used by initialize — used by handoff):
 - `discovery_output_template.json`
 - `planning_brief_template.md`
+- `design_brief_template.md`
 - `execution_brief_template.md`
 
 ## MEMORY FILE FORMATS

package/skills/intuition-initialize/references/claude_template.md

@@ -1,36 +1,46 @@
 ## Project Workflow and Memory System
 
-This project uses a three-phase workflow coordinated by the Intuition system, with institutional knowledge maintained in `docs/project_notes/` for consistency across sessions.
+This project uses a four-phase workflow coordinated by the Intuition system, with institutional knowledge maintained in `docs/project_notes/` for consistency across sessions.
 
 ### Workflow Phases
 
 The project follows a structured workflow with handoff transitions between phases:
 
-**Discovery (Waldo)** — `/intuition-discovery`
-- Deep understanding of the problem through collaborative dialogue
-- Framework: GAPP (Problem → Goals → UX Context → Personalization)
+**Prompt** — `/intuition-prompt`
+- Transforms a rough vision into a precise, planning-ready discovery brief
+- Framework: Capture → Refine → Reflect → Confirm
 - Output: `discovery_brief.md` and `discovery_output.json`
 
 **Handoff** — `/intuition-handoff`
 - Processes phase outputs, updates memory files, generates brief for next agent
-- Runs between every phase transition (discovery→planning and planning→execution)
+- Runs between every phase transition
+- Manages the design loop (item-by-item design cycles)
 - ONLY component that writes to `.project-memory-state.json`
 
-**Planning (Magellan)** — `/intuition-plan`
+**Planning** — `/intuition-plan`
 - Strategic synthesis and structured execution planning
 - Researches codebase, identifies patterns, creates detailed plan
-- Output: `plan.md` with tasks, dependencies, risks
+- Flags tasks requiring design exploration with rationale
+- Output: `plan.md` with tasks, dependencies, risks, design recommendations
 
-**Execution (Faraday)** — `/intuition-execute`
+**Design** — `/intuition-design`
+- Detailed design exploration for flagged plan items
+- Framework: ECD (Elements, Connections, Dynamics)
+- Domain-agnostic: works for code, world building, UI, documents, or any creative/structural work
+- Runs once per flagged item in a loop managed by handoff
+- Output: `design_spec_[item].md` per item
+
+**Execution** — `/intuition-execute`
 - Methodical implementation with verification and quality checks
 - Delegates to specialized sub-agents, coordinates work, verifies outputs
+- Reads both plan.md and design specs for implementation guidance
 - Output: Implemented features, updated memory, completion report
 
 **Session Primer** — `/intuition-start`
 - Loads project context, detects workflow phase, suggests next step
 - Run at the start of any session to get oriented
 
-**Recommended Flow**: Discovery → Handoff → Planning → Handoff → Execution → Handoff
+**Recommended Flow**: Prompt → Handoff → Plan → Handoff → [Design Loop] → Handoff → Execute → Handoff
 
 ### Memory Files
 
@@ -42,10 +52,12 @@ The project follows a structured workflow with handoff transitions between phase
 - **.project-memory-state.json** — Workflow phase tracking and session state
 
 **Phase Output Files** (created during workflow):
-- **discovery_brief.md** — Discovery phase synthesis (created by Waldo)
-- **discovery_output.json** — Structured findings (created by Waldo, processed by Handoff)
+- **discovery_brief.md** — Prompt phase synthesis
+- **discovery_output.json** — Structured findings (processed by Handoff)
 - **planning_brief.md** — Brief for planning phase (created by Handoff)
-- **plan.md** — Structured project plan (created by Magellan)
+- **plan.md** — Structured project plan with design recommendations
+- **design_brief.md** — Brief for current design item (created/updated by Handoff)
+- **design_spec_[item].md** — Design specifications per item
 - **execution_brief.md** — Brief for execution phase (created by Handoff)
 
 ### Memory-Aware Protocols
@@ -77,14 +89,17 @@ The project follows a structured workflow with handoff transitions between phase
 
 ### Smart Skill Suggestions
 
-**When discovery is complete:**
-- "Discovery looks complete! Use `/intuition-handoff` to process insights and prepare for planning."
+**When prompt refinement is complete:**
+- "Prompt refinement looks complete! Use `/intuition-handoff` to process insights and prepare for planning."
 
 **When user suggests planning work:**
 - "This sounds like a good candidate for planning. Use `/intuition-handoff` to process discovery, then `/intuition-plan` to develop a structured approach."
 
-**When plan is ready for execution:**
-- "The plan looks ready! Use `/intuition-handoff` to prepare execution context, then `/intuition-execute` to begin."
+**When plan is ready and has design items:**
+- "The plan looks ready! Use `/intuition-handoff` to review design recommendations and start the design loop."
+
+**When design items are complete:**
+- "All design specs are done! Use `/intuition-handoff` to prepare the execution brief."
 
 **When user is ready to execute:**
 - "Execution brief is ready! Use `/intuition-execute` to kick off coordinated implementation."