@tgoodington/intuition 2.0.0 → 2.0.2

package/README.md

@@ -1,312 +1,378 @@
 # Intuition
 
-Four Claude Code skills for structured planning, execution orchestration, project initialization, and compliance enforcement.
+A three-agent system for software project planning and execution. Intuition splits complex work into focused phases with clean context boundaries, dramatically improving success rates.
 
-Intuition provides:
-- **`/intuition-start`**: Load project context and enforce compliance with documented protocols
-- **`/intuition-plan`**: Waldo planning agent for thoughtful architecture and feature planning
-- **`/intuition-execute`**: Architect execution orchestrator for implementing approved plans
-- **`/intuition-initialize`**: Project initialization for structured knowledge system tracking decisions, bugs, and progress
+**The Three Agents:**
+- **Waldo** (`/intuition-discovery`) - Explores problems through GAPP discovery and Socratic dialogue
+- **Magellan** (`/intuition-plan`) - Synthesizes discovery into structured, executable plans
+- **Faraday** (`/intuition-execute`) - Orchestrates implementation with methodical precision
+
+**Supporting Skills:**
+- `/intuition-start` - Load project context and workflow status
+- `/intuition-initialize` - Setup project memory system
 
 ## Quick Start
 
 ```bash
 # Install globally
-npm install -g .
+npm install -g @tgoodington/intuition
 
 # In Claude Code, typical workflow:
-/intuition-initialize      # Set up project memory (once per project)
-/intuition-start           # Load context at start of session
-/intuition-plan "..."      # Plan new features
-/intuition-execute         # Execute the plan
+/intuition-start           # Load context and check workflow status
+/intuition-discovery       # Waldo guides you through GAPP discovery
+/intuition-plan            # Magellan creates a structured plan
+/intuition-execute         # Faraday orchestrates implementation
 ```
 
-## Skills
+## Why Three Agents?
+
+Each agent has a focused responsibility:
+
+| Agent | Skill | Phase | Input | Output | Focus |
+|-------|-------|-------|-------|--------|-------|
+| **Waldo** | `/intuition-discovery` | Discovery | Problem description | `discovery_brief.md` | Understanding & dialogue |
+| **Magellan** | `/intuition-plan` | Planning | `discovery_brief.md` | `plan.md` | Strategy & synthesis |
+| **Faraday** | `/intuition-execute` | Execution | `plan.md` | Code + memory updates | Implementation & verification |
+
+By splitting into three phases:
+- **Clean context** - Each agent starts fresh, focused on one job
+- **Reusable outputs** - Discovery briefs and plans are stored in project memory
+- **Higher success rate** - Less context bloat = fewer dropped threads
+- **Resume support** - Interrupted work picks up from last checkpoint
 
-### `/intuition-start` Skill
+## The Three-Phase Workflow
 
-Load your project context and enforce compliance with documented protocols.
+### Phase 1: Discovery with Waldo
+
+Explore your problem deeply using the GAPP framework:
 
-**Usage:**
 ```
-/intuition-start
+/intuition-discovery
 ```
 
-**What happens:**
-1. Reads project memory files (bugs.md, decisions.md, key_facts.md, issues.md)
-2. Reads protocol documents (CLAUDE.md, AGENTS.md)
-3. Summarizes project status, decisions, and constraints
-4. Primes Waldo and Architect to follow project patterns
-5. Offers next steps (plan, execute, or continue work)
+Waldo guides you through:
+- **Problem** - What's the core challenge?
+- **Goals** - What does success look like?
+- **UX Context** - Who will use this and how?
+- **Personalization** - What drives this work for you?
+
+**Output:** `docs/project_notes/discovery_brief.md`
 
-**When to use:** Start of every session to load full project context.
+Uses Socratic questioning and systems thinking to surface authentic intentions before planning begins.
 
-### `/intuition-plan` Skill
+### Phase 2: Planning with Magellan
 
-Start a planning session with Waldo, your planning thought partner.
+Create a structured plan from discovery:
 
-**Usage:**
 ```
-/intuition-plan "Implement real-time notifications with WebSockets"
+/intuition-plan
 ```
 
-**What happens:**
-1. Auto-initializes project memory on first run (creates `docs/project_notes/`)
-2. Waldo engages in dialogue to understand your goals
-3. Waldo researches your codebase and develops a detailed plan through reflection and refinement
-4. Plan is saved to `docs/project_notes/project_plan.md`
-5. You can review and approve before execution
+Magellan:
+1. Reads your discovery brief
+2. Researches your codebase (parallel agents)
+3. Synthesizes insights into a strategic plan
+4. Auto-detects planning depth (simple vs. complex)
+5. Presents plan for your approval
+
+**Output:** `docs/project_notes/plan.md`
+
+Includes tasks with acceptance criteria, dependencies, risks, and execution notes.
 
-### `/intuition-execute` Skill
+### Phase 3: Execution with Faraday
 
