@tgoodington/intuition 8.0.0 → 8.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "8.0.0",
-  "description": "Trunk-and-branch workflow system for Claude Code: prompt, plan, design, execute with iterative branching. Holistic coding expert, domain-agnostic design exploration with ECD framework, and file-based handoffs through project memory.",
+  "version": "8.1.0",
+  "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",
     "skills",

package/skills/intuition-build/SKILL.md

@@ -243,33 +243,44 @@ If Security Expert review has not been run, you MUST run it now. ZERO exceptions
 
 ## STEP 7: REPORT RESULTS
 
-Present the build report:
+Write the build report to `{context_path}/build_report.md` AND display a summary to the user.
+
+### Write `{context_path}/build_report.md`
 
 ```markdown
-## Build Complete
+# Build Report
 
 **Plan:** [Title]
+**Date:** [YYYY-MM-DD]
 **Status:** Success / Partial / Failed
 
-**Tasks Completed:**
+## Tasks Completed
 - [x] Task 1 — [brief outcome]
 - [x] Task 2 — [brief outcome]
 
-**Verification Results:**
+## Verification Results
 - Security Review: PASS / FAIL
 - Code Review: PASS / N/A
 - Tests: X passed, Y failed / N/A
 
-**Files Modified:**
+## Files Modified
 - path/to/file — [what changed]
 
-**Issues & Resolutions:**
+## Issues & Resolutions
 - [Any problems encountered and how they were resolved]
 
-**Required User Steps:**
+## Required User Steps
 - [From code_specs.md — remind user of manual steps needed]
+
+## Deviations from Specs
+- [Any places where implementation diverged from code_specs.md, with rationale]
+- [Or "None — all specs followed as written"]
 ```
 
+### Display summary to user
+
+Present a concise version: task count, pass/fail status, files modified count, any required user steps. Reference the full report at `{context_path}/build_report.md`.
+
 ## STEP 8: ROUTE TO HANDOFF
 
 After reporting results:

package/skills/intuition-debugger/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: intuition-debugger
-description: Expert debugger and diagnostic specialist. Investigates hard problems in completed workflow contexts — complex bugs, cross-context failures, performance issues, and cases where the plan or design was wrong. Not for simple fixes caught during execution.
+description: Expert debugger and diagnostic specialist. Investigates hard problems in completed workflow contexts — complex bugs, cross-context failures, performance issues, and cases where the plan or design was wrong. Not for simple fixes caught during build.
 model: opus
 tools: Read, Write, Glob, Grep, Task, AskUserQuestion, Bash, mcp__ide__getDiagnostics
 allowed-tools: Read, Write, Glob, Grep, Task, Bash, mcp__ide__getDiagnostics
@@ -21,14 +21,14 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 9. You MUST NOT modify plan.md, design specs, discovery_brief.md, or any workflow planning artifacts.
 10. You MUST classify the bug category (see DIAGNOSTIC SPECIALIZATIONS) — this determines your investigation protocol.
 
-REMINDER: You are a diagnostic specialist, not a general fixer. Execute's Senior Engineer handles routine implementation issues. You handle the hard problems that survive good engineering.
+REMINDER: You are a diagnostic specialist, not a general fixer. Build's Code Reviewer and retry logic handle routine implementation issues. You handle the hard problems that survive good engineering.
 
 # WHEN TO USE THIS SKILL VS OTHERS
 
 | Situation | Use |
 |-----------|-----|
-| Simple bug found during execution | Execute's retry/escalation logic |
-| Implementation doesn't match plan | Execute's Code Reviewer catches this |
+| Simple bug found during build | Build's retry/escalation logic |
+| Implementation doesn't match specs | Build's Code Reviewer catches this |
 | Complex bug in completed work | **This skill** |
 | Bug symptom is far from root cause | **This skill** |
 | Cross-context or cross-branch failure | **This skill** |
@@ -112,14 +112,15 @@ Resolve `context_path` from selected context:
 Read ALL of these before proceeding — do NOT wait for the user's issue description:
 
 - `{context_path}/plan.md` — what was planned
-- `{context_path}/implementation_guide.md` — engineering decisions made during execution
-- `{context_path}/execution_brief.md` — what was executed
+- `{context_path}/code_specs.md` — engineering decisions (what approach was chosen for each task and why)
+- `{context_path}/build_brief.md` — context passed to the build phase
+- `{context_path}/build_report.md` — what was actually built (task outcomes, files modified, deviations)
 - `{context_path}/design_spec_*.md` — design decisions (if any exist)
 - `docs/project_notes/key_facts.md` — project-wide knowledge
 - `docs/project_notes/decisions.md` — architectural decisions
 - `docs/project_notes/bugs.md` — previously logged bugs
 
