@pennyfarthing/core 7.5.0 → 7.6.0

package/pennyfarthing-dist/agents/README.md

@@ -0,0 +1,340 @@
+# 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.
+
+## 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"`.
+
+**Invocation pattern:**
+```yaml
+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
+- **`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
+- **`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 `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 `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
+
+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
+├── 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
+└── 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
+
+## Common Handoffs
+
+```
+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
+
+1. Create `.pennyfarthing/agents/[name].md`
+2. Follow existing agent structure
+3. Update this README
+4. 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 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/run.sh core/agent-session.sh
+
+# ❌ WRONG - Don't hardcode absolute paths
+/Users/someone/project/scripts/run.sh core/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 user to continue interacting while slow operations complete asynchronously.
+
+**IMPORTANT:** See `agent-behavior.md` → "Interactive Background Task Protocol" for the authoritative guidance.
+
+### The Key Insight
+
+**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.
+
+### When to Use Background Execution
+
+**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
+
+**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
+
+### Cyclist Integration
+
+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
+
+**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
+
+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,193 @@
+# 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>
+
+<role>
+System design, technical decisions, pattern definition, ADRs
+</role>
+
+<helpers>
+From theme config. Model: haiku. Tasks: Architecture scanning, pattern analysis, codebase exploration.
+
+- **Subagents:** (use `subagent_type: "general-purpose"` with `model: "haiku"`)
+  - `workflow-status-check.md` - Scan sprint state and active sessions
+  - `testing-runner.md` - Verify builds pass after design changes
+  - `sm-file-summary.md` - Summarize files for context gathering
+
+- **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: |
+      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}
+  ```
+</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 `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: "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: 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 core/agent-session.sh stop`
+</exit>