@tgoodington/intuition 6.0.0 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. package/docs/v7_design_spec.md +1111 -0
  2. package/docs/v7_plan.md +339 -0
  3. package/package.json +2 -2
  4. package/scripts/install-skills.js +2 -0
  5. package/scripts/uninstall-skills.js +1 -0
  6. package/skills/intuition-design/SKILL.md +25 -13
  7. package/skills/intuition-engineer/SKILL.md +278 -0
  8. package/skills/intuition-execute/SKILL.md +91 -50
  9. package/skills/intuition-handoff/SKILL.md +201 -373
  10. package/skills/intuition-initialize/SKILL.md +42 -34
  11. package/skills/intuition-initialize/references/claude_template.md +18 -1
  12. package/skills/intuition-initialize/references/design_brief_template.md +4 -2
  13. package/skills/intuition-initialize/references/execution_brief_template.md +5 -3
  14. package/skills/intuition-initialize/references/intuition_readme_template.md +22 -2
  15. package/skills/intuition-initialize/references/planning_brief_template.md +4 -2
  16. package/skills/intuition-initialize/references/state_template.json +30 -28
  17. package/skills/intuition-plan/SKILL.md +52 -14
  18. package/skills/intuition-prompt/SKILL.md +34 -3
  19. package/skills/intuition-start/SKILL.md +155 -72
package/skills/intuition-initialize/SKILL.md CHANGED
@@ -16,7 +16,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
16
16
 
17
17
  1. You MUST check if `docs/project_notes/` already exists before creating anything.
18
18
  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.
19
- 3. You MUST create `.project-memory-state.json` using the v2.0 WORKFLOW schema from `references/state_template.json`. Do NOT use the old v1.0 personalization schema.
19
+ 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).
20
20
  4. You MUST update CLAUDE.md with workflow and memory protocols.
21
21
  5. You MUST NOT overwrite existing memory files without asking the user first.
22
22
  6. You MUST NOT invoke other skills (discovery, plan, execute). You only set up infrastructure.
@@ -30,7 +30,7 @@ Execute these steps in order:
30
30
  ```
31
31
  Step 1: Detect existing setup
32
32
  Step 2: Create memory directory and files from templates
33
- Step 3: Create .project-memory-state.json with v2.0 workflow schema
33
+ Step 3: Create .project-memory-state.json with v4.0 schema
34
34
  Step 4: Update CLAUDE.md with workflow protocols
35
35
  Step 4.5: Create INTUITION.md framework overview
36
36
  Step 5: Offer optional components (AGENTS.md, settings, user profile)
@@ -63,6 +63,8 @@ Create the directory structure and initialize memory files:
63
63
  ```
64
64
  docs/
65
65
  └── project_notes/
66
+ ├── trunk/
67
+ ├── branches/
66
68
  ├── bugs.md
67
69
  ├── decisions.md
68
70
  ├── key_facts.md
@@ -70,6 +72,8 @@ docs/
70
72
  └── .project-memory-state.json
71
73
  ```
72
74
 
75
+ Create `docs/project_notes/trunk/` and `docs/project_notes/branches/` as empty directories. Write a `.gitkeep` placeholder to each so they are tracked by git.
76
+
73
77
  For each file, use the Read tool to read the template, then use Write to create the target:
74
78
 
75
79
  | Template Source | Target File |
@@ -85,42 +89,44 @@ Do NOT create workflow output files (discovery_brief.md, plan.md, execution_brie
85
89
 
86
90
  Read `references/state_template.json` and write to `docs/project_notes/.project-memory-state.json`.
87
91
 
88
- The state file uses the v3.0 WORKFLOW schema:
92
+ The state file uses the v4.0 schema:
89
93
 
90
94
  ```json
