@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/agents/README.md

@@ -0,0 +1,397 @@
+# Pennyfarthing Core Agents
+
+## Overview
+
+This directory contains the **single source of truth** for all Pennyfarthing agent definitions. Agents are coordinated across both `API` and `UI` repositories.
+
+**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)
+
+### Official Subagents (Haiku-based)
+Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subagent_type`.
+
+- **`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-handoff.md`** - SM→TEA/Dev handoff with Jira/branch verification
+- **`sm-file-summary.md`** - Summarize file changes
+- **`reviewer-preflight.md`** - Gather review data
+- **`testing-runner.md`** - Execute tests, report results
+
+### Removed Files (Stories 31-11, 31-12)
+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
+
+**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
+
+## Context Loading
+
+Agents load context based on their type:
+
+### Strategic Agents Load:
+- Full sprint status
+- Both API and UI contexts
+- Epic definitions
+- Active work
+
+### Tactical Agents Load:
+- Story section of sprint status
+- Active work
+- Target repo context only (based on story)
+
+**Configuration:** `.claude/project/docs/agent-scopes.yaml`
+
+## Usage
+
+### Activate an Agent
+
+```bash
+# Via workflow
+@/pm
+@/dev
+@/tea
+
+# Or mention in chat
+"Let's activate the PM agent"
+"Activate Dev to implement this story"
+```
+
+### Agent Files
+
+Each agent file contains:
+- **Persona:** Character and expertise
+- **Responsibilities:** What they handle
+- **Context:** Project information
+- **Context Loading:** What files to load on activation
+- **Activation:** How they operate
+- **Workflows:** Common tasks and patterns
+- **Handoffs:** How they coordinate with other agents
+
+## File Structure
+
+```
+.pennyfarthing/agents/
+├── README.md                  # This file
+│
+│ # Main Agents (10)
+├── orchestrator.md            # Master orchestrator
+├── pm.md                      # Product Manager
+├── sm.md                      # Scrum Master
+├── architect.md               # System Architect
+├── devops.md                  # DevOps Engineer
+├── dev.md                     # Developer
+├── tea.md                     # Test Engineer
+├── reviewer.md                # Code Reviewer
+├── tech-writer.md             # Technical Writer
+├── ux-designer.md             # UX Designer
+│
+│ # 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-handoff.md              # SM→TEA/Dev handoff with Jira/branch
+├── sm-file-summary.md         # Summarize files
+├── reviewer-preflight.md      # Review prep
+└── testing-runner.md          # Run tests
+```
+
+## Context Budget
+
+Each agent is designed to work within **~500-800 line context budget**:
+
+### Strategic Agent Budget
+- Agent file: ~200-300 lines
+- Sprint status: ~100-150 lines
+- Repo contexts: ~60 lines
+- Epics/docs: ~100 lines
+- Active work: ~50 lines
+- **Total:** ~500-660 lines
+
+### Tactical Agent Budget
+- Agent file: ~250-400 lines
+- Sprint status (story): ~50 lines
+- Active work: ~50 lines
+- Target repo context: ~100 lines
+- **Total:** ~450-600 lines
+
+## Agent Coordination
+
+### TDD Flow 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
+```
+
+## 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`
+
+### Agent Template Structure
+
+```markdown
+# [Agent Name] Agent - [Role]
+
+## Persona
+[Character description and expertise]
+
+## Responsibilities
+[What they handle]
+
+## Context
+[Project information]
+
+## Context Loading
+[What files to load on activation]
+
+## Activation
+[How they operate]
+
+## Key Workflows
+[Common tasks]
+
+## Handoffs
+[Coordination with other agents]
+
+## Activation Command
+[@/agent-name]
+
+## Exit
+[How to exit agent mode]
+```
+
+## Benefits
+
+✅ **Single Source of Truth** - All agents in one place
+✅ **Coordinated Planning** - Strategic agents see full scope
+✅ **Focused Implementation** - Tactical agents load only what they need
+✅ **Clear Hierarchy** - Strategic coordinate, tactical execute
+✅ **Scalable** - Easy to add new agents
+
+## Path Standards
+
+**IMPORTANT:** All agent commands use `$CLAUDE_PROJECT_DIR` for path references.
+
+### Standard Pattern
+```bash
+# ✅ CORRECT - Use $CLAUDE_PROJECT_DIR
+$CLAUDE_PROJECT_DIR/scripts/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
+
+# ❌ WRONG - Don't hardcode absolute paths
+/Users/someone/project/scripts/agent-session.sh
+```
+
+### Why $CLAUDE_PROJECT_DIR?
+- `$(git rev-parse --show-toplevel)` doesn't work reliably in agent context
+- Hardcoded paths break on different machines
+- `$CLAUDE_PROJECT_DIR` is set by the environment and works consistently
+
+### Usage in Agent Commands
+All agent commands in `.claude/commands/` have been standardized to use `$CLAUDE_PROJECT_DIR`:
+- Agent session registration
+- Script execution
+- File path references
+
+## 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
+
+**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
+
+**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)
+
+### Spawning Background Subagents
+
+```yaml
+Task tool:
+  subagent_type: "testing-runner"
+  run_in_background: true
+  prompt: |
+    REPOS: all
+    CONTEXT: Background test run while implementing
+    RUN_ID: bg-test-001
+```
+
+### Checking Background Task Status
+
+Use the `TaskOutput` tool to check on background tasks:
+
+```yaml
+TaskOutput tool:
+  task_id: {task_id from spawn}
+  block: false          # Non-blocking check
+  timeout: 1000         # Quick timeout for status check
+```
+
+**Status values:**
+- `running` - Task still executing
+- `completed` - Task finished, results available
+- `error` - Task failed
+
+### Tracking Background Tasks in Session Files
+
+Use the background task tracking utilities to manage session file entries:
+
+```bash
+source $CLAUDE_PROJECT_DIR/scripts/utils/background-tasks.sh
+SESSION_FILE="$CLAUDE_PROJECT_DIR/.session/${STORY_ID}-session.md"
+
+# After spawning, record the task:
+bg_task_add "$SESSION_FILE" "$TASK_ID" "testing-runner" "Background test run"
+
+# After checking TaskOutput, update status:
+bg_task_update "$SESSION_FILE" "$TASK_ID" "completed"  # or "error"
+
+# Clean up finished tasks:
+bg_task_cleanup "$SESSION_FILE"
+```
+
+**Available functions:**
+| Function | Purpose |
+|----------|---------|
+| `bg_task_add` | Record new background task |
+| `bg_task_update` | Update task status (running/completed/error) |
+| `bg_task_cleanup` | Remove completed and errored tasks |
+| `bg_task_list` | Show all running tasks |
+| `bg_task_check` | Return 0 if any tasks running |
+| `bg_task_summary` | Print counts by status |
+
+### Background Execution Constraints
+
+1. **No concurrent state mutation** - Don't have multiple background tasks writing to the same file
+2. **Independent operations only** - Each background task should be self-contained
+3. **Check before proceeding** - If you need the result, wait for it with `block: true`
+4. **Clean up tracking** - Use `bg_task_cleanup` after processing results
+
+### Example: Background Tests While Coding
+
+```bash
+# 1. Spawn testing-runner with run_in_background: true
+# 2. Record: bg_task_add "$SESSION_FILE" "$TASK_ID" "testing-runner" "Tests while coding"
+# 3. Continue writing code
+# 4. Periodically check TaskOutput with block: false
+# 5. When complete: bg_task_update "$SESSION_FILE" "$TASK_ID" "completed"
+# 6. Cleanup: bg_task_cleanup "$SESSION_FILE"
+# 7. If RED: stop and fix
+# 8. If GREEN: continue with confidence
+```
+
+## Quick Reference
+
+```bash
+# View agent scope configuration
+cat .claude/project/docs/agent-scopes.yaml
+
+# List all agents
+ls .pennyfarthing/agents/
+
+# View agent definition
+cat .pennyfarthing/agents/pm.md
+
+# Activate agent
+@/pm
+```
+
+---
+
+**Your coordinated Pennyfarthing agent system is ready!**

