@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/commands/prime.md

@@ -0,0 +1,140 @@
+---
+description: Load essential project context at agent activation
+---
+
+<purpose>
+Quickly load essential context files to reduce agent cold-start overhead.
+Automatically invoked on agent activation via agent-session.sh.
+</purpose>
+
+<when-to-use>
+- Automatically on agent activation (`/sm`, `/tea`, `/dev`, `/reviewer`)
+- Manually to refresh context mid-session
+- To verify what context is available
+</when-to-use>
+
+<execution>
+
+## Running /prime
+
+Use the prime.sh script:
+
+```bash
+# Load all essential context (default)
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh
+
+# Minimal mode - CLAUDE.md only (fastest)
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --minimal
+
+# Full mode - include domain docs
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --full
+
+# Quiet mode - suppress headers (used by agent-session.sh)
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --quiet
+
+# With agent sidecar loading
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --agent reviewer
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--minimal` | Load only CLAUDE.md files (fastest startup) |
+| `--full` | Include domain docs from .claude/project/ |
+| `--quiet` | Suppress section headers (for automated use) |
+| `--agent <name>` | Load agent's sidecar patterns (learned project-specific patterns) |
+
+## What Gets Loaded
+
+Context is loaded in priority order:
+
+### Default Mode
+| Priority | Content | Source |
+|----------|---------|--------|
+| 1 | Project instructions | `CLAUDE.md` |
+| 2 | User instructions | `~/.claude/CLAUDE.md` (if exists) |
+| 3 | Sprint summary | `sprint/current-sprint.yaml` (key fields only) |
+| 4 | Active session | `.session/*-session.md` (first 50 lines) |
+| 5 | Agent sidecar | `.pennyfarthing/sidecars/{agent}/*.md` (if `--agent` provided) |
+| 6 | Shared context | `.pennyfarthing/guides/shared-context.md` (project info - all agents) |
+| 7 | Shared behavior | `.pennyfarthing/guides/shared-agent-behavior.md` (protocols - all agents) |
+| 8 | Tactical guide | `.pennyfarthing/guides/tactical-agent-behavior.md` (for sm, tea, dev, reviewer only) |
+
+### Minimal Mode (`--minimal`)
+Only loads CLAUDE.md files (priority 1-2).
+
+### Full Mode (`--full`)
+Adds domain documentation from `.claude/project/CLAUDE-*.md` files.
+
+### Agent Sidecar (`--agent <name>`)
+When agent name is provided, loads the agent's project-specific patterns from their sidecar directory. This gives agents their learned patterns immediately on activation.
+
+### Shared Context (automatic for all agents)
+All agents receive the shared context guide which includes project info, directory structure, git strategy, sprint system overview, and build commands.
+
+### Shared Behavior (automatic for all agents)
+All agents receive the shared behavior guide which includes confidence protocols, sidecar memory system documentation, reasoning modes, and exit protocols.
+
+### Tactical Guide (automatic for tactical agents)
+For tactical agents (sm, tea, dev, reviewer), additionally loads the tactical behavior guide which includes critical patterns for Bash tool usage, session file handling, and handoff protocols.
+
+</execution>
+
+<output-format>
+
+```
+# CLAUDE.md
+[Project instructions content...]
+
+# ~/.claude/CLAUDE.md (if exists)
+[User instructions content...]
+
+---
+# Sprint Context
+Sprint 7: Benchmark framework expansion, monorepo consolidation, rich agent telemetry
+Progress: 62/106 points
+
+---
+# Active Session
+[First 50 lines of session file...]
+```
+
+With `--quiet`, section headers are suppressed.
+
+</output-format>
+
+<integration>
+
+## agent-session.sh Integration
+
+The `/prime` command is automatically invoked when agents activate:
+
+1. User invokes `/sm`, `/tea`, `/dev`, or `/reviewer`
+2. `agent-session.sh start` runs
+3. Persona XML is output
+4. `/prime --quiet --agent <agent-name>` loads context automatically
+5. Agent starts with full context AND their learned patterns loaded
+
+This reduces the "cold start" problem where agents must discover context through multiple file reads. The `--agent` flag ensures each agent gets their project-specific sidecar patterns immediately.
+
+## Manual Refresh
+
+If context becomes stale mid-session, run `/prime` manually:
+
+```bash
+/prime        # Refresh standard context
+/prime --full # Include domain docs
+```
+
+</integration>
+
+<reference>
+- **Script:** `.pennyfarthing/scripts/prime.sh`
+- **Called by:** agent-session.sh on agent start (with `--agent` flag)
+- **Loads:** CLAUDE.md, sprint, session, sidecar, shared context, shared behavior, tactical guide
+- **Sidecar location:** `.pennyfarthing/sidecars/{agent}/*.md`
+- **Shared context:** `.pennyfarthing/guides/shared-context.md` (all agents)
+- **Shared behavior:** `.pennyfarthing/guides/shared-agent-behavior.md` (all agents)
+- **Tactical guide:** `.pennyfarthing/guides/tactical-agent-behavior.md` (sm, tea, dev, reviewer only)
+</reference>

