@pennyfarthing/core 7.9.1 → 7.9.3

package/pennyfarthing-dist/guides/patterns/helper-delegation-pattern.md

@@ -1,488 +0,0 @@
-# Helper Delegation Pattern
-
-**Pattern Type:** Strategic-to-Tactical Delegation
-**Agents Involved:** Opus (strategic), Haiku (mechanical)
-**Coordination Mechanism:** Task tool with `subagent_type`
-
-## Problem Statement
-
-AI agents face a fundamental tension between strategic reasoning and mechanical execution:
-
-1. **Context Waste:** Opus-level models burn expensive context on mechanical tasks (git commands, file scanning, session updates)
-2. **Instruction Drift:** Agents tend to ignore multi-step markdown instructions during handoffs, leading to incomplete state updates
-3. **Reliability Gap:** Strategic agents make creative decisions well but may skip critical mechanical steps
-4. **Cost Inefficiency:** Using expensive models for simple, deterministic tasks is wasteful
-
-Without delegation, agents may:
-- Forget to update session files during handoffs
-- Skip verification steps (tests, lint, git status)
-- Burn context on repetitive scanning operations
-- Make mechanical errors that a simpler, focused agent wouldn't
-
-## Solution
-
-Delegate mechanical work to **Haiku subagents** via Claude Code's Task tool. This creates a two-tier architecture:
-
-```
-Opus Agent (strategic)
-    │
-    ├── Makes decisions, analyzes problems, writes code
-    │
-    └── Delegates mechanical work via Task tool
-            │
-            ├── workflow-status-check (state detection)
-            ├── sm-setup (research backlog or setup story)
-            ├── sm-finish (preflight checks or execute finish)
-            ├── sm-handoff (SM→TEA/Dev with Jira/branch verification)
-            ├── handoff (TEA/Dev/Reviewer phase transitions)
-            ├── reviewer-preflight (test/lint data gathering)
-            └── testing-runner (test execution)
-```
-
-The key insight: **Make critical behaviors AUTOMATIC via subagent delegation** rather than relying on agents to follow markdown instructions.
-
-## State Diagram
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                      HELPER DELEGATION FLOW                              │
-└─────────────────────────────────────────────────────────────────────────┘
-
-    ┌──────────────────┐
-    │   Opus Agent     │
-    │   (strategic)    │
-    └────────┬─────────┘
-             │
-             │ Task tool invocation
-             │ subagent_type: "workflow-status-check"
-             │
-             ▼
-    ┌──────────────────┐
-    │  Haiku Subagent  │
-    │   (mechanical)   │
-    └────────┬─────────┘
-             │
-             │ Executes bash, reads files,
-             │ updates session, returns report
-             │
-             ▼
-    ┌──────────────────┐
-    │  Structured      │
-    │  Markdown Report │
-    └────────┬─────────┘
-             │
-             │ Opus receives result,
-             │ continues strategic work
-             │
-             ▼
-    ┌──────────────────┐
-    │   Opus Agent     │
-    │   (continues)    │
-    └──────────────────┘
-```
-
-### Delegation Categories
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│ CATEGORY          │ SUBAGENT               │ PURPOSE                    │
-├───────────────────┼────────────────────────┼────────────────────────────┤
-│ State Detection   │ workflow-status-check  │ Scan files, report state   │
-├───────────────────┼────────────────────────┼────────────────────────────┤
-│ Setup/Init        │ sm-setup       │ Research or setup (MODE)   │
-│                   │ sm-handoff             │ SM→TEA/Dev with Jira/branch│
-├───────────────────┼────────────────────────┼────────────────────────────┤
-│ Phase Handoff     │ handoff        │ TEA/Dev/Reviewer transitions│
-├───────────────────┼────────────────────────┼────────────────────────────┤
-│ Verification      │ reviewer-preflight     │ Gather facts before review │
-│                   │ testing-runner         │ Execute tests, report      │
-├───────────────────┼────────────────────────┼────────────────────────────┤
-│ Finish/Cleanup    │ sm-finish      │ Preflight or execute (PHASE)│
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-## Implementation
-
-### Invocation Pattern
-
-Use Claude Code's Task tool with the `subagent_type` parameter:
-
-```yaml
-Task tool:
-  subagent_type: "workflow-status-check"
-  model: "haiku"                           # Optional, defaults to haiku
-  description: "Check workflow state"
-  prompt: |
-    CALLING_AGENT: SM
-    PROJECT_ROOT: $CLAUDE_PROJECT_DIR
-
-    Scan .session files and git status to determine workflow state.
-```
-
-### Placeholder Substitution
-
-Subagent definitions use placeholders that the calling agent fills:
-
-```markdown
-# Subagent Definition (.pennyfarthing/agents/tea-handoff.md)
----
-name: tea-handoff
-tools: Bash, Read, Edit, Grep
-model: haiku
----
-You are a workflow handoff assistant for story {STORY_ID}.
-
-Session file: .session/{STORY_ID}-session.md
-Test files: {TEST_FILE_LIST}
-Failing count: {FAILING_COUNT}
-```
-
-When invoking:
-```yaml
-Task tool:
-  subagent_type: "tea-handoff"
-  prompt: |
-    STORY_ID: 5-2
-    TEST_FILE_LIST: internal/service/feature_test.go
-    FAILING_COUNT: 4
-    PASSING_COUNT: 0
-```
-
-### Subagent Definition Structure
-
-Each subagent follows this template (see `agents/*.md`):
-
-```markdown
----
-name: subagent-name
-description: One-line description
-tools: Bash, Read, Edit, Grep    # Limited tool set
-model: haiku                       # Fast, cheap model
----
-You are a [role] assistant. [Brief purpose].
-
-## Placeholders
-- `{PLACEHOLDER}` - Description
-
-## Project Root
-$CLAUDE_PROJECT_DIR (set by SessionStart hook)
-
-## Step 1: [First Action]
-```bash
-# Bash commands with placeholders
-```
-
-## Step 2: [Second Action]
-[More steps...]
-
-## Output Format
-```markdown
-## [Report Title]
-[Structured output template]
-```
-
-## Error Recovery
-[Retry pattern and escalation format]
-```
-
-### Real Example: workflow-status-check
-
-**Definition** (from `agents/workflow-status-check.md:14-45`):
-
-```bash
-# Step 1: Scan Session Files
-ls -la .session/*-session.md 2>/dev/null
-
-for f in .session/*-session.md; do
-    [ -f "$f" ] && head -50 "$f"
-done
-
-# Extract: Story ID, Phase, Status, Branch, Jira key
-```
-
-**State Determination** (lines 89-100):
-
-```
-Rules applied in order:
-1. MISSING_EPIC_CONTEXT: No epic context AND no sessions
-2. FINISH_STATE: Phase=approved OR (Phase=review AND Status=approved)
-3. NEW_WORK_STATE: No sessions AND no in_progress stories
-4. IN_PROGRESS_STATE: Session exists with active phase
-```
-
-**Output** (lines 129-183):
-
-```markdown
-## Workflow Status Report
-
-### Detected State
-**{STATE}**
-
-### Active Work Sessions
-| Story | Phase | Status | Days Active |
-|-------|-------|--------|-------------|
-
-### Agent Guidance
-**For {CALLING_AGENT}:** {specific action}
-```
-
-### Real Example: tea-handoff
-
-**Pre-flight Verification** (from `agents/tea-handoff.md:29-40`):
-
-```bash
-# Check TEA Assessment exists
-grep -q "## TEA Assessment" .session/{STORY_ID}-session.md
-# If NOT found: STOP
-```
-
-**Subagent-to-Subagent Delegation** (lines 42-67):
-
-```yaml
-# tea-handoff spawns testing-runner for verification
-subagent_type: "general-purpose"
-model: "haiku"
-prompt: |
-  Run tests and report results.
-  Run ID: {STORY_ID}-tea
-  Context: Verify tests are RED
-```
-
-**Session Update** (lines 79-92):
-
-```markdown
-1. Read current session file
-2. Add "TEA Assessment" section
-3. Mark workflow checkbox complete
-4. Add log entry: "Tests are RED. Ready for Dev."
-```
-
-### Result Handling
-
-Subagents return structured markdown that the calling Opus agent parses:
-
-```markdown
-## Pre-Flight Report: Story 5-2
-
-### Test Results
-| Repo | Passed | Failed | Status |
-|------|--------|--------|--------|
-| API  | 0      | 4      | RED    |
-
-### Readiness
-**Ready for Dev:** Yes
-```
-
-The Opus agent reads this report and decides next steps—it doesn't re-execute the mechanical work.
-
-## When to Use
-
-### Delegate When:
-
-| Scenario | Subagent | Why |
-|----------|----------|-----|
-| Determining workflow state | `workflow-status-check` | Scanning files is mechanical |
-| Creating branches/sessions | `sm-setup MODE=setup` | Git operations are deterministic |
-| Verifying test state | `testing-runner` | Test execution is mechanical |
-| Updating session files | `handoff` | State updates must be reliable |
-| Gathering review data | `reviewer-preflight` | Fact-finding, not judgment |
-| Sprint file updates | `sm-finish` | Archiving is mechanical |
-
-### Don't Delegate When:
-
-| Scenario | Why Keep in Opus |
-|----------|------------------|
-| Making architectural decisions | Requires strategic reasoning |
-| Writing code/tests | Creative work needs full context |
-| Code review judgment | Adversarial analysis is strategic |
-| User interaction decisions | Context-dependent choices |
-| Error diagnosis | May need creative problem solving |
-
-### Decision Heuristic
-
-```
-Is the task...
-├── Deterministic (same input → same output)?
-│   └── YES → Delegate
-├── Requiring judgment or creativity?
-│   └── NO → Keep in Opus
-├── Repetitive across sessions?
-│   └── YES → Delegate
-├── Involving file scanning/git operations?
-│   └── YES → Delegate
-└── Making decisions that affect flow?
-    └── Keep in Opus
-```
-
-## Error Recovery
-
-### Subagent Retry Pattern
-
-From `agents/sm-setup.md` (Error Recovery section):
-
-```
-1. Log the failure: Note which step failed and why
-2. Diagnose: What specifically went wrong?
-3. Adjust: Try a different approach (max 2 retries)
-4. Escalate: If still failing, report to calling agent
-```
-
-### Escalation Format
-
-When subagents cannot complete their task:
-
-```markdown
-SETUP BLOCKED
-
-Step failed: [which step]
-Error: [error message]
-Diagnosis: [what went wrong]
-
-Recommended fix: [what calling agent should do]
-```
-
-### Common Failure Patterns
-
-| Failure | Subagent | Fix |
-|---------|----------|-----|
-| Jira claim failed | sm-setup | Choose different story |
-| Tests all GREEN | handoff | TEA must verify tests are correct |
-| PR not found | handoff | Verify PR was created |
-| Session file missing | any handoff | Check path, may need recreation |
-| Git command failed | any | Check for uncommitted changes |
-
-### Never Silently Fail
-
-From `agents/workflow-status-check.md:195`:
-
-> If partial failure, report what worked and mark unknowns. **Never silently fail.**
-
-Subagents must always return a result, even if partial. The calling agent decides how to proceed.
-
-## Anti-Patterns
-
-### Direct Execution by Opus
-
-**Wrong:**
-```
-SM agent runs 50 lines of bash to scan session files,
-check git status, update sprint YAML, create branch...
-```
-Burns context, may skip steps, prone to errors.
-
-**Correct:**
-```yaml
-Task tool:
-  subagent_type: "sm-setup"
-  prompt: |
-    MODE: setup
-    STORY_ID: 5-2
-    [other placeholders]
-```
-Haiku executes reliably, returns structured result.
-
-### Skipping Handoff Subagents
-
-**Wrong:**
-```
-TEA: "I wrote the tests. Dev, please continue."
-```
-Session file not updated, next agent unclear, state lost.
-
-**Correct:**
-```
-TEA: spawns tea-handoff → session updated → Dev activated
-```
-
-### Overloading Subagents
-
-**Wrong:**
-```yaml
-# Subagent doing too much
-prompt: |
-  1. Analyze code architecture
-  2. Decide which tests to write
-  3. Write the tests
-  4. Commit them
-  5. Update session
-```
-Mixing strategic (1-2) with mechanical (3-5).
-
-**Correct:**
-```yaml
-# Opus does strategic work, then delegates mechanical
-# OPUS: Decides tests, writes them
-# Then:
-subagent_type: "tea-handoff"
-prompt: |
-  STORY_ID: 5-2
-  TEST_FILES: [list from Opus work]
-  # Only mechanical: verify, update session
-```
-
-### Ignoring Subagent Results
-
-**Wrong:**
-```
-Opus spawns workflow-status-check, ignores output, proceeds anyway
-```
-
-**Correct:**
-```
-Opus spawns workflow-status-check
-→ Reads state (NEW_WORK_STATE, FINISH_STATE, etc.)
-→ Branches logic based on result
-```
-
-### Missing Error Handling
-
-**Wrong:**
-```markdown
-## Step 3: Update Sprint
-Edit sprint/current-sprint.yaml
-```
-No error handling, silent failures possible.
-
-**Correct:**
-```markdown
-## Step 3: Update Sprint
-Edit sprint/current-sprint.yaml
-
-If edit fails:
-- Log: "Sprint YAML update failed"
-- Diagnose: File locked? Wrong path?
-- Escalate: Report to calling agent
-```
-
-## Related Patterns
-
-- **TDD Flow Pattern** (`tdd-flow-pattern.md`): The workflow that uses delegation extensively
-- **Approval Gates Pattern** (`approval-gates-pattern.md`): How delegation supports review gates
-- **Fan-out/Fan-in Pattern** (`fan-out-fan-in-pattern.md`): Parallel delegation patterns
-
-## References
-
-### Subagent Definitions
-- State Detection: `agents/workflow-status-check.md`
-- SM Setup/Research: `agents/sm-setup.md`
-- SM Finish: `agents/sm-finish.md`
-- SM Handoff: `agents/sm-handoff.md`
-- Phase Transitions: `agents/handoff.md`
-- Reviewer Preflight: `agents/reviewer-preflight.md`
-- Testing Runner: `agents/testing-runner.md`
-
-### Agent Definitions (Opus)
-- SM: `agents/sm.md`
-- TEA: `agents/tea.md`
-- Dev: `agents/dev.md`
-- Reviewer: `agents/reviewer.md`
-
-### Claude Code Documentation
-- Task tool: Spawns subagents with isolated context
-- `subagent_type` parameter: Routes to specialized agents
-- `model` parameter: Specifies haiku for mechanical work
-
----
-
-*Last verified: 2026-01-06*
-*Pennyfarthing v4.0.0*