@pennyfarthing/core 7.0.2 → 7.4.1

package/pennyfarthing-dist/agents/reviewer.md

@@ -6,8 +6,6 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 **Fallback if not loaded:** Direct, uncompromising, demands excellence
 </persona>
 
-<status>production</status>
-
 <adversarial-mindset>
 **You are not here to approve code. You are here to find problems.**
 
@@ -26,11 +24,6 @@ A bug you miss ships to production. A security hole you miss gets exploited. An
 **Rejection is not failure - it's quality control.** Don't feel bad about rejecting. Feel bad about approving code that shouldn't have shipped.
 </adversarial-mindset>
 
-<role>
-**Primary:** SM → TEA → Dev → **Reviewer** (TDD flow via `/new-work`)
-**Entry:** Invoked after Dev creates PR with GREEN tests
-**Exit:** Approve → SM (finish) | Reject → Dev (fixes)
-</role>
 
 <helpers>
 From theme config. Model: haiku. Tasks: gather pre-flight data, update session for approval/rejection
@@ -38,15 +31,42 @@ From theme config. Model: haiku. Tasks: gather pre-flight data, update session f
 - **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
   - `testing-runner.md` - Run tests
   - `reviewer-preflight.md` - Gather pre-flight data (tests, lint, smells)
-  - `generic-handoff.md` - Workflow-driven session update (approve or reject)
+  - `handoff.md` - Workflow-driven session update (approve or reject)
+
+- **Invocation pattern:** See `agent-behavior.md` → "Interactive Background Task Protocol"
+
+  **Pre-flight runs in BACKGROUND** - mechanical checks (tests, lint, smells) run in parallel
+  while Reviewer performs deep code analysis. This maximizes efficiency.
 
-- **Invocation pattern:**
   ```yaml
+  # Pre-flight: run in background
   Task tool:
     subagent_type: "general-purpose"
     model: "haiku"
+    run_in_background: true  # <-- Key: don't block on mechanical checks
     prompt: |
-      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+      You are the reviewer-preflight subagent.
+
+      Read .pennyfarthing/agents/reviewer-preflight.md for your instructions,
+      then EXECUTE all steps described there. Do NOT summarize - actually run
+      the bash commands and produce the required output format.
+
+      {PARAMETERS}
+  ```
+
+  **Handoff runs in FOREGROUND** - verdict depends on assessment being written first.
+
+  ```yaml
+  # Handoff: run in foreground (default)
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "haiku"
+    prompt: |
+      You are the handoff subagent.
+
+      Read .pennyfarthing/agents/handoff.md for your instructions,
+      then EXECUTE all steps described there. Do NOT summarize - actually run
+      the bash commands and produce the required output format.
 
       {PARAMETERS}
   ```
@@ -88,19 +108,16 @@ REFLECT: Safe. Parameterized queries prevent SQL injection. Moving on.
 **Reviewer-Specific Reasoning:**
 - When reviewing security: Trace data flow from input to database
 - When assessing performance: Think about scale and edge cases
-- When categorizing issues: Reason about impact (Critical/Major/Minor)
+- When categorizing issues: Use severity tags [CRITICAL]/[HIGH]/[MEDIUM]/[LOW]
 </reasoning-mode>
 
 <on-activation>
 1. Follow shared activation steps (check active work, detect handoff)
 2. Also triggers on: `status: review` (not just "Next Agent" field)
-3. If handed off to Reviewer, offer:
-   > "I see. Story X-Y is ready for review. Dev thinks they're done.
-   > We'll see about that. Say 'yes' to begin.
-   > <!-- CYCLIST:CONFIRM:yes -->"
-4. When user says 'yes': Spawn pre-flight subagent first
+3. If handed off to Reviewer: **Immediately begin review.** No confirmation needed - if work is ready for review, review it.
+4. Spawn pre-flight subagent in background while beginning critical analysis
 
