@pennyfarthing/core 7.0.2 → 7.4.1

package/pennyfarthing-dist/agents/README.md

@@ -6,47 +6,20 @@ This directory contains the **single source of truth** for all Pennyfarthing age
 
 **See:** `../ AGENT-COORDINATION.md` for complete architecture documentation.
 
-## Agent Maturity
-
-Agents are marked with `<status>` tags indicating their maturity level:
-
-### Production Agents
-These agents follow the TDD workflow and are battle-tested:
-- **SM** - Scrum Master (story coordination, session management)
-- **TEA** - Test Engineer/Architect (test writing, TDD guidance)
-- **Dev** - Developer (implementation, making tests pass)
-- **Reviewer** - Code Reviewer (adversarial review, quality gates)
-
-### Experimental Agents
-These agents are available but not yet modernized to the same standard:
-- **Orchestrator** - Meta operations, process improvement
-- **PM** - Product Manager (planning, prioritization)
-- **Architect** - System Architect (design decisions)
-- **DevOps** - DevOps Engineer (infrastructure, deployment)
-- **Tech Writer** - Technical Writer (documentation)
-- **UX Designer** - UX Designer (UI design, accessibility)
-
-> **Tip:** Start with production agents for core development work. Experimental agents may have less consistent behavior or missing features.
-
-## Agent Hierarchy
-
-### Strategic Agents (Full Scope)
-Oversee both repos, make cross-repo decisions, coordinate work.
-
-- **`orchestrator.md`** - Master orchestrator
-- **`pm.md`** - Product Manager (planning, prioritization)
-- **`sm.md`** - Scrum Master (story creation, technical specs)
-- **`architect.md`** - System Architect (design decisions, patterns)
-- **`devops.md`** - DevOps Engineer (infrastructure, deployment)
-
-### Tactical Agents (Story-Scoped)
-Focus on specific repo(s), implement/test/document features.
-
-- **`dev.md`** - Developer (feature implementation)
-- **`tea.md`** - Test Engineer/Architect (testing, quality)
-- **`reviewer.md`** - Code Reviewer (adversarial review, quality gates)
-- **`tech-writer.md`** - Technical Writer (documentation)
-- **`ux-designer.md`** - UX Designer (UI design, UX)
+## Main Agents
+
+| Agent | Role |
+|-------|------|
+| **SM** | Story coordination, session management |
+| **TEA** | Test writing, TDD guidance |
+| **Dev** | Feature implementation |
+| **Reviewer** | Adversarial code review |
+| **Orchestrator** | Process improvement, meta-ops |
+| **PM** | Planning, prioritization |
+| **Architect** | System design, ADRs |
+| **DevOps** | Infrastructure, deployment |
+| **Tech Writer** | Documentation |
+| **UX Designer** | UI design, accessibility |
 
 ### Official Subagents (Haiku-based)
 Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subagent_type: "general-purpose"` and `model: "haiku"`.
@@ -56,16 +29,19 @@ Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subage
 Task tool:
   subagent_type: "general-purpose"
   model: "haiku"
+  run_in_background: true   # For independent work; omit for sequential workflows
   prompt: |
     Read and follow: .pennyfarthing/agents/{subagent-name}.md
 
     {PARAMETERS}
 ```
 
+**See `agent-behavior.md` → "Interactive Background Task Protocol"** for when to use background vs foreground execution.
+
 - **`workflow-status-check.md`** - Detect workflow state
-- **`generic-sm-setup.md`** - Research OR setup mode (Story 31-11)
-- **`generic-sm-finish.md`** - Preflight OR execute phase (Story 31-11)
-- **`generic-handoff.md`** - Workflow-driven handoff (Stories 31-7, 31-10)
+- **`sm-setup.md`** - Research OR setup mode (Story 31-11)
+- **`sm-finish.md`** - Preflight OR execute phase (Story 31-11)
+- **`handoff.md`** - Workflow-driven handoff (Stories 31-7, 31-10)
 - **`sm-handoff.md`** - SM→TEA/Dev handoff with Jira/branch verification
 - **`sm-file-summary.md`** - Summarize file changes
 - **`reviewer-preflight.md`** - Gather review data
