@pennyfarthing/core 11.2.2 → 11.3.2

package/pennyfarthing-dist/gates/reviewer-preflight-check.md

@@ -0,0 +1,90 @@
+<gate name="reviewer-preflight-check" model="haiku">
+
+<purpose>
+Composite gate for reviewer preflight. Extends tests-pass with code smell
+detection and error boundary checks. The reviewer-preflight subagent runs
+this gate before the Reviewer does critical analysis.
+</purpose>
+
+<ref gate="gates/tests-pass" />
+
+<check name="no-debug-code">
+No debug artifacts in changed files.
+Search changed files (`git diff --name-only develop...HEAD`) for:
+- `console.log` (not guarded by `process.env.NODE_ENV`)
+- `dangerouslySetInnerHTML`
+- `.skip(` (test skips)
+- `TODO` / `FIXME`
+Count by category. None found = pass.
+</check>
+
+<check name="error-boundaries">
+UI components have error boundaries (UI repos only).
+For React component files in diff, verify error boundary wrapping.
+Skip for non-UI repos.
+</check>
+
+<pass>
+Run all checks from `gates/tests-pass` (test-suite, working-tree, branch-status),
+then run no-debug-code and error-boundaries.
+
+If ALL pass, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: reviewer-preflight-check
+  message: "Preflight clear: tests green, no smells, boundaries present"
+  checks:
+    - name: test-suite
+      status: pass
+      detail: "{passed}/{total} passing ({source: cached|fresh})"
+    - name: working-tree
+      status: pass
+      detail: "No uncommitted changes"
+    - name: branch-status
+      status: pass
+      detail: "On branch {branch}"
+    - name: no-debug-code
+      status: pass
+      detail: "No debug patterns in {N} changed files"
+    - name: error-boundaries
+      status: pass
+      detail: "Error boundaries present (or N/A for non-UI)"
+```
+</pass>
+
+<fail>
+If ANY check fails, report all results. Note: code smells are advisory (YELLOW)
+rather than blocking (RED) — the Reviewer makes the final call.
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: reviewer-preflight-check
+  message: "Preflight issues: {summary}"
+  checks:
+    - name: test-suite
+      status: pass | fail
+      detail: "{test results or failure list}"
+    - name: working-tree
+      status: pass | fail
+      detail: "{clean or list of uncommitted files}"
+    - name: branch-status
+      status: pass | fail
+      detail: "{branch info}"
+    - name: no-debug-code
+      status: pass | fail
+      detail: "{clean or smell counts by category}"
+    - name: error-boundaries
+      status: pass | fail
+      detail: "{present, missing list, or N/A}"
+  recovery:
+    - "Fix failing tests before review"
+    - "Commit or stash uncommitted changes"
+    - "Remove debug code: {locations}"
+    - "Add error boundaries to: {components}"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/gates/sm-setup-exit.md

@@ -0,0 +1,82 @@
+<gate name="sm-setup-exit" model="haiku">
+
+<purpose>
+Verify SM has completed story setup before handing off to the next agent.
+Without a properly configured session file, the next agent cannot function.
+Extracts the inline pre-handoff checklist from sm.md.
+</purpose>
+
+<pass>
+Run these checks in order:
+
+1. **session-exists:** Check `.session/{story-id}-session.md` exists.
+   ```bash
+   ls .session/{story-id}-session.md
+   ```
+
+2. **session-fields-set:** Read session file and verify:
+   - `**Workflow:**` field present and non-empty
+   - `**Phase:**` field present and set to `setup`
+
+3. **story-context-exists:** Verify:
+   - `sprint/context/context-epic-{N}.md` exists (extract epic number from story ID)
+   - Session file contains technical approach section
+   - Session file contains acceptance criteria
+
+4. **branch-created:** For each repo in session `**Repos:**`:
+   - Run `git branch --show-current`
+   - Confirm not on `main` or `develop`
+
+If ALL pass, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: sm-setup-exit
+  message: "Session {story-id} ready. Workflow: {workflow}, Branch: {branch}"
+  checks:
+    - name: session-exists
+      status: pass
+      detail: ".session/{story-id}-session.md exists"
+    - name: session-fields-set
+      status: pass
+      detail: "Workflow: {workflow}, Phase: setup"
+    - name: story-context-exists
+      status: pass
+      detail: "Epic context and story ACs present"
+    - name: branch-created
+      status: pass
+      detail: "Branch {branch} created in {repos}"
+```
+</pass>
+
+<fail>
+If ANY check fails, report all results:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: sm-setup-exit
+  message: "Setup incomplete: {summary}"
+  checks:
+    - name: session-exists
+      status: pass | fail
+      detail: "{exists or missing}"
+    - name: session-fields-set
+      status: pass | fail
+      detail: "{fields present or missing fields list}"
+    - name: story-context-exists
+      status: pass | fail
+      detail: "{context present or missing sections}"
+    - name: branch-created
+      status: pass | fail
+      detail: "{branch status per repo}"
+  recovery:
+    - "Run sm-setup to create session file"
+    - "Set Workflow and Phase fields in session"
+    - "Write story context with technical approach and ACs"
+    - "Create feature branch: git checkout -b feat/{story-slug}"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/guides/agent-behavior.md