package/pennyfarthing-dist/commands/release.md

@@ -0,0 +1,58 @@
+---
+description: Merge develop to main and push (optional version bump)
+---
+
+```bash
+./scripts/run.sh release.sh "$@"
+```
+
+<purpose>
+Release current develop branch to main and push to origin.
+</purpose>
+
+<usage>
+```bash
+# Just merge and push (no version change)
+/release
+
+# With version bump
+/release --bump patch    # 1.5.0 -> 1.5.1
+/release --bump minor    # 1.5.0 -> 1.6.0
+/release --bump major    # 1.5.0 -> 2.0.0
+
+# Preview what would happen
+/release --dry-run
+/release --bump patch --dry-run
+```
+</usage>
+
+<workflow>
+1. Pre-flight checks (clean working directory, branches exist)
+2. Pull latest develop and main
+3. Merge develop into main (fast-forward when possible)
+4. Push main to origin
+5. Push develop to origin
+6. Push any tags
+
+If `--bump` specified, delegates to `deploy.sh` which also:
+- Bumps VERSION file
+- Commits version change
+- Creates annotated git tag
+- Creates GitHub release from the tag (requires `gh` CLI)
+</workflow>
+
+<when-to-use>
+- After completing a sprint or set of features
+- When develop is stable and ready for production
+- Before deploying to production environments
+</when-to-use>
+
+<prerequisites>
+- Clean working directory (no uncommitted changes)
+- On develop branch (or will switch to it)
+- Origin remote configured
+</prerequisites>
+
+<skills>
+- `/changelog` - For changelog format reference, auto-generation patterns, and version bump decisions
+</skills>

package/pennyfarthing-dist/commands/repo-status.md

@@ -0,0 +1,49 @@
+---
+description: Check git status of all project repos
+---
+
+# Repository Status Check
+
+Check the git status of all project repos at once.
+
+## Configuration
+
+Repos are configured in `.claude/project/repos.yaml`. The script automatically reads this configuration.
+
+## Instructions
+
+Run this command to show the status of all repos:
+
+```bash
+$CLAUDE_PROJECT_DIR/scripts/run.sh git-status-all.sh
+```
+
+For a brief one-line-per-repo summary:
+
+```bash
+$CLAUDE_PROJECT_DIR/scripts/run.sh git-status-all.sh --brief
+```
+
+## What It Shows
+
+For each configured repo:
+- Current branch
+- Whether there are uncommitted changes
+- Whether the repo is ahead/behind origin
+- Unpushed commits (if any)
+
+## Adding More Repos
+
+To add repos, edit `.claude/project/repos.yaml`:
+
+```yaml
+repos:
+  my-api:
+    path: my-api        # relative to project root
+    type: api
+    language: go
+  my-ui:
+    path: my-ui
+    type: ui
+    language: typescript
+```

package/pennyfarthing-dist/commands/retro.md