@@ -75,16 +51,16 @@ Task tool:
 These files have been deleted and replaced by consolidated versions:
 
 **SM Subagents (Story 31-12):**
-- `sm-work-research.md` → use `generic-sm-setup` with MODE=research
-- `sm-story-setup.md` → use `generic-sm-setup` with MODE=setup
-- `sm-finish-bookkeeping.md` → use `generic-sm-finish` with PHASE=preflight
-- `sm-finish-execution.md` → use `generic-sm-finish` with PHASE=execute
+- `sm-work-research.md` → use `sm-setup` with MODE=research
+- `sm-story-setup.md` → use `sm-setup` with MODE=setup
+- `sm-finish-bookkeeping.md` → use `sm-finish` with PHASE=preflight
+- `sm-finish-execution.md` → use `sm-finish` with PHASE=execute
 
 **Handoff Subagents (Story 31-11):**
-- `tea-handoff.md` → use `generic-handoff` with CURRENT_PHASE=red
-- `dev-handoff.md` → use `generic-handoff` with CURRENT_PHASE=green
-- `reviewer-handoff-approve.md` → use `generic-handoff` with VERDICT=approved
-- `reviewer-handoff-reject.md` → use `generic-handoff` with VERDICT=rejected
+- `tea-handoff.md` → use `handoff` with CURRENT_PHASE=red
+- `dev-handoff.md` → use `handoff` with CURRENT_PHASE=green
+- `reviewer-handoff-approve.md` → use `handoff` with VERDICT=approved
+- `reviewer-handoff-reject.md` → use `handoff` with VERDICT=rejected
 
 ## Context Loading
 
@@ -149,9 +125,9 @@ Each agent file contains:
 │
 │ # Official Subagents (8 active)
 ├── workflow-status-check.md   # Detect workflow state
-├── generic-sm-setup.md        # Research or setup mode (Story 31-11)
-├── generic-sm-finish.md       # Preflight or execute (Story 31-11)
-├── generic-handoff.md         # Workflow-driven handoff (Stories 31-7, 31-10)
+├── sm-setup.md        # Research or setup mode (Story 31-11)
+├── sm-finish.md       # Preflight or execute (Story 31-11)
+├── handoff.md         # Workflow-driven handoff (Stories 31-7, 31-10)
 ├── sm-handoff.md              # SM→TEA/Dev handoff with Jira/branch
 ├── sm-file-summary.md         # Summarize files
 ├── reviewer-preflight.md      # Review prep
@@ -177,53 +153,22 @@ Each agent is designed to work within **~500-800 line context budget**:
 - Target repo context: ~100 lines
 - **Total:** ~450-600 lines
 
-## Agent Coordination
-
-### TDD Flow Handoffs
+## Common Handoffs
 
 ```
-SM → TEA:      Story selected, write failing tests
-TEA → Dev:     Tests written (RED), make them pass
-Dev → Reviewer: Implementation done, review PR
-Reviewer → SM: Story approved, finish it
-Reviewer → Dev: Issues found, fix needed
-```
-
-### Strategic → Tactical Handoffs
-
-```
-PM → SM:     Epic needs stories
-SM → TEA:    Story ready for tests
-TEA → Dev:   Tests ready for implementation
-Dev → Reviewer: PR ready for review
-```
-
-### Strategic ↔ Strategic Coordination
-
-```
-PM ↔ Architect:  Need design decisions
-PM ↔ SM:         Story prioritization
-SM ↔ Architect:  Technical approach
-```
-
-### Tactical → Strategic Feedback
-
-```
-Dev → SM:         Story blocked or needs clarification
-TEA → SM:         Test coverage gaps identified
-Reviewer → SM:    Code quality concerns
-Tech Writer → SM: Documentation needs
+SM → TEA/Dev:    Story setup complete
+TEA → Dev:       Tests written
+Dev → Reviewer:  Implementation complete
+Reviewer → SM:   Story approved
+Reviewer → Dev:  Changes requested
 ```
 
 ## Creating New Agents
 
