@tgoodington/intuition 6.0.0 → 7.0.0

package/skills/intuition-handoff/SKILL.md

@@ -14,549 +14,377 @@ You are the handoff orchestrator. You process phase outputs, update project memo
 
 These are non-negotiable. Violating any of these means the protocol has failed.
 
-1. You MUST detect which transition is happening before doing anything else.
-2. You MUST read all phase output files before processing.
-3. You MUST update memory files with proper formatting (see formats below).
-4. You MUST generate a brief for the next agent.
-5. You MUST update `.project-memory-state.json` — you are the ONLY skill that writes to this file.
-6. You MUST NOT evaluate or critique phase outputs. Process and document, never judge.
-7. You MUST NOT skip the user profile merge step during prompt→planning transitions.
-8. You MUST suggest the correct next skill after completing the transition.
-9. You MUST NOT modify discovery_brief.md, plan.md, design_spec_*.md, or other phase output files — they are read-only inputs.
-10. You MUST manage the design loop: track which items are designed, route to next item or to execute when all are done.
+1. You MUST resolve the active context and context_path before every transition. NEVER hardcode `docs/project_notes/` for workflow artifacts.
+2. You MUST detect which transition is happening before doing anything else.
+3. You MUST read all phase output files before processing.
+4. You MUST update memory files with proper formatting (see formats below).
+5. You MUST generate a brief for the next agent.
+6. You MUST update `.project-memory-state.json` — you are the ONLY skill that writes to this file.
+7. You MUST NOT evaluate or critique phase outputs. Process and document, never judge.
+8. You MUST NOT skip the user profile merge step during prompt→planning transitions.
+9. You MUST suggest the correct next skill after completing the transition.
+10. You MUST NOT modify discovery_brief.md, plan.md, design_spec_*.md, or other phase output files — they are read-only inputs.
+11. You MUST manage the design loop: track which items are designed, route to next item or to execute when all are done.
+
+## CONTEXT PATH RESOLUTION
+
+Before ANY transition, resolve the active context:
+
+1. Read `docs/project_notes/.project-memory-state.json`
+2. Get `active_context` value
+3. IF active_context == "trunk": `context_path = "docs/project_notes/trunk/"`
+   ELSE: `context_path = "docs/project_notes/branches/{active_context}/"`
+4. Get context_workflow:
+   IF active_context == "trunk": `context_workflow = state.trunk`
+   ELSE: `context_workflow = state.branches[active_context]`
+5. Use `context_path` for all workflow artifact file operations
+6. Use `context_workflow` for all status checks and state writes
+7. Shared files (key_facts.md, decisions.md, issues.md, bugs.md) always stay at `docs/project_notes/` — do NOT use context_path for these.
 
 ## PROTOCOL: COMPLETE FLOW
 
-Execute these steps in order:
-
 ```
-Step 1: Read .project-memory-state.json and detect transition type
-Step 2: Read phase output files
-Step 3: Extract insights and structure findings
-Step 4: Update memory files (key_facts.md, decisions.md, issues.md)
-Step 5: Merge user profile learnings (prompt→planning only)
-Step 6: Generate brief for next agent
-Step 7: Update .project-memory-state.json
-Step 8: Report what was processed and suggest next skill
+Step 1: Resolve context_path and context_workflow (see above)
+Step 2: Detect transition type from context_workflow
+Step 3: Read phase output files from {context_path}
+Step 4: Extract insights and structure findings
+Step 5: Update shared memory files (key_facts.md, decisions.md, issues.md)
+Step 6: Merge user profile learnings (prompt→planning only)
+Step 7: Generate brief for next agent at {context_path}
+Step 8: Update .project-memory-state.json (target active context object)
+Step 9: Report what was processed and suggest next skill
 ```
 
 ## STEP 1: DETECT TRANSITION
 
