@pennyfarthing/core 7.9.2 → 7.9.5

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,7 @@
+---
+description: UX Designer - User experience design and UI patterns
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "ux-designer"
+```

package/pennyfarthing-dist/commands/work.md

@@ -0,0 +1,23 @@
+---
+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/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "sm"
+```
+This finds the project root and 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,311 @@
+# Agent Behavior Guide
+
+**For all Pennyfarthing agents.**
+
+---
+
+## Critical Protocols
+
+<critical>
+**Reflector markers:** Run `handoff-marker.sh {next_agent}` as your ABSOLUTE LAST ACTION and output the result verbatim. See `<agent-exit-protocol>` below.
+</critical>
+
+<critical>
+**Path resolution:** Use `.pennyfarthing/scripts/core/run.sh` for all script calls - it handles path resolution.
+For direct commands, use relative paths from project root (Claude Code starts there).
+
+```bash
+# GOOD: Use run.sh wrapper
+.pennyfarthing/scripts/core/run.sh workflow/check.sh
+
+# GOOD: Relative paths for simple commands
+just test
+npm run build
+
+# BAD: $CLAUDE_PROJECT_DIR doesn't exist in Bash calls
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/foo.sh  # BROKEN!
+```
+</critical>
+
+<critical>
+**Session file:** `.session/{story-id}-session.md` - extract `**Phase:**` (whose turn), `**Workflow:**`, `**Repos:**`, `**Feature Branch:**`.
+</critical>
+
+<critical>
+**Handoff Action:** After handoff subagent returns, run `handoff-marker.sh` as LAST action, output result, EXIT.
+</critical>
+
+<critical>
+**Test delegation:** Never run tests directly. Always use `testing-runner` subagent.
+</critical>
+
+<critical>
+**Sidecar memory:** Capture learnings BEFORE spawning handoff subagent. Don't wait until exit.
+</critical>
+
+---
+
+## Reference
+
+<info>
+**Workflow:** SM → TEA → Dev → Reviewer → SM (finish). Trivial (1-2 pts) skips TEA.
+
+**Confidence:** HIGH=proceed, MEDIUM=ask before risky, LOW=always ask.
+
+**Skills:** `/sprint-context`, `/testing`, `/dev-patterns`, `/jira`, `/just`
+
+**Reflector:** HTML comments parsed by Cyclist UI (see below).
+
+**Turn efficiency:** Parallelize reads, batch bash with `&&`, spawn independent subagents together.
+
+**Background tasks:** Don't block unless result needed. Cyclist notifies on completion.
+
+**Sidecar location:** `.pennyfarthing/sidecars/{agent}/` with `patterns.md`, `gotchas.md`, `decisions.md`.
+
+**Subagent skills:** Include skill paths in prompts - subagents don't auto-load skills.
+
+**Worktree:** Get path from session: `WORKTREE_PATH=$(grep "^path:" "$SESSION_FILE" | cut -d' ' -f2)`
+
+**Dogfooding:** Write to `pennyfarthing-dist/` not `.claude/` (symlink permission issue).
+</info>
+
+---
+
+## Project Context
+
+<info>
+**Project:** Pennyfarthing - Claude Code agent orchestration (pnpm monorepo, TypeScript)
+
+**Key paths:**
+- `pennyfarthing-dist/` - agents, commands, skills, guides, personas
+- `sprint/current-sprint.yaml` - active sprint
+- `.session/` - active work sessions
+
+**Git:** Branch from `develop`, PR to `develop`, release merges to `main`.
+
+**Commit:** `<type>(<scope>): <subject>` + `Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>`
+
+**Build:** `npm run build`, `npm test`, `npm run lint`
+</info>
+
+---
+
+## Sprint YAML and Jira Interaction Rules
+
+<critical>
+**Never directly edit sprint YAML.** All sprint YAML modifications MUST go through dedicated scripts.
+</critical>
+
+<info>
+**Rule 1:** Use `/sprint` skill for sprint operations
+- `/sprint status` - View sprint
+- `/sprint backlog` - View available stories
+- `/sprint work` - Start a story
+- `/sprint archive` - Archive completed story
+
+**Rule 2:** Use `/story` skill for story operations
+- `/story finish` - Complete story (handles YAML, Jira, merge, archive)
+- `/story create` - Add new story to sprint
+
+**Rule 3:** Use `/jira` skill for all Jira operations
+- `/jira claim` - Assign and move to In Progress
+- `/jira move` - Transition status
+- `/jira view` - Check status
+- `/jira sync` - Sync YAML ↔ Jira
+
+**Rule 4:** All sprint YAML access goes through scripts
+```bash
+# GOOD: Use scripts for ALL operations
+.pennyfarthing/scripts/core/run.sh sprint/get-story-field.sh X-Y workflow
+.pennyfarthing/scripts/core/run.sh sprint/get-epic-field.sh 35 jira
+.pennyfarthing/scripts/core/run.sh sprint/check-story.sh X-Y
+
+# BAD: Direct yq queries (even read-only)
+yq '.epics[].stories[] | ...' sprint/current-sprint.yaml
+```
+
+**Script Responsibilities:**
+| Operation | Script | Skill |
+|-----------|--------|-------|
+| Get story field | `get-story-field.sh` | - |
+| Get epic field | `get-epic-field.sh` | - |
+| Check story/epic | `check-story.sh` | `/sprint work` |
+| Start story | `jira-claim-story.sh` | `/jira claim` |
+| Finish story | `finish-story.sh` | `/story finish` |
+| Archive story | `archive-story.sh --apply` | `/sprint archive` |
+| Sync to Jira | `sync-epic-jira.sh` | `/jira sync` |
+| Create epic | `create-jira-epic.sh` | `/jira create epic` |
+</info>
+
+---
+
+
+## Persona System
+
+<info>
+**Config:** `.pennyfarthing/config.local.yaml` with `theme:` field.
+
+**many themes available:** `/list-themes` to browse, `/show-theme <name>` for details, `/set-theme <name>` to change.
+
+**Categories:** TV Series, Film, Literature, Anime, Games, History/Mythology.
+
+**Attributes:** `verbosity` (low/medium/high), `formality` (formal/casual/playful), `humor` (enabled/disabled/subtle).
+
+**Per-agent override:**
+```yaml
+overrides:
+  reviewer:
+    theme: discworld  # Keep Granny even in Star Trek mode
+```
+</info>
+
+---
+
+## Reflector
+
+<critical>
+**EVERY TURN MUST END WITH A CYCLIST MARKER.** A Stop hook enforces this - you will be blocked if you forget.
+</critical>
+
+<info>
+HTML comments that agents emit to signal Cyclist UI. Format: `<!-- CYCLIST:TYPE:value -->`
+
+| Type | Value | Cyclist Action |
+|------|-------|----------------|
+| `HANDOFF` | `/agent` | Shows "Continue with /agent" button |
+| `CONTEXT_CLEAR` | `/agent` | Clears session, reloads with agent |
+| `QUESTION` | `yesno` or `open` | Shows input dialog |
+| `CHOICES` | `opt1,opt2,opt3` | Shows choice buttons |
+| `CONTINUE` | (none) | Shows "Continue" button for status updates |
+
+**Examples:**
+```
+<!-- CYCLIST:HANDOFF:/tea -->
+<!-- CYCLIST:CONTEXT_CLEAR:/dev -->
+<!-- CYCLIST:QUESTION:yesno -->
+<!-- CYCLIST:QUESTION:open -->
+<!-- CYCLIST:CHOICES:option1,option2,option3 -->
+<!-- CYCLIST:CONTINUE -->
+```
+
+**When to use:**
+- `HANDOFF` - End of phase (TEA→Dev, Dev→Reviewer)
+- `CONTEXT_CLEAR` - Context >80% at handoff
+- `QUESTION`/`CHOICES` - User input needed mid-work
+- `CONTINUE` - Status updates, task completion, any turn that isn't a handoff or question
+</info>
+
+<critical>
+**Marker Selection Guide:**
+
+| Situation | Marker |
+|-----------|--------|
+| Workflow handoff to next agent | `<!-- CYCLIST:HANDOFF:/agent -->` |
+| Handoff with 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 -->` |
+| Status update / task complete | `<!-- CYCLIST:CONTINUE -->` |
+| Providing information | `<!-- CYCLIST:CONTINUE -->` |
+| Reporting an error/blocker | `<!-- CYCLIST:CONTINUE -->` |
+
+**Question types requiring QUESTION/CHOICES markers:**
+- Direct questions ending with `?`
+- Implicit questions: "let me know if...", "would you like...", "should I..."
+- Choice offerings: "Option A or Option B"
+- Requests for input: "what do you think", "your preference"
+- Clarification requests: "could you clarify"
+
+**Exempt from question detection (but still need CONTINUE):**
+- Rhetorical questions you answer yourself
+- Questions inside code blocks or examples
+- Historical context ("the question was...")
+</critical>
+
+---
+
+<agent-exit-protocol>
+## Agent Exit Protocol
+
+### Exit Sequence
+
+1. Write assessment to session file
+2. Spawn `handoff` subagent
+3. Await `HANDOFF_RESULT`
+4. If `status: blocked` → report error, stop
+5. **Run this as ABSOLUTE LAST ACTION:**
+   ```bash
+   .pennyfarthing/scripts/core/handoff-marker.sh {next_agent}
+   ```
+6. **Output the script result verbatim and EXIT**
+
+### HANDOFF_RESULT Format
+
+```
+HANDOFF_RESULT:
+  status: success|blocked
+  next_agent: {agent_name}
+  error: "{message}"  # if blocked
+```
+
+### Script Output (emit verbatim)
+
+```
+---
+AGENT_COMMAND:
+  marker: "<!-- CYCLIST:HANDOFF:/dev -->"
+  fallback: "Run `/dev` to continue"
+---
+```
+
+**Nothing after the marker. EXIT.**
+</agent-exit-protocol>
+
+<wrong-phase-detection>
+## Wrong Phase Detection
+
+When an agent detects the story is NOT in their phase, emit a marker immediately.
+
+### How to Check (works with custom workflows)
+
+1. Read `**Workflow:**` and `**Phase:**` from session file
+2. Query the phase owner:
+   ```bash
+   OWNER=$(.pennyfarthing/scripts/core/run.sh workflow/phase-owner.sh {workflow} {phase})
+   ```
+3. If `$OWNER` != your agent name → story belongs to another agent
+
+### Action When Not Your Phase
+
+```bash
+.pennyfarthing/scripts/core/handoff-marker.sh {OWNER}
+```
+
+Then output the result verbatim. This triggers Cyclist's handoff button.
+
+### Example
+
+Dev reads session: `**Workflow:** tdd`, `**Phase:** review`
+
+```bash
+OWNER=$(.pennyfarthing/scripts/core/run.sh workflow/phase-owner.sh tdd review)
+# Returns: reviewer
+```
+
+Since "reviewer" != "dev", Dev runs:
+```bash
+.pennyfarthing/scripts/core/handoff-marker.sh reviewer
+```
+
+### Do NOT just say "run /reviewer"
+
+Wrong:
+> The story is in review. Run `/reviewer` to continue.
+
+Right:
+> The story is in review phase.
+>
+> <!-- CYCLIST:HANDOFF:/reviewer -->
+>
+> Run `/reviewer` to continue
+</wrong-phase-detection>