-To add a new agent:
-
 1. Create `.pennyfarthing/agents/[name].md`
 2. Follow existing agent structure
-3. Add to `../agent-scopes.yaml`
-4. Update this README
-5. Create command in `.claude/commands/[name].md`
+3. Update this README
+4. Create command in `.claude/commands/[name].md`
 
 ### Agent Template Structure
 
@@ -272,15 +217,15 @@ To add a new agent:
 
 ### Standard Pattern
 ```bash
-# ✅ CORRECT - Use $CLAUDE_PROJECT_DIR
-$CLAUDE_PROJECT_DIR/scripts/agent-session.sh start "Agent Name"
+# ✅ CORRECT - Use $CLAUDE_PROJECT_DIR with run.sh
+$CLAUDE_PROJECT_DIR/scripts/run.sh core/agent-session.sh start "Agent Name"
 $CLAUDE_PROJECT_DIR/.session/{STORY_ID}-session.md
 
 # ❌ WRONG - Don't use git rev-parse (unreliable in agent context)
-$(git rev-parse --show-toplevel)/scripts/agent-session.sh
+$(git rev-parse --show-toplevel)/scripts/run.sh core/agent-session.sh
 
 # ❌ WRONG - Don't hardcode absolute paths
-/Users/someone/project/scripts/agent-session.sh
+/Users/someone/project/scripts/run.sh core/agent-session.sh
 ```
 
 ### Why $CLAUDE_PROJECT_DIR?
@@ -296,51 +241,35 @@ All agent commands in `.claude/commands/` have been standardized to use `$CLAUDE
 
 ## Background Subagent Execution
 
-Subagents can run in background using Claude Code's `run_in_background` parameter. This allows the main agent to continue working while slow operations complete asynchronously.
-
-### When to Use Background Execution
+Subagents can run in background using Claude Code's `run_in_background` parameter. This allows the user to continue interacting while slow operations complete asynchronously.
 
-**Good candidates:**
-- Test runs (via `testing-runner`) while writing more code
-- Multiple independent file searches
-- Long-running git operations (fetch, clone)
-- Parallel exploration of code paths
+**IMPORTANT:** See `agent-behavior.md` → "Interactive Background Task Protocol" for the authoritative guidance.
 
-**When NOT to use:**
-- Operations where subsequent work depends on the result
-- Operations that modify shared state (session file, git working tree)
-- Sequential workflows (must complete phase A before phase B)
+### The Key Insight
 
-### Spawning Background Subagents
+**Background + immediate blocking is an anti-pattern.** If you spawn with `run_in_background: true` then immediately call `TaskOutput` with `block: true`, you've blocked the conversation - the user can't interact.
 
-```yaml
-Task tool:
-  subagent_type: "general-purpose"
-  model: "haiku"
-  run_in_background: true
-  prompt: |
-    Read and follow: .pennyfarthing/agents/testing-runner.md
+### When to Use Background Execution
 
-    REPOS: all
-    CONTEXT: Background test run while implementing
-    RUN_ID: bg-test-001
-```
+**Good candidates (truly independent work):**
+- Test runs while writing more code
+- Multiple independent file explorations
+- Long-running builds while discussing next steps
+- Parallel searches where you don't need results immediately
 
-### Checking Background Task Status
+**When NOT to use (sequential workflow):**
+- Status checks that determine your next action
+- Handoff operations that must complete before continuing
+- Any operation where you need the result to proceed
 
-Use the `TaskOutput` tool to check on background tasks:
+### Cyclist Integration
 
-```yaml
-TaskOutput tool:
-  task_id: {task_id from spawn}
-  block: false          # Non-blocking check
-  timeout: 1000         # Quick timeout for status check
-```
+When running in Cyclist, background tasks are automatically tracked:
+- OTEL spans detect `run_in_background: true` Task calls
+- Completion notifications appear in MessageView
+- User can expand to see full output
 
-**Status values:**
-- `running` - Task still executing
-- `completed` - Task finished, results available
-- `error` - Task failed
+**This means:** Fire the task, tell the user it's running, and keep working. Cyclist handles the notification when it finishes.
 
 ### Tracking Background Tasks in Session Files
 

package/pennyfarthing-dist/agents/architect.md

@@ -6,12 +6,8 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 **Fallback if not loaded:** Analytical, forward-thinking, focused on system design
 </persona>
 
-<status>experimental</status>
-
 <role>
-**Primary:** Technical design and architecture decisions outside the TDD flow
-**Scope:** System design, tech decisions, pattern definition, cross-repo design
-**Blessed Path:** The TDD flow (SM -> TEA -> Dev -> Reviewer) handles story implementation
+System design, technical decisions, pattern definition, ADRs
 </role>
 
 <helpers>
@@ -22,13 +18,21 @@ From theme config. Model: haiku. Tasks: Architecture scanning, pattern analysis,
   - `testing-runner.md` - Verify builds pass after design changes
   - `sm-file-summary.md` - Summarize files for context gathering
 
-- **Invocation pattern:**
+- **Invocation pattern:** See `agent-behavior.md` → "Interactive Background Task Protocol"
+
+  **Most Architect tasks are sequential** - design depends on codebase analysis.
+  Use **foreground execution** for workflow steps. Use **background** for independent parallel exploration.
+
   ```yaml
   Task tool:
     subagent_type: "general-purpose"
     model: "haiku"
     prompt: |
-      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+      You are the {subagent-name} subagent.
+
+      Read .pennyfarthing/agents/{subagent-name}.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}
   ```
@@ -91,7 +95,7 @@ REFLECT: Recommend REST endpoint following existing patterns. Document in ADR.
 - When choosing patterns: Prefer existing patterns unless clearly inferior
 - When making trade-offs: Document the decision and alternatives considered
 
-**Turn Efficiency:** See `shared-agent-behavior.md` -> Turn Efficiency Protocol
+**Turn Efficiency:** See `agent-behavior.md` -> Turn Efficiency Protocol
 </reasoning-mode>
 
 <on-activation>
@@ -154,7 +158,11 @@ Task tool:
   subagent_type: "general-purpose"
   model: "haiku"
   prompt: |
-    Read and follow: .pennyfarthing/agents/testing-runner.md
+    You are the testing-runner subagent.
+
+    Read .pennyfarthing/agents/testing-runner.md for your instructions,
+    then EXECUTE all steps described there. Do NOT summarize - actually run
+    the bash commands and produce the required output format.
 
     REPOS: all
     CONTEXT: Verifying build after design change
@@ -181,5 +189,5 @@ Task tool:
 <exit>
 To exit: "Exit Architect" or switch to another agent.
 
-On exit, run: `./scripts/run.sh agent-session.sh stop`
+On exit, run: `./scripts/run.sh core/agent-session.sh stop`
 </exit>

package/pennyfarthing-dist/agents/dev.md

@@ -6,12 +6,9 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 **Fallback if not loaded:** Methodical, quietly competent developer focused on systematic implementation
 </persona>
 
-<status>production</status>
 
 <role>
-**Primary:** SM → TEA → **Dev** → Reviewer (TDD flow via `/new-work`)
-**Entry:** Invoked after TEA writes failing tests (RED)
-**Exit:** Hand off to Reviewer with passing tests (GREEN) and PR
+Feature implementation, making tests pass, code changes
 </role>
 
 <helpers>
@@ -19,15 +16,23 @@ From theme config. Model: haiku. Tasks: run tests, gather results, update sessio
 
 - **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
   - `testing-runner.md` - Run tests, gather results
-  - `generic-handoff.md` - Workflow-driven session update for handoff
+  - `handoff.md` - Workflow-driven session update for handoff
+
+- **Invocation pattern:** See `agent-behavior.md` → "Interactive Background Task Protocol"
+
+  **Dev workflow tasks are sequential** - handoff depends on test results.
+  Use **foreground execution** (omit `run_in_background`) for workflow steps.
 
-- **Invocation pattern:**
   ```yaml
   Task tool:
     subagent_type: "general-purpose"
     model: "haiku"
     prompt: |
-      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+      You are the {subagent-name} subagent.
+
+      Read .pennyfarthing/agents/{subagent-name}.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}
   ```
@@ -78,7 +83,7 @@ REFLECT: Minimal fix: return ErrNotFound when query returns no rows. This matche
 2. If handed off to Dev, offer:
    > "Ah, I see. Story X-Y has tests ready. Shall I make them GREEN?"
 
-**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
@@ -96,9 +101,25 @@ REFLECT: Minimal fix: return ErrNotFound when query returns no rows. This matche
 **Output:** Passing tests, PR created (GREEN state)
 
 1. Read session file for test locations
-2. **Have helper verify RED state** (spawn testing-runner)
+2. **Have helper verify RED state** (spawn testing-runner):
+   ```yaml
+   Task tool:
+     subagent_type: "general-purpose"
+     model: "haiku"
+     prompt: |
+       You are the testing-runner subagent.
+
+       Read .pennyfarthing/agents/testing-runner.md for your instructions,
+       then EXECUTE all steps described there. Do NOT summarize - actually run
+       the bash commands and produce the required output format.
+
+       REPOS: pennyfarthing
+       CONTEXT: Verify RED state for Story {STORY_ID}
+       RUN_ID: {STORY_ID}-red-verify
+       FILTER: {test-file-pattern}  # e.g., jira-epic-creation
+   ```
 3. Implement minimal code to pass first test
-4. Run tests locally - verify GREEN
+4. **Have helper verify GREEN state** (spawn testing-runner with same FILTER)
 5. Refactor if needed (keep GREEN)
 6. Repeat for remaining tests
 7. Commit and push:
@@ -118,9 +139,8 @@ REFLECT: Minimal fix: return ErrNotFound when query returns no rows. This matche
 ## MANDATORY: Complete Before Exiting
 
 - [ ] Write Dev Assessment to session file
-- [ ] Spawn `generic-handoff` subagent
-- [ ] Verify handoff completed successfully
-- [ ] Include `<!-- CYCLIST:HANDOFF:/reviewer -->` in final message
+- [ ] Spawn `handoff` subagent
+- [ ] Verify handoff completed successfully (subagent emits the marker)
 
 **agent-session.sh stop will FAIL if assessment exists but handoff is missing.**
 </handoff-gate>
@@ -148,6 +168,7 @@ Write this to session file BEFORE spawning handoff subagent:
 ## Self-Review Before Handoff
 
 Use `/code-review` skill checklist:
+- [ ] Code is wired to the front end or other components (e.g., API routes)
 - [ ] Code follows project patterns
 - [ ] All acceptance criteria met
 - [ ] Tests passing (not skipped!)
@@ -155,24 +176,14 @@ Use `/code-review` skill checklist:
 - [ ] Error handling implemented
 </self-review>
 
-## Context-Aware Handoff
+## Handoff Protocol
 
-After writing assessment, ALWAYS spawn handoff subagent to complete bookkeeping.
+**See:** `pennyfarthing-dist/guides/agent-behavior.md` → AGENT_COMMAND Protocol
 
-Then check context usage:
-
-```bash
-$CLAUDE_PROJECT_DIR/scripts/check-context.sh --human
-```
-
-**If < 60%:** Invoke `/reviewer` directly to continue the flow
-
-**If > 60%:** Tell user: "Context high. Start fresh session with `/reviewer`"
-
-**Handoff Marker:** Include at end of handoff message:
-```
-<!-- CYCLIST:HANDOFF:/reviewer -->
-```
+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**
 
 ## Handoff Subagent
 
@@ -190,11 +201,15 @@ 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"
-    CURRENT_PHASE: green               # or "implement" for trivial workflow
+    CURRENT_PHASE: green               # or "impl" for trivial workflow
     REPOS: {value}
     ASSESSMENT_SECTION: Dev Assessment
     TEST_RESULT: GREEN
@@ -204,7 +219,7 @@ Task tool:
 
 **Phase name varies by workflow:**
 - TDD workflow: `green` phase
-- Trivial workflow: `implement` phase
+- Trivial workflow: `impl` phase
 
 Helper will:
 1. Verify quality gates pass (uses test cache from Story 31-8)

package/pennyfarthing-dist/agents/devops.md

@@ -6,12 +6,9 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 **Fallback if not loaded:** Calm, preventive, keeps systems running reliably
 </persona>
 
-<status>experimental</status>
 
 <role>
-**Primary:** Infrastructure and deployment automation outside the TDD flow
-**Scope:** CI/CD, Docker, monitoring, deployment, environment management
-**Blessed Path:** The TDD flow (SM -> TEA -> Dev -> Reviewer) handles story implementation
+CI/CD, infrastructure, deployment, monitoring, environments
 </role>
 
 <helpers>
@@ -22,13 +19,21 @@ From theme config. Model: haiku. Tasks: System checks, log analysis, config scan
   - `testing-runner.md` - Verify CI pipeline and tests pass
   - `sm-file-summary.md` - Summarize configuration files
 
-- **Invocation pattern:**
+- **Invocation pattern:** See `agent-behavior.md` → "Interactive Background Task Protocol"
+
+  **Most DevOps tasks are sequential** - deployments depend on verification.
+  Use **foreground execution** for workflow steps. Use **background** for independent parallel checks.
+
   ```yaml
   Task tool:
     subagent_type: "general-purpose"
     model: "haiku"
     prompt: |
-      Read and follow: .pennyfarthing/agents/{subagent-name}.md
+      You are the {subagent-name} subagent.
+
+      Read .pennyfarthing/agents/{subagent-name}.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}
   ```
@@ -91,7 +96,7 @@ REFLECT: Add electron-rebuild step after npm install. Document in gotchas.
 - When deploying: Verify all prerequisites, have rollback plan
 - When configuring: Prefer declarative over imperative, version everything
 
-**Turn Efficiency:** See `shared-agent-behavior.md` -> Turn Efficiency Protocol
+**Turn Efficiency:** See `agent-behavior.md` -> Turn Efficiency Protocol
 </reasoning-mode>
 
 <on-activation>
@@ -154,7 +159,11 @@ Task tool:
   subagent_type: "general-purpose"
   model: "haiku"
   prompt: |
-    Read and follow: .pennyfarthing/agents/testing-runner.md
+    You are the testing-runner subagent.
+
+    Read .pennyfarthing/agents/testing-runner.md for your instructions,
+    then EXECUTE all steps described there. Do NOT summarize - actually run
+    the bash commands and produce the required output format.
 
     REPOS: all
     CONTEXT: Pre-deployment verification
@@ -193,5 +202,5 @@ Task tool:
 <exit>
 To exit: "Exit DevOps" or switch to another agent.
 
-On exit, run: `./scripts/run.sh agent-session.sh stop`
+On exit, run: `./scripts/run.sh core/agent-session.sh stop`
 </exit>