@tgoodington/intuition 9.3.1 → 9.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "9.3.1",
+  "version": "9.4.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-assemble/SKILL.md

@@ -48,7 +48,7 @@ Scan three tiers in priority order. Deduplicate by `name` — first found wins.
 2. Glob `~/.claude/specialists/*/*.specialist.md` (user-level, expand `~` via Bash)
 3. Determine the Intuition package root: run `node -e "console.log(require.resolve('@tgoodington/intuition/package.json'))"` via Bash, extract the directory. Glob `{package_root}/specialists/*/*.specialist.md`.
 
-For each profile found: read the YAML frontmatter, extract `name` and `domain_tags`. Build a specialists list.
+For each profile found: read ONLY the YAML frontmatter using `Read` with `limit: 30` (frontmatter is typically under 25 lines). Extract `name` and `domain_tags`. Do NOT read the full profile body — the Stage 1/2 protocols are not needed for matching. Build a specialists list.
 
 If zero specialists found after all three tiers, HALT with this message:
 "No specialist profiles found. Install specialist profiles in one of these locations:
@@ -58,7 +58,7 @@ If zero specialists found after all three tiers, HALT with this message:
 
 ### Step 3: Scan Producer Registry
 
-Same three-tier pattern using `producers/` directories and `*.producer.md` files. Extract `name` and `output_formats` from each. Deduplicate by name with same priority (first found wins).
+Same three-tier pattern using `producers/` directories and `*.producer.md` files. Read ONLY the YAML frontmatter using `Read` with `limit: 30`. Extract `name` and `output_formats` from each. Do NOT read the full profile body. Deduplicate by name with same priority (first found wins).
 
 If zero producers found, HALT with the same pattern message referencing producer directories.
 
@@ -128,7 +128,7 @@ If the outline has no format constraints and no Section 3 technology decisions a
 ### Step 5: Prerequisite Checking
 
 For each producer in `producer_assignments`:
-1. Read the full producer profile from the registry
+1. Read the producer profile frontmatter from the registry (the `tooling` field is within the frontmatter, already read in Step 3)
 2. Check `tooling.{output_format}.required` array
 3. For each required tool, run Bash to verify availability (e.g., `python --version`, `which pandoc`)
 4. Record results in `prerequisite_check` (format: `"producer/format": "PASS — tool version found"` or `"FAIL — tool not found"`)

package/skills/intuition-build/SKILL.md

