@tgoodington/intuition 5.0.0 → 7.0.0

package/skills/intuition-initialize/SKILL.md

@@ -16,7 +16,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 
 1. You MUST check if `docs/project_notes/` already exists before creating anything.
 2. You MUST use template files from `references/` directory for all initial content. Read each template with the Read tool, then Write to the target path.
-3. You MUST create `.project-memory-state.json` using the v2.0 WORKFLOW schema from `references/state_template.json`. Do NOT use the old v1.0 personalization schema.
+3. You MUST create `.project-memory-state.json` using the v4.0 schema from `references/state_template.json`. Do NOT use older schemas (v1.0, v2.0, v3.0).
 4. You MUST update CLAUDE.md with workflow and memory protocols.
 5. You MUST NOT overwrite existing memory files without asking the user first.
 6. You MUST NOT invoke other skills (discovery, plan, execute). You only set up infrastructure.
@@ -30,8 +30,9 @@ Execute these steps in order:
 ```
 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 3: Create .project-memory-state.json with v4.0 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
 ```
@@ -62,6 +63,8 @@ Create the directory structure and initialize memory files:
 ```
 docs/
 └── project_notes/
+    ├── trunk/
+    ├── branches/
     ├── bugs.md
     ├── decisions.md
     ├── key_facts.md
@@ -69,6 +72,8 @@ docs/
     └── .project-memory-state.json
 ```
 
+Create `docs/project_notes/trunk/` and `docs/project_notes/branches/` as empty directories. Write a `.gitkeep` placeholder to each so they are tracked by git.
+
 For each file, use the Read tool to read the template, then use Write to create the target:
 
 | Template Source | Target File |
@@ -84,39 +89,52 @@ 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 v4.0 schema:
 
 ```json
 {
-  "workflow": {
+  "initialized": true,
+  "version": "4.0",
+  "active_context": "trunk",
+  "trunk": {
     "status": "none",
-    "discovery": {
-      "started": false,
-      "completed": false,
-      "started_at": null,
-      "completed_at": null,
-      "output_files": []
-    },
-    "planning": {
-      "started": false,
-      "completed": false,
-      "started_at": null,
-      "completed_at": null,
-      "approved": false
-    },
-    "execution": {
-      "started": false,
-      "completed": false,
-      "started_at": null,
-      "completed_at": null
+    "workflow": {
+      "prompt": {
+        "started": false,
+        "completed": false,
+        "started_at": null,
+        "completed_at": null,
+        "output_files": []
+      },
+      "planning": {
+        "started": false,
+        "completed": false,
+        "completed_at": null,
+        "approved": false
+      },
+      "design": {
+        "started": false,
+        "completed": false,
+        "completed_at": null,
+        "items": [],
+        "current_item": null
+      },
+      "execution": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      }
     }
-  }
+  },
+  "branches": {},
+  "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, v2.0, or v3.0). Those schemas are obsolete.
 
 ## STEP 4: UPDATE CLAUDE.MD
 
@@ -133,10 +151,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
 
@@ -195,16 +228,19 @@ Present a concise summary of what was created:
 Project memory initialized!
 
 Created:
+- docs/project_notes/trunk/         (trunk workflow artifacts)
+- docs/project_notes/branches/      (branch workflow artifacts)
 - docs/project_notes/bugs.md
 - 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 (v4.0 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.
 ```
 
@@ -226,7 +262,10 @@ These template files are in the `references/` directory. Use Read tool to access
 - `issues_template.md`
 
 **State template** (used in Step 3):
-- `state_template.json` — v2.0 workflow schema
+- `state_template.json` — v4.0 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
@@ -237,6 +276,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,60 @@
 ## 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 Model
+
+The Intuition workflow uses a trunk-and-branch model:
+- **Trunk**: The first prompt→plan→design→execute cycle. Represents the core vision.
+- **Branches**: Subsequent cycles that build on, extend, or diverge from trunk or other branches.
+- **Engineer**: Post-execution troubleshooting with holistic codebase awareness.
+
+All phases: `/intuition-prompt` → `/intuition-handoff` → `/intuition-plan` → `/intuition-handoff` →
+`[/intuition-design loop]` → `/intuition-handoff` → `/intuition-execute` → `/intuition-handoff` → complete
+
+After completion: `/intuition-start` to create branches or `/intuition-engineer` to troubleshoot.
 
 ### 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 → complete
+
+After completion, run `/intuition-start` to create a branch or invoke `/intuition-engineer` to troubleshoot.
 
 ### Memory Files
 
@@ -42,10 +66,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 +103,20 @@ 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."
+
+**When execution is complete:**
+- "Workflow cycle complete! Use `/intuition-start` to create a branch for new work, or `/intuition-engineer` to troubleshoot any issues."

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

@@ -0,0 +1,64 @@
+# Design Brief Template
+
+> **Path note:** `{context_path}` resolves to `docs/project_notes/trunk/` for the trunk context, or `docs/project_notes/branches/{name}/` for a branch context. Shared files (`key_facts.md`, `decisions.md`, `issues.md`, `bugs.md`) always remain at `docs/project_notes/`.
+
+> **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: `{context_path}/plan.md`
+- Discovery: `{context_path}/discovery_brief.md`
+- Prior design specs: [list completed spec files, if any]

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