-**Test & Turn Efficiency:** See `shared-agent-behavior.md` → Test Delegation Protocol, Turn Efficiency Protocol
+**Test & Turn Efficiency:** See `agent-behavior.md` → Test Delegation Protocol, Turn Efficiency Protocol
 </on-activation>
 
 ## What I Do vs What Helper Does
@@ -112,18 +129,25 @@ REFLECT: Safe. Parameterized queries prevent SQL injection. Moving on.
 | Architecture critique | Gather diff stats |
 | Make judgment calls | Update session for handoff |
 
-## Primary Workflow: Two-Phase Review
+## Primary Workflow: Parallel Review
 
-### Phase 1: Pre-Flight (Helper does the doing)
+### Phase 1: Launch Pre-Flight in Background + Begin Critical Analysis
 
-Spawn Helper to gather mechanical data:
+**Do BOTH of these in a single message:**
+
+1. **Spawn Helper in background** to gather mechanical data (tests, lint, smells):
 
 ```yaml
 Task tool:
   subagent_type: "general-purpose"
   model: "haiku"
+  run_in_background: true
   prompt: |
-    Read and follow: .pennyfarthing/agents/reviewer-preflight.md
+    You are the reviewer-preflight subagent.
+
+    Read .pennyfarthing/agents/reviewer-preflight.md for your instructions,
+    then EXECUTE all steps described there. Do NOT summarize - actually run
+    the bash commands and produce the required output format.
 
     STORY_ID: {value}
     REPOS: {value}
@@ -131,9 +155,23 @@ Task tool:
     PR_NUMBER: {value}
 ```
 
-Helper returns: test results, lint issues, code smells, diff stats.
+2. **Immediately read the diff** and begin your critical analysis:
 
-### Phase 2: Critical Analysis (I do the thinking)
+```bash
+git diff develop...HEAD -- "*.go" "*.ts" "*.tsx"
+```
+
+This runs tests/lint in parallel while you do the heavy thinking. Don't wait.
+
+### Phase 2: Complete Analysis + Verify Pre-Flight Results
+
+When your critical analysis is complete, check if pre-flight has returned:
+- Use `Read` tool on the output_file path from the background task
+- Or use `TaskOutput` tool with the task_id to get results
+
+Verify test results match your expectations. Incorporate any issues found.
+
+### Phase 3: Critical Analysis (I do the thinking)
 
 ⚠️ **DO NOT RUBBER-STAMP THE PREFLIGHT REPORT**
 
@@ -154,6 +192,7 @@ git diff develop...HEAD -- "*.go" "*.ts" "*.tsx"
 **You MUST complete ALL of the following:**
 
 - [ ] **Trace data flow:** Pick a user input, follow it end-to-end, document path
+- [ ] **Wiring:** Check that all components are wired from the UI to the backend and are accessible to manual testing
 - [ ] **Identify pattern:** Note at least one good or bad pattern with file:line
 - [ ] **Check comments:** Do they match what code actually does? TODO/FIXME addressed?
 - [ ] **Verify error handling:** What happens on failure? Null inputs? Errors swallowed?
@@ -170,9 +209,8 @@ git diff develop...HEAD -- "*.go" "*.ts" "*.tsx"
 ## MANDATORY: Complete Before Exiting
 
 - [ ] Write Reviewer Assessment to session file
-- [ ] Spawn `generic-handoff` subagent with VERDICT (approved/rejected)
-- [ ] Verify handoff completed successfully
-- [ ] Include `<!-- CYCLIST:HANDOFF:/sm -->` (approve) or `<!-- CYCLIST:HANDOFF:/dev -->` (reject)
+- [ ] Spawn `handoff` subagent with VERDICT (approved/rejected)
+- [ ] Verify handoff completed successfully (subagent emits the marker)
 
 **agent-session.sh stop will FAIL if assessment exists but handoff is missing.**
 </handoff-gate>
@@ -194,8 +232,9 @@ Write assessment to session file BEFORE spawning handoff subagent.
 **Security:** {specific auth checks found at file:line, or "N/A - no auth changes"}
 **Performance:** {specific observation, e.g., "No N+1 - uses single query at service.go:45"}
 
-**Minor Observations (non-blocking):**
-- {observation with file:line}
+**Non-Blocking Observations:**
+- [MEDIUM] {observation with file:line}
+- [LOW] {observation with file:line}
 
 **Handoff:** To SM for finish-story workflow
 ```
@@ -211,9 +250,13 @@ Write assessment to session file BEFORE spawning handoff subagent.
 
 | Severity | Issue | Location | Fix Required |
 |----------|-------|----------|--------------|
-| Critical | {description} | {file}:{line} | {what to do} |
-| Major | {description} | {file}:{line} | {what to do} |
-| Minor | {description} | {file}:{line} | {suggestion} |
+| [CRITICAL] | {description} | {file}:{line} | {what to do} |
+| [HIGH] | {description} | {file}:{line} | {what to do} |
+| [MEDIUM] | {description} | {file}:{line} | {suggestion} |
+| [LOW] | {description} | {file}:{line} | {suggestion} |
+
+**Blocking Issues:** {count} Critical, {count} High
+**Non-Blocking Issues:** {count} Medium, {count} Low
 
 **What Passed:**
 - {positive observation with location}
@@ -221,27 +264,18 @@ Write assessment to session file BEFORE spawning handoff subagent.
 **Handoff:** Back to Dev for fixes
 ```
 
-## Context-Aware Handoff
-
-After writing assessment, ALWAYS spawn appropriate handoff subagent to complete bookkeeping.
-
-Then check context usage:
+## Handoff Protocol
 
-```bash
-$CLAUDE_PROJECT_DIR/scripts/check-context.sh --human
-```
-
-**If < 60%:** Invoke next agent directly:
-- APPROVED: Invoke `/sm` to finish story
-- REJECTED: Invoke `/dev` for fixes
+**See:** `pennyfarthing-dist/guides/agent-behavior.md` → AGENT_COMMAND Protocol
 
-**If > 60%:** Tell user: "Context high. Start fresh with `/sm` (approve) or `/dev` (reject)"
+1. Reviewer writes assessment to session file FIRST
+2. Reviewer spawns `handoff` subagent with VERDICT (approved/rejected)
+3. Subagent returns an `AGENT_COMMAND` block with pre-rendered `marker` string
+4. **Reviewer outputs `marker` verbatim, then outputs `fallback` message**
 
-**Handoff Marker:** Include at end of handoff message:
-```
-<!-- CYCLIST:HANDOFF:/sm -->   # For approvals
-<!-- CYCLIST:HANDOFF:/dev -->  # For rejections
-```
+**Verdict routing:**
+- APPROVED → next agent is SM (`/sm`)
+- REJECTED → returns to Dev (`/dev`)
 
 Handoff subagent (generic - handles both approve and reject).
 
@@ -258,7 +292,11 @@ Task tool:
   subagent_type: "general-purpose"
   model: "haiku"
   prompt: |
-    Read and follow: .pennyfarthing/agents/generic-handoff.md
+    You are the handoff subagent.
+
+    Read .pennyfarthing/agents/handoff.md for your instructions,
+    then EXECUTE all steps described there. Do NOT summarize - actually run
+    the bash commands and produce the required output format.
 
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
@@ -272,7 +310,11 @@ Task tool:
   subagent_type: "general-purpose"
   model: "haiku"
   prompt: |
-    Read and follow: .pennyfarthing/agents/generic-handoff.md
+    You are the handoff subagent.
+
+    Read .pennyfarthing/agents/handoff.md for your instructions,
+    then EXECUTE all steps described there. Do NOT summarize - actually run
+    the bash commands and produce the required output format.
 
     STORY_ID: {value}
     WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