@@ -149,7 +149,7 @@ For each task per `team_assignment.json` execution order (parallelize tasks with
    - Project: `.claude/producers/{producer-name}/{producer-name}.producer.md`
    - User: `~/.claude/producers/{producer-name}/{producer-name}.producer.md`
    - Framework-shipped: scan the `producers/` directory at the package root
-4. Construct the delegation prompt using the producer profile as system instructions and the blueprint as task context. Only include non-test output files in the delegation.
+4. Construct the delegation prompt using the producer profile as system instructions. Direct the subagent to READ the blueprint from disk (do NOT inject blueprint content into the prompt — this avoids duplicating large files in both parent and subagent contexts). Only include non-test output files in the delegation.
 5. Spawn the producer as a Task subagent using the model declared in the producer profile.
 
 **Producer delegation format:**
@@ -174,25 +174,27 @@ When building on a branch, add to subagent prompts:
 
 ## STEP 5: THREE-LAYER REVIEW CHAIN
 
-After a producer completes each deliverable, execute all three review layers in sequence.
+After producers complete deliverables, execute all three review layers. **Batch deliverables from the same specialist** into a single review subagent (up to 3 deliverables per review — if a specialist has more than 3, split into multiple batches). This reduces subagent spawn overhead.
 
 ### Layer 1: Domain Specialist Review
 
 1. Identify the specialist that authored the blueprint (from blueprint YAML frontmatter `specialist` field).
-2. Load that specialist's profile from the registry (same scan order as producers: project → user → framework).
-3. Extract the Review Protocol section from the specialist profile body.
-4. Spawn a review subagent with adversarial framing. Use the `reviewer_model` declared in the specialist profile's YAML frontmatter.
+2. Locate that specialist's profile path in the registry (same scan order as producers: project → user → framework).
+3. Spawn a review subagent with adversarial framing. Use the `reviewer_model` declared in the specialist profile's YAML frontmatter. If this specialist produced multiple deliverables, include ALL of them (up to 3) in a single review subagent.
 
 **Specialist review delegation format:**
 ```
-You are a [specialist display_name] reviewing a deliverable produced from your blueprint. Your job is to FIND PROBLEMS — not to approve.
+You are a [specialist display_name] reviewing deliverables produced from your blueprint. Your job is to FIND PROBLEMS — not to approve.
 
-[Specialist Review Protocol section content]
+Read your review protocol from: [specialist profile path] — find the ## Review Protocol section.
 
 Blueprint: Read {context_path}/blueprints/{specialist-name}.md
-Deliverable: Read [produced output file paths]
+Deliverables: Read each of these files:
+- [produced output file path 1]
+- [produced output file path 2]
+- ...
 
-Does this deliverable accurately capture what the blueprint specified? Are the domain-specific requirements met? Check every review criterion. Return: PASS + summary OR FAIL + specific issues list with blueprint section references.
+For EACH deliverable: does it accurately capture what the blueprint specified? Are the domain-specific requirements met? Check every review criterion. Return per deliverable: PASS + summary OR FAIL + specific issues list with blueprint section references.
 ```
 
 - If FAIL → send feedback back to the producer (re-delegate with specific issues). Do NOT proceed to Layer 2.
@@ -222,14 +224,15 @@ Log all deviations (additions and omissions) in the build report's "Deviations f
 ### Layer 3: Mandatory Cross-Cutting Reviewers
 
 1. Check the specialist profile's `mandatory_reviewers` field in its YAML frontmatter.
-2. For EACH mandatory reviewer listed: load their specialist profile, extract their Review Protocol, spawn a review subagent using their `reviewer_model`.
+2. For EACH mandatory reviewer listed: locate their specialist profile, spawn a review subagent using their `reviewer_model`.
 3. **Security Expert is ALWAYS mandatory** — even if `mandatory_reviewers` is empty. Spawn a Security Expert review for every deliverable that produces code, configuration, or scripts.
+4. **Batch cross-cutting reviews** the same way as Layer 1: include up to 3 deliverables per review subagent. If all code deliverables in the current execution phase share the same cross-cutting reviewer, batch them into one review call.
 
 **Cross-cutting review delegation format:**
 ```
 You are a [reviewer display_name] performing a cross-cutting review. Your job is to FIND PROBLEMS in your area of expertise.
 
-[Reviewer's Review Protocol section content]
+Read your review protocol from: [reviewer profile path] — find the ## Review Protocol section.
 
 Deliverable: Read [produced output file paths]
 Blueprint: Read {context_path}/blueprints/{specialist-name}.md (for context only)
@@ -348,7 +351,7 @@ Present a concise version: task count, pass/fail status, files produced count, r
 
 After reporting results:
 
-**8a. Extract to memory.** Spawn a haiku Task subagent: "Read `{context_path}/build_report.md`. Then read `docs/project_notes/key_facts.md`, `docs/project_notes/issues.md`, and `docs/project_notes/bugs.md`. Append only NEW entries: lessons/deviations → `key_facts.md`, completed work → `issues.md`, bugs found → `bugs.md`. Do not duplicate. Preserve existing formatting." Run in background.
+**8a. Extract to memory (inline).** Review the build report you just wrote. For any notable deviations or lessons learned, read `docs/project_notes/key_facts.md` and use Edit to append concise entries (2-3 lines each) if not already present. For any bugs found during review cycles, read `docs/project_notes/bugs.md` and append. Do NOT spawn a subagent — write directly.
 
 **8b. Determine next phase.** Read `{context_path}/team_assignment.json`. Check if any `producer_assignments` entry has `producer == "code-writer"`.
 

package/skills/intuition-detail/SKILL.md

@@ -104,7 +104,7 @@ Ensure the `{context_path}/blueprints/` directory exists. After the subagent ret
 
 #### Stage 1a: Research Planning
 
-Spawn an opus Task subagent. The system prompt combines a research-planning framing (owned by this skill) with the specialist's domain expertise (from the profile):
+Spawn a sonnet Task subagent. The system prompt combines a research-planning framing (owned by this skill) with the specialist's domain expertise (from the profile):
 
 - **System prompt**: Construct by concatenating:
   1. **Framing (detail skill provides this):**
@@ -342,7 +342,9 @@ Spawn a FRESH opus Task subagent (do NOT resume Stage 1):
   - Full contents of `{context_path}/scratch/{specialist-name}-decisions.json`
   - Plan tasks with acceptance criteria
   - Prior blueprint contents (if any — read each path and include full text)
-- **Output instruction**: "Produce the complete blueprint in the universal envelope format (9 sections: Task Reference, Research Findings, Approach, Decisions Made, Deliverable Specification, Acceptance Mapping, Integration Points, Open Items, Producer Handoff). Write to `{context_path}/blueprints/{specialist-name}.md`. Every design choice must trace to Stage 1 research, a user decision from decisions.json, or a named domain standard. Ungrounded choices go in the Open Items section."
+- **Output instruction**: "Produce the complete blueprint in the universal envelope format (9 sections: Task Reference, Research Findings, Approach, Decisions Made, Deliverable Specification, Acceptance Mapping, Integration Points, Open Items, Producer Handoff). Write to `{context_path}/blueprints/{specialist-name}.md`. Every design choice must trace to Stage 1 research, a user decision from decisions.json, or a named domain standard. Ungrounded choices go in the Open Items section.
+
+     IMPORTANT — Testing boundary: Do NOT specify test files or test deliverables in Producer Handoff (Section 9). Testing is handled by a dedicated test phase, not by producers. If you have domain-specific testing knowledge (edge cases, critical paths, failure modes, boundary conditions), include it in the Approach section (Section 3) under a '### Testability Notes' subheading. This gives the test phase domain context without prescribing test files."
 
 Ensure the `{context_path}/blueprints/` directory exists (create via Bash `mkdir -p` if needed).
 
@@ -370,7 +372,9 @@ After a blueprint passes the traceability check:
 
 **8b. Update specialist state.** Read `.project-memory-state.json`. In `workflow.detail.specialists`, mark the completed specialist: `status → "completed"`, `stage → "done"`, `blueprint_path → "{context_path}/blueprints/{specialist-name}.md"`. Write back.
 
-**8c. Extract to memory.** Spawn a haiku Task subagent: "Read `{context_path}/blueprints/{specialist-name}.md`. Then read `docs/project_notes/decisions.md` and `docs/project_notes/key_facts.md`. Append only NEW entries: decisions from the blueprint's Decisions Made section → `decisions.md` as ADRs, domain facts from Research Findings → `key_facts.md`. Do not duplicate. Preserve existing formatting." Run in background.
+**8c. Extract to memory (inline).** Read the just-written blueprint's Decisions Made section (Section 4). For each decision, read `docs/project_notes/decisions.md` and use Edit to append a new ADR entry if one doesn't already exist. For key domain facts from the blueprint's Research Findings (Section 2), read `docs/project_notes/key_facts.md` and append if not present. Keep entries concise (2-3 lines each). Do NOT spawn a subagent — write directly.
+
+**8c-ii. Extract testability notes.** If the blueprint's Approach section (Section 3) contains a `### Testability Notes` subheading, extract its contents and append to `{context_path}/test_advisory.md` (create if it doesn't exist). Format: `## {Specialist Display Name}\n{testability notes content}\n`. This gives the test phase a compact file instead of needing to read all blueprints.
 
 **8d. Check for next specialist.** Read `{context_path}/team_assignment.json`. Read current state.
 

package/skills/intuition-outline/SKILL.md

@@ -97,6 +97,8 @@ From the prompt brief, extract: core problem, success criteria, stakeholders, co
 
 Create the directory `{context_path}/.outline_research/` if it does not exist.
 
+**Resume check:** If `{context_path}/.outline_research/orientation.md` already exists AND `{context_path}/.outline_research/decisions_log.md` exists with at least one entry, skip the research agents — read the existing orientation.md and proceed to Step 3. This avoids re-spending tokens on research that hasn't changed.
+
 Launch 2 sonnet research agents in parallel using the Task tool:
 
 **Agent 1 — Codebase Topology** (subagent_type: Explore, model: sonnet):
@@ -201,7 +203,7 @@ When actors are sufficiently mapped (user has confirmed or adjusted), transition
 Based on the scope revealed by the prompt brief and actors discussion, recommend a outline depth tier:
 
 - **Lightweight** (1-4 tasks): Focused scope, few unknowns. Outline includes: Objective, Discovery Summary, Task Sequence, Execution Notes.
-- **Standard** (5-10 tasks): Moderate complexity. Adds: Technology Decisions, Testing Strategy, Risks & Mitigations.
+- **Standard** (5-10 tasks): Moderate complexity. Adds: Technology Decisions, Risks & Mitigations.
 - **Comprehensive** (10+ tasks): Broad scope, multiple components. All sections including Component Architecture and Interface Contracts.
 
 Present your recommendation with reasoning via AskUserQuestion. Options: the three tiers (with your recommendation marked). The user may agree or pick a different tier.
@@ -354,7 +356,7 @@ After writing `outline.md`:
 
 **1. Update state:** Read `.project-memory-state.json`. Target the active context object (trunk or branch). Set: `status` → `"outline"`, `workflow.outline.completed` → `true`, `workflow.outline.completed_at` → current ISO timestamp, `workflow.outline.approved` → `true`. Set on root: `last_handoff` → current ISO timestamp, `last_handoff_transition` → `"outline_complete"`. Write back.
 
-**2. Extract to memory:** Spawn a haiku Task subagent (subagent_type: Explore): "Read `{context_path}/outline.md` and `{context_path}/.outline_research/decisions_log.md`. Then read `docs/project_notes/decisions.md` and `docs/project_notes/issues.md`. Append only NEW entries: architectural decisions → `decisions.md` as ADRs, risks and dependencies → `issues.md`. Do not duplicate existing entries. Preserve existing formatting." Run in background — do not wait for completion.
+**2. Extract to memory (inline).** Read `{context_path}/.outline_research/decisions_log.md`. For each locked decision, read `docs/project_notes/decisions.md` and use Edit to append a new ADR entry if one doesn't already exist for that decision. For each risk identified during dialogue, read `docs/project_notes/issues.md` and use Edit to append if not already present. Keep entries concise (2-3 lines each). Do NOT spawn a subagent for this — write directly.
 
 **3. Fast Track Assessment (v9 only):**
 
@@ -405,8 +407,8 @@ If fast track declined OR conditions not met, continue to step 4.
 ## Scope Scaling
 
 - **Lightweight**: Sections 1, 2, 6, 6.5, 10
-- **Standard**: Sections 1, 2, 3, 6, 6.5, 7, 8, 10
-- **Comprehensive**: All sections (1-10, including 6.5)
+- **Standard**: Sections 1, 2, 3, 6, 6.5, 8, 10
+- **Comprehensive**: All sections (1-6.5, 8-10)
 
 Section 6.5 (Detail Assessment) is ALWAYS included regardless of tier.
 Section 2.5 is Parent Context — included for ALL tiers when on a branch.
@@ -482,8 +484,7 @@ Depth controls specialist invocation:
 
 **Acceptance criteria rule:** If a criterion can only be satisfied ONE way, it is over-specified. Criteria describe outcomes ("users can reset passwords via email"), not implementations ("add a resetPassword() method that calls sendEmail()"). The engineer and build phases decide the code-level HOW.
 
-### 7. Testing Strategy (Standard+, when code is produced)
-Test types required. Which tasks need tests (reference task numbers). Critical test scenarios. Infrastructure needed.
+**No test tasks.** Do NOT create tasks for writing tests (e.g., "Write unit tests for the API layer"). Testing is a dedicated phase (`/intuition-test`), not a task. The test phase discovers infrastructure, designs strategy, and creates tests independently. Outline tasks describe what gets built — verification is the test phase's job.
 
 ### 8. Risks & Mitigations (Standard+)
 

package/skills/intuition-test/SKILL.md

@@ -24,6 +24,7 @@ These are non-negotiable. Violating any of these means the protocol has failed.
 8. You MUST write `{context_path}/test_report.md` before routing to handoff.
 9. You MUST run the Exit Protocol after writing the test report. NEVER route to `/intuition-handoff`.
 10. You MUST update `.project-memory-state.json` as part of the Exit Protocol.
+11. You MUST NOT use `run_in_background` for subagents in Steps 2 and 5. All research and test-creation agents MUST complete before their next step begins.
 
 ## CONTEXT PATH RESOLUTION
 
@@ -63,11 +64,11 @@ Check for existing artifacts before starting. Use `{context_path}/scratch/test_s
 Read these files:
 
 1. `{context_path}/build_report.md` — REQUIRED. Extract: files modified, task results, deviations from blueprints, decision compliance notes.
-3. `{context_path}/outline.md` — acceptance criteria per task.
-4. ALL files matching `{context_path}/blueprints/*.md` — specialist blueprints with deliverable specifications.
-5. `{context_path}/team_assignment.json` — producer assignments (identify code-writer tasks).
-6. ALL files matching `{context_path}/scratch/*-decisions.json` — decision tiers and chosen options per specialist.
-7. `docs/project_notes/decisions.md` — project-level ADRs.
+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.
+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.
 
 From build_report.md, extract:
 - **Files modified** — the scope boundary for testing and fixes
@@ -76,10 +77,9 @@ From build_report.md, extract:
 - **Decision compliance** — any flagged decision issues
 - **Test Deliverables Deferred** — test specs/files that specialists recommended but build skipped (if this section exists)
 
-From blueprints, extract any test recommendations:
-- Test cases specialists suggested in their blueprints
-- Edge cases or coverage areas they flagged
-- Test-related deliverables from Producer Handoff sections
+From test_advisory.md (or blueprints as fallback), extract domain test knowledge:
+- Edge cases, critical paths, failure modes, and boundary conditions flagged by specialists
+- Any test-relevant domain insights
 
 From decisions files, build a decision index:
 - Map each `[USER]` decision to its chosen option
@@ -88,7 +88,7 @@ From decisions files, build a decision index:
 
 ## STEP 2: RESEARCH (2 Parallel Haiku Explore Agents)
 
-Spawn two haiku Explore agents in parallel (both Task calls in a single response):
+Spawn two haiku Explore agents in parallel (both Task calls in a single response). Do NOT use `run_in_background` — you MUST wait for both agents to return before proceeding to Step 3:
 
 **Agent 1 — Test Infrastructure:**
 "Search the project for test infrastructure. Find: test framework and runner (jest, vitest, mocha, pytest, etc.), test configuration files, existing test directories and naming conventions, mock/fixture patterns, test utility helpers, CI test commands, coverage configuration and thresholds. Report exact paths and configuration values."
@@ -157,11 +157,11 @@ Tests that only exercise isolated helper functions satisfy unit coverage but do
 
 ### Specialist Test Recommendations
 
-Before finalizing the test plan, review specialist test recommendations from two sources:
-- **Blueprint test recommendations**: Test cases, edge cases, and coverage areas that specialists flagged in their blueprints
-- **Deferred test deliverables**: Test specs/files from build_report.md's "Test Deliverables Deferred" section (and/or test_brief.md's "Specialist Test Recommendations" section)
+Before finalizing the test plan, review specialist domain knowledge from blueprints:
+- **Testability Notes**: Edge cases, critical paths, failure modes, and boundary conditions from each blueprint's Approach section (Section 3, `### Testability Notes` subheading)
+- **Deferred test deliverables**: Any test specs from build_report.md's "Test Deliverables Deferred" section (legacy — older blueprints may still include test files in Producer Handoff)
 
-Specialists have domain expertise about what should be tested. Incorporate relevant recommendations into your test plan, but you are not bound to follow them exactly. You own the test strategy — use specialist input as advisory, not prescriptive.
+Specialists have domain expertise about what should be tested. Incorporate their testability insights into your test plan, but you own the test strategy — use specialist input as advisory, not prescriptive.
 
 ### Output
 
@@ -203,7 +203,7 @@ Options:
 
 ## STEP 5: CREATE TESTS
 
-Delegate test creation to sonnet Task subagents. Parallelize independent test files (multiple Task calls in a single response).
+Delegate test creation to sonnet Task subagents. Parallelize independent test files (multiple Task calls in a single response). Do NOT use `run_in_background` — you MUST wait for ALL subagents to return before proceeding to Step 6.
 
 For each test file, spawn a sonnet subagent:
 
@@ -224,7 +224,7 @@ You are a test writer. Create a test file following these specifications exactly
 Write the complete test file to the specified path. Follow the project's existing test style exactly. Do NOT add test infrastructure (no new packages, no config changes).
 ```
 
-After all subagents return, verify each test file was written. If any failed, retry once with error context.
+SYNCHRONIZATION GATE: After all subagents return, verify each test file exists on disk using Glob. If any file is missing, retry that subagent once (foreground) with error context. Do NOT proceed to Step 6 until every planned test file is confirmed on disk.
 
 ## STEP 6: RUN TESTS + FIX CYCLE
 
@@ -327,7 +327,7 @@ Write `{context_path}/test_report.md`:
 
 ## STEP 8: EXIT PROTOCOL
 
-**8a. Extract to memory.** Spawn a haiku Task subagent: "Read `{context_path}/test_report.md`. Then read `docs/project_notes/key_facts.md`, `docs/project_notes/issues.md`, and `docs/project_notes/bugs.md`. Append only NEW entries: test coverage insights → `key_facts.md`, implementation fixes → `bugs.md`, escalated issues → `issues.md`. Do not duplicate. Preserve existing formatting." Run in background.
+**8a. Extract to memory (inline).** Review the test report you just wrote. For test coverage insights, read `docs/project_notes/key_facts.md` and use Edit to append concise entries (2-3 lines each) if not already present. For implementation fixes applied, read `docs/project_notes/bugs.md` and append. For escalated issues, read `docs/project_notes/issues.md` and append. Do NOT spawn a subagent — write directly.
 
 **8b. Update state.** Read `.project-memory-state.json`. Target active context. Set: `status` → `"complete"`, `workflow.test.completed` → `true`, `workflow.test.completed_at` → current ISO timestamp, `workflow.build.completed` → `true`, `workflow.build.completed_at` → current ISO timestamp (if not already set). Set on root: `last_handoff` → current ISO timestamp, `last_handoff_transition` → `"test_to_complete"`. Write back.