@@ -101,46 +101,104 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
 ---
 
 <team-mode>
-## Team Mode Protocol
+## Team Mode — Phase-Scoped Native Teams
 
-When a workflow phase has a `team:` configuration block, the phase agent acts as
-**team lead** and spawns teammates for parallel collaboration within that phase.
+Team mode enables parallel agent collaboration within a single workflow phase using Claude Code's native Agent Teams. The phase agent is always the **team lead**; spawned agents are **teammates**. Teams are created at phase start and destroyed before handoff.
 
-### Team Creation
+**Prerequisites:**
+- Workflow phase has a `team:` block in its YAML definition
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set
+- Interactive session (not `-p` mode)
+- Feature detection passes (`pf detect teams` or equivalent)
 
-On phase entry, detect the `team:` block in workflow YAML. Use `TeamCreate`
-to create a phase-scoped team named after the phase (e.g., `"green-phase"`).
+**If prerequisites are not met:** Fall back to solo execution (optionally with tandem consultation). No error — team mode is always optional.
 
-### Teammate Spawning
+### Detection
 
-Spawn teammates via the Task tool with `team_name` parameter. Each teammate
-runs `pf agent start {agent}` for full Prime activation. Keep spawn prompts
-under 500 tokens — teammates auto-load CLAUDE.md, MCP servers, and skills.
+On activation, check the workflow YAML for a `team:` block on your phase:
 
-### Communication
+```yaml
+phases:
+  - name: green
+    agent: dev
+    team:
+      teammates:
+        - agent: architect
+          task: "Review implementation approach and patterns"
+        - agent: tea
+          task: "Verify tests stay green, flag regressions"
+```
+
+If `team:` is present and prerequisites are met, you are the **team lead** for this phase.
+
+### Team Lead Responsibilities
+
+**On phase entry:**
+
+1. **Create the team:**
+   ```
+   TeamCreate("phase-{PHASE}-{STORY_ID}")
+   ```
+
+2. **Spawn teammates** per workflow YAML config. Each teammate gets a spawn prompt:
+   ```
+   Task(team_name="phase-{PHASE}-{STORY_ID}", name="{agent}",
+        prompt="Run `pf agent start {agent}`. Story: {STORY_ID}.
+                {task assignment from YAML}")
+   ```
+   Teammates auto-load CLAUDE.md, MCP servers, and skills from the working directory. Spawn prompts only need the activation command and task assignment — keep under 500 tokens.
+
+3. **Coordinate via SendMessage.** Use `SendMessage` for all intra-phase communication with teammates:
+   - Assign work: `SendMessage(to="{teammate}", message="Implement the adapter pattern for...")`
+   - Check status: `SendMessage(to="{teammate}", message="Status on your review?")`
+   - Broadcast: `SendMessage(message="Shifting approach — using strategy pattern instead")`
+
+4. **Do your own work.** You are still the primary implementer. Teammates assist — they don't replace you.
+
+**Before exit protocol:**
 
-- **Inter-phase handoff:** Use Reflector markers (`<!-- CYCLIST:HANDOFF -->`)
-  for phase transitions — unchanged from sequential mode.
-- **Intra-phase collaboration:** Use `SendMessage` for real-time teammate
-  communication. Never use markers for intra-phase messaging.
+5. **Shut down all teammates.** This is mandatory before starting the normal exit protocol:
+   ```
+   SendMessage(to="{teammate}", message="Phase complete. Shut down.")
+   ```
+   Wait for teammates to go idle, then:
+   ```
+   TeamDelete("phase-{PHASE}-{STORY_ID}")
+   ```
+
+6. **Proceed with normal exit protocol** (assessment → resolve-gate → complete-phase → marker).
+
+### Teammate Responsibilities
+
+When spawned as a teammate (you receive a task via spawn prompt, not a phase handoff):
 
-### Teammate Behavior
+1. **Recognize you are a teammate, not the lead.** You do not own the phase. You do not run the exit protocol. You do not emit handoff markers.
 
-Teammates know they are NOT the lead. They:
-- Communicate via SendMessage (DMs to lead or other teammates)
-- Go idle when their assigned task is complete
-- Respond to shutdown requests with shutdown_response
+2. **Activate normally** via `pf agent start {agent}`. Read the session file for story context.
 
-### Cleanup Before Handoff
+3. **Communicate via SendMessage.** All collaboration with the lead and other teammates uses `SendMessage`:
+   - Report findings: `SendMessage(to="lead", message="Found coupling issue in...")`
+   - Ask questions: `SendMessage(to="lead", message="Should I use the existing adapter?")`
+   - Share status: `SendMessage(to="lead", message="Review complete. 2 issues found.")`
 
-Before starting the exit protocol, the lead MUST:
-1. Send `shutdown_request` to all teammates via SendMessage
-2. Wait for `shutdown_response` from each teammate
-3. Run `TeamDelete` to clean up the team
-4. Then proceed with normal handoff (resolve-gate → complete-phase → marker)
+4. **Go idle when your task is done.** Once your assigned task is complete, send a final status message and wait. Do not start new work unprompted.
 
-Teams are **phase-scoped** — created at phase start, destroyed at phase end.
-Handoff between phases is unchanged.
+5. **Respond to shutdown requests.** When the lead sends a shutdown message, wrap up immediately. Save any observations to the session file or sidecar, then stop.
+
+### Communication Channels
+
+| Channel | Scope | Used For |
+|---------|-------|----------|
+| `SendMessage` | Intra-phase (within team) | Lead ↔ teammate collaboration, status updates, task assignment |
+| Reflector markers (`<!-- CYCLIST:... -->`) | Inter-phase (between phases) | Handoff from one phase agent to the next — **unchanged** |
+| Session file | Cross-phase persistence | Story state, assessments, ACs — written by lead only in team mode |
+| Sidecar files | Agent learning | Teammates may write to their own sidecar with file locking |
+
+<critical>
+**Never use SendMessage for inter-phase handoff.** Markers and `pf handoff` are the only way to transition between phases. SendMessage is for real-time collaboration within a phase.
+
+**Never use markers for intra-phase communication.** Markers are routing signals for Cyclist UI and the handoff system. They have no meaning inside a team.
+</critical>
 </team-mode>
 
 ---
@@ -167,8 +225,8 @@ Handoff between phases is unchanged.
 ## Exit Protocol
 
 1. Write assessment to session
-2. Terminate tandem backseat (if active)
-3. **If team is active:** Shut down all teammates → `TeamDelete` to clean up
+2. **If team mode active:** Shut down all teammates via `SendMessage`, then `TeamDelete`. Wait for cleanup before proceeding.
+3. Terminate tandem backseat (if active)
 4. `"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff resolve-gate {story-id} {workflow} {phase}` → RESOLVE_RESULT
 5. If blocked → report error, STOP
 6. If skip → jump to step 8

