@tgoodington/intuition 8.1.1 → 8.1.2

package/README.md

@@ -1,440 +1,131 @@
-# Intuition v2
+# Intuition
 
-A five-skill orchestration system for software development. Intuition coordinates discovery, planning, and execution through a symphony of specialized agents, with explicit handoff phases maintaining clean context and memory consistency.
+A trunk-and-branch workflow system for Claude Code. Turns rough ideas into structured plans, detailed designs, code specifications, and verified implementations through guided dialogue.
 
-**The Five Skills:**
-1. **`/intuition-start`** - Session primer (load context, detect phase, suggest next step)
-2. **`/intuition-discovery`** - Waldo (explore problems through GAPP and Socratic dialogue)
-3. **`/intuition-handoff`** - Orchestrator (extract insights, update memory, brief next agent)
-4. **`/intuition-plan`** - Magellan (synthesize discovery into structured executable plans)
-5. **`/intuition-execute`** - Faraday (orchestrate implementation with methodical precision)
+**npm**: [`@tgoodington/intuition`](https://www.npmjs.com/package/@tgoodington/intuition)
+**GitHub**: [tgoodington/intuition](https://github.com/tgoodington/intuition)
 
-**Also includes:**
-- `/intuition-initialize` - Setup project memory system
-
-## Quick Start
-
-```bash
-# Install globally
-npm install -g intuition
-
-# In Claude Code, typical workflow:
-/intuition-start            # Load context and check workflow status
-/intuition-discovery        # Waldo guides discovery (GAPP dialogue)
-/intuition-handoff          # Extract insights, brief planner
-/intuition-plan             # Magellan creates structured plan
-/intuition-handoff          # Prepare execution context
-/intuition-execute          # Faraday orchestrates implementation
-```
-
-**Key Point:** Always start with `/intuition-start` — it will tell you which step to take next.
-
-## Why Five Skills?
-
-Each skill has a focused responsibility:
-
-| Skill | Role | Phase | Input | Output | Focus |
-|-------|------|-------|-------|--------|-------|
-| `/intuition-start` | Primer | Any | State file | Context brief + suggestion | Navigation |
-| `/intuition-discovery` | Waldo | Discovery | Problem description | `discovery_brief.md`, `discovery_output.json` | Understanding & dialogue |
-| `/intuition-handoff` | Orchestrator | Transition | Phase output | Updated memory + brief | Context bridging |
-| `/intuition-plan` | Magellan | Planning | `planning_brief.md` | `plan.md` | Strategy & synthesis |
-| `/intuition-execute` | Faraday | Execution | `execution_brief.md` | Code + memory | Implementation |
-
-By splitting into five phases with explicit handoffs:
-- **Clean context** - Each skill gets exactly what it needs, nothing more
-- **Memory consistency** - Handoff maintains project memory across phases
-- **Higher success rate** - Less context bloat, better focus
-- **Resume support** - Interrupted work picks up from last checkpoint
-- **Transparency** - Every phase produces readable, auditable outputs
-
-## The Five-Phase Workflow
-
-### Phase 1: Discovery with Waldo
-
-Explore your problem deeply using the GAPP framework:
-
-```
-/intuition-discovery
-```
-
-Waldo guides you through genuine dialogue covering:
-- **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` + `discovery_output.json`
-
-Uses Socratic questioning and systems thinking to surface authentic intentions.
-
-### Phase 1.5: Discovery → Planning Handoff
-
-Process discovery and prepare for planning:
-
-```
-/intuition-handoff
-```
-
-The orchestrator:
-1. Reads your discovery output
-2. Extracts key facts, decisions, constraints
-3. Updates project memory files
-4. Generates `planning_brief.md` for Magellan
-5. Updates workflow state
-
-**Output:** Updated memory + fresh planning context
-
-### Phase 2: Planning with Magellan
-
-Create a structured plan from discovery:
-
-```
-/intuition-plan
-```
-
-Magellan:
-1. Reads your planning brief and memory
-2. Researches your codebase
-3. Synthesizes insights into a strategic plan
-4. 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.
-
-### Phase 2.5: Planning → Execution Handoff
-
-Process plan and prepare for execution:
-
-```
-/intuition-handoff
-```
-
-The orchestrator:
-1. Reads your plan
-2. Extracts task structure and risks
-3. Updates project memory with planning outcomes
-4. Generates `execution_brief.md` for Faraday
-5. Updates workflow state
-
-**Output:** Updated memory + fresh execution context
-
-### Phase 3: Execution with Faraday
-
-Execute the approved plan:
-
-```
-/intuition-execute
-```
-
-Faraday:
-1. Reads execution brief and memory
-2. Confirms approach with you
-3. Delegates to specialized sub-agents
-4. Verifies outputs against acceptance criteria
-5. Updates project memory
-6. Reports completion
-
-**Output:** Implemented code + updated project memory
-
-## Project Memory System
-
-Intuition maintains persistent project knowledge:
-
-```
-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)
-```
-
-All three agents reference and update project memory for consistency.
-
-## Workflow Status
-
-Check where you are in the workflow:
-
-```
-/intuition-start
-```
-
-Returns current status:
-- **Discovery:** In progress / Complete
-- **Planning:** In progress / Complete / Approved
-- **Execution:** In progress / Complete
-
-Also provides helpful next-step suggestions.
-
-## File Outputs
-
-### discovery_brief.md (From Waldo)
-
-```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 (From Magellan)
-
-```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 Support
-
-All three agents can resume 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 from the checkpoint.
-
-## Discovery Revision
-
-If you need to revise your discovery:
-
-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)
+## Install
 
 ```bash
 npm install -g @tgoodington/intuition
 ```
 
-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
+This installs 12 skills globally to `~/.claude/skills/`. Verify by typing `/` in Claude Code — you should see skills starting with `intuition-`.
 
-### Install from Source (Development)
+## Workflow
 
-```bash
-cd intuition
-npm install -g .
-```
-
-### Verify Installation
-
-In Claude Code, type `/` to see available skills. You should see all five:
-- `/intuition-start`
-- `/intuition-initialize`
-- `/intuition-discovery`
-- `/intuition-plan`
-- `/intuition-execute`
-
-## Skills Reference
-
-### `/intuition-start`
-
-Load project context and check workflow status.
+Five phases with handoff transitions between each:
 
 ```
-/intuition-start
+prompt → plan → [design] → engineer → build
 ```
 
-**Does:**
-- Loads project memory files
-- Checks workflow status
-- Suggests next steps based on status
-- Enforces project protocols
-
-**When to use:** Start of every session
+The first cycle is the **trunk**. After completion, create **branches** for new features or changes.
 
-### `/intuition-initialize`
-
-Setup project memory system.
+### Quick Start
 
 ```
-/intuition-initialize
+/intuition-initialize          # Set up project memory (once per project)
+/intuition-start               # Check status, get routed to next step
+/intuition-prompt              # Describe what you want to build
+/intuition-handoff             # Process → move to planning
+/intuition-plan                # Create the blueprint
+/intuition-handoff             # Review design flags
+/intuition-design              # Elaborate flagged items (if any)
+/intuition-handoff             # Prepare for engineering
+/intuition-engineer            # Create code specifications
+/intuition-handoff             # Prepare for build
+/intuition-build               # Implement and verify
+/intuition-handoff             # Complete the cycle
 ```
 
-**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
+Run `/clear` before each phase skill to keep context clean. Not every project needs design — if the plan is clear enough, handoff skips straight to engineer.
 
-**When to use:** Once per project, at the start
+## Skills
 
-### `/intuition-discovery`
+### Core Workflow
 
-Explore your problem with Waldo.
+| Skill | Model | Purpose |
+|-------|-------|---------|
+| `/intuition-prompt` | opus | Refines a rough idea into a planning-ready brief |
+| `/intuition-plan` | opus | Strategic blueprint with tasks, dependencies, design flags |
+| `/intuition-design` | opus | ECD framework design exploration for flagged items |
+| `/intuition-engineer` | opus | Code-level specs through research + interactive dialogue |
+| `/intuition-build` | sonnet | Delegates implementation, verifies against specs |
 
-```
-/intuition-discovery
-```
+### Infrastructure
 
-**Waldo does:**
-- GAPP discovery (Problem → Goals → UX Context → Personalization)
-- Socratic questioning
-- Systems thinking perspective
-- Clarifying questions to validate understanding
-- Saves `discovery_brief.md`
+| Skill | Model | Purpose |
+|-------|-------|---------|
+| `/intuition-start` | haiku | Detects phase, routes to next skill, version check |
+| `/intuition-handoff` | haiku | State transitions, brief generation, design loop |
+| `/intuition-initialize` | haiku | Project memory setup (run once) |
+| `/intuition-update` | haiku | Package update manager |
 
-**When to use:** Start of new work
+### Advisory
 
-### `/intuition-plan`
+| Skill | Model | Purpose |
+|-------|-------|---------|
+| `/intuition-debugger` | opus | Expert diagnostics for complex post-completion bugs |
+| `/intuition-agent-advisor` | opus | Guidance on building custom Claude Code agents |
+| `/intuition-skill-guide` | opus | Guidance on building custom Claude Code skills |
 
-Create a plan with Magellan.
+## Key Concepts
 
-```
-/intuition-plan
-```
+### Engineer → Build Split
 
-**Magellan does:**
-- Reads your discovery brief
-- Researches codebase (parallel agents)
-- Synthesizes into strategic plan
-- Auto-detects planning depth
-- Saves `plan.md`
+- **Engineer** (opus) determines the code-level HOW: researches codebase, discusses decisions interactively, produces `code_specs.md`
+- **Build** (sonnet) implements against specs: delegates to subagents, verifies with reviewers, runs mandatory security review, produces `build_report.md`
 
-**When to use:** After discovery is complete
+### Trunk and Branches
 
-### `/intuition-execute`
+- **Trunk**: First prompt→build cycle — the foundation
+- **Branches**: Subsequent cycles that read parent context for continuity
+- After any cycle completes, `/intuition-start` offers branch creation or debugging
 
-Execute the plan with Faraday.
+### Design Loop
 
-```
-/intuition-execute
-```
+The plan flags tasks needing design exploration. Handoff manages a loop: design one item → check for more → design next or advance to engineer.
 
-**Faraday does:**
-- Reads plan and discovery context
-- Confirms approach with you
-- Delegates to sub-agents (parallel when possible)
-- Verifies outputs
-- Updates project memory
+### Project Memory
 
-**When to use:** After plan is approved
-
-## Sub-Agents
-
-Faraday coordinates these specialized agents:
-
-| 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 |
-
-## Documentation
-
-- **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`
-
-## Requirements
-
-- Node.js 14.0.0 or higher
-- Claude Code or similar agent system
+All workflow state and knowledge lives in `docs/project_notes/`:
+- Shared memory: `bugs.md`, `decisions.md`, `key_facts.md`, `issues.md`
+- State: `.project-memory-state.json` (owned by handoff)
+- Phase outputs: briefs, plan, code specs, build report (in context-specific paths)
 
 ## Project Structure
 
 ```
 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
-├── docs/                       # Documentation
-│   ├── intuition-workflow.md   # User guide
-│   └── intuition-architecture.md # Technical details
-├── scripts/                    # Installation scripts
-├── package.json                # npm package config
-└── README.md                   # This file
+│   ├── intuition-start/           # Session primer + routing
+│   ├── intuition-prompt/          # Discovery refinement
+│   ├── intuition-plan/            # Strategic planning
+│   ├── intuition-design/          # ECD design exploration
+│   ├── intuition-engineer/        # Code spec creation
+│   ├── intuition-build/           # Implementation + verification
+│   ├── intuition-handoff/         # State transitions + briefs
+│   ├── intuition-debugger/        # Post-completion diagnostics
+│   ├── intuition-initialize/      # Project memory setup
+│   ├── intuition-update/          # Package updates
+│   ├── intuition-agent-advisor/   # Agent building guidance
+│   └── intuition-skill-guide/     # Skill building guidance
+├── scripts/
+│   ├── install-skills.js          # Postinstall → copies skills to ~/.claude/skills/
+│   └── uninstall-skills.js        # Preuninstall → removes skills
+├── docs/                          # Architecture and design documentation
+├── bin/                           # CLI entry point
+├── package.json
+└── README.md
 ```
 
-## Contributing
+## Requirements
 
-Contributions welcome! Areas for enhancement:
-- Additional specialized sub-agents
-- Workflow improvements
-- Documentation enhancements
-- Framework extensions
+- Node.js 14.0.0+
+- Claude Code
 
 ## License
 
 MIT
-
-## Support
-
-For issues or questions:
-- 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "8.1.1",
+  "version": "8.1.2",
   "description": "Trunk-and-branch workflow system for Claude Code: prompt, plan, design, engineer, build with iterative branching. Code spec creation, domain-agnostic design exploration with ECD framework, and file-based handoffs through project memory.",
   "keywords": [
     "claude-code",

package/skills/intuition-design/SKILL.md

@@ -24,6 +24,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 12. You MUST NOT modify `plan.md`, `discovery_brief.md`, or `design_brief.md`.
 13. You MUST NOT manage `.project-memory-state.json` — handoff owns state transitions.
 14. You MUST treat user input as suggestions unless explicitly stated as requirements. Evaluate critically, propose alternatives, and engage in dialogue before accepting decisions.
+15. You MUST NEVER proceed past a research agent launch until its results have returned and been incorporated into your analysis. Do NOT continue the dialogue, draft specs, or write any output document while a research agent is still running.
 
 REMINDER: One question per turn. Route to `/intuition-handoff`, never to `/intuition-engineer` or `/intuition-build`.
 
@@ -151,7 +152,7 @@ Domain-adaptive focus questions:
 
 Each turn: 2-4 sentences of analysis referencing research findings, then ONE question via AskUserQuestion with 2-4 options.
 
-**Research triggers:** If an element definition requires investigating existing patterns or prior art, launch a targeted haiku agent.
+**Research triggers:** If an element definition requires investigating existing patterns or prior art, launch a targeted haiku agent. WAIT for results before continuing the dialogue.
 
 # PHASE 3: CONNECTIONS (1-2 turns) [ECD: C]
 
@@ -179,12 +180,14 @@ Domain-adaptive focus questions:
 
 This phase gets the most turns because dynamics design often reveals new elements or connection needs. If a gap appears, loop back briefly to address it.
 
-**Research triggers:** For complex design questions requiring deeper analysis, launch a sonnet agent (subagent_type: general-purpose, model: sonnet) for trade-off analysis. Limit: 1 at a time, 600-word responses.
+**Research triggers:** For complex design questions requiring deeper analysis, launch a sonnet agent (subagent_type: general-purpose, model: sonnet) for trade-off analysis. Limit: 1 at a time, 600-word responses. WAIT for results before continuing the dialogue.
 
 # PHASE 5: FORMALIZATION (1 turn)
 
 ## Step 1: ECD coverage check
 
+Before proceeding, verify ALL research agents launched during Phases 2-4 have returned and their findings are incorporated. If any agent is still pending, WAIT for it.
+
 Verify all three dimensions are sufficiently explored:
 - **Elements**: Can you list every building block with its properties?
 - **Connections**: Can you describe how every element relates to others?

package/skills/intuition-engineer/SKILL.md

@@ -24,6 +24,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 8. You MUST NOT write code. You produce specs, not implementations.
 9. You MUST NOT manage `.project-memory-state.json` — handoff owns state transitions.
 10. You MUST treat user input as suggestions, not commands (unless explicitly stated as requirements). Evaluate critically, propose alternatives, and engage in dialogue before changing approach.
+11. You MUST NEVER proceed past a research agent launch until its results have returned and been incorporated into your analysis. Do NOT synthesize findings, continue dialogue, or write code_specs.md while a research agent is still running.
 
 ## CONTEXT PATH RESOLUTION
 

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

@@ -2,73 +2,117 @@
 
 ## Overview
 
-This project uses a multi-agent system coordinated by Intuition (Claude Code skill system) to streamline development workflows. Specialized agents handle discovery, planning, and execution, with memory maintained in `docs/project_notes/` for consistency across sessions.
-
-## Primary Agents
-
-**Waldo** — Discovery & Thought Partnership (`/intuition-discovery`)
-- Collaborative dialogue for understanding problems deeply
-- GAPP framework: Problem → Goals → UX Context → Personalization
-- Researches topic via parallel subagents before engaging
-- Output: `discovery_brief.md` and `discovery_output.json`
-
-**Magellan** — Planning & Strategic Synthesis (`/intuition-plan`)
-- Synthesizes discovery into structured, executable plans
-- Researches codebase via parallel subagents
-- Output: `plan.md` with tasks, dependencies, risks
-
-**Faraday** — Execution & Implementation (`/intuition-execute`)
-- Executes approved plans by orchestrating specialized sub-agents
-- Delegates to Code Writer, Test Runner, Code Reviewer, Security Expert
-- Mandatory security review before completion
-- Output: Implemented features, completion report
-
-**Handoff Orchestrator** (`/intuition-handoff`)
-- Processes phase outputs, updates memory files, briefs next agent
-- ONLY component that writes to `.project-memory-state.json`
-- Bridges discovery→planning and planning→execution transitions
-
-## Specialized Sub-Agents
-
-**Code Writer** — Implements features and fixes
-**Test Runner** — Runs unit and integration tests
-**Code Reviewer** — Reviews quality, maintainability, security
-**Security Expert** — Scans for vulnerabilities (mandatory before completion)
-**Documentation** — Creates and updates docs
-**Research** — Investigates issues, explores codebases
-
-## Workflow Patterns
-
-### Pattern 1: Full Feature Development (Recommended)
-1. User → Waldo (collaborative discovery dialogue)
-2. Handoff (processes discovery, briefs planner)
-3. Magellan (creates structured plan)
-4. Handoff (processes plan, briefs executor)
-5. Faraday → Sub-agents (parallel delegation)
-6. Security Expert review (mandatory)
-
-### Pattern 2: Direct Execution (Simple Tasks)
-1. User → Faraday (describe what to do)
-2. Faraday → Sub-agents (delegated work)
-3. Security Expert review
-
-## Project Memory Integration
-
-**Memory Files Location**: `docs/project_notes/`
-- `bugs.md` — Bug log with solutions
-- `decisions.md` — Architectural Decision Records
-- `key_facts.md` — Project configuration, constants
+This project uses a multi-agent system coordinated by Intuition (`@tgoodington/intuition`), a Claude Code skill system. Twelve specialized skills handle prompt refinement, planning, design exploration, code engineering, and build execution, with memory maintained in `docs/project_notes/` for consistency across sessions.
+
+## Workflow Skills
+
+### Core Workflow (run in sequence with handoff between each)
+
+| Skill | Model | What it does |
+|-------|-------|-------------|
+| `/intuition-prompt` | opus | Transforms a rough vision into a planning-ready brief through focused iterative refinement |
+| `/intuition-plan` | opus | Strategic architect — maps stakeholders, explores components, evaluates options, creates executable blueprint |
+| `/intuition-design` | opus | Elaborates flagged plan items through ECD framework (Elements, Connections, Dynamics) |
+| `/intuition-engineer` | opus | Creates code-level specifications through codebase research and interactive dialogue → `code_specs.md` |
+| `/intuition-build` | sonnet | Delegates implementation to subagents, verifies outputs against code specs and acceptance criteria |
+
+### Infrastructure
+
+| Skill | Model | What it does |
+|-------|-------|-------------|
+| `/intuition-start` | haiku | Loads project context, detects workflow phase, routes to correct next skill |
+| `/intuition-handoff` | haiku | Processes phase outputs, updates memory, generates briefs for the next phase |
+| `/intuition-initialize` | haiku | Sets up project memory infrastructure (run once per project) |
+| `/intuition-update` | haiku | Package update manager |
+
+### Advisory
+
+| Skill | Model | What it does |
+|-------|-------|-------------|
+| `/intuition-debugger` | opus | Expert debugger — 5 diagnostic categories, causal chain analysis, post-completion only |
+| `/intuition-agent-advisor` | opus | Expert advisor on building custom Claude Code agents |
+| `/intuition-skill-guide` | opus | Expert advisor on building custom Claude Code skills |
+
+## Model Strategy
+
+- **opus** — Complex multi-step reasoning: prompt refinement, planning, design exploration, code engineering, debugging, advisory
+- **sonnet** — Project management and delegation: build manager, broad research subagents
+- **haiku** — Focused simple tasks: start, handoff, state updates, narrow research subagents
+
+## Workflow
+
+### Trunk (first cycle)
+
+```
+/intuition-prompt → handoff → /intuition-plan → handoff →
+  [/intuition-design loop] → handoff → /intuition-engineer → handoff →
+  /intuition-build → handoff → complete
+```
+
+Each handoff transition:
+1. Reads the previous phase's output
+2. Updates shared memory files
+3. Generates a fresh brief for the next phase
+4. Updates `.project-memory-state.json`
+5. Routes to the next skill (with `/clear` between phases)
+
+### Branches (subsequent cycles)
+
+After trunk completes, run `/intuition-start` to:
+- **Create a branch** — new prompt→build cycle informed by trunk context
+- **Open the debugger** — investigate hard problems in any completed context
+
+Branches follow the same 5-phase workflow but read parent context for continuity.
+
+### Design Loop (optional)
+
+The plan flags tasks requiring design exploration (Section 6.5). If design items exist:
+1. Handoff generates a design brief for the first item
+2. `/intuition-design` elaborates it using the ECD framework
+3. Handoff checks for remaining items → loops back or advances to engineer
+
+### Engineer → Build Split
+
+- **Engineer** (opus, interactive) determines the code-level HOW: reads codebase via research subagents, discusses decisions with you, produces `code_specs.md`
+- **Build** (sonnet, PM) implements against specs: delegates to Code Writer subagents, verifies with Code Reviewer, runs mandatory Security Expert review, produces `build_report.md`
+- Build makes NO engineering decisions — it matches output to specs
+
+## Build Sub-Agents
+
+The build phase delegates to these task-based subagents via the Task tool:
+
+| Sub-Agent | Model | Purpose |
+|-----------|-------|---------|
+| Code Writer | sonnet | Implements features and fixes per code specs |
+| Code Reviewer | sonnet | Reviews quality, maintainability, adherence to specs |
+| Security Expert | sonnet | Scans for vulnerabilities (mandatory before completion) |
+
+## Project Memory
+
+**Memory Files** (`docs/project_notes/`):
+- `bugs.md` — Bug log with solutions and prevention notes
+- `decisions.md` — Architectural Decision Records (ADRs)
+- `key_facts.md` — Project configuration, constants, URLs
 - `issues.md` — Work log with ticket references
 
-**How Agents Use Memory:**
+**Phase Output Files** (in `{context_path}/`):
+- `planning_brief.md` — Brief for planning (created by handoff)
+- `plan.md` — Structured plan with tasks, design recommendations
+- `design_brief.md` — Brief for current design item (created/updated by handoff)
+- `engineering_brief.md` — Brief for engineering (created by handoff)
+- `code_specs.md` — Code-level specifications (created by engineer)
+- `build_brief.md` — Brief for build (created by handoff)
+- `build_report.md` — Task outcomes, files modified (created by build)
+
+**How Skills Use Memory:**
 - Check `decisions.md` before proposing architectural changes
 - Search `bugs.md` for similar issues before debugging
 - Reference `key_facts.md` for project configuration
 - Log completed work in `issues.md`
 
-## Agent Coordination
+## Coordination
 
-- All work skills route to `/intuition-handoff` between phases
-- Handoff owns all state transitions in `.project-memory-state.json`
-- Agents use structured markdown output
-- State is tracked in memory files for cross-session continuity
+- All workflow skills route to `/intuition-handoff` between phases
+- Handoff is the ONLY skill that writes to `.project-memory-state.json`
+- `/clear` runs between phases to keep context clean (each skill reads from disk)
+- State tracks trunk, branches, and active context with per-context workflow pipelines

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

@@ -1,16 +1,17 @@
 ## Project Workflow and Memory System
 
-This project uses a four-phase workflow coordinated by the Intuition system, with institutional knowledge maintained in `docs/project_notes/` for consistency across sessions.
+This project uses a five-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.
+- **Trunk**: The first prompt→plan→design→engineer→build cycle. Represents the core vision.
 - **Branches**: Subsequent cycles that build on, extend, or diverge from trunk or other branches.
-- **Debugger**: Post-execution diagnostic specialist for hard problems.
+- **Debugger**: Post-completion diagnostic specialist for hard problems.
 
 All phases: `/intuition-prompt` → `/intuition-handoff` → `/intuition-plan` → `/intuition-handoff` →
-`[/intuition-design loop]` → `/intuition-handoff` → `/intuition-execute` → `/intuition-handoff` → complete
+`[/intuition-design loop]` → `/intuition-handoff` → `/intuition-engineer` → `/intuition-handoff` →
+`/intuition-build` → `/intuition-handoff` → complete
 
 After completion: `/intuition-start` to create branches or `/intuition-debugger` to debug issues.
 
@@ -19,12 +20,12 @@ After completion: `/intuition-start` to create branches or `/intuition-debugger`
 The project follows a structured workflow with handoff transitions between phases:
 
 **Prompt** — `/intuition-prompt`
-- Transforms a rough vision into a precise, planning-ready discovery brief
+- Transforms a rough vision into a precise, planning-ready brief
 - Framework: Capture → Refine → Reflect → Confirm
-- Output: `discovery_brief.md` and `discovery_output.json`
+- Output: Planning-ready brief (processed by Handoff into `planning_brief.md`)
 
 **Handoff** — `/intuition-handoff`
-- Processes phase outputs, updates memory files, generates brief for next agent
+- Processes phase outputs, updates memory files, generates brief for next phase
 - Runs between every phase transition
 - Manages the design loop (item-by-item design cycles)
 - ONLY component that writes to `.project-memory-state.json`
@@ -40,21 +41,26 @@ The project follows a structured workflow with handoff transitions between phase
 - 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
+- Output: Design specifications 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
+**Engineering** — `/intuition-engineer`
+- Creates code-level specifications through codebase research and interactive dialogue
+- Research subagents read codebase, engineer discusses decisions with user
+- Output: `code_specs.md` — determines the code-level HOW for every task
+
+**Build** — `/intuition-build`
+- Delegates implementation to subagents, verifies against code specs and acceptance criteria
+- Mandatory security review before completion
+- Makes NO engineering decisions — matches output to specs
+- Output: `build_report.md` — task outcomes, files modified, deviations from specs
 
 **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**: Prompt → Handoff → Plan → Handoff → [Design Loop] → Handoff → Execute → Handoff → complete
+**Recommended Flow**: Prompt → Handoff → Plan → Handoff → [Design Loop] → Handoff → Engineer → Handoff → Build → Handoff → complete
 
-After completion, run `/intuition-start` to create a branch or invoke `/intuition-debugger` to debug issues.
+Run `/clear` before each phase skill. After completion, run `/intuition-start` to create a branch or invoke `/intuition-debugger` to debug issues.
 
 ### Memory Files
 
@@ -65,14 +71,14 @@ After completion, run `/intuition-start` to create a branch or invoke `/intuitio
 - **issues.md** — Work log with ticket IDs, descriptions, and URLs
 - **.project-memory-state.json** — Workflow phase tracking and session state
 
-**Phase Output Files** (created during workflow):
-- **discovery_brief.md** — Prompt phase synthesis
-- **discovery_output.json** — Structured findings (processed by Handoff)
+**Phase Output Files** (created during workflow, in `{context_path}/`):
 - **planning_brief.md** — Brief for planning phase (created by Handoff)
 - **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)
+- **engineering_brief.md** — Brief for engineering phase (created by Handoff)
+- **code_specs.md** — Code-level specifications (created by Engineer)
+- **build_brief.md** — Brief for build phase (created by Handoff)
+- **build_report.md** — Task outcomes and files modified (created by Build)
 
 ### Memory-Aware Protocols
 
@@ -107,16 +113,22 @@ After completion, run `/intuition-start` to create a branch or invoke `/intuitio
 - "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."
+- "This sounds like a good candidate for planning. Use `/intuition-handoff` to process the brief, then `/intuition-plan` to develop a structured approach."
 
 **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."
+- "All design specs are done! Use `/intuition-handoff` to prepare the engineering brief."
+
+**When user is ready to engineer:**
+- "Engineering brief is ready! Use `/intuition-engineer` to create code specifications."
+
+**When engineering is complete:**
+- "Code specs are ready! Use `/intuition-handoff` to prepare the build brief."
 
-**When user is ready to execute:**
-- "Execution brief is ready! Use `/intuition-execute` to kick off coordinated implementation."
+**When user is ready to build:**
+- "Build brief is ready! Use `/intuition-build` to kick off implementation."
 
-**When execution is complete:**
+**When build is complete:**
 - "Workflow cycle complete! Use `/intuition-start` to create a branch for new work, or `/intuition-debugger` to debug any issues."

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

@@ -1,6 +1,6 @@
 # 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 debugging.
+A trunk-and-branch workflow system for Claude Code. Turns rough ideas into structured plans, detailed designs, code specifications, and verified implementations through guided dialogue. Supports iterative development through independent branch cycles and post-completion debugging.
 
 ## Workflow
 
@@ -9,16 +9,18 @@ A trunk-and-branch workflow system for Claude Code. Turns rough ideas into struc
                                                                         ↓
                                                               [design loop, if needed]
                                                                         ↓
-                                                /intuition-execute  ←  /intuition-handoff
+                                                               /intuition-handoff  →  /intuition-engineer
+                                                                                            ↓
+                                               /intuition-build  ←  /intuition-handoff
                                                         ↓
                                                /intuition-handoff  →  complete
                                                         ↓
                               /intuition-start  →  create branch  or  /intuition-debugger
 ```
 
-Run `/intuition-handoff` between every phase. It manages state, generates briefs, and routes you forward.
+Run `/intuition-handoff` between every phase. It manages state, generates briefs, and routes you forward. Run `/clear` before each new phase skill to keep context clean.
 
-The first prompt→execute cycle is the **trunk**. After trunk completes, create **branches** for new features or changes. Use `/intuition-debugger` to investigate hard problems in any completed context.
+The first prompt→build cycle is the **trunk**. After trunk completes, create **branches** for new features or changes. Use `/intuition-debugger` to investigate hard problems in any completed context.
 
 ## Skills
 
@@ -28,7 +30,8 @@ The first prompt→execute cycle is the **trunk**. After trunk completes, create
 | `/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` | Tech lead orchestrator — engineering assessment, implementation guide, informed delegation |
+| `/intuition-engineer` | Creates code-level specifications through codebase research and interactive dialogue |
+| `/intuition-build` | Delegates implementation to subagents, verifies against code specs and acceptance criteria |
 | `/intuition-debugger` | Expert debugger — diagnostic specialist for complex bugs, cross-context failures, performance issues |
 | `/intuition-handoff` | Processes phase outputs, updates memory, prepares the next phase |
 | `/intuition-initialize` | Sets up project memory (you already ran this) |
@@ -43,15 +46,17 @@ The first prompt→execute cycle is the **trunk**. After trunk completes, create
 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
+7. `/intuition-handoff` — prepare for engineering
+8. `/intuition-engineer` — create code specifications
+9. `/intuition-handoff` — prepare for build
+10. `/intuition-build` — implement and verify
+11. `/intuition-handoff` — complete the cycle
 
-Not every project needs design. If the plan is clear enough, handoff skips straight to execute.
+Not every project needs design. If the plan is clear enough, handoff skips straight to engineer. Run `/clear` before each phase skill.
 
 ### After trunk completes (branches)
 
-10. `/intuition-start` — see project status and choose next step
+12. `/intuition-start` — see project status and choose next step
     - **Create a branch** — start a new feature or change cycle, informed by trunk
     - **Open the debugger** — investigate hard problems in any completed context
 

package/skills/intuition-plan/SKILL.md

@@ -26,6 +26,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 14. You MUST treat user input as suggestions unless explicitly stated as requirements. Evaluate critically and propose alternatives when warranted.
 15. 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).
 16. When planning on a branch, you MUST read the parent context's plan.md and include a Parent Context section (Section 2.5). Inherited architectural decisions from the parent are binding unless the user explicitly overrides them.
+17. You MUST NEVER proceed past a research agent launch until its results have returned and been incorporated into your analysis. Do NOT draft options, present findings, or write any output document while a research agent is still running.
 
 REMINDER: One question per turn. Route to `/intuition-handoff`, never to `/intuition-engineer` or `/intuition-build`.
 
@@ -221,7 +222,8 @@ For each major decision domain identified from the discovery brief, orientation
    - Each agent prompt MUST reference the specific decision domain, return under 400 words.
    - Write results to `{context_path}/.planning_research/decision_[domain].md` (snake_case).
    - NEVER launch more than 2 agents simultaneously.
-3. **Present** 2-3 options with trade-offs. Include your recommendation and why.
+   - WAIT for all research agents to return and read their results before proceeding to step 3.
+3. **Present** 2-3 options with trade-offs. Include your recommendation and why. Incorporate the research findings.
 4. **Ask** the user to select via AskUserQuestion.
 5. **Record** the resolved decision to `{context_path}/.planning_research/decisions_log.md`:
 
@@ -267,6 +269,8 @@ If the user wants to discuss more, return to Phase 3.
 
 ## Step 2: Draft the plan
 
+Before drafting, verify ALL research agents launched during Phase 3 have returned and their findings are recorded in `decisions_log.md`. If any agent is still pending, WAIT for it.
+
 Read `{context_path}/.planning_research/decisions_log.md` and `orientation.md` to gather resolved context. Draft the plan following the plan.md output format below, applying scope scaling for the selected tier.
 
 ## Step 3: Validate