-Read `docs/project_notes/.project-memory-state.json` and determine:
+After resolving context_path and context_workflow, determine:
 
 ```
-IF workflow.status == "prompt" AND prompt.completed == true
-   AND planning.started == false:
+IF context_workflow.status == "prompt" AND workflow.prompt.completed == true
+   AND workflow.planning.started == false:
    → TRANSITION: Prompt → Planning
 
-IF workflow.status == "planning" AND planning.completed == true
-   AND design.started == false:
+IF context_workflow.status == "planning" AND workflow.planning.completed == true
+   AND workflow.design.started == false:
    → TRANSITION: Planning → Design (initial setup)
 
-IF workflow.status == "design":
-   → Check design.items array
+IF context_workflow.status == "design":
+   → Check workflow.design.items array
    → IF current item just completed AND more items remain:
       → TRANSITION: Design → Design (next item)
    → IF all items completed:
       → TRANSITION: Design → Execution
 
-IF workflow.status == "executing" AND execution.completed == true:
+IF context_workflow.status == "executing" AND workflow.execution.completed == true:
    → TRANSITION: Execution → Complete
 
 IF no clear transition detected:
    → ASK USER: "Which phase just completed?" (use AskUserQuestion)
 ```
 
-## STATE SCHEMA
+## STATE SCHEMA (v4.0)
 
 This is the authoritative schema for `.project-memory-state.json`:
 
 ```json
 {
   "initialized": true,
-  "version": "3.0",
-  "workflow": {
+  "version": "4.0",
+  "active_context": "trunk",
+  "trunk": {
     "status": "none | prompt | planning | design | executing | complete",
-    "prompt": {
-      "started": false,
-      "completed": false,
-      "started_at": null,
-      "completed_at": null,
-      "output_files": []
-    },
-    "planning": {
-      "started": false,
-      "completed": false,
-      "completed_at": null,
-      "approved": false
-    },
-    "design": {
-      "started": false,
-      "completed": false,
-      "completed_at": null,
-      "items": [],
-      "current_item": null
-    },
-    "execution": {
-      "started": false,
-      "completed": false,
-      "completed_at": null
+    "workflow": {
+      "prompt": { "started": false, "completed": false, "started_at": null, "completed_at": null, "output_files": [] },
+      "planning": { "started": false, "completed": false, "completed_at": null, "approved": false },
+      "design": { "started": false, "completed": false, "completed_at": null, "items": [], "current_item": null },
+      "execution": { "started": false, "completed": false, "completed_at": null }
     }
   },
+  "branches": {},
   "last_handoff": null,
   "last_handoff_transition": null
 }
 ```
 
+### Branch Entry Schema
+
+Each branch in `branches` has: `display_name`, `created_from`, `created_at`, `purpose`, `status`, and a `workflow` object identical to trunk's workflow structure.
+
 ### Design Items Schema
 
-Each item in `design.items` has this structure:
+Each item in `design.items`: `{ "name": "snake_case", "display_name": "Human Name", "status": "pending|in_progress|completed|skipped", "plan_tasks": [N], "spec_file": null, "flagged_reason": "..." }`
+
+When updating state, preserve all existing fields and only modify the relevant ones. Always set `last_handoff` to the current ISO timestamp and `last_handoff_transition` to the transition name.
+
+### State Write Pattern
+
+All state writes MUST target the active context object:
 
