@pennyfarthing/core 11.2.1 → 11.3.1

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

@@ -0,0 +1,89 @@
+# BDD Team Workflow - BDD with Native Team Collaboration
+#
+# When to use: Best for UI/UX-heavy stories where sustained parallel
+# collaboration during design and implementation provides more value than
+# periodic tandem consultation. Use this instead of bdd-tandem when the
+# designer-architect and dev-tester pairings need continuous interaction
+# throughout their respective phases.
+#
+# Compared to bdd-tandem: Tandem spawns a Haiku subagent for a single
+# request/response exchange. Team mode spawns full teammate sessions that
+# work in parallel with the lead for the entire phase duration.
+#
+# Team pairings:
+#   - DESIGN phase: UX-Designer (lead) + Architect — Architect validates
+#     technical feasibility of design decisions in real-time
+#   - GREEN phase: Dev (lead) + TEA — TEA verifies tests stay green and
+#     flags regressions as Dev implements
+#
+# Fallback: When native teams are unavailable (non-interactive mode, feature
+# flag off, or CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS not set), phases with
+# team blocks fall back to solo execution. The lead agent works alone —
+# consider using bdd-tandem as an alternative that works in all modes.
+#
+# Flow: SM → UX-Designer (+Architect) → TEA → Dev (+TEA) → Reviewer → SM
+
+workflow:
+  name: bdd-team
+  description: BDD with native team collaboration — architect on design, TEA on green phase
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: design
+      agent: ux-designer
+      input: [session_file, story_context]
+      output: [design_spec, user_flows, wireframes, behavior_scenarios]
+      gate:
+        file: gates/design-review
+        type: design_review
+        condition: UX spec defines user flows and acceptance behaviors
+      team:
+        teammates:
+          - agent: architect
+            task: "Validate technical feasibility of design decisions. Flag constraints via SendMessage."
+
+    - name: red
+      agent: tea
+      input: [design_spec, behavior_scenarios, story_context]
+      output: [failing_tests]
+      gate:
+        file: gates/tests-fail
+        type: tests_fail
+        condition: Behavior scenarios have test coverage
+
+    - name: green
+      agent: dev
+      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
+      team:
+        teammates:
+          - agent: tea
+            task: "Verify tests stay green and flag regressions as Dev implements."
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests, design_spec]
+      output: [approval]
+      gate:
+        file: gates/approval
+        type: approval
+        condition: Code review approved, UX requirements met
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    tags: [team, bdd-team]
+    points:
+      min: 3
+    default: false

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/epics-and-stories/steps/step-05-import-to-future.md

@@ -170,7 +170,7 @@ Display completion message:
 
 Next steps:
 - Use `/pf-sprint` to view the backlog
-- Use `pf sprint epic promote` to move to a sprint when ready
+- Use `pf.sh sprint epic promote` to move to a sprint when ready
 ```
 
 ## SUCCESS CRITERIA:

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-01-analyze.md

@@ -32,7 +32,7 @@ Build a complete picture of uncommitted changes across ALL repos defined in `.cl
 **CRITICAL: Use the multi-repo script, not plain `git status`.**
 
 ```bash
-pf git status
+pf.sh git status
 ```
 
 This shows branch, staged/unstaged changes, and unpushed commits for **all repos** defined in the project configuration.

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-04-verify.md

@@ -34,7 +34,7 @@ Git cleanup summary report including:
 ### 4.1 Final Git Status (All Repos)
 
 ```bash
-pf git status
+pf.sh git status
 ```
 
 Expected: Clean working directory in all repos, or only intentionally skipped files.

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-05-complete.md

@@ -68,7 +68,7 @@ To run git-cleanup again:
 Or for a quick status check across all repos:
 
 ```bash
-pf git status
+pf.sh git status
 ```
 
 ---

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

package/pennyfarthing-dist/workflows/installation-check/steps/step-02-commands.md

