@tgoodington/intuition 5.0.0 → 6.0.0

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

@@ -0,0 +1,62 @@
+# Design Brief Template
+
+> **Generated by:** `/intuition-handoff` (Planning→Design transition, updated per design item)
+> **Consumed by:** `/intuition-design`
+> **Overwritten for:** each design item in the loop
+
+---
+
+## 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 from plan.md]
+- **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 can proceed]
+
+---
+
+## Prior Design Context
+
+[If this is not the first design item: 1-2 sentences about what was designed in previous items that may be relevant. If first item, omit this section.]
+
+---
+
+## Constraints
+
+- [From plan's architectural decisions]
+- [From discovery constraints]
+- [From prior design decisions, if any]
+
+---
+
+## Design Queue
+
+- [x] Item 1 (completed) -> design_spec_item_1.md
+- **Item 2 (current)**
+- [ ] Item 3 (pending)
+
+---
+
+## References
+
+- Plan: docs/project_notes/plan.md
+- Discovery: docs/project_notes/discovery_brief.md
+- Prior design specs: [list completed spec files, if any]

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

@@ -1,7 +1,7 @@
 # Execution Brief Template
 
-> **Generated by:** `/intuition-handoff` (Planning→Execution stage)
-> **Consumed by:** `/intuition-execute` (Faraday)
+> **Generated by:** `/intuition-handoff` (Design→Execution or Planning→Execution transition)
+> **Consumed by:** `/intuition-execute`
 > **Frozen for:** execution phase (don't modify during execution)
 
 ---
@@ -43,6 +43,18 @@
 
 ---
 
+## Design Specifications
+
+[List all design specs produced during the design phase, if any:]
+- `design_spec_[item1].md` — [One-line summary]
+- `design_spec_[item2].md` — [One-line 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.
+
+[If no design phase was run, omit this section.]
+
+---
+
 ## Plan Overview
 
 **Architecture approach:** [High-level design strategy]
@@ -66,10 +78,7 @@
 - Testing: [Count]
 - Documentation: [Count]
 
-**Estimated breakdown:**
-- Small tasks (1-2 hours): [Count]
-- Medium tasks (2-4 hours): [Count]
-- Large tasks (4+ hours): [Count]
+[Mark which tasks have associated design specs]
 
 ---
 
@@ -132,22 +141,18 @@
 - Alternatives considered: [What else could have been done]
 - Trade-offs: [What's given up]
 
-**Decision 2:** [What was decided]
-- Rationale: [Why this choice]
-- Alternatives considered: [What else could have been done]
-- Trade-offs: [What's given up]
-
 ---
 
 ## References
 
 - Plan file: `docs/project_notes/plan.md`
 - Planning brief: `docs/project_notes/planning_brief.md`
-- State file: `docs/project_notes/state.json`
+- Design specs: `docs/project_notes/design_spec_*.md`
+- State file: `docs/project_notes/.project-memory-state.json`
 - Related docs: [Links to relevant documentation]
 
 ---
 
 ## Notes for Executor
 
-[Any guidance for Faraday when executing this plan - context about approach, team norms, debugging strategies, or gotchas to watch for]
+[Any guidance for execution — context about approach, team norms, debugging strategies, or gotchas to watch for]

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

@@ -0,0 +1,40 @@
+# Intuition
+
+A four-phase workflow system for Claude Code. Turns rough ideas into structured plans, detailed designs, and executed implementations through guided dialogue.
+
+## Workflow
+
+```
+/intuition-prompt  →  /intuition-handoff  →  /intuition-plan  →  /intuition-handoff
+                                                                        ↓
+                                                              [design loop, if needed]
+                                                                        ↓
+                                                /intuition-execute  ←  /intuition-handoff
+```
+
+Run `/intuition-handoff` between every phase. It manages state, generates briefs, and routes you forward.
+
+## Skills
+
+| Skill | What it does |
+|-------|-------------|
+| `/intuition-start` | Detects where you left off and tells you what to run next |
+| `/intuition-prompt` | Sharpens a rough idea into a planning-ready brief through focused Q&A |
+| `/intuition-plan` | Builds a strategic blueprint with tasks, decisions, and design flags |
+| `/intuition-design` | Elaborates flagged items through collaborative design exploration (ECD framework) |
+| `/intuition-execute` | Delegates implementation to specialized subagents and verifies quality |
+| `/intuition-handoff` | Processes phase outputs, updates memory, prepares the next phase |
+| `/intuition-initialize` | Sets up project memory (you already ran this) |
+
+## Quick Start
+
+1. `/intuition-start` — see where you are
+2. `/intuition-prompt` — describe what you want to build
+3. `/intuition-handoff` — process and move to planning
+4. `/intuition-plan` — create the blueprint
+5. `/intuition-handoff` — review design flags, confirm items
+6. `/intuition-design` — elaborate each flagged item (repeat with handoff between)
+7. `/intuition-handoff` — prepare for execution
+8. `/intuition-execute` — build it
+
+Not every project needs design. If the plan is clear enough, handoff skips straight to execute.

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

@@ -1,8 +1,8 @@
 # Planning Brief Template
 
-> **Generated by:** `/intuition-handoff` (Discovery→Planning stage)
-> **Consumed by:** `/intuition-plan` (Magellan)
-> **Frozen for:** execution phase (don't modify during plan approval or execution)
+> **Generated by:** `/intuition-handoff` (Prompt→Planning transition)
+> **Consumed by:** `/intuition-plan`
+> **Frozen for:** planning phase (don't modify during plan approval or execution)
 
 ---
 
@@ -14,7 +14,7 @@
 
 ## Discovery Summary
 
-**Key findings from discovery phase:**
+**Key findings from prompt refinement:**
 - Fact 1
 - Fact 2
 - Fact 3
@@ -96,4 +96,4 @@
 
 ## Notes for Planner
 
-[Any guidance for Magellan when approaching this problem - context that shape how the plan should be structured]
+[Any guidance for the planning phase when approaching this problem - context that shapes how the plan should be structured]

package/skills/intuition-initialize/references/state_template.json

@@ -1,9 +1,9 @@
 {
   "initialized": true,
-  "version": "2.0",
+  "version": "3.0",
   "workflow": {
     "status": "none",
-    "discovery": {
+    "prompt": {
       "started": false,
       "started_at": null,
       "completed": false,
@@ -17,6 +17,13 @@
       "completed_at": null,
       "approved": false
     },
+    "design": {
+      "started": false,
+      "completed": false,
+      "completed_at": null,
+      "items": [],
+      "current_item": null
+    },
     "execution": {
       "started": false,
       "started_at": null,

package/skills/intuition-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: intuition-plan
-description: Strategic architect. Reads discovery brief, engages in interactive dialogue to map stakeholders, explore components, evaluate options, and synthesize an executable blueprint.
+description: Strategic architect. Reads discovery brief, engages in interactive dialogue to map stakeholders, explore components, evaluate options, synthesize an executable blueprint, and flag tasks requiring design exploration.
 model: opus
 tools: Read, Write, Glob, Grep, Task, AskUserQuestion, Bash, WebFetch
 allowed-tools: Read, Write, Glob, Grep, Task, Bash, WebFetch
@@ -10,7 +10,7 @@ allowed-tools: Read, Write, Glob, Grep, Task, Bash, WebFetch
 
 These are non-negotiable. Violating any of these means the protocol has failed.
 
-1. You MUST read `docs/project_notes/discovery_brief.md` before planning. If missing, stop and tell the user to run `/intuition-discovery`.
+1. You MUST read `docs/project_notes/discovery_brief.md` before planning. If missing, stop and tell the user to run `/intuition-prompt`.
 2. You MUST launch orientation research agents during Intake, after reading the discovery brief but BEFORE your first AskUserQuestion.
 3. You MUST use ARCH coverage tracking. Homestretch only unlocks when Actors, Reach, and Choices are sufficiently explored.
 4. You MUST ask exactly ONE question per turn via AskUserQuestion. For decisional questions, present 2-3 options with trade-offs. For informational questions (gathering facts, confirming understanding), present relevant options but trade-off analysis is not required.
@@ -23,6 +23,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 11. You MUST NOT modify `discovery_brief.md` or `planning_brief.md`.
 12. You MUST NOT manage `.project-memory-state.json` — handoff owns state transitions.
 13. You MUST treat user input as suggestions unless explicitly stated as requirements. Evaluate critically and propose alternatives when warranted.
+14. You MUST assess every task for design readiness and include a "Design Recommendations" section in the plan. Flag any task where execution cannot proceed without further design exploration (see DESIGN READINESS ASSESSMENT below).
 
 REMINDER: One question per turn. Route to `/intuition-handoff`, never to `/intuition-execute`.
 
@@ -81,7 +82,7 @@ This phase is exactly 1 turn. Execute all of the following before your first use
 ## Step 1: Read inputs
 
 Read these files:
-- `docs/project_notes/discovery_brief.md` — REQUIRED. If missing, stop immediately: "No discovery brief found. Run `/intuition-discovery` first."
+- `docs/project_notes/discovery_brief.md` — REQUIRED. If missing, stop immediately: "No discovery brief found. Run `/intuition-prompt` first."
 - `docs/project_notes/planning_brief.md` — optional, may contain handoff context.
 - `.claude/USER_PROFILE.json` — optional, for tailoring communication style.
 
@@ -223,9 +224,11 @@ After explicit approval:
 
 ## Scope Scaling
 
-- **Lightweight**: Sections 1, 2, 6, 10
-- **Standard**: Sections 1, 2, 3, 6, 7, 8, 10
-- **Comprehensive**: All sections (1-10)
+- **Lightweight**: Sections 1, 2, 6, 6.5, 10
+- **Standard**: Sections 1, 2, 3, 6, 6.5, 7, 8, 10
+- **Comprehensive**: All sections (1-10, including 6.5)
+
+Section 6.5 is Design Recommendations — ALWAYS included regardless of tier.
 
 ## Section Specifications
 
@@ -297,6 +300,45 @@ Overlap resolution: Planning specifies public interfaces between components and
 
 Interim artifacts in `.planning_research/` are working files for planning context management. They are NOT part of the plan-execute contract. Only `plan.md` crosses the handoff boundary.
 
+# DESIGN READINESS ASSESSMENT
+
+After drafting the task sequence, evaluate EVERY task for design readiness. A task is "ready for execution" if it is 95% clear — execution can fill in the remaining 5% without making design decisions.
+
+## Flagging Criteria
+
+Flag a task as **DESIGN REQUIRED** if ANY of these apply:
+
+- **Novel territory**: No existing pattern in the project to follow. The implementation approach needs to be invented, not just applied.
+- **Multiple valid approaches**: There are 2+ reasonable ways to build this, and the choice has lasting consequences. Execution shouldn't make this call.
+- **User-facing decisions**: The task involves layout, creative direction, user experience, tone, or aesthetic choices the user should weigh in on.
+- **Complex interactions**: The task touches multiple components and the interfaces between them need explicit definition before implementation.
+- **Ambiguous scope**: The task description says WHAT but the HOW has genuine options that affect quality, performance, or maintainability.
+
+Do NOT flag tasks that are:
+- Straightforward application of existing patterns
+- Mechanical wiring, boilerplate, or configuration
+- Well-understood implementations with clear precedent in the codebase
+- Simple enough that a competent engineer needs no design input
+
+## Design Recommendations Output
+
+Include this section in the plan AFTER the Task Sequence (Section 6) and BEFORE Testing Strategy (Section 7):
+
+```markdown
+### Design Recommendations
+
+| Task(s) | Item Name | Recommendation | Rationale |
+|---------|-----------|---------------|-----------|
+| Task 3, 4 | [Descriptive Name] | DESIGN REQUIRED | [Specific reason — what's unclear] |
+| Task 7 | [Descriptive Name] | DESIGN REQUIRED | [Specific reason] |
+| Task 1, 2 | [Name] | Ready for execution | [Why it's clear enough] |
+| Task 5, 6 | [Name] | Ready for execution | [Why it's clear enough] |
+
+**Design items group related tasks that share a design surface.** A single design session covers all tasks in the group. Items are named descriptively (e.g., "Behavior Tree AI System" not "Tasks 3-4").
+```
+
+When presenting the draft plan in Phase 4, explicitly call out which items you're recommending for design and why. The user confirms or adjusts during plan approval.
+
 # EXECUTABLE PLAN CHECKLIST
 
 Validate ALL before presenting the draft:
@@ -310,6 +352,8 @@ Validate ALL before presenting the draft:
 - [ ] Interface contracts provided where components interact (Comprehensive)
 - [ ] Risks have mitigations (Standard+)
 - [ ] Execution phase has enough context in Execution Notes to begin independently
+- [ ] Design Recommendations section included with every task assessed
+- [ ] Each DESIGN REQUIRED flag has a specific rationale (not generic)
 
 If any check fails, fix it before presenting.
 

package/skills/intuition-prompt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: intuition-prompt
-description: Prompt-engineering discovery. Transforms a rough vision into a precise, planning-ready discovery brief through focused iterative refinement. Use instead of /intuition-discovery when you already know roughly what you want and need to sharpen it.
+description: Prompt-engineering discovery. Transforms a rough vision into a precise, planning-ready discovery brief through focused iterative refinement. The primary entry point for all new work in the Intuition workflow.
 model: opus
 tools: Read, Write, Glob, Grep, Task, AskUserQuestion
 allowed-tools: Read, Write, Glob, Grep, Task

package/skills/intuition-start/SKILL.md

@@ -57,7 +57,7 @@ Review the "Package Version Info" section above. Parse the version numbers from
 2. Extract latest version from the npm view output (should be just the version number)
 3. Compare the versions:
    - If installed < latest: Add this line at the TOP of your output (before welcome message):
-     `⚠️  Update available: v[installed] → v[latest]. Run /intuition-update to install.`
+     `Update available: v[installed] -> v[latest]. Run /intuition-update to install.`
    - If versions match OR if version info is missing/errored: Say nothing about versions
    - If you cannot parse versions: Say nothing (don't block startup)
 
@@ -70,11 +70,11 @@ Read `docs/project_notes/.project-memory-state.json`. Use this decision tree:
 ```
 IF .project-memory-state.json does NOT exist:
   → PHASE: first_time
-  → ACTION: Welcome, suggest /intuition-prompt or /intuition-discovery
+  → ACTION: Welcome, suggest /intuition-prompt
 
-ELSE IF workflow.discovery.started == false OR workflow.discovery.completed == false:
-  → PHASE: discovery_in_progress
-  → ACTION: Note discovery is underway, suggest /intuition-discovery
+ELSE IF workflow.prompt.started == false OR workflow.prompt.completed == false:
+  → PHASE: prompt_in_progress
+  → ACTION: Note prompt is underway, suggest /intuition-prompt
 
 ELSE IF workflow.planning.started == false:
   → PHASE: ready_for_planning
@@ -84,6 +84,11 @@ ELSE IF workflow.planning.completed == false:
   → PHASE: planning_in_progress
   → ACTION: Note planning is underway, suggest /intuition-plan
 
+ELSE IF workflow.status == "design" AND workflow.design.started == true
+     AND workflow.design.completed == false:
+  → PHASE: design_in_progress
+  → ACTION: Show design queue progress, suggest /intuition-design or /intuition-handoff
+
 ELSE IF workflow.execution.started == false:
   → PHASE: ready_for_execution
   → ACTION: Summarize plan, suggest /intuition-execute
@@ -94,52 +99,42 @@ ELSE IF workflow.execution.completed == false:
 
 ELSE:
   → PHASE: complete
-  → ACTION: Celebrate, suggest /intuition-prompt or /intuition-discovery for next cycle
+  → ACTION: Celebrate, suggest /intuition-prompt for next cycle
 ```
 
 If `.project-memory-state.json` exists but is corrupted or unreadable, infer the phase from which output files exist:
-- `discovery_brief.md` exists → discovery complete
+- `discovery_brief.md` exists → prompt complete
 - `plan.md` exists → planning complete
+- `design_spec_*.md` exists → design in progress or complete
 - Ask user to confirm if ambiguous.
 
 ## PHASE HANDLERS
 
 ### First Time (No Project Memory)
 
-Output a welcome message, then use AskUserQuestion to offer the discovery choice:
+Output a welcome message, then suggest getting started:
 
 ```
 Welcome to Intuition!
 
-I don't see any project memory yet. Let's kick things off with discovery.
-```
+I don't see any project memory yet. Let's kick things off.
 
-Then immediately use AskUserQuestion:
-```
-Question: "How would you like to start?"
-Header: "Discovery"
-Options:
-- "Prompt — I have a vision, help me sharpen it" / "Focused and fast. You describe what you want, and we'll refine it into a planning-ready brief through targeted questions. Best when you already know roughly what you're after. Runs /intuition-prompt"
-- "Discovery — I want to think this through" / "Exploratory and collaborative. We'll dig into the problem together, with research to inform smarter questions along the way. Best when you're still forming the idea. Runs /intuition-discovery"
-MultiSelect: false
+Run /intuition-prompt to describe what you want to build or change.
+I'll help you sharpen it into something the planning phase can run with.
 ```
 
-After the user selects, tell them to run the corresponding skill:
-- If Prompt: "Run `/intuition-prompt` to get started."
-- If Discovery: "Run `/intuition-discovery` to get started."
-
-### Discovery In Progress
+### Prompt In Progress
 
 Check if `docs/project_notes/discovery_brief.md` exists for progress context.
 
 Output:
 ```
-Welcome back! Discovery is in progress.
+Welcome back! Prompt refinement is in progress.
 
 [If brief exists]: Progress saved at docs/project_notes/discovery_brief.md
-[If no brief yet]: No brief saved yet — still early in discovery.
+[If no brief yet]: No brief saved yet — still early in refinement.
 
-Run /intuition-discovery to continue.
+Run /intuition-prompt to continue.
 ```
 
 ### Ready for Planning
@@ -182,12 +177,35 @@ Plan: In progress (docs/project_notes/plan.md)
 Run /intuition-plan to continue.
 ```
 
+### Design In Progress
+
+Read `.project-memory-state.json` for design queue status. Read `docs/project_notes/design_brief.md` for current item context.
+
+Output:
+```
+Welcome back! Design exploration is in progress.
+
+Discovery: Complete
+Plan: Approved
+Design: In progress
+
+Design Queue:
+[For each item in design.items:]
+- [x] [Item Name] (completed) → design_spec_[name].md
+- [>] [Item Name] (in progress)
+- [ ] [Item Name] (pending)
+
+[If current item is in_progress]: Run /intuition-design to continue designing [current item].
+[If current item just completed]: Run /intuition-handoff to process the design and move to the next item.
+```
+
 ### Ready for Execution
 
 Read and curate from:
 - `docs/project_notes/plan.md` — extract objective, task count, approach
 - `docs/project_notes/execution_brief.md` — reference location
 - `docs/project_notes/decisions.md` — relevant ADRs
+- `docs/project_notes/design_spec_*.md` — list any design specs
 
 Output:
 ```
@@ -195,6 +213,9 @@ Welcome back! Your plan is approved and ready.
 
 Discovery: Complete
 Plan: Approved
+[If design specs exist]: Design: Complete ([N] specs)
+Execution: Ready
+
   - [N] tasks
   - Approach: [1 sentence]
   - Scope: [Simple/Moderate/Complex]
@@ -218,6 +239,7 @@ Welcome back! Execution is in progress.
 
 Discovery: Complete
 Plan: Approved
+[If design specs exist]: Design: Complete
 Execution: In progress
 
 Run /intuition-execute to continue.
@@ -225,30 +247,19 @@ Run /intuition-execute to continue.
 
 ### Complete
 
-Output a completion summary, then use AskUserQuestion to offer the next cycle choice:
+Output a completion summary:
 
 ```
 Welcome back! This workflow cycle is complete.
 
 Discovery: Complete
 Plan: Complete
+[If design was used]: Design: Complete
 Execution: Complete
 
-Ready for the next cycle?
+Ready for the next cycle? Run /intuition-prompt to start a new project or feature.
 ```
 
-Then use AskUserQuestion:
-```
-Question: "How would you like to start your next cycle?"
-Header: "Next cycle"
-Options:
-- "Prompt — I have a vision, help me sharpen it" / "Focused and fast. Refine a clear idea into a planning-ready brief. Runs /intuition-prompt"
-- "Discovery — I want to think this through" / "Exploratory and collaborative. Dig into a new problem with research-informed dialogue. Runs /intuition-discovery"
-MultiSelect: false
-```
-
-After the user selects, tell them to run the corresponding skill.
-
 ## BRIEF CURATION RULES
 
 You are curating information for the user, not dumping files. Follow these rules:
@@ -267,6 +278,11 @@ You are curating information for the user, not dumping files. Follow these rules
 - Scope: Simple/Moderate/Complex
 - One key constraint
 
+**For design summaries:**
+- Design queue status (completed/in-progress/pending)
+- Current item name
+- Number of specs produced
+
 **NEVER include:**
 - Every assumption from discovery
 - All context details
@@ -279,6 +295,7 @@ You are curating information for the user, not dumping files. Follow these rules
 - **Missing files referenced by state**: Report what you found and what's missing. Don't try to fix it. Suggest `/intuition-handoff` if briefs need regeneration.
 - **State says complete but output files missing**: "State indicates [phase] is complete but I can't find [file]. Run `/intuition-handoff` to reconcile, or check if the file was moved."
 - **User manually edited memory files**: Trust file contents as source of truth. Report what you find.
+- **Old v2.0 state schema detected** (has `discovery` instead of `prompt`): Treat `discovery` fields as `prompt` fields. Suggest running `/intuition-initialize` to update to v3.0 schema.
 
 ## VOICE