@pennyfarthing/core 7.9.3 → 8.0.0

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

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

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

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