-Execute an existing plan with Architect, the execution orchestrator.
+Execute the approved plan:
 
-**Usage:**
 ```
 /intuition-execute
 ```
 
-**What happens:**
-1. Architect reads your plan from `docs/project_notes/project_plan.md`
-2. Reviews plan for feasibility and gaps
-3. Creates tasks with dependencies
-4. Delegates implementation to specialized sub-agents
-5. Verifies outputs and reports completion
+Faraday:
+1. Reads plan and discovery context
+2. Confirms approach with you
+3. Delegates to specialized sub-agents (parallel when possible)
+4. Verifies outputs against acceptance criteria
+5. Updates project memory
+6. Reports completion
 
-**Prerequisite:** A plan must exist from a previous `/intuition-plan` session
+**Output:** Implemented code + updated project memory
 
-### `/intuition-initialize` Skill
+## Project Memory System
 
-Initialize the project memory system.
+Intuition maintains persistent project knowledge:
 
-**Usage:**
 ```
-/intuition-initialize
+docs/project_notes/
+├── .project-memory-state.json    (workflow status & resume data)
+├── discovery_brief.md            (from Waldo)
+├── plan.md                       (from Magellan)
+├── bugs.md                       (known issues & solutions)
+├── decisions.md                  (architectural decisions)
+├── key_facts.md                  (project configuration)
+└── issues.md                     (work log)
 ```
 
-**What happens:**
-1. Creates `docs/project_notes/` directory structure
-2. Sets up memory files:
-   - `bugs.md` - Bug log with solutions
-   - `decisions.md` - Architectural decisions
-   - `key_facts.md` - Project configuration
-   - `issues.md` - Work log
-3. Configures project memory tracking
-4. Sets up CLAUDE.md and AGENTS.md with memory-aware protocols
+All three agents reference and update project memory for consistency.
 
-## Workflow
+## Workflow Status
 
-A typical Intuition workflow in Claude Code:
+Check where you are in the workflow:
 
 ```
-1. /intuition-initialize
-   └─ Initialize project memory system in docs/project_notes/
-
-2. /intuition-start (at beginning of each session)
-   └─ Load project context and enforce protocol compliance
-   └─ Understand project decisions, constraints, and status
-
-3. /intuition-plan "Feature description"
-   └─ Work with Waldo to develop a comprehensive plan
-   └─ Plan saved to docs/project_notes/project_plan.md
-   └─ Review and approve plan
-
-4. /intuition-execute
-   └─ Architect reads the plan and enforces compliance
-   └─ Delegates work to specialized sub-agents
-   └─ Executes plan tasks with verification
-   └─ Reports completion
-
-5. (Iterate as needed)
-   └─ /intuition-start (reload context for new session)
-   └─ /intuition-plan "Next phase"
-   └─ /intuition-execute
+/intuition-start
 ```
 
-## Using Intuition Skills
+Returns current status:
+- **Discovery:** In progress / Complete
+- **Planning:** In progress / Complete / Approved
+- **Execution:** In progress / Complete
 
-After installation via npm, the four Intuition skills are available globally in Claude Code:
+Also provides helpful next-step suggestions.
 
-### `/intuition-initialize` Skill
+## File Outputs
 
-Set up project memory and structured knowledge system.
+### discovery_brief.md (From Waldo)
 
-```
-/intuition-initialize
-```
+```markdown
+# Discovery Brief
 
-This creates:
-- `docs/project_notes/bugs.md` - Bug log with solutions
-- `docs/project_notes/decisions.md` - Architectural decisions
-- `docs/project_notes/key_facts.md` - Project configuration
-- `docs/project_notes/issues.md` - Work log
-- Configures CLAUDE.md and AGENTS.md with memory protocols
+## Problem
+[Core challenge and context]
 
-**Run this first** when starting a new project.
+## Goals
+[Success criteria]
 
-### `/intuition-plan` Skill
+## User Context
+[Personas and workflows]
 
-Start a planning session with Waldo:
+## Personalization / Motivation
+[What drives this work]
 
-```
-/intuition-plan "Add user authentication to the app"
+## Scope
+[In scope / out of scope]
+
+## Assumptions
+[With confidence levels]
 ```
 
-Waldo will:
-1. Engage in dialogue to understand your goals
-2. Research your codebase for context
-3. Develop a structured plan with confidence scoring
-4. Reflect and refine before finalizing
-5. Save the plan to `docs/project_notes/project_plan.md`
+### plan.md (From Magellan)
 
-### `/intuition-execute` Skill
+```markdown
+# Plan: [Title]
 
-Execute an existing plan with Architect:
+## Objective
+[What will be accomplished]
 
-```
-/intuition-execute
+## Discovery Summary
+[Key insights from Waldo]
+
+## Research Context
+[Codebase findings]
+
+## Approach
+[Strategy and rationale]
+
+## Tasks
+[With acceptance criteria, dependencies]
+
+## Risks & Mitigations
+[Identified risks]
+
+## Execution Notes for Faraday
+[Guidance for execution]
 ```
 