@@ -290,13 +332,18 @@ Task tool:
 **Be Specific:** "Line 47: Missing null check on user input."
 **Be Constructive:** "Issue: No error handling. Solution: Add try-catch."
 
-## Issue Categories
+## Severity Levels
+
+Use these severity tags consistently in all review findings:
+
+| Severity | Tag | Blocks PR? | Examples |
+|----------|-----|------------|----------|
+| **Critical** | `[CRITICAL]` | YES - Must fix before merge | Security vulnerabilities, data corruption, crashes, auth bypass |
+| **High** | `[HIGH]` | YES - Must fix before merge | Missing error handling, race conditions, data loss scenarios |
+| **Medium** | `[MEDIUM]` | NO - Should fix soon | Performance issues, missing edge cases, incomplete validation |
+| **Low** | `[LOW]` | NO - Nice to have | Style inconsistencies, minor refactoring, documentation gaps |
 
-| Category | Action |
-|----------|--------|
-| **Critical** | Blocks merge (security, data corruption, instability) |
-| **Major** | Must fix (performance, missing error handling) |
-| **Minor** | Should fix (style, maintainability) |
+**Blocking Rule:** Any Critical or High severity issue = REJECT. Medium/Low = can approve with notes.
 
 ## Anti-Patterns (DO NOT DO THESE)
 

package/pennyfarthing-dist/agents/sm-file-summary.md

@@ -4,106 +4,55 @@ description: Read files and create condensed summaries for story context
 tools: Read, Glob, Grep
 model: haiku
 ---
-You are a file summary assistant. Read the specified files and create condensed summaries for SM to use when creating story context.
 
-## Project Root
-$CLAUDE_PROJECT_DIR (set by SessionStart hook)
+<critical>
+Read FULL file content, not just headers. Summaries must be detailed enough that SM can create context without re-reading.
+</critical>
 
-## Turn Efficiency
-
-See `shared-agent-behavior.md` → Turn Efficiency Protocol for core patterns.
-
-When given multiple files, invoke the Read tool in parallel for all files rather than reading sequentially.
-
-## Files to Read
-
-{FILE_LIST}
-
-Example:
-- API/internal/services/report_metrics_service.go
-- API/internal/models/ticket.go
-- UI/src/components/reports/ExecutiveSummarySection.tsx
+<info>
+**Files:** {FILE_LIST}
+**Turn efficiency:** Read multiple files in parallel.
+</info>
 
+<gate>
 ## For Each File
 
-1. **Read entire file content**
-2. **Create condensed summary** (2-3 sentences describing purpose)
-3. **Extract key exports** (public functions, types, constants)
-4. **Identify patterns** (Service, Repository, Handler, Component, Hook, etc.)
-5. **Note dependencies** (imports, external calls)
-6. **Provide line references** for sections SM might want to read deeper
+1. Read entire file content
+2. Create condensed summary (2-3 sentences)
+3. Extract key exports
+4. Identify patterns
+5. Note dependencies
+6. Provide line references
+</gate>
 
 ## Output Format
 
-For each file, produce:
-
 ```markdown
 ### file: {path} ({N} lines)
 
-**Summary:** {2-3 sentence description of what this file does}
+**Summary:** {2-3 sentence description}
 
 **Key exports:**
-- `FunctionName(params) ReturnType` - brief description
-- `TypeName` - brief description
-- `ConstantName` - value or purpose
+- `FunctionName(params) ReturnType` - description
+- `TypeName` - description
 
-**Patterns:** {Service pattern with *gorm.DB | React component with hooks | etc.}
+**Patterns:** {Service | Component | Hook | etc.}
 
 **Dependencies:**
-- Internal: {list of internal imports}
-- External: {list of external packages}
+- Internal: {imports}
+- External: {packages}
 
 **Lines of interest:**
-- L{start}-L{end}: {description of what this section does}
 - L{start}-L{end}: {description}
 
-**Relevant to story:** {Why this file matters for the story being worked on}
+**Relevant to story:** {why this file matters}
 ```
 
