feature: create plan-builder-agent skill, delete delegate-agent, fix invocation workflow

Author: cowwoc

.claude/cat/issues/v2/v2.1/extract-shared-planning-approach/STATE.md

@@ -1,7 +1,9 @@
 # State
 
-- **Status:** in-progress
-- **Progress:** 0%
+- **Status:** closed
+- **Progress:** 100%
 - **Dependencies:** []
 - **Blocks:** []
 - **Target Branch:** v2.1
+- **Last Updated:** 2026-03-07
+- **Completed Waves:** Wave 1, Wave 2

client/src/main/java/io/github/cowwoc/cat/hooks/util/IssueCreator.java

@@ -70,18 +70,27 @@ public String execute(String jsonInput, Path workingDirectory) throws IOExceptio
       throw new IOException("Input must be a JSON object, got: " + parsedNode.getNodeType());
     ObjectNode data = (ObjectNode) parsedNode;
 
-    String[] required = {"major", "minor", "issue_name", "state_content", "plan_content"};
+    String[] required = {"major", "minor", "issue_name", "state_content"};
     for (String field : required)
     {
       if (!data.has(field))
         throw new IOException("Missing required field: " + field);
     }
+    if (!data.has("plan_content") && !data.has("plan_file"))
+      throw new IOException("Missing required field: plan_content or plan_file (provide one)");
 
     int major = data.get("major").asInt();
     int minor = data.get("minor").asInt();
     String issueName = data.get("issue_name").asString();
     String stateContent = data.get("state_content").asString();
-    String planContent = data.get("plan_content").asString();
+    String planContent;
+    if (data.has("plan_file"))
+    {
+      Path planSourceFile = Path.of(data.get("plan_file").asString());
+      planContent = Files.readString(planSourceFile, StandardCharsets.UTF_8);
+    }
+    else
+      planContent = data.get("plan_content").asString();
     String commitDesc;
     if (data.has("commit_description"))
       commitDesc = data.get("commit_description").asString();

plugin/concepts/subagent-delegation.md

@@ -57,6 +57,68 @@ TaskCreate:
   description: "..."
 ```
 
+## Model Selection for Subagents
+
+**MANDATORY: Always specify a model explicitly. Never use the default.**
+
+Choose the model based on issue complexity:
+
+| Issue Type | Model | Reasoning |
+|-----------|-------|-----------|
+| Skill invocation (orchestration only) | `haiku` | Skill is pure orchestration, subagent just runs it |
+| Skill invocation (skill exposes algorithm) | `sonnet` | Skill doc shows HOW to do it; haiku will apply algorithm manually |
+| Simple file operations | `haiku` | Explicit instructions, no reasoning needed |
+| Run commands, check output | `haiku` | Purely mechanical execution |
+| Code refactoring | `sonnet` | Requires understanding patterns and context |
+| Multi-file changes | `sonnet` | Needs to maintain consistency across files |
+| Exploration/research | `sonnet` | Requires judgment about what's relevant |
+| Complex logic changes | `sonnet` | Must reason about correctness |
+| Critical validation gates | `opus` | Asymmetric failure costs justify higher accuracy |
+
+**Decision rule:** If the execution plan can be followed with zero reasoning (copy-paste level
+explicit), use `haiku`. If the subagent needs to understand WHY to do something correctly,
+use `sonnet`. If failure would be very costly or the task requires generating novel approaches,
+consider `opus`.
+
+### When to Use Opus (Rare Cases)
+
+**Opus is the exception, not the default.** Most delegated work should use haiku or sonnet.
+
+Use Opus only when:
+
+1. **Critical validation gates** - When the cost of a false positive (incorrectly passing) is much
+   higher than the cost of running a more capable model. Examples:
+   - Security review of authentication changes
+   - Validating semantic equivalence of compressed documentation
+   - Final quality gate before production deployment
+
+2. **Complex architectural analysis** - Evaluating tradeoffs across multiple systems, identifying
+   non-obvious dependencies, or reasoning about emergent behavior.
+
+**Signal to reconsider delegation:** If you find yourself reaching for Opus, ask whether this work
+should be delegated at all. Work requiring Opus-level reasoning often benefits from:
+- Main agent handling it directly (with user oversight)
+- Breaking into smaller pieces that sonnet can handle
+- More explicit specifications that reduce reasoning requirements
+
+**Anti-pattern:**
+```
+❌ model: "opus" for mechanical file operations (wasteful)
+❌ model: "opus" for straightforward code changes (sonnet suffices)
+❌ model: "opus" as a "just to be safe" default (defeats cost efficiency)
+✅ model: "opus" for security-critical validation gates
+```
+
+**Anti-pattern:**
+```
+❌ Task tool: subagent_type: "general-purpose" (missing model - uses expensive default)
+❌ Task tool: model: "haiku" for code refactoring (will likely fail)
+❌ Task tool: model: "haiku" for "/cat:optimize-doc file.md" (skill exposes algorithm)
+✅ Task tool: model: "sonnet" for "/cat:optimize-doc file.md" (skill doc shows HOW, needs reasoning)
+✅ Task tool: model: "sonnet" for "refactor these 4 handlers" (needs reasoning)
+✅ Task tool: model: "haiku" for "/cat:status" (pure orchestration, no algorithm exposed)
+```
+
 ## Core Constraint
 
 **Claude Code does not allow users to supervise subagent execution.**

plugin/skills/add/first-use.md

@@ -818,116 +818,35 @@ Use appropriate template format:
 - **Blocks:** []
 ```
 