@@ -0,0 +1,82 @@
+# Step 2: Commands & Skills
+
+<step-meta>
+step: 2
+name: commands
+workflow: installation-check
+agent: devops
+gate: false
+next: step-03-hooks
+</step-meta>
+
+<purpose>
+Verify that slash commands, skills, user project files, and configuration are properly installed. These are the agent interface layer — what users and agents interact with directly.
+</purpose>
+
+<prerequisites>
+- Foundation check (step 1) completed
+- `.claude/` directory exists
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the commands category
+2. For each result, explain what it checks and why it matters:
+   - **core/commands**: Slash commands (`.claude/commands/pf-*.md`) should be file copies (not symlinks) to avoid node_modules drift. Stale copies mean agents use outdated instructions.
+   - **core/skills**: Skills (`.claude/skills/pf-*/`) should also be file copies. Missing skills break agent workflows.
+   - **project/directory**: `.claude/project/` holds user-specific project configuration.
+   - **project/sidecars**: `.pennyfarthing/sidecars/` stores per-agent learning files that accumulate context across sessions.
+   - **persona-config**: `.pennyfarthing/config.local.yaml` sets the active theme. Without it, agents use default (unthemed) personas.
+   - **settings.local.json**: The most critical user file — registers hooks with Claude Code. Missing = no hooks, no OTEL, no bell mode.
+3. For warnings about stale/symlinked commands, explain the migration from symlinks to copies (v11.3.0+)
+4. Present the collaboration menu
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category commands`
+- Check: `.claude/commands/` contains `pf-*` files (copies, not symlinks)
+- Check: `.claude/skills/` contains `pf-*` directories (copies, not symlinks)
+- Check: `.pennyfarthing/config.local.yaml` exists
+</actions>
+
+<output>
+Present results in a clear table format:
+
+```markdown
+## Commands & Skills Check Results
+
+| Check | Status | Detail |
+|-------|--------|--------|
+| commands | ... | ... |
+| skills | ... | ... |
+| project dir | ... | ... |
+| sidecars | ... | ... |
+| persona config | ... | ... |
+| settings.local.json | ... | ... |
+
+### Issues Found
+[Explain each failure/warning with remediation steps]
+```
+</output>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category commands` to auto-repair
+- **[E] Explain** - Deep dive on a specific check result
+- **[C] Continue** - Proceed to Hook Configuration check
+- **[R] Recheck** - Re-run after manual changes
+</collaboration-menu>
+
+<next-step>
+After reviewing command and skill results, proceed to step-03-hooks.md for Hook Configuration verification.
+</next-step>
+
+## Failure Modes
+
+- Commands still symlinked from pre-v11.3 installs
+- Skills missing after partial update
+- settings.local.json deleted by user accidentally
+
+## Success Metrics
+
+- All commands and skills are file copies (not symlinks)
+- settings.local.json exists
+- User understands the symlink-to-copy migration

package/pennyfarthing-dist/workflows/installation-check/steps/step-03-hooks.md

@@ -0,0 +1,121 @@
+# Step 3: Hook Configuration
+
+<step-meta>
+step: 3
+name: hooks
+workflow: installation-check
+agent: devops
+gate: true
+next: step-04-scripts
+</step-meta>
+
+<purpose>
+Verify all 9 hook configurations in settings.local.json. Hooks are the runtime integration between Pennyfarthing and Claude Code — each one controls a critical behavior. This is the most complex and consequential category, which is why it has a gate.
+</purpose>
+
+<prerequisites>
+- settings.local.json exists (verified in step 2)
+- User understands that hooks are registered in `.claude/settings.local.json`
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the hooks category
+2. For each of the 9 hook checks, explain what it does, why it matters, and the impact of it being missing:
+
+   **SessionStart hooks:**
+   - **session-start-hook**: Exports `PROJECT_ROOT` env var. Without it, agents can't find project files. The most critical hook.
+   - **otel-auto-start**: Starts WheelHub server and configures 5 OTEL env vars for telemetry. Legacy `.sh` version only sets 2 of 5 vars.
+   - **auto-load-sm**: Auto-invokes `/sm` agent on new sessions. Without it, users must manually run `/sm` every time.
+
+   **Stop hooks:**
+   - **stop-hook**: Runs reflector-check to enforce CYCLIST markers at turn end. Without it, Cyclist QuickActions won't render.
+
+   **PostToolUse hooks:**
+   - **post-tool-use-hook**: Bell mode — injects queued messages via `additionalContext`. Without it, `/bell` messages are lost.
+   - **sprint-yaml-validation**: Validates sprint YAML after edits. Without it, malformed YAML breaks SprintPanel.
+
+   **PreToolUse hooks:**
+   - **context-circuit-breaker**: Auto-saves session when context exceeds threshold. Without it, long sessions lose work.
+   - **schema-validation**: Validates XML schema on Write to session/skill/step files. Without it, malformed files slip through.
+
+   **Permissions:**
+   - **benchmark-permissions**: `Bash(claude:*)` needed for parallel benchmarks. Without it, only sequential runs work.
+
+3. For each warning/failure, explain the specific impact and offer targeted fix
+4. Present gate criteria for user approval
+
+**IMPORTANT:** Modifying settings.local.json affects all Claude Code sessions. Explain this to the user before applying fixes.
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category hooks`
+- Read: `.claude/settings.local.json` to show current hook configuration
+</actions>
+
+<output>
+Present results grouped by hook type:
+
+```markdown
+## Hook Configuration Results
+
+### SessionStart Hooks
+| Hook | Status | Detail |
+|------|--------|--------|
+| session-start | ... | ... |
+| otel-auto-start | ... | ... |
+| auto-load-sm | ... | ... |
+
+### Stop Hooks
+| Hook | Status | Detail |
+|------|--------|--------|
+| reflector-check | ... | ... |
+
+### PostToolUse Hooks
+| Hook | Status | Detail |
+|------|--------|--------|
+| bell-mode | ... | ... |
+| sprint-yaml | ... | ... |
+
+### PreToolUse Hooks
+| Hook | Status | Detail |
+|------|--------|--------|
+| context-circuit-breaker | ... | ... |
+| schema-validation | ... | ... |
+
+### Permissions
+| Check | Status | Detail |
+|-------|--------|--------|
+| benchmark-permissions | ... | ... |
+```
+</output>
+
+<gate>
+## Completion Criteria
+- [ ] All 9 hook checks reviewed with user
+- [ ] User understands what each hook controls
+- [ ] Any fixes to settings.local.json approved by user
+- [ ] User confirmed hook configuration is acceptable
+</gate>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category hooks` to add missing hooks
+- **[E] Explain** - Deep dive on a specific hook's behavior
+- **[C] Continue** - Approve configuration and proceed to Scripts check
+- **[R] Recheck** - Re-run after manual edits to settings.local.json
+</collaboration-menu>
+
+<next-step>
+After user approves hook configuration, proceed to step-04-scripts.md for Hook Scripts verification.
+</next-step>
+
+## Failure Modes
+
+- Applying fixes without understanding what each hook does
+- Not realizing settings.local.json changes affect all sessions
+- Skipping gate without reviewing critical hooks (session-start, context-circuit-breaker)
+
+## Success Metrics
+
+- All 9 hooks configured or user made informed decision to skip
+- User understands the relationship between hooks and features
+- Gate approval recorded

package/pennyfarthing-dist/workflows/installation-check/steps/step-04-scripts.md

@@ -0,0 +1,83 @@
+# Step 4: Hook Scripts
+
+<step-meta>
+step: 4
+name: scripts
+workflow: installation-check
+agent: devops
+gate: false
+next: step-05-layout
+</step-meta>
+
+<purpose>
+Verify that hook script files exist on disk and are executable. Step 3 checked that hooks are registered in settings.local.json — this step checks that the script files those hooks point to actually exist and can run.
+</purpose>
+
+<prerequisites>
+- Hook configuration reviewed (step 3)
+- Installation type known (symlink vs copy mode)
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the scripts category
+2. For each result, explain the relationship between the settings entry and the script file:
+   - **hook/* checks**: Scripts in `.pennyfarthing/scripts/hooks/` (symlink mode) or `.claude/pennyfarthing/scripts/hooks/` (copy mode). These are the actual bash scripts that hooks execute.
+   - **Execute permissions**: Scripts must be executable (`chmod +x`). A registered hook pointing to a non-executable script causes "Permission denied" errors on every tool use.
+   - **git-hook/* checks**: Scripts in `.git/hooks/` (pre-commit, pre-push, post-merge). Framework repos should use symlinks to `pennyfarthing-dist/scripts/hooks/`; end-user repos use copies.
+3. For git hooks, explain the difference between framework symlinks and user copies
+4. Present the collaboration menu
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category scripts`
+- Check: Hook scripts at `.pennyfarthing/scripts/hooks/` are executable
+- Check: Git hooks at `.git/hooks/` are up-to-date
+</actions>
+
+<output>
+Present results in two sections:
+
+```markdown
+## Hook Scripts
+
+| Script | Status | Detail |
+|--------|--------|--------|
+| session-start.sh | ... | ... |
+| pre-edit-check.sh | ... | ... |
+| context-warning.sh | ... | ... |
+| context-circuit-breaker.sh | ... | ... |
+| bell-mode-hook.sh | ... | ... |
+| question-reflector-check.sh | ... | ... |
+| sprint-yaml-validation.sh | ... | ... |
+
+## Git Hooks
+
+| Hook | Status | Detail |
+|------|--------|--------|
+| pre-commit | ... | ... |
+| pre-push | ... | ... |
+| post-merge | ... | ... |
+```
+</output>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category scripts` to fix permissions and stale hooks
+- **[E] Explain** - Deep dive on a specific script's behavior
+- **[C] Continue** - Proceed to Layout check
+- **[R] Recheck** - Re-run after manual changes
+</collaboration-menu>
+
+<next-step>
+After reviewing script results, proceed to step-05-layout.md for Directory & File Layout verification.
+</next-step>
+
+## Failure Modes
+
+- Scripts missing after partial update (need `pennyfarthing update`)
+- Execute permission stripped by git or file copy operations
+- Git hooks stale after package version bump
+
+## Success Metrics
+
+- All hook scripts exist and are executable
+- Git hooks match package source (or are custom non-pennyfarthing hooks)

package/pennyfarthing-dist/workflows/installation-check/steps/step-05-layout.md

@@ -0,0 +1,81 @@
+# Step 5: Directory & File Layout
+
+<step-meta>
+step: 5
+name: layout
+workflow: installation-check
+agent: devops
+gate: false
+next: step-06-legacy
+</step-meta>
+
+<purpose>
+Verify that files and directories are at their correct locations. Pennyfarthing has migrated file locations across versions — this step ensures everything is at the current canonical paths and flags any files stuck at old locations.
+</purpose>
+
+<prerequisites>
+- Foundation and commands checks completed (steps 1-2)
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the layout category
+2. For each result, explain the expected location and why it matters:
+   - **dir/sprint**: `sprint/` directory holds sprint tracking YAML files.
+   - **dir/session**: `.session/` stores active work session files for each story.
+   - **layout/manifest**: `.pennyfarthing/manifest.json` tracks installed version.
+   - **layout/config**: `.pennyfarthing/config.local.yaml` stores theme and local settings.
+   - **layout/settings**: `.claude/settings.local.json` registers hooks with Claude Code.
+   - **layout/sidecars**: `.pennyfarthing/sidecars/` stores per-agent learning files.
+   - **layout/project-hooks**: `.pennyfarthing/project/hooks/` stores user-customized hook scripts (setup-env.sh, auto-load-sm.sh).
+   - **layout/*-old-location**: Files found at legacy paths that should be migrated.
+3. For old-location warnings, explain when the migration happened and what the fix does
+4. Present the collaboration menu
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category layout`
+- Check: `sprint/` and `.session/` directories exist
+- Check: Files at canonical `.pennyfarthing/` locations
+</actions>
+
+<output>
+Present results:
+
+```markdown
+## Directory & File Layout Results
+
+| Check | Status | Detail |
+|-------|--------|--------|
+| sprint dir | ... | ... |
+| session dir | ... | ... |
+| manifest location | ... | ... |
+| config location | ... | ... |
+| settings location | ... | ... |
+| sidecars location | ... | ... |
+| project hooks | ... | ... |
+
+### Migration Needed
+[List any files at old locations with migration path]
+```
+</output>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category layout` to migrate files
+- **[E] Explain** - Deep dive on the file layout evolution
+- **[C] Continue** - Proceed to Legacy cleanup check
+- **[R] Recheck** - Re-run after manual moves
+</collaboration-menu>
+
+<next-step>
+After reviewing layout results, proceed to step-06-legacy.md for Legacy artifact cleanup.
+</next-step>
+
+## Failure Modes
+
+- Moving files manually without updating references in settings.local.json
+- Missing sprint/ or .session/ directories (need `pennyfarthing init`)
+
+## Success Metrics
+
+- All files at canonical locations
+- No old-location warnings remaining