@@ -1,7 +1,9 @@
 # Execution Brief Template
 
-> **Generated by:** `/intuition-handoff` (Planning→Execution stage)
-> **Consumed by:** `/intuition-execute` (Faraday)
+> **Path note:** `{context_path}` resolves to `docs/project_notes/trunk/` for the trunk context, or `docs/project_notes/branches/{name}/` for a branch context. Shared files (`key_facts.md`, `decisions.md`, `issues.md`, `bugs.md`) always remain at `docs/project_notes/`.
+
+> **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 +45,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 +80,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 +143,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`
+- Plan file: `{context_path}/plan.md`
+- Planning brief: `{context_path}/planning_brief.md`
+- Design specs: `{context_path}/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,60 @@
+# Intuition
+
+A trunk-and-branch workflow system for Claude Code. Turns rough ideas into structured plans, detailed designs, and executed implementations through guided dialogue. Supports iterative development through independent branch cycles and post-execution troubleshooting.
+
+## Workflow
+
+```
+/intuition-prompt  →  /intuition-handoff  →  /intuition-plan  →  /intuition-handoff
+                                                                        ↓
+                                                              [design loop, if needed]
+                                                                        ↓
+                                                /intuition-execute  ←  /intuition-handoff
+                                                        ↓
+                                               /intuition-handoff  →  complete
+                                                        ↓
+                              /intuition-start  →  create branch  or  /intuition-engineer
+```
+
+Run `/intuition-handoff` between every phase. It manages state, generates briefs, and routes you forward.
+
+The first prompt→execute cycle is the **trunk**. After trunk completes, create **branches** for new features or changes. Use `/intuition-engineer` to troubleshoot issues in any completed context.
+
+## Skills
+
+| Skill | What it does |
+|-------|-------------|
+| `/intuition-start` | Detects where you left off, shows project status, routes to next step or branch creation |
+| `/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-engineer` | Holistic post-execution troubleshooter — diagnoses and fixes issues with full codebase awareness |
+| `/intuition-handoff` | Processes phase outputs, updates memory, prepares the next phase |
+| `/intuition-initialize` | Sets up project memory (you already ran this) |
+
+## Quick Start
+
+### First cycle (trunk)
+
+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
+9. `/intuition-handoff` — complete the cycle
+
+Not every project needs design. If the plan is clear enough, handoff skips straight to execute.
+
+### After trunk completes (branches)
+
+10. `/intuition-start` — see project status and choose next step
+    - **Create a branch** — start a new feature or change cycle, informed by trunk
+    - **Open the engineer** — diagnose and fix issues in any completed context
+
+### Troubleshooting
+
+Run `/intuition-engineer` at any time after a context is complete. It loads your workflow artifacts, investigates issues holistically, and delegates fixes to subagents.

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

@@ -1,8 +1,10 @@
 # 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)
+> **Path note:** `{context_path}` resolves to `docs/project_notes/trunk/` for the trunk context, or `docs/project_notes/branches/{name}/` for a branch context. Shared files (`key_facts.md`, `decisions.md`, `issues.md`, `bugs.md`) always remain at `docs/project_notes/`.
+
+> **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 +16,7 @@
 
 ## Discovery Summary
 
-**Key findings from discovery phase:**
+**Key findings from prompt refinement:**
 - Fact 1
 - Fact 2
 - Fact 3
@@ -88,12 +90,12 @@
 
 ## References
 
-- Discovery output: `docs/project_notes/discovery_output.json`
-- Discovery brief: `docs/project_notes/discovery_brief.md`
+- Discovery output: `{context_path}/discovery_output.json`
+- Discovery brief: `{context_path}/discovery_brief.md`
 - Related docs: [Links to relevant documentation]
 
 ---
 
 ## 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,29 +1,38 @@
 {
   "initialized": true,
-  "version": "2.0",
-  "workflow": {
+  "version": "4.0",
+  "active_context": "trunk",
+  "trunk": {
     "status": "none",
-    "discovery": {
-      "started": false,
-      "started_at": null,
-      "completed": false,
-      "completed_at": null,
-      "output_files": []
-    },
-    "planning": {
-      "started": false,
-      "started_at": null,
-      "completed": false,
-      "completed_at": null,
-      "approved": false
-    },
-    "execution": {
-      "started": false,
-      "started_at": null,
-      "completed": false,
-      "completed_at": null
+    "workflow": {
+      "prompt": {
+        "started": false,
+        "completed": false,
+        "started_at": null,
+        "completed_at": null,
+        "output_files": []
+      },
+      "planning": {
+        "started": false,
+        "completed": false,
+        "completed_at": null,
+        "approved": false
+      },
+      "design": {
+        "started": false,
+        "completed": false,
+        "completed_at": null,
+        "items": [],
+        "current_item": null
+      },
+      "execution": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      }
     }
   },
+  "branches": {},
   "last_handoff": null,
   "last_handoff_transition": null
 }