-The implementation guide is especially valuable — it tells you WHAT engineering decisions were made and WHY. Bugs often hide in the gap between intended approach and actual implementation.
+The code specs are especially valuable — they tell you WHAT engineering decisions were made and WHY. The build report tells you what was actually built and any deviations. Bugs often hide in the gap between intended approach and actual implementation.
 
 Do NOT read source code files yet. Read targeted code only after the user describes the issue.
 
@@ -310,10 +311,10 @@ After the subagent returns:
 - **Root Cause**: [The actual problem — with causal chain]
 - **Solution**: [What was changed]
 - **Files Modified**: [list]
-- **Prevention**: [How to avoid in future — what should execution have caught?]
+- **Prevention**: [How to avoid in future — what should the build phase have caught?]
 ```
 
-Do NOT skip the log entry. The Prevention field is critical — it feeds back into improving the execution process.
+Do NOT skip the log entry. The Prevention field is critical — it feeds back into improving the build process.
 
 **Report:**
 
@@ -334,7 +335,7 @@ Do NOT skip the log entry. The Prevention field is critical — it feeds back in
 **Logged to:** docs/project_notes/bugs.md
 
 **Prevention recommendation:**
-- [What should change in future execution to prevent this class of bug]
+- [What should change in future builds to prevent this class of bug]
 ```
 
 ### Git Commit Offer

package/skills/intuition-design/SKILL.md

@@ -18,14 +18,14 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 6. You MUST present 2-4 sentences of analysis BEFORE every question. Show your reasoning.
 7. You MUST get explicit user approval before saving the spec.
 8. You MUST save the spec to `{context_path}/design_spec_[item_name].md`.
-9. You MUST route to `/intuition-handoff` after saving. NEVER to `/intuition-execute`.
+9. You MUST route to `/intuition-handoff` after saving. NEVER to `/intuition-engineer` or `/intuition-build`.
 10. You MUST be domain-agnostic. Adapt your language, questions, and output format to match what is being designed — code, creative work, business documents, UI, or anything else.
 11. You MUST NOT write code or implementation artifacts — you produce design specifications only.
 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.
 
-REMINDER: One question per turn. Route to `/intuition-handoff`, never to `/intuition-execute`.
+REMINDER: One question per turn. Route to `/intuition-handoff`, never to `/intuition-engineer` or `/intuition-build`.
 
 # BRANCH CONTEXT (Branch Only)
 
@@ -92,7 +92,7 @@ Phase 5:   FORMALIZATION      (1 turn)      Draft spec, validate, approve, save
 
 Before starting the protocol, check for existing state:
 
-1. If `docs/project_notes/.design_research/` exists with prior artifacts for this item:
+1. If `{context_path}/.design_research/` exists with prior artifacts for this item:
    - Read `decisions.md` inside to reconstruct ECD coverage
    - Ask via AskUserQuestion: "I found a draft design for [item]. Continue from where we left off, or start fresh?"
 2. If a `design_spec_[item].md` already exists:
@@ -106,9 +106,9 @@ Execute all of the following before your first user-facing message.
 ## Step 1: Read inputs
 
 Read these files:
-- `docs/project_notes/design_brief.md` — REQUIRED. Contains the current item, plan context, and design rationale. If missing, stop: "No design brief found. Run `/intuition-handoff` first."
-- `docs/project_notes/plan.md` — for full task context and acceptance criteria.
-- `docs/project_notes/discovery_brief.md` — for original problem context.
+- `{context_path}/design_brief.md` — REQUIRED. Contains the current item, plan context, and design rationale. If missing, stop: "No design brief found. Run `/intuition-handoff` first."
+- `{context_path}/plan.md` — for full task context and acceptance criteria.
+- `{context_path}/discovery_brief.md` — for original problem context.
 
 From the design brief, extract:
 - Current item name and description
@@ -118,7 +118,7 @@ From the design brief, extract:
 
 ## Step 2: Launch context research (2 haiku agents in parallel)
 
-Create the directory `docs/project_notes/.design_research/[item_name]/` if it does not exist.
+Create the directory `{context_path}/.design_research/[item_name]/` if it does not exist.
 
 **Agent 1 — Existing Work Scan** (subagent_type: Explore, model: haiku):
 Prompt: "Search the project for existing work related to [item description]. Look for: prior documentation, existing implementations, reference material, patterns that inform this design. Check docs/, src/, and any relevant directories. Report findings in under 400 words. Facts only."