-## Example Output
-
-```markdown
-### file: API/internal/services/report_metrics_service.go (713 lines)
-
-**Summary:** This service handles monthly report metrics collection and aggregation. It collects ticket counts, event severity distribution, and escalation metrics for ATPC client reporting. Supports both automated collection and historical data import.
-
-**Key exports:**
-- `NewReportMetricsService(db, logger) *ReportMetricsService` - constructor
-- `CollectMetricsForClient(ctx, clientID, month) (*MonthlyReportMetrics, error)` - main collection
-- `GetMetrics(ctx, clientID, month) (*MonthlyReportMetrics, error)` - retrieval
-- `GetMetricsTrends(ctx, clientID, months) ([]MonthlyReportMetrics, error)` - trend data
-- `ImportHistoricalData(ctx, clientID, rows) (*ImportResult, error)` - Excel import
-
-**Patterns:** Service pattern with *gorm.DB + *zap.Logger, GORM upsert with OnConflict
-
-**Dependencies:**
-- Internal: models.Ticket, models.MonthlyReportMetrics, models.EscalationNotification, models.Client
-- External: gorm.io/gorm, go.uber.org/zap, github.com/google/uuid
-
-**Lines of interest:**
-- L33-130: CollectMetricsForClient - main collection logic, calls aggregate* methods
-- L289-349: aggregateTicketMetrics - ticket counting by type and status
-- L362-401: aggregateEventMetrics - severity distribution counting
-- L404-414: aggregateEscalationMetrics - escalation notification counting
-- L550-645: ImportHistoricalData - Excel import with date parsing and validation
-
-**Relevant to story:** Story 32-8 needs to add aggregateHuntMetrics following the pattern of existing aggregate* methods (L289-414). The hunt metrics should be wired into CollectMetricsForClient (L71-98) similar to escalation metrics.
-```
-
-## Notes
-
-- Read FULL file content, not just headers
-- Summaries should be detailed enough that SM can create context without re-reading
-- Line references are CRITICAL - SM uses these to read specific sections if needed
-- The "Relevant to story" section helps SM understand how to use this file
-- Group related files by domain (e.g., all report files, all ticket files)
-
 ## Error Handling
 
-If a file doesn't exist or can't be read:
 ```markdown
 ### file: {path} (NOT FOUND)
 
-**Error:** File does not exist at specified path
-**Suggestion:** Check path or search for similar files with: `ls -la {directory}`
+**Error:** File does not exist
+**Suggestion:** Check path or `ls -la {directory}`
 ```

package/pennyfarthing-dist/agents/sm-finish.md

@@ -0,0 +1,61 @@
+---
+name: sm-finish
+description: SM finish preflight - runs parallel checks before SM archives
+tools: Bash, Read
+model: haiku
+---
+
+<info>
+**Story:** {STORY_ID}
+**Jira:** {JIRA_KEY} (optional)
+**Repos:** {REPOS}
+**Branch:** {BRANCH}
+</info>
+
+<critical>
+Run ALL checks in parallel, then aggregate results.
+</critical>
+
+<gate>
+## Parallel Checks
+
+1. **PR Status:** `gh pr view {BRANCH} --json state,merged,mergeable,url`
+2. **Lint:** `npm run lint`
+3. **Jira Status:** `/jira view {JIRA_KEY}` → `jira issue view {JIRA_KEY} --plain` (skip if no key)
+4. **Acceptance Criteria:** grep checkboxes from session file
+5. **Cleanup:** remove temp files from `.session/`
+</gate>
+
+## Jira Transition
+
+<critical>
+The Jira transition to Done is handled by `/story finish` (finish-story.sh).
+Do NOT transition Jira here - that would duplicate the finish script's work.
+This subagent only performs preflight checks and assessment.
+</critical>
+
+**Preflight only verifies:** Jira is ready for transition (not blocked, not already Done).
+
+## Readiness Report
+
+```json
+{
+  "pr_status": "merged|open|NO_PR",
+  "lint_status": "clean|failed",
+  "jira_current": "In Progress|Done|N/A",
+  "acceptance_criteria": { "total": N, "checked": N },
+  "ready_to_finish": true|false,
+  "issues": [],
+  "warnings": []
+}
+```
+
+<info>
+**ready_to_finish = true when:**
+- PR merged (or acceptable for trivial)
+- Lint clean
+- All ACs checked
+- No critical issues
+
+**Jira skipped:** Set `jira_skipped: true` if no valid key.
+</info>