-```json
-{
-  "name": "item_name_snake_case",
-  "display_name": "Human Readable Item Name",
-  "status": "pending | in_progress | completed | skipped",
-  "plan_tasks": [3, 4, 5],
-  "spec_file": null,
-  "flagged_reason": "Why plan flagged this for design"
-}
+```
+IF active_context == "trunk":
+  Update state.trunk.status and state.trunk.workflow.*
+ELSE:
+  Update state.branches[active_context].status and state.branches[active_context].workflow.*
 ```
 
-When updating state, preserve all existing fields and only modify the relevant ones. Always set `last_handoff` to the current ISO timestamp and `last_handoff_transition` to the transition name.
+## TRANSITION 0: BRANCH CREATION
+
+Triggered when start routes to handoff with branch creation intent. User has provided: branch name, purpose, parent context.
+
+### Protocol
+
+1. **Validate branch name**: Convert to kebab-case for the state key. Reject names containing `/`, `\`, `.`, or `..` — only alphanumeric characters and hyphens allowed. Reject if `state.branches[branch_key]` already exists — tell user to pick a different name.
+2. **Create branch directory**: `docs/project_notes/branches/{branch_key}/`
+3. **Add branch to state**:
+   - `display_name`: user-provided name
+   - `created_from`: parent context key ("trunk" or another branch key)
+   - `created_at`: ISO timestamp
+   - `purpose`: user-provided sentence
+   - `status`: "none"
+   - `workflow`: identical structure to trunk's workflow (all false/null/empty)
+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."
+
+## V3 STATE MIGRATION
+
+Fires automatically when handoff detects a v3.0 state before processing any transition.
+
+### Detection
+
+`version == "3.0"` OR missing `active_context` field in state.
+
+### Migration Steps
+
+1. Create `docs/project_notes/trunk/` directory.
+2. Move existing workflow artifacts from `docs/project_notes/` into `docs/project_notes/trunk/`:
+   - `discovery_brief.md`, `discovery_output.json`, `planning_brief.md`, `plan.md`
+   - `design_brief.md`, `design_spec_*.md`, `execution_brief.md`
+   - `.planning_research/` directory (entire folder)
+   - Only move files that exist. Skip missing files silently.
+3. Restructure state:
+   - Wrap existing `status` and `workflow` into a `trunk` object
+   - Add `active_context: "trunk"`
+   - Add `branches: {}`
+   - Set `version: "4.0"`
+   - Preserve all other top-level fields (`initialized`, `last_handoff`, `last_handoff_transition`)
+4. Write updated state.
+5. Report to user: list which files were migrated and confirm v4.0 upgrade. Then continue with the original transition.
+
+Leave shared files (`key_facts.md`, `decisions.md`, `issues.md`, `bugs.md`) at `docs/project_notes/` — do NOT move them.
 
 ## TRANSITION 1: PROMPT → PLANNING
 
 ### Read Outputs
 
-Read these files:
-- `docs/project_notes/discovery_brief.md` — human-readable discovery summary
-- `docs/project_notes/discovery_output.json` — structured data (if exists)
+Read from `{context_path}`:
+- `{context_path}discovery_brief.md` — human-readable discovery summary
+- `{context_path}discovery_output.json` — structured data (if exists)
 
 If `discovery_output.json` doesn't exist, extract insights manually from `discovery_brief.md`.
 
 ### Extract and Structure
 
 From the outputs, identify:
-- **Key facts** → add to `key_facts.md`
-- **Constraints** → add to `key_facts.md` under constraints category
-- **Suggested decisions** → create ADRs in `decisions.md`
+- **Key facts** → add to `docs/project_notes/key_facts.md`
+- **Constraints** → add to `docs/project_notes/key_facts.md` under constraints category
+- **Suggested decisions** → create ADRs in `docs/project_notes/decisions.md`
 - **Assumptions** → reference in brief, not directly added to memory
-- **Follow-up items** → add to `issues.md`
+- **Follow-up items** → add to `docs/project_notes/issues.md`
 
 ### User Profile Merge
 
-If `docs/project_notes/discovery_output.json` contains `user_profile_learnings` AND `.claude/USER_PROFILE.json` exists:
-
+If `{context_path}discovery_output.json` contains `user_profile_learnings` AND `.claude/USER_PROFILE.json` exists:
 1. Read existing USER_PROFILE.json
-2. Merge learnings:
-   - If a profile field is `null` and learnings have a value → add it
-   - If a profile field is populated → only overwrite if discovery_confidence is "high"
-   - Always update `metadata.last_updated`
+2. Merge learnings (null fields get new values; populated fields only overwrite if confidence is "high")
 3. Save updated profile
 
-If USER_PROFILE.json does NOT exist, skip this step. Do NOT create it from scratch.
+If USER_PROFILE.json does NOT exist, skip this step.
 
 ### Generate Planning Brief
 
-Write `docs/project_notes/planning_brief.md`:
-
-```markdown
-# Planning Brief: [Problem Title]
-
-## Discovery Summary
-[1-2 paragraph summary]
-
-## Problem Statement
-[Clear statement of what needs to be solved]
-
-## Goals & Success Criteria
-[What success looks like]
-
-## Key Constraints
-- [Constraint 1]
-- [Constraint 2]
-
-## Architectural Context
-[Existing decisions and patterns relevant to planning]
-
-## Assumptions & Risks
-- [Assumption]: Confidence High/Medium/Low
-- [Risk]: Should be explored during planning
-
-## References
-- Discovery Brief: docs/project_notes/discovery_brief.md
-- Relevant Decisions: [ADR numbers]
-```
+Write `{context_path}planning_brief.md` with these sections:
+- **Discovery Summary** (1-2 paragraphs)
+- **Problem Statement**
+- **Goals & Success Criteria**
+- **Key Constraints**
+- **Architectural Context** (existing decisions/patterns)
+- **Assumptions & Risks** (with confidence levels)
+- **References** (discovery_brief path, relevant ADR numbers)
 
 ### Update State
 
-```json
-{
-  "workflow": {
-    "status": "planning",
-    "prompt": { "completed": true, "completed_at": "[ISO timestamp]" },
-    "planning": { "started": true }
-  }
-}
-```
+Update the active context: set `status` to `"planning"`, mark `prompt.completed = true` with timestamp, set `planning.started = true`.
 
 ### Route User
 
-Tell the user: "Discovery processed. Planning brief saved to `docs/project_notes/planning_brief.md`. Run `/intuition-plan` to create a structured plan."
+"Discovery processed. Planning brief saved to `{context_path}planning_brief.md`. Run `/intuition-plan` to create a structured plan."
 
 ## TRANSITION 2: PLANNING → DESIGN (Initial Setup)
 
 ### Read Outputs
 
-Read: `docs/project_notes/plan.md`
+Read: `{context_path}plan.md`
 
 ### Extract Design Items
 
-From the plan, find the "Design Recommendations" section. Extract all items flagged for design, along with their rationale and associated task numbers.
-
-If no "Design Recommendations" section exists in the plan, check each task: if any task lacks sufficient detail for execution (ambiguous implementation path, multiple valid approaches, user-facing decisions needed), flag it yourself. Present your assessment to the user.
+From the plan, find "Design Recommendations" section. Extract all items flagged for design with rationale and task numbers. If no section exists, assess tasks yourself and present to user.
 
 ### Extract and Structure
 
-From the plan, also identify:
-- **New architectural decisions** → create ADRs in `decisions.md`
-- **Risks and dependencies** → include in design brief
-- **Planning work completed** → log in `issues.md`
+From the plan: new architectural decisions → `docs/project_notes/decisions.md`, risks/dependencies → include in brief, planning work → `docs/project_notes/issues.md`.
 
 ### Present Design Items to User
 
-Use AskUserQuestion to present the flagged items and get user confirmation:
-
-```
-Question: "Plan recommends design exploration for these items:
-
-[For each flagged item:]
-- **[Item Name]** (Tasks [N, M]): [Rationale from plan]
-
-Which items need design? You can also add items not listed."
-
-Header: "Design Items"
-Options:
-- "All recommended items need design"
-- "Some items — let me specify"
-- "None — skip design, go straight to execution"
-```
+Use AskUserQuestion:
+- Header: "Design Items"
+- Question: List each flagged item with rationale
+- Options: "All recommended items need design" / "Some items — let me specify" / "None — skip design, go straight to execution"
 
-If user selects "Some items," ask a follow-up to identify which ones.
-If user selects "None," skip to generating an execution brief instead (use Transition 4B below).
+If "Some items," follow up. If "None," use Transition 4B.
 
 ### Generate Design Brief
 
-Write `docs/project_notes/design_brief.md` for the FIRST item:
-
-```markdown
-# Design Brief: [First Item Name]
-
-## Current Item
-**[Item Name]** — [Brief description from plan]
-
-## Plan Context
-[1-2 paragraph summary of what the plan says about this item]
-
-## Task Details
-- **Plan Tasks**: [Task numbers]
-- **Description**: [From plan.md]
-- **Acceptance Criteria**: [From plan.md]
-- **Dependencies**: [From plan.md]
-
-## Design Rationale
-[Why plan flagged this for design — what needs elaboration before execution]
-
-## Constraints
-- [From plan's architectural decisions]
-- [From discovery constraints]
-
-## Design Queue
-[For each item, show status:]
-- **[Item 1 Name] (current)**
-- [Item 2 Name] (pending)
-- [Item 3 Name] (pending)
-
-## References
-- Plan: docs/project_notes/plan.md
-- Discovery: docs/project_notes/discovery_brief.md
-```
+Write `{context_path}design_brief.md` for the FIRST item with these sections:
+- **Current Item** (name + description)
+- **Plan Context** (1-2 paragraphs)
+- **Task Details** (task numbers, description, acceptance criteria, dependencies)
+- **Design Rationale** (why flagged)
+- **Constraints**
+- **Design Queue** (all items with status)
+- **References** (plan path, discovery path)
 
 ### Update State
 
-```json
-{
-  "workflow": {
-    "status": "design",
-    "planning": { "completed": true, "completed_at": "[ISO timestamp]", "approved": true },
-    "design": {
-      "started": true,
-      "items": [
-        {
-          "name": "[snake_case_name]",
-          "display_name": "[Human Name]",
-          "status": "pending",
-          "plan_tasks": [3, 4, 5],
-          "spec_file": null,
-          "flagged_reason": "[reason]"
-        }
-      ],
-      "current_item": "[first_item_snake_case_name]"
-    }
-  }
-}
-```
-
-Mark the first item's status as `"in_progress"`.
+Update active context: set `status` to `"design"`, mark `planning.completed = true` with timestamp and `approved = true`, set `design.started = true`, populate `design.items` array with all confirmed items, set `design.current_item` to first item, mark first item status `"in_progress"`.
 
 ### Route User
 
-Tell the 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 `/intuition-design` to begin design exploration."
 
 ## TRANSITION 3: DESIGN → DESIGN (Next Item)
 
 ### Read Outputs
 
 Read:
-- The design spec that was just saved: `docs/project_notes/design_spec_[completed_item].md`
+- `{context_path}design_spec_[completed_item].md`
 - Current `.project-memory-state.json`
 
 ### Extract and Structure
 
-From the completed design spec:
-- **New architectural decisions** → create ADRs in `decisions.md`
-- **Key technical facts** → add to `key_facts.md`
-- **Design work completed** → log in `issues.md`
+From completed spec: decisions → `docs/project_notes/decisions.md`, key facts → `docs/project_notes/key_facts.md`, design work → `docs/project_notes/issues.md`.
 
 ### Determine Next Item
 
-Read `design.items` from state. Find the next item with status `"pending"`. If no pending items remain, this is actually Transition 4 — proceed to Design → Execution.
+Find next item with status `"pending"` in `design.items`. If none remain, proceed to Transition 4.
 
 ### Update Design Brief
 
-Overwrite `docs/project_notes/design_brief.md` with the next item's context:
-
-```markdown
-# Design Brief: [Next Item Name]
-
-## Current Item
-**[Next Item Name]** — [Brief description from plan]
-
-## Plan Context
-[1-2 paragraph summary for this item]
-
-## Task Details
-[Same structure as Transition 2]
-
-## Design Rationale
-[Why this item needs design]
-
-## Prior Design Context
-[1-2 sentences about what was designed in previous items that may be relevant]
-
-## Constraints
-[Updated constraints including any decisions from prior design items]
-
-## Design Queue
-- [x] [Item 1 Name] (completed) → design_spec_[item1].md
-- **[Item 2 Name] (current)**
-- [ ] [Item 3 Name] (pending)
-
-## References
-- Plan: docs/project_notes/plan.md
-- Prior design specs: [list completed spec files]
-```
+Overwrite `{context_path}design_brief.md` for the next item with these sections:
+- **Current Item** (name + description)
+- **Plan Context**
+- **Task Details**
+- **Design Rationale**
+- **Prior Design Context** (relevant prior design decisions)
+- **Constraints** (updated with prior design decisions)
+- **Design Queue** (show completed, current, pending items)
+- **References** (plan path, completed spec paths)
 
 ### Update State
 
-```json
-{
-  "design": {
-    "items": [
-      { "name": "item_1", "status": "completed", "spec_file": "design_spec_item_1.md" },
-      { "name": "item_2", "status": "in_progress", "spec_file": null },
-      { "name": "item_3", "status": "pending", "spec_file": null }
-    ],
-    "current_item": "item_2"
-  }
-}
-```
+Update active context's `design.items`: mark completed item as `"completed"` with `spec_file`, mark next item as `"in_progress"`, set `design.current_item` to next item.
 
 ### Route User
 
-Tell the 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 `/intuition-design` to continue."
 
 ## TRANSITION 4: DESIGN → EXECUTION
 
-Triggers when ALL design items have status `"completed"` (or `"skipped"`).
+Triggers when ALL design items have status `"completed"` or `"skipped"`.
 
 ### Read Outputs
 
-Read all design specs: `docs/project_notes/design_spec_*.md`
-Read: `docs/project_notes/plan.md`
+Read all design specs: `{context_path}design_spec_*.md`
+Read: `{context_path}plan.md`
 
 ### Extract and Structure
 
-From the design specs:
-- **All architectural decisions** → ensure they're in `decisions.md`
-- **Key facts discovered during design** → add to `key_facts.md`
-- **All design work** → log in `issues.md`
+From design specs: decisions → `docs/project_notes/decisions.md`, key facts → `docs/project_notes/key_facts.md`, design work → `docs/project_notes/issues.md`.
 
 ### Generate Execution Brief
 
-Write `docs/project_notes/execution_brief.md`:
-
-```markdown
-# Execution Brief: [Plan Title]
-
-## Plan Summary
-[1-2 paragraph overview]
-
-## Objective
-[What will be accomplished]
-
-## Discovery Context
-[Brief reminder of why this matters]
-
-## Design Specifications
-[List all design specs produced, with one-line summary of each:]
-- design_spec_[item1].md — [summary]
-- design_spec_[item2].md — [summary]
-
-**IMPORTANT:** Execute agents MUST read these specs before implementing flagged tasks. Implement exactly what's specified. If ambiguity is found, escalate to user — do not make design decisions autonomously.
-
-## Task Summary
-[List tasks in execution order with brief descriptions]
-[Mark which tasks have associated design specs]
-
-## Quality Gates
-- Security review: MANDATORY
-- Tests must pass
-- Code review required
-
-## Known Risks
-- [Risk]: Mitigation [strategy]
-
-## References
-- Full Plan: docs/project_notes/plan.md
-- Discovery Brief: docs/project_notes/discovery_brief.md
-- Design Specs: docs/project_notes/design_spec_*.md
-```
+Write `{context_path}execution_brief.md` with these sections:
+- **Plan Summary** (1-2 paragraphs)
+- **Objective**
+- **Discovery Context** (brief reminder)
+- **Design Specifications** (list each spec with one-line summary; include: "Execute agents MUST read these specs before implementing flagged tasks.")
+- **Task Summary** (execution order, mark tasks with design specs)
+- **Quality Gates** (security review, tests, code review)
+- **Known Risks** (with mitigations)
+- **References** (plan path, discovery path, design spec paths)
 
 ### Update State
 
-```json
-{
-  "workflow": {
-    "status": "executing",
-    "design": { "completed": true, "completed_at": "[ISO timestamp]" },
-    "execution": { "started": true }
-  }
-}
-```
+Update active context: set `status` to `"executing"`, mark `design.completed = true` with timestamp, set `execution.started = true`.
 
 ### Route User
 
-Tell the user: "All design specs processed. Execution brief saved to `docs/project_notes/execution_brief.md`. Run `/intuition-execute` to begin implementation."
+"All design specs processed. Execution brief saved to `{context_path}execution_brief.md`. Run `/intuition-execute` to begin implementation."
 
 ## TRANSITION 4B: PLANNING → EXECUTION (Skip Design)
 
-Used when the user confirms NO items need design at the Planning → Design transition.
+Used when user confirms NO items need design.
 
 ### Generate Execution Brief
 
-Same format as Transition 4 but without the "Design Specifications" section.
+Same format as Transition 4 but without the "Design Specifications" section. Write to `{context_path}execution_brief.md`.
 
 ### Update State
 
-```json
-{
-  "workflow": {
-    "status": "executing",
-    "planning": { "completed": true, "completed_at": "[ISO timestamp]", "approved": true },
-    "design": { "started": false, "completed": false, "items": [] },
-    "execution": { "started": true }
-  }
-}
-```
+Update active context: set `status` to `"executing"`, mark `planning.completed = true` with timestamp and `approved = true`, set `design.started = false`, `design.completed = false`, `design.items = []`, set `execution.started = true`.
 
 ### Route User
 
-Tell the user: "Plan processed. No design items flagged. Execution brief saved to `docs/project_notes/execution_brief.md`. Run `/intuition-execute` to begin implementation."
+"Plan processed. No design items flagged. Execution brief saved to `{context_path}execution_brief.md`. Run `/intuition-execute` to begin implementation."
 
 ## TRANSITION 5: EXECUTION → COMPLETE
 
 ### Read Outputs
 
-Read execution results from any files the execution phase produced. Check `docs/project_notes/` for execution reports.
+Read execution results from `{context_path}` for any reports the execution phase produced.
 
 ### Extract and Structure
 
-- **Bugs found** → add to `bugs.md`
-- **Lessons learned** → add to `key_facts.md`
-- **Work completed** → update `issues.md`
+Bugs found → `docs/project_notes/bugs.md`, lessons learned → `docs/project_notes/key_facts.md`, work completed → `docs/project_notes/issues.md`.
 
 ### Update State
 
-```json
-{
-  "workflow": {
-    "status": "complete",
-    "execution": { "completed": true, "completed_at": "[ISO timestamp]" }
-  }
-}
-```
+Update active context: set `status` to `"complete"`, mark `execution.completed = true` with timestamp.
 
 ### Route User
 
-Tell the user: "Workflow cycle complete. Run `/intuition-prompt` to start a new cycle, or `/intuition-start` to review project status."
+"Workflow cycle complete for [context display name]. Run `/intuition-start` to see your project status and decide what's next."
 
 ## MEMORY FILE FORMATS
 
-### key_facts.md
-
-```markdown
-## [Category]
-
-- **[Fact]**: [value] (discovered [date])
-- **[Fact]**: [value] (discovered [date])
-```
+All shared memory files live at `docs/project_notes/` (never context_path).
 
-Add new categories as needed. Add facts under existing categories. Do not remove old facts unless explicitly outdated.
+**key_facts.md**: Categories with bulleted facts: `- **[Fact]**: [value] (discovered [date])`. Add categories as needed; never remove existing facts unless outdated.
 
-### decisions.md
+**decisions.md**: ADR format: `### ADR-NNN: [Title] ([date])` with Status, Context, Decision, Consequences, Discovered During fields.
 
-```markdown
-### ADR-NNN: [Title] ([date])
-
-**Status**: Proposed | Accepted | Superseded
-**Context:** [Why this decision was needed]
-**Decision:** [What was chosen]
-**Consequences:** [Benefits and trade-offs]
-**Discovered During**: [Phase name]
-```
-
-### issues.md
-
-```markdown
-### [Date] - [ID]: [Title]
-
-- **Status**: Completed | In Progress | Blocked
-- **Description**: [1-2 line summary]
-- **Source**: [Phase and file reference]
-```
+**issues.md**: `### [Date] - [ID]: [Title]` with Status, Description, Source fields.
 
 ## EDGE CASES
 
-- **Missing discovery_output.json**: Extract insights manually from discovery_brief.md. Less structured but handoff still works.
-- **Poor output quality**: Process as-is. Note concerns in the brief: "Output quality was limited — next agent may need more exploration." Do NOT try to fix or improve outputs.
-- **Planning revealed new constraints**: Update key_facts.md, create ADR if architectural, note in design/execution brief.
-- **Interrupted handoff**: Check what's been updated in memory files. Continue from where you left off. Don't duplicate entries.
-- **Corrupted state**: If .project-memory-state.json is malformed, infer phase from which output files exist (discovery_brief.md → prompt complete, plan.md → planning complete, design_spec_*.md → design in progress). Ask user to confirm.
-- **Design item skipped mid-loop**: If user asks to skip a design item during the loop, mark it as `"skipped"` in state. Do not block the loop — proceed to next item. Note the skip in the execution brief.
-- **No Design Recommendations in plan**: If plan.md has no flagged items, present the plan tasks to the user and ask if any need design. If none, proceed with Transition 4B.
-- **Plan revision after design started**: If plan.md has been modified after design began, alert the user. Ask whether to continue with current design items or re-evaluate.
+- **Missing discovery_output.json**: Extract insights from discovery_brief.md manually.
+- **Poor output quality**: Process as-is. Note concerns in brief. Do NOT fix outputs.
+- **New constraints from planning**: Update key_facts.md, create ADR if architectural.
+- **Interrupted handoff**: Check what's updated, continue from there, don't duplicate.
+- **Corrupted state**: Infer phase from existing files. Ask user to confirm.
+- **Design item skipped mid-loop**: Mark as `"skipped"`, proceed to next. Note in execution brief.
+- **No Design Recommendations in plan**: Present tasks to user, ask if any need design. If none, use 4B.
+- **Plan revision after design started**: Alert user. Ask whether to continue or re-evaluate.
 
 ## VOICE