@@ -0,0 +1,200 @@
+---
+description: Facilitate a sprint retrospective
+---
+
+# Retro - Sprint Retrospective
+
+You are facilitating a **sprint retrospective** to reflect on what happened, learn from it, and improve.
+
+## Pre-Retro: Load Context
+
+First, load the sprint data:
+```bash
+# Check sprint status
+cat sprint/current-sprint.yaml
+
+# Check completed work
+ls -la sprint/archive/
+
+# Check any session handoffs
+cat .session/{STORY_ID}-session.md 2>/dev/null || echo "No active work"
+```
+
+## Retro Format: 4 Ls
+
+### 1. Liked (What went well?)
+- What worked?
+- What should we keep doing?
+- What made us proud?
+
+### 2. Learned (What did we discover?)
+- New techniques or approaches
+- Things we didn't know before
+- Surprises (good or bad)
+
+### 3. Lacked (What was missing?)
+- Resources we needed
+- Information gaps
+- Tools or processes that would have helped
+
+### 4. Longed For (What do we wish we had?)
+- Improvements for next time
+- Things to try
+- Experiments to run
+
+## Output Template
+
+```markdown
+## Sprint [N] Retrospective
+**Date**: [Date]
+**Sprint Goal**: [Goal from sprint file]
+**Velocity**: [Planned] planned / [Completed] completed
+
+### Liked
+- [Thing that went well]
+- [Another positive]
+
+### Learned
+- [Discovery or insight]
+- [Technical learning]
+
+### Lacked
+- [Missing resource/info]
+- [Gap identified]
+
+### Longed For
+- [Improvement idea]
+- [Experiment to try]
+
+### Action Items
+| Action | Owner | Due |
+|--------|-------|-----|
+| [Specific action] | [Agent/Person] | [Next sprint] |
+
+### Metrics
+- Stories completed: X/Y
+- Bugs fixed: N
+- Tech debt addressed: [List]
+- Tests added: N
+```
+
+## Sidecar Maintenance
+
+Review and consolidate agent sidecars during retro:
+
+### 1. Review Sidecar Entries
+
+```bash
+echo "=== Sidecar Entries This Sprint ==="
+for agent in dev tea sm reviewer architect; do
+    SIDECAR=".claude/project/agents/${agent}-sidecar"
+    if [ -d "$SIDECAR" ]; then
+        echo "--- $agent ---"
+        for file in "$SIDECAR"/*.md; do
+            [ -f "$file" ] && grep -l "$(date +%Y)" "$file" 2>/dev/null && cat "$file"
+        done
+    fi
+done
+```
+
+### 2. Consolidate Learnings
+
+For each sidecar entry, ask:
+- **Still relevant?** Keep if yes, remove if no
+- **Needs updating?** Refine based on experience
+- **Promote to docs?** If it's general knowledge, move to project docs
+
+### 3. Prune Stale Entries
+
+Remove entries that:
+- Were one-time fixes
+- No longer apply (code changed)
+- Have been superseded by newer learnings
+
+### 4. Cross-Pollinate
+
+If Dev learned something TEA should know:
+- Add reference to TEA's sidecar
+- Or move to shared docs if both need it
+
+### Sidecar Health Check
+
+```bash
+echo "=== Sidecar Health ==="
+for agent in dev tea sm reviewer; do
+    SIDECAR=".claude/project/agents/${agent}-sidecar"
+    if [ -d "$SIDECAR" ]; then
+        ENTRIES=$(grep -c "^## " "$SIDECAR"/*.md 2>/dev/null | awk -F: '{sum+=$2} END {print sum}')
+        echo "$agent: $ENTRIES entries"
+    fi
+done
+```
+
+**Target:** 5-15 entries per agent. More = too noisy. Fewer = not capturing enough.
+
+---
+
+## Session Artifact Cleanup
+
+During retro, clean up accumulated session artifacts from the sprint:
+
+### 1. Preview Cleanup
+
+```bash
+# See what would be cleaned (dry-run)
+$CLAUDE_PROJECT_DIR/scripts/run.sh session-cleanup.sh --dry-run --aggressive
+```
+
+Review the output. Look for:
+- Files that should NOT be cleaned (active work artifacts)
+- Unexpectedly large number of files (indicates cleanup wasn't running properly)
+
+### 2. Execute Cleanup
+
+```bash
+# Run full cleanup with aggressive mode (archives completed epic contexts)
+$CLAUDE_PROJECT_DIR/scripts/run.sh session-cleanup.sh --aggressive
+```
+
+This removes:
+- Old test result files (7+ days): `test-*.log`, `test-*.md`
+- Old TEA artifacts: `tea-*.md`, `*-red-*.md`, `*-green-*.md`
+- Completed handoff files: `*-handoff*.md`, `*-handoff*.txt`
+- Old lint logs: `lint-*.log`
+- Rotates `session-log.txt` to last 1000 lines
+- Archives epic contexts for completed epics
+
+### 3. Verify Clean State
+
+```bash
+# Check remaining files
+ls -la .session/
+
+# Should only see:
+# - .gitkeep
+# - session-log.txt (rotated)
+# - agents/ directory
+# - Any active work artifacts
+```
+
+---
+
+## Follow-Up Actions
+
+After the retro:
+1. Update sprint/current-sprint.yaml with lessons learned
+2. Create stories for improvement actions
+3. Archive the retro in sprint/archive/
+4. Commit sidecar updates
+5. Verify session cleanup completed successfully
+
+## Usage
+
+```
+/retro                    # Run retro for current sprint
+/retro sprint-1          # Run retro for specific sprint
+```
+
+---
+
+**TIME TO REFLECT. WHAT SPRINT ARE WE REVIEWING?**

package/pennyfarthing-dist/commands/reviewer.md

@@ -0,0 +1,64 @@
+---
+description: Code Reviewer - Critical code review and quality enforcement
+---
+
+<agent-activation>
+**FIRST:** Use Bash tool to run:
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/run.sh" agent-session.sh start "reviewer"
+```
+This finds the project root and loads your persona. Adopt the character shown in the output.
+
+Then load and follow `.pennyfarthing/agents/reviewer.md`
+</agent-activation>
+
+<agent-exit>
+On exit: Capture learnings to sidecar, run `agent-session.sh stop`
+</agent-exit>
+
+<purpose>
+Adversarial code reviewer who demands excellence and prevents flawed code from shipping.
+</purpose>
+
+<when-to-use>
+- After Dev creates PR with GREEN tests
+- Security and architecture concerns need validation
+- Performance implications need assessment
+- Edge cases and error handling need verification
+</when-to-use>
+
+<workflow-position>
+**TDD Flow:** SM → TEA → Dev → **Reviewer**
+
+| Entry | Exit |
+|-------|------|
+| After Dev (tests GREEN + PR created) | Approve → SM (finish) OR Reject → Dev (fixes) |
+</workflow-position>
+
+<workflow-steps>
+1. Receive handoff from Dev with PR link and test results
+2. Spawn pre-flight subagent to gather mechanical data (tests, lint, diff stats)
+3. Read actual code changes using `git diff develop...HEAD`
+4. Apply critical analysis: security, edge cases, performance, architecture
+5. Categorize findings (Critical/Major/Minor)
+6. Make judgment: APPROVE or REJECT
+7. Write assessment to session file
+8. Spawn handoff subagent (approve or reject)
+9. Check context usage; invoke next agent or tell user to start fresh
+</workflow-steps>
+
+<responsibilities>
+| I Do (Opus) | Helper Does (Haiku) |
+|-------------|---------------------|
+| Security analysis, data flow tracing | Run tests, gather lint results |
+| Edge case and performance analysis | Check for code smells |
+| Architecture critique, judgment calls | Gather diff statistics |
+| Write assessment; decide APPROVE/REJECT | Update session for handoff |
+</responsibilities>
+
+<reference>
+- **Agent:** `.pennyfarthing/agents/reviewer.md`
+- **Sidecar:** `.claude/project/agents/reviewer-sidecar/`
+- **Skills:** `/code-review`, `/testing`, `/architecture`
+- **Subagents:** `reviewer-preflight.md`, `reviewer-handoff-approve.md`, `reviewer-handoff-reject.md`
+</reference>

package/pennyfarthing-dist/commands/run-ci.md

@@ -0,0 +1,116 @@
+---
+description: Detect and run CI locally
+---
+
+<purpose>
+Run CI locally by detecting the project's CI system and executing the appropriate commands. Thin wrapper that delegates to project configuration.
+</purpose>
+
+<when-to-use>
+- Before pushing to verify CI will pass
+- To reproduce CI failures locally
+- To run the full CI pipeline without pushing
+- When you want to know what CI system the project uses
+</when-to-use>
+
+<execution>
+
+## Running CI Locally
+
+Use the run-ci.sh script:
+
+```bash
+# Run CI locally (auto-detects CI system)
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/run-ci.sh
+
+# Show what CI system is detected without running
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/run-ci.sh --detect-only
+
+# Show what command would run without executing
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/run-ci.sh --dry-run
+
+# Show help
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/run-ci.sh --help
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--help`, `-h` | Show help message |
+| `--detect-only` | Show detected CI system without running |
+| `--dry-run` | Show what would run without executing |
+
+</execution>
+
+<detection-order>
+
+## CI System Detection
+
+The script detects CI systems in this order:
+
+| Priority | System | Detection | Command |
+|----------|--------|-----------|---------|
+| 1 | Justfile | `just --list` shows `ci` recipe | `just ci` |
+| 2 | GitHub Actions | `.github/workflows/*.yml` exists | `act` |
+| 3 | GitLab CI | `.gitlab-ci.yml` exists | `gitlab-runner exec` |
+| 4 | npm fallback | `package.json` exists | `npm run build && npm test && npm run lint` |
+
+### Package Manager Detection
+
+For npm fallback, the script detects package manager:
+- `pnpm-lock.yaml` or `pnpm-workspace.yaml` → `pnpm`
+- `yarn.lock` → `yarn`
+- Otherwise → `npm`
+
+</detection-order>
+
+<output-format>
+
+## Output Examples
+
+### --detect-only
+```
+Detected CI system: github-actions
+Would run: act
+```
+
+### --dry-run
+```
+Detected: github-actions
+Would run: act
+```
+
+### Running CI
+```
+Running CI: github-actions
+Command: act
+
+[act output follows...]
+```
+
+Exit codes:
+- `0` - CI ran successfully
+- `1` - CI failed or no CI system detected
+
+</output-format>
+
+<requirements>
+
+## Tool Requirements
+
+| CI System | Required Tool | Installation |
+|-----------|--------------|--------------|
+| GitHub Actions | `act` | `brew install act` |
+| GitLab CI | `gitlab-runner` | See GitLab docs |
+| Justfile | `just` | `brew install just` |
+| npm fallback | `npm`/`pnpm`/`yarn` | Comes with Node.js |
+
+If a required tool is not installed, the script will show a warning.
+
+</requirements>
+
+<reference>
+- **Script:** `.pennyfarthing/scripts/run-ci.sh`
+- **Story:** 21-4 (Command & Skill Expansion)
+</reference>

package/pennyfarthing-dist/commands/set-theme.md

@@ -0,0 +1,52 @@
+---
+description: Set the active persona theme
+---
+
+# Set Theme
+
+Change the active persona theme for all agents.
+
+## Arguments
+
+- `<name>` - Theme name to activate (required)
+
+## Instructions
+
+1. If no theme name provided, list available themes:
+   ```bash
+   ls pennyfarthing-dist/personas/themes/*.yaml | xargs -I{} basename {} .yaml | sort
+   ```
+   Then ask the user which theme they want to use.
+
+2. Validate theme exists:
+   ```bash
+   ls pennyfarthing-dist/personas/themes/<name>.yaml
+   ```
+   If not found, show error and list available themes.
+
+3. Read the current config file to prepare for editing:
+   ```bash
+   cat .pennyfarthing/config.local.yaml 2>/dev/null || echo "FILE_NOT_FOUND"
+   ```
+
+4. Set the theme in `.pennyfarthing/config.local.yaml`:
+
+   **If the file exists and has a `theme:` line:**
+   - Use the Edit tool to replace `theme: <old>` with `theme: <new>`
+
+   **If the file doesn't exist or lacks the theme line:**
+   - Use the Write tool to create/overwrite the file:
+   ```yaml
+   # Pennyfarthing Local Configuration
+   # This file is gitignored - your personal preferences
+
+   theme: <name>
+   ```
+
+5. Verify the change was written:
+   ```bash
+   cat .pennyfarthing/config.local.yaml
+   ```
+   Confirm the theme line shows the new value.
+
+6. Inform the user they need to start a new agent session to use the new theme.

package/pennyfarthing-dist/commands/show-theme.md

@@ -0,0 +1,21 @@
+---
+description: Show details of a theme including all agent personas
+---
+
+# Show Theme
+
+Display full details of a theme including all agent character mappings.
+
+## Arguments
+
+- `[name]` - Theme name to show (optional, defaults to current theme)
+
+## Instructions
+
+Run the pennyfarthing CLI to show theme details:
+
+```bash
+pennyfarthing theme show [name]
+```
+
+Present the theme information clearly, showing each agent's character, style, and quote.