@@ -126,7 +126,7 @@ Prompt: "Search the project for existing work related to [item description]. Loo
 **Agent 2 — Context Mapping** (subagent_type: Explore, model: haiku):
 Prompt: "Map the context surrounding [item description]. What already exists that this design must work with or within? What are the boundaries and integration points? Check the codebase structure, existing docs, and configuration. Report in under 400 words. Facts only."
 
-When both return, combine results and write to `docs/project_notes/.design_research/[item_name]/context.md`.
+When both return, combine results and write to `{context_path}/.design_research/[item_name]/context.md`.
 
 ## Step 3: Frame the design challenge
 
@@ -204,13 +204,13 @@ If changes requested, address them (1-2 more turns), then re-present.
 
 ## Step 4: Save and route
 
-Write the spec to `docs/project_notes/design_spec_[item_name].md` using the output format below.
+Write the spec to `{context_path}/design_spec_[item_name].md` using the output format below.
 
-Log design decisions to `docs/project_notes/.design_research/[item_name]/decisions.md`.
+Log design decisions to `{context_path}/.design_research/[item_name]/decisions.md`.
 
 Tell the user:
 ```
-Design spec saved to docs/project_notes/design_spec_[item_name].md.
+Design spec saved to {context_path}/design_spec_[item_name].md.
 Run /intuition-handoff to continue.
 ```
 
@@ -218,7 +218,7 @@ ALWAYS route to `/intuition-handoff`. NEVER suggest `/intuition-execute`.
 
 # OUTPUT FORMAT: DESIGN SPECIFICATION
 
-Saved to `docs/project_notes/design_spec_[item_name].md`. The content adapts to the domain being designed.
+Saved to `{context_path}/design_spec_[item_name].md`. The content adapts to the domain being designed.
 
 ```markdown
 # Design Specification: [Item Name]
@@ -330,15 +330,15 @@ Validate ALL before presenting the draft:
 
 ### Working Files (ephemeral, per-item)
 ```
-docs/project_notes/.design_research/[item_name]/
+{context_path}/.design_research/[item_name]/
   context.md          # Context research from Phase 1
   options_[topic].md  # Research for specific design questions
   decisions.md        # Running log of design decisions made
 ```
 
 ### Final Artifacts (permanent)
-- `docs/project_notes/design_spec_[item_name].md` — the deliverable
-- Updates to `docs/project_notes/decisions.md` if new ADRs emerge during design
+- `{context_path}/design_spec_[item_name].md` — the deliverable
+- Updates to `docs/project_notes/decisions.md` if new ADRs emerge during design (shared memory stays at root)
 
 ### Resume Capability
 Working files in `.design_research/` enable resuming interrupted design sessions. The `decisions.md` log reconstructs ECD coverage state.

package/skills/intuition-engineer/SKILL.md

@@ -96,33 +96,81 @@ Options:
 
 ## STEP 2: FAN-OUT RESEARCH
 
-For each task (or group of related tasks), launch a haiku research subagent via the Task tool:
+For each task (or group of related tasks), launch a haiku research subagent via the Task tool (subagent_type: Explore, model: haiku).
+
+When constructing each prompt, replace bracketed placeholders with actual values from the plan. If the task has known file paths, use the "Known Files" variant. If files are marked TBD, use the "TBD Files" variant.
+
+### Known Files variant:
 
 ```
-You are a codebase researcher gathering information for engineering specs.
+You are a codebase researcher. The project root is the current working directory.
+
+TASK: Gather implementation details for plan Task #[N]: [title]
+DESCRIPTION: [from plan]
+COMPONENT: [from plan]
 
-TASK: Research the codebase relevant to plan Task #[N]: [title]
+EXECUTE THESE STEPS IN ORDER:
 
