@pennyfarthing/core 7.4.1 → 7.6.0

package/pennyfarthing-dist/agents/dev.md

@@ -38,6 +38,21 @@ From theme config. Model: haiku. Tasks: run tests, gather results, update sessio
   ```
 </helpers>
 
+<phase-check>
+## On Startup: Check Phase
+
+Read `**Workflow:**` and `**Phase:**` from session. Query phase owner:
+
+```bash
+OWNER=$($CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/run.sh workflow/phase-owner.sh {workflow} {phase})
+```
+
+**If OWNER != "dev":**
+1. Run: `$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh $OWNER`
+2. Output the result verbatim
+3. Tell user the story is waiting for that agent
+</phase-check>
+
 <responsibilities>
 - Implement minimal code to pass failing tests
 - Follow TDD: RED → GREEN → Refactor cycle
@@ -176,25 +191,25 @@ Use `/code-review` skill checklist:
 - [ ] Error handling implemented
 </self-review>
 
-## Handoff Protocol
+## Exit Sequence
 
-**See:** `pennyfarthing-dist/guides/agent-behavior.md` → AGENT_COMMAND Protocol
-
-1. Dev writes assessment to session file FIRST
-2. Dev spawns `handoff` subagent
-3. Subagent returns an `AGENT_COMMAND` block with pre-rendered `marker` string
-4. **Dev outputs `marker` verbatim, then outputs `fallback` message**
+1. Write Dev Assessment to session file
+2. Spawn `handoff` subagent (see below)
+3. Await `HANDOFF_RESULT` with `next_agent`
+4. **Run as ABSOLUTE LAST ACTION:**
+   ```bash
+   $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {next_agent}
+   ```
+5. **Output the script result verbatim and EXIT**
 
 ## Handoff Subagent
 
-After writing assessment, spawn helper to handle bookkeeping.
-
 **First, read workflow from session file:**
 ```bash
 grep "^\*\*Workflow:\*\*" .session/{STORY_ID}-session.md | sed 's/\*\*Workflow:\*\* //'
 ```
 
-Then spawn with detected workflow (tdd, trivial, etc.):
+Then spawn:
 
 ```yaml
 Task tool:
@@ -204,28 +219,18 @@ Task tool:
     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.
+    then EXECUTE all steps described there.
 
     STORY_ID: {value}
-    WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
-    CURRENT_PHASE: green               # or "impl" for trivial workflow
+    WORKFLOW: {workflow from session}
+    CURRENT_PHASE: green  # or "impl" for trivial
     REPOS: {value}
     ASSESSMENT_SECTION: Dev Assessment
     TEST_RESULT: GREEN
     PR_NUMBER: {value}
-    BRANCH: {value}
 ```
 
-**Phase name varies by workflow:**
-- TDD workflow: `green` phase
-- Trivial workflow: `impl` phase
-
-Helper will:
-1. Verify quality gates pass (uses test cache from Story 31-8)
-2. Verify git clean, pushed, PR exists
-3. Update session with Reviewer Handoff section
-4. Determine next phase (review) and agent (Reviewer)
+Helper returns `HANDOFF_RESULT` with `next_agent: reviewer`.
 
 ## Chore Implementation
 

package/pennyfarthing-dist/agents/handoff.md

@@ -19,9 +19,9 @@ model: haiku
 </info>
 
 <critical>
-**Subagent output is NOT visible to Cyclist.** Tool results are not parsed for markers.
-You MUST return an explicit `AGENT_COMMAND` block with a pre-rendered `marker` string.
-The calling agent will output the `marker` string verbatim in their direct text output.
+**Marker generation happens in the CALLING agent, not here.**
+This subagent does gate checks and session updates only.
+Return `HANDOFF_RESULT` with the next agent name - the calling agent runs `handoff-marker.sh` as their last action.
 </critical>
 
 ---
@@ -39,7 +39,7 @@ The calling agent will output the `marker` string verbatim in their direct text
 
 <gate>
 ### tests_pass (Dev → Reviewer)
-- Quality checks pass (`check.sh`)
+- Quality checks pass (run: `.pennyfarthing/scripts/run.sh workflow/check.sh`)
 - Git working tree clean
 - Changes pushed to remote
 - PR exists and is open
@@ -131,135 +131,51 @@ No automated checks. Always passes.
    |------|-----|------|--------|-----------|
    ```
 
