@pennyfarthing/core 11.0.0 → 11.1.1

package/pennyfarthing-dist/guides/handoff-cli.md

@@ -0,0 +1,116 @@
+# Handoff CLI
+
+<info>
+Python CLI for managing workflow phase transitions. Agents use `pf handoff` to resolve gates, complete phase transitions, and generate handoff markers during their exit protocol.
+</info>
+
+## Commands
+
+### resolve-gate
+
+Check whether the current phase has a gate and what state it's in.
+
+```bash
+pf handoff resolve-gate STORY_ID WORKFLOW PHASE
+```
+
+**Arguments:**
+- `STORY_ID` — Story identifier (e.g., `105-1`)
+- `WORKFLOW` — Workflow name (e.g., `tdd`, `trivial`, `patch`)
+- `PHASE` — Current phase name (e.g., `green`, `implement`, `fix`)
+
+**Output:** YAML `RESOLVE_RESULT` block:
+
+```yaml
+RESOLVE_RESULT:
+  status: ready | skip | blocked
+  gate_file: tests-pass       # Only when status=ready
+  reason: "..."               # Human-readable explanation
+```
+
+| Status | Meaning |
+|--------|---------|
+| `ready` | Gate exists, subagent should evaluate it |
+| `skip` | No gate defined for this phase, proceed directly |
+| `blocked` | Phase cannot transition (exits with code 1) |
+
+### complete-phase
+
+Atomically update the session file to record a phase transition.
+
+```bash
+pf handoff complete-phase STORY_ID WORKFLOW FROM_PHASE TO_PHASE GATE_TYPE
+```
+
+**Arguments:**
+- `STORY_ID` — Story identifier
+- `WORKFLOW` — Workflow name
+- `FROM_PHASE` — Phase being completed (e.g., `green`)
+- `TO_PHASE` — Phase being entered (e.g., `review`)
+- `GATE_TYPE` — Gate that was passed (e.g., `tests_pass`, `skip`, `none`)
+
+**Output:** YAML `COMPLETE_RESULT` block:
+
+```yaml
+COMPLETE_RESULT:
+  status: success | error
+  from_phase: green
+  to_phase: review
+  gate_type: tests_pass
+```
+
+Updates the session file: `**Phase:**` line, timestamps, and phase history table.
+
+### marker
+
+Generate an environment-aware handoff marker block.
+
+```bash
+pf handoff marker NEXT_AGENT
+pf handoff marker --error "Tests failing"
+```
+
+**Arguments:**
+- `NEXT_AGENT` — Agent to hand off to (e.g., `dev`, `tea`, `reviewer`)
+
+**Options:**
+- `--error MSG` — Generate an error marker instead of a handoff
+
+The marker generator detects the current environment (Cyclist, relay mode, context usage) and produces the appropriate marker type:
+
+- **Cyclist + relay mode:** `<!-- CYCLIST:HANDOFF:/agent -->` (auto-executed)
+- **Cyclist + high context:** `<!-- CYCLIST:CONTEXT_CLEAR:/agent -->` (clears context first)
+- **CLI mode:** Plain text `AGENT_COMMAND` block
+
+## Agent Exit Protocol
+
+The handoff CLI is used in sequence during agent exit:
+
+```
+1. Write assessment to session file
+2. pf handoff resolve-gate {story-id} {workflow} {phase}
+   ├── blocked → report error, STOP
+   ├── skip → jump to step 4
+   └── ready → spawn gate subagent → GATE_RESULT
+       ├── fail → fix issues, retry (max 3)
+       └── pass → continue
+3. pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
+4. pf handoff marker {next-agent} → emit marker → EXIT
+```
+
+See `guides/gates.md` for gate file format and evaluation details.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `pennyfarthing_scripts/handoff/cli.py` | Click command definitions |
+| `pennyfarthing_scripts/handoff/resolve_gate.py` | Gate resolution logic |
+| `pennyfarthing_scripts/handoff/complete_phase.py` | Session file atomic updates |
+| `pennyfarthing_scripts/handoff/marker.py` | Environment-aware marker generation |
+| `pennyfarthing_scripts/handoff/gate_runner.py` | Gate subagent spawner |
+| `pennyfarthing_scripts/handoff/gate_file.py` | Gate file discovery |
+
+<info>
+**Related:** `guides/gates.md` (gate system), `agents/agent-behavior.md` (exit protocol), `guides/reflector.md` (marker types)
+</info>

