@tgoodington/intuition 8.1.0 → 8.1.2

package/skills/intuition-initialize/SKILL.md

@@ -2,41 +2,69 @@
 name: intuition-initialize
 description: Set up project memory infrastructure with workflow state tracking, memory files, and configuration templates.
 model: haiku
-tools: Read, Write, Glob, Grep, AskUserQuestion
+tools: Read, Write, Glob, Grep, Bash, AskUserQuestion
 allowed-tools: Read, Write, Glob, Grep
 ---
 
 # Initialize - Project Memory Setup Protocol
 
-You are the project memory initializer. You create the `docs/project_notes/` directory structure, initialize memory files from templates, create the workflow state file, and configure CLAUDE.md with memory-aware protocols. You run once per project to set up infrastructure, then hand off to the workflow skills.
+You create the `docs/project_notes/` directory structure, initialize memory files from templates, create the workflow state file, and set up project configuration files. You run once per project to set up infrastructure, then hand off to the workflow skills.
 
 ## CRITICAL RULES
 
-These are non-negotiable. Violating any of these means the protocol has failed.
-
-1. You MUST check if `docs/project_notes/` already exists before creating anything.
-2. You MUST use template files from `references/` directory for all initial content. Read each template with the Read tool, then Write to the target path.
-3. You MUST create `.project-memory-state.json` using the v5.0 schema from `references/state_template.json`. Do NOT use older schemas (v1.0, v2.0, v3.0, v4.0).
-4. You MUST update CLAUDE.md with workflow and memory protocols.
-5. You MUST NOT overwrite existing memory files without asking the user first.
-6. You MUST NOT invoke other skills (discovery, plan, execute). You only set up infrastructure.
-7. You MUST ask the user before creating optional components (AGENTS.md, settings, user profile).
+1. You MUST check install location before doing anything else — enforce global install.
+2. You MUST check if `docs/project_notes/` already exists before creating anything.
+3. You MUST use template files from `references/` directory for all initial content. Read each template with the Read tool, then Write to the target path.
+4. You MUST create `.project-memory-state.json` using the v5.0 schema from `references/state_template.json`. Do NOT use older schemas.
+5. You MUST auto-create all configuration files (CLAUDE.md, INTUITION.md, AGENTS.md, settings, profile) if they do not exist. Do NOT ask — just create them.
+6. You MUST NOT overwrite existing files. If a file already exists, skip it silently.
+7. You MUST NOT invoke other skills. You only set up infrastructure.
 8. You MUST report what was created at the end.
 
 ## PROTOCOL: COMPLETE FLOW
 
-Execute these steps in order:
-
 ```
+Step 0: Check install location — enforce global install
 Step 1: Detect existing setup
 Step 2: Create memory directory and files from templates
 Step 3: Create .project-memory-state.json with v5.0 schema
 Step 4: Update CLAUDE.md with workflow protocols
 Step 4.5: Create INTUITION.md framework overview
-Step 5: Offer optional components (AGENTS.md, settings, user profile)
+Step 5: Create configuration files (AGENTS.md, settings, user profile)
 Step 6: Report completion and suggest next step
 ```
 
+## STEP 0: ENFORCE GLOBAL INSTALL
+
+Before anything else, check whether `@tgoodington/intuition` is installed locally (project-level) vs globally.
+
+Run these checks using Bash:
+
+```
+Local:  npm list @tgoodington/intuition --depth=0 2>&1
+Global: npm list -g @tgoodington/intuition --depth=0 2>&1
+```
+
+Apply this logic:
+
+```
+IF local install found AND global install found:
+  → Uninstall local: npm uninstall @tgoodington/intuition
+  → Notify: "Removed local install. Using global install."
+
+IF local install found AND no global install:
+  → Uninstall local: npm uninstall @tgoodington/intuition
+  → Install global: npm install -g @tgoodington/intuition
+  → Notify: "Moved install from local to global."
+
+IF no local install AND global install found:
+  → Proceed (correct setup)
+
+IF neither found:
+  → Warn: "Package not found. Install with: npm install -g @tgoodington/intuition"
+  → STOP
+```
+
 ## STEP 1: DETECT EXISTING SETUP
 
 Check if `docs/project_notes/` exists.
@@ -83,7 +111,7 @@ For each file, use the Read tool to read the template, then use Write to create
 | `references/key_facts_template.md` | `docs/project_notes/key_facts.md` |
 | `references/issues_template.md` | `docs/project_notes/issues.md` |
 
