@pennyfarthing/core 10.0.1 → 10.0.2

package/pennyfarthing-dist/commands/continue-session.md

@@ -0,0 +1,218 @@
+---
+description: Resume work from a saved checkpoint after context circuit breaker
+---
+
+# Continue Session
+
+<purpose>
+Recovery command for resuming work after the context circuit breaker (85% threshold) halts execution. Loads saved checkpoints and resumes the appropriate agent to continue where you left off.
+</purpose>
+
+<when-to-use>
+- After context circuit breaker blocks further work
+- After a session timeout or interruption
+- When returning to work saved with `checkpoint_save`
+- To recover from any context overflow situation
+</when-to-use>
+
+<usage>
+```
+/continue-session [--list] [--story-id ID]
+```
+
+| Option | Description |
+|--------|-------------|
+| (none) | Interactive: show checkpoints, let user choose |
+| `--list` | Just display available checkpoints, don't restore |
+| `--story-id ID` | Resume specific story directly (skip selection) |
+</usage>
+
+<on-invoke>
+
+## Step 1: Check for Circuit Breaker Agent
+
+First, check if the circuit breaker saved an active agent:
+
+```bash
+source "${PROJECT_ROOT:-.}/.pennyfarthing/scripts/lib/checkpoint.sh"
+SAVED_AGENT=$(checkpoint_restore "circuit_breaker_agent")
+if [[ -n "$SAVED_AGENT" ]]; then
+    echo "Circuit breaker saved agent: $SAVED_AGENT"
+else
+    echo "No circuit breaker agent found"
+fi
+```
+
+**If a saved agent is found:**
+- Invoke that agent's command (e.g., `/sm`, `/dev`, `/tea`, `/reviewer`)
+- The agent will be primed with FULL tier context (fresh session)
+- This restores the exact agent that was active when the circuit breaker triggered
+
+```markdown
+## Circuit Breaker Recovery
+
+The circuit breaker saved your active agent: **{SAVED_AGENT}**
+
+Invoking `/{SAVED_AGENT}` to restore with full context...
+```
+
+Then invoke the Skill tool with skill="{SAVED_AGENT}" to activate the agent.
+
+**If no saved agent**, continue to Step 2 below.
+
+## Step 2: Scan for Checkpoints
+
+Run bash to check for saved checkpoints:
+
+```bash
+CHECKPOINT_FILE="${PROJECT_ROOT:-.}/.session/checkpoints.log"
+if [[ -f "$CHECKPOINT_FILE" ]]; then
+    echo "=== Recent Checkpoints ==="
+    tail -20 "$CHECKPOINT_FILE"
+else
+    echo "No checkpoints found."
+fi
+```
+
+## Step 3: Parse and Present Options (if no saved agent)
+
+If checkpoints exist, parse and present them:
+
+```markdown
+## Available Checkpoints
+
+| # | Timestamp | Label | Data |
+|---|-----------|-------|------|
+| 1 | 2026-01-06T14:30:22Z | phase:3-4 | dev |
+| 2 | 2026-01-06T14:28:15Z | context:3-4 | Working on continue-session command |
+
+Which checkpoint would you like to restore? (Enter number or 'all' for most recent of each label)
+```
+
+Output `<!-- CYCLIST:CHOICES:checkpoint -->` marker, then use AskUserQuestion to let user choose.
+
+## Step 4: Restore Checkpoint
+
+Source the checkpoint utilities and restore:
+
+```bash
+# Source checkpoint utilities
+source "${PROJECT_ROOT:-.}/.pennyfarthing/scripts/lib/checkpoint.sh"
+
+# Restore by label
+PHASE=$(checkpoint_restore "phase:${STORY_ID}")
+CONTEXT=$(checkpoint_restore "context:${STORY_ID}")
+FILES=$(checkpoint_restore "files:${STORY_ID}")
+
+echo "Restored checkpoint:"
+echo "  Phase: $PHASE"
+echo "  Context: $CONTEXT"
+echo "  Files: $FILES"
+```
+
+## Step 5: Find Session File
+
+Look for the matching session file:
+
+```bash
+SESSION_FILE=".session/${STORY_ID}-session.md"
+if [[ -f "$SESSION_FILE" ]]; then
+    echo "Found session file: $SESSION_FILE"
+    head -20 "$SESSION_FILE"
+else
+    echo "Warning: No session file found for story $STORY_ID"
+fi
+```
+
+## Step 6: Resume Appropriate Agent
+
+Based on the restored phase, invoke the appropriate agent:
+
+| Phase | Agent | Command |
+|-------|-------|---------|
+| `setup` or `sm` | TEA | `/tea` |
+| `tea` or `red` | Dev | `/dev` |
+| `dev` or `green` | Reviewer | `/reviewer` |
+| `review` | Reviewer | `/reviewer` |
+| `approved` | SM | `/sm` (finish flow) |
+
+Present to user:
+```markdown
+## Session Restored
+
+**Story:** {STORY_ID} - {title from session}
+**Phase:** {PHASE}
+**Context:** {CONTEXT}
+
+Ready to continue with **{Agent Name}**.
+
+The checkpoint shows you were working on: {CONTEXT}
+
+[Continue] [Show more details] [Cancel]
+```
+
+</on-invoke>
+
+<checkpoint-labels>
+Standard checkpoint labels include the story ID:
+
+| Label Pattern | Purpose | Example |
+|---------------|---------|---------|
+| `circuit_breaker_agent` | **Auto-saved** by circuit breaker | `circuit_breaker_agent` → `dev` |
+| `phase:{story-id}` | Workflow phase | `phase:3-4` → `dev` |
+| `context:{story-id}` | Work summary | `context:3-4` → `Implementing validation` |
+| `files:{story-id}` | Key files | `files:3-4` → `src/api.ts,src/utils.ts` |
+| `branch:{story-id}` | Git branch | `branch:3-4` → `feat/3-4-session` |
+</checkpoint-labels>
+
+<no-checkpoints>
+If no checkpoints are found:
+
+```markdown
+## No Checkpoints Found
+
+No saved checkpoints exist in `.session/checkpoints.log`.
+
+**Options:**
+1. `/work` - Check for active session files
+2. `/new-work` - Start fresh with a new story
+3. Check git stash: `git stash list`
+```
+</no-checkpoints>
+
+<stale-checkpoint-warning>
+If checkpoint is older than 24 hours:
+
+```markdown
+## Stale Checkpoint Warning
+
+The most recent checkpoint is from **{timestamp}** ({hours} hours ago).
+
+The codebase may have changed significantly since then.
+
+**Options:**
+1. [Restore anyway] - Load this checkpoint
+2. [Check git log] - See what changed since checkpoint
+3. [Start fresh] - Begin new work with `/new-work`
+```
+</stale-checkpoint-warning>
+
+<integration>
+This command completes the circuit breaker workflow:
+
+1. Agent works normally
+2. Context reaches 85% → circuit breaker triggers
+3. Circuit breaker **automatically saves** the active agent to `circuit_breaker_agent` checkpoint
+4. User starts new Claude session
+5. User runs `/continue-session`
+6. Command reads `circuit_breaker_agent` checkpoint
+7. Agent is invoked with `/{agent}` command → FULL tier context injection
+8. Agent resumes with complete persona, behavior guide, and session context
+</integration>
+
+<reference>
+- **Checkpoint API:** `.pennyfarthing/scripts/lib/checkpoint.sh`
+- **Circuit Breaker:** `scripts/hooks/context-circuit-breaker.sh`
+- **Related:** `/work`, `/new-work`
+- **Session Files:** `.session/{story-id}-session.md`
+</reference>

package/pennyfarthing-dist/commands/create-branches-from-story.md

@@ -0,0 +1,358 @@
+---
+description: Create feature branches in both repos from a story
+---
+
+# Create Branches from Story Workflow
+
+This workflow helps you create coordinated feature branches in the subrepos (`API`, `UI`) from a story or feature request.
+
+## Prerequisites
+
+- [ ] Story/feature is defined
+- [ ] You're on the main branch in both repos
+- [ ] Working directory is clean (no uncommitted changes)
+
+## Steps
+
+### 1. Extract Branch Name from Story
+
+Read the story/feature description and create a branch name following the pattern:
+- Format: `feature/[story-id]-[short-description]`
+- Example: `feature/AUTH-123-user-login`
+- Use kebab-case for description
+- Keep it short but descriptive
+
+**Branch naming conventions:**
+- `feature/` - New features
+- `bugfix/` - Bug fixes
+- `hotfix/` - Urgent production fixes
+- `refactor/` - Code refactoring
+- `chore/` - Maintenance tasks
+
+### 2. Determine Scope
+
+Ask: Does this story require changes in:
+- [ ] API only → Create branch in `API` only
+- [ ] UI only → Create branch in `UI` only
+- [ ] Both → Create branches in both repos
+
+### 2b. Choose Branch Strategy
+
+**Option A: Standard (in-place branch switching)**
+- Use when: Working on one thing at a time
+- Pros: Simple, no extra directories
+- Cons: Must stash/commit before switching
+
+**Option B: Worktree (parallel development)**
+- Use when: Need to work on multiple things simultaneously
+- Pros: No branch switching, isolated work directories
+- Cons: Uses more disk space
+
+If you need parallel work, skip to **Step 3b** below.
+
+### 3. Create Branches
+
+Run the following commands based on scope:
+
+#### For API Changes
+
+```bash
+cd $CLAUDE_PROJECT_DIR/API
+
+# Ensure you're on main and up to date
+git checkout main
+git pull origin main
+
+# Create and checkout new branch
+git checkout -b feature/[story-id]-[description]
+
+# Push branch to remote
+git push -u origin feature/[story-id]-[description]
+
+# Confirm
+git branch --show-current
+```
+
+#### For UI Changes
+
+```bash
+cd $CLAUDE_PROJECT_DIR/UI
+
+# Ensure you're on main and up to date
+git checkout main
+git pull origin main
+
+# Create and checkout new branch
+git checkout -b feature/[story-id]-[description]
+
+# Push branch to remote
+git push -u origin feature/[story-id]-[description]
+
+# Confirm
+git branch --show-current
+```
+
+### 3b. Create Worktree (Alternative for Parallel Work)
+
+Use this instead of Step 3 if you need to work on multiple stories simultaneously:
+
+```bash
+cd $CLAUDE_PROJECT_DIR
+
+# Create worktree with branches (both API and UI)
+./scripts/git/worktree-manager.sh create [story-id] feat/[story-id]-[description]
+
+# Example: Story 5-2
+./scripts/git/worktree-manager.sh create 5-2 feat/5-2-csv-import
+
+# For API-only work
+./scripts/git/worktree-manager.sh create [story-id] feat/[story-id]-[description] api
+
+# For UI-only work
+./scripts/git/worktree-manager.sh create [story-id] feat/[story-id]-[description] ui
+```
+
+This creates:
+- Worktree at `worktrees/[story-id]/API` and/or `UI`
+- Session file at `.session/wt-[story-id].md`
+- Branches created from develop
+
+**Skip to Step 5b** if using worktrees.
+
+### 4. Document the Work
+
+Edit `.session/{STORY_ID}-session.md`:
+
+```markdown
+# Feature: [Story Title]
+
+**Story ID:** [STORY-123]
+**Repos:** [X] API  [X] UI  [ ] Both
+**Branches:** 
+- API: feature/[story-id]-[description]
+- UI: feature/[story-id]-[description]
+**Date:** [YYYY-MM-DD]
+
+## Goal
+[One sentence - what are you building?]
+
+## Story Description
+[Copy relevant parts of the story]
+
+## Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+## API Changes
+- Files: [list expected files]
+- Endpoints: [list new/modified endpoints]
+- Branch: feature/[story-id]-[description]
+
+## UI Changes
+- Files: [list expected files]
+- Components: [list new/modified components]
+- Branch: feature/[story-id]-[description]
+
+## Technical Notes
+[Any technical considerations, dependencies, etc.]
+
+## Testing Plan
+- [ ] API unit tests
+- [ ] UI component tests
+- [ ] Integration tests
+- [ ] Manual testing
+
+## Done
+- [ ] All acceptance criteria met
+- [ ] Tests pass
+- [ ] Code reviewed
+- [ ] Branches merged
+- [ ] Deployed
+
+## Next Steps
+[What happens after this story is complete?]
+```
+
+### 6. Verify Setup
+
+Check that everything is ready:
+
+```bash
+# Check API branch
+cd $CLAUDE_PROJECT_DIR/API
+git branch --show-current
+# Should show: feature/[story-id]-[description]
+
+# Check UI branch
+cd $CLAUDE_PROJECT_DIR/UI
+git branch --show-current
+# Should show: feature/[story-id]-[description]
+
+# Check Pennyfarthing session exists
+cd $CLAUDE_PROJECT_DIR
+ls -la .session/{STORY_ID}-session.md
+# Should exist
+```
+
+### 5b. Document Worktree Work (if using worktrees)
+
+The worktree manager already created a session file. Edit `.session/wt-[story-id].md` with the same content as Step 5.
+
+### 7. Start Development
+
+You're now ready to start work:
+
+**Standard (in-place branches):**
+```bash
+# Work in API
+cd $CLAUDE_PROJECT_DIR/API
+# You're on feature branch, AI loads session + API context
+
+# Work in UI
+cd $CLAUDE_PROJECT_DIR/UI
+# You're on feature branch, AI loads session + UI context
+```
+
+**Worktree (parallel work):**
+```bash
+# Work in API worktree
+cd $CLAUDE_PROJECT_DIR/worktrees/[story-id]/API
+
+# Work in UI worktree
+cd $CLAUDE_PROJECT_DIR/worktrees/[story-id]/UI
+
+# Get port configuration for dev servers
+eval $(./scripts/git/worktree-manager.sh ports [story-id])
+echo "API: $API_PORT, UI: $UI_PORT"
+```
+
+## Example: Complete Workflow
+
+### Story: "Add User Authentication"
+
+```bash
+# 1. Create API branch
+cd $CLAUDE_PROJECT_DIR/API
+git checkout main && git pull
+git checkout -b feature/AUTH-123-user-authentication
+git push -u origin feature/AUTH-123-user-authentication
+
+# 2. Create UI branch
+cd ../UI
+git checkout main && git pull
+git checkout -b feature/AUTH-123-user-authentication
+git push -u origin feature/AUTH-123-user-authentication
+
+# 3. Edit session file
+# Update .session/{STORY_ID}-session.md with story details
+
+# 5. Start working
+cd API
+# Implement auth endpoints
+
+cd ../UI
+# Implement login UI
+```
+
+## Tips
+
+### Branch Naming Best Practices
+
+- **Be consistent** - Use same branch name in both repos for related work
+- **Include story ID** - Makes it easy to track back to requirements
+- **Keep it short** - But descriptive enough to understand at a glance
+- **Use prefixes** - feature/, bugfix/, etc. for clarity
+
+### When to Create Branches
+
+- **Both repos affected** - Create matching branches in both
+- **Single repo** - Only create branch where needed
+- **Uncertain** - Start with both, delete unused later
+
+### Branch Cleanup
+
+After merging:
+```bash
+# Delete local branch
+git branch -d feature/[story-id]-[description]
+
+# Delete remote branch
+git push origin --delete feature/[story-id]-[description]
+```
+
+## Troubleshooting
+
+### Already have uncommitted changes?
+
+```bash
+# Stash changes
+git stash
+
+# Create branch
+git checkout -b feature/[story-id]-[description]
+
+# Apply stashed changes
+git stash pop
+```
+
+### Wrong branch name?
+
+```bash
+# Rename local branch
+git branch -m old-name new-name
+
+# Delete old remote branch
+git push origin --delete old-name
+
+# Push new branch
+git push -u origin new-name
+```
+
+### Forgot to pull main first?
+
+```bash
+# Fetch latest
+git fetch origin
+
+# Rebase your branch on latest main
+git rebase origin/main
+```
+
+## Integration with Pennyfarthing
+
+This workflow integrates with the solo dev Pennyfarthing structure:
+
+1. **Branches** - Git manages code isolation
+2. **Session** - Pennyfarthing tracks work progress
+3. **Context** - Repo context files guide AI
+4. **Archive** - When done, archive session and delete branches
+
+**Workflow:**
+```
+Story → Branches → Pennyfarthing Session → Development → Merge → Archive
+```
+
+## Quick Reference
+
+```bash
+# Create API branch
+cd API && git checkout main && git pull && \
+git checkout -b feature/STORY-ID-description && \
+git push -u origin feature/STORY-ID-description
+
+# Create UI branch
+cd ../UI && git checkout main && git pull && \
+git checkout -b feature/STORY-ID-description && \
+git push -u origin feature/STORY-ID-description
+
+# Edit session
+# Update .session/{STORY_ID}-session.md
+
+# Start work
+cd API  # or UI
+```
+
+---
+
+**You're ready to start development with coordinated branches and Pennyfarthing tracking!**

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

@@ -0,0 +1,29 @@
+---
+description: Create a new custom persona theme
+---
+
+# Create Theme
+
+Create a new custom theme, optionally based on an existing theme.
+
+## Arguments
+
+- `<name>` - Name for the new theme (lowercase, hyphens allowed)
+
+## Options
+
+- `--base <theme>` - Base theme to copy from (default: minimalist)
+- `--user` - Create as user-level theme (available across all projects)
+
+## Instructions
+
+1. If no theme name provided, ask the user what they want to call their theme.
+
+2. Create the theme:
+   ```bash
+   pennyfarthing theme create <name> [--base <theme>] [--user]
+   ```
+
+3. Guide the user on next steps:
+   - Edit the theme file to customize agents
+   - Run `/set-theme <name>` to activate

package/pennyfarthing-dist/commands/dev.md

@@ -0,0 +1,9 @@
+---
+description: Developer - Feature implementation and coding
+---
+
+```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 "dev"
+```

package/pennyfarthing-dist/commands/devops.md

@@ -0,0 +1,9 @@
+---
+description: DevOps Engineer - Infrastructure and deployment automation
+---
+
+```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 "devops"
+```

package/pennyfarthing-dist/commands/fix-blocker.md

@@ -0,0 +1,22 @@
+---
+description: Quick alias for /patch - fix blocking issue during story work
+---
+
+# Fix Blocker
+
+<purpose>
+Alias for `/patch`. Use when a blocking issue prevents story progress.
+</purpose>
+
+<on-invoke>
+Invoke the patch command:
+
+```
+/patch
+```
+</on-invoke>
+
+<related>
+- `/patch` - Full patch mode documentation
+- `/chore` - Quick commits without tracking
+</related>

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

@@ -0,0 +1,57 @@
+---
+description: Clean up git repos by organizing changes into proper commits/branches by initiative
+workflow: git-cleanup
+---
+
+# Git Cleanup Command
+
+Organize uncommitted changes into proper commits and branches across **all configured repos**.
+
+## Quick Start
+
+Run `/git-cleanup` to start the stepped workflow.
+
+## Multi-Repo Support
+
+This workflow handles multiple repos defined in `.claude/project/pennyfarthing-settings.yaml`.
+
+**CRITICAL:** Always use the multi-repo status script, not plain `git status`:
+
+```bash
+.pennyfarthing/scripts/git/git-status-all.sh
+```
+
+For operations in a specific repo, use `git -C {repo_path}`:
+
+```bash
+git -C pennyfarthing status --short
+git -C pennyfarthing diff
+```
+
+## Workflow Steps
+
+| Step | Name | Purpose |
+|------|------|---------|
+| 1 | Analyze | Gather status from ALL repos |
+| 2 | Categorize | Group changes by initiative (may span repos) |
+| 3 | Execute | Create branches, commit, merge in each repo |
+| 4 | Verify | Confirm clean state across all repos |
+| 5 | Complete | Push and summary |
+
+## Critical Rules
+
+- **NEVER** commit directly to develop (use branches)
+- **NEVER** force push
+- **ALWAYS** use `git -C {repo_path}` for subrepo operations
+- **ALWAYS** check ALL repos, not just the orchestrator
+
+## Commit Types
+
+| Prefix | Use For |
+|--------|---------|
+| `feat:` | New features |
+| `fix:` | Bug fixes |
+| `chore:` | Maintenance |
+| `docs:` | Documentation |
+| `refactor:` | Code improvement |
+| `test:` | Test changes |