91
95
  {
92
96
  "initialized": true,
93
- "version": "3.0",
94
- "workflow": {
97
+ "version": "4.0",
98
+ "active_context": "trunk",
99
+ "trunk": {
95
100
  "status": "none",
96
- "prompt": {
97
- "started": false,
98
- "completed": false,
99
- "started_at": null,
100
- "completed_at": null,
101
- "output_files": []
102
- },
103
- "planning": {
104
- "started": false,
105
- "completed": false,
106
- "started_at": null,
107
- "completed_at": null,
108
- "approved": false
109
- },
110
- "design": {
111
- "started": false,
112
- "completed": false,
113
- "completed_at": null,
114
- "items": [],
115
- "current_item": null
116
- },
117
- "execution": {
118
- "started": false,
119
- "completed": false,
120
- "started_at": null,
121
- "completed_at": null
101
+ "workflow": {
102
+ "prompt": {
103
+ "started": false,
104
+ "completed": false,
105
+ "started_at": null,
106
+ "completed_at": null,
107
+ "output_files": []
108
+ },
109
+ "planning": {
110
+ "started": false,
111
+ "completed": false,
112
+ "completed_at": null,
113
+ "approved": false
114
+ },
115
+ "design": {
116
+ "started": false,
117
+ "completed": false,
118
+ "completed_at": null,
119
+ "items": [],
120
+ "current_item": null
121
+ },
122
+ "execution": {
123
+ "started": false,
124
+ "completed": false,
125
+ "completed_at": null
126
+ }
122
127
  }
123
128
  },
129
+ "branches": {},
124
130
  "last_handoff": null,
125
131
  "last_handoff_transition": null
126
132
  }
@@ -128,7 +134,7 @@ The state file uses the v3.0 WORKFLOW schema:
128
134
 
129
135
  **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.
130
136
 
131
- Do NOT use older schemas (v1.0 with `personalization` fields, or v2.0 with `discovery` instead of `prompt`). Those schemas are obsolete.
137
+ Do NOT use older schemas (v1.0, v2.0, or v3.0). Those schemas are obsolete.
132
138
 
133
139
  ## STEP 4: UPDATE CLAUDE.MD
134
140
 
@@ -222,11 +228,13 @@ Present a concise summary of what was created:
222
228
  Project memory initialized!
223
229
 
224
230
  Created:
231
+ - docs/project_notes/trunk/ (trunk workflow artifacts)
232
+ - docs/project_notes/branches/ (branch workflow artifacts)
225
233
  - docs/project_notes/bugs.md
226
234
  - docs/project_notes/decisions.md
227
235
  - docs/project_notes/key_facts.md
228
236
  - docs/project_notes/issues.md
229
- - docs/project_notes/.project-memory-state.json (v3.0 workflow schema)
237
+ - docs/project_notes/.project-memory-state.json (v4.0 schema)
230
238
  - CLAUDE.md workflow protocols
231
239
  - INTUITION.md framework overview
232
240
 
@@ -254,7 +262,7 @@ These template files are in the `references/` directory. Use Read tool to access
254
262
  - `issues_template.md`
255
263
 
256
264
  **State template** (used in Step 3):
257
- - `state_template.json` — v2.0 workflow schema
265
+ - `state_template.json` — v4.0 schema
258
266
 
259
267
  **Framework overview** (used in Step 4.5):
260
268
  - `intuition_readme_template.md` — high-level workflow overview for INTUITION.md
package/skills/intuition-initialize/references/claude_template.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  This project uses a four-phase workflow coordinated by the Intuition system, with institutional knowledge maintained in `docs/project_notes/` for consistency across sessions.
4
4
 
5
+ ### Workflow Model
6
+
7
+ The Intuition workflow uses a trunk-and-branch model:
8
+ - **Trunk**: The first prompt→plan→design→execute cycle. Represents the core vision.
9
+ - **Branches**: Subsequent cycles that build on, extend, or diverge from trunk or other branches.
10
+ - **Engineer**: Post-execution troubleshooting with holistic codebase awareness.
11
+
12
+ All phases: `/intuition-prompt` → `/intuition-handoff` → `/intuition-plan` → `/intuition-handoff` →
13
+ `[/intuition-design loop]` → `/intuition-handoff` → `/intuition-execute` → `/intuition-handoff` → complete
14
+
15
+ After completion: `/intuition-start` to create branches or `/intuition-engineer` to troubleshoot.
16
+
5
17
  ### Workflow Phases
6
18
 
7
19
  The project follows a structured workflow with handoff transitions between phases:
@@ -40,7 +52,9 @@ The project follows a structured workflow with handoff transitions between phase
40
52
  - Loads project context, detects workflow phase, suggests next step
41
53
  - Run at the start of any session to get oriented
42
54
 
43
- **Recommended Flow**: Prompt → Handoff → Plan → Handoff → [Design Loop] → Handoff → Execute → Handoff
55
+ **Recommended Flow**: Prompt → Handoff → Plan → Handoff → [Design Loop] → Handoff → Execute → Handoff → complete
56
+
57
+ After completion, run `/intuition-start` to create a branch or invoke `/intuition-engineer` to troubleshoot.
44
58
 
45
59
  ### Memory Files
46
60
 
@@ -103,3 +117,6 @@ The project follows a structured workflow with handoff transitions between phase
103
117
 
104
118
  **When user is ready to execute:**
105
119
  - "Execution brief is ready! Use `/intuition-execute` to kick off coordinated implementation."
120
+
121
+ **When execution is complete:**
122
+ - "Workflow cycle complete! Use `/intuition-start` to create a branch for new work, or `/intuition-engineer` to troubleshoot any issues."
package/skills/intuition-initialize/references/design_brief_template.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # Design Brief Template
2
2
 
3
+ > **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/`.
4
+
3
5
  > **Generated by:** `/intuition-handoff` (Planning→Design transition, updated per design item)
4
6
  > **Consumed by:** `/intuition-design`
5
7
  > **Overwritten for:** each design item in the loop
@@ -57,6 +59,6 @@
57
59
 
58
60
  ## References
59
61
 
60
- - Plan: docs/project_notes/plan.md
61
- - Discovery: docs/project_notes/discovery_brief.md
62
+ - Plan: `{context_path}/plan.md`
63
+ - Discovery: `{context_path}/discovery_brief.md`
62
64
  - Prior design specs: [list completed spec files, if any]
package/skills/intuition-initialize/references/execution_brief_template.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # Execution Brief Template
2
2
 
3
+ > **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/`.
4
+
3
5
  > **Generated by:** `/intuition-handoff` (Design→Execution or Planning→Execution transition)
4
6
  > **Consumed by:** `/intuition-execute`
5
7
  > **Frozen for:** execution phase (don't modify during execution)
@@ -145,9 +147,9 @@
145
147
 
146
148
  ## References
147
149
 
148
- - Plan file: `docs/project_notes/plan.md`
149
- - Planning brief: `docs/project_notes/planning_brief.md`
150
- - Design specs: `docs/project_notes/design_spec_*.md`
150
+ - Plan file: `{context_path}/plan.md`
151
+ - Planning brief: `{context_path}/planning_brief.md`
152
+ - Design specs: `{context_path}/design_spec_*.md`
151
153
  - State file: `docs/project_notes/.project-memory-state.json`
152
154
  - Related docs: [Links to relevant documentation]
153
155
 
package/skills/intuition-initialize/references/intuition_readme_template.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Intuition
2
2
 
3
- A four-phase workflow system for Claude Code. Turns rough ideas into structured plans, detailed designs, and executed implementations through guided dialogue.
3
+ A trunk-and-branch workflow system for Claude Code. Turns rough ideas into structured plans, detailed designs, and executed implementations through guided dialogue. Supports iterative development through independent branch cycles and post-execution troubleshooting.
4
4
 
5
5
  ## Workflow
6
6
 
@@ -10,24 +10,33 @@ A four-phase workflow system for Claude Code. Turns rough ideas into structured
10
10
  [design loop, if needed]
11
11
  ↓
12
12
  /intuition-execute ← /intuition-handoff
13
+ ↓
14
+ /intuition-handoff → complete
15
+ ↓
16
+ /intuition-start → create branch or /intuition-engineer
13
17
  ```
14
18
 
15
19
  Run `/intuition-handoff` between every phase. It manages state, generates briefs, and routes you forward.
16
20
 
21
+ The first prompt→execute cycle is the **trunk**. After trunk completes, create **branches** for new features or changes. Use `/intuition-engineer` to troubleshoot issues in any completed context.
22
+
17
23
  ## Skills
18
24
 
19
25
  | Skill | What it does |
20
26
  |-------|-------------|
21
- | `/intuition-start` | Detects where you left off and tells you what to run next |
27
+ | `/intuition-start` | Detects where you left off, shows project status, routes to next step or branch creation |
22
28
  | `/intuition-prompt` | Sharpens a rough idea into a planning-ready brief through focused Q&A |
23
29
  | `/intuition-plan` | Builds a strategic blueprint with tasks, decisions, and design flags |
24
30
  | `/intuition-design` | Elaborates flagged items through collaborative design exploration (ECD framework) |
25
31
  | `/intuition-execute` | Delegates implementation to specialized subagents and verifies quality |
32
+ | `/intuition-engineer` | Holistic post-execution troubleshooter — diagnoses and fixes issues with full codebase awareness |
26
33
  | `/intuition-handoff` | Processes phase outputs, updates memory, prepares the next phase |
27
34
  | `/intuition-initialize` | Sets up project memory (you already ran this) |
28
35
 
29
36
  ## Quick Start
30
37
 
38
+ ### First cycle (trunk)
39
+
31
40
  1. `/intuition-start` — see where you are
32
41
  2. `/intuition-prompt` — describe what you want to build
33
42
  3. `/intuition-handoff` — process and move to planning
@@ -36,5 +45,16 @@ Run `/intuition-handoff` between every phase. It manages state, generates briefs
36
45
  6. `/intuition-design` — elaborate each flagged item (repeat with handoff between)
37
46
  7. `/intuition-handoff` — prepare for execution
38
47
  8. `/intuition-execute` — build it
48
+ 9. `/intuition-handoff` — complete the cycle
39
49
 
40
50
  Not every project needs design. If the plan is clear enough, handoff skips straight to execute.
51
+
52
+ ### After trunk completes (branches)
53
+
54
+ 10. `/intuition-start` — see project status and choose next step
55
+ - **Create a branch** — start a new feature or change cycle, informed by trunk
56
+ - **Open the engineer** — diagnose and fix issues in any completed context
57
+
58
+ ### Troubleshooting
59
+
60
+ Run `/intuition-engineer` at any time after a context is complete. It loads your workflow artifacts, investigates issues holistically, and delegates fixes to subagents.
package/skills/intuition-initialize/references/planning_brief_template.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # Planning Brief Template
2
2
 
3
+ > **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/`.
4
+
3
5
  > **Generated by:** `/intuition-handoff` (Prompt→Planning transition)
4
6
  > **Consumed by:** `/intuition-plan`
5
7
  > **Frozen for:** planning phase (don't modify during plan approval or execution)
@@ -88,8 +90,8 @@
88
90
 
89
91
  ## References
90
92
 
91
- - Discovery output: `docs/project_notes/discovery_output.json`
92
- - Discovery brief: `docs/project_notes/discovery_brief.md`
93
+ - Discovery output: `{context_path}/discovery_output.json`
94
+ - Discovery brief: `{context_path}/discovery_brief.md`
93
95
  - Related docs: [Links to relevant documentation]
94
96
 
95
97
  ---
package/skills/intuition-initialize/references/state_template.json CHANGED
@@ -1,36 +1,38 @@
1
1
  {
2
2
  "initialized": true,
3
- "version": "3.0",
4
- "workflow": {
3
+ "version": "4.0",
4
+ "active_context": "trunk",
5
+ "trunk": {
5
6
  "status": "none",
6
- "prompt": {
7
- "started": false,
8
- "started_at": null,
9
- "completed": false,
10
- "completed_at": null,
11
- "output_files": []
12
- },
13
- "planning": {
14
- "started": false,
15
- "started_at": null,
16
- "completed": false,
17
- "completed_at": null,
18
- "approved": false
19
- },
20
- "design": {
21
- "started": false,
22
- "completed": false,
23
- "completed_at": null,
24
- "items": [],
25
- "current_item": null
26
- },
27
- "execution": {
28
- "started": false,
29
- "started_at": null,
30
- "completed": false,
31
- "completed_at": null
7
+ "workflow": {
8
+ "prompt": {
9
+ "started": false,
10
+ "completed": false,
11
+ "started_at": null,
12
+ "completed_at": null,
13
+ "output_files": []
14
+ },
15
+ "planning": {
16
+ "started": false,
17
+ "completed": false,
18
+ "completed_at": null,
19
+ "approved": false
20
+ },
21
+ "design": {
22
+ "started": false,
23
+ "completed": false,
24
+ "completed_at": null,
25
+ "items": [],
26
+ "current_item": null
27
+ },
28
+ "execution": {
29
+ "started": false,
30
+ "completed": false,
31
+ "completed_at": null
32
+ }
32
33
  }
33
34
  },
35
+ "branches": {},
34
36
  "last_handoff": null,
35
37
  "last_handoff_transition": null
36
38
  }
package/skills/intuition-plan/SKILL.md CHANGED
@@ -10,20 +10,22 @@ allowed-tools: Read, Write, Glob, Grep, Task, Bash, WebFetch
10
10
 
11
11
  These are non-negotiable. Violating any of these means the protocol has failed.
12
12
 
13
- 1. You MUST read `docs/project_notes/discovery_brief.md` before planning. If missing, stop and tell the user to run `/intuition-prompt`.
14
- 2. You MUST launch orientation research agents during Intake, after reading the discovery brief but BEFORE your first AskUserQuestion.
15
- 3. You MUST use ARCH coverage tracking. Homestretch only unlocks when Actors, Reach, and Choices are sufficiently explored.
16
- 4. 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.
17
- 5. You MUST get explicit user approval before saving the plan.
18
- 6. You MUST save the final plan to `docs/project_notes/plan.md`.
19
- 7. You MUST route to `/intuition-handoff` after saving. NEVER to `/intuition-execute`.
20
- 8. You MUST write interim artifacts to `docs/project_notes/.planning_research/` for context management.
21
- 9. You MUST validate against the Executable Plan Checklist before presenting the draft plan.
22
- 10. You MUST present 2-4 sentences of analysis BEFORE every question. Show your reasoning.
23
- 11. You MUST NOT modify `discovery_brief.md` or `planning_brief.md`.
24
- 12. You MUST NOT manage `.project-memory-state.json` — handoff owns state transitions.
25
- 13. You MUST treat user input as suggestions unless explicitly stated as requirements. Evaluate critically and propose alternatives when warranted.
26
- 14. 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).
13
+ 1. You MUST read `.project-memory-state.json` on startup to determine `active_context` and resolve `context_path`. Use context_path for ALL file reads and writes.
14
+ 2. You MUST read `{context_path}/discovery_brief.md` before planning. If missing, stop and tell the user to run `/intuition-prompt`.
15
+ 3. You MUST launch orientation research agents during Intake, after reading the discovery brief but BEFORE your first AskUserQuestion.
16
+ 4. You MUST use ARCH coverage tracking. Homestretch only unlocks when Actors, Reach, and Choices are sufficiently explored.
17
+ 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.
18
+ 6. You MUST get explicit user approval before saving the plan.
19
+ 7. You MUST save the final plan to `{context_path}/plan.md`.
20
+ 8. You MUST route to `/intuition-handoff` after saving. NEVER to `/intuition-execute`.
21
+ 9. You MUST write interim artifacts to `{context_path}/.planning_research/` for context management.
22
+ 10. You MUST validate against the Executable Plan Checklist before presenting the draft plan.
23
+ 11. You MUST present 2-4 sentences of analysis BEFORE every question. Show your reasoning.
24
+ 12. You MUST NOT modify `discovery_brief.md` or `planning_brief.md`.
25
+ 13. You MUST NOT manage `.project-memory-state.json` — handoff owns state transitions.
26
+ 14. You MUST treat user input as suggestions unless explicitly stated as requirements. Evaluate critically and propose alternatives when warranted.
27
+ 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).
28
+ 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.
27
29
 
28
30
  REMINDER: One question per turn. Route to `/intuition-handoff`, never to `/intuition-execute`.
29
31
 
@@ -43,6 +45,8 @@ Sufficiency thresholds scale with the selected depth tier:
43
45
  - **Standard**: Actors mapped with tensions identified, Reach fully scoped, all major Choices resolved with research.
44
46
  - **Comprehensive**: Actors deeply analyzed, Reach mapped with integration points, all Choices resolved with multiple options evaluated and documented.
45
47
 
48
+ When on a branch, the Reach dimension explicitly includes intersection with parent. The Choices dimension must acknowledge inherited decisions from the parent plan.
49
+
46
50
  # VOICE
47
51
 
48
52
  You are a strategic architect presenting options to a client, not a contractor taking orders.
@@ -102,6 +106,22 @@ Prompt: "Analyze this project's codebase for patterns. Report on: (1) architectu
102
106
 
103
107
  When both return, combine results and write to `docs/project_notes/.planning_research/orientation.md`.
104
108
 
109
+ ## BRANCH-AWARE INTAKE (Branch Only)
110
+
111
+ When `active_context` is NOT trunk:
112
+
113
+ 1. Determine parent: `state.branches[active_context].created_from`
114
+ 2. Resolve parent path:
115
+ - If parent is "trunk": `docs/project_notes/trunk/`
116
+ - If parent is a branch: `docs/project_notes/branches/{parent}/`
117
+ 3. Read parent's plan.md and any design specs at `{parent_path}/design_spec_*.md`.
118
+ 4. Launch a THIRD orientation research agent alongside the existing two:
119
+
120
+ **Agent 3 — Parent Intersection Analysis** (subagent_type: Explore, model: haiku):
121
+ 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."
122
+
123
+ Write results to `{context_path}/.planning_research/parent_intersection.md`.
124
+
105
125
  ## Step 3: Greet and begin
106
126
 
107
127
  In a single message:
@@ -229,6 +249,7 @@ After explicit approval:
229
249
  - **Comprehensive**: All sections (1-10, including 6.5)
230
250
 
231
251
  Section 6.5 is Design Recommendations — ALWAYS included regardless of tier.
252
+ Section 2.5 is Parent Context — included for ALL tiers when on a branch.
232
253
 
233
254
  ## Section Specifications
234
255
 
@@ -238,6 +259,23 @@ Section 6.5 is Design Recommendations — ALWAYS included regardless of tier.
238
259
  ### 2. Discovery Summary (always)
239
260
  Bullets: problem statement, goals, target users, constraints, key findings from discovery.
240
261
 
262
+ ### 2.5. Parent Context (branch plans only, all tiers)
263
+
264
+ **Parent:** [trunk or branch name]
265
+ **Parent Objective:** [1 sentence from parent plan]
266
+
267
+ **Shared Components:**
268
+ - [Component]: [how this branch's work relates to parent's use]
269
+
270
+ **Inherited Decisions:**
271
+ - [Decision from parent that constrains this branch]
272
+
273
+ **Intersection Points:**
274
+ - [File/module touched by both parent and this branch]
275
+
276
+ **Divergence:**
277
+ - [Where this branch intentionally departs from parent patterns]
278
+
241
279
  ### 3. Technology Decisions (Standard+, when decisions exist)
242
280
 
243
281
  | Decision | Choice | Status | Rationale |
package/skills/intuition-prompt/SKILL.md CHANGED
@@ -22,6 +22,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
22
22
  6. You MUST route to `/intuition-handoff` at the end. NEVER to `/intuition-plan` directly.
23
23
  7. You MUST NOT ask about the user's motivations, feelings, philosophical drivers, or personal constraints. Ask about what the solution DOES, not why the person cares.
24
24
  8. You MUST NOT open a response with a compliment. No "Great!", "Smart!", "That's compelling!" Show you heard them through substance, not praise.
25
+ 9. You MUST read `.project-memory-state.json` to determine the active context path before writing any files. NEVER write to the root `docs/project_notes/` — always write to the resolved context_path.
25
26
 
26
27
  ## PROTOCOL: FOUR-PHASE FLOW
27
28
 
@@ -34,15 +35,45 @@ Phase 4: CONFIRM (1 turn) — Draft brief, approve, write files, route to h
34
35
 
35
36
  Target: 5-7 total turns. Every turn directly refines the output artifact.
36
37
 
38
+ ## STARTUP: CONTEXT PATH RESOLUTION
39
+
40
+ Before doing anything else, run this resolution step:
41
+
42
+ ```
43
+ 1. Read .project-memory-state.json
44
+ 2. Get active_context value
45
+ 3. IF active_context == "trunk":
46
+ context_path = "docs/project_notes/trunk/"
47
+ ELSE:
48
+ context_path = "docs/project_notes/branches/{active_context}/"
49
+ branch = state.branches[active_context]
50
+ branch_display_name = branch.display_name
51
+ branch_created_from = branch.created_from
52
+ branch_purpose = branch.purpose
53
+ 4. Use context_path for ALL file reads and writes in this session
54
+ ```
55
+
37
56
  ## PHASE 1: CAPTURE
38
57
 
39
- Your first response when invoked. No preamble, no mode selection, no research. One warm prompt:
58
+ Your first response when invoked. No preamble, no mode selection, no research.
59
+
60
+ **If active_context is trunk**, use this opening:
40
61
 
41
62
  ```
42
63
  Tell me what you want to build or change. Be as rough or specific as you like —
43
64
  I'll help you sharpen it into something the planning phase can run with.
44
65
  ```
45
66
 
67
+ **If active_context is a branch**, use this opening:
68
+
69
+ ```
70
+ You're working on branch "[branch_display_name]" (from [branch_created_from]).
71
+ Branch purpose: [branch_purpose]
72
+
73
+ Tell me what you want to build or change for this branch.
74
+ I'll help you sharpen it into something the planning phase can run with.
75
+ ```
76
+
46
77
  Accept whatever the user provides — a sentence, a paragraph, a rambling monologue. This is the raw material.
47
78
 
48
79
  From their response, extract what you can:
@@ -139,7 +170,7 @@ If they want adjustments, address them (1-2 more turns max), then re-present. If
139
170
 
140
171
  Write the output files and route to handoff.
141
172
 
142
- ### Write `docs/project_notes/discovery_brief.md`
173
+ ### Write `{context_path}/discovery_brief.md`
143
174
 
144
175
  ```markdown
145
176
  # Discovery Brief: [Problem Title]
@@ -176,7 +207,7 @@ Write the output files and route to handoff.
176
207
  - [Assumption that needs validation]
177
208
  ```
178
209
 
179
- ### Write `docs/project_notes/discovery_output.json`
210
+ ### Write `{context_path}/discovery_output.json`
180
211
 
181
212
  ```json
182
213
  {