@pennyfarthing/core 11.2.2 → 11.3.2

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

package/pennyfarthing-dist/workflows/installation-check/steps/step-06-legacy.md

@@ -0,0 +1,94 @@
+# Step 6: Legacy Artifact Cleanup
+
+<step-meta>
+step: 6
+name: legacy
+workflow: installation-check
+agent: devops
+gate: true
+next: step-07-tools
+</step-meta>
+
+<purpose>
+Detect and clean up legacy artifacts from previous Pennyfarthing versions. These include old statusline scripts, persona configs at deprecated paths, legacy sidecar directories, and hook commands still using `.sh` scripts instead of `pf hooks` commands. This step has a gate because some fixes delete files.
+</purpose>
+
+<prerequisites>
+- Layout check completed (step 5)
+- User understands current vs legacy file locations
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the legacy category
+2. For each result, explain what the legacy artifact is and why it should be cleaned up:
+   - **legacy/.claude/scripts/statusline.sh**: Old statusline location that may shadow the proper `.pennyfarthing/scripts/misc/statusline.sh`.
+   - **legacy/.claude/persona-config.yaml**: Pre-v7 theme config. Should be migrated to `.pennyfarthing/config.local.yaml`.
+   - **legacy/.claude/project/agents/sidecars**: Pre-v8 sidecar location. Should be at `.pennyfarthing/sidecars/`.
+   - **legacy/sprint/sidecars**: Another pre-v8 sidecar location.
+   - **legacy/.claude/project/hooks/setup-env.sh**: Pre-v9 hook location. Should be at `.pennyfarthing/project/hooks/`.
+   - **settings/statusline-path**: settings.local.json references a legacy statusline script path.
+   - **legacy/hook-commands**: Hook entries in settings.local.json still use `.sh` script paths instead of `pf hooks` commands. The `.sh` scripts work (they're shims) but `pf hooks` is faster — no shell indirection.
+3. For each fix, explain what will be deleted or moved and whether it's reversible
+4. Present gate criteria — user must approve before files are deleted
+
+**IMPORTANT:** Legacy cleanup deletes files. The user may have customized legacy locations. Always explain what will be removed before applying fixes.
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category legacy`
+- Check: No legacy artifacts at `.claude/scripts/`, `.claude/persona-config.yaml`
+- Check: No legacy sidecar directories
+- Check: Hook commands use `pf hooks` not `.sh` scripts
+</actions>
+
+<output>
+Present results:
+
+```markdown
+## Legacy Artifact Check Results
+
+| Artifact | Status | Detail |
+|----------|--------|--------|
+| statusline.sh | ... | ... |
+| persona-config.yaml | ... | ... |
+| agent sidecars | ... | ... |
+| sprint sidecars | ... | ... |
+| project hooks | ... | ... |
+| statusline path | ... | ... |
+| hook commands | ... | ... |
+
+### Cleanup Actions
+[For each warning, explain what the fix will do: delete, move, or update]
+```
+</output>
+
+<gate>
+## Completion Criteria
+- [ ] All legacy artifacts reviewed with user
+- [ ] User understands what each cleanup action will do
+- [ ] User approved or declined each destructive cleanup
+- [ ] No unapproved file deletions performed
+</gate>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category legacy` to clean up (requires gate approval)
+- **[E] Explain** - Deep dive on a specific legacy artifact's history
+- **[C] Continue** - Approve cleanup and proceed to Tools check
+- **[R] Recheck** - Re-run after manual cleanup
+</collaboration-menu>
+
+<next-step>
+After user approves legacy cleanup, proceed to step-07-tools.md for Optional Tools verification.
+</next-step>
+
+## Failure Modes
+
+- Deleting customized legacy files without checking for user modifications
+- Not explaining that `.sh` shims still work (migration is optional optimization)
+- Removing sidecar directories before confirming new location has the content
+
+## Success Metrics
+
+- All legacy artifacts addressed (cleaned up or acknowledged)
+- User made informed decisions about each cleanup action
+- Gate approval recorded

package/pennyfarthing-dist/workflows/installation-check/steps/step-07-tools.md

@@ -0,0 +1,80 @@
+# Step 7: Optional Tools
+
+<step-meta>
+step: 7
+name: tools
+workflow: installation-check
+agent: devops
+gate: false
+next: step-08-summary
+</step-meta>
+
+<purpose>
+Check optional components that enhance but are not required for core Pennyfarthing functionality. These include the Cyclist visual terminal and the pf Python CLI.
+</purpose>
+
+<prerequisites>
+- Core installation verified (steps 1-6)
+</prerequisites>
+
+<instructions>
+1. Run the doctor command for the tools category
+2. For each result, explain what the tool provides and when it's needed:
+   - **cyclist/installed**: Cyclist is the Electron visual terminal for Pennyfarthing. It provides a graphical UI with panels for sprint tracking, diffs, workflow visualization, and more. Not required for CLI-only usage.
+   - **cyclist/node-pty**: node-pty powers the terminal panel in Cyclist. Without it, the embedded terminal won't work but other panels still function.
+   - **cyclist/spawn-helper**: The native binary that node-pty uses to spawn processes. Must have execute permission on macOS/Linux. Missing permission causes `posix_spawnp` failures.
+   - **tools/pf-cli**: The Python `pf` command provides agent activation (`pf agent start`), hook dispatch (`pf hooks`), and sprint management. Required for agent workflows. Installable via `uv tool install pennyfarthing-scripts` or `pipx install pennyfarthing-scripts`.
+3. For missing tools, explain whether they're required or optional based on the user's workflow
+4. Present the collaboration menu
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json --category tools`
+- Check: Cyclist package location and node-pty health
+- Check: `pf` CLI is available and reports a version
+</actions>
+
+<output>
+Present results:
+
+```markdown
+## Optional Tools Check Results
+
+### Cyclist Visual Terminal
+| Check | Status | Detail |
+|-------|--------|--------|
+| installed | ... | ... |
+| node-pty | ... | ... |
+| spawn-helper | ... | ... |
+
+### Python CLI
+| Check | Status | Detail |
+|-------|--------|--------|
+| pf CLI | ... | ... |
+
+### Recommendation
+[Based on results, recommend which tools to install for the user's use case]
+```
+</output>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix --category tools` to fix permissions or install pf CLI
+- **[E] Explain** - Deep dive on a specific tool's purpose
+- **[C] Continue** - Proceed to Summary
+- **[R] Recheck** - Re-run after installing tools
+</collaboration-menu>
+
+<next-step>
+After reviewing tools, proceed to step-08-summary.md for the final health report.
+</next-step>
+
+## Failure Modes
+
+- Installing Cyclist when only CLI usage is needed (unnecessary complexity)
+- spawn-helper permission issues after pnpm install (common on macOS)
+
+## Success Metrics
+
+- User understands which tools they need
+- Required tools (pf CLI) are installed
+- Optional tools have clear install path if wanted

package/pennyfarthing-dist/workflows/installation-check/steps/step-08-summary.md

@@ -0,0 +1,99 @@
+# Step 8: Health Summary
+
+<step-meta>
+step: 8
+name: summary
+workflow: installation-check
+agent: devops
+gate: false
+next: complete
+</step-meta>
+
+<purpose>
+Aggregate results from all previous steps into a final health report with an overall score and prioritized recommendations.
+</purpose>
+
+<prerequisites>
+- All previous steps (1-7) completed
+</prerequisites>
+
+<instructions>
+1. Run the full doctor command to get a complete picture
+2. Aggregate results into a health score:
+   - **HEALTHY**: All checks pass (0 failures, 0 warnings)
+   - **GOOD**: No failures, some warnings (non-critical issues)
+   - **NEEDS_ATTENTION**: 1-3 failures (some features broken)
+   - **NEEDS_FIX**: 4+ failures (significant functionality impaired)
+3. Group remaining issues by priority:
+   - **Critical**: Failures that break core functionality (missing settings.local.json, broken symlinks, missing manifest)
+   - **Important**: Warnings that degrade features (missing hooks, stale commands, non-executable scripts)
+   - **Optional**: Informational items (legacy artifacts, missing optional tools)
+4. For each remaining issue, provide the specific fix command
+5. Write the summary to the output file if configured
+6. Suggest next steps based on the health score
+</instructions>
+
+<actions>
+- Run: `pennyfarthing doctor --json`
+- Write: `{output_file}` with full health report
+</actions>
+
+<output>
+Present the final report:
+
+```markdown
+# Pennyfarthing Health Report
+
+**Project:** {project_root}
+**Version:** {installed_version} / {package_version}
+**Mode:** {installation_type}
+**Health:** {HEALTHY | GOOD | NEEDS_ATTENTION | NEEDS_FIX}
+**Score:** {pass_count}/{total_count} checks passing
+
+## Results by Category
+
+| Category | Pass | Warn | Fail |
+|----------|------|------|------|
+| Installation | ... | ... | ... |
+| Commands & Skills | ... | ... | ... |
+| Hook Configuration | ... | ... | ... |
+| Hook Scripts | ... | ... | ... |
+| Directory Layout | ... | ... | ... |
+| Legacy Artifacts | ... | ... | ... |
+| Optional Tools | ... | ... | ... |
+
+## Remaining Issues (by priority)
+
+### Critical
+[List failures with fix commands]
+
+### Important
+[List warnings with fix commands]
+
+### Optional
+[List informational items]
+
+## Recommended Next Steps
+1. [Based on health score]
+2. [Specific to findings]
+```
+</output>
+
+<collaboration-menu>
+- **[F] Fix** - Run `pennyfarthing doctor --fix` to auto-repair all fixable issues
+- **[E] Explain** - Deep dive on any remaining issue
+- **[C] Continue** - Complete the health check workflow
+- **[R] Recheck** - Run full check again to verify fixes
+</collaboration-menu>
+
+## Failure Modes
+
+- Reporting HEALTHY when critical issues were skipped in earlier steps
+- Not prioritizing issues (user doesn't know what to fix first)
+
+## Success Metrics
+
+- Complete health report generated
+- All issues categorized by priority
+- Clear next steps provided
+- User has actionable path to resolve any remaining issues

package/pennyfarthing-dist/workflows/installation-check/workflow.yaml

@@ -0,0 +1,47 @@
+# Installation Check Workflow
+# Interactive health check with AI-guided explanation and remediation
+#
+# Flow: Foundation → Commands → Hooks (gate) → Scripts → Layout → Legacy (gate) → Tools → Summary
+# Wraps `pennyfarthing doctor --category` for step-by-step guided verification
+#
+# Use for: onboarding, post-update verification, troubleshooting broken installs
+
+workflow:
+  name: installation-check
+  description: Interactive installation health check with AI-guided remediation. Walks through each check category with explanation and targeted fixes.
+  version: "1.0.0"
+  type: stepped
+
+  steps:
+    path: ./steps/
+    pattern: step-{nn}-*.md
+
+  variables:
+    project_root: .
+    doctor_command: pennyfarthing doctor --json
+    output_file: .session/doctor-results.md
+
+  gates:
+    after_steps: [3, 6]
+    gate_marker: "<!-- GATE -->"
+
+  collaboration:
+    menus:
+      - key: F
+        name: Fix
+        description: Apply recommended fixes for this category
+      - key: E
+        name: Explain
+        description: Get detailed explanation of a specific check
+      - key: C
+        name: Continue
+        description: Proceed to next check category
+      - key: R
+        name: Recheck
+        description: Re-run checks after manual changes
+
+  agent: devops
+
+  triggers:
+    types: [installation-check, doctor, health-check]
+    tags: [installation, health, diagnostics]