package/pennyfarthing-dist/guides/hooks.md

@@ -14,7 +14,9 @@ Hooks are shell scripts that Claude Code runs at specific events:
 
 ## Pennyfarthing Default Hooks
 
-### SessionStart: session-start.sh
+### SessionStart Hooks
+
+#### session-start.sh
 
 **Location:** `.pennyfarthing/scripts/hooks/session-start.sh`
 
@@ -23,7 +25,13 @@ Initializes the Pennyfarthing environment:
 - Clears stale agent state from previous sessions
 - Sets `PROJECT_ROOT` and `SESSION_ID` environment variables
 
-### SessionStart: setup-env.sh
+#### session-stop.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/session-stop.sh`
+
+Cleans up session state when Claude Code exits.
+
+#### setup-env.sh
 
 **Location:** `.pennyfarthing/project/hooks/setup-env.sh`
 
@@ -32,7 +40,21 @@ Project-specific environment setup. Edit this file to:
 - Configure project-specific paths
 - Initialize project dependencies
 
-### PreToolUse: pre-edit-check.sh
+#### otel-auto-config.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/otel-auto-config.sh`
+
+Auto-configures OTEL telemetry for Cyclist web mode. Checks for a `.cyclist-port` file and sets `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_ENDPOINT` to route Claude Code telemetry to the running Cyclist/BikeRack server.
+
+#### welcome-hook.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/welcome-hook.sh`
+
+Displays a welcome message on session start. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
+
+### PreToolUse Hooks
+
+#### pre-edit-check.sh
 
 **Location:** `.pennyfarthing/scripts/hooks/pre-edit-check.sh`
 
@@ -41,6 +63,64 @@ Protects sensitive files from accidental edits:
 - Blocks: `.git/`, `node_modules/`, `vendor/`
 - Blocks: `.pennyfarthing/*` (managed files)
 
+#### cyclist-pretooluse-hook.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/cyclist-pretooluse-hook.sh`
+
+Cyclist-specific pre-tool validation. Runs additional safety checks when operating inside Cyclist.
+
+#### context-warning.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/context-warning.sh`
+
+Warns agents when context usage is high. Outputs a warning at 60% usage and a critical warning at 85%. Never blocks — warning only (always exits 0).
+
+#### context-circuit-breaker.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/context-circuit-breaker.sh`
+
+Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `context-warning.sh`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
+
+#### schema-validation.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/schema-validation.sh`
+
+Validates file writes against XML schema rules for agent definitions, workflow files, and other structured content.
+
+#### sprint-yaml-validation.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/sprint-yaml-validation.sh`
+
+Validates sprint YAML files on write to prevent structural corruption.
+
+### PostToolUse Hooks
+
+#### bell-mode-hook.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/bell-mode-hook.sh`
+
+Bell mode message injection. Checks the bell mode queue and injects queued messages into the agent's context at the next tool execution. Also handles tandem observation injection.
+
+#### question-reflector-check.sh / question_reflector_check.py
+
+**Location:** `.pennyfarthing/scripts/hooks/question-reflector-check.sh`
+
+Stop hook enforcing that every agent turn ends with a CYCLIST marker. Detects questions, handoff phrases, and validates marker presence. Blocks turns without valid markers in Cyclist mode. The `.sh` file wraps the Python implementation.
+
+### Git Hooks
+
+#### dispatcher-template.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/dispatcher-template.sh`
+
+Template for git hook dispatchers. Installs as `.git/hooks/{hook-name}` and runs all executable scripts in `.git/hooks/{hook-name}.d/` in sorted order. This enables hook chaining — multiple tools can add hooks without overwriting each other.
+
+#### pre-commit.sh / pre-push.sh / post-merge.sh
+
+**Location:** `.pennyfarthing/scripts/hooks/`
+
+Standard git hooks installed into the dispatcher `.d/` directories. Handle linting, validation, and post-merge cleanup.
+
 ## Configuration Schema
 
 Hooks are configured in `.claude/settings.local.json`:
@@ -225,6 +305,8 @@ If a hook fails or behaves unexpectedly:
 
 | Type | Location | Editable |
 |------|----------|----------|