-6. **Generate AGENT_COMMAND block:**
-   ```bash
-   $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {NEXT_AGENT}
-   ```
-   The script handles IS_CYCLIST and USE_TIREPUMP detection automatically.
-
-   For errors:
-   ```bash
-   $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh --error "Error message here"
-   ```
-
-7. **Return handoff summary + AGENT_COMMAND block** (see Output Format below)
+6. **Return HANDOFF_RESULT** (see Output Format below)
 
 ---
 
 ## Output Format
 
-Your output MUST end with an `AGENT_COMMAND` block containing a pre-rendered `marker` string.
-The calling agent outputs the `marker` string verbatim - no parsing or mapping required.
+Return a `HANDOFF_RESULT` block. The calling agent will use this to run `handoff-marker.sh`.
 
-```
-HANDOFF COMPLETE
-
-From: {CURRENT_PHASE} ({CURRENT_AGENT})
-To: {NEXT_PHASE} ({NEXT_AGENT})
-Gate: {GATE_TYPE} - PASSED
-
-Context: {CONTEXT_PERCENT}%
-Mode: {PERMISSION_MODE}
-Cyclist: {IS_CYCLIST}
-TirePump: {USE_TIREPUMP}
+### Success Format
 
----
-AGENT_COMMAND:
-  marker: "{MARKER_STRING}"
-  fallback: "Run `/{NEXT_AGENT}` to continue"
----
 ```
-
-### Marker String Generation
-
-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}
+HANDOFF_RESULT:
+  status: success
+  next_agent: {NEXT_AGENT}
+  next_phase: {NEXT_PHASE}
+  gate: {GATE_TYPE}
 ```
 
-**Output the script result verbatim.** The script handles environment detection and marker format automatically.
-
-### Example Output (Cyclist, TirePump active)
+### Example (TEA → Dev)
 
 ```
-HANDOFF COMPLETE
-
-From: green (Dev)
-To: review (Reviewer)
-Gate: tests_pass - PASSED
-
-Context: 72%
-Mode: turbo
-Cyclist: true
-TirePump: true
-
----
-AGENT_COMMAND:
-  marker: "<!-- CYCLIST:CONTEXT_CLEAR:/reviewer -->"
-  fallback: "Run `/reviewer` to continue"
----
+HANDOFF_RESULT:
+  status: success
+  next_agent: dev
+  next_phase: green
+  gate: tests_fail
 ```
 
-### Example Output (Cyclist, no TirePump)
+### Example (Dev → Reviewer)
 
 ```
-HANDOFF COMPLETE
-
-From: red (TEA)
-To: green (Dev)
-Gate: tests_fail - PASSED
-
-Context: 35%
-Mode: accept
-Cyclist: true
-TirePump: false
-
----
-AGENT_COMMAND:
-  marker: "<!-- CYCLIST:HANDOFF:/dev -->"
-  fallback: "Run `/dev` to continue"
----
+HANDOFF_RESULT:
+  status: success
+  next_agent: reviewer
+  next_phase: review
+  gate: tests_pass
 ```
 
-### Example Output (Not Cyclist)
+### Error Format
 
 ```
