@pennyfarthing/core 7.9.2 → 7.9.5

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/run.sh git/worktree-manager.sh create [story-id] feat/[story-id]-[description]
+
+# Example: Story 5-2
+./scripts/run.sh git/worktree-manager.sh create 5-2 feat/5-2-csv-import
+
+# For API-only work
+./scripts/run.sh git/worktree-manager.sh create [story-id] feat/[story-id]-[description] api
+
+# For UI-only work
+./scripts/run.sh 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/run.sh 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,7 @@
+---
+description: Developer - Feature implementation and coding
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/phase-check-start.sh "dev"
+```

package/pennyfarthing-dist/commands/devops.md

@@ -0,0 +1,7 @@
+---
+description: DevOps Engineer - Infrastructure and deployment automation
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "devops"
+```

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

@@ -0,0 +1,51 @@
+---
+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.
+
+## Quick Start
+
+Run `/git-cleanup` to start the stepped workflow.
+
+## Workflow Steps
+
+| Step | Name | Purpose |
+|------|------|---------|
+| 1 | Analyze | Check stash, gather git status |
+| 2 | Categorize | Group changes by initiative |
+| 3 | Execute | Create branches, commit, merge |
+| 4 | Verify | Confirm clean state, push |
+| 5 | Complete | Verify stash empty, summary |
+
+## Critical Rules
+
+- **NEVER** commit directly to develop (use branches)
+- **NEVER** force push
+- **ALWAYS** check stash before starting (`git stash list`)
+- **ALWAYS** clear stash after completing (with user permission)
+- **ALWAYS** check stash before assuming work is lost
+
+## Stash Safety
+
+Work is rarely lost - it's usually in stash:
+
+```bash
+git stash list              # Check for saved work
+git stash show -p stash@{0} # See contents
+git stash pop               # Restore it
+```
+
+## Commit Types
+
+| Prefix | Use For |
+|--------|---------|
+| `feat:` | New features |
+| `fix:` | Bug fixes |
+| `chore:` | Maintenance |
+| `docs:` | Documentation |
+| `refactor:` | Code improvement |
+| `test:` | Test changes |

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

@@ -0,0 +1,141 @@
+---
+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>
+
+<drift-detection>
+
+## Agent Behavior Drift Detection
+
+Check if agents are following expected behavioral patterns:
+
+```bash
+# Run drift detection
+.pennyfarthing/scripts/core/run.sh health/drift-detection.sh
+
+# Verbose mode (see individual files)
+.pennyfarthing/scripts/core/run.sh health/drift-detection.sh --verbose
+```
+
+The script analyzes archived session files for:
+
+| Agent | Checks For |
+|-------|------------|
+| **Reviewer** | Substantive comments (not just approvals) |
+| **Dev** | Test evidence when declaring GREEN |
+| **SM** | Structured handoff sections with target agent |
+| **TEA** | Test file references before Dev handoff |
+
+**Healthy rates:** Under 10% drift is considered normal.
+
+**When drift is high:**
+- Review agent behavior files for clarity
+- Add explicit gates/checklists
+- Consider making critical behaviors automatic via scripts
+
+</drift-detection>
+
+<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.
+- **Drift Detection:** `.pennyfarthing/scripts/health/drift-detection.sh`
+</reference>