@pennyfarthing/core 10.0.5 → 10.2.0

package/pennyfarthing-dist/guides/patterns/helper-delegation-pattern.md

@@ -30,7 +30,6 @@ Opus Agent (strategic)
     │
     └── Delegates mechanical work via Task tool
             │
-            ├── workflow-status-check (state detection)
             ├── sm-setup (research backlog or setup story)
             ├── sm-finish (preflight checks or execute finish)
             ├── sm-handoff (SM→TEA/Dev with Jira/branch verification)
@@ -54,7 +53,7 @@ The key insight: **Make critical behaviors AUTOMATIC via subagent delegation** r
     └────────┬─────────┘
              │
              │ Task tool invocation
-             │ subagent_type: "workflow-status-check"
+             │ subagent_type: "sm-setup"
              │
              ▼
     ┌──────────────────┐
@@ -87,8 +86,6 @@ The key insight: **Make critical behaviors AUTOMATIC via subagent delegation** r
 ┌─────────────────────────────────────────────────────────────────────────┐
 │ CATEGORY          │ SUBAGENT               │ PURPOSE                    │
 ├───────────────────┼────────────────────────┼────────────────────────────┤
-│ State Detection   │ workflow-status-check  │ Scan files, report state   │
-├───────────────────┼────────────────────────┼────────────────────────────┤
 │ Setup/Init        │ sm-setup       │ Research or setup (MODE)   │
 │                   │ sm-handoff             │ SM→TEA/Dev with Jira/branch│
 ├───────────────────┼────────────────────────┼────────────────────────────┤
@@ -109,14 +106,14 @@ Use Claude Code's Task tool with the `subagent_type` parameter:
 
 ```yaml
 Task tool:
-  subagent_type: "workflow-status-check"
+  subagent_type: "sm-setup"
   model: "haiku"                           # Optional, defaults to haiku
-  description: "Check workflow state"
+  description: "Research backlog"
   prompt: |
-    CALLING_AGENT: SM
+    MODE: research
     PROJECT_ROOT: $CLAUDE_PROJECT_DIR
 
-    Scan .session files and git status to determine workflow state.
+    Scan sprint backlog and report available stories.
 ```
 
 ### Placeholder Substitution