-CONTEXT:
-- Task description: [from plan]
-- Known files: [from plan's Files field]
-- Component: [from plan's Component field]
+Step 1 — Read target files:
+- Read [exact path 1]
+- Read [exact path 2]
+- [list all known files]
 
-RESEARCH PROTOCOL:
-1. Read the files listed in the task (or Glob/Grep to find them if marked TBD).
-2. Identify existing patterns: naming conventions, error handling, module structure.
-3. Find 2-3 examples of similar patterns already in the codebase.
-4. Check for shared utilities or abstractions that should be reused.
-5. Read 1 level of dependents — what imports or calls the files you'll modify?
-6. Note any conventions that must be followed.
+Step 2 — Find dependents:
+- Grep for the filename (without extension) in all source files to find imports/references.
+- Read the top 2-3 files that import or call the target files.
+
+Step 3 — Find similar patterns:
+- In the target files, identify the primary function or class name.
+- Grep for similar patterns in other files within the same directory or parent directory.
 
 REPORT FORMAT (under 500 words):
-- **Relevant Files**: [paths with brief descriptions]
-- **Existing Patterns**: [patterns found with file references]
-- **Shared Utilities**: [reusable code found]
+- **Relevant Files**: [paths with 1-line descriptions]
+- **Existing Patterns**: [patterns found, with file:line references]
+- **Shared Utilities**: [reusable code found, or "None found"]
 - **Dependents**: [files that import/use the target files]
-- **Conventions**: [naming, structure, error handling patterns]
-- **Notes**: [anything unexpected or important]
+- **Conventions**: [naming, structure, error handling patterns observed]
+- **Notes**: [anything unexpected]
+
+Report only what you find. Do not speculate.
+```
+
+### TBD Files variant:
+
+```
+You are a codebase researcher. The project root is the current working directory.
+
+TASK: Gather implementation details for plan Task #[N]: [title]
+DESCRIPTION: [from plan]
+COMPONENT: [from plan]
+
+EXECUTE THESE STEPS IN ORDER:
+
+Step 1 — Locate files:
+- Run Glob('[component directory]/**/*') to list files in the component area.
+- If no component directory is obvious, Grep for keywords from the task title across all source files.
+- Read the 3-5 most relevant files found.
+
+Step 2 — Find dependents:
+- For each relevant file found, Grep for its name in other source files to find imports/references.
+
+Step 3 — Find similar patterns:
+- Grep for function or class names related to the task domain.
+- Read 1-2 examples of similar functionality elsewhere in the codebase.
+
+Step 4 — Check for shared utilities:
+- Run Glob('**/util*') and Glob('**/helper*') and Glob('**/shared*').
+- Read any utility file relevant to this task's domain.
+
+REPORT FORMAT (under 500 words):
+- **Relevant Files**: [paths with 1-line descriptions]
+- **Existing Patterns**: [patterns found, with file:line references]
+- **Shared Utilities**: [reusable code found, or "None found"]
+- **Dependents**: [files that import/use the target files]
+- **Conventions**: [naming, structure, error handling patterns observed]
+- **Notes**: [anything unexpected]
+
+Report only what you find. Do not speculate.
 ```
 
 **Parallelization rules:**

package/skills/intuition-handoff/SKILL.md

@@ -149,7 +149,7 @@ Triggered when start routes to handoff with branch creation intent. User has pro
    - `workflow`: identical structure to trunk's workflow (all false/null/empty — including `engineering` and `build` phases)
 4. **Set `active_context`** to the new branch key.
 5. **Write updated state**. Set `last_handoff_transition` to "branch_creation".
-6. **Route user**: "Branch **[display_name]** created. Run `/intuition-prompt` to define what this branch will accomplish."
+6. **Route user**: "Branch **[display_name]** created. Run `/clear` then `/intuition-prompt` to define what this branch will accomplish."
 
 ## V4 STATE MIGRATION
 
@@ -243,7 +243,7 @@ Update the active context: set `status` to `"planning"`, mark `prompt.completed
 
 ### Route User
 
-"Discovery processed. Planning brief saved to `{context_path}planning_brief.md`. Run `/intuition-plan` to create a structured plan."
+"Discovery processed. Planning brief saved to `{context_path}planning_brief.md`. Run `/clear` then `/intuition-plan` to create a structured plan."
 
 ## TRANSITION 2: PLANNING → DESIGN (Initial Setup)
 
@@ -285,7 +285,7 @@ Update active context: set `status` to `"design"`, mark `planning.completed = tr
 
 ### Route User
 
-"Plan processed. Design brief prepared for **[First Item Name]**. Run `/intuition-design` to begin design exploration."
+"Plan processed. Design brief prepared for **[First Item Name]**. Run `/clear` then `/intuition-design` to begin design exploration."
 
 ## TRANSITION 2B: PLANNING → ENGINEER (Skip Design)
 
@@ -307,7 +307,7 @@ Update active context: set `status` to `"engineering"`, mark `planning.completed
 
 ### Route User
 
-"Plan processed. No design items flagged. Engineering brief saved to `{context_path}engineering_brief.md`. Run `/intuition-engineer` to create code specs."
+"Plan processed. No design items flagged. Engineering brief saved to `{context_path}engineering_brief.md`. Run `/clear` then `/intuition-engineer` to create code specs."
 
 ## TRANSITION 3: DESIGN → DESIGN (Next Item)
 
@@ -343,7 +343,7 @@ Update active context's `design.items`: mark completed item as `"completed"` wit
 
 ### Route User
 
-"[Previous Item] design complete. Design brief updated for **[Next Item Name]** ([N] of [total], [remaining] remaining). Run `/intuition-design` to continue."
+"[Previous Item] design complete. Design brief updated for **[Next Item Name]** ([N] of [total], [remaining] remaining). Run `/clear` then `/intuition-design` to continue."
 
 ## TRANSITION 4: DESIGN → ENGINEER
 
@@ -375,7 +375,7 @@ Update active context: set `status` to `"engineering"`, mark `design.completed =
 
 ### Route User
 
-"All design specs processed. Engineering brief saved to `{context_path}engineering_brief.md`. Run `/intuition-engineer` to create code specs."
+"All design specs processed. Engineering brief saved to `{context_path}engineering_brief.md`. Run `/clear` then `/intuition-engineer` to create code specs."
 
 ## TRANSITION 5: ENGINEER → BUILD
 
@@ -405,17 +405,20 @@ Update active context: set `status` to `"building"`, mark `engineering.completed
 
 ### Route User
 
-"Code specs processed. Build brief saved to `{context_path}build_brief.md`. Run `/intuition-build` to begin implementation."
+"Code specs processed. Build brief saved to `{context_path}build_brief.md`. Run `/clear` then `/intuition-build` to begin implementation."
 
 ## TRANSITION 6: BUILD → COMPLETE
 
 ### Read Outputs
 
-Read build results from `{context_path}` for any reports the build phase produced.
+Read `{context_path}/build_report.md` — REQUIRED. Contains task outcomes, files modified, verification results, and any deviations from specs. If missing, warn the user that build may not have completed properly, then proceed with what's available.
 
 ### Extract and Structure
 
-Bugs found → `docs/project_notes/bugs.md`, lessons learned → `docs/project_notes/key_facts.md`, work completed → `docs/project_notes/issues.md`.
+From the build report:
+- Bugs found or issues encountered → `docs/project_notes/bugs.md`
+- Lessons learned or deviations → `docs/project_notes/key_facts.md`
+- Work completed → `docs/project_notes/issues.md`
 
 ### Git Commit Offer
 
@@ -433,7 +436,7 @@ Options:
 
 If user approves commit:
 1. Run `git status` to see changed files
-2. Run `git add [specific files from build report]` — only add files that were part of the build
+2. Run `git add` for files listed in the build report's "Files Modified" section. Cross-reference with `git status` to catch any files the report missed.
 3. Run `git commit` with a descriptive message summarizing the build
 4. If user chose push: run `git push`
 
@@ -445,7 +448,7 @@ Update active context: set `status` to `"complete"`, mark `build.completed = tru
 
 ### Route User
 
-"Workflow cycle complete for [context display name]. Run `/intuition-start` to see your project status and decide what's next."
+"Workflow cycle complete for [context display name]. Run `/clear` then `/intuition-start` to see your project status and decide what's next."
 
 ## MEMORY FILE FORMATS
 

package/skills/intuition-initialize/SKILL.md

@@ -16,7 +16,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 
 1. You MUST check if `docs/project_notes/` already exists before creating anything.
 2. You MUST use template files from `references/` directory for all initial content. Read each template with the Read tool, then Write to the target path.
-3. You MUST create `.project-memory-state.json` using the v4.0 schema from `references/state_template.json`. Do NOT use older schemas (v1.0, v2.0, v3.0).
+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.
@@ -30,7 +30,7 @@ Execute these steps in order:
 ```
 Step 1: Detect existing setup
 Step 2: Create memory directory and files from templates
-Step 3: Create .project-memory-state.json with v4.0 schema
+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)
@@ -83,18 +83,18 @@ 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, execution_brief.md, etc.). Those are created by their respective skills during the workflow.
+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.
 
 ## STEP 3: CREATE STATE FILE
 
 Read `references/state_template.json` and write to `docs/project_notes/.project-memory-state.json`.
 
-The state file uses the v4.0 schema:
+The state file uses the v5.0 schema:
 
 ```json
 {
   "initialized": true,
-  "version": "4.0",
+  "version": "5.0",
   "active_context": "trunk",
   "trunk": {
     "status": "none",
@@ -119,7 +119,12 @@ The state file uses the v4.0 schema:
         "items": [],
         "current_item": null
       },
-      "execution": {
+      "engineering": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      },
+      "build": {
         "started": false,
         "completed": false,
         "completed_at": null
@@ -134,7 +139,7 @@ The state file uses the v4.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, or v3.0). Those schemas are obsolete.
+Do NOT use older schemas (v1.0, v2.0, v3.0, or v4.0). Those schemas are obsolete.
 
 ## STEP 4: UPDATE CLAUDE.MD
 
@@ -151,10 +156,10 @@ IF CLAUDE.md does NOT exist:
 ```
 
 The template includes:
-- Four-phase workflow description (prompt → plan → design → execute with handoffs)
+- 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, etc.)
+- Smart skill suggestions (when to suggest /intuition-prompt, /intuition-plan, /intuition-design, /intuition-engineer, /intuition-build, etc.)
 
 ## STEP 4.5: CREATE INTUITION.MD
 
@@ -234,7 +239,7 @@ Created:
 - docs/project_notes/decisions.md
 - docs/project_notes/key_facts.md
 - docs/project_notes/issues.md
