@tgoodington/intuition 11.4.0 → 11.5.1

package/docs/archive/intuition-architecture.md

@@ -1,342 +0,0 @@
-# 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/archive/intuition-workflow.md

@@ -1,210 +0,0 @@
-# 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!