@tgoodington/intuition 10.0.0 → 10.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "10.0.0",
+  "version": "10.2.0",
   "description": "Domain-adaptive workflow system for Claude Code: prompt, outline, assemble specialist teams, detail with domain experts, build with format producers, test code output. Supports v8 compat (design, engineer, build) and v9 specialist workflows with 14 domain specialists and 6 format producers.",
   "keywords": [
     "claude-code",

package/skills/intuition-build/SKILL.md

@@ -79,6 +79,7 @@ Read these files:
 5. `{context_path}/scratch/*-decisions.json` (all specialist decision logs) — decision tiers and chosen options.
 6. `{context_path}/prompt_brief.md` — Commander's Intent, success criteria, non-negotiables (for Vision Alignment in report).
 7. `{context_path}/vision-review.md` (if exists) — flagged items from detail's vision review that build should address.
+8. `{context_path}/process_flow.md` (if exists) — end-to-end user flows, component interactions, data paths, error paths. Used for flow verification in Layer 2 and as orientation context for producers.
 
 From team_assignment.json, extract:
 - `specialist_assignments` — which specialist owns which tasks
@@ -165,6 +166,9 @@ The full blueprint contains all specifications — do not deviate from them.
 
 Output directory: [from blueprint's Producer Handoff]
 Output files: [from blueprint's Producer Handoff]
+
+## Flow Context (if process_flow.md exists)
+[Extract the relevant flow segment from process_flow.md showing where this deliverable fits in the end-to-end path. This is for orientation only — your specifications come from the blueprint.]
 ```
 
 When building on a branch, add to subagent prompts:
@@ -218,6 +222,16 @@ Check the deliverable yourself against outline.md acceptance criteria:
 
 Log all deviations (additions and omissions) in the build report's "Deviations from Blueprint" section, even if they seem minor.
 
+**Process flow verification (conditional):**
+If `{context_path}/process_flow.md` exists, verify the produced deliverables match the described end-to-end flows:
+- Trace each Core Flow's path against the implemented code. Do the components interact as described?
+- Check that error paths described in process_flow.md have corresponding implementation.
+- Check that integration seams have matching contracts on both sides.
+
+Log any mismatches in the build report under "Process Flow Deviations." If a deviation affects what the end user sees or experiences, escalate via AskUserQuestion with options: "Fix the code to match the process flow" / "Accept the deviation" / "I need to think about this." If the user accepts a deviation, note in the build report that process_flow.md is stale at that section.
+
+In **fast track mode**, treat process_flow.md as advisory only — log observations but do not escalate deviations (the document is in skeletal draft form without detail refinement).
+
 - If FAIL → send feedback back to the producer with specific acceptance criteria gaps. Do NOT proceed to Layer 3.
 - If PASS → proceed to Layer 3.
 
@@ -322,6 +336,13 @@ Write the build report to `{context_path}/build_report.md` AND display a summary
 
 [If no test deliverables were found in any blueprint, write "No test deliverables found in blueprints."]
 
+## Process Flow Deviations
+[Cross-cutting deviations between implementation and process_flow.md. If no process_flow.md exists, write "N/A — no process flow document." If no deviations, write "None — implementation matches process flows."]
+
+| Flow | Deviation | Resolution |
+|------|-----------|------------|
+| [flow name] | [what differs] | [Fixed / Accepted — user approved / Flagged for update] |
+
 ## Vision Alignment
 [Read `{context_path}/prompt_brief.md` — extract Success Criteria and Commander's Intent non-negotiables. Map each to the produced output.]
 

package/skills/intuition-debugger/SKILL.md

@@ -3,7 +3,7 @@ name: intuition-debugger
 description: Expert diagnostic and resolution service for completed workflow contexts. Investigates issues holistically — considering architectural alignment, security, ripple effects, maintenance burden, and functional correctness — then presents solution options in plain language for a non-technical creative director. Generates fast-track briefs when issues require upstream workflow passes.
 model: opus
 tools: Read, Write, Edit, Glob, Grep, Agent, AskUserQuestion, Bash, mcp__ide__getDiagnostics
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash, mcp__ide__getDiagnostics
+allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash, mcp__ide__getDiagnostics
 ---
 
 # CRITICAL RULES
@@ -105,10 +105,11 @@ Read ALL of these before proceeding — build your understanding of what was bui
 - `docs/project_notes/bugs.md` — previously logged bugs
 - `{context_path}/scratch/*-decisions.json` — specialist decisions (if any exist)
 
-Also check for blueprints:
+Also check for blueprints and process flow:
 - `{context_path}/blueprints/*.md` — detailed specialist blueprints (if detail phase ran)
+- `{context_path}/process_flow.md` (if exists) — end-to-end user flows, component interactions, data paths, error paths, state mutations, integration seams, known invariants. This is your primary map of how the app works. Use it to understand upstream/downstream impact before reading source code.
 
-The gap between intended approach and actual implementation is where bugs hide. The decisions files tell you what constraints MUST be preserved.
+The gap between intended approach and actual implementation is where bugs hide. The decisions files tell you what constraints MUST be preserved. The process flow document tells you how the pieces connect — trace the reported issue through the flow to understand the full impact chain.
 
 Do NOT read source code files yet. Read targeted code only after the user describes the issue.
 
@@ -164,7 +165,8 @@ With the root cause identified, evaluate through EVERY lens:
 - Check: input validation, output encoding, auth boundaries, data exposure.
 
 **Ripple Effects:**
-- Launch an `intuition-researcher` agent to map the dependency graph:
+- If `{context_path}/process_flow.md` exists, start with it: identify which Core Flows pass through the affected area, what's upstream and downstream, and what state mutations or integration seams are involved. Use the Component Dependencies and Integration Seams sections to pre-map the blast radius before launching a researcher.
+- Launch an `intuition-researcher` agent to verify and extend the process flow mapping against actual code:
   ```
   "Map all imports, usages, and dependents of [affected module/function/interface]
   across the codebase. Report: file paths, line numbers, how each usage depends
@@ -395,6 +397,14 @@ After the subagent returns:
 - **Prevention**: [How to avoid in future — what should the build process catch?]
 ```
 
+**Update process flow (conditional)** — If `{context_path}/process_flow.md` exists AND the fix changes how a flow actually works (e.g., adds error handling that changes an error path, restructures a component interaction, or modifies state mutations):
+1. Read the current process_flow.md
+2. Update ONLY the specific flow section affected by the fix
+3. Add an entry to the Flow History table: `| [YYYY-MM-DD] | Debugger | [What changed] | [Fix for: brief issue description] |`
+4. Add or update the Known Fragile Areas section if the investigation revealed a fragile pattern
+
+Do NOT update process_flow.md for fixes that don't change flow behavior (e.g., fixing a typo, correcting a calculation that doesn't change the data path). Do NOT rewrite the Overview or restructure the document. When generating a fast-track brief (upstream fix), do NOT update process_flow.md — the upstream workflow will update it after implementing changes.
+
 **Save Intuition memory** — When the investigation reveals something with cross-conversation value, save a memory file to `C:\Users\tgoodington\.claude\projects\C--Claude-Projects-Intuition\memory\`:
 
 Save a memory when:

package/skills/intuition-detail/SKILL.md

@@ -404,6 +404,29 @@ Triggers when Step 8d finds no remaining specialists.
 
 **9a. Conflict detection.** Spawn an `intuition-researcher` agent: "Read all blueprint files in `{context_path}/blueprints/`. Compare for: contradictory decisions, overlapping file modifications with conflicting changes, inconsistent interface assumptions, and duplicated work. Write findings to `{context_path}/blueprint-conflicts.md`. If no conflicts, write 'No conflicts detected.'" Wait for completion. If conflicts found, present to user via AskUserQuestion and resolve before continuing.
 
+**9a-ii. Process flow synthesis (conditional).** Skip this step if `{context_path}/process_flow.md` does not exist (non-code project or Lightweight outline).
+
+If `process_flow.md` exists, spawn an `intuition-synthesizer` agent:
+
+"Read these files:
+1. `{context_path}/process_flow.md` — the outline's initial WHAT-level flow draft
+2. For each blueprint in `{context_path}/blueprints/`: read Section 3 (Approach) and Section 7 (Integration Points) only
+
+Refine the process flow document with specialist knowledge. The outline draft describes flows at the WHAT level. Your job is to add the HOW:
+- Fill in concrete data paths, state transitions, and error propagation chains from the blueprints
+- Add state mutations per flow (which stores are written, by which step)
+- Add known invariants per flow (things that MUST remain true)
+- Populate the Component Dependencies section from blueprint integration points
+- Populate Integration Seams with contracts and failure modes
+- Resolve any conflicts between the outline's assumed flows and specialist approaches (specialist knowledge supersedes outline assumptions — they had deeper research)
+- Update the Flow History table
+
+Keep the document under 200 lines for Standard-tier projects, under 400 for Comprehensive. Be terse — structured steps, not prose.
+
+Write the refined document to `{context_path}/process_flow.md` (overwriting the outline's draft)."
+
+Wait for completion. If the vision review (9b) later triggers a specialist re-run, re-run this synthesis step after the re-run completes.
+
 **9b. Vision review.** Skip this step if only 1 specialist completed (no cross-specialist seams to check).
 
 For multi-specialist projects, spawn an `intuition-reviewer` agent:
@@ -411,7 +434,8 @@ For multi-specialist projects, spawn an `intuition-reviewer` agent:
 "Read these files:
 1. `{context_path}/prompt_brief.md` — extract Commander's Intent (desired end state, non-negotiables, boundaries) and Success Criteria
 2. `{context_path}/outline.md` — extract the task list and acceptance criteria
-3. For each blueprint in `{context_path}/blueprints/`: read the Approach section (Section 3) and Acceptance Mapping section (Section 6) only — skip the full deliverable specs
+3. `{context_path}/process_flow.md` (if exists) — the refined end-to-end flow document. Check that flows honor Commander's Intent and that no seams are missing.
+4. For each blueprint in `{context_path}/blueprints/`: read the Approach section (Section 3) and Acceptance Mapping section (Section 6) only — skip the full deliverable specs
 
 Then evaluate the blueprints AS A WHOLE against the original vision:
 

package/skills/intuition-initialize/SKILL.md

@@ -3,7 +3,7 @@ name: intuition-initialize
 description: Set up project memory infrastructure with workflow state tracking, memory files, and configuration templates.
 model: haiku
 tools: Read, Write, Glob, Grep, Bash, AskUserQuestion
-allowed-tools: Read, Write, Glob, Grep
+allowed-tools: Read, Write, Glob, Grep, Bash
 ---
 
 # Initialize - Project Memory Setup Protocol

package/skills/intuition-meander/SKILL.md

@@ -3,7 +3,7 @@ name: intuition-meander
 description: Thought partner for reasoning through problems. Use when the user wants to think through an idea, explore a problem space, work through a decision, or talk something out. A collaborative thinking companion — not a workflow tool.
 model: opus
 tools: Read, Glob, Grep, Bash, Agent, AskUserQuestion, WebFetch, WebSearch
-allowed-tools: Read, Glob, Grep, Bash, Agent
+allowed-tools: Read, Glob, Grep, Bash, Agent, WebFetch, WebSearch
 ---
 
 # Meander — Thinking Partner

package/skills/intuition-outline/SKILL.md

@@ -313,6 +313,52 @@ Before drafting, verify ALL research agents launched during Phase 3 have returne
 
 Read `{context_path}/.outline_research/decisions_log.md` and `orientation.md` to gather resolved context. Draft the outline following the outline.md output format below, applying scope scaling for the selected tier.
 
+## Step 2b: Draft process flow (conditional)
+
+**Gate:** Generate process_flow.md ONLY when ALL conditions are met:
+1. Tier is **Standard** or **Comprehensive**
+2. Orientation research identified code, interactive components, or systems with runtime behavior (3+ components that interact)
+
+If the gate is not met, skip this step entirely. Non-code projects (documents, spreadsheets, strategies) do not get a process flow.
+
+If the gate IS met, draft `{context_path}/process_flow.md` alongside the outline. This is a WHAT-level document — describe flows in terms of user actions, involved components, and expected outcomes. Do NOT specify data shapes, state implementation details, or internal algorithms (those are HOW decisions for the detail phase).
+
+Use this structure:
+
+```markdown
+# Process Flow: [App/Feature Name]
+
+## Overview
+[2-3 sentences: what the app/feature does and who it serves]
+
+## Core Flows
+
+### [Flow Name]
+**Trigger:** [user action / API call / scheduled job]
+**Path:** ComponentA → ComponentB → ComponentC
+1. [Actor does action → which component handles it → expected outcome]
+2. [...]
+N. [Final result visible to user or system]
+
+**Error path:** [what happens on failure — at WHAT level, not implementation detail]
+**Side effects:** [notifications, logging, external calls — if known]
+
+[Repeat for each major user-facing flow identified during ARCH exploration]
+
+## Integration Points
+[Component handoff seams identified during Reach exploration — where components interact]
+
+## Cross-Cutting Concerns
+[Auth, error handling, state management patterns — from Section 10 context]
+
+## Flow History
+| Date | Phase | Change | Reason |
+|------|-------|--------|--------|
+| [today] | Outline | Initial draft | Created from ARCH exploration |
+```
+
+Present process_flow.md alongside the outline for user approval in Step 4.
+
 ## Step 3: Validate
 
 Run the Executable Outline Checklist (below). Fix any failures before presenting.
@@ -348,7 +394,8 @@ If changes requested, make them and present again. Repeat until explicitly appro
 After explicit approval:
 
 1. Write the final outline to `{context_path}/outline.md`.
-2. Run the Exit Protocol.
+2. If process_flow.md was drafted in Step 2b, write it to `{context_path}/process_flow.md`.
+3. Run the Exit Protocol.
 
 ## Exit Protocol
 
@@ -599,6 +646,7 @@ Validate ALL before presenting the draft:
 - [ ] Tasks with decision points have Decisions field with `[USER]`/`[SPEC]` classifications
 - [ ] Decision classifications use Commander's Intent to determine human-facing boundary
 - [ ] Large data files (if detected in orientation) have a preprocessing task before any dependent work
+- [ ] Process flow document generated for Standard+ code projects with 3+ interacting components (skip for non-code or Lightweight)
 
 If any check fails, fix it before presenting.
 

package/skills/intuition-start/SKILL.md

@@ -2,13 +2,13 @@
 name: intuition-start
 description: Load project context, detect workflow phase, route to the correct next skill.
 model: haiku
-tools: Read, Glob, Grep, AskUserQuestion, Bash
-allowed-tools: Read, Glob, Grep, Bash
+tools: Read, Write, Glob, Grep, AskUserQuestion, Bash
+allowed-tools: Read, Write, Glob, Grep, Bash
 ---
 
 # Start - Phase Detector & Router
 
-You detect the current workflow phase and route the user to the correct next skill. You are strictly read-only — you NEVER write or modify any files.
+You detect the current workflow phase and route the user to the correct next skill. You are read-only except for bootstrapping a missing state file in legacy projects (Step 1.5).
 
 ## Package Version Info
 
@@ -26,8 +26,8 @@ You detect the current workflow phase and route the user to the correct next ski
 
 1. You MUST detect the current workflow phase before doing anything else.
 2. You MUST suggest the correct next skill based on the detected phase.
-3. You MUST NOT write, create, or modify ANY files.
-4. You MUST NOT manage .project-memory-state.json — handoff owns state.
+3. You MUST NOT write or modify files EXCEPT to bootstrap a missing `.project-memory-state.json` (see STEP 1.5).
+4. You MUST NOT manage .project-memory-state.json after creation — handoff owns state transitions.
 5. You MUST resolve context_path from active_context before phase detection.
 
 ## PROTOCOL
@@ -35,6 +35,7 @@ You detect the current workflow phase and route the user to the correct next ski
 ```
 Step 0: Check package version — notify if update available (non-blocking)
 Step 1: Read docs/project_notes/.project-memory-state.json
+Step 1.5: If state file missing but docs/project_notes/ exists, bootstrap it
 Step 2: Validate schema version
 Step 3: Resolve active_context and context_path
 Step 4: Detect phase using decision tree
@@ -52,6 +53,44 @@ Parse version numbers from "Package Version Info" above:
 
 NON-BLOCKING: If version commands failed, skip and proceed.
 
+## BOOTSTRAP MISSING STATE FILE (Step 1.5)
+
+If `.project-memory-state.json` does NOT exist, check whether `docs/project_notes/` directory exists (use Glob for `docs/project_notes/*`).
+
+```
+IF docs/project_notes/ exists BUT .project-memory-state.json is missing:
+  → This is a legacy project from an older framework version.
+  → Create docs/project_notes/.project-memory-state.json with the v8.0 default schema:
+
+  {
+    "initialized": true,
+    "version": "8.0",
+    "active_context": "trunk",
+    "trunk": {
+      "status": "none",
+      "workflow": {
+        "prompt": { "started": false, "completed": false, "started_at": null, "completed_at": null, "output_files": [] },
+        "outline": { "started": false, "completed": false, "completed_at": null, "approved": false },
+        "design": { "started": false, "completed": false, "completed_at": null, "items": [], "current_item": null },
+        "engineering": { "started": false, "completed": false, "completed_at": null },
+        "build": { "started": false, "completed": false, "completed_at": null },
+        "test": { "started": false, "completed": false, "completed_at": null, "skipped": false },
+        "detail": { "started": false, "completed": false, "completed_at": null, "team_assignment": null, "specialists": [], "current_specialist": null, "execution_phase": 1 }
+      }
+    },
+    "branches": {},
+    "last_handoff": null,
+    "last_handoff_transition": null
+  }
+
+  → Also create docs/project_notes/trunk/.gitkeep and docs/project_notes/branches/.gitkeep if those directories are missing.
+  → OUTPUT: "Legacy project detected — created .project-memory-state.json (v8.0)."
+  → Continue to Step 2 with the newly created state.
+
+IF neither docs/project_notes/ NOR .project-memory-state.json exist:
+  → This is a brand new project. Route to first_time as before.
+```
+
 ## SCHEMA VERSION CHECK (Step 2)
 
 After reading `.project-memory-state.json`:

package/skills/intuition-test/SKILL.md

@@ -65,7 +65,8 @@ Read these files:
 
 1. `{context_path}/build_report.md` — REQUIRED. Extract: files modified, task results, deviations from blueprints, decision compliance notes.
 2. `{context_path}/outline.md` — acceptance criteria per task.
-3. `{context_path}/test_advisory.md` — compact testability notes extracted by the detail phase (one section per specialist). Read this INSTEAD of all blueprints. If this file does not exist (older workflows), fall back to reading `{context_path}/blueprints/*.md` and extracting Testability Notes from each Approach section.
+3. `{context_path}/process_flow.md` (if exists) — end-to-end user flows, component interactions, data paths, error paths. Primary source for designing integration and E2E tests. If this file does not exist (non-code project or Lightweight workflow), proceed without it.
+4. `{context_path}/test_advisory.md` — compact testability notes extracted by the detail phase (one section per specialist). Read this INSTEAD of all blueprints. If this file does not exist (older workflows), fall back to reading `{context_path}/blueprints/*.md` and extracting Testability Notes from each Approach section.
 4. `{context_path}/team_assignment.json` — producer assignments (identify code-writer tasks).
 5. ALL files matching `{context_path}/scratch/*-decisions.json` — decision tiers and chosen options per specialist.
 6. `docs/project_notes/decisions.md` — project-level ADRs.
@@ -107,6 +108,15 @@ Prioritize by value:
 - **Integration tests** (medium priority): API routes, database operations, service interactions, middleware chains. Use real dependencies where feasible, mock externals.
 - **E2E tests** (only if framework exists): Only create if the project already has an E2E framework configured. Never introduce a new E2E framework.
 
+### Process Flow Coverage (if process_flow.md exists)
+
+Use process_flow.md to identify cross-component integration boundaries and E2E paths that acceptance criteria alone don't reveal:
+- **Integration seams**: For each Integration Seam in process_flow.md, design at least one integration test that exercises the handoff between components.
+- **Error propagation**: For each error path described in Core Flows, design a test that triggers the failure and verifies the described fallback behavior.
+- **State mutations**: For each state mutation listed in Core Flows, verify the mutation occurs and dependents react correctly.
+
+If process_flow.md conflicts with actual implementation (check build_report.md deviations), test against the implementation, not the document.
+
 ### File Type Heuristic
 
 For each modified file, classify the appropriate test type:
@@ -216,6 +226,7 @@ You are a test writer. Create a test file following these specifications exactly
 
 **Source file:** Read [source file path]
 **Blueprint context:** Read [relevant blueprint path] (for domain understanding)
+**Flow context (integration/E2E tests only):** Read `{context_path}/process_flow.md` (if exists) for understanding how this component participates in end-to-end user flows. Not needed for unit tests.
 
 **Test file path:** [target test file path]
 **Test cases to implement:**

package/skills/intuition-think-tank/SKILL.md

@@ -3,7 +3,7 @@ name: intuition-think-tank
 description: Rapid expert-panel analysis. Use when the user wants a well-rounded evaluation of documents, ideas, proposals, or strategies — faster than a full workflow pass. Assembles a dynamic panel of perspectives, runs parallel analysis, and delivers a cohesive synthesis.
 model: opus
 tools: Read, Glob, Grep, Bash, Agent, AskUserQuestion, WebFetch, WebSearch
-allowed-tools: Read, Glob, Grep, Bash, Agent
+allowed-tools: Read, Glob, Grep, Bash, Agent, WebFetch, WebSearch
 ---
 
 # Think Tank — Rapid Expert Panel