-| Managed hooks | `.pennyfarthing/scripts/hooks/` | No (use pennyfarthing repo) |
+| Managed hooks | `.pennyfarthing/scripts/hooks/` | No (symlinked — edit in `pennyfarthing-dist/`) |
 | Project hooks | `.claude/project/hooks/` | Yes |
 | Settings | `.claude/settings.local.json` | Yes |
+| Git hook dispatchers | `.git/hooks/{name}` | No (installed by `pennyfarthing init`) |
+| Git hook scripts | `.git/hooks/{name}.d/` | Yes (add scripts to `.d/` directories) |

package/pennyfarthing-dist/guides/output-styles.md

@@ -0,0 +1,65 @@
+# Output Styles
+
+<info>
+Configurable response styles that control how agents communicate. Output styles adjust verbosity, tone, and formatting without changing agent behavior or capabilities.
+</info>
+
+## Overview
+
+Output styles are markdown files in `pennyfarthing-dist/output-styles/` that agents load to adjust their communication style. They don't change what agents do — they change how they talk about it.
+
+## Available Styles
+
+### Terse
+
+Minimal, efficient output for experienced users.
+
+- Brief responses — only what's necessary
+- Skip explanations, assume context
+- Bullet points over paragraphs
+- Code output without commentary
+
+### Verbose
+
+Detailed, educational explanations throughout.
+
+- Walk through reasoning step by step
+- Explain context and trade-offs
+- Document decisions and alternatives
+- Cover edge cases and related considerations
+
+### Teaching
+
+Explain reasoning and teach as you go.
+
+- Show your work — explain decisions
+- Point out reusable patterns and principles
+- Suggest alternatives with trade-offs
+- Build understanding by connecting concepts
+- Collaborative tone, not lecturing
+
+## Configuration
+
+Set the output style in `.pennyfarthing/config.local.yaml`:
+
+```yaml
+output_style: terse    # terse | verbose | teaching
+```
+
+When no style is configured, agents use their default communication patterns.
+
+## How It Works
+
+During prime activation, the output style file is loaded and injected into the agent's system prompt alongside the agent definition and persona. The style acts as a behavioral modifier — it constrains how the agent formats and presents its output.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `pennyfarthing-dist/output-styles/terse.md` | Minimal output style |
+| `pennyfarthing-dist/output-styles/verbose.md` | Detailed output style |
+| `pennyfarthing-dist/output-styles/teaching.md` | Educational output style |
+
+## Creating Custom Styles
+
+Add a markdown file to `pennyfarthing-dist/output-styles/` with guidelines for the agent to follow. The file name (without `.md`) becomes the style identifier used in config.

package/pennyfarthing-dist/guides/patterns/approval-gates-pattern.md

@@ -322,7 +322,7 @@ EnterPlanMode:
 
 ### The Assessment-First Protocol
 
-**Critical Pattern:** All agents must write their assessment BEFORE spawning the handoff subagent.
+**Critical Pattern:** All agents must write their assessment BEFORE starting the exit protocol.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
@@ -569,9 +569,9 @@ Gate BLOCKED. Address security issue before proceeding.
 ```
 Agent completes work
     ↓
-Spawns handoff subagent immediately
+Runs exit protocol immediately
     ↓
-Subagent has no assessment to verify
+resolve-gate finds no assessment
     ↓
 Gate is effectively bypassed
 ```
@@ -582,9 +582,9 @@ Agent completes work
     ↓
 Writes assessment to session file
     ↓
-Spawns handoff subagent
+Runs exit protocol (resolve-gate → complete-phase → marker)
     ↓
-Subagent verifies assessment exists
+resolve-gate verifies assessment exists
     ↓
 Gate functions properly
 ```

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

@@ -36,7 +36,7 @@ Each transition is mediated by a **handoff subagent** that updates the session f
 
 ```mermaid
 stateDiagram-v2
-    [*] --> NEW_WORK: /new-work invoked
+    [*] --> NEW_WORK: /pf-session new invoked
 
     NEW_WORK --> SM_SETUP: User selects story
     SM_SETUP --> TEA_RED: Standard story (3+ pts)
@@ -153,7 +153,7 @@ The session file (`.session/{story-id}-session.md`) tracks state:
 ### Agent Responsibilities
 
 #### SM (Scrum Master)
-**Entry:** `/new-work` command
+**Entry:** `/pf-session new` command
 **Role:** Story selection, context creation, finish workflow
 **Files:** `agents/sm.md`
 
@@ -291,9 +291,9 @@ Session file tracks rejection count and issues.
 ### Missing Epic Context
 
 ```
-User runs /new-work → prime detects no epic context
+User runs /pf-session new → prime detects no epic context
 → Returns MISSING_EPIC_CONTEXT state
-→ Blocks until user runs /start-epic
+→ Blocks until user runs /pf-epic start
 ```
 
 ### Context Overflow

package/pennyfarthing-dist/guides/prompt-patterns.md

@@ -141,7 +141,7 @@ Load this agent's persona before activation:
 
 Explains the primary "happy path" workflow for tactical agents.
 
-**Purpose:** Guides users to use `/new-work` rather than invoking agents directly.
+**Purpose:** Guides users to use `/pf-session new` rather than invoking agents directly.
 
 **Structure:**
 ```xml
@@ -152,9 +152,9 @@ Explains the primary "happy path" workflow for tactical agents.
 
 | Command | When to Use |
 |---------|-------------|
-| `/new-work` | Start a NEW story from the backlog |
+| `/pf-session new` | Start a NEW story from the backlog |
 
-**The TDD Flow:** `/new-work` -> SM -> TEA -> Dev -> Reviewer -> SM (finish)
+**The TDD Flow:** `/pf-session new` -> SM -> TEA -> Dev -> Reviewer -> SM (finish)
 
 **Other commands exist** but are not part of the main dev loop.
 </blessed-path-guidance>
@@ -171,13 +171,13 @@ Clarifies that an agent is outside the core TDD loop.
 
 This agent supports the development process but is **not part of the core TDD loop**.
 
-**The Core TDD Loop:** `/new-work` -> SM -> TEA -> Dev -> Reviewer -> SM
+**The Core TDD Loop:** `/pf-session new` -> SM -> TEA -> Dev -> Reviewer -> SM
 
 **When to use {Agent}:**
 - {Use case 1}
 - {Use case 2}
 
-**To start story-based development work,** use `/new-work` instead.
+**To start story-based development work,** use `/pf-session new` instead.
 </support-agent-guidance>
 ```
 

package/pennyfarthing-dist/guides/reflector.md

@@ -34,10 +34,10 @@ Marker pattern: /<!--\s*CYCLIST:(\w+)(?::([^>]+?))?\s*-->/gi
 
 | File | Purpose |
 |------|---------|
-| `packages/shared/src/marker/detect.ts` | `detectMarkers()` — parses markers from text |
-| `packages/shared/src/marker/strip.ts` | `stripMarkers()`, `stripCodeBlocks()` |
-| `packages/shared/src/marker/types.ts` | `MarkerType`, `Marker` interface |
-| `packages/shared/src/marker/constants.ts` | `MARKER_PATTERN`, `MARKER_TYPES` |
+| `packages/core/src/shared/marker/detect.ts` | `detectMarkers()` — parses markers from text |
+| `packages/core/src/shared/marker/strip.ts` | `stripMarkers()`, `stripCodeBlocks()` |
+| `packages/core/src/shared/marker/types.ts` | `MarkerType`, `Marker` interface |
+| `packages/core/src/shared/marker/constants.ts` | `MARKER_PATTERN`, `MARKER_TYPES` |
 | `packages/cyclist/src/public/components/QuickActions.tsx` | Renders action buttons from detected markers |
 | `packages/cyclist/src/public/hooks/useMarkerActions.ts` | Detects markers, builds action metadata |
 | `pennyfarthing-dist/scripts/hooks/question_reflector_check.py` | Stop hook — enforces marker presence |

package/pennyfarthing-dist/guides/session-artifacts.md

@@ -52,7 +52,7 @@ context-epic-{EPIC_NUM}.md
 - `context-epic-10.md`
 
 **Created by:** SM (epic-tech-context task)
-**Archived by:** `sm-finish PHASE=execute` (story), `/start-epic` or `/retro` (epic)
+**Archived by:** `sm-finish PHASE=execute` (story), `/pf-epic start` or `/retro` (epic)
 
 ---
 

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