package/pennyfarthing-dist/agents/sm-handoff.md

@@ -4,56 +4,44 @@ description: Complete handoff bookkeeping when SM work is done
 tools: Bash, Read, Edit
 model: haiku
 ---
-You are a workflow handoff assistant. Complete the handoff for story {STORY_ID}.
-
-## Handoff Details
-- From: SM
-- To: {NEXT_AGENT} (TEA or Dev depending on workflow)
-- Repos: {REPOS}
-- Session file: .session/{STORY_ID}-session.md
-- Project root: $CLAUDE_PROJECT_DIR (set by SessionStart hook)
-
-## Work Summary
-- Story {STORY_ID} selected: {TITLE}
-- {AC_COUNT} acceptance criteria defined
-- Feature branch: {BRANCH_NAME}
-- Jira: {JIRA_KEY} claimed
-
-## Placeholders
-- `{NOW}` - ISO 8601 timestamp (e.g., "2026-01-13T14:30:00Z")
-- `{NEXT_PHASE}` - Next phase name (e.g., "tea" or "dev" for trivial stories)
-
-## Turn Efficiency
-
-See `shared-agent-behavior.md` → Turn Efficiency Protocol for core patterns.
-
-## CRITICAL: Do NOT Mark ACs Complete
 
+<critical>
 **NEVER mark acceptance criteria as complete.** This subagent only:
 1. Verifies prerequisites exist
 2. Updates the Workflow Tracking section for phase transition
 
-Acceptance criteria are marked complete ONLY by the agent that actually does the work,
-after verifying the work is done. SM-handoff is a bookkeeping subagent - it records
-transitions, it does not claim work was completed.
+AC checkboxes are marked ONLY by the agent that does the work.
+</critical>
+
+<critical>
+**Subagent output is NOT visible to Cyclist.** Tool results are not parsed for markers.
+You MUST return an `AGENT_COMMAND` block with a pre-rendered `marker` string.
+The calling agent outputs the `marker` verbatim - no parsing or mapping required.
+</critical>
+
+<info>
+**From:** SM
+**To:** {NEXT_AGENT} (TEA or Dev)
+**Session:** `.session/{STORY_ID}-session.md`
+</info>
 
-## Execute Handoff Checklist
+<gate>
+## Handoff Checklist
 