-**Generate PLAN.md content based on issue type:**
+**Generate PLAN.md via plan-builder-agent:**
 
-Use appropriate template (Feature, Bugfix, or Refactor) from issue-plan.md reference.
+Invoke the plan-builder-agent skill to generate the PLAN.md. This centralizes all planning logic (effort-based depth,
+comprehensiveness requirements, sub-agent waves, templates) in one place.
 
-**CRITICAL:** Follow template guidance to separate Sub-Agent Waves/Steps (actions only) from Success Criteria
-(measurable outcomes). Do NOT include expected values like "score = 1.0" in Execution sections as this primes subagents
-to fabricate
-results.
+1. Write a temporary context file with the issue details:
 
-**PLAN.md Comprehensiveness:** The PLAN.md must be comprehensive enough for a haiku-level
-model to implement mechanically without making architectural decisions. Include:
-- Exact file paths to create/modify
-- Specific code patterns or formats to use
-- Complete lists (all files, all references to update, all post-conditions)
-- Research findings that inform implementation decisions
-
-If the execution subagent needs to make judgment calls about "how" to implement, the PLAN.md
-is not detailed enough. The subagent should only decide "how to write the code", not "what approach to take".
-
-**Effort-Based Planning Depth:**
-
-Use the EFFORT value set in issue_read_config to calibrate planning thoroughness.
-
-Apply the following depth to PLAN.md content based on `$EFFORT`:
-
-- `low`: Generate a concise plan. Assume the obvious approach. Skip alternative analysis. List only essential steps
-  and post-conditions.
-- `medium`: Explore two or three alternative approaches before settling on one. Note key trade-offs in a brief
-  section. Execution steps should cover non-obvious edge cases.
-- `high`: Perform deep research on the problem space. Document the reasoning for the chosen approach and explicitly
-  list rejected alternatives with rationale. Execution steps must cover all known edge cases and failure modes.
-
-**Batch Execution Check:** When the issue involves multiple files AND a skill (e.g., compress 9 files with
-/cat:optimize-doc-agent):
-1. Read the target skill's documentation for batch/parallel execution patterns
-2. If the skill documents using `/cat:delegate-agent` for multiple files, write execution steps to use delegate
-3. Example: Instead of "For each file: Run /cat:optimize-doc-agent", use "/cat:delegate-agent --skill optimize-doc-agent file1.md file2.md
-   ..."
-
-This ensures batch tasks leverage parallel execution rather than sequential processing.
-
-**Sub-Agent Waves for Parallel Execution:** When the issue has clearly independent work that can run simultaneously,
-use `## Sub-Agent Waves` with `### Wave N` sections to enable parallel subagent spawning. Use sparingly — only when
-items genuinely don't depend on each other and won't modify the same files.
-
-Rules for sub-agent waves:
-- Create `## Sub-Agent Waves` section (replaces `## Execution Steps`)
-- Each `### Wave N` subsection contains bullet items for parallel execution
-- Waves execute sequentially (Wave 1 completes before Wave 2 starts)
-- All items within a wave run in parallel
-- Waves must not modify the same files (to avoid merge conflicts)
-- The last wave is responsible for updating STATE.md
-
-**Main Agent Waves (optional):** If the issue requires skills that spawn their own subagents (e.g.,
-`/cat:optimize-doc`, `/cat:compare-docs`, `/cat:stakeholder-review-agent`), add a `## Main Agent Waves` section
-**above** `## Sub-Agent Waves`. The main agent executes these skills directly before spawning implementation
-subagents. Each bullet is a skill invocation:
-
-```markdown
-## Main Agent Waves
-
-- /cat:optimize-doc path/to/file.md
-```
-
-Omit `## Main Agent Waves` entirely when the issue has no pre-delegation skills.
-
-Example valid sub-agent wave structure (independent modules):
-
-```markdown
-## Sub-Agent Waves
-
-### Wave 1
-- Implement parser module
-- Add parser tests
-
-### Wave 2
-- Implement formatter module
-- Add formatter tests
-- Run full test suite
+```bash
+PLAN_CONTEXT="/tmp/plan-context-${ISSUE_NAME}.json"
+cat > "$PLAN_CONTEXT" << EOF
+{
+  "issue_type": "${ISSUE_TYPE}",
+  "description": "${ISSUE_DESCRIPTION}",
+  "postconditions": ${POSTCONDITIONS_JSON},
+  "research_findings": "${RESEARCH_FINDINGS:-}",
+  "impact_notes": "${IMPACT_NOTES:-}"
+}
+EOF
 ```
 
-Do NOT use multiple waves if items share files or if the sequential dependency is unclear. In such cases, use a single
-`## Sub-Agent Waves` / `### Wave 1` section or revert to `## Execution Steps` for sequential execution.
-
-**If RESEARCH_FINDINGS exists:**
-
-Add a Research Findings section to PLAN.md after the Goal/Problem section:
+2. Invoke plan-builder-agent:
 