@@ -237,7 +237,7 @@ When filtered, only shows epics with matching stories.
 ```xml
 <when>
 - Starting new development work
-- `/new-work` is an alias for this command
+- `/pf-session new` is an alias for this command
 Next steps after promote:
 - Review appended YAML in current-sprint.yaml
 - Create Jira epic: `/pf-jira create epic <epic-id>`

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

@@ -102,7 +102,7 @@ When the primary agent receives a tandem injection, it surfaces the observation
 
 ### 7. Cleanup
 
-Before handoff, the primary agent terminates the backseat background task. This must happen before spawning the handoff subagent.
+Before handoff, the primary agent terminates the backseat background task. This must happen before starting the exit protocol.
 
 ## Observation Scopes
 
@@ -143,6 +143,18 @@ From `bdd-tandem.yaml`:
 | green | Dev | UX Designer | file-watch |
 | review | Reviewer | PM | file-watch |
 
+## Tandem Consultation Protocol
+
+For active, synchronous agent-to-agent questions (as opposed to passive observation), see `protocols/tandem-consultation.md`. Key differences:
+
+| Aspect | Backseat (this guide) | Consultation |
+|--------|----------------------|--------------|
+| Mode | Passive observer | Active request/response |
+| Trigger | Phase start (automatic) | Leader-initiated (on demand) |
+| Model | Haiku | Sonnet |
+| Output | Observation file | Structured recommendation |
+| Lifecycle | Background process | Synchronous spawn |
+
 ## Related Infrastructure
 
 | Component | Status | Purpose |

package/pennyfarthing-dist/guides/worktree-mode.md

@@ -11,7 +11,7 @@ Work on multiple stories in parallel using git worktrees.
 ## Quick Start
 
 ```
-/parallel-work
+/pf-session parallel
 ```
 
 This creates a worktree, sets up the session, and starts the TDD flow.
@@ -85,7 +85,7 @@ Ports are stored in the session file and passed to agents.
 
 | Command | Purpose |
 |---------|---------|
-| `/parallel-work` | Start a new parallel work session |
+| `/pf-session parallel` | Start a new parallel work session |
 | `.pennyfarthing/scripts/git/worktree-manager.sh list` | Show active worktrees |
 | `.pennyfarthing/scripts/git/worktree-manager.sh remove <name>` | Clean up a worktree |
 
@@ -94,7 +94,7 @@ Ports are stored in the session file and passed to agents.
 Same flow as main checkout:
 
 ```
-/parallel-work → SM → TEA → Dev → Reviewer → SM (finish)
+/pf-session parallel → SM → TEA → Dev → Reviewer → SM (finish)
 ```
 
 Agents use worktree paths from session file for all operations.

package/pennyfarthing-dist/guides/xml-tags.md

@@ -21,7 +21,7 @@ Tags that affect LLM behavior and attention.
 **Examples:**
 - "Subagent output is NOT visible to Cyclist"
 - "NEVER mark acceptance criteria as complete" (for subagents)
-- "Write assessment BEFORE spawning handoff subagent"
+- "Write assessment BEFORE starting exit protocol"
 
 ### `<gate>`
 
@@ -135,7 +135,7 @@ Read `**Workflow:**` and `**Phase:**` from session. Query:
 OWNER=$(.pennyfarthing/scripts/workflow/phase-owner.sh {workflow} {phase})
 ```
 
-**If OWNER != "dev":** Run `handoff-marker.sh $OWNER`, output result, tell user.
+**If OWNER != "dev":** Run `pf handoff marker $OWNER`, output result, tell user.
 </phase-check>
 ```
 
@@ -150,8 +150,9 @@ OWNER=$(.pennyfarthing/scripts/workflow/phase-owner.sh {workflow} {phase})
 ## MANDATORY: Complete Before Exiting
 
 - [ ] Write Assessment to session file
-- [ ] Spawn `handoff` subagent
-- [ ] Verify handoff completed (subagent emits marker)
+- [ ] Run `pf handoff resolve-gate` — verify gate status
+- [ ] Run `pf handoff complete-phase` — atomic session update
+- [ ] Run `pf handoff marker {next_agent}` — emit marker and EXIT
 </handoff-gate>
 ```