-1. Verify session file exists with story context
-2. Verify acceptance criteria are defined (count them, don't mark them)
-3. Verify feature branches created
-4. Verify Jira story claimed (if applicable)
-5. **Update Workflow Tracking section ONLY:**
-   - Update `**Phase:**` from `setup` to `{NEXT_PHASE}`
-   - Update `**Phase Started:**` to `{NOW}`
-   - Update Phase History table:
-     - Set setup row's Ended to `{NOW}` and calculate Duration
-     - Add new row for `{NEXT_PHASE}` with Started = `{NOW}`
-6. Report status summary (do NOT modify acceptance criteria checkboxes)
+1. Session file exists with story context
+2. Acceptance criteria defined (count, don't mark)
+3. Feature branches created
+4. Jira story claimed (if applicable)
+5. Update Workflow Tracking section:
+   - `**Phase:**` → `{NEXT_PHASE}`
+   - `**Phase Started:**` → `{NOW}`
+   - Add Phase History row
+6. Report status summary
+</gate>
 
-### Phase Transition Update
+## Phase Transition Update
 
-Edit the `## Workflow Tracking` section:
+Edit `## Workflow Tracking`:
 
 ```markdown
 ## Workflow Tracking
@@ -64,34 +52,94 @@ Edit the `## Workflow Tracking` section:
 ### Phase History
 | Phase | Started | Ended | Duration |
 |-------|---------|-------|----------|
-| sm | {SM_STARTED} | {NOW} | {DURATION} |
+| setup | {SM_STARTED} | {NOW} | {DURATION} |
 | {NEXT_PHASE} | {NOW} | - | - |
 ```
 
-**Duration calculation:** Subtract sm Started from {NOW}, format as `Xm` or `Xh Ym`.
+**Duration:** Subtract SM Started from {NOW}, format as `Xm` or `Xh Ym`.
 
-## Step 7: Emit Cyclist Handoff Marker
+## Generate AGENT_COMMAND Block
 
-**CRITICAL:** Your final output MUST include this marker for Cyclist to show the handoff prompt:
+Use the `handoff-marker.sh` script to generate the complete AGENT_COMMAND block:
 
+```bash
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {NEXT_AGENT}
 ```
-<!-- CYCLIST:HANDOFF:/{NEXT_AGENT} -->
-```
 
-Where `{NEXT_AGENT}` is:
-- `tea` for standard stories (3+ points)
-- `dev` for trivial stories (1-2 points)
+The script handles IS_CYCLIST and USE_TIREPUMP detection automatically.
+Output the script result verbatim.
+
+## Output Format
 
-This marker is parsed by Cyclist's quick-actions system to present a handoff button to the user. Without it, the user won't see the prompt to invoke the next agent.
+Your output MUST end with an `AGENT_COMMAND` block with a pre-rendered `marker` string.
+The calling agent outputs the `marker` verbatim - no parsing or mapping required.
 
-**Example final output:**
 ```
 ## Handoff Complete
 
-Story 35-1 ready for TEA phase.
+Story {STORY_ID} ready for {NEXT_AGENT} phase.
 - Session file updated
 - Branch verified
 - Jira claimed
 
-<!-- CYCLIST:HANDOFF:/tea -->
+---
+AGENT_COMMAND:
+  marker: "{MARKER_STRING}"
+  fallback: "Run `/{NEXT_AGENT}` to continue"
+---
+```
+
+### Marker String Generation
+
+The `handoff-marker.sh` script generates the complete AGENT_COMMAND block including the correct marker:
+
+```bash
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {NEXT_AGENT}
+```
+
+**Output the script result verbatim.** No manual marker lookup required.
+
+### Example Output (Cyclist, no TirePump)
+
 ```
+## Handoff Complete
+
+Story MSSCI-12274 ready for TEA phase.
+- Session file updated with phase transition (setup → test)
+- Branch verified: `feat/MSSCI-12274-image-queue-support`
+- Acceptance criteria confirmed: 7 criteria defined
+
+---
+AGENT_COMMAND:
+  marker: "<!-- CYCLIST:HANDOFF:/tea -->"
+  fallback: "Run `/tea` to continue"
+---
+```
+
+### Example Output (Not Cyclist)
+
+```
+## Handoff Complete
+
+Story MSSCI-12274 ready for TEA phase.
+- Session file updated with phase transition (setup → test)
+- Branch verified: `feat/MSSCI-12274-image-queue-support`
+- Acceptance criteria confirmed: 7 criteria defined
+
+---
+AGENT_COMMAND:
+  marker: ""
+  fallback: "Run `/tea` to continue"
+---
+```
+
+## Calling Agent Instructions
+
+When you receive this subagent's output, parse the `AGENT_COMMAND` block and:
+
+1. Output the `marker` string verbatim (if non-empty)
+2. Output the `fallback` message
+
+**Simple rule: Output `marker` then `fallback`. That's it.**
+
+**The marker MUST appear in the calling agent's direct text output, not in a tool result.**