@pennyfarthing/core 7.9.1 → 7.9.3

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

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

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

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

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

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

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