-HANDOFF COMPLETE
-
-From: red (TEA)
-To: green (Dev)
-Gate: tests_fail - PASSED
-
-Context: unknown
-Mode: unknown
-Cyclist: false
-TirePump: false
-
----
-AGENT_COMMAND:
-  marker: ""
-  fallback: "Run `/dev` to continue"
----
-```
-
-## Error Format
-
-```
-HANDOFF BLOCKED
-
-Step failed: {step}
-Gate type: {gate}
-Error: {message}
-
-Recommended fix: {action}
-
----
-AGENT_COMMAND:
-  marker: ""
-  fallback: "{message}"
-  error: true
----
+HANDOFF_RESULT:
+  status: blocked
+  error: "{error message}"
+  fix: "{recommended action}"
 ```
 
 ---
@@ -274,16 +190,23 @@ AGENT_COMMAND:
 | SM | `/sm` |
 | Architect | `/architect` |
 | DevOps | `/devops` |
+| Tech-Writer | `/tech-writer` |
+| UX-Designer | `/ux-designer` |
+| PM | `/pm` |
 
 ---
 
-## Calling Agent Instructions
+## Calling Agent Exit Sequence
+
+When you receive `HANDOFF_RESULT`:
 
-When you receive this subagent's output, parse the `AGENT_COMMAND` block and:
+1. If `status: blocked` → Report the error, do NOT proceed
+2. If `status: success` → Continue to exit sequence below
 
-1. If `error: true` → Report the `fallback` message as an error, do not emit any marker
-2. Otherwise → Output the `marker` string verbatim (if non-empty), then output the `fallback` message
+**CRITICAL: The calling agent MUST run this as their ABSOLUTE LAST ACTION:**
 
-**Simple rule: Output `marker` then `fallback`. That's it.**
+```bash
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {next_agent}
+```
 
-**CRITICAL: The marker MUST appear in the calling agent's direct text output, not in a tool result.**
+Then output the script's result verbatim and EXIT. Nothing else after.

package/pennyfarthing-dist/agents/reviewer.md

@@ -72,6 +72,21 @@ From theme config. Model: haiku. Tasks: gather pre-flight data, update session f
   ```
 </helpers>
 
+<phase-check>
+## On Startup: Check Phase
+
+Read `**Workflow:**` and `**Phase:**` from session. Query phase owner:
+
+```bash
+OWNER=$($CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/run.sh workflow/phase-owner.sh {workflow} {phase})
+```
+
+**If OWNER != "reviewer":**
+1. Run: `$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh $OWNER`
+2. Output the result verbatim
+3. Tell user the story is waiting for that agent
+</phase-check>
+
 <responsibilities>
 - Security analysis (vulnerabilities, auth issues, injection risks)
 - Edge case analysis (null/empty/max values)
@@ -264,67 +279,47 @@ Write assessment to session file BEFORE spawning handoff subagent.
 **Handoff:** Back to Dev for fixes
 ```
 
-## Handoff Protocol
+## Exit Sequence
 
-**See:** `pennyfarthing-dist/guides/agent-behavior.md` → AGENT_COMMAND Protocol
-
-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**
+1. Write Reviewer Assessment to session file
+2. Spawn `handoff` subagent with VERDICT
+3. Await `HANDOFF_RESULT` with `next_agent`
+4. **Run as ABSOLUTE LAST ACTION:**
+   ```bash
+   $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {next_agent}
+   ```
+5. **Output the script result verbatim and EXIT**
 
 **Verdict routing:**
-- APPROVED → next agent is SM (`/sm`)
-- REJECTED → returns to Dev (`/dev`)
+- APPROVED → `next_agent: sm`
+- REJECTED → `next_agent: dev`
 
-Handoff subagent (generic - handles both approve and reject).
+## Handoff Subagent
 
 **First, read workflow from session file:**
 ```bash
 grep "^\*\*Workflow:\*\*" .session/{STORY_ID}-session.md | sed 's/\*\*Workflow:\*\* //'
 ```
 
-Then spawn with detected workflow:
+Then spawn:
 
 ```yaml
-# Approval
-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.
-
-    STORY_ID: {value}
-    WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
-    CURRENT_PHASE: review
-    REPOS: {value}
-    ASSESSMENT_SECTION: Reviewer Assessment
-    VERDICT: approved
-
-# Rejection
 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.