package/pennyfarthing-dist/guides/gates.md

@@ -15,7 +15,12 @@ Gates live in `pennyfarthing-dist/gates/` and are referenced by workflow YAML fi
 | **tests-pass** | `gates/tests-pass.md` | Verify all tests pass, working tree clean, correct branch | Dev → Reviewer transitions |
 | **tests-fail** | `gates/tests-fail.md` | Verify tests are RED (failing) with AC coverage | TEA → Dev transitions |
 | **approval** | `gates/approval.md` | Verify reviewer has issued explicit APPROVED verdict | Reviewer → SM transitions |
-| **confidence-sm** | `gates/confidence-sm.md` | Check if user instruction to SM is ambiguous | SM entry gate |
+| **confidence** | `gates/confidence.md` | Check if user instruction is ambiguous | Any agent entry gate |
+| **dev-exit** | `gates/dev-exit.md` | Composite: tests-pass + no debug code | Dev → Reviewer transitions |
+| **sm-setup-exit** | `gates/sm-setup-exit.md` | Session file, fields, context, branch created | SM → next agent transitions |
+| **merge-ready** | `gates/merge-ready.md` | No open non-draft PRs | SM new work gate |
+| **release-ready** | `gates/release-ready.md` | Composite: tests-pass + build, version, changelog | DevOps pre-deploy |
+| **reviewer-preflight-check** | `gates/reviewer-preflight-check.md` | Composite: tests-pass + code smells, error boundaries | Reviewer preflight |
 
 ## Gate File Format
 
@@ -96,7 +101,7 @@ Extended evaluation criteria can live in `gates/evaluations/`:
 
 | File | Purpose |
 |------|---------|
-| `evaluations/confidence-sm.md` | Detailed rubric for SM confidence scoring |
+| `evaluations/confidence-sm.md` | Historical evaluation of SM confidence gate (led to agent-agnostic `confidence` gate) |
 
 ## Creating Custom Gates
 

package/pennyfarthing-dist/scripts/lib/find-root.sh