-Architect will:
-1. Read your plan from `docs/project_notes/project_plan.md`
-2. Review for feasibility and gaps
-3. Create tasks with dependencies
-4. Delegate to specialized sub-agents
-5. Verify outputs and report completion
+## Resume Support
 
-**Prerequisite:** A plan must exist from a previous `/intuition-plan` session.
+All three agents can resume interrupted work:
 
-### Verification
+- **Waldo** resumes from the last GAPP phase
+- **Magellan** resumes from research or draft state
+- **Faraday** resumes from the last completed task
 
-To verify installation in Claude Code:
+Just run the skill again and it will pick up from the checkpoint.
 
-1. Open any project in Claude Code
-2. Type `/` to see available skills
-3. You should see `/intuition-start`, `/intuition-plan`, `/intuition-execute`, and `/intuition-initialize`
+## Discovery Revision
 
-If skills are not available:
-- Ensure installation completed (check `~/.claude/skills/` contains the skill directories)
-- Restart Claude Code if just installed
-- See [INSTALLATION.md](./INSTALLATION.md) for troubleshooting
+If you need to revise your discovery:
 
-## Project Structure
+1. Run `/intuition-discovery` again
+2. Waldo updates `discovery_brief.md`
+3. Magellan detects the change and offers to re-plan
+4. New plan created with updated context
+
+## Installation
 
+### Install Globally (Recommended)
+
+```bash
+npm install -g @tgoodington/intuition
 ```
-intuition/
-├── skills/
-│   ├── intuition-start/      # Context loading and compliance enforcement
-│   ├── intuition-plan/       # Planning with Waldo
-│   ├── intuition-execute/    # Execution with Architect
-│   └── intuition-initialize/ # Project memory setup
-├── agents/
-│   ├── waldo.md              # Planning agent definition
-│   ├── architect.md          # Execution orchestrator
-│   └── [other sub-agents]
-├── scripts/
-│   └── install-skills.js     # Installation script
-├── package.json              # npm package config
-└── README.md                 # This file
+
+This installs five skills globally to `~/.claude/skills/`:
+- `/intuition-start` - Load project context
+- `/intuition-initialize` - Setup project memory
+- `/intuition-discovery` - Waldo's discovery
+- `/intuition-plan` - Magellan's planning
+- `/intuition-execute` - Faraday's execution
+
+### Install from Source (Development)
+
+```bash
+cd intuition
+npm install -g .
 ```
 
-## Agents
+### Verify Installation
 
-### Waldo - Planning Thought Partner
+In Claude Code, type `/` to see available skills. You should see all five:
+- `/intuition-start`
+- `/intuition-initialize`
+- `/intuition-discovery`
+- `/intuition-plan`
+- `/intuition-execute`
 
-Waldo specializes in collaborative planning. When you run `intuition plan`, Waldo:
-- Engages in dialogue to understand your goals
-- Researches your codebase for context
-- Develops structured plans with confidence scoring
-- Reflects and refines before finalizing
-- Outputs markdown plans for review
+## Skills Reference
 
-Read more in `agents/waldo.md`
+### `/intuition-start`
 
-### Architect - Execution Orchestrator
+Load project context and check workflow status.
 
-Architect specializes in execution coordination. When you run `intuition execute`, Architect:
-- Reviews the plan for completeness
-- Breaks plans into discrete tasks
-- Delegates to specialized sub-agents (Code Writer, Test Runner, etc.)
-- Verifies outputs against acceptance criteria
-- Handles failures with retry/fallback strategies
+```
+/intuition-start
+```
 
-Read more in `agents/architect.md`
+**Does:**
+- Loads project memory files
+- Checks workflow status
+- Suggests next steps based on status
+- Enforces project protocols
 
-## Project Memory System
+**When to use:** Start of every session
 
-Intuition includes a project memory system that maintains institutional knowledge across sessions.
+### `/intuition-initialize`
 
-**Memory files:**
-- `docs/project_notes/bugs.md` - Known bugs and solutions
-- `docs/project_notes/decisions.md` - Architectural decisions
-- `docs/project_notes/key_facts.md` - Project configuration
-- `docs/project_notes/issues.md` - Work log and tickets
+Setup project memory system.
 
-Memory is automatically referenced by Waldo and Architect to maintain consistency and avoid repeating past mistakes.
+```
+/intuition-initialize
+```
 
-See `skills/intuition-initialize/SKILL.md` for full details.
+**Creates:**
+- `docs/project_notes/` directory
+- `bugs.md` - Bug tracking
+- `decisions.md` - Architecture decisions
+- `key_facts.md` - Project configuration
+- `issues.md` - Work log
+- `.project-memory-state.json` - Workflow tracking
 
-## Installation
+**When to use:** Once per project, at the start
 
-### Install Globally via npm (Recommended)
+### `/intuition-discovery`
 
-```bash
-npm install -g intuition
+Explore your problem with Waldo.
+
+```
+/intuition-discovery
 ```
 
-This automatically installs the four Intuition skills to `~/.claude/skills/` for use across all projects with Claude Code:
-- `/intuition-start` - Load project context
-- `/intuition-plan` - Planning with Waldo
-- `/intuition-execute` - Execution with Architect
-- `/intuition-initialize` - Project initialization
+**Waldo does:**
+- GAPP discovery (Problem → Goals → UX Context → Personalization)
+- Socratic questioning
+- Systems thinking perspective
+- Clarifying questions to validate understanding
+- Saves `discovery_brief.md`
+
+**When to use:** Start of new work
+
+### `/intuition-plan`
+
+Create a plan with Magellan.
 
-**Verification:**
-```bash
-ls ~/.claude/skills/intuition-*
+```
+/intuition-plan
 ```
 
-### Install from Source (Development)
+**Magellan does:**
+- Reads your discovery brief
+- Researches codebase (parallel agents)
+- Synthesizes into strategic plan
+- Auto-detects planning depth
+- Saves `plan.md`
 
-```bash
-cd intuition
-npm install -g .
+**When to use:** After discovery is complete
+
+### `/intuition-execute`
+
+Execute the plan with Faraday.
+
+```
+/intuition-execute
 ```
 
-After installation, restart Claude Code and the skills will be available globally.
+**Faraday does:**
+- Reads plan and discovery context
+- Confirms approach with you
+- Delegates to sub-agents (parallel when possible)
+- Verifies outputs
+- Updates project memory
 
-## Requirements
+**When to use:** After plan is approved
 
-- Node.js 14.0.0 or higher
-- Access to Claude Code or similar agent system
+## Sub-Agents
 
-## Architecture
+Faraday coordinates these specialized agents:
 
-Intuition provides four integrated skills for Claude Code:
+| Agent | Purpose |
+|-------|---------|
+| Code Writer | Implementation |
+| Test Runner | Testing & verification |
+| Code Reviewer | Quality review |
+| Documentation | Updates docs |
+| Research | Codebase exploration |
+| Security Expert | Vulnerability scanning |
+| Technical Spec Writer | Specification creation |
+| Communications Specialist | User-facing documentation |
 
-1. **Context Loading** (`/intuition-start`) - Loads project memory and enforces protocol compliance
-2. **Initialization** (`/intuition-initialize`) - Sets up project memory and knowledge system
-3. **Planning** (`/intuition-plan` with Waldo agent) - Structured planning with reflection and dialogue
-4. **Execution** (`/intuition-execute` with Architect agent) - Orchestration and verification through sub-agents
+## Documentation
 
-All skills coordinate through the project memory system (`docs/project_notes/`) for consistency and context across sessions. `/intuition-start` ensures every session begins with full project context and compliance enforcement.
+- **Workflow Guide:** `docs/intuition-workflow.md`
+- **Architecture:** `docs/intuition-architecture.md`
+- **Waldo Reference:** `skills/intuition-discovery/references/waldo_core.md`
+- **Magellan Reference:** `skills/intuition-plan/references/magellan_core.md`
+- **Faraday Reference:** `skills/intuition-execute/references/faraday_core.md`
 
-### Sub-Agent System
+## Requirements
+
+- Node.js 14.0.0 or higher
+- Claude Code or similar agent system
+
+## Project Structure
 
-When `/execute` runs, Architect delegates to specialized sub-agents:
-- Code Writer - Implementation
-- Test Runner - Verification
-- Code Reviewer - Quality assurance
-- Documentation - Knowledge updates
-- Research - Investigation and exploration
-- Security Expert - Vulnerability detection
+```
+intuition/
+├── skills/
+│   ├── intuition-start/        # Context loading & workflow status
+│   ├── intuition-initialize/   # Project memory setup
+│   ├── intuition-discovery/    # Waldo - discovery & GAPP
+│   ├── intuition-plan/         # Magellan - strategic planning
+│   └── intuition-execute/      # Faraday - orchestrated execution
+├── agents/                     # Agent definitions
+├── docs/                       # Documentation
+│   ├── intuition-workflow.md   # User guide
+│   └── intuition-architecture.md # Technical details
+├── scripts/                    # Installation scripts
+├── package.json                # npm package config
+└── README.md                   # This file
+```
 
 ## Contributing
 
 Contributions welcome! Areas for enhancement:
 - Additional specialized sub-agents
-- Plan format improvements
-- Memory system enhancements
-- CLI features
+- Workflow improvements
+- Documentation enhancements
+- Framework extensions
 
 ## License
 
@@ -315,15 +381,19 @@ MIT
 ## Support
 
 For issues or questions:
-- Check `docs/project_notes/` for known issues and decisions
-- Review agent definitions in `agents/`
-- Check the skill documentation in `skills/`
-
-## See Also
-
-- Intuition Start Skill: `skills/intuition-start/SKILL.md`
-- Intuition Plan Skill: `skills/intuition-plan/SKILL.md`
-- Intuition Execute Skill: `skills/intuition-execute/SKILL.md`
-- Intuition Initialize Skill: `skills/intuition-initialize/SKILL.md`
-- Waldo Agent: `agents/waldo.md`
-- Architect Agent: `agents/architect.md`
+- Check `docs/intuition-workflow.md` for user guide
+- Check `docs/intuition-architecture.md` for technical details
+- Review skill documentation in `skills/*/SKILL.md`
+- Check project memory in `docs/project_notes/` for decisions and issues
+
+## Version History
+
+### 2.0.0+
+- Complete refactor into three-agent system (Waldo → Magellan → Faraday)
+- GAPP framework for discovery
+- File-based handoffs through project memory
+- Enhanced state management
+- Resume support for all phases
+
+### 1.x
+- Original monolithic planning system

package/docs/intuition-architecture.md

@@ -0,0 +1,342 @@
+# Intuition Architecture
+
+This document describes the technical architecture of the Intuition three-agent system.
+
+## System Overview
+
+Intuition is a skill-based system for Claude Code that implements a three-phase workflow for software development:
+
+```
+Discovery → Planning → Execution
+ (Waldo)   (Magellan)  (Faraday)
+```
+
+Each phase is handled by a specialized agent with focused responsibilities, connected through file-based handoffs in project memory.
+
+## Design Principles
+
+### 1. Separation of Concerns
+Each agent has a single, focused responsibility:
+- Waldo: Discovery and dialogue
+- Magellan: Research and planning
+- Faraday: Orchestration and execution
+
+### 2. Clean Context
+By separating phases, each agent starts with clean, focused context:
+- Waldo only holds dialogue state
+- Magellan reads synthesis from files
+- Faraday reads plans from files
+
+### 3. File-Based Handoffs
+Agents communicate through project memory files, not conversation context:
+- `discovery_brief.md` - Waldo → Magellan
+- `plan.md` - Magellan → Faraday
+- `state.json` - Workflow coordination
+
+### 4. Resume Support
+All agents can resume interrupted work by reading state from project memory.
+
+## Skill Structure
+
+```
+skills/
+├── intuition-start/
+│   └── SKILL.md              # Context loader, workflow status
+├── intuition-initialize/
+│   ├── SKILL.md              # Project memory setup
+│   └── references/
+│       └── state_template.json
+├── intuition-discovery/
+│   ├── SKILL.md              # Waldo's interface
+│   └── references/
+│       ├── waldo_core.md     # GAPP methodology
+│       └── templates/
+│           └── discovery_brief_template.md
+├── intuition-plan/
+│   ├── SKILL.md              # Magellan's interface
+│   └── references/
+│       ├── magellan_core.md  # Planning methodology
+│       └── templates/
+│           └── plan_template.md
+└── intuition-execute/
+    ├── SKILL.md              # Faraday's interface
+    └── references/
+        └── faraday_core.md   # Execution methodology
+```
+
+## State Management
+
+### State File Location
+`docs/project_notes/.project-memory-state.json`
+
+### State Schema (v2.0)
+
+```json
+{
+  "initialized": true,
+  "version": "2.0",
+
+  "workflow": {
+    "status": "none|discovery|planning|executing|complete",
+
+    "discovery": {
+      "completed": false,
+      "completed_at": null,
+      "brief_file": "docs/project_notes/discovery_brief.md",
+      "resume_data": null
+    },
+
+    "planning": {
+      "completed": false,
+      "completed_at": null,
+      "plan_file": "docs/project_notes/plan.md",
+      "approved": false,
+      "approved_at": null,
+      "resume_data": null
+    },
+
+    "execution": {
+      "started": false,
+      "started_at": null,
+      "completed": false,
+      "completed_at": null,
+      "tasks_completed": 0,
+      "tasks_total": 0,
+      "resume_data": null
+    }
+  },
+
+  "agents": {
+    "waldo": { "greeted": false },
+    "magellan": { "greeted": false },
+    "faraday": { "greeted": false }
+  },
+
+  "history": {
+    "discovery_revisions": 0,
+    "planning_revisions": 0,
+    "last_activity": null
+  }
+}
+```
+
+### State Transitions
+
+```
+none → discovery (when /intuition-discovery starts)
+discovery → planning (when discovery completes)
+planning → executing (when plan is approved)
+executing → complete (when execution finishes)
+complete → discovery (when new workflow starts)
+```
+
+## Data Flow
+
+### Discovery Phase (Waldo)
+
+**Input:**
+- User dialogue
+- (Optional) Existing project memory
+
+**Process:**
+1. GAPP dialogue (Problem → Goals → UX Context → Personalization)
+2. Clarifying questions
+3. Synthesize into discovery brief
+
+**Output:**
+- `docs/project_notes/discovery_brief.md`
+- Updated `state.json` (workflow.status = "discovery", discovery.completed = true)
+
+### Planning Phase (Magellan)
+
+**Input:**
+- `docs/project_notes/discovery_brief.md`
+- Codebase (via Research agents)
+
+**Process:**
+1. Read discovery brief
+2. Assess scope (auto-detect planning depth)
+3. Launch parallel Research agents
+4. Synthesize plan
+5. Present for user approval
+
+**Output:**
+- `docs/project_notes/plan.md`
+- Updated `state.json` (workflow.status = "planning", planning.approved = true)
+
+### Execution Phase (Faraday)
+
+**Input:**
+- `docs/project_notes/plan.md`
+- `docs/project_notes/discovery_brief.md`
+- Codebase
+
+**Process:**
+1. Read plan and discovery context
+2. Confirm with user
+3. Create tasks from plan
+4. Delegate to sub-agents (parallel when possible)
+5. Verify outputs
+6. Update project memory
+
+**Output:**
+- Implemented code changes
+- Updated project memory (bugs.md, decisions.md, etc.)
+- Updated `state.json` (workflow.status = "complete")
+
+## Sub-Agent Architecture
+
+### Available Sub-Agents
+
+| Agent | Used By | Purpose |
+|-------|---------|---------|
+| Research | Waldo, Magellan | Explore codebase |
+| Security Expert | Magellan, Faraday | Security review |
+| Code Writer | Faraday | Implementation |
+| Test Runner | Faraday | Testing |
+| Code Reviewer | Faraday | Quality review |
+| Documentation | Faraday | Doc updates |
+| Technical Spec Writer | Faraday | Specifications |
+| Communications Specialist | Faraday | User-facing docs |
+
+### Parallel Execution
+
+Both Magellan and Faraday can run sub-agents in parallel:
+
+```
+Magellan (Planning):
+├── Research Agent 1: Authentication patterns
+├── Research Agent 2: Database schema
+└── Research Agent 3: API routing
+    ↓ (all complete)
+    Synthesize findings
+
+Faraday (Execution):
+├── Code Writer 1: User model
+├── Code Writer 2: Product model
+└── Code Writer 3: Order model
+    ↓ (all complete)
+    Verify each independently
+```
+
+## File Formats
+
+### discovery_brief.md
+
+```markdown
+# Discovery Brief
+
+## Problem
+[Core challenge and context]
+
+## Goals
+[Success criteria]
+
+## User Context
+[Personas and workflows]
+
+## Personalization / Motivation
+[What drives this work]
+
+## Scope
+[In scope / out of scope]
+
+## Assumptions
+[With confidence levels]
+```
+
+### plan.md
+
+```markdown
+# Plan: [Title]
+
+## Objective
+[What will be accomplished]
+
+## Discovery Summary
+[Key insights from Waldo]
+
+## Research Context
+[Codebase findings]
+
+## Approach
+[Strategy and rationale]
+
+## Tasks
+[With acceptance criteria, dependencies]
+
+## Risks & Mitigations
+[Identified risks]
+
+## Execution Notes for Faraday
+[Guidance for execution]
+```
+
+## Resume Mechanism
+
+Each agent stores resume data in `state.json`:
+
+**Waldo:**
+- Current GAPP phase
+- Key insights captured
+- Open questions
+
+**Magellan:**
+- Research completed
+- Draft progress
+- Current synthesis state
+
+**Faraday:**
+- Tasks completed
+- Current task
+- Checkpoint reached
+
+On resume, agents read their resume_data and continue from last checkpoint.
+
+## Discovery Revision Flow
+
+When discovery is revised:
+
+1. User runs `/intuition-discovery` again
+2. Waldo updates `discovery_brief.md`
+3. State tracks revision: `history.discovery_revisions++`
+4. Magellan detects timestamp change
+5. Magellan offers to re-plan
+6. If yes, new plan created; old plan archived
+
+## Error Handling
+
+### Workflow Validation
+Each skill validates workflow state before proceeding:
+- Magellan requires discovery to be complete
+- Faraday requires plan to be approved
+
+### Graceful Degradation
+If state.json is missing or corrupted:
+- Skills fall back to checking for file existence
+- User prompted to re-initialize if needed
+
+### Sub-Agent Failures
+Faraday handles sub-agent failures with:
+1. Retry with additional context
+2. Decompose into smaller tasks
+3. Escalate to user
+
+## Security Considerations
+
+- Security Expert review is MANDATORY before any commit
+- No skipping or bypassing security gates
+- Faraday verifies security review before completing execution
+
+## Extension Points
+
+### Adding New Sub-Agents
+1. Document in each skill's sub_agents.md
+2. Add delegation patterns to core reference
+3. Update SKILL.md with agent description
+
+### Adding New Workflow Phases
+1. Add state tracking in state_template.json
+2. Create new skill directory
+3. Update intuition-start for status detection
+4. Document handoff files and formats

package/docs/intuition-workflow.md

@@ -0,0 +1,210 @@
+# Intuition Workflow Guide
+
+Welcome to Intuition! This guide explains how to use the three-phase workflow for planning and executing software projects.
+
+## Overview
+
+Intuition uses three specialized agents, each focused on a specific phase of work:
+
+| Phase | Skill | Agent | Purpose |
+|-------|-------|-------|---------|
+| 1. Discovery | `/intuition-discovery` | **Waldo** | Explore problems, goals, and motivations through dialogue |
+| 2. Planning | `/intuition-plan` | **Magellan** | Synthesize discovery into executable plans |
+| 3. Execution | `/intuition-execute` | **Faraday** | Implement plans with methodical precision |
+
+Each agent has a focused role, which keeps context clean and improves success rate.
+
+## Quick Start
+
+```bash
+# Start your session
+/intuition-start
+
+# Explore your problem with Waldo
+/intuition-discovery
+
+# Create a plan with Magellan
+/intuition-plan
+
+# Execute with Faraday
+/intuition-execute
+```
+
+## The Three Phases
+
+### Phase 1: Discovery with Waldo
+
+**What happens:** Waldo guides you through the GAPP framework to surface authentic intentions before planning.
+
+**GAPP Framework:**
+- **Problem** - What's the core challenge?
+- **Goals** - What does success look like?
+- **UX Context** - Who will use this and how?
+- **Personalization** - What drives this work for you?
+
+**What you'll experience:**
+- Socratic questioning that helps you think deeper
+- Systems thinking perspective on how problems connect
+- Clarifying questions to validate understanding
+
+**Output:** `docs/project_notes/discovery_brief.md`
+
+**Example:**
+```
+You: /intuition-discovery
+Waldo: What's the core challenge you're trying to solve?
+You: Our API is too slow for large data requests.
+Waldo: What happens when this slowness occurs? Who's affected?
+...
+```
+
+### Phase 2: Planning with Magellan
+
+**What happens:** Magellan reads the discovery brief, researches your codebase, and creates a structured plan.
+
+**What Magellan does:**
+- Reads your discovery brief
+- Launches Research agents to explore the codebase
+- Synthesizes insights into a coherent strategy
+- Creates tasks with dependencies and acceptance criteria
+- Presents the plan for your approval
+
+**Output:** `docs/project_notes/plan.md`
+
+**Example:**
+```
+You: /intuition-plan
+Magellan: I've read your discovery brief about API performance. Let me research the codebase...
+
+[Research agents explore in parallel]
+
+Magellan: Based on discovery and research, here's my recommended plan:
+- Task 1: Add caching layer to data endpoints
+- Task 2: Implement pagination for large results
+- Task 3: Add performance monitoring
+...
+```
+
+### Phase 3: Execution with Faraday
+
+**What happens:** Faraday reads the approved plan and orchestrates implementation through specialized sub-agents.
+
+**What Faraday does:**
+- Reads the plan and discovery brief
+- Confirms approach with you
+- Delegates tasks to sub-agents (Code Writer, Test Runner, etc.)
+- Verifies outputs against acceptance criteria
+- Reports completion with files modified
+
+**Sub-agents available:**
+- Code Writer, Test Runner, Documentation
+- Research, Code Reviewer, Security Expert
+- Technical Spec Writer, Communications Specialist
+
+**Example:**
+```
+You: /intuition-execute
+Faraday: I've read the plan. Here's my execution approach:
+- Tasks 1-3 can run in parallel (different files)
+- Security review is mandatory before completion
+
+Ready to proceed?
+
+You: Yes
+Faraday: [Delegates to Code Writer agents in parallel]
+...
+Faraday: Execution complete. 3 tasks finished, all tests passing.
+```
+
+## Workflow Status
+
+Intuition tracks your progress through the workflow in `docs/project_notes/.project-memory-state.json`.
+
+Run `/intuition-start` at any time to see where you are:
+
+```
+/intuition-start
+
+Workflow Status: Discovery complete, awaiting planning
+- Discovery: ✓ Complete
+- Planning: Not started
+- Execution: Not started
+
+Suggested Next Step: Run /intuition-plan
+```
+
+## File Outputs
+
+Each phase produces files in your project memory:
+
+```
+docs/project_notes/
+├── .project-memory-state.json  (workflow tracking)
+├── discovery_brief.md          (from Waldo)
+├── plan.md                     (from Magellan)
+├── bugs.md                     (project memory)
+├── decisions.md                (project memory)
+├── key_facts.md                (project memory)
+└── issues.md                   (project memory)
+```
+
+## Resume Support
+
+All three skills support resuming interrupted work:
+
+- **Waldo** resumes from the last GAPP phase
+- **Magellan** resumes from research or draft state
+- **Faraday** resumes from the last completed task
+
+Just run the skill again and it will pick up where you left off.
+
+## Discovery Revision
+
+If you need to revise your discovery (maybe you learned something new):
+
+1. Run `/intuition-discovery` again
+2. Waldo will update the discovery brief
+3. Magellan will detect the change and offer to re-plan
+
+This keeps plans aligned with your current understanding.
+
+## Best Practices
+
+1. **Start with `/intuition-start`** - Load context at the beginning of each session
+
+2. **Don't skip discovery** - The GAPP framework significantly improves plan quality
+
+3. **Trust the agents** - Each has a focused role; let them do their job
+
+4. **Approve before execution** - Always review Magellan's plan before Faraday executes
+
+5. **Use project memory** - Initialize with `/intuition-initialize` for persistent context
+
+## Troubleshooting
+
+**"No discovery brief found"**
+- Run `/intuition-discovery` first to create one
+
+**"Plan not approved"**
+- Review `docs/project_notes/plan.md` and tell Magellan to proceed
+
+**"Workflow out of sync"**
+- Run `/intuition-start` to see current status and reset if needed
+
+## Agent Personalities
+
+Each agent has a distinct personality:
+
+- **Waldo** (after Ralph Waldo Emerson) - Thoughtful, curious, philosophical. Asks probing questions.
+
+- **Magellan** (after Ferdinand Magellan) - Strategic, organized, confident. Turns vision into plans.
+
+- **Faraday** (after Michael Faraday) - Methodical, precise, rigorous. Transforms plans into reality.
+
+## Getting Help
+
+- `/intuition-start` - See current status and get suggestions
+- Check `docs/project_notes/` for all workflow files
+- Each skill's SKILL.md has detailed documentation
+
+Happy building!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Three-agent system for software project planning and execution. Waldo (discovery), Magellan (planning), Faraday (execution) with file-based handoffs through project memory.",
   "keywords": [
     "claude-code",
@@ -27,6 +27,7 @@
     "skills/",
     "scripts/",
     "agents/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],

package/scripts/install-skills.js

@@ -106,13 +106,26 @@ try {
     process.exit(1);
   }
 
+  // Copy /intuition-discovery skill
+  const discoverySrc = path.join(packageRoot, 'skills', 'intuition-discovery');
+  const discoveryDest = path.join(claudeSkillsDir, 'intuition-discovery');
+
+  if (fs.existsSync(discoverySrc)) {
+    copyDirRecursive(discoverySrc, discoveryDest);
+    log(`✓ Installed /intuition-discovery skill to ${discoveryDest}`);
+  } else {
+    error(`intuition-discovery skill not found at ${discoverySrc}`);
+    process.exit(1);
+  }
+
   // Verify installation
-  if (fs.existsSync(startDest) && fs.existsSync(planDest) && fs.existsSync(executeDest) && fs.existsSync(initializeDest)) {
+  if (fs.existsSync(startDest) && fs.existsSync(planDest) && fs.existsSync(executeDest) && fs.existsSync(initializeDest) && fs.existsSync(discoveryDest)) {
     log(`✓ Installation complete!`);
     log(`Skills are now available globally:`);
     log(`  /intuition-start       - Load project context and enforce compliance`);
-    log(`  /intuition-plan        - Planning skill (develop structured plans)`);
-    log(`  /intuition-execute     - Execution skill (orchestrate implementation)`);
+    log(`  /intuition-discovery   - Discovery with Waldo (GAPP dialogue)`);
+    log(`  /intuition-plan        - Planning with Magellan (strategic planning)`);
+    log(`  /intuition-execute     - Execution with Faraday (methodical implementation)`);
     log(`  /intuition-initialize  - Project initialization (set up project memory)`);
     log(`\nYou can now use these skills in any project with Claude Code.`);
   } else {

package/scripts/uninstall-skills.js

@@ -40,17 +40,21 @@ try {
     process.exit(0);
   }
 
-  // Remove /plan skill
-  const planDest = path.join(claudeSkillsDir, 'plan');
-  if (removeDir(planDest)) {
-    log(`✓ Removed /plan skill from ${planDest}`);
-  }
+  // Remove all Intuition skills
+  const skillsToRemove = [
+    'intuition-start',
+    'intuition-initialize',
+    'intuition-discovery',
+    'intuition-plan',
+    'intuition-execute'
+  ];
 
-  // Remove /execute skill
-  const executeDest = path.join(claudeSkillsDir, 'execute');
-  if (removeDir(executeDest)) {
-    log(`✓ Removed /execute skill from ${executeDest}`);
-  }
+  skillsToRemove.forEach(skillName => {
+    const skillDest = path.join(claudeSkillsDir, skillName);
+    if (removeDir(skillDest)) {
+      log(`✓ Removed /${skillName} skill from ${skillDest}`);
+    }
+  });
 
   // Clean up empty .claude/skills directory if it's empty
   if (fs.existsSync(claudeSkillsDir)) {