@pennyfarthing/core 7.4.1 → 7.5.0

package/pennyfarthing-dist/guides/patterns/tdd-flow-pattern.md

@@ -1,402 +0,0 @@
-# TDD Flow Pattern
-
-**Pattern Type:** Sequential Handoff Chain
-**Agents Involved:** SM, TEA, Dev, Reviewer
-**Coordination Mechanism:** Session file state machine
-
-## Problem Statement
-
-Multi-agent development workflows need structured coordination to ensure:
-- Tests are written before implementation (TDD discipline)
-- Code is reviewed before merge (quality gate)
-- State is preserved across agent transitions
-- Error recovery paths are clear
-
-Without explicit coordination, agents may:
-- Skip testing entirely
-- Implement without understanding requirements
-- Approve code without thorough review
-- Lose context during handoffs
-
-## Solution
-
-A linear state machine where each agent:
-1. Receives work in a known state
-2. Performs their specialized role
-3. Transitions to the next state via handoff subagent
-4. Passes control to the next agent
-
-```
-SM (setup) → TEA (RED) → Dev (GREEN) → Reviewer (gate) → SM (finish)
-```
-
-Each transition is mediated by a **handoff subagent** that updates the session file, ensuring the next agent has clear context.
-
-## State Diagram
-
-```mermaid
-stateDiagram-v2
-    [*] --> NEW_WORK: /new-work invoked
-
-    NEW_WORK --> SM_SETUP: User selects story
-    SM_SETUP --> TEA_RED: Standard story (3+ pts)
-    SM_SETUP --> DEV_GREEN: Trivial story (1-2 pts)
-
-    TEA_RED --> DEV_GREEN: Tests written (tea-handoff)
-    DEV_GREEN --> REVIEW: PR created (dev-handoff)
-
-    REVIEW --> DEV_GREEN: REJECTED (reviewer-handoff-reject)
-    REVIEW --> APPROVED: APPROVED (reviewer-handoff-approve)
-
-    APPROVED --> FINISH: SM archives story
-    FINISH --> [*]: Story complete
-
-    note right of TEA_RED: RED = Tests fail
-    note right of DEV_GREEN: GREEN = Tests pass
-    note right of REVIEW: Adversarial review
-```
-
-### ASCII Alternative
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         TDD FLOW STATE MACHINE                       │
-└─────────────────────────────────────────────────────────────────────┘
-
-    ┌──────────┐
-    │ NEW_WORK │ ─────────────────────────────────────┐
-    └────┬─────┘                                      │
-         │ User selects story                         │
-         ▼                                            │
-    ┌──────────┐                                      │
-    │ SM_SETUP │                                      │
-    └────┬─────┘                                      │
-         │                                            │
-         ├─────────────────┐                          │
-         │ 3+ pts          │ 1-2 pts (skip TEA)       │
-         ▼                 │                          │
-    ┌──────────┐           │                          │
-    │ TEA_RED  │           │                          │
-    │ (tests   │           │                          │
-    │  fail)   │           │                          │
-    └────┬─────┘           │                          │
-         │ tea-handoff     │                          │
-         ▼                 ▼                          │
-    ┌───────────────────────┐                         │
-    │      DEV_GREEN        │ ◄───────────────────────┤
-    │   (tests pass, PR)    │                         │
-    └──────────┬────────────┘                         │
-               │ dev-handoff                          │
-               ▼                                      │
-    ┌──────────────────────┐                          │
-    │       REVIEW         │                          │
-    │  (adversarial gate)  │                          │
-    └──────────┬───────────┘                          │
-               │                                      │
-         ┌─────┴─────┐                                │
-         │           │                                │
-    REJECTED    APPROVED                              │
-         │           │                                │
-         │           ▼                                │
-         │     ┌──────────┐                           │
-         │     │  FINISH  │                           │
-         │     │ (archive)│                           │
-         │     └────┬─────┘                           │
-         │          │                                 │
-         │          ▼                                 │
-         │     ┌──────────┐                           │
-         │     │   DONE   │                           │
-         │     └──────────┘                           │
-         │                                            │
-         └──────────────► DEV_GREEN (fix issues)      │
-```
-
-## Implementation
-
-### Session File Structure
-
-The session file (`.session/{story-id}-session.md`) tracks state:
-
-```markdown
-# Story 5-2: Implement Feature X
-
-## Story Info
-- Story ID: 5-2
-- Title: Implement Feature X
-- Points: 3
-- Phase: dev          # Current phase: sm | tea | dev | review | approved
-- Status: in-progress
-- Repos: pennyfarthing
-- Branch: feature/5-2-implement-feature-x
-
-## Workflow
-- [x] Story claimed
-- [x] Session file created
-- [x] TEA: Tests written (RED)
-- [ ] Dev: Implementation complete (GREEN)
-- [ ] Reviewer: Code approved
-- [ ] SM: Story archived
-```
-
-### Phase Transitions
-
-| From | To | Trigger | Subagent |
-|------|-----|---------|----------|
-| setup | red | Story setup complete | `sm-setup MODE=setup` + `sm-handoff` |
-| setup | implement | 1-2 pt story (skip TEA) | `sm-setup MODE=setup` + `sm-handoff` |
-| red | green | Tests written, failing | `handoff CURRENT_PHASE=red` |
-| green | review | PR created, tests pass | `handoff CURRENT_PHASE=green` |
-| review | implement | Issues found | `handoff VERDICT=rejected` |
-| review | approved | No blocking issues | `handoff VERDICT=approved` |
-| approved | done | Story archived | `sm-finish PHASE=execute` |
-
-### Agent Responsibilities
-
-#### SM (Scrum Master)
-**Entry:** `/new-work` command
-**Role:** Story selection, context creation, finish workflow
-**Files:** `agents/sm.md`
-
-Key behaviors:
-- Spawns `workflow-status-check` to detect current state
-- Creates story context with technical approach
-- Routes to TEA (standard) or Dev (trivial)
-- Handles finish flow when story approved
-
-```yaml
-# SM routing decision
-| Points | Scale | Route |
-|--------|-------|-------|
-| 1-2 pts | Trivial | SM → Dev (skip TEA) |
-| 3-5 pts | Standard | SM → TEA → Dev |
-| 8+ pts | Complex | SM → TEA → Dev |
-```
-
-#### TEA (Test Engineer/Architect)
-**Entry:** Handoff from SM
-**Role:** Write failing tests (RED phase)
-**Files:** `agents/tea.md`
-
-Key behaviors:
-- Analyzes acceptance criteria for testability
-- Writes tests that FAIL (RED state)
-- May bypass tests for documentation/config changes
-- Spawns `tea-handoff` to update session
-
-```markdown
-## TEA Assessment
-**Tests Required:** Yes
-**Test Files:**
-- `internal/service/feature_test.go` - Unit tests for feature logic
-**Tests Written:** 4 tests covering 3 ACs
-**Status:** RED (failing - ready for Dev)
-```
-
-#### Dev (Developer)
-**Entry:** Handoff from TEA (or SM for trivial)
-**Role:** Implement code to pass tests (GREEN phase)
-**Files:** `agents/dev.md`
-
-Key behaviors:
-- Implements minimal code to pass tests
-- Follows RED → GREEN → Refactor cycle
-- Creates PR with clear description
-- Spawns `dev-handoff` to update session
-
-```markdown
-## Dev Assessment
-**Implementation Complete:** Yes
-**Files Changed:**
-- `internal/service/feature.go` - Core implementation
-**Tests:** 4/4 passing (GREEN)
-**PR:** #42 - Implement feature X
-```
-
-#### Reviewer (Code Reviewer)
-**Entry:** Handoff from Dev
-**Role:** Adversarial code review (quality gate)
-**Files:** `agents/reviewer.md`
-
-Key behaviors:
-- Spawns `reviewer-preflight` for mechanical checks
-- Performs security, edge case, and performance analysis
-- Makes APPROVE/REJECT judgment
-- Routes back to Dev (reject) or SM (approve)
-
-```markdown
-## Reviewer Assessment
-**PR:** #42
-**Verdict:** APPROVED | REJECTED
-
-**Code Review Evidence:**
-- **Data flow traced:** userId from request → SQL (parameterized at repo.go:89)
-- **Pattern observed:** Follows existing service pattern
-- **Error handling:** Returns wrapped errors with context
-```
-
-### Handoff Subagents
-
-Each handoff subagent (Haiku model) handles mechanical updates:
-
-| Subagent | Purpose | Updates |
-|----------|---------|---------|
-| `tea-handoff` | TEA → Dev transition | Phase, workflow checkboxes, next agent |
-| `dev-handoff` | Dev → Reviewer transition | Phase, PR info, workflow checkboxes |
-| `reviewer-handoff-approve` | Reviewer → SM (finish) | Phase to approved, route to SM |
-| `reviewer-handoff-reject` | Reviewer → Dev (fix) | Phase back to dev, issue summary |
-
-Example invocation:
-```yaml
-Task tool:
-  subagent_type: "dev-handoff"
-  prompt: |
-    STORY_ID: 5-2
-    REPOS: pennyfarthing
-    PR_NUMBER: 42
-    TEST_COUNT: 4
-```
-
-## When to Use
-
-**Use TDD Flow when:**
-- Building new features that need testing
-- Implementing stories with clear acceptance criteria
-- Work benefits from structured code review
-
-**Skip TEA phase when:**
-- Documentation-only changes
-- Configuration changes
-- Dependency updates
-- Refactoring with existing test coverage
-
-**Don't use this pattern for:**
-- Exploratory spikes (use Plan mode instead)
-- Bug fixes (may use abbreviated flow)
-- Emergency hotfixes (direct to main with review)
-
-## Error Recovery
-
-### Rejection Loop
-
-```
-Dev submits PR → Reviewer rejects → Dev fixes → Reviewer re-reviews
-```
-
-The rejection loop continues until:
-- All Critical/Major issues are resolved
-- Reviewer approves
-
-Session file tracks rejection count and issues.
-
-### Missing Epic Context
-
-```
-User runs /new-work → workflow-status-check detects no epic context
-→ Returns MISSING_EPIC_CONTEXT state
-→ Blocks until user runs /start-epic
-```
-
-### Context Overflow
-
-Each agent checks context usage after completing work:
-
-```bash
-$CLAUDE_PROJECT_DIR/scripts/core/check-context.sh --human
-```
-
-| Context | Action |
-|---------|--------|
-| < 60% | Invoke next agent directly |
-| > 60% | Tell user to start fresh session |
-
-This prevents context overflow mid-flow.
-
-### Stale Session Recovery
-
-If a session file exists but work was interrupted:
-
-1. `workflow-status-check` detects `IN_PROGRESS_STATE`
-2. Reports which agent should resume
-3. User decides: continue or abandon
-
-### Test Failures in Review
-
-If tests fail during review preflight:
-1. Reviewer spawns `testing-runner` subagent
-2. Tests fail → automatic rejection
-3. Routes back to Dev with failure details
-
-## Anti-Patterns
-
-### Skipping Phases
-
-**Wrong:**
-```
-SM → Dev → merge
-```
-Missing TEA means no test discipline. Missing Reviewer means no quality gate.
-
-**Correct:**
-```
-SM → TEA → Dev → Reviewer → SM (finish)
-```
-
-### Rubber-Stamp Reviews
-
-**Wrong:**
-```markdown
-Tests pass, lint clean, approved.
-```
-
-**Correct:**
-```markdown
-**Data flow traced:** userId from handler.go:47 → repo.go:89 (parameterized)
-**Pattern:** Follows usePresence hook pattern at hooks/usePresence.ts:12
-**Security:** Auth check at handler.go:52 verifies admin role
-```
-
-### Skipping Handoff Subagents
-
-**Wrong:**
-```
-TEA writes tests → directly tells Dev to continue
-```
-Session file not updated, next agent unclear.
-
-**Correct:**
-```
-TEA writes tests → spawns tea-handoff → session updated → Dev activated
-```
-
-### Giant PRs
-
-**Wrong:**
-```
-Story: 8 pts, 47 files changed, 2000+ lines
-```
-
-**Correct:**
-```
-Break into smaller stories (2-3 pts each)
-Each story: 5-15 files, focused changes
-```
-
-## Related Patterns
-
-- **Helper Delegation Pattern** (`helper-delegation-pattern.md`): How Opus agents delegate mechanical work to Haiku subagents
-- **Approval Gates Pattern** (`approval-gates-pattern.md`): Deep dive on Reviewer approval mechanisms
-- **Fan-out/Fan-in Pattern** (`fan-out-fan-in-pattern.md`): Parallel agent execution
-
-## References
-
-- SM Agent: `agents/sm.md`
-- TEA Agent: `agents/tea.md`
-- Dev Agent: `agents/dev.md`
-- Reviewer Agent: `agents/reviewer.md`
-- Workflow Status Check: `agents/workflow-status-check.md`
-- Tactical Agent Behavior: `guides/tactical-agent-behavior.md`
-
----
-
-*Last verified: 2026-01-06*
-*Pennyfarthing v4.0.0*

package/pennyfarthing-dist/guides/permission-protocol.md

@@ -1,188 +0,0 @@
-# Permission Request Protocol
-
-Defines how agents request runtime permissions and how grants are managed.
-
-## Overview
-
-Agents may need tool access that wasn't pre-configured. This protocol provides:
-1. Structured format for permission requests
-2. Grant types with different lifetimes
-3. Integration points for UI prompts and persistence
-
-## Permission Request Schema
-
-```yaml
-permission_request:
-  tool: string        # Tool name (WebFetch, Bash, Read, Write, etc.)
-  reason: string      # Human-readable explanation of why access is needed
-  scope: string       # Scope pattern (URL pattern, command pattern, file glob)
-  grant_type: string  # "once" | "session" | "always"
-```
-
-### Required Fields
-
-| Field | Type | Description | Example |
-|-------|------|-------------|---------|
-| `tool` | string | Claude Code tool name | `"WebFetch"`, `"Bash"` |
-| `reason` | string | Why access is needed | `"Fetch API docs from GitHub"` |
-| `scope` | string | What access is needed | `"*.github.com"`, `"npm test"` |
-| `grant_type` | string | How long grant lasts | `"once"`, `"session"`, `"always"` |
-
-### Grant Types
-
-| Type | Behavior | Storage | Use Case |
-|------|----------|---------|----------|
-| `once` | Single use, cleared after tool call | Memory | One-time operations |
-| `session` | Valid until session ends | Memory | Repeated access during story |
-| `always` | Persisted across sessions | `settings.local.json` | Trusted patterns |
-
-## Validation Rules
-
-All fields are required and must be non-empty strings. Grant type must be exactly one of: `once`, `session`, `always`.
-
-### Valid Request Example
-
-```json
-{
-  "tool": "WebFetch",
-  "reason": "Fetch React documentation for component implementation",
-  "scope": "*.reactjs.org",
-  "grant_type": "session"
-}
-```
-
-### Invalid Request Examples
-
-```json
-// Missing required field
-{ "tool": "WebFetch", "reason": "Need docs" }
-
-// Invalid grant_type
-{ "tool": "Bash", "reason": "Run tests", "scope": "npm", "grant_type": "forever" }
-
-// Empty string
-{ "tool": "", "reason": "Access", "scope": "*", "grant_type": "once" }
-```
-
-## Permission Grant Structure
-
-When a request is approved, a grant is created:
-
-```yaml
-permission_grant:
-  tool: string          # Tool name from request
-  scope: string         # Scope pattern from request
-  grant_type: string    # Grant type from request
-  granted_at: string    # ISO timestamp when granted
-  uses_remaining: number # Only for "once" type (starts at 1)
-```
-
-### Grant Lifecycle
-
-```
-Request → Validate → Prompt User → Create Grant → Tool Executes → Check/Decrement
-```
-
-For `once` grants:
-1. Grant created with `uses_remaining: 1`
-2. Tool executes successfully
-3. `uses_remaining` decremented to 0
-4. Grant expired, removed from cache
-
-For `session` and `always` grants:
-- No use limit, valid until session ends or revoked
-
-## Integration Points
-
-### TypeScript Types
-
-Import from `@pennyfarthing/core`:
-
-```typescript
-import {
-  validatePermissionRequest,
-  createGrant,
-  type PermissionRequest,
-  type PermissionGrant,
-  type GrantType,
-  VALID_GRANT_TYPES,
-} from '@pennyfarthing/core/permissions';
-```
-
-### Session File Tracking
-
-Session files can track active grants:
-
-```markdown
-## Permissions
-| Tool | Scope | Grant | Granted |
-|------|-------|-------|---------|
-| WebFetch | *.github.com | session | 2026-01-13T10:30:00Z |
-| Bash | npm test | once | 2026-01-13T10:31:00Z |
-```
-
-### Settings Persistence
-
-`always` grants persist in `.claude/settings.local.json`:
-
-```json
-{
-  "permissions": {
-    "grants": {
-      "WebFetch": ["*.github.com", "*.npmjs.com"],
-      "Bash": ["npm *", "git *"]
-    }
-  }
-}
-```
-
-## Request Flow
-
-```
-┌─────────────────┐
-│  Agent needs    │
-│  tool access    │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│ Create request  │
-│ with protocol   │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐     Invalid
-│   Validate      │────────────► Reject
-│   request       │
-└────────┬────────┘
-         │ Valid
-         ▼
-┌─────────────────┐     Denied
-│  Prompt user    │────────────► Block tool
-│  for approval   │
-└────────┬────────┘
-         │ Approved
-         ▼
-┌─────────────────┐
-│  Create grant   │
-│  per grant_type │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Tool executes  │
-│  (grant cached) │
-└─────────────────┘
-```
-
-## Related Stories
-
-- **33-2**: `/permissions` skill for viewing and managing grants
-- **33-3**: Cyclist UI for permission prompts
-- **33-4**: Spot permission grants (once/session/always implementation)
-- **33-5**: Workflow permission presets
-
-## See Also
-
-- `AGENT-SCOPES.md` - Agent permission tiers
-- `.claude/project/docs/agent-scopes.yaml` - Active scope configuration

package/pennyfarthing-dist/guides/persona-loading.md

@@ -1,46 +0,0 @@
-# Persona Loading (For Command Files)
-
-This block is included in command files to pre-load the agent's persona before the agent file is read.
-
-## Usage in Command Files
-
-Add this block BEFORE `<agent-activation>`:
-
-```markdown
-<persona-loading agent="{agent-name}">
-Load this agent's persona before activation:
-1. Read `.pennyfarthing/config.local.yaml`
-2. Get `theme` value (e.g., "discworld")
-3. Read `pennyfarthing-dist/personas/themes/{theme}.yaml` (or `.pennyfarthing/personas/themes/`)
-4. Extract `agents.{agent-name}` section (character, style, helper, etc.)
-5. Apply `attributes` from config (verbosity, formality, humor, emoji_use)
-6. Store resolved persona for use during session
-</persona-loading>
-```
-
-## What Gets Resolved
-
-From theme file (`agents.{agent-name}`):
-- `character` - The persona name (e.g., "Captain Carrot")
-- `style` - Communication style
-- `expertise` - Domain expertise
-- `helper` - Helper name and style
-- `emoji` - Default emoji
-
-From config (`attributes`):
-- `verbosity` - low | medium | high
-- `formality` - formal | casual | playful
-- `humor` - enabled | disabled | subtle
-- `emoji_use` - none | minimal | frequent
-
-## Agent File Reference
-
-After persona loading, the agent file just needs:
-
-```markdown
-## Persona
-
-**Fallback:** {brief description if config unavailable}
-```
-
-The agent receives the resolved persona from the command file's loading step.