+    Read .pennyfarthing/agents/handoff.md and EXECUTE.
 
     STORY_ID: {value}
-    WORKFLOW: {workflow from session}  # e.g., "tdd" or "trivial"
+    WORKFLOW: {workflow from session}
     CURRENT_PHASE: review
     REPOS: {value}
     ASSESSMENT_SECTION: Reviewer Assessment
-    VERDICT: rejected
+    VERDICT: {approved|rejected}
 ```
 
-**Note:** Both TDD and trivial workflows have a `review` phase with the same name.
+Helper returns `HANDOFF_RESULT` with `next_agent`.
 
 ## Communication Style
 

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

@@ -14,9 +14,9 @@ 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.
+**Marker generation happens in the CALLING agent, not here.**
+This subagent verifies prerequisites and updates session file only.
+Return `HANDOFF_RESULT` with the next agent name - SM runs `handoff-marker.sh` as their last action.
 </critical>
 
 <info>
@@ -58,88 +58,65 @@ Edit `## Workflow Tracking`:
 
 **Duration:** Subtract SM Started from {NOW}, format as `Xm` or `Xh Ym`.
 
-## Generate AGENT_COMMAND Block
-
-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}
-```
-
-The script handles IS_CYCLIST and USE_TIREPUMP detection automatically.
-Output the script result verbatim.
-
 ## Output Format
 
-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.
+Return a `HANDOFF_RESULT` block. SM will use this to run `handoff-marker.sh`.
 
-```
-## Handoff Complete
+### Success Format
 
-Story {STORY_ID} ready for {NEXT_AGENT} phase.
-- Session file updated
-- Branch verified
-- Jira claimed
-
----
-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}
+HANDOFF_RESULT:
+  status: success
+  next_agent: {NEXT_AGENT}
+  next_phase: {NEXT_PHASE}
+  story_id: {STORY_ID}
+  summary: "Session updated, branch verified, Jira claimed"
 ```
 
-**Output the script result verbatim.** No manual marker lookup required.
-
-### Example Output (Cyclist, no TirePump)
+### Example (SM → TEA)
 
 ```
-## Handoff Complete
+HANDOFF_RESULT:
+  status: success
+  next_agent: tea
+  next_phase: red
+  story_id: MSSCI-12274
+  summary: "Session updated (setup → red), branch feat/MSSCI-12274-image-queue verified, 7 AC defined"
+```
 
-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
+### Example (SM → Dev, trivial workflow)
 
----
-AGENT_COMMAND:
-  marker: "<!-- CYCLIST:HANDOFF:/tea -->"
-  fallback: "Run `/tea` to continue"
----
+```
+HANDOFF_RESULT:
+  status: success
+  next_agent: dev
+  next_phase: implement
+  story_id: 46-3
+  summary: "Session updated (setup → implement), branch feat/46-3-fix-typo verified"
 ```
 
-### Example Output (Not Cyclist)
+### Error Format
 
 ```
-## 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
+HANDOFF_RESULT:
+  status: blocked
+  error: "{error message}"
+  fix: "{recommended action}"
+```
 
 ---
-AGENT_COMMAND:
-  marker: ""
-  fallback: "Run `/tea` to continue"
----
-```
 
-## Calling Agent Instructions
+## Calling Agent Exit Sequence
 
-When you receive this subagent's output, parse the `AGENT_COMMAND` block and:
+When SM receives `HANDOFF_RESULT`:
 
-1. Output the `marker` string verbatim (if non-empty)
-2. Output the `fallback` message
+1. If `status: blocked` → Report the error, do NOT proceed
+2. If `status: success` → Continue to exit sequence below
 
-**Simple rule: Output `marker` then `fallback`. That's it.**
+**CRITICAL: SM MUST run this as their ABSOLUTE LAST ACTION:**
+
+```bash
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {next_agent}
+```
 
-**The marker MUST appear in the calling agent's direct text output, not in a tool result.**
+Then output the script's result verbatim and EXIT. Nothing else after.