-Do NOT create workflow output files (discovery_brief.md, plan.md, engineering_brief.md, build_brief.md, etc.). Those are created by their respective skills during the workflow.
+Do NOT create workflow output files (discovery_brief.md, plan.md, etc.). Those are created by their respective skills.
 
 ## STEP 3: CREATE STATE FILE
 
@@ -137,113 +165,69 @@ The state file uses the v5.0 schema:
 }
 ```
 
-**CRITICAL**: This is the authoritative schema. Handoff is the ONLY skill that updates this file after initialization. All other skills read it but NEVER write to it.
-
-Do NOT use older schemas (v1.0, v2.0, v3.0, or v4.0). Those schemas are obsolete.
+**CRITICAL**: Handoff is the ONLY skill that updates this file after initialization.
 
 ## STEP 4: UPDATE CLAUDE.MD
 
 Read `references/claude_template.md` for the workflow protocol content.
 
 ```
-IF CLAUDE.md exists:
-  → Check for existing "Project Workflow and Memory System" section
-  → If section exists: Ask user before replacing
-  → If section missing: Append the template content
-
 IF CLAUDE.md does NOT exist:
   → Create CLAUDE.md with the template content
-```
 
-The template includes:
-- Five-phase workflow description (prompt → plan → design → engineer → build with handoffs)
-- Memory file descriptions and locations
-- Memory-aware protocols (check decisions before changes, search bugs before debugging)
-- Smart skill suggestions (when to suggest /intuition-prompt, /intuition-plan, /intuition-design, /intuition-engineer, /intuition-build, etc.)
+IF CLAUDE.md exists BUT has no "Project Workflow and Memory System" section:
+  → Append the template content to the end of the file
+
+IF CLAUDE.md exists AND already has the section:
+  → Skip (do not overwrite)
+```
 
 ## STEP 4.5: CREATE INTUITION.MD
 
-Read `references/intuition_readme_template.md` and write to `INTUITION.md` at the project root (same level as CLAUDE.md).
+Read `references/intuition_readme_template.md` and write to `INTUITION.md` at the project root.
 
 ```
-IF INTUITION.md already exists:
-  → Ask user: "INTUITION.md already exists. Overwrite with current version?"
-  → If no, skip
-
 IF INTUITION.md does NOT exist:
   → Create it from template
-```
-
-This is a brief, human-readable overview of the Intuition workflow. It helps anyone on the project understand what the skills do and how to use them.
 
-## STEP 5: OPTIONAL COMPONENTS
+IF INTUITION.md already exists:
+  → Skip
+```
 
-Offer each optional component using AskUserQuestion. Do not create without asking.
+## STEP 5: CREATE CONFIGURATION FILES
 
-### 5A: AGENTS.md Configuration
+Auto-create each file if it does not exist. Do NOT ask — just create. If a file already exists, skip it silently.
 
-```
-Question: "Create AGENTS.md with agent registry and coordination protocols?"
-Options:
-- "Yes, create it" (Recommended)
-- "Skip this"
-```
+### 5A: AGENTS.md
 
-If yes:
 - Read `references/agents_template.md`
-- If AGENTS.md exists: append or update the "Multi-Agent System" section
-- If AGENTS.md does not exist: create with full template content
+- If `AGENTS.md` does not exist: create with full template content
+- If `AGENTS.md` exists: skip
 
 ### 5B: Claude Code Settings
 
-```
-Question: "Create .claude/settings.local.json to pre-authorize common tools?"
-Options:
-- "Yes, create it" (Recommended)
-- "Skip this"
-```
-
-If yes:
 - Read `references/settings_template.json`
-- If `.claude/settings.local.json` exists: ask before overwriting
-- If not exists: create from template
-- Pre-authorizes: Read, Glob, Grep, WebSearch, WebFetch, Task, common git operations
+- If `.claude/settings.local.json` does not exist: create from template
+- If `.claude/settings.local.json` exists: skip
 
 ### 5C: User Profile
 
-```
-Question: "Create .claude/USER_PROFILE.json for cross-project user context?"
-Options:
-- "Yes, create it"
-- "Skip this" (Recommended)
-```
-
-If yes:
 - Read `references/user_profile_template.json`
-- If `.claude/USER_PROFILE.json` exists: ask before overwriting
-- If not exists: create from template
-- This is a global file (in `.claude/`), not project-specific
-- Agents populate it naturally through conversation over time
+- If `.claude/USER_PROFILE.json` does not exist: create from template
+- If `.claude/USER_PROFILE.json` exists: skip
 
 ## STEP 6: REPORT COMPLETION
 
-Present a concise summary of what was created:
+Present a concise summary of what was created vs skipped:
 
 ```
 Project memory initialized!
 
 Created:
-- docs/project_notes/trunk/         (trunk workflow artifacts)
-- docs/project_notes/branches/      (branch workflow artifacts)
-- docs/project_notes/bugs.md
-- docs/project_notes/decisions.md
-- docs/project_notes/key_facts.md
-- docs/project_notes/issues.md
-- docs/project_notes/.project-memory-state.json (v5.0 schema)
-- CLAUDE.md workflow protocols
-- INTUITION.md framework overview
-
-[List any optional components created]
+- [list each file that was created]
+
+Skipped (already existed):
+- [list each file that was skipped, if any]
 
 Next step: Run /intuition-prompt to describe what you want to build,
 or /intuition-start to check project status.
@@ -251,78 +235,25 @@ or /intuition-start to check project status.
 
 ## EDGE CASES
 
-- **Partial setup exists**: Check each file individually. Only create missing files. Ask before overwriting any existing file.
+- **Partial setup exists**: Check each file individually. Only create missing files.
 - **CLAUDE.md has custom content**: Append the workflow section. Do not replace the entire file.
-- **User declines all optional components**: That's fine. Core memory files and CLAUDE.md are sufficient.
-- **Git-tracked project**: Memory files in `docs/project_notes/` are safe to commit. The `.project-memory-state.json` contains only metadata. Settings in `.claude/` are typically gitignored.
+- **Git-tracked project**: Memory files in `docs/project_notes/` are safe to commit. Settings in `.claude/` are typically gitignored.
 
 ## REFERENCE FILES
 
 These template files are in the `references/` directory. Use Read tool to access them:
 
-**Memory file templates** (used in Step 2):
-- `bugs_template.md`
-- `decisions_template.md`
-- `key_facts_template.md`
-- `issues_template.md`
+**Memory file templates** (Step 2):
+- `bugs_template.md`, `decisions_template.md`, `key_facts_template.md`, `issues_template.md`
 
-**State template** (used in Step 3):
-- `state_template.json` — v4.0 schema
+**State template** (Step 3):
+- `state_template.json`
 
-**Framework overview** (used in Step 4.5):
-- `intuition_readme_template.md` — high-level workflow overview for INTUITION.md
+**Framework overview** (Step 4.5):
+- `intuition_readme_template.md`
 
-**Configuration templates** (used in Steps 4-5):
+**Configuration templates** (Steps 4-5):
 - `claude_template.md` — workflow protocols for CLAUDE.md
 - `agents_template.md` — agent registry for AGENTS.md
 - `settings_template.json` — pre-authorized tools for Claude Code
 - `user_profile_template.json` — cross-project user context
-
-**Workflow output templates** (NOT used by initialize — used by handoff):
-- `discovery_output_template.json`
-- `planning_brief_template.md`
-- `design_brief_template.md`
-- `execution_brief_template.md` (engineering brief template — legacy filename)
-
-## MEMORY FILE FORMATS
-
-For reference, here's how memory files should be formatted. Templates already include these formats.
-
-### bugs.md
-```markdown
-### YYYY-MM-DD - Brief Bug Description
-- **Issue**: What went wrong
-- **Root Cause**: Why it happened
-- **Solution**: How it was fixed
-- **Prevention**: How to avoid it in the future
-```
-
-### decisions.md
-```markdown
-### ADR-NNN: Decision Title (YYYY-MM-DD)
-**Status**: Proposed | Accepted | Superseded
-**Context:** [Why this decision was needed]
-**Decision:** [What was chosen]
-**Consequences:** [Benefits and trade-offs]
-```
-
-### key_facts.md
-```markdown
-## [Category]
-- **[Fact]**: [value] (discovered [date])
-```
-
-### issues.md
-```markdown
-### YYYY-MM-DD - TICKET-ID: Brief Description
-- **Status**: Completed | In Progress | Blocked
-- **Description**: [1-2 line summary]
-- **URL**: [link to ticket]
-```
-
-## VOICE
-
-- Direct and procedural — "Creating files..." "Updated CLAUDE.md"
-- Status-focused — report what was done
-- No marketing copy — skip "empowering you" language
-- Offer optional components without being pushy

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."