@@ -185,47 +182,6 @@ $CLAUDE_PROJECT_DIR (set by SessionStart hook)
 [Retry pattern and escalation format]
 ```
 
-### Real Example: workflow-status-check
-
-**Definition** (from `agents/workflow-status-check.md:14-45`):
-
-```bash
-# Step 1: Scan Session Files
-ls -la .session/*-session.md 2>/dev/null
-
-for f in .session/*-session.md; do
-    [ -f "$f" ] && head -50 "$f"
-done
-
-# Extract: Story ID, Phase, Status, Branch, Jira key
-```
-
-**State Determination** (lines 89-100):
-
-```
-Rules applied in order:
-1. MISSING_EPIC_CONTEXT: No epic context AND no sessions
-2. FINISH_STATE: Phase=approved OR (Phase=review AND Status=approved)
-3. NEW_WORK_STATE: No sessions AND no in_progress stories
-4. IN_PROGRESS_STATE: Session exists with active phase
-```
-
-**Output** (lines 129-183):
-
-```markdown
-## Workflow Status Report
-
-### Detected State
-**{STATE}**
-
-### Active Work Sessions
-| Story | Phase | Status | Days Active |
-|-------|-------|--------|-------------|
-
-### Agent Guidance
-**For {CALLING_AGENT}:** {specific action}
-```
-
 ### Real Example: tea-handoff
 
 **Pre-flight Verification** (from `agents/tea-handoff.md:29-40`):
@@ -281,7 +237,6 @@ The Opus agent reads this report and decides next steps—it doesn't re-execute
 
 | Scenario | Subagent | Why |
 |----------|----------|-----|
-| Determining workflow state | `workflow-status-check` | Scanning files is mechanical |
 | Creating branches/sessions | `sm-setup MODE=setup` | Git operations are deterministic |
 | Verifying test state | `testing-runner` | Test execution is mechanical |
 | Updating session files | `handoff` | State updates must be reliable |
@@ -353,11 +308,7 @@ Recommended fix: [what calling agent should do]
 
 ### Never Silently Fail
 
-From `agents/workflow-status-check.md:195`:
-
-> If partial failure, report what worked and mark unknowns. **Never silently fail.**
-
-Subagents must always return a result, even if partial. The calling agent decides how to proceed.
+Subagents must always return a result, even if partial. The calling agent decides how to proceed. **Never silently fail.**
 
 ## Anti-Patterns
 
@@ -424,13 +375,13 @@ prompt: |
 
 **Wrong:**
 ```
-Opus spawns workflow-status-check, ignores output, proceeds anyway
+Opus spawns sm-setup, ignores output, proceeds anyway
 ```
 
 **Correct:**
 ```
-Opus spawns workflow-status-check
-→ Reads state (NEW_WORK_STATE, FINISH_STATE, etc.)
+Opus spawns sm-setup
+→ Reads result (backlog stories, setup confirmation, etc.)
 → Branches logic based on result
 ```
 
@@ -463,7 +414,6 @@ If edit fails:
 ## References
 
 ### Subagent Definitions
-- State Detection: `agents/workflow-status-check.md`
 - SM Setup/Research: `agents/sm-setup.md`
 - SM Finish: `agents/sm-finish.md`
 - SM Handoff: `agents/sm-handoff.md`

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

@@ -158,7 +158,7 @@ The session file (`.session/{story-id}-session.md`) tracks state:
 **Files:** `agents/sm.md`
 
 Key behaviors:
-- Spawns `workflow-status-check` to detect current state
+- Reads workflow state from prime activation output
 - Creates story context with technical approach
 - Routes to TEA (standard) or Dev (trivial)
 - Handles finish flow when story approved
@@ -291,7 +291,7 @@ Session file tracks rejection count and issues.
 ### Missing Epic Context
 
 ```
-User runs /new-work → workflow-status-check detects no epic context
+User runs /new-work → prime detects no epic context
 → Returns MISSING_EPIC_CONTEXT state
 → Blocks until user runs /start-epic
 ```
@@ -315,7 +315,7 @@ This prevents context overflow mid-flow.
 
 If a session file exists but work was interrupted:
 
-1. `workflow-status-check` detects `IN_PROGRESS_STATE`
+1. Prime detects `IN_PROGRESS_STATE` in activation output
 2. Reports which agent should resume
 3. User decides: continue or abandon
 
@@ -393,8 +393,7 @@ Each story: 5-15 files, focused changes
 - 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`
+- Agent Behavior: `guides/agent-behavior.md`
 
 ---
 

package/pennyfarthing-dist/guides/prime.md

@@ -52,8 +52,8 @@ Prime selects a context tier based on session state to manage token overhead:
 ## Invocation
 
 ```bash
-# From agent commands (via CLI)
-python3 -m pennyfarthing_scripts.cli agent start "<agent>" --quiet
+# From agent commands (via pf CLI)
+pf agent start "<agent>" --quiet
 
 # TypeScript API (from Cyclist)
 getPrimeContext(agentName, projectDir)

package/pennyfarthing-dist/guides/scale-levels.md

@@ -7,7 +7,7 @@ Pennyfarthing uses scale levels (0-4) to route work to appropriate workflows. Sc
 | Level | Scope | Story Count | Workflow | Required Artifacts |
 |-------|-------|-------------|----------|-------------------|
 | **0** | fix, bug, typo, small change, patch | 1 | `trivial` | None |
-| **1** | simple, basic, small feature, add | 1-10 | `quick-spec` | tech-spec |
+| **1** | simple, basic, small feature, add | 1-10 | `prd` | tech-spec |
 | **2** | dashboard, several features, admin panel | 5-15 | `prd` | PRD |
 | **3** | platform, integration, complex, system | 12-40 | `prd` | PRD + architecture |
 | **4** | enterprise, multi-tenant, multiple products | 40+ | `prd` | Full BMAD process |
@@ -38,8 +38,7 @@ When you describe work to Pennyfarthing, the scale level is detected from keywor
 | Level | Workflow | Description |
 |-------|----------|-------------|
 | 0 | `trivial` | Direct fix, no planning artifacts |
-| 1 | `quick-spec` | Conversational spec, produces tech-spec |
-| 2-4 | `prd` | Full PRD workflow with gates |
+| 1-4 | `prd` | PRD workflow with gates |
 
 ## Required Artifacts
 
@@ -47,7 +46,7 @@ When you describe work to Pennyfarthing, the scale level is detected from keywor
 Just fix it. No planning documents required.
 
 ### Level 1: Tech-Spec
-Quick conversational spec producing implementation-ready technical specification.
+Lightweight PRD producing implementation-ready technical specification.
 
 ### Level 2: PRD
 Product Requirements Document. Architecture is optional.
@@ -102,7 +101,7 @@ info = get_scale_level_info(level)
 | Description | Detected Level | Workflow |
 |-------------|----------------|----------|
 | "Fix the login bug" | 0 | trivial |
-| "Add a logout button" | 1 | quick-spec |
+| "Add a logout button" | 1 | prd |
 | "Build an admin dashboard" | 2 | prd |
 | "New platform for data processing" | 3 | prd |
 | "Enterprise multi-tenant SaaS" | 4 | prd |
@@ -111,4 +110,3 @@ info = get_scale_level_info(level)
 
 - [Workflow Skill](/workflow) - Workflow management commands
 - [PRD Workflow](../workflows/prd/) - Full PRD stepped workflow
-- [Quick-Spec Workflow](../workflows/quick-spec/) - Lightweight spec workflow

package/pennyfarthing-dist/guides/skill-schema.md

@@ -292,7 +292,7 @@ Never manually edit sprint YAML. Use the provided commands.
 Add a new story to an epic.
 
 <run>
-python3 -m pennyfarthing_scripts.cli sprint story add <epic-id> "<title>" <points>
+pf sprint story add <epic-id> "<title>" <points>
 </run>
 
 <args>
@@ -304,7 +304,7 @@ python3 -m pennyfarthing_scripts.cli sprint story add <epic-id> "<title>" <point
 </args>
 
 <example>
-python3 -m pennyfarthing_scripts.cli sprint story add epic-76 "Add user authentication" 3
+pf sprint story add epic-76 "Add user authentication" 3
 </example>
 
 <output>
@@ -322,7 +322,7 @@ After creating, use `/sprint story size` for sizing guidelines.
 Complete a story after PR merge.
 
 <run>
-python3 -m pennyfarthing_scripts.cli sprint story finish <story-id>
+pf sprint story finish <story-id>
 </run>
 
 <args>
@@ -332,7 +332,7 @@ python3 -m pennyfarthing_scripts.cli sprint story finish <story-id>
 </args>
 
 <example>
-python3 -m pennyfarthing_scripts.cli sprint story finish MSSCI-12052
+pf sprint story finish MSSCI-12052
 # Archives story, updates Jira, cleans session files
 </example>
 

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

@@ -0,0 +1,158 @@
+# Tandem Protocol Guide
+
+Tandem mode pairs a background observer ("backseat") with the primary agent during a workflow phase. The backseat watches the primary agent's work and writes observations to a shared file. The PostToolUse hook automatically injects those observations into the primary agent's context.
+
+## Architecture
+
+```
+Primary Agent (Opus)          Backseat Agent (Haiku, background)
+     │                              │
+     ├── works on story             ├── watches via git diff / file reads
+     │                              │
+     │                              ├── writes observation to
+     │                              │   .session/{story}-tandem-{partner}.md
+     │                              │
+     ├── PostToolUse hook fires ────┤
+     │   bell-mode-hook.sh detects  │
+     │   new observation, injects   │
+     │   "[Tandem] Character: ..."  │
+     │                              │
+     ├── surfaces in own voice      │
+     │   "The Caterpillar notes..." │
+     │                              │
+     └── terminates backseat ───────┘
+         before handoff
+```
+
+## Prerequisites
+
+- Workflow must have `tandem:` block on the phase (e.g., `tdd-tandem`, `bdd-tandem`)
+- Session file must contain `**Tandem:** {partner} ({scope})` line (written by handoff subagent)
+
+No configuration required. Tandem injection is always active in the PostToolUse hook — the presence of observation files in `.session/` is the only signal needed. Works in both CLI and Cyclist.
+
+## How It Works
+
+### 1. Detection
+
+On activation, agents check the session file for a `**Tandem:**` line:
+
+```
+**Tandem:** architect (file-watch)
+```
+
+If present, the agent spawns a backseat observer. If absent, tandem is a complete no-op.
+
+### 2. Persona Resolution
+
+The backseat agent plays its character from the active theme:
+
+```bash
+THEME=$(yq '.theme' .pennyfarthing/config.local.yaml)
+CHARACTER=$(yq ".agents.{PARTNER}.character" .pennyfarthing/personas/themes/${THEME}.yaml)
+```
+
+### 3. Observation File Initialization
+
+The primary agent creates the observation file before spawning the backseat:
+
+```markdown
+# Tandem Observations: {STORY_ID}
+**Observer:** {PARTNER} ({CHARACTER})
+**Phase:** {PHASE}
+**Started:** {ISO_TIMESTAMP}
+
+---
+```
+
+File path: `.session/{STORY_ID}-tandem-{PARTNER}.md`
+
+### 4. Backseat Spawn
+
+Via the Task tool:
+
+```yaml
+subagent_type: "general-purpose"
+model: "haiku"
+run_in_background: true
+prompt: |
+  Read .pennyfarthing/agents/tandem-backseat.md for your instructions.
+
+  PARTNER: "{PARTNER}"
+  CHARACTER: "{CHARACTER}"
+  STORY_ID: "{STORY_ID}"
+  SCOPE: "{SCOPE}"
+  OBSERVATION_FILE: ".session/{STORY_ID}-tandem-{PARTNER}.md"
+  SESSION_FILE: ".session/{STORY_ID}-session.md"
+```
+
+### 5. Observation Injection
+
+The PostToolUse hook (tandem injection runs unconditionally, no config required):
+1. Checks `.session/*-tandem-*.md` files for mtime changes
+2. Parses the latest `## [HH:MM] Observation` block
+3. Extracts the persona from the `**Observer:**` header
+4. Injects as: `[Tandem] {Character}: {observation text}`
+
+### 6. Surfacing Observations
+
+When the primary agent receives a tandem injection, it surfaces the observation in its own voice using the backseat's character name:
+
+> "The Caterpillar notes that `UserService.ts:42` returns null instead of the result object AC-3 requires."
+
+### 7. Cleanup
+
+Before handoff, the primary agent terminates the backseat background task. This must happen before spawning the handoff subagent.
+
+## Observation Scopes
+
+| Scope | What the backseat monitors |
+|-------|---------------------------|
+| `file-watch` | `git diff --stat`, changed file inspection, pattern drift |
+| `tool-watch` | Tool call log (`.session/{story}-tool-log.md`), test failures, edit patterns |
+| `context-watch` | Session file progress, AC coverage, scope drift |
+
+## Observation File Format
+
+Each entry follows this format (matches `observation-writer.ts`):
+
+```markdown
+## [HH:MM] Observation
+**Trigger:** {scope}: {detail}
+{observation text}
+
+---
+```
+
+## Tandem Workflow Pairings
+
+From `tdd-tandem.yaml`:
+
+| Phase | Primary | Backseat | Scope |
+|-------|---------|----------|-------|
+| red | TEA | Architect | file-watch |
+| green | Dev | TEA | file-watch |
+| review | Reviewer | PM | file-watch |
+
+From `bdd-tandem.yaml`:
+
+| Phase | Primary | Backseat | Scope |
+|-------|---------|----------|-------|
+| design | UX Designer | Architect | file-watch |
+| red | TEA | Architect | file-watch |
+| green | Dev | UX Designer | file-watch |
+| review | Reviewer | PM | file-watch |
+
+## Related Infrastructure
+
+| Component | Status | Purpose |
+|-----------|--------|---------|
+| `tandem-lifecycle.ts` | Built | Library module for future WheelHub integration |
+| `observation-writer.ts` | Built | TypeScript API for observation file I/O |
+| `file-watch.ts` | Built | File system change detection |
+| `tool-watch.ts` | Built | Tool call log monitoring |
+| `bell-mode-hook.sh` | Built | PostToolUse hook with tandem injection |
+| `bellmode_hook.py` | Built | Python implementation of bell mode hook |
+| `statusline.sh` | Built | CLI statusline with tandem indicator |
+| `tandem-backseat.md` | Built | Backseat agent prompt template |
+| `agent-behavior.md` | Built | Shared agent behavior with tandem protocol |

package/pennyfarthing-dist/personas/themes/discworld.yaml

@@ -12,7 +12,7 @@ theme:
   default_emoji_use: minimal
   default_humor: enabled
   character_immersion: high
-  user_title: Citizen of Ankh-Morpork 
+  user_title: Citizen of Ankh-Morpork
   portrait_style: ", ink and wash illustration, satirical fantasy, whimsical yet serious"
   tier: A
   dimensions: