Launch subagent with task context in isolated worktree with token tracking
Launches subagent in isolated worktree to execute predefined tasks with token tracking.
/plugin marketplace add cowwoc/claude-code-cat/plugin install cat@claude-code-catThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Launch a Claude Code subagent in an isolated git worktree to execute a specific task. The subagent operates independently with its own context window while the parent agent continues coordinating.
Subagents run without user supervision. Claude Code does not provide a way for users to view subagent output while it runs. Users cannot:
All decision-making MUST happen in the main agent before spawning. The subagent prompt must be comprehensive enough that execution is purely mechanical - following explicit instructions without judgment calls.
Subagents inherit project hooks automatically when running in the same project directory. However, subagents may not follow hook guidance if not explicitly reminded.
MANDATORY: Include key requirements in subagent prompt:
CRITICAL REQUIREMENTS (enforced by hooks):
- Always decompose code instead of adding PMD suppression annotations
- Always use git merge --ff-only for linear history
- Always use git-filter-repo instead of git filter-branch
- Preserve .git/refs/original unless user explicitly requests deletion
- Include tests for bugfixes in the SAME commit as the fix
COMMIT SEPARATION (M089):
- .claude/rules/ updates → separate config: commit (not bundled with bugfix/feature)
- STATE.md updates → same commit as implementation (M076/M077)
These are ABSOLUTE rules. Violation will be detected and blocked.
Why explicit in prompt: Hooks can block commands, but subagents may try alternatives. Stating prohibitions in the prompt prevents wasted effort on blocked approaches.
Planning Subagent (two stages for token efficiency):
| Stage | Purpose | Output | Tokens |
|---|---|---|---|
| Stage 1 | High-level approach outlines | 3 brief options + agent_id | ~5K |
| Stage 2 | Detailed implementation spec | Full PLAN.md for selected approach | ~20K |
Stage 1 prompt template:
Analyze the task and produce HIGH-LEVEL outlines (1-2 sentences each) for:
- Conservative approach: [minimal scope, low risk]
- Balanced approach: [moderate scope, medium risk]
- Aggressive approach: [comprehensive, high risk]
Do NOT produce detailed execution steps yet. Keep outlines brief.
Return your agent_id for later resumption.
Stage 2 prompt (using Task tool with resume parameter):
resume: {agent_id from Stage 1}
prompt: "User selected [approach]. Now produce the DETAILED spec with:
- Specific files to modify
- Exact code changes
- Step-by-step execution
- Verification commands"
Implementation Subagent: Receives completed PLAN.md, executes mechanically.
This skill respects task-level locking. Before spawning, verify the parent agent holds the task lock.
The lock should have been acquired by /cat:work. Subagents inherit lock ownership through
their worktree association (recorded in the lock file).
MANDATORY: Verify Lock Ownership (M082)
After any lock acquisition attempt, verify ownership by reading the actual lock file:
TASK_ID="${MAJOR}.${MINOR}-${TASK_NAME}"
LOCK_FILE="${CLAUDE_PROJECT_DIR}/.claude/cat/locks/${TASK_ID}.lock"
# Verify lock file exists and we own it
if [[ ! -f "$LOCK_FILE" ]]; then
echo "ERROR: Lock file does not exist at $LOCK_FILE"
echo "Lock was NOT acquired. Another session may own this task."
exit 1
fi
# Verify session_id matches current session
LOCK_SESSION=$(grep "^session_id=" "$LOCK_FILE" | cut -d= -f2)
if [[ "$LOCK_SESSION" != "$SESSION_ID" ]]; then
echo "ERROR: Lock owned by different session: $LOCK_SESSION"
echo "Current session: $SESSION_ID"
echo "Do NOT proceed - another Claude instance is working on this task."
exit 1
fi
echo "Lock verified: $LOCK_FILE owned by current session"
Anti-pattern (M082): Trusting lock script return value without verifying the actual lock file.
Lock directory must be .claude/cat/locks/ (NOT /tmp/cat-locks/ or other paths).
After session restart (M083): Re-run lock verification commands. Always re-verify state after restart - the filesystem may have changed while the session was inactive.
MANDATORY: Before spawning, ensure the prompt contains everything needed for mechanical execution.
| Element | Why Required |
|---|---|
| Clear task type | "Explore and report" OR "Execute these steps" - never both |
| Fail-fast conditions | When to stop and report BLOCKED |
| Exact file paths | For implementation tasks |
| Specific code changes | Before/after examples, not descriptions |
| Test verification steps | Explicit commands to run, expected outcomes |
| Edge cases to handle | Subagent won't discover these independently |
| Commit message format | Exact text, not guidelines |
| STATE.md update | Task STATE.md must be updated to completed IN THE SAME COMMIT |
CRITICAL: Every prompt must include fail-fast conditions.
# Always include:
FAIL-FAST CONDITIONS:
- If [specific condition], report "BLOCKED: [reason]" and stop
- Report status and return to main agent for decisions
- Main agent handles all workarounds and fallback choices
Subagents use fail-fast behavior: report BLOCKED and stop. Fallback decisions require user oversight.
Before spawning, verify your prompt answers:
CRITICAL: Cross-reference recent learnings before spawning.
Every subagent prompt MUST include these items based on past mistakes:
STATE.md Requirements (M076, M077, M085, M087, M092):
STATE.md UPDATE (required in SAME commit as implementation):
- Path: .claude/cat/v{major}/v{major}.{minor}/{task-name}/STATE.md
- Set: Status: completed
- Set: Progress: 100%
- Set: Resolution: implemented (MANDATORY - not optional)
- Set: Completed: {YYYY-MM-DD HH:MM}
- Set: Tokens Used: {tokensUsed from .completion.json}
- Include STATE.md in git add before commit
Trust Setting (from cat-config.json trust preference, for PLANNING subagents):
TRUST_PREF=$(jq -r '.trust // "medium"' .claude/cat/cat-config.json)
| Value | Include in Planning Prompt |
|---|---|
short | "Present multiple options for the user to choose from. Include conservative, balanced, and comprehensive approaches." |
medium | "Present options for meaningful trade-offs. For routine decisions, proceed with the balanced approach." |
long | "Make autonomous decisions. Only present options when the choice has significant architectural implications." |
Curiosity Setting (from cat-config.json curiosity preference, for IMPLEMENTATION subagents):
CURIOSITY_PREF=$(jq -r '.curiosity // "low"' .claude/cat/cat-config.json)
| Value | Include in Implementation Prompt |
|---|---|
low | "Focus ONLY on the assigned task. Report only task-related issues." |
medium | "While working, NOTE obvious issues in files you touch (same function/class). Report them in .completion.json. Fixing is handled by main agent." |
high | "Actively look for code quality issues, patterns, and improvement opportunities in files you touch. Report ALL findings in .completion.json. Fixing is handled by main agent." |
IMPORTANT: The implementor subagent reports discovered issues in .completion.json. Main agent
handles fixes based on the patience setting.
Patience Setting — Main Agent Uses This (NOT passed to subagent):
The patience setting determines what the MAIN AGENT does with issues returned from subagents. Do NOT include patience instructions in implementation subagent prompts.
| Value | Main Agent Action on Returned Issues |
|---|---|
low | Resume PLANNER subagent to update plan with fixes, then continue execution |
medium | Create tasks for discovered issues in CURRENT version backlog |
high | Create tasks for discovered issues in FUTURE version backlog (prioritized by benefit/cost) |
Issues Return Format (subagent writes to .completion.json):
{
"status": "success",
"tokensUsed": 65000,
"inputTokens": 45000,
"outputTokens": 20000,
"compactionEvents": 0,
"summary": "Implemented parser with full test coverage",
"discoveredIssues": [
{
"file": "src/parser/Lexer.java",
"line": 142,
"type": "code-quality",
"severity": "medium",
"description": "Duplicate token validation logic could be extracted",
"benefitCost": 2.5
}
]
}
discoveredIssues: Only populated if curiosity is medium or high. Empty array if curiosity is low.
Parser Test Requirements (M079, for parser tasks only):
PARSER TEST STYLE:
- Use text blocks which are self-documenting (skip position comments)
- Use isEqualTo(expected) for assertions
- Derive expected values manually from source analysis
Code Style Requirements:
CODE STYLE:
- Decompose code instead of adding @SuppressWarnings annotations
- Rethrow caught exceptions as AssertionError (ensure visibility)
- Include tests for bugfixes in the SAME commit as the fix
Token Tracking Requirements (A017 - CRITICAL):
MAIN AGENT MUST include session ID in prompt - subagents cannot measure tokens without it.
Include this block in EVERY subagent prompt:
TOKEN MEASUREMENT (required):
Session ID: {paste actual session ID from your CAT SESSION INSTRUCTIONS}
Session file: /home/node/.config/claude/projects/-workspace/{SESSION_ID}.jsonl
On completion, measure tokens:
TOKENS=$(jq -s '[.[] | select(.type == "assistant") | .message.usage |
select(. != null) | (.input_tokens + .output_tokens)] | add // 0' "$SESSION_FILE")
Why explicit session ID? Subagents don't receive CAT SESSION INSTRUCTIONS automatically. Without the session ID, token measurement fails and reports show "NOT MEASURED" (M099, M109, M123).
Token tracking requirements:
On completion, write .completion.json with cumulative totals:
{
"status": "success|partial|failed",
"tokensUsed": {CUMULATIVE_TOTAL},
"inputTokens": {CUMULATIVE_INPUT},
"outputTokens": {CUMULATIVE_OUTPUT},
"compactionEvents": {COUNT},
"summary": "..."
}
If compaction occurred, the pre-compaction tokens are NOT lost - they must be preserved and added to post-compaction usage for accurate reporting.
Context Limit Enforcement (A018):
MANDATORY: Validate task size BEFORE spawning subagent.
# Values from agent-architecture.md § Context Limit Constants
CONTEXT_LIMIT=...
SOFT_TARGET_PCT=...
HARD_LIMIT_PCT=...
SOFT_TARGET=$((CONTEXT_LIMIT * SOFT_TARGET_PCT / 100))
HARD_LIMIT=$((CONTEXT_LIMIT * HARD_LIMIT_PCT / 100))
Limit Hierarchy:
| Limit | Percentage | Tokens (200K) | Purpose |
|---|---|---|---|
| Soft target | 40% | 80,000 | Recommended task size for optimal quality |
| Hard limit | 80% | 160,000 | Maximum allowed - MANDATORY decomposition above this |
| Context limit | 100% | 200,000 | Absolute ceiling - compaction occurs |
Pre-Spawn Validation Requirement:
BEFORE spawning ANY subagent, the main agent MUST:
# Pre-spawn validation
# Values from agent-architecture.md § Context Limit Constants
CONTEXT_LIMIT=...
HARD_LIMIT_PCT=...
HARD_LIMIT=$((CONTEXT_LIMIT * HARD_LIMIT_PCT / 100))
SOFT_TARGET=$((CONTEXT_LIMIT * 40 / 100))
if [ "${ESTIMATED_TOKENS}" -ge "${HARD_LIMIT}" ]; then
echo "ERROR: Task estimate (${ESTIMATED_TOKENS}) exceeds hard limit (${HARD_LIMIT})"
echo "MANDATORY: Decompose task before spawning. Use /cat:decompose-task"
exit 1
fi
Post-Execution Limit Check:
After subagent completes (in collect_results), verify actual usage:
ACTUAL_TOKENS={from .completion.json}
if [ "${ACTUAL_TOKENS}" -ge "${HARD_LIMIT}" ]; then
echo "EXCEEDED: Subagent used ${ACTUAL_TOKENS} tokens (hard limit: ${HARD_LIMIT})"
# Trigger learn-from-mistakes with A018 reference
fi
Verification:
Before invoking Task tool, confirm:
| Checklist Item | Required For | Mistake Ref |
|---|---|---|
| STATE.md path specified | All implementation tasks | M076, M085 |
| Resolution field mentioned | All implementation tasks | M092 |
| CRITICAL PROHIBITIONS block | All tasks | A008 |
| Parser test style notes | Parser tasks | M079 |
| Exact code examples | Non-trivial changes | M062 |
| Fail-fast conditions | All tasks | spawn-subagent core |
| Session ID in prompt | All tasks | A017, M099, M109, M123 |
| Token measurement instructions | All tasks | spawn-subagent core |
| Pre-spawn limit validation | All tasks | A018 |
Anti-pattern: Spawning subagent without reviewing this checklist against your prompt.
❌ WRONG (explores AND decides):
Find the best place to add caching and implement it.
✅ CORRECT (explores, returns findings):
Find all database query methods in src/repository/.
Return for each method:
- File path and line number
- Method signature
- Estimated call frequency (from usages)
- Current caching status (none/exists)
FAIL-FAST:
- If src/repository/ doesn't exist, report BLOCKED
- If no query methods found in 10 minutes, report BLOCKED
- Do NOT implement caching - return findings only
❌ WRONG (requires decisions):
Implement the Parser class following PLAN.md.
Add appropriate error handling.
Write tests for the main functionality.
✅ CORRECT (mechanical execution):
Create src/parser/Parser.java with this implementation:
[Full code listing with all methods]
Create test/parser/ParserTest.java:
[Full test code with expected values]
Verification:
1. Run: ./gradlew test --tests ParserTest
2. Expected: BUILD SUCCESSFUL, 5 tests passed
FAIL-FAST:
- If tests fail, report BLOCKED with failure output
- Do NOT modify code to fix failures - report and stop
Commit:
message: "feature: add Parser class for token processing"
files: src/parser/Parser.java, test/parser/ParserTest.java
Progress Output (MANDATORY):
Display spawning progress using visible feedback symbols:
At spawn start:
◆ Spawning subagent: {task-id}...
→ Worktree: {worktree-path}
→ Branch: {branch-name}
On successful launch:
✓ Subagent launched: {subagent-id}
→ Session: {session-id}
→ Estimated tokens: {N}K
On failure:
✗ Spawn failed: {error-reason}
→ {specific error details}
These symbols match the phase-based progress format used in /cat:work.
# Generate UUID for uniqueness
UUID=$(uuidgen | cut -c1-8)
# Construct names from task context
# Format: {major}.{minor}-{task-name}-sub-{uuid}
WORKTREE_NAME="1.2-implement-parser-sub-a1b2c3d4"
BRANCH_NAME="1.2-implement-parser-sub-a1b2c3d4"
# Create worktree directory
WORKTREE_PATH=".worktrees/${WORKTREE_NAME}"
# Verify task lock is held (should be acquired by work)
TASK_ID="${MAJOR}.${MINOR}-${TASK_NAME}"
LOCK_STATUS=$("${CLAUDE_PLUGIN_ROOT}/scripts/task-lock.sh" check "$TASK_ID" 2>/dev/null || echo '{}')
if ! echo "$LOCK_STATUS" | jq -e '.locked == true' > /dev/null 2>&1; then
echo "WARNING: Task lock not held. Acquire lock via work first."
fi
# Create branch and worktree together
git worktree add -b "${BRANCH_NAME}" "${WORKTREE_PATH}" HEAD
Copy or reference the task's PLAN.md that the subagent will execute:
# Ensure PLAN.md exists in task directory
TASK_PLAN=".claude/cat/tasks/${MAJOR}.${MINOR}-${TASK_NAME}/PLAN.md"
# Subagent will read this directly - no copy needed
Create session tracking files:
# Write session ID to worktree for monitoring script
echo "${CLAUDE_SESSION_ID}" > "${WORKTREE_PATH}/.session_id"
# Session file location (for reference)
SESSION_FILE="/home/node/.config/claude/projects/-workspace/${CLAUDE_SESSION_ID}.jsonl"
Use the Task tool to spawn subagents - do NOT use raw CLI commands:
Task tool invocation:
description: "Execute parser task"
subagent_type: "general-purpose"
model: "haiku"
prompt: |
Execute PLAN.md at ${TASK_PLAN}.
WORKING DIRECTORY: ${WORKTREE_PATH}
CRITICAL REQUIREMENTS (enforced by hooks):
- Decompose code instead of adding PMD suppression annotations
- Use git merge --ff-only for linear history
- Include tests for bugfixes in SAME commit as the fix
VERIFICATION:
1. Run tests: ./mvnw test -pl parser
2. Run style checks: ./mvnw checkstyle:check pmd:check -pl parser
3. All must pass
FAIL-FAST CONDITIONS:
- If build fails, report BLOCKED with error
- Do NOT attempt workarounds
COMMIT:
After verification passes:
git add <files>
git commit -m "feature: description"
ON COMPLETION: Report summary of changes made.
Why Task tool instead of CLI:
Update parent's tracking:
subagents:
- id: a1b2c3d4
task: 1.2-implement-parser
worktree: .worktrees/1.2-implement-parser-sub-a1b2c3d4
branch: 1.2-implement-parser-sub-a1b2c3d4
session: ${CLAUDE_SESSION_ID}
spawned_at: 2026-01-10T14:30:00Z
status: running
# Parent agent: First create worktree
TASK="1.2-implement-parser"
UUID="a1b2c3d4"
WORKTREE=".worktrees/${TASK}-sub-${UUID}"
git worktree add -b "${TASK}-sub-${UUID}" "${WORKTREE}" HEAD
Then use the Task tool to launch the subagent:
Task tool invocation:
description: "Execute parser task"
subagent_type: "general-purpose"
model: "haiku"
prompt: |
Execute task 1.2 PLAN.md.
WORKING DIRECTORY: .worktrees/1.2-implement-parser-sub-a1b2c3d4
VERIFICATION:
1. Run tests
2. Run style checks
ON COMPLETION: Report summary.
Task tool invocation:
description: "Implement feature X"
subagent_type: "general-purpose"
model: "haiku"
prompt: |
Implement feature X following PLAN.md.
WORKING DIRECTORY: ${WORKTREE_PATH}
CRITICAL REQUIREMENTS:
- Decompose code instead of adding PMD suppression annotations
- Include tests in SAME commit as implementation
EXACT CHANGES:
1. Create src/Feature.java with: [code listing]
2. Create test/FeatureTest.java with: [test code]
VERIFICATION:
1. ./mvnw test -Dtest=FeatureTest
2. ./mvnw checkstyle:check pmd:check
FAIL-FAST: If any check fails, report BLOCKED
COMMIT: git commit -m "feature: add X"
# ❌ WRONG - Requires subagent to make decisions
Task prompt: "Implement error handling for the parser. Choose appropriate exception types."
# ✅ CORRECT - All decisions made by main agent
Task prompt: |
Add error handling to Parser.java:
- Line 45: wrap in try-catch, throw ParseException("Invalid token at position " + pos)
- Line 72: add null check, throw IllegalArgumentException("Input cannot be null")
- All exceptions must include position information for debugging
# ❌ WRONG - Vague instructions
Task prompt: "Work on the parser"
# ✅ CORRECT - Concrete plan reference
Task prompt: |
Execute PLAN.md at .claude/cat/tasks/1.2-implement-parser/PLAN.md.
WORKING DIRECTORY: .worktrees/1.2-implement-parser-sub-a1b2c3d4
When specific API usage or patterns are required, provide explicit before/after code examples:
# ❌ WRONG - Vague instruction, subagent may find different solution
Task prompt: "Remove the unnecessary cast in LexerTest.java"
# ✅ CORRECT - Explicit code example showing expected change
Task prompt: |
Change LexerTest.java line 625:
FROM: requireThat(token.text() == token.decodedText(), "sameInstance").isTrue();
TO: requireThat(token.text(), "token.text()").isReferenceEqualTo(token.decodedText(), "token.decodedText()");
Why: Subagents optimize for passing tests/builds. Without explicit examples, they may find alternative solutions (e.g., @SuppressWarnings) that technically work but don't match the intended approach.
For parser/test tasks, include manual derivation requirement in prompt:
# ❌ WRONG - Missing test derivation guidance
Task prompt: "Add parser tests for new feature"
# ✅ CORRECT - Explicit manual derivation requirement
Task prompt: |
Add parser tests for new feature.
CRITICAL: Test expected values MUST be manually derived:
1. Analyze source string character by character
2. Determine expected node types from Java grammar
3. Use (0, 0) placeholders for positions initially
4. VERIFY actual positions are correct before updating expected values
5. Always verify before copying actual output as expected values
Why: Subagents may use placeholder technique incorrectly - copying actual output without verification creates tests that pass but don't validate correctness.
Parser tests MUST verify AST structure, not just parsing success:
# ❌ WRONG - Only checks parsing succeeded
Task prompt: |
Add tests for new parser feature.
@Test
public void testNewFeature()
{
try (Parser _ = parse(source))
{
// INADEQUATE - only checks parsing didn't throw
}
}
# ✅ CORRECT - Verifies expected AST structure
Task prompt: |
Add tests for new parser feature.
@Test
public void testNewFeature()
{
try (Parser parser = parse(source);
NodeArena expected = new NodeArena())
{
NodeArena actual = parser.getArena();
// Build expected AST with exact node types and positions
expected.allocateNode(NodeType.X, startPos, endPos);
requireThat(actual, "actual").isEqualTo(expected);
}
}
Why (M062): Tests that only check isSuccess() provide false confidence - parsing can succeed
but produce incorrect AST. The isEqualTo(expected) pattern catches structural errors.
# ❌ WRONG - Spawning B that depends on A's output
Task tool: task-a
Task tool: task-b # Depends on task-a!
# ✅ CORRECT - Wait for dependency
Task tool: task-a
# ... wait for task-a result ...
Task tool: task-b # Now safe to spawn
# ❌ WRONG - No tracking of worktree location
git worktree add somewhere
# ✅ CORRECT - Track for later cleanup
WORKTREE=".worktrees/${TASK}-sub-${UUID}"
git worktree add "${WORKTREE}"
# Record in STATE.md for merge-subagent skill
Task STATE.md MUST be updated to status: completed in the SAME commit as implementation:
# ❌ WRONG - No STATE.md update in prompt
Task prompt: |
Implement feature X.
COMMIT: git commit -m "feature: add X"
# ✅ CORRECT - STATE.md update included in commit instructions
Task prompt: |
Implement feature X.
COMMIT (all in same commit):
1. Update .claude/cat/v0/v1.2/task/feature-x/STATE.md:
- Set status: completed
- Set progress: 100%
- Add completed: {date}
2. git add <implementation files> .claude/cat/v0/v1.2/task/feature-x/STATE.md
3. git commit -m "feature: add X"
Why: STATE.md tracks task lifecycle. Committing it separately creates incomplete history and violates atomic task completion (M076). Main agent prompts must include explicit STATE.md instructions.
Subagents should not spawn further subagents. If a task needs decomposition, report back to the parent agent.
Subagents CAN explore/research, but must return findings for main agent to decide - not act on them.
# ❌ WRONG - Subagent explores AND decides what to do
Task prompt: "Find where authentication is handled and add rate limiting"
# ✅ CORRECT - Subagent explores, returns findings, main agent decides later
Task prompt: |
Find all authentication entry points in the codebase.
Return a list of:
- File path and line number
- Method signature
- Current error handling approach
FAIL-FAST: If you cannot locate authentication code within 10 minutes,
report 'BLOCKED: Could not locate auth code' and stop.
Do NOT implement anything - return findings only.
# ✅ ALSO CORRECT - Main agent already explored, provides exact instructions
Task prompt: |
Add rate limiting to src/auth/AuthService.java:
In the authenticate() method at line 45, add before the password check:
if (rateLimiter.isRateLimited(username)) {
throw new RateLimitExceededException(username);
}
# ❌ WRONG - Subagent must judge "working correctly"
Task prompt: "Make sure the parser handles all edge cases correctly"
# ✅ CORRECT - Explicit verification steps
Task prompt: |
Verify parser handles edge cases:
1. Run: ./gradlew test --tests 'ParserEdgeCaseTest'
2. All 12 tests must pass
3. Run: ./scripts/parse-corpus.sh testdata/edge-cases/
4. Output must show: 'Processed 47 files, 0 errors'
FAIL-FAST: If any test fails, report BLOCKED with output. Do NOT fix.
# ❌ WRONG - Fallback involves decisions
Task prompt: "Try to use the new API. If it doesn't work, fall back to the legacy API."
# ✅ CORRECT - Fail-fast, let main agent decide
Task prompt: |
Use the new API at src/api/v2/Client.java.
FAIL-FAST:
- If new API returns errors, report BLOCKED with error details
- Do NOT fall back to legacy API
- Do NOT try alternative approaches
- Return status for main agent to decide next steps
Why: Choosing between approaches is a decision. Decisions require user oversight.
When a subagent returns findings (especially exploration results like "DUPLICATE" or "NOT FOUND"), the main agent must NOT investigate directly:
# ❌ WRONG - Main agent investigates subagent findings directly
Subagent returns: "DUPLICATE: fix already exists in commit c2da15e"
Main agent: "Let me verify by reading ExpressionParser.java..."
Main agent: "Let me run the test to confirm..."
# ✅ CORRECT - Spawn verification subagent if uncertain
Subagent returns: "DUPLICATE: fix already exists in commit c2da15e"
Main agent options:
1. ACCEPT finding and proceed with appropriate workflow (e.g., mark task as duplicate)
2. SPAWN a verification subagent with specific questions:
Task prompt: |
Verify that fix for lambda arrow in parenthesized context exists:
1. Check commit c2da15e7 - does it modify ExpressionParser.java?
2. Run test: ./mvnw test -Dtest="LambdaArrowEdgeCaseParserTest#shouldParseLambdaAfterMethodReferenceWithTrailingComments"
3. Report: VERIFIED or NOT_VERIFIED with evidence
Why this matters:
Decision tree for subagent findings:
The exploration subagent handles three phases internally, hiding noisy tool calls from the user and returning a structured JSON result for clean display.
| Phase | Responsibilities | Output |
|---|---|---|
| Preparation | Read PLAN.md, analyze task size, create worktree | preparation object with estimate and worktree path |
| Exploration | Search codebase, find relevant code, check duplicates | findings object with locations and patterns |
| Verification | Verify findings exist, run preliminary tests, confirm state | verification object with validation results |
Phase 1: Preparation
The exploration subagent performs task setup that would otherwise expose Bash/Read calls to user:
Phase 2: Exploration
Standard exploration responsibilities:
Phase 3: Verification
Post-exploration validation before returning to main agent:
The exploration subagent MUST return structured JSON for clean main agent display:
{
"status": "READY|OVERSIZED|DUPLICATE|BLOCKED",
"preparation": {
"estimatedTokens": 45000,
// See agent-architecture.md § Context Limit Constants for context limits
"percentOfThreshold": 56,
"worktreePath": "/workspace/.worktrees/1.0-parse-lambdas",
"branch": "1.0-parse-lambdas"
},
"findings": {
"filesToModify": [
{"path": "src/Parser.java", "lines": "145-200", "reason": "Add lambda parsing"},
{"path": "src/Lexer.java", "lines": "50-60", "reason": "Add arrow token"}
],
"filesToCreate": [
{"path": "src/LambdaNode.java", "reason": "AST node for lambdas"}
],
"patterns": ["Visitor pattern for AST", "Recursive descent parsing"],
"duplicateCheck": "NOT_DUPLICATE",
"blockers": []
},
"verification": {
"allPathsExist": true,
"patternsConfirmed": true,
"preliminaryChecks": "PASSED",
"notes": []
}
}
| Status | Meaning | Main Agent Action |
|---|---|---|
READY | Task within threshold, ready to proceed | Continue to approach selection |
OVERSIZED | Estimated tokens exceed threshold | Trigger decomposition |
DUPLICATE | Task already implemented elsewhere | Mark as duplicate, skip |
BLOCKED | Cannot proceed (missing deps, etc.) | Present blocker to user |
# ❌ WRONG - Main agent does preparation work inline
Main agent: "Let me read the PLAN.md..."
Main agent: "Now let me calculate the task size..."
Main agent: "Creating worktree with git worktree add..."
# User sees all this noisy output!
# ✅ CORRECT - Exploration subagent handles it internally
Main agent: "Spawning exploration subagent..."
[Subagent runs preparation + exploration + verification internally]
Main agent receives JSON: {"status": "READY", "preparation": {...}, ...}
Main agent displays: "✓ Task size OK: ~45K tokens (56% of threshold)"
# User sees clean summary only!
# ❌ WRONG - Main agent investigates after exploration subagent returns
Exploration subagent returns: {"filesToModify": ["Parser.java"]}
Main agent: "Let me read Parser.java to understand the structure..."
# Violates M088 - main agent should NOT read source files!
# ✅ CORRECT - Trust exploration findings, pass to implementation
Exploration subagent returns: {"filesToModify": ["Parser.java", lines: "145-200"]}
Main agent: "Exploration complete. Spawning implementation subagent..."
# Main agent trusts findings, doesn't re-investigate
cat:monitor-subagents - Check status of spawned subagentscat:collect-results - Gather results when subagent completescat:merge-subagent - Merge subagent work back to task branchcat:parallel-execute - Spawn multiple subagents concurrentlyThis skill should be used when the user asks to "create a hookify rule", "write a hook rule", "configure hookify", "add a hookify rule", or needs guidance on hookify rule syntax and patterns.
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.