@@ -29,6 +29,11 @@ if [[ -n "$_caller_script" ]]; then
         _pkg="${_pkg%/.pennyfarthing}"
         if [[ "$_pkg" == */node_modules/* ]]; then
             PROJECT_ROOT="${_pkg%/node_modules/*}"
+        elif [[ -d "$_pkg/.pennyfarthing" ]]; then
+            PROJECT_ROOT="$_pkg"
+        elif [[ -d "$_pkg/../.pennyfarthing" ]]; then
+            # Dogfooding: pennyfarthing/ inlined inside orchestrator
+            PROJECT_ROOT="$(cd "$_pkg/.." && pwd -P)"
         else
             PROJECT_ROOT="$_pkg"
         fi

package/pennyfarthing-dist/scripts/lib/run-pf.sh

@@ -18,15 +18,22 @@ _pf_project=""
 if [[ -f "$PROJECT_ROOT/pennyfarthing/pyproject.toml" ]]; then
     # Dogfooding: inlined framework repo
     _pf_project="$PROJECT_ROOT/pennyfarthing"
+elif [[ -f "$PROJECT_ROOT/node_modules/@pennyfarthing/core/pyproject.toml" ]]; then
+    # Symlink install: npm package has full Python source
+    _pf_project="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
 elif [[ -f "$PROJECT_ROOT/pyproject.toml" ]]; then
     # Consumer: project-level pyproject.toml with pennyfarthing-scripts dep
     _pf_project="$PROJECT_ROOT"
+elif [[ -f "$PROJECT_ROOT/.pennyfarthing/pyproject.toml" ]]; then
+    # Consumer: auto-generated by pennyfarthing init
+    _pf_project="$PROJECT_ROOT/.pennyfarthing"
 fi
 
 if [[ -z "$_pf_project" ]]; then
     echo "Error: No pyproject.toml found for pennyfarthing-scripts" >&2
     echo "Expected: $PROJECT_ROOT/pennyfarthing/pyproject.toml (dogfooding)" >&2
     echo "      or: $PROJECT_ROOT/pyproject.toml (consumer)" >&2
+    echo "      or: $PROJECT_ROOT/.pennyfarthing/pyproject.toml (auto-generated)" >&2
     exit 1
 fi
 

package/pennyfarthing-dist/skills/pf-settings/skill.md

@@ -0,0 +1,42 @@
+---
+name: pf-settings
+description: |
+  View and manage .pennyfarthing/config.local.yaml settings.
+  Get, set, and show configuration values using dot-path notation.
+args: "[show|get|set] [key] [value]"
+---
+
+# /pf-settings - Configuration Settings
+
+View and manage `.pennyfarthing/config.local.yaml` settings.
+
+## Quick Reference
+
+| Command | CLI | Purpose |
+|---------|-----|---------|
+| `/pf-settings show` | `pf.sh settings show` | Pretty-print all settings |
+| `/pf-settings get <key>` | `pf.sh settings get <key>` | Get value by dot-path |
+| `/pf-settings set <key> <value>` | `pf.sh settings set <key> <value>` | Set value by dot-path |
+
+## Examples
+
+```bash
+# Show all interesting settings (theme, workflow, display, split, last_panel)
+pf.sh settings show
+
+# Get a specific value
+pf.sh settings get theme                    # → fifth-element
+pf.sh settings get workflow.relay_mode       # → True
+pf.sh settings get display.colorPreset      # → catppuccin
+
+# Set a value (auto-coerces bool/int)
+pf.sh settings set workflow.bell_mode false
+pf.sh settings set workflow.relay_mode true
+pf.sh settings set display.colorPreset monokai
+```
+
+## Notes
+
+- Dot-path notation traverses nested keys: `workflow.relay_mode` → `workflow: { relay_mode: ... }`
+- Value coercion: `true`/`false` → bool, numeric strings → int, else string
+- `show` skips large blobs (layout, bikerack_layout, panels, theme_characters) for readability

package/pennyfarthing-dist/skills/skill-registry.yaml

@@ -216,6 +216,21 @@ skills:
     related_skills: []
     keywords: [grants, scopes, tools, runtime, security]
 
+  pf-settings:
+    name: pf-settings
+    description: View and manage .pennyfarthing/config.local.yaml settings
+    category: tools
+    tags: [configuration, settings, config]
+    version: "1.0.0"
+    command_group: settings
+    examples:
+      - context: View all settings
+        invocation: /pf-settings show
+      - context: Get a specific setting
+        invocation: /pf-settings get workflow.relay_mode
+    related_skills: [pf-theme, pf-bc]
+    keywords: [theme, relay, bell, permission, display, config]
+
   pf-persona-benchmark:
     name: pf-persona-benchmark
     description: Run benchmarks to compare persona effectiveness

package/pennyfarthing-dist/templates/pyproject.toml

@@ -0,0 +1,27 @@
+# Auto-generated by pennyfarthing init — provides Python dependencies for hooks.
+# This file enables `uv run --project` to resolve pennyfarthing_scripts.
+# Safe to customize: init/update will not overwrite this file once created.
+
+[project]
+name = "pennyfarthing-scripts"
+version = "0.0.0"
+description = "Python utilities for Pennyfarthing agent orchestration"
+requires-python = ">=3.11"
+
+dependencies = [
+    "pyyaml>=6.0",
+    "ruamel.yaml>=0.18",
+    "httpx>=0.28",
+    "click>=8.0",
+    "pydriller>=2.6",
+]
+
+[project.scripts]
+pf = "pennyfarthing_scripts.cli:main"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["pennyfarthing_scripts*"]

package/pennyfarthing-dist/workflows/bdd-tandem.yaml

@@ -24,6 +24,10 @@ workflow:
     - name: setup
       agent: sm
       output: [session_file, branches, story_context]
+      gate:
+        file: gates/sm-setup-exit
+        type: sm_setup_exit
+        condition: Session file created with workflow, phase, context, and branch
 
     - name: design
       agent: ux-designer
@@ -54,9 +58,9 @@ workflow:
       input: [failing_tests, design_spec, story_context]
       output: [implementation, passing_tests]
       gate:
-        file: gates/tests-pass
-        type: tests_pass
-        condition: All tests passing, UX spec implemented
+        file: gates/dev-exit
+        type: dev_exit
+        condition: Tests green, tree clean, no debug code, correct branch
       tandem:
         partner: ux-designer
         scope: file-watch

package/pennyfarthing-dist/workflows/bdd.yaml

@@ -13,6 +13,10 @@ workflow:
     - name: setup
       agent: sm
       output: [session_file, branches, story_context]
+      gate:
+        file: gates/sm-setup-exit
+        type: sm_setup_exit
+        condition: Session file created with workflow, phase, context, and branch
 
     - name: design
       agent: ux-designer
@@ -37,9 +41,9 @@ workflow:
       input: [failing_tests, design_spec, story_context]
       output: [implementation, passing_tests]
       gate:
-        file: gates/tests-pass
-        type: tests_pass
-        condition: All tests passing, UX spec implemented
+        file: gates/dev-exit
+        type: dev_exit
+        condition: Tests green, tree clean, no debug code, correct branch
 
     - name: review
       agent: reviewer

package/pennyfarthing-dist/workflows/installation-check/steps/step-01-foundation.md

@@ -0,0 +1,77 @@
+# Step 1: Foundation Check
+
+<step-meta>
+step: 1
+name: foundation
+workflow: installation-check
+agent: devops
+gate: false
+next: step-02-commands
+</step-meta>
+
+<purpose>
+Verify the core Pennyfarthing installation exists and is intact. This checks the manifest, core framework directories, symlinks, and file integrity — the foundation everything else depends on.
+</purpose>
+
+<prerequisites>
+- Project has been initialized with `pennyfarthing init`
+- Running from the project root directory
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the installation category
+2. For each result, explain what it checks and why it matters:
+   - **manifest/exists**: The manifest tracks installed version and file hashes. Without it, Pennyfarthing can't detect drift or apply updates.
+   - **core/* directories**: These contain agents, commands, guides, skills, personas, and scripts. Missing directories mean broken agent invocation.
+   - **symlink/* checks** (symlink mode only): Symlinks to node_modules keep files in sync with the installed package version.
+   - **core/integrity**: Detects locally modified framework files that may conflict with updates.
+   - **core/completeness**: Flags missing files that should have been installed.
+3. For any failures, explain the impact and offer remediation
+4. Present the collaboration menu
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category installation`
+- Check: manifest.json exists at `.pennyfarthing/manifest.json`
+- Check: Core directories exist under `.claude/pennyfarthing/` or via symlinks
+</actions>
+
+<output>
+Present results in a clear table format:
+
+```markdown
+## Foundation Check Results
+
+| Check | Status | Detail |
+|-------|--------|--------|
+| manifest | ... | ... |
+| core files | ... | ... |
+| symlinks | ... | ... |
+
+### Issues Found
+[Explain each failure/warning with remediation steps]
+```
+</output>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category installation` to auto-repair
+- **[E] Explain** - Deep dive on a specific check result
+- **[C] Continue** - Proceed to Commands & Skills check
+- **[R] Recheck** - Re-run after manual changes
+</collaboration-menu>
+
+<next-step>
+After reviewing foundation results, proceed to step-02-commands.md for Commands & Skills verification.
+</next-step>
+
+## Failure Modes
+
+- Running from wrong directory (not project root)
+- Manifest missing entirely (needs `pennyfarthing init`)
+- Broken symlinks after `node_modules` cleanup without reinstall
+
+## Success Metrics
+
+- All manifest and core file checks pass
+- User understands each check's purpose
+- Any failures have clear remediation path