@pennyfarthing/core 7.4.1 → 7.5.0

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

@@ -1,340 +0,0 @@
----
-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

@@ -1,108 +0,0 @@
----
-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

@@ -1,264 +0,0 @@
----
-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>