@pennyfarthing/core 7.4.1 → 7.5.0

package/pennyfarthing-dist/agents/README.md

@@ -1,340 +0,0 @@
-# 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

@@ -1,193 +0,0 @@
-# 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>