-- docs/project_notes/.project-memory-state.json (v4.0 schema)
+- docs/project_notes/.project-memory-state.json (v5.0 schema)
 - CLAUDE.md workflow protocols
 - INTUITION.md framework overview
 
@@ -277,7 +282,7 @@ These template files are in the `references/` directory. Use Read tool to access
 - `discovery_output_template.json`
 - `planning_brief_template.md`
 - `design_brief_template.md`
-- `execution_brief_template.md`
+- `execution_brief_template.md` (engineering brief template — legacy filename)
 
 ## MEMORY FILE FORMATS
 

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

@@ -1,10 +1,10 @@
-# Execution Brief Template
+# Engineering Brief Template
 
 > **Path note:** `{context_path}` resolves to `docs/project_notes/trunk/` for the trunk context, or `docs/project_notes/branches/{name}/` for a branch context. Shared files (`key_facts.md`, `decisions.md`, `issues.md`, `bugs.md`) always remain at `docs/project_notes/`.
 
-> **Generated by:** `/intuition-handoff` (Design→Execution or Planning→Execution transition)
-> **Consumed by:** `/intuition-execute`
-> **Frozen for:** execution phase (don't modify during execution)
+> **Generated by:** `/intuition-handoff` (Design→Engineer or Planning→Engineer transition)
+> **Consumed by:** `/intuition-engineer`
+> **Frozen for:** engineering phase (don't modify during engineering)
 
 ---
 

package/skills/intuition-initialize/references/state_template.json

@@ -1,6 +1,6 @@
 {
   "initialized": true,
-  "version": "4.0",
+  "version": "5.0",
   "active_context": "trunk",
   "trunk": {
     "status": "none",
@@ -25,7 +25,12 @@
         "items": [],
         "current_item": null
       },
-      "execution": {
+      "engineering": {
+        "started": false,
+        "completed": false,
+        "completed_at": null
+      },
+      "build": {
         "started": false,
         "completed": false,
         "completed_at": null

package/skills/intuition-plan/SKILL.md

@@ -17,7 +17,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 5. You MUST ask exactly ONE question per turn via AskUserQuestion. For decisional questions, present 2-3 options with trade-offs. For informational questions (gathering facts, confirming understanding), present relevant options but trade-off analysis is not required.
 6. You MUST get explicit user approval before saving the plan.
 7. You MUST save the final plan to `{context_path}/plan.md`.
-8. You MUST route to `/intuition-handoff` after saving. NEVER to `/intuition-execute`.
+8. You MUST route to `/intuition-handoff` after saving. NEVER to `/intuition-engineer` or `/intuition-build`.
 9. You MUST write interim artifacts to `{context_path}/.planning_research/` for context management.
 10. You MUST validate against the Executable Plan Checklist before presenting the draft plan.
 11. You MUST present 2-4 sentences of analysis BEFORE every question. Show your reasoning.
@@ -27,7 +27,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 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.
 
-REMINDER: One question per turn. Route to `/intuition-handoff`, never to `/intuition-execute`.
+REMINDER: One question per turn. Route to `/intuition-handoff`, never to `/intuition-engineer` or `/intuition-build`.
 
 # ARCH COVERAGE FRAMEWORK
 
@@ -73,10 +73,10 @@ Phase 5:   FORMALIZATION    (1 turn)     Save plan.md, route to handoff
 
 Before starting the protocol, check for existing state:
 
-1. If `docs/project_notes/plan.md` already exists:
+1. If `{context_path}/plan.md` already exists:
    - If it appears complete and approved: ask via AskUserQuestion — "A plan already exists. Would you like to revise it or start fresh?"
    - If it appears incomplete or is a draft: ask — "I found a draft plan. Would you like to continue from where we left off?"
-2. If `docs/project_notes/.planning_research/` exists with interim artifacts, read them to reconstruct dialogue state. Use `decisions_log.md` to determine which ARCH dimensions have been covered.
+2. If `{context_path}/.planning_research/` exists with interim artifacts, read them to reconstruct dialogue state. Use `decisions_log.md` to determine which ARCH dimensions have been covered.
 3. If no prior state exists, proceed with Phase 1.
 
 # PHASE 1: INTAKE
@@ -86,25 +86,59 @@ This phase is exactly 1 turn. Execute all of the following before your first use
 ## Step 1: Read inputs
 
 Read these files:
-- `docs/project_notes/discovery_brief.md` — REQUIRED. If missing, stop immediately: "No discovery brief found. Run `/intuition-prompt` first."
-- `docs/project_notes/planning_brief.md` — optional, may contain handoff context.
+- `{context_path}/discovery_brief.md` — REQUIRED. If missing, stop immediately: "No discovery brief found. Run `/intuition-prompt` first."
+- `{context_path}/planning_brief.md` — optional, may contain handoff context.
 - `.claude/USER_PROFILE.json` — optional, for tailoring communication style.
 
 From the discovery brief, extract: core problem, success criteria, stakeholders, constraints, scope, assumptions, and research insights.
 
 ## Step 2: Launch orientation research
 
-Create the directory `docs/project_notes/.planning_research/` if it does not exist.
+Create the directory `{context_path}/.planning_research/` if it does not exist.
 
-Launch 2 haiku research agents in parallel using the Task tool:
+Launch 2 sonnet research agents in parallel using the Task tool:
 
-**Agent 1 — Codebase Topology** (subagent_type: Explore, model: haiku):
-Prompt: "Analyze this project's codebase structure. Report on: (1) top-level directory structure, (2) key modules and responsibilities, (3) entry points, (4) test infrastructure, (5) build system. Use Glob, Grep, Read to explore. Under 500 words. Facts only."
+**Agent 1 — Codebase Topology** (subagent_type: Explore, model: sonnet):
+Prompt:
+"The project root is the current working directory. Analyze the codebase structure by following these steps in order:
 
-**Agent 2 — Pattern Extraction** (subagent_type: Explore, model: haiku):
-Prompt: "Analyze this project's codebase for patterns. Report on: (1) architectural patterns in use, (2) coding conventions, (3) existing abstractions, (4) dependency patterns between modules. Use Glob, Grep, Read to explore. Under 500 words. Facts only."
+1. Run Glob('*') to list all top-level files and directories.
+2. Read package.json (or equivalent manifest) for project metadata, scripts, and dependencies.
+3. Read any README.md or CLAUDE.md at the project root.
+4. For each top-level source directory, run Glob('{dir}/*') to map one level of contents.
+5. Grep for common entry points: 'main', 'index', 'app', 'server' in source files.
+6. Check for test infrastructure: Glob('**/*.test.*') or Glob('**/*.spec.*') or Glob('**/test/**').
+7. Check for build config: Glob('**/tsconfig*') or Glob('**/webpack*') or Glob('**/vite*') or similar.
 
-When both return, combine results and write to `docs/project_notes/.planning_research/orientation.md`.
+Report on:
+(1) Top-level directory structure with purpose of each directory
+(2) Key modules and their responsibilities
+(3) Entry points
+(4) Test infrastructure (framework, location, patterns)
+(5) Build system and tooling
+
+Under 500 words. Facts only, no speculation."
+
+**Agent 2 — Pattern Extraction** (subagent_type: Explore, model: sonnet):
+Prompt:
+"The project root is the current working directory. Analyze codebase patterns by following these steps:
+
+1. Read 3-5 representative source files from different directories to identify coding style.
+2. Grep for 'export' or 'module.exports' to understand module boundaries.
+3. Grep for 'import' or 'require' to map dependency patterns between modules.
+4. Grep for error handling patterns: 'catch', 'throw', 'Error', 'try'.
+5. Grep for common abstractions: 'class', 'interface', 'type', 'abstract', 'base'.
+6. Check for configuration patterns: Glob('**/*.config.*') or Glob('**/.{eslint,prettier}*').
+
+Report on:
+(1) Architectural patterns in use (MVC, event-driven, plugin system, etc.)
+(2) Coding conventions (naming, file organization, export style)
+(3) Existing abstractions and base classes/utilities
+(4) Dependency patterns between modules (which modules depend on which)
+
+Under 500 words. Facts only, no speculation."
+
+When both return, combine results and write to `{context_path}/.planning_research/orientation.md`.
 
 ## BRANCH-AWARE INTAKE (Branch Only)
 
@@ -117,8 +151,23 @@ When `active_context` is NOT trunk:
 3. Read parent's plan.md and any design specs at `{parent_path}/design_spec_*.md`.
 4. Launch a THIRD orientation research agent alongside the existing two:
 
-**Agent 3 — Parent Intersection Analysis** (subagent_type: Explore, model: haiku):
-Prompt: "Compare the discovery brief at {context_path}/discovery_brief.md with the plan at {parent_path}/plan.md. Identify: (1) Shared files/components that both touch, (2) Decisions in the parent plan that constrain this branch, (3) Potential conflicts or dependencies, (4) Patterns from parent that should be reused. Under 500 words. Facts only."
+**Agent 3 — Parent Intersection Analysis** (subagent_type: Explore, model: sonnet):
+Prompt:
+"The project root is the current working directory. Compare two workflow artifacts:
+
+1. Read the discovery brief at {context_path}/discovery_brief.md.
+2. Read the parent plan at {parent_path}/plan.md.
+3. For each file path mentioned in the parent plan's tasks, check if the discovery brief references the same files or components.
+4. Extract all technology decisions from the parent plan (Section 3 if it exists).
+5. Identify acceptance criteria in the parent plan that touch the same areas as the discovery brief.
+
+Report on:
+(1) Shared files/components that both parent plan and this branch's discovery brief touch
+(2) Decisions in the parent plan that constrain this branch
+(3) Potential conflicts or dependencies between parent and branch work
+(4) Patterns from parent implementation that this branch should reuse
+
+Under 500 words. Facts only, no speculation."
 
 Write results to `{context_path}/.planning_research/parent_intersection.md`.
 
@@ -170,11 +219,11 @@ For each major decision domain identified from the discovery brief, orientation
    - Use haiku (subagent_type: Explore) for straightforward fact-gathering.
    - Use sonnet (subagent_type: general-purpose) for trade-off analysis against the existing codebase.
    - Each agent prompt MUST reference the specific decision domain, return under 400 words.
-   - Write results to `docs/project_notes/.planning_research/decision_[domain].md` (snake_case).
+   - 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.
 4. **Ask** the user to select via AskUserQuestion.
-5. **Record** the resolved decision to `docs/project_notes/.planning_research/decisions_log.md`:
+5. **Record** the resolved decision to `{context_path}/.planning_research/decisions_log.md`:
 
 ```markdown
 ## [Decision Domain]
@@ -218,7 +267,7 @@ If the user wants to discuss more, return to Phase 3.
 
 ## Step 2: Draft the plan
 
-Read `docs/project_notes/.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.
+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
 
@@ -236,8 +285,8 @@ If changes requested, make them and present again. Repeat until explicitly appro
 
 After explicit approval:
 
-1. Write the final plan to `docs/project_notes/plan.md`.
-2. Tell the user: "Plan saved to `docs/project_notes/plan.md`. Next step: Run `/intuition-handoff` to transition into execution."
+1. Write the final plan to `{context_path}/plan.md`.
+2. Tell the user: "Plan saved to `{context_path}/plan.md`. Next step: Run `/intuition-handoff` to transition to the next phase."
 3. ALWAYS route to `/intuition-handoff`. NEVER suggest `/intuition-execute`.
 
 # PLAN.MD OUTPUT FORMAT (Plan-Execute Contract v1.0)
@@ -403,7 +452,7 @@ If any check fails, fix it before presenting.
 
 ## Tier 1: Orientation (launched in Phase 1)
 
-Launch 2 haiku Explore agents in parallel via Task tool. See Phase 1, Step 2 for prompt templates. Write combined results to `docs/project_notes/.planning_research/orientation.md`.
+Launch 2 sonnet Explore agents in parallel via Task tool. See Phase 1, Step 2 for prompt templates. Write combined results to `{context_path}/.planning_research/orientation.md`.
 
 ## Tier 2: Decision Research (launched on demand in Phase 3)
 
@@ -413,7 +462,7 @@ Launch 1-2 agents per decision domain when dialogue reveals unknowns needing inv
 - Use sonnet general-purpose agents for trade-off analysis (e.g., "Compare approaches X and Y given the current architecture").
 - Each prompt MUST specify the decision domain and a 400-word limit.
 - Reference specific files or directories when possible.
-- Write results to `docs/project_notes/.planning_research/decision_[domain].md`.
+- Write results to `{context_path}/.planning_research/decision_[domain].md`.
 - NEVER launch more than 2 simultaneously.
 
 # CONTEXT MANAGEMENT