-```markdown
-## Research Findings
-{RESEARCH_FINDINGS}
 ```
-
-This section should appear before the "Parent Requirements" section in all templates.
-
-**If IMPACT_NOTES is non-empty:**
-
-Add an Impact Notes section to PLAN.md after the Research Findings section (or after the Goal/Problem section if no
-Research Findings):
-
-```markdown
-## Impact Notes
-{IMPACT_NOTES}
+Skill tool:
+  skill: "cat:plan-builder-agent"
+  args: "${CAT_AGENT_ID} ${EFFORT} initial ${PLAN_CONTEXT}"
 ```
 
-This section documents the potential impact of this issue on existing features, identified during issue creation.
-
-**After generating STATE.md and PLAN.md content, create the issue:**
-
-Call the create-issue binary with JSON input:
+3. Create the issue, passing the generated PLAN.md file path:
 
 ```bash
 "${CLAUDE_PLUGIN_ROOT}/client/bin/create-issue" --json '{
@@ -937,7 +856,7 @@ Call the create-issue binary with JSON input:
   "issue_type": "{issue-type}",
   "dependencies": ["{dep1}", "{dep2}"],
   "state_content": "{full STATE.md content}",
-  "plan_content": "{full PLAN.md content}",
+  "plan_file": "'"${PLAN_CONTEXT%.json}.plan.md"'",
   "commit_description": "{one-line description}"
 }'
 ```

plugin/skills/consolidate-doc-agent/first-use.md

@@ -248,7 +248,7 @@ Extracted **56 semantic units** from original document, categorized as:
 
 | Category | Count | Examples |
 |----------|-------|----------|
-| REQUIREMENT | 18 | Main agent only, report validation status, use delegate-agent |
+| REQUIREMENT | 18 | Main agent only, report validation status, spawn parallel subagents |
 | PROHIBITION | 8 | Never manually compress, cannot invoke from subagent |
 | SEQUENCE | 10 | Check baseline, save original, validate, iterate |
 | CONDITIONAL | 8 | If EQUIVALENT then approve, if NOT_EQUIVALENT then iterate |
@@ -302,7 +302,7 @@ GOAL: Complete compression with validation and optional iteration
    - **Missing from consolidated**: Validation Context explanation, exact decision logic algorithm,
      "don't ask user if ITERATE" requirement
 7. **Step 6: Iteration Loop** (u32-u37, u49-u50): Re-invoke with feedback, self-check, max 3 attempts
-8. **Step 7: Multiple Files** (u38-u40): Batch processing via delegate-agent
+8. **Step 7: Multiple Files** (u38-u40): Batch processing via parallel subagents
 9. **Supporting Details**: References (u44-u46), **u55-u56 missing** (File Operations, Rollback)
 
 ---