@pennyfarthing/core 11.0.0 → 11.1.0

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

@@ -0,0 +1,40 @@
+---
+description: Detect and run CI locally
+args: "[run] [--detect-only] [--dry-run]"
+---
+
+# CI Operations
+
+<purpose>
+Run CI locally by detecting the project's CI system and executing appropriate commands.
+</purpose>
+
+## Commands
+
+### `/pf-ci run`
+
+Run CI locally (auto-detects CI system).
+
+```bash
+# Run CI
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/run-ci.sh
+
+# Detect only
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/run-ci.sh --detect-only
+
+# Dry run
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/run-ci.sh --dry-run
+```
+
+## CI System Detection
+
+| Priority | System | Detection | Command |
+|----------|--------|-----------|---------|
+| 1 | Justfile | `just --list` shows `ci` recipe | `just ci` |
+| 2 | GitHub Actions | `.github/workflows/*.yml` | `act` |
+| 3 | GitLab CI | `.gitlab-ci.yml` | `gitlab-runner exec` |
+| 4 | npm fallback | `package.json` | `npm run build && npm test && npm run lint` |
+
+## Related
+
+- `/pf-check` — Run quality gates before handoff

package/pennyfarthing-dist/commands/pf-close-epic.md

@@ -1,32 +1,14 @@
 ---
-description: Close an epic - verify completion, update status, and archive context
+deprecated: true
+redirect: pf-epic
+description: "DEPRECATED: Use /pf-epic close instead."
 ---
 
-# Close Epic
+# /close-epic - DEPRECATED
 
-<purpose>
-Closes an epic after all stories are done. Updates sprint YAML, transitions Jira, archives context.
-Counterpart to `/start-epic`. Idempotent — safe to run multiple times.
-</purpose>
+Epic commands have been consolidated into `/pf-epic`. Use:
 
-<usage>
-```bash
-/close-epic 79        # Close epic 79
-/close-epic epic-79   # Also accepts epic-N format
-```
-</usage>
-
-<workflow>
-1. Parse epic ID (strip `epic-` prefix if present). Ask if not provided.
-2. Read epic shard `sprint/epic-{JIRA_KEY}.yaml`, verify all stories `status: done`. Warn if incomplete.
-3. Update epic: `status: done`, `completed_points: {sum of story points}`
-4. Recalculate sprint summary totals in `sprint/current-sprint.yaml`
-5. If epic has `jira:` key → `pf jira move {JIRA_KEY} "Done"`
-6. If `sprint/context/context-epic-{N}.md` exists → move to `sprint/archive/`
-7. Commit and push sprint changes
-</workflow>
-
-<related>
-- `/start-epic` — Start an epic (move to current sprint, generate context)
-- `/pf-sprint status` — View sprint progress
-</related>
+| Old Command | New Command |
+|-------------|-------------|
+| `/start-epic <id>` | `/pf-epic start <id>` |
+| `/close-epic <id>` | `/pf-epic close <id>` |

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

@@ -1,218 +1,14 @@
 ---
-description: Resume work from a saved checkpoint after context circuit breaker
+deprecated: true
+redirect: pf-session
+description: "DEPRECATED: Use /pf-session continue instead."
 ---
 
-# Continue Session
+# /continue-session - DEPRECATED
 
-<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>
+Session commands have been consolidated into `/pf-session`. Use:
 
-<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>
+| Old Command | New Command |
+|-------------|-------------|
+| `/new-work` | `/pf-session new` |
+| `/continue-session` | `/pf-session continue` |

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

@@ -1,358 +1,16 @@
 ---
-description: Create feature branches in both repos from a story
+deprecated: true
+redirect: pf-git
+description: "DEPRECATED: Use /pf-git branches instead."
 ---
 
-# Create Branches from Story Workflow
+# /create-branches-from-story - DEPRECATED
 
-This workflow helps you create coordinated feature branches in the subrepos (`API`, `UI`) from a story or feature request.
+Git commands have been consolidated into `/pf-git`. Use:
 
-## 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!**
+| Old Command | New Command |
+|-------------|-------------|
+| `/repo-status` | `/pf-git status` |
+| `/git-cleanup` | `/pf-git cleanup` |
+| `/create-branches-from-story` | `/pf-git branches` |
+| `/release` | `/pf-git release` |

package/pennyfarthing-dist/commands/pf-docs.md

@@ -0,0 +1,28 @@
+---
+description: Domain documentation management
+args: "[update]"
+---
+
+# Documentation Operations
+
+<purpose>
+Manage domain documentation files. Currently supports updating CLAUDE-*.md domain documentation files to reflect the current state of the codebase.
+</purpose>
+
+## Commands
+
+### `/pf-docs update`
+
+Update CLAUDE-*.md domain documentation files based on current codebase.
+
+Scans the relevant files for each domain and updates documentation with:
+- Service files and their main functions
+- Handler files and their endpoints
+- Model files and their structs
+- Worker files (if applicable)
+- Test files
+
+## Related
+
+- `/pf-help` — Context-aware help
+- `/tech-writer` — Technical Writer agent