npm - @pennyfarthing/core - Versions diffs - 9.2.0 → 9.3.0 - Mend

@pennyfarthing/core 9.2.0 → 9.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1039) hide show

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

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

@@ -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/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 DELETED Viewed

@@ -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 DELETED Viewed

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

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

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

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