@pennyfarthing/core 10.0.1 → 10.0.2

package/pennyfarthing-dist/commands/update-domain-docs.md

@@ -0,0 +1,83 @@
+---
+description: Update CLAUDE-*.md domain documentation files based on current codebase
+---
+
+# Update Domain Documentation
+
+You are a documentation updater. Your job is to refresh the `internal/CLAUDE-*.md` domain documentation files to reflect the current state of the codebase.
+
+## Process
+
+### 1. Analyze Current Code Structure
+
+For each domain, scan the relevant files and extract:
+- Service files and their main functions
+- Handler files and their endpoints
+- Model files and their structs
+- Worker files (if applicable)
+- Test files
+
+### 2. Domain Mappings
+
+Use these file patterns to identify domain content:
+
+| Domain | Service Pattern | Handler Pattern | Model Pattern | Worker Pattern |
+|--------|-----------------|-----------------|---------------|----------------|
+| ticket | `ticket_*.go`, `activity_*.go`, `event_*.go`, `bulk_*.go` | `ticket_*.go`, `events.go` | `ticket.go`, `activity_log.go`, `event.go` | `event_worker.go` |
+| escalation | `sla_*.go`, `escalation_*.go` | `sla_*.go`, `escalation_*.go` | `sla*.go`, `escalation.go` | `sla_violation_checker.go` |
+| notification | `notifiers/*`, `quota_alert_*.go` | `notification_*.go` | `notification_*.go`, `quota_alert.go` | `notification_*.go` |
+| search | `search_*.go`, `filter_*.go`, `similarity_*.go` | `search_*.go`, `filter_*.go`, `similarity_*.go` | `filter_preset.go` | - |
+| impact | `impact_*.go`, `risk_*.go`, `predictive_*.go` | `ticket_impact_*.go` | `impact.go`, `risk_*.go`, `historical_*.go` | - |
+| asset | `asset_*.go`, `client_asset_*.go`, `completeness_*.go` | `asset_*.go`, `client_asset_*.go`, `completeness_*.go` | `asset.go`, `score_history.go` | - |
+| dashboard | `dashboard_*.go`, `system_metrics_*.go`, `consolidation_*.go`, `metrics_collector.go` | `dashboard_*.go`, `metrics_*.go`, `analytics_*.go` | `dashboard_*.go`, `metrics.go` | - |
+| compliance | `audit_*.go`, `compliance_*.go`, `merkle_*.go` | `audit_*.go`, `compliance_*.go` | `audit_log.go`, `compliance.go`, `legal_hold.go` | - |
+| feedback | `feedback_*.go` | `feedback_*.go` | `feedback.go` | - |
+| client | `client_*.go`, `tenant_*.go`, `resource_*.go` | `client_*.go`, `tenant_*.go` | `client*.go` | - |
+| admin | `admin_*.go` | `admin_*.go` | `admin.go` | - |
+
+### 3. For Each Domain, Update:
+
+1. **Key Files section** - List actual files that exist (exclude _test.go in main list)
+2. **API Endpoints section** - Extract from handler files using grep for route patterns
+3. **Key Concepts** - Keep existing if accurate, update if code changed
+4. **Testing section** - Verify test command patterns work
+
+### 4. Update Process
+
+```bash
+# For each domain, run these to gather info:
+ls internal/services/*{pattern}*.go 2>/dev/null | grep -v _test
+ls internal/handlers/*{pattern}*.go 2>/dev/null | grep -v _test
+ls internal/models/*{pattern}*.go 2>/dev/null | grep -v _test
+ls internal/workers/*{pattern}*.go 2>/dev/null | grep -v _test
+
+# Extract API routes from handlers:
+grep -h "\.GET\|\.POST\|\.PUT\|\.PATCH\|\.DELETE" internal/handlers/{pattern}*.go | head -20
+```
+
+### 5. Output
+
+After updating each file:
+1. Show what changed (new files added, removed files, new endpoints)
+2. Confirm the update was made
+
+### 6. Update Index
+
+After all domain files are updated, refresh `internal/CLAUDE.md`:
+- Update the keyword table if new keywords discovered
+- Update file sizes in any size references
+- Verify all domain files listed exist
+
+## Execution
+
+Start by asking: "Which domains should I update? (all / specific domain names)"
+
+Then systematically:
+1. Scan the codebase for each domain
+2. Compare with existing CLAUDE-{domain}.md
+3. Update files with current information
+4. Report changes made
+
+## Quick Mode
+
+If user says "quick" or "all", update all domains without confirmation prompts.

package/pennyfarthing-dist/commands/ux-designer.md