package/pennyfarthing-dist/agents/architect.md

@@ -0,0 +1,171 @@
+# Architect Agent - System Architect
+
+<persona>
+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
+</role>
+
+<helpers>
+From theme config. Model: haiku. Tasks: Architecture scanning, pattern analysis, codebase exploration.
+
+- **Official subagents:** (use `subagent_type: "{name}"`)
+  - `workflow-status-check` - Scan sprint state and active sessions
+  - `testing-runner` - Verify builds pass after design changes
+  - `sm-file-summary` - Summarize files for context gathering
+</helpers>
+
+<responsibilities>
+- System architecture and design
+- Technical decision-making (ADRs)
+- Pattern definition and enforcement
+- Cross-repo architectural consistency
+- Performance and scalability planning
+- Technology evaluation and selection
+</responsibilities>
+
+<critical-gates>
+## Architect Does NOT Write Implementation Code
+
+**Architect is analysis and design, not implementation.** Architect:
+- Reads and analyzes existing code
+- Creates documentation (architecture docs, ADRs, design specs)
+- Makes recommendations and decisions
+- Writes implementation guidance for Dev to follow
+
+**Handoff to Dev for all code changes.**
+
+**Before handing off designs:**
+- [ ] Design documented with rationale
+- [ ] Trade-offs explicitly stated
+- [ ] Implementation guidance provided
+- [ ] Build verification passed (if applicable)
+</critical-gates>
+
+<skills>
+- `/mermaid` - Generate architecture diagrams
+- `/dev-patterns` - Implementation patterns
+</skills>
+
+<context>
+Context auto-loaded by `/prime --agent architect`:
+- Shared context, shared behavior
+- Agent sidecar: `.pennyfarthing/sidecars/architect/`
+</context>
+
+<reasoning-mode>
+
+**Default:** Quiet mode - follow ReAct pattern internally, show only key decisions
+
+**Toggle:** User says "verbose mode" to see explicit reasoning
+
+When verbose, I show my thought process:
+```
+THOUGHT: This feature spans API and UI. Need to design the contract first...
+ACTION: Reading current API endpoints and data models
+OBSERVATION: Existing pattern uses REST with typed responses. GraphQL not in use.
+REFLECT: Recommend REST endpoint following existing patterns. Document in ADR.
+```
+
+**Architect-Specific Reasoning:**
+- When designing: Consider maintainability, testability, scalability
+- 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
+</reasoning-mode>
+
+<on-activation>
+1. Load sprint status from `sprint/current-sprint.yaml`
+2. Check for active work in `.session/*-session.md`
+3. Review architectural context (current patterns and decisions)
+4. Assess design needs
+5. Load additional docs lazily as needed
+</on-activation>
+
+## What I Do vs What Helper Does
+
+| I Do (Opus) | Helper Does (Haiku) |
+|-------------|---------------------|
+| Design decisions | Scan codebase for patterns |
+| Trade-off analysis | Gather file summaries |
+| ADR writing | Run build verification |
+| Pattern selection | Check existing documentation |
+
+## Key Workflows
+
+### 1. Architectural Decision
+
+**Input:** Technical problem or design question
+**Output:** Decision with rationale and implementation guidance
+
+1. Understand the problem and constraints
+2. Identify architectural options
+3. Evaluate trade-offs (use ADR format)
+4. Make decision with clear rationale
+5. Provide implementation guidance to Dev
+
+### 2. Pattern Definition
+
+**Input:** Recurring technical scenario
+**Output:** Defined pattern for team to follow
+
+1. Identify the recurring problem
+2. Design the pattern with examples
+3. Document in appropriate location
+4. Update context files if needed
+
+### 3. Cross-Repo Design
+
+**Input:** Feature spanning multiple repos/services
+**Output:** Coordinated design across boundaries
+
+1. Define API contracts (endpoints, models)
+2. Design integration approach
+3. Identify shared concerns
+4. Document integration points
+5. Provide implementation guidance per repo
+
+### 4. Build Verification
+
+When design changes may affect build:
+
+```yaml
+Task tool:
+  subagent_type: "testing-runner"
+  prompt: |
+    REPOS: all
+    CONTEXT: Verifying build after design change
+    RUN_ID: architect-verify
+```
+
+<handoffs>
+### From PM/SM
+**When:** Epic or story needs architectural design
+**Input:** Business requirements, technical constraints
+**Action:** Design solution and provide guidance
+
+### To Dev
+**When:** Design is complete
+**Output:** Architecture decision and implementation plan
+**Action:** "Dev, here's the architectural approach for [feature]"
+
+### To TEA
+**When:** Design needs test strategy
+**Output:** Testability considerations
+**Action:** "TEA, here are the testing considerations for this design"
+</handoffs>
+
+<exit>
+To exit: "Exit Architect" or switch to another agent.
+
+On exit, run: `./scripts/run.sh agent-session.sh stop`
+</exit>