@pennyfarthing/core 7.4.0 → 7.4.1

package/pennyfarthing-dist/commands/git-cleanup.md

@@ -0,0 +1,340 @@
+---
+description: Clean up git repos by organizing changes into proper commits/branches by initiative
+---
+
+# Git Cleanup Command
+
+Analyze and organize uncommitted changes across all repos into proper commits and branches based on initiative/feature groupings.
+
+## Git Workflow Rules
+
+**CRITICAL: Never commit directly to develop. Branch protection hooks will reject direct commits.**
+
+All changes MUST follow this workflow:
+1. Create a branch from develop
+2. Commit changes to the branch
+3. Merge to develop locally
+4. Push develop (branches don't need to be pushed)
+
+## Analysis Phase
+
+### 1. Gather Current State and Check for Unpushed Commits
+
+```bash
+./scripts/run.sh git/git-status-all.sh
+```
+
+This shows branch, changes, and unpushed commits for all repos.
+
+### 2. Check Recent Commits for Patterns
+
+```bash
+echo "=== Recent Commit Patterns ==="
+git log --oneline -10 | head -10
+echo ""
+echo "=== Recent Branches ==="
+git branch --sort=-committerdate | head -10
+```
+
+### 3. Check Active Work Sessions
+
+```bash
+echo "=== Active Work ==="
+if [ -f ".session/{STORY_ID}-session.md" ]; then
+  head -30 .session/{STORY_ID}-session.md
+else
+  echo "No active work session"
+fi
+```
+
+### 4. Check Worktree Status
+
+```bash
+echo "=== Worktree Status ==="
+./scripts/run.sh git/worktree-manager.sh status
+```
+
+This shows all active worktrees with their branches and uncommitted changes.
+
+### 5. Check Epics for Story Context
+
+```bash
+echo "=== Active Epics ==="
+head -60 docs/epics.md
+```
+
+## Categorization Guidelines
+
+Group changes by these initiative types (based on conventional commits):
+
+| Prefix | Type | Branch Pattern | Example |
+|--------|------|----------------|---------|
+| `docs:` | Documentation | `docs/description` | docs/update-epics |
+| `chore:` | Maintenance | `chore/description` | chore/sprint-cleanup |
+| `chore(sprint):` | Sprint tracking | `chore/sprint-update` | - |
+| `chore(pennyfarthing):` | Pennyfarthing config | `chore/pennyfarthing-cleanup` | - |
+| `feat:` | New feature | `feat/story-id-desc` | feat/4-12-risk-scoring |
+| `fix:` | Bug fix | `fix/issue-desc` | fix/validation-error |
+| `refactor:` | Code improvement | `refactor/description` | refactor/seed-data |
+
+## Common Change Categories
+
+### Sprint/Docs Changes
+Files: `docs/*.md`, `sprint/*.yaml`, `sprint/*.md`
+- Branch: `chore/sprint-cleanup` or `docs/update-[topic]`
+- Commit: `chore(sprint): update sprint tracking` or `docs: update documentation`
+
+### Pennyfarthing Configuration
+Files: `.claude/**/*`
+- Branch: `chore/pennyfarthing-[description]`
+- Commit: `chore(pennyfarthing): description`
+
+### Feature Work
+Files: `internal/**`, `src/**`, `migrations/**`
+- Branch: `feat/[story-id]-description`
+- Commit: `feat: description`
+
+### Seed/Test Data
+Files: `internal/seed/**`, `cmd/seed/**`
+- Branch: `chore/seed-improvements` or part of feature branch
+- Commit: `chore(seed): description`
+
+### Bug Fixes
+Files: Various
+- Branch: `fix/[issue-description]`
+- Commit: `fix: description`
+
+## Execution Phase - Branch Workflow
+
+**For each group of changes, follow this exact workflow:**
+
+### Step 1: Stash All Changes First
+```bash
+# Stash everything to start clean
+git stash push -m "cleanup-wip"
+```
+
+### Step 2: Create Branch from Develop
+```bash
+# Ensure on develop and up to date
+git checkout develop
+git pull origin develop
+
+# Create feature branch
+git checkout -b type/description
+```
+
+### Step 3: Apply Relevant Changes
+```bash
+# Pop stash
+git stash pop
+
+# Stage only files for this group
+git add <specific-files>
+
+# Stash remaining changes for next group
+git stash push -m "remaining-cleanup"
+```
+
+### Step 4: Commit
+```bash
+# Commit with proper message
+git commit -m "$(cat <<'EOF'
+type(scope): description
+
+Details if needed.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Step 5: Merge to Develop
+```bash
+# Switch to develop
+git checkout develop
+
+# Merge the branch
+git merge type/description
+
+# Delete local branch
+git branch -d type/description
+```
+
+### Step 6: Repeat for Next Group
+```bash
+# Pop remaining stash and repeat from Step 2
+git stash pop
+```
+
+## Multi-Repo Cleanup Pattern
+
+When cleaning up changes across multiple repos (configured in `.claude/project/repos.yaml`):
+
+```bash
+# Source repo utilities
+source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
+
+# For each configured repo, run the same workflow
+for_each_repo '
+  # ... branch workflow ...
+  git status --short
+'
+```
+
+Or manually iterate:
+
+```bash
+source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
+for repo in $(get_repos); do
+  repo_path=$(get_repo_full_path "$repo")
+  echo "=== Processing $repo ==="
+  cd "$repo_path"
+  # ... branch workflow ...
+  cd -
+done
+```
+
+## Interactive Cleanup Process
+
+When running this command, Claude should:
+
+1. **Show current state** - Display all uncommitted changes grouped by repo
+2. **Check for unpushed commits** - Identify any commits on develop not yet pushed
+3. **Analyze changes** - Look for patterns in file paths, recent commits, and epics
+4. **Propose groupings** - Suggest how to organize changes:
+   ```
+   Group 1: Sprint Updates
+   - docs/epics.md
+   - sprint/current-sprint.yaml
+   → Branch: chore/sprint-cleanup
+   → Commit: "chore(sprint): clean up sprint tracking files"
+
+   Group 2: Migration Fix
+   - migrations/056_*.sql
+   → Branch: fix/risk-scoring-migration
+   → Commit: "fix(db): add missing risk scoring migration"
+
+   Group 3: Seed Improvements
+   - internal/seed/*.go
+   → Branch: chore/seed-improvements
+   → Commit: "chore(seed): improve demo data generation"
+   ```
+4. **Ask for confirmation** - Let user approve or modify groupings
+5. **Execute** - Create branches, commit, merge to develop for each group
+6. **Push develop** - Push all merged changes at the end
+7. **Verify** - Show clean git status at the end
+
+## Safety Rules
+
+- **NEVER commit directly to develop** - hooks will reject it
+- **Never force push**
+- **Never commit secrets** (.env, credentials, etc.)
+- **Show diff before committing**
+- **Respect .gitignore**
+- **Handle unpushed commits on develop before starting cleanup**
+
+## Quick Reference
+
+```bash
+# View what needs cleanup (all repos)
+./scripts/run.sh git/git-status-all.sh
+
+# Create cleanup branch
+git checkout develop && git pull
+git checkout -b chore/cleanup-$(date +%Y%m%d)
+
+# Stage specific files
+git add "docs/*.md"
+git add "sprint/*.yaml"
+
+# Commit with proper message (use heredoc for multiline)
+git commit -m "$(cat <<'EOF'
+chore(sprint): update sprint status
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+
+# Merge to develop (local)
+git checkout develop
+git merge chore/cleanup-$(date +%Y%m%d)
+git branch -d chore/cleanup-$(date +%Y%m%d)
+
+# Push develop after all merges complete
+git push origin develop
+```
+
+## Branch Cleanup
+
+Stale feature branches can accumulate over time. Include branch cleanup as part of git hygiene.
+
+### Check for Stale Branches
+
+```bash
+echo "=== Branch Status ==="
+
+./scripts/run.sh misc/check-status.sh
+```
+
+### Remove Merged Branches
+
+**Only remove branches that are fully merged:**
+
+```bash
+# Source repo utilities
+source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
+
+# For each configured repo
+for repo in $(get_repos); do
+  repo_path=$(get_repo_full_path "$repo")
+  echo "=== $repo ==="
+  cd "$repo_path"
+
+  git checkout develop
+  git pull origin develop
+
+  # List branches merged into develop
+  git branch --merged develop | grep -v "develop\|main"
+
+  # Delete merged branches
+  git branch --merged develop | grep -v "develop\|main" | xargs -r git branch -d
+
+  cd -
+done
+```
+
+### Branch Cleanup Criteria
+
+| Branch Type | When to Remove |
+|-------------|----------------|
+| `feat/*` | After PR merged to develop |
+| `fix/*` | After PR merged to develop |
+| `chore/*` | After PR merged to develop |
+
+**Note:** Never delete `main` or `develop` branches.
+
+## Post-Cleanup Verification
+
+```bash
+echo "=== Final State ==="
+./scripts/run.sh git/git-status-all.sh
+echo ""
+echo "=== Branches ==="
+
+# Source repo utilities
+source $CLAUDE_PROJECT_DIR/scripts/repo-utils.sh
+
+for repo in $(get_repos); do
+  repo_path=$(get_repo_full_path "$repo")
+  echo "$repo:" && git -C "$repo_path" branch
+done
+```
+
+---
+
+**Start by analyzing, then propose groupings, then execute with user approval. Always use branches!**

package/pennyfarthing-dist/commands/health-check.md

@@ -0,0 +1,108 @@
+---
+description: Check Pennyfarthing installation health and apply updates
+---
+
+```bash
+./scripts/run.sh core/agent-session.sh start "devops"
+```
+
+<agent-activation>
+1. Load DevOps agent for infrastructure work
+2. Run health check via CLI
+</agent-activation>
+
+<purpose>
+Examine current Pennyfarthing installation, detect drift from expected state, and guide user through fixes/updates.
+</purpose>
+
+<when-to-use>
+- After updating Pennyfarthing (`pennyfarthing update`)
+- When something seems broken
+- Periodic health verification
+- Before starting new sprint
+</when-to-use>
+
+<health-checks>
+
+## Health Check
+
+Use the pennyfarthing CLI:
+
+```bash
+# Full health check
+pennyfarthing doctor
+
+# Or via npx
+npx pennyfarthing doctor
+
+# Auto-fix issues
+pennyfarthing doctor --fix
+```
+
+The CLI checks:
+- manifest.json exists and is valid
+- All managed files present in .claude/pennyfarthing/
+- Symlinks point to correct targets
+- User directories exist (.claude/project/)
+- Settings paths are correct
+- Hook scripts are executable
+
+## Check for Updates
+
+```bash
+# Check if update available
+pennyfarthing update --check
+
+# Apply update
+pennyfarthing update
+```
+
+</health-checks>
+
+<output-format>
+
+```markdown
+# Pennyfarthing Health Check
+
+## Installation: npm v2.2.x
+## Status: [HEALTHY | NEEDS_UPDATE | NEEDS_FIX]
+
+### Checks
+| Check | Status | Detail |
+|-------|--------|--------|
+| Installation | OK | npm v2.2.0 |
+| Core Files | OK | All present |
+| Symlinks | OK | All valid |
+| User Files | OK | 10 sidecars |
+| Directories | OK | sprint/, .session/ |
+| Hooks | WARN | Not executable |
+
+### Recommended Actions
+1. [Action with command to run]
+2. [Action with command to run]
+```
+
+</output-format>
+
+<auto-fixes>
+
+```bash
+pennyfarthing doctor --fix
+```
+
+The CLI can auto-fix:
+- Broken symlinks
+- Missing directories
+- Outdated settings format
+- Non-executable hooks
+
+**Always ask before applying fixes.**
+
+</auto-fixes>
+
+<reference>
+- **CLI:** `pennyfarthing doctor`, `pennyfarthing update`
+- **Manifest:** `.claude/manifest.json` (tracks version and file hashes)
+- **Source:** `.claude/pennyfarthing/` (managed files)
+- **Symlinks:** `.pennyfarthing/agents/`, `.claude/commands/`, etc.
+</reference>

package/pennyfarthing-dist/commands/help.md

@@ -0,0 +1,264 @@
+---
+description: Context-aware help for Pennyfarthing commands, agents, and workflows
+---
+
+<purpose>
+Get help with Pennyfarthing commands, agents, themes, and workflows.
+Provides quick-start guidance for new users and context-aware suggestions based on current work state.
+</purpose>
+
+<when-to-use>
+- New to Pennyfarthing and need orientation
+- Looking for a specific command or agent
+- Want to understand the TDD workflow
+- Need to check available themes
+- Forgot what command to use next
+</when-to-use>
+
+<quick-start>
+
+## New to Pennyfarthing?
+
+Start here:
+
+1. **`/work`** - Smart entry point (resumes existing work or starts new)
+2. **`/new-work`** - Start a fresh work session from backlog
+3. **`/health-check`** - Verify your installation is working
+
+### First Time Setup
+
+If Pennyfarthing isn't installed yet:
+```bash
+npx pennyfarthing init
+```
+
+</quick-start>
+
+<workflow>
+
+## TDD Workflow
+
+Pennyfarthing uses Test-Driven Development with four core agents:
+
+```
+SM → TEA → Dev → Reviewer → SM (finish)
+```
+
+| Phase | Agent | Command | Role |
+|-------|-------|---------|------|
+| Setup | SM (Scrum Master) | `/sm` | Story selection, context creation |
+| RED | TEA (Test Engineer) | `/tea` | Write failing tests |
+| GREEN | Dev (Developer) | `/dev` | Implement to pass tests |
+| Review | Reviewer | `/reviewer` | Code review, quality enforcement |
+| Finish | SM | `/sm` | Merge PR, archive session |
+
+### Workflow Commands
+
+| Command | Description |
+|---------|-------------|
+| `/new-work` | Start a new work session with Pennyfarthing |
+| `/work` | Resume work or start new - smart entry point |
+| `/sm` | Scrum Master - Story coordination and sprint management |
+| `/tea` | Test Engineer/Architect - Test strategy and TDD |
+| `/dev` | Developer - Feature implementation and coding |
+| `/reviewer` | Code Reviewer - Critical code review and quality enforcement |
+| `/check` | Run quality gates (lint, type check, tests) before handoff |
+
+</workflow>
+
+<agents>
+
+## All Agents (24)
+
+### TDD Workflow Agents
+
+| Agent | Command | Role |
+|-------|---------|------|
+| SM | `/sm` | Scrum Master - Story coordination, sprint management, workflow entry/exit |
+| TEA | `/tea` | Test Engineer - Test strategy, TDD design, RED phase |
+| Dev | `/dev` | Developer - Implementation, feature shipping, GREEN phase |
+| Reviewer | `/reviewer` | Code Reviewer - Quality enforcement, adversarial review |
+
+### Specialist Agents
+
+| Agent | Command | Role |
+|-------|---------|------|
+| Architect | `/architect` | System Architect - Technical design and architecture |
+| PM | `/pm` | Product Manager - Strategic planning and prioritization |
+| DevOps | `/devops` | DevOps Engineer - Infrastructure and deployment automation |
+| Tech-Writer | `/tech-writer` | Technical Writer - Documentation creation and maintenance |
+| UX-Designer | `/ux-designer` | UX Designer - User experience design and UI patterns |
+| Orchestrator | `/orchestrator` | Orchestrator - Coordinator of all agents and meta operations |
+
+</agents>
+
+<commands>
+
+## All Commands (43)
+
+### TDD Workflow (7)
+| Command | Description |
+|---------|-------------|
+| `/new-work` | Start a new work session with Pennyfarthing |
+| `/work` | Resume work or start new - smart entry point |
+| `/sm` | Scrum Master - Story coordination and sprint management |
+| `/tea` | Test Engineer/Architect - Test strategy and TDD |
+| `/dev` | Developer - Feature implementation and coding |
+| `/reviewer` | Code Reviewer - Critical code review and quality enforcement |
+| `/check` | Run quality gates (lint, type check, tests) before handoff |
+
+### Specialist Agents (6)
+| Command | Description |
+|---------|-------------|
+| `/architect` | System Architect - Technical design and architecture |
+| `/pm` | Product Manager - Strategic planning and prioritization |
+| `/devops` | DevOps Engineer - Infrastructure and deployment automation |
+| `/tech-writer` | Technical Writer - Documentation creation and maintenance |
+| `/ux-designer` | UX Designer - User experience design and UI patterns |
+| `/orchestrator` | Orchestrator - Coordinator of all agents and meta operations |
+
+### Sprint & Planning (5)
+| Command | Description |
+|---------|-------------|
+| `/sprint-planning` | Facilitate sprint planning session |
+| `/start-epic` | Start an epic - move to current sprint and generate tech context |
+| `/retro` | Facilitate a sprint retrospective |
+| `/sync-work-with-sprint` | Sync Pennyfarthing work session with unified sprint status |
+| `/sync-epic-to-jira` | Sync Pennyfarthing epic to Jira MSSCI project |
+
+### Context & Loading (2)
+| Command | Description |
+|---------|-------------|
+| `/prime` | Load essential project context at agent activation |
+| `/health-check` | Check Pennyfarthing installation health and apply updates |
+
+### Theme Management (5)
+| Command | Description |
+|---------|-------------|
+| `/list-themes` | List all available persona themes |
+| `/show-theme` | Show details of a theme including all agent personas |
+| `/set-theme` | Set the active persona theme |
+| `/create-theme` | Create a new custom persona theme |
+| `/theme-maker` | Interactive wizard for creating custom persona themes |
+
+### Creative & Brainstorm (4)
+| Command | Description |
+|---------|-------------|
+| `/party-mode` | Free-form creative brainstorming with all agents |
+| `/brainstorm` | Structured problem-solving brainstorm session |
+| `/job-fair` | Discover which characters in a theme excel at each role |
+| `/solo` | Run a single agent on a scenario with absolute rubric scoring |
+
+### Benchmarking (2)
+| Command | Description |
+|---------|-------------|
+| `/benchmark` | Compare an agent's performance against a stored baseline |
+| `/benchmark-control` | Create control baseline for a scenario |
+
+### Git & Repository (4)
+| Command | Description |
+|---------|-------------|
+| `/repo-status` | Check git status of all project repos |
+| `/git-cleanup` | Clean up git repos by organizing changes into commits/branches |
+| `/create-branches-from-story` | Create feature branches in both repos from a story |
+| `/release` | Merge develop to main and push (optional version bump) |
+
+### Utility (4)
+| Command | Description |
+|---------|-------------|
+| `/continue-session` | Resume work from a saved checkpoint after context circuit breaker |
+| `/parallel-work` | Start parallel work in a new worktree |
+| `/update-domain-docs` | Update CLAUDE-*.md domain documentation files |
+| `/help` | This help command |
+
+</commands>
+
+<themes>
+
+## Themes
+
+Pennyfarthing agents adopt personas from themed character sets. There are **102 themes** available.
+
+### Popular Themes
+
+| Theme | Description |
+|-------|-------------|
+| `rome` | Characters from HBO's Rome series |
+| `star-trek-tos` | Original Star Trek series characters |
+| `star-trek-tng` | Star Trek: The Next Generation characters |
+| `discworld` | Terry Pratchett's Discworld characters |
+| `shakespeare` | Shakespearean characters |
+| `jane-austen` | Jane Austen novel characters |
+| `breaking-bad` | Breaking Bad characters |
+| `battlestar-galactica` | Battlestar Galactica characters |
+
+Run `/list-themes` to see all 102 available themes.
+
+### Theme Commands
+
+| Command | Description |
+|---------|-------------|
+| `/list-themes` | See all available themes |
+| `/show-theme` | View current theme with character mappings |
+| `/set-theme <name>` | Change to a different theme |
+| `/create-theme` | Create a custom theme |
+| `/theme-maker` | Interactive theme creation wizard |
+
+### Current Theme
+
+Check your current theme:
+```bash
+cat .pennyfarthing/config.local.yaml
+```
+
+</themes>
+
+<context-aware>
+
+## Context-Aware Help
+
+Based on your current state, here's what you might need:
+
+### No Active Session
+- Use `/work` or `/new-work` to begin
+- Check `/health-check` if first time
+
+### In Dev Phase
+- Run `/check` before handoff
+- Then `/reviewer` for code review
+
+### In Review Phase
+- Reviewer will approve or reject
+- Then `/sm` to finish the story
+
+### Between Stories
+- `/work` to pick up next story
+- `/sprint-planning` for planning session
+
+</context-aware>
+
+<reference>
+
+## Documentation
+
+- **Project Setup:** `CLAUDE.md`
+- **Sprint Status:** `sprint/current-sprint.yaml`
+- **Active Session:** `.session/*-session.md`
+- **Agent Definitions:** `pennyfarthing-dist/agents/*.md`
+- **Command Definitions:** `pennyfarthing-dist/commands/*.md`
+- **Theme Files:** `pennyfarthing-dist/personas/themes/*.yaml`
+- **Guides:** `.pennyfarthing/guides/*.md`
+
+## Getting More Help
+
+For detailed help on a specific command, read its definition file:
+```bash
+cat pennyfarthing-dist/commands/<command-name>.md
+```
+
+For agent documentation:
+```bash
+cat pennyfarthing-dist/agents/<agent-name>.md
+```
+
+</reference>