@@ -0,0 +1,9 @@
+---
+description: UX Designer - User experience design and UI patterns
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
+export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
+python3 -m pennyfarthing_scripts.cli agent start "ux-designer"
+```

package/pennyfarthing-dist/commands/work.md

@@ -0,0 +1,25 @@
+---
+description: Resume work or start new - smart entry point that picks up where you left off
+---
+
+# Resume or Start Work
+
+<agent-activation>
+**FIRST:** Use Bash tool to run:
+```bash
+d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
+export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
+python3 -m pennyfarthing_scripts.cli agent start "sm"
+```
+This loads your persona. Adopt the character shown in the output.
+</agent-activation>
+
+<purpose>
+Smart entry point for picking up work. Activates SM who handles all work coordination.
+</purpose>
+
+<instructions>
+You are now the SM agent. Follow your agent instructions from the activation output.
+
+Your first action is ALWAYS to spawn `workflow-status-check` - this is defined in your agent file.
+</instructions>

package/pennyfarthing-dist/commands/workflow.md

@@ -0,0 +1,21 @@
+---
+description: List available workflows, show current workflow details, and switch workflows mid-session. Use when checking available workflow types (TDD, trivial, agent-docs), viewing current workflow phase, switching to a different workflow pattern, or managing BikeLane stepped workflows.
+---
+
+# /workflow - Workflow Management
+
+Load and follow the workflow skill: `.claude/skills/workflow/skill.md`
+
+Pass any arguments provided by the user to the skill commands.
+
+## Quick Reference
+
+| Command | Action |
+|---------|--------|
+| `/workflow` | List all available workflows |
+| `/workflow list` | List all available workflows |
+| `/workflow show [name]` | Show workflow details (current session if no name) |
+| `/workflow set <name>` | Switch to a different workflow mid-session |
+| `/workflow start <name> [--mode <mode>]` | Start a stepped workflow |
+| `/workflow resume [name]` | Resume an interrupted stepped workflow |
+| `/workflow status` | Show current stepped workflow progress |

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

@@ -0,0 +1,92 @@
+<critical>
+**Session file:** `.session/{story-id}-session.md` - read `**Phase:**`, `**Workflow:**`, `**Repos:**`.
+
+**Tests:** Use `testing-runner` subagent, never run directly.
+
+**Handoff:** Run `handoff-marker.sh {next_agent}` → extract marker → emit → EXIT. See `<agent-exit-protocol>`.
+
+**Sidecars:** Write learnings BEFORE spawning handoff subagent.
+
+**Scripts:** Pennyfarthing scripts are Python-based (`pennyfarthing_scripts/`), not shell—check before assuming `.sh`.
+</critical>
+
+<critical>
+**Story completion is MANDATORY.** A story is NOT done until:
+1. Reviewer approves and merges the PR
+2. SM runs `finish-story.sh` (archive session, update Jira, clean up)
+
+**Never** start new work while stories have open PRs. The merge gate blocks `/sprint work` if open PRs exist.
+
+**If stuck in incomplete state:**
+- Open PRs? → Run `/reviewer` to complete reviews and merge
+- Merged but not finished? → Run `/sm` to trigger finish flow
+</critical>
+
+---
+
+## Reference
+
+<info>
+**Workflow:** SM → TEA → Dev → Reviewer → SM. Trivial skips TEA.
+
+**Skills:** `/sprint`, `/testing`, `/dev-patterns`, `/jira`, `/just`
+
+**Efficiency:** Parallelize reads, batch bash with `&&`, spawn independent subagents together.
+
+**Subagents:** Include skill paths in prompts - they don't auto-load.
+
+**Dogfooding:** Write to `pennyfarthing-dist/` not `.claude/` (symlink issue).
+</info>
+
+---
+
+## Reflector
+
+<critical>
+**EVERY TURN MUST END WITH A CYCLIST MARKER.** Stop hook enforces this.
+
+| Situation | Marker |
+|-----------|--------|
+| Workflow handoff | `<!-- CYCLIST:HANDOFF:/agent -->` |
+| Handoff + context >80% | `<!-- CYCLIST:CONTEXT_CLEAR:/agent -->` |
+| Yes/no question | `<!-- CYCLIST:QUESTION:yesno -->` |
+| Open-ended question | `<!-- CYCLIST:QUESTION:open -->` |
+| Multiple choice | `<!-- CYCLIST:CHOICES:a,b,c -->` |
+| Everything else | `<!-- CYCLIST:CONTINUE -->` |
+</critical>
+
+---
+
+<agent-exit-protocol>
+## Exit Protocol
+
+1. Write assessment to session
+2. Spawn `handoff` subagent → returns `HANDOFF_RESULT: {status, next_agent}`
+3. If blocked → report error, stop
+4. Run `.pennyfarthing/scripts/core/handoff-marker.sh {next_agent}`
+5. Extract marker from YAML output, emit it:
+   ```
+   <!-- CYCLIST:HANDOFF:/dev -->
+
+   Run `/dev` to continue
+   ```
+6. EXIT (nothing after marker)
+</agent-exit-protocol>
+
+<wrong-phase-detection>
+## Wrong Phase Detection
+
+On activation, check if story phase belongs to you:
+
+```bash
+OWNER=$(.pennyfarthing/scripts/workflow/phase-owner.sh {workflow} {phase})
+# If OWNER != your agent → emit handoff marker and EXIT
+```
+
+Output:
+```
+<!-- CYCLIST:HANDOFF:/{OWNER} -->
+
+Run `/{OWNER}` to continue
+```
+</wrong-phase-detection>