@tgoodington/intuition 11.4.0 → 11.5.0

package/docs/project_notes/project_map.md

@@ -0,0 +1,117 @@
+# Project Map — Intuition Framework
+
+Living architecture document for the Intuition framework repo. Update as architecture changes. Do NOT duplicate what's in SKILL.md frontmatter or skill rules — capture relationships, data flow, and where to make changes.
+
+## What This Repo Is / Isn't
+
+**Is:** the source for `@tgoodington/intuition`, an npm package that installs skills, specialists, producers, and agents into a user's `~/.claude/` directory for use inside Claude Code.
+
+**Isn't:** a downstream project that uses the Enuncia pipeline to build something. Work here modifies the framework itself.
+
+**Distribution:** published globally. Consumers run `npm install -g @tgoodington/intuition`. The `postinstall` hook in `package.json` runs `scripts/install-skills.js`, which copies this repo's `skills/`, `specialists/`, `producers/`, and `agents/` directories into `~/.claude/`. Uninstall mirrors via `preuninstall` → `scripts/uninstall-skills.js`.
+
+## Architecture
+
+### Top-level layout
+
+| Directory | Role |
+|-----------|------|
+| `skills/` | Skill packages, each with `SKILL.md` and optional `references/` subdir |
+| `specialists/` | Domain specialist profiles (business analyst, legal, database architect, etc.) used by `intuition-detail` |
+| `producers/` | Format-specific writers (code, document, spreadsheet, ui, etc.) invoked by build/execute phases |
+| `agents/` | Reusable subagent definitions (researcher, synthesizer, reviewer, code-writer) |
+| `scripts/` | Install/uninstall logic — the distribution entry points |
+| `bin/` | CLI entry (`intuition.js`) — minimal; most UX is through slash commands |
+| `docs/project_notes/` | This file, plus decisions/bugs/key_facts/issues |
+
+### Enuncia pipeline — data flow
+
+The primary workflow (v11). Each skill reads and writes files in the consumer project's `docs/project_notes/{trunk|branches/<name>}/`, referred to here as `{ctx}/`.
+
+```
+initialize  →  creates docs/project_notes/ scaffold + state + CLAUDE.md
+                                                           │
+start       →  reads state, routes to the correct phase    │
+                                                           ▼
+discovery   →  interactive Q&A, writes {ctx}/discovery_brief.md
+                                                           │
+compose     →  reads brief, writes {ctx}/tasks.json + updates project_map.md
+                                                           │
+design      →  reads brief + tasks, enriches tasks.json with design fields,
+               updates project_map.md
+                                                           │
+execute     →  reads brief + enriched tasks, delegates to producers,
+               writes {ctx}/build_output.json
+                                                           │
+verify      →  reads brief + tasks + build_output + project_map,
+               wires code in, walks user through live UX validation
+```
+
+**Handoff** (`intuition-enuncia-handoff`) runs independently to create branches. Each enuncia phase handles its own state transitions — handoff is branch-creation only.
+
+### Subagent model
+
+Skills do not produce deliverables directly. They delegate via the `Task` tool to:
+
+- **Producers** (`producers/`) — format-specific writers. `code-writer` for code, `document-writer` for prose, `spreadsheet-builder` for sheets, `ui-writer` for UI, etc.
+- **Specialists** (`specialists/`) — domain experts. Used by `intuition-detail` (classic pipeline) to explore a problem through a domain lens.
+- **Agents** (`agents/`) — reusable roles (researcher, synthesizer, reviewer, code-writer) distinct from producers. Scanned dynamically at install.
+
+New producer or specialist → drop a directory with its profile; installer picks it up. New skill → add its name to the hardcoded `skills` array in `scripts/install-skills.js`.
+
+### State and context
+
+- `docs/project_notes/.project-memory-state.json` — workflow state (phase progress, active context, branches). v11 Enuncia schema in `skills/intuition-enuncia-initialize/references/state_template.json`.
+- `active_context` = `"trunk"` or a branch name. Each skill resolves `context_path` from this before reading/writing.
+- CLAUDE.md (in consumer project, written by `intuition-enuncia-initialize`) carries the Project Goal and How to Interact framing.
+
+## Active vs Legacy
+
+### Active — Enuncia pipeline (v11)
+
+Primary workflow. All skills prefixed `intuition-enuncia-*`:
+- `initialize`, `start`, `discovery`, `compose`, `design`, `execute`, `verify`, `handoff`
+
+### Active — Utilities (version-agnostic)
+
+- `intuition-meander` — thought partner
+- `intuition-think-tank` — expert-panel analysis
+- `intuition-debugger` — diagnostic service
+- `intuition-agent-advisor`, `intuition-skill-guide` — advisory skills for building agents/skills
+- `intuition-update` — framework update helper
+
+### Legacy — Classic pipeline (v8–v10)
+
+Still installed and functional; kept for compatibility but not the recommended path:
+- `intuition-start`, `intuition-prompt`, `intuition-handoff`, `intuition-outline`, `intuition-initialize`
+- `intuition-assemble`, `intuition-detail`, `intuition-build`, `intuition-test`, `intuition-implement`
+
+Note: `intuition-outline` (classic) was renamed from `intuition-plan` in v9.1; the enuncia equivalent is `intuition-enuncia-compose`.
+
+### Removed (installer cleans up stale installs)
+
+- `intuition-discovery` — replaced by `intuition-design` in v6.0, then removed in v10.0
+- `intuition-execute` — split into `engineer`+`build` in v8.0, both removed in v10.0
+- `intuition-plan` — renamed to `intuition-outline` in v9.1
+
+See `scripts/install-skills.js` lines ~118–150 for the cleanup logic.
+
+## Where to Make Changes
+
+| Want to... | Edit |
+|------------|------|
+| Change a skill's rules or protocol | `skills/<skill-name>/SKILL.md` |
+| Change what CLAUDE.md says for new Enuncia projects | `skills/intuition-enuncia-initialize/references/claude_template.md` |
+| Change the memory file scaffold (bugs/decisions/etc.) | `skills/intuition-enuncia-initialize/references/*_template.md` |
+| Change the state schema | `skills/intuition-enuncia-initialize/references/state_template.json` |
+| Add a new skill | Create `skills/<name>/SKILL.md`, then add the name to the `skills` array in `scripts/install-skills.js` |
+| Add a new producer or specialist | Drop directory; installer picks up dynamically |
+| Change install behavior | `scripts/install-skills.js` (mirror in `uninstall-skills.js`) |
+| Bump version | `package.json` `version` field; commit with matching message |
+
+## Notes and Caveats
+
+- The `skills` array in `scripts/install-skills.js` is hardcoded (line 44). New skills must be added there or they won't install.
+- Producers are also hardcoded (line 82); specialists and agents are scanned dynamically.
+- The package distributes the directories listed in `package.json` `files` — if you add a new top-level directory that needs to ship, add it there too.
+- Consumer projects must install Intuition globally, not locally. `intuition-enuncia-initialize` Step 0 enforces this by uninstalling local installs it finds.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "11.4.0",
+  "version": "11.5.0",
   "description": "Domain-adaptive workflow system for Claude Code. Includes the Enuncia pipeline (discovery, compose, design, execute, verify) and the classic pipeline (prompt, outline, assemble, detail, build, test, implement).",
   "keywords": [
     "claude-code",

package/skills/intuition-enuncia-compose/SKILL.md

@@ -8,10 +8,6 @@ allowed-tools: Read, Write, Glob, Grep, Task, Bash
 
 # Outline Protocol
 
-## PROJECT GOAL
-
-Deliver something to the user through an experience that places them as creative director, offloading technical implementation to Claude, that satisfies their needs and desires.
-
 ## SKILL GOAL
 
 Take the discovery foundation and determine what needs to exist from each stakeholder's perspective (experience slices), then decompose into tasks that the design phase can build technical specs from. Produce the first draft of the project map — a living document that tracks how the pieces connect and evolves through each downstream phase.
@@ -24,12 +20,11 @@ You are a decomposition thinker. You see a vision and ask "what needs to be true
 2. You MUST read `{context_path}/discovery_brief.md`. If missing, stop: "No discovery brief found. Run `/intuition-enuncia-discovery` first."
 3. During dialogue, you MUST ask questions as plain text. AskUserQuestion is ONLY for the approval gate at the end.
 4. You MUST NOT make technical decisions. Architecture, technology choices, and implementation approaches belong to specialists.
-5. You MUST NOT open a response with a compliment or filler.
-6. You MUST produce experience slices that are stakeholder-perspective-in, not component-out.
-7. You MUST decompose tasks until each one passes the producer-ready test (see SIZING CHECK). There is no "Deep" or "Standard" — every task should be light enough to build directly.
-8. You MUST write `tasks.json`, `docs/project_notes/project_map.md`, and update state before routing.
-9. You MUST route to `/intuition-enuncia-design`. NEVER to `/intuition-enuncia-handoff`.
-10. You MUST reference the discovery brief's North Star when evaluating whether experience slices are complete — if a slice doesn't serve the North Star, it doesn't belong.
+5. You MUST produce experience slices that are stakeholder-perspective-in, not component-out.
+6. You MUST decompose tasks until each one passes the producer-ready test (see SIZING CHECK). There is no "Deep" or "Standard" — every task should be light enough to build directly.
+7. You MUST write `tasks.json`, `docs/project_notes/project_map.md`, and update state before routing.
+8. You MUST route to `/intuition-enuncia-design`. NEVER to `/intuition-enuncia-handoff`.
+9. You MUST reference the discovery brief's North Star when evaluating whether experience slices are complete — if a slice doesn't serve the North Star, it doesn't belong.
 
 ## CONTEXT PATH RESOLUTION
 

package/skills/intuition-enuncia-design/SKILL.md

@@ -8,10 +8,6 @@ allowed-tools: Read, Write, Glob, Grep, Task, Bash
 
 # Design Protocol
 
-## PROJECT GOAL
-
-Deliver something to the user through an experience that places them as creative director, offloading technical implementation to Claude, that satisfies their needs and desires.
-
 ## SKILL GOAL
 
 Take the outline's experience slices and tasks and determine how they get built. Research the codebase and technical landscape, make design decisions, write specs detailed enough for producers to execute, and surface decisions to the user per their decision posture. Update the project map to reflect the real architecture.

package/skills/intuition-enuncia-discovery/SKILL.md

@@ -8,18 +8,12 @@ allowed-tools: Read, Write, Glob, Grep, Task
 
 # Discovery Protocol
 
-## PROJECT GOAL
-
-Deliver something to the user through an experience that places them as creative director, offloading technical implementation to Claude, that satisfies their needs and desires.
-
 ## SKILL GOAL
 
 Understand the who, what, where, and why of the project to create a foundational document that all other skills orient from and verify against.
 
 You help users figure out what they're building. You do this through focused conversation across four dimensions — Who, Where, What, Why — producing a foundational brief that every downstream skill will reference as its source of truth.
 
-You are a sharp collaborator. You listen carefully, confirm what's clear, push back when something seems incomplete or inconsistent, and help the user think when they're uncertain. You never flatter, never pad, never ask questions you already know the answer to.
-
 ## CRITICAL RULES
 
 1. You MUST ask exactly ONE question per turn. No exceptions.
@@ -27,7 +21,7 @@ You are a sharp collaborator. You listen carefully, confirm what's clear, push b
 3. AskUserQuestion is ONLY used for the Confirm step and Decision Posture — the two approval gates at the end.
 4. Every question MUST target one of the four dimensions: Who, Where, What, or Why.
 5. You MUST NOT ask implementation-level questions. "How should the database handle X" is too detailed. "What should users be able to do" is right.
-6. You MUST NOT open a response with a compliment or filler. Show you heard them through substance. Do NOT restate what the user just said back to them — only recap when you are sharpening or reframing their words into something more precise.
+6. You MUST NOT restate what the user just said back to them — only recap when you are sharpening or reframing their words into something more precise.
 7. You MUST NOT ask about motivations, feelings, or personal drivers. Ask about the project, not the person.
 8. You MUST read `.project-memory-state.json` to determine the active context path before writing any files.
 9. You MUST write `discovery_brief.md` when formalizing.

package/skills/intuition-enuncia-execute/SKILL.md

@@ -8,10 +8,6 @@ allowed-tools: Read, Write, Glob, Grep, Task, TaskCreate, TaskUpdate, TaskList,
 
 # Execute Protocol
 
-## PROJECT GOAL
-
-Deliver something to the user through an experience that places them as creative director, offloading technical implementation to Claude, that satisfies their needs and desires.
-
 ## SKILL GOAL
 
 Execute the design specs. Delegate production to the right producers, verify what's built matches both the specs and the discovery foundation, and surface problems honestly. You are the execution arm — you don't make design decisions, you carry them out and verify the results.

package/skills/intuition-enuncia-handoff/SKILL.md

@@ -8,10 +8,6 @@ allowed-tools: Read, Write, Glob, Grep, Bash
 
 # Handoff Protocol (Enuncia Pipeline)
 
-## PROJECT GOAL
-
-Deliver something to the user through an experience that places them as creative director, offloading technical implementation to Claude, that satisfies their needs and desires.
-
 ## SKILL GOAL
 
 Create and register new branches. In the Enuncia pipeline, each skill handles its own state transitions — handoff exists only for branch creation.

package/skills/intuition-enuncia-initialize/references/claude_template.md

@@ -1,3 +1,23 @@
+## Project Goal
+
+Deliver something the user actually wants, through a process where:
+
+- **The user directs.** They decide what gets built, how it should feel, and whether it's right. Product decisions are theirs.
+- **Claude implements.** Claude handles the technical work — architecture, code, configuration. Claude surfaces tradeoffs and options, but never makes product decisions unilaterally.
+- **The result satisfies the user's real needs and desires** — not what's easiest to build, not what Claude assumes they want.
+
+This goal holds whether or not a skill is active. Every skill in the Enuncia pipeline is one step toward it.
+
+## How to Interact
+
+The user is the director. You are the implementer. This holds in every conversation, skill-active or not.
+
+- **Offer options, don't decide.** When the user faces a choice that shapes the product, surface the tradeoffs and let them pick.
+- **Be a sharp collaborator.** Listen carefully. Confirm what's clear. Push back when something seems incomplete or inconsistent. Help them think when they're uncertain.
+- **Never flatter, never pad, never restate what they just said.** Show you heard them through substance, not echo.
+- **When a request is ambiguous, ask — don't guess.** One question at a time.
+- **Flag goal conflicts.** If a request would compromise the director experience or push implementation work back on the user, say so.
+
 ## Project Workflow and Memory System
 
 This project uses the Enuncia pipeline (`@tgoodington/intuition`). Run `/intuition-enuncia-start` to check project status and get routed to the next step.

package/skills/intuition-enuncia-start/SKILL.md

@@ -8,10 +8,6 @@ allowed-tools: Read, Write, Glob, Grep, Bash
 
 # Start Protocol (Enuncia Pipeline)
 
-## PROJECT GOAL
-
-Deliver something to the user through an experience that places them as creative director, offloading technical implementation to Claude, that satisfies their needs and desires.
-
 ## SKILL GOAL
 
 Detect where the project is in the Enuncia pipeline and route the user to the correct next skill. You are a router — read state, determine phase, suggest the next command.

package/skills/intuition-enuncia-verify/SKILL.md

@@ -8,10 +8,6 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Task, Bash, Agent, WebFetch, mcp__
 
 # Verify Protocol
 
-## PROJECT GOAL
-
-Deliver something to the user through an experience that places them as creative director, offloading technical implementation to Claude, that satisfies their needs and desires.
-
 ## SKILL GOAL
 
 Two jobs, done relentlessly: