@pennyfarthing/core 7.4.1 → 7.5.0

package/pennyfarthing-dist/guides/AGENT-COORDINATION.md

@@ -1,480 +0,0 @@
-# Pennyfarthing Agent Coordination Architecture
-
-## Overview
-
-This document describes how Pennyfarthing agents are coordinated. The framework supports both single-repo and multi-repo projects.
-
-**Key Principle:** Single entry point (`/new-work` or `/work`), state detection via session files, handoffs via Haiku subagents.
-
-## The TDD Flow
-
-```
-/new-work → SM → TEA → Dev → Reviewer → SM (finish)
-              │     │     │        │
-           setup  tests  impl   review
-              │     │     │        │
-              └─────┴─────┴────────┘
-                 subagent handoffs
-```
-
-**Entry points:** `/new-work` (new story) or `/work` (smart resume/start)
-**State detection:** Agents read session file on activation
-**Handoffs:** Agents spawn Haiku subagents to update session file
-**Finish:** SM handles when status = `approved`
-
-## Architecture Principles
-
-### 1. Single Source of Truth
-- **Agent definitions:** `.pennyfarthing/agents/`
-- **Subagent prompts:** `.pennyfarthing/agents/`
-- **Scope configuration:** `.pennyfarthing/guides/agent-scopes.yaml`
-- **Sprint tracking:** `sprint/current-sprint.yaml`
-- **Session state:** `.session/{STORY_ID}-session.md`
-
-### 2. Hierarchical Agent Structure
-```
-Strategic Agents (Full Scope)
-├── orchestrator  → Orchestrates everything
-├── pm           → Plans across all repos
-├── architect    → Designs across all repos
-└── devops       → Infrastructure and deployment
-
-Tactical Agents (Story-Scoped) - THE TDD FLOW
-├── sm           → Story setup and finish
-├── tea          → Write failing tests (RED)
-├── dev          → Implement to GREEN, create PR
-└── reviewer     → Adversarial code review
-
-Support Agents
-├── tech-writer  → Documentation
-└── ux-designer  → UI design
-```
-
-### 3. Context Loading Strategy
-- **Strategic agents** load full project context (both repos)
-- **Tactical agents** load only target repo context based on active story
-- **Context budget** kept under 500-800 lines per agent
-- **Lazy loading** - load docs only when specific task requires them
-
-## Directory Structure
-
-```
-/$CLAUDE_PROJECT_DIR/
-├── .claude/                              # Pennyfarthing coordination directory
-│   ├── agents/                         # Agent definitions (symlinks to pennyfarthing-dist)
-│   │   ├── orchestrator.md             # Master orchestrator
-│   │   ├── pm.md                       # Product Manager
-│   │   ├── sm.md                       # Scrum Master (+ sm-*.md subagents)
-│   │   ├── architect.md                # System Architect
-│   │   ├── dev.md                      # Developer (+ dev-handoff.md)
-│   │   ├── tea.md                      # Test Engineer (+ tea-handoff.md)
-│   │   ├── reviewer.md                 # Code Reviewer (+ reviewer-*.md subagents)
-│   │   ├── tech-writer.md              # Technical Writer
-│   │   ├── ux-designer.md              # UX Designer
-│   │   └── devops.md                   # DevOps Engineer
-│   │
-│   ├── commands/                       # 42 slash commands (symlinks)
-│   ├── guides/                         # Behavior guides (symlinks)
-│   ├── skills/                         # 18+ knowledge domain skills (symlinks)
-│   ├── scripts/                        # Utility scripts (symlinks)
-│   │
-│   ├── project/                        # Project-specific overrides
-│   │   ├── agents/                     # Agent sidecars (patterns, gotchas, decisions)
-│   │   └── commands/                   # Custom project commands
-│   │
-│   ├── persona-config.yaml             # Project default theme (shared with team)
-│   └── CLAUDE.md                       # Project instructions
-│
-├── .session/                           # Active work sessions
-│   └── {story-id}-session.md           # Session files (one per story)
-│
-├── sprint/                             # Sprint tracking
-│   ├── current-sprint.yaml             # Active sprint and stories
-│   ├── context/                        # Epic technical context
-│   ├── archive/                        # Completed sprints
-│   └── sidecars/                       # Agent learning files
-│
-└── pennyfarthing-dist/                 # Source of truth (if Pennyfarthing project itself)
-    ├── agents/                         # 10 main agents + 14 subagents
-    ├── commands/                       # 42 slash commands
-    ├── guides/                         # Behavior guides and patterns
-    ├── skills/                         # Knowledge domain skills
-    ├── personas/themes/                # 102 themed personas
-    └── scripts/                        # Utility scripts
-```
-
-## Agent Types
-
-### Strategic Agents (Full Scope)
-
-**Characteristics:**
-- See entire project (both repos)
-- Load all context on activation
-- Make cross-repo decisions
-- Coordinate work across repos
-
-**Agents:**
-- **Pennyfarthing Master:** Orchestrates all agents and workflows
-- **PM:** Plans sprints, prioritizes epics, manages backlog
-- **SM:** Creates stories, adds technical context, validates readiness
-- **Architect:** Makes design decisions, defines patterns, ensures consistency
-
-**Context Loading:**
-```yaml
-On Activation:
-  1. sprint/sprint-status.yaml     # Full sprint status
-  2. API/.claude/context.md      # API context
-  3. UI/.claude/context.md       # UI context
-  4. API/docs/epics.md         # Epic definitions (PM only)
-  5. .session/{STORY_ID}-session.md        # Active work
-```
-
-### Tactical Agents (Story-Scoped)
-
-**Characteristics:**
-- Focus on specific repo(s)
-- Load context based on active story
-- Implement/test/document specific features
-- Narrow, deep expertise
-
-**Agents:**
-- **Dev:** Implements features in target repo
-- **TEA:** Tests features in target repo
-- **Tech Writer:** Documents features in target repo
-- **UX Designer:** Designs UI interfaces (UI only)
-
-**Context Loading:**
-```yaml
-On Activation:
-  1. sprint/sprint-status.yaml     # Current sprint (story section)
-  2. .session/{STORY_ID}-session.md        # Active story
-  3. Determine target repo from story "Repos:" field
-  4. Load target repo context:
-     - If API:  API/.claude/context.md
-     - If UI:   UI/.claude/context.md
-     - If Both: Load both contexts
-```
-
-## Context Files
-
-### Base Directory Context
-
-#### `sprint/sprint-status.yaml`
-**Purpose:** Unified sprint tracking for all stories
-**Size:** ~100-200 lines
-**Loaded By:** All agents
-**Content:**
-- Sprint goals
-- All stories (API, UI, Both)
-- Story status (backlog, in-progress, review, done)
-- Story metadata (repos, priority, points, files)
-
-#### `.session/{STORY_ID}-session.md`
-**Purpose:** Current work session context
-**Size:** ~50-100 lines
-**Loaded By:** All agents
-**Content:**
-- Active story ID
-- Target repo(s)
-- Story context
-- Progress notes
-- Done checklist
-
-### Repository Context
-
-#### `API/.claude/context.md`
-**Purpose:** API-specific patterns and structure
-**Size:** ~30-50 lines
-**Loaded By:** Strategic agents + Dev/TEA when working on API
-**Content:**
-- Tech stack (Go, PostgreSQL, MongoDB, Redis)
-- Key patterns (Repository, DI, REST, Middleware)
-- Project structure
-- Quick links to key directories
-
-#### `UI/.claude/context.md`
-**Purpose:** UI-specific patterns and structure
-**Size:** ~30-50 lines
-**Loaded By:** Strategic agents + Dev/TEA/UX when working on UI
-**Content:**
-- Tech stack (React, TypeScript, TailwindCSS)
-- Key patterns (Components, Hooks, Context API)
-- Project structure
-- Quick links to key directories
-
-### Documentation
-
-#### `API/docs/epics.md`
-**Purpose:** All epic definitions for API
-**Size:** ~800+ lines (load summary only)
-**Loaded By:** PM, Architect
-**Content:**
-- Epic descriptions
-- Story breakdowns
-- Technical context
-- Dependencies
-
-## Agent Activation Protocol
-
-### Step 1: Load Agent Definition
-```
-Read: .pennyfarthing/agents/[agent].md
-Identify: Strategic or Tactical agent type
-```
-
-### Step 2: Load Base Context
-```
-Load files from agent-scopes.yaml:
-  - Sprint status
-  - Active work (if exists)
-  - Repo contexts (based on agent type)
-```
-
-### Step 3: Determine Scope (Tactical Agents Only)
-```
-Read: .session/{STORY_ID}-session.md
-Extract: "Repos:" field (API|UI|Both)
-Load: Appropriate repo context
-```
-
-### Step 4: Present Ready State
-```
-Display: Agent persona and menu
-Show: Loaded context summary
-Ready: For user input
-```
-
-## Agent Workflows
-
-### Strategic Agent Workflow (PM Example)
-
-```
-User: @/pm
-
-1. Load PM agent definition (.pennyfarthing/agents/pm.md)
-2. Load all strategic context:
-   - Sprint status (full)
-   - API context
-   - UI context
-   - Epic definitions
-   - Active work
-3. Present PM menu with options
-4. Execute PM tasks (sprint planning, backlog grooming, etc.)
-5. Update sprint status
-6. Hand off to SM or other agents as needed
-```
-
-### Tactical Agent Workflow (Dev Example)
-
-```
-User: @/dev
-
-1. Load Dev agent definition (.pennyfarthing/agents/dev.md)
-2. Load base context:
-   - Sprint status (story section)
-   - Active work
-3. Determine target repo from active work "Repos:" field
-4. Load target repo context:
-   - If API: API/.claude/context.md
-   - If UI: UI/.claude/context.md
-   - If Both: Load both
-5. Present Dev ready state
-6. Implement story in target repo(s)
-7. Update sprint status to 'review'
-8. Hand off to TEA or SM
-```
-
-## Agent Handoffs (TDD Flow)
-
-Handoffs are automated via Haiku subagents in `.pennyfarthing/agents/`.
-
-### The Flow
-
-```
-SM → TEA → Dev → Reviewer → SM
-│      │     │        │       │
-│      │     │        │       └── sm-finish PHASE=execute
-│      │     │        └── handoff VERDICT=approved/rejected
-│      │     └── handoff CURRENT_PHASE=green
-│      └── handoff CURRENT_PHASE=red
-└── sm-setup MODE=setup + sm-handoff
-```
-
-### Complete Subagent Inventory
-
-| Subagent File | Purpose | Model |
-|--------------|---------|-------|
-| **SM Subagents** | | |
-| `sm-setup.md` | Research backlog (MODE=research) or setup story (MODE=setup) | haiku |
-| `sm-finish.md` | Preflight checks (PHASE=preflight) or execute finish (PHASE=execute) | haiku |
-| `sm-handoff.md` | SM → TEA/Dev handoff with Jira/branch verification | haiku |
-| `sm-file-summary.md` | Summarize file changes for commits | haiku |
-| **Shared Subagents** | | |
-| `handoff.md` | Workflow-driven phase transitions (TEA, Dev, Reviewer) | haiku |
-| `testing-runner.md` | Run tests and report results | haiku |
-| **Reviewer Subagents** | | |
-| `reviewer-preflight.md` | Pre-flight checks before review | haiku |
-| **Utility Subagents** | | |
-| `workflow-status-check.md` | Check workflow status across repos | haiku |
-
-### SM → TEA (Story Setup)
-**Trigger:** User selects story via `/new-work`
-**Subagent:** `sm-setup MODE=setup` then `sm-handoff`
-**Action:** Claim Jira, write session file, create branches
-**Handoff phrase:** "TEA, Story X-Y needs tests. Write failing tests for these ACs."
-
-### TEA → Dev (Tests Written)
-**Trigger:** TEA completes failing tests
-**Subagent:** `handoff CURRENT_PHASE=red`
-**Action:** Update session file, transition to green phase
-**Handoff phrase:** "Dev, tests are RED and ready. Make them GREEN."
-
-### Dev → Reviewer (Implementation Complete)
-**Trigger:** Dev creates PR with passing tests
-**Subagent:** `handoff CURRENT_PHASE=green`
-**Action:** Update session file, transition to review phase
-**Handoff phrase:** "Reviewer, PR #N is ready. All tests GREEN."
-
-### Reviewer → SM (Approved)
-**Trigger:** Reviewer approves PR
-**Subagent:** `handoff VERDICT=approved`
-**Action:** Update status to `approved`, transition to finish phase
-**Handoff phrase:** "SM, Story X-Y approved. Run finish-story."
-
-### Reviewer → Dev (Rejected)
-**Trigger:** Reviewer finds issues
-**Subagent:** `handoff VERDICT=rejected`
-**Action:** Update session with issues, route back to implement phase
-**Handoff phrase:** "Dev, {N} issues found. See assessment for details."
-
-### SM → Done (Finish)
-**Trigger:** Status = `approved`
-**Subagent:** `sm-finish PHASE=execute`
-**Action:** Archive session, create summary, update sprint YAML, sync Jira
-
-## Support Agent Handoffs
-
-### Any → Architect
-**Trigger:** Need design decisions or architectural guidance
-**Context:** Technical problem or design question
-**Action:** Architect provides design and implementation guidance
-
-### Any → Tech Writer
-**Trigger:** Feature needs documentation
-**Context:** Implemented feature
-**Action:** Tech Writer creates documentation
-
-### Any → UX Designer
-**Trigger:** Feature needs UI design
-**Context:** User story and requirements
-**Action:** UX Designer creates UI design and specs
-
-## Context Budget Management
-
-### Target Budgets
-- **Agent file:** 200-400 lines
-- **Sprint status:** 100-200 lines (full) or 50 lines (story section)
-- **Repo contexts:** 30-50 lines each
-- **Active work:** 50-100 lines
-- **Total per agent:** 500-800 lines
-
-### Strategic Agent Budget
-```
-PM Agent Example:
-  - pm.md:                    200 lines
-  - sprint-status.yaml:       150 lines
-  - API/context:     30 lines
-  - UI/context:      30 lines
-  - epics.md (summary):       100 lines
-  - active work:               50 lines
-  Total:                      560 lines ✓
-```
-
-### Tactical Agent Budget
-```
-Dev Agent Example (API story):
-  - dev.md:                   300 lines
-  - sprint-status (story):     50 lines
-  - API/context:     30 lines
-  - active work:               50 lines
-  Total:                      430 lines ✓
-```
-
-## Benefits
-
-### ✅ Single Source of Truth
-- All agents defined in one place
-- No duplicate or conflicting agent files
-- Easy to update and maintain
-
-### ✅ Coordinated Planning
-- Strategic agents see full project scope
-- Unified sprint tracking
-- Clear cross-repo dependencies
-
-### ✅ Focused Implementation
-- Tactical agents load only what they need
-- Reduced context overhead
-- Faster agent activation
-
-### ✅ Clear Hierarchy
-- Strategic agents coordinate
-- Tactical agents execute
-- Clean handoffs between agents
-
-### ✅ Scalable
-- Easy to add new agents
-- Context budgets stay manageable
-- Works for solo dev or team
-
-## Architecture History
-
-### Previous Architecture (Pre-December 2025)
-- Separate commands: `/new-work`, `/pickup-work`, `/handoff-work`, `/finish-work`
-- Manual handoff documentation
-- No subagent extraction
-
-### Current Architecture (January 2026)
-- Smart entry point: `/work` (resumes or starts new)
-- Alternative: `/new-work` (explicitly start new story)
-- State detection via session file in `.session/`
-- Handoffs via Haiku subagents in `.pennyfarthing/agents/`
-- SM handles finish-story when status = `approved`
-- 102 themed personas for agent personality
-
-### Directory Structure
-```
-.pennyfarthing/agents/             # Agent definitions (symlinked)
-.claude/commands/           # 42 slash commands
-.claude/skills/             # 18+ knowledge domain skills
-.session/                   # Session files
-sprint/                     # Sprint tracking
-```
-
-### Commands Reference
-```bash
-# Entry points
-/work          # Smart entry - resume or start new
-/new-work      # Explicitly start new story
-
-# TDD Flow agents
-/sm            # Scrum Master (setup + finish)
-/tea           # Test Engineer (RED phase)
-/dev           # Developer (GREEN phase)
-/reviewer      # Code Reviewer
-
-# Support agents
-/architect     # Architecture design
-/tech-writer   # Documentation
-/ux-designer   # UI/UX design
-/devops        # Infrastructure
-
-# Utility
-/check         # Run quality gates before handoff
-/chore         # Quick commit for small changes
-/release       # Merge develop to main
-```
-
----
-
-**Smart entry. State detection. Subagent handoffs. Themed personas.**

package/pennyfarthing-dist/guides/HOOKS.md

@@ -1,230 +0,0 @@
-# Hooks Configuration Guide
-
-Pennyfarthing uses Claude Code hooks to integrate with session lifecycle events and protect files from accidental modification.
-
-## Overview
-
-Hooks are shell scripts that Claude Code runs at specific events:
-
-| Hook Type | When It Runs | Purpose |
-|-----------|--------------|---------|
-| `SessionStart` | When Claude Code session begins | Initialize environment, set variables |
-| `PreToolUse` | Before a tool call executes | Validate/block operations |
-| `PostToolUse` | After a tool call completes | Log, cleanup, notifications |
-
-## Pennyfarthing Default Hooks
-
-### SessionStart: session-start.sh
-
-**Location:** `.claude/pennyfarthing/scripts/hooks/session-start.sh`
-
-Initializes the Pennyfarthing environment:
-- Creates `.session/` directory structure
-- Clears stale agent state from previous sessions
-- Sets `PROJECT_ROOT` and `SESSION_ID` environment variables
-
-### SessionStart: setup-env.sh
-
-**Location:** `.claude/project/hooks/setup-env.sh`
-
-Project-specific environment setup. Edit this file to:
-- Set custom environment variables
-- Configure project-specific paths
-- Initialize project dependencies
-
-### PreToolUse: pre-edit-check.sh
-
-**Location:** `.claude/pennyfarthing/scripts/hooks/pre-edit-check.sh`
-
-Protects sensitive files from accidental edits:
-- Blocks: `.env`, `.pem`, `.key`, credentials, secrets
-- Blocks: `.git/`, `node_modules/`, `vendor/`
-- Blocks: `.claude/pennyfarthing/*` (managed files)
-
-## Configuration Schema
-
-Hooks are configured in `.claude/settings.local.json`:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/pennyfarthing/scripts/hooks/session-start.sh"
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/pennyfarthing/scripts/hooks/pre-edit-check.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Hook Entry Structure
-
-```json
-{
-  "matcher": "ToolNameRegex",  // Optional: regex to filter by tool name
-  "hooks": [
-    {
-      "type": "command",
-      "command": "path/to/script.sh"
-    }
-  ]
-}
-```
-
-### Matcher Format
-
-The `matcher` field is a regex string that matches tool names:
-- `"Edit|Write"` - Match Edit or Write tools
-- `"Bash"` - Match Bash tool only
-- Omit matcher to run on all tool uses
-
-## Hook Script Contract
-
-### Input
-
-Hooks receive JSON via stdin:
-
-```json
-{
-  "session_id": "abc123",
-  "source": "vscode",
-  "tool_name": "Edit",
-  "tool_input": {
-    "file_path": "/path/to/file.ts",
-    "old_string": "...",
-    "new_string": "..."
-  }
-}
-```
-
-### Output
-
-| Exit Code | Meaning |
-|-----------|---------|
-| `0` | Allow (continue execution) |
-| `2` | Block (stderr shown to Claude as error) |
-
-### Environment Variables
-
-Available in hooks:
-- `CLAUDE_PROJECT_DIR` - Project root directory
-- `CLAUDE_ENV_FILE` - Path to write persistent env vars
-
-## Adding Custom Hooks
-
-### 1. Create Hook Script
-
-```bash
-#!/usr/bin/env zsh
-# .claude/project/hooks/my-custom-hook.sh
-set -euo pipefail
-
-input=$(cat)
-# Your logic here
-
-exit 0  # Allow, or exit 2 to block
-```
-
-### 2. Make Executable
-
-```bash
-chmod +x .claude/project/hooks/my-custom-hook.sh
-```
-
-### 3. Configure in settings.local.json
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/project/hooks/my-custom-hook.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Examples
-
-### Block Specific File Patterns
-
-```bash
-#!/usr/bin/env zsh
-# Block edits to migration files
-input=$(cat)
-file_path=$(echo "$input" | jq -r '.tool_input.file_path // ""')
-
-if [[ "$file_path" == *"/migrations/"* ]]; then
-    echo "BLOCKED: Migration files are immutable" >&2
-    exit 2
-fi
-exit 0
-```
-
-### Log All Bash Commands
-
-```bash
-#!/usr/bin/env zsh
-# Log bash commands for audit
-input=$(cat)
-command=$(echo "$input" | jq -r '.tool_input.command // ""')
-
-echo "$(date -Iseconds) | $command" >> "$CLAUDE_PROJECT_DIR/.session/bash-log.txt"
-exit 0
-```
-
-### Environment Setup
-
-```bash
-#!/usr/bin/env zsh
-# .claude/project/hooks/setup-env.sh
-# Set project-specific environment
-
-if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
-    cat >> "$CLAUDE_ENV_FILE" << EOF
-export API_URL="http://localhost:3000"
-export DATABASE_URL="postgres://localhost/myapp"
-EOF
-fi
-exit 0
-```
-
-## Debugging Hooks
-
-If a hook fails or behaves unexpectedly:
-
-1. **Check permissions:** `chmod +x your-hook.sh`
-2. **Test manually:** `echo '{}' | ./your-hook.sh`
-3. **Check stderr:** Hook errors appear in Claude Code output
-4. **Validate JSON:** Use `jq` to parse input correctly
-
-## File Locations
-
-| Type | Location | Editable |
-|------|----------|----------|
-| Managed hooks | `.claude/pennyfarthing/scripts/hooks/` | No (use pennyfarthing repo) |
-| Project hooks | `.claude/project/hooks/` | Yes |
-| Settings | `.claude/settings.local.json` | Yes |