@pennyfarthing/core 9.1.2 → 9.3.0

package/pennyfarthing-dist/commands/check.md

@@ -1,156 +0,0 @@
----
-description: Run quality gates (lint, type check, tests) before handoff
----
-
-<purpose>
-Run all quality gates before handing off to Reviewer. Ensures code meets quality standards.
-</purpose>
-
-<when-to-use>
-- Before creating a PR
-- Before handoff to Reviewer
-- After implementing a feature
-- To verify codebase health
-</when-to-use>
-
-<execution>
-
-## Running Quality Checks
-
-Use the check.sh script:
-
-```bash
-# Run all checks (lint, typecheck, tests)
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh
-
-# Run checks in a specific repo subdirectory
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo api
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo ui
-
-# Run only tests (skip lint and typecheck)
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --tests-only
-
-# Run tests with a filter pattern
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --filter "TestUserLogin"
-
-# Run filtered tests in a specific repo
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --repo api --filter "TestUserLogin"
-
-# Run only filtered tests (no lint/typecheck)
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --tests-only --filter "TestUserLogin"
-
-# Skip individual checks
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --no-lint
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --no-typecheck
-
-# Skip all checks (emergencies only)
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/check.sh --skip-check
-```
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--skip-check` | Skip all checks (emergency bypass) |
-| `--tests-only` | Run only tests, skip lint and typecheck |
-| `--filter PATTERN` | Filter tests by pattern |
-| `--repo REPO` | Run checks in a specific repo subdirectory |
-| `--no-lint` | Skip lint check |
-| `--no-typecheck` | Skip type check |
-
-## What Gets Checked
-
-The script automatically detects project type and runs appropriate checks:
-
-### For Node/TypeScript Projects:
-| Check | Command | Condition |
-|-------|---------|-----------|
-| Lint | `just lint` or `npm run lint` | If configured |
-| Type Check | `just typecheck` or `tsc --noEmit` | If tsconfig.json exists |
-| Tests | `just test` or `npm test` | If configured |
-
-### For Go Projects:
-| Check | Command | Condition |
-|-------|---------|-----------|
-| Lint | `just lint` or `golangci-lint run` | If available |
-| Tests | `just test` or `go test ./...` | Always |
-
-### Justfile Preference
-If both justfile and npm scripts exist, justfile recipes take priority.
-
-</execution>
-
-<output-format>
-
-```
-Quality Gate Check
-==================
-Project: /path/to/project
-
-Lint
-========================================
-  [PASS] Lint (npm run lint)
-
-Type Check
-========================================
-  [PASS] Type Check (tsc --noEmit)
-
-Tests
-========================================
-  [PASS] Tests (npm test)
-
-Summary
-========================================
-
-Checks run:    3
-Checks passed: 3
-Checks failed: 0
-
-PASSED - All checks passed
-```
-
-Exit codes:
-- `0` - All checks passed (or --skip-check used)
-- `1` - One or more checks failed
-
-</output-format>
-
-<skip-check>
-
-## Emergency Skip
-
-Use `--skip-check` only in emergencies:
-
-```bash
-./scripts/check.sh --skip-check
-```
-
-This will:
-- Skip all quality checks
-- Show a warning message
-- Return exit code 0
-
-**Use sparingly.** Skipped checks should pass before PR merge.
-
-</skip-check>
-
-<integration>
-
-## dev-handoff Integration
-
-The dev-handoff subagent runs `/check` automatically before handoff to Reviewer:
-
-1. Dev completes implementation
-2. dev-handoff runs `check.sh`
-3. If checks fail: handoff is blocked
-4. If checks pass: proceed to Reviewer
-
-To bypass (emergencies): pass `--skip-check` to dev-handoff.
-
-</integration>
-
-<reference>
-- **Script:** `pennyfarthing-dist/scripts/check.sh`
-- **Called by:** dev-handoff subagent
-- **Blocks:** Handoff to Reviewer on failure
-</reference>

package/pennyfarthing-dist/commands/chore.md

@@ -1,179 +0,0 @@
----
-description: Quick commit for small changes without full git-cleanup ceremony
----
-
-# Quick Chore Commit
-
-Quickly commit dirty changes without the full `/git-cleanup` ceremony. Creates a branch, commits, merges to develop, and pushes in one command.
-
-<purpose>
-Fast path for committing small changes that don't warrant story tracking.
-</purpose>
-
-<usage>
-```bash
-# Default: chore commit (auto-generate message)
-/chore
-
-# Chore with custom message
-/chore "update sprint tracking"
-
-# Variants for different commit types
-/chore doc                       # docs: prefix, docs/* branch
-/chore doc "update README"       # docs: with custom message
-/chore ux                        # style: prefix, ux/* branch
-/chore ux "adjust button spacing"
-```
-</usage>
-
-<variants>
-| Command | Branch | Commit Prefix | Use For |
-|---------|--------|---------------|---------|
-| `/chore` | `chore/*` | `chore:` | Maintenance, config, scripts |
-| `/chore doc` | `docs/*` | `docs:` | Documentation, README, guides |
-| `/chore ux` | `ux/*` | `style:` | UI tweaks, CSS, styling |
-</variants>
-
-<workflow>
-**CRITICAL: Never commit directly to develop. Branch protection hooks will reject direct commits.**
-
-**CRITICAL: Never use git stash.** The stash/pull/pop pattern can silently revert changes when upstream modifies the same files during the pull.
-
-1. Verify dirty files exist (abort if clean)
-2. Determine variant (chore/doc/ux) from first arg
-3. Create branch from current HEAD (keeps dirty changes): `{variant}/{timestamp}`
-4. Stage and commit all changes
-5. Fetch origin and rebase onto latest develop
-6. Switch to develop, merge the branch
-7. Push develop
-8. Delete local branch
-</workflow>
-
-## Execution
-
-### Step 1: Pre-Flight
-
-```bash
-# Abort if clean
-if git diff --quiet && git diff --cached --quiet; then
-  echo "ERROR: No changes to commit."
-  exit 1
-fi
-
-echo "=== Changes to Commit ==="
-git status --short
-```
-
-### Step 2: Parse Arguments
-
-```bash
-# Defaults
-VARIANT="chore"
-PREFIX="chore"
-BRANCH_TYPE="chore"
-MESSAGE=""
-
-# Check first arg
-case "$1" in
-  doc|docs)
-    VARIANT="docs"
-    PREFIX="docs"
-    BRANCH_TYPE="docs"
-    shift
-    ;;
-  ux|style)
-    VARIANT="ux"
-    PREFIX="style"
-    BRANCH_TYPE="ux"
-    shift
-    ;;
-esac
-
-# Remaining args are the message
-MESSAGE="$*"
-```
-
-### Step 3: Generate Message (if needed)
-
-```bash
-if [ -z "$MESSAGE" ]; then
-  CHANGED_FILES=$(git status --porcelain | awk '{print $2}')
-
-  case "$VARIANT" in
-    docs)
-      if echo "$CHANGED_FILES" | grep -qi "readme"; then
-        MESSAGE="update README"
-      elif echo "$CHANGED_FILES" | grep -qi "changelog"; then
-        MESSAGE="update changelog"
-      else
-        MESSAGE="update documentation"
-      fi
-      ;;
-    ux)
-      if echo "$CHANGED_FILES" | grep -qE "\.css|\.scss"; then
-        MESSAGE="update styles"
-      else
-        MESSAGE="update styling"
-      fi
-      ;;
-    chore)
-      if echo "$CHANGED_FILES" | grep -q "sprint/"; then
-        MESSAGE="update sprint tracking"
-      elif echo "$CHANGED_FILES" | grep -q "\.claude/"; then
-        MESSAGE="update pennyfarthing config"
-      elif echo "$CHANGED_FILES" | grep -q "scripts/"; then
-        MESSAGE="update scripts"
-      else
-        FILE_COUNT=$(echo "$CHANGED_FILES" | wc -l | tr -d ' ')
-        MESSAGE="minor updates to ${FILE_COUNT} files"
-      fi
-      ;;
-  esac
-fi
-```
-
-### Step 4: Branch and Commit
-
-**IMPORTANT: Do NOT use git stash.** Stash + pull + pop can silently revert changes when upstream modifies the same files.
-
-```bash
-# Create branch from current HEAD (preserves dirty changes)
-BRANCH="${BRANCH_TYPE}/$(date +%Y%m%d-%H%M%S)"
-git checkout -b "$BRANCH"
-
-# Stage and commit on the branch
-git add .
-git commit -m "${PREFIX}: ${MESSAGE}
-
-Co-Authored-By: Claude <noreply@anthropic.com>"
-
-# Now fetch and rebase onto latest develop
-git fetch origin develop
-git rebase origin/develop
-
-# Switch to develop, fast-forward merge, and push
-git checkout develop
-git pull origin develop
-git merge "$BRANCH"
-git branch -d "$BRANCH"
-git push origin develop
-```
-
-## Safety
-
-- **NEVER commit directly to develop**
-- **Never force push**
-- **Never commit secrets** (.env, credentials)
-- **Abort if working directory is clean**
-
-## When to Use
-
-| Use /chore | Use /git-cleanup |
-|------------|------------------|
-| Single logical change | Multiple unrelated changes |
-| Quick fix or tweak | Need to organize into groups |
-| One type of change | Mixed types requiring separation |
-
-<related>
-- `/git-cleanup` - Full ceremony for organizing multiple changes
-</related>

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

@@ -1,139 +0,0 @@
----
-description: Close an epic - verify completion, update status, and archive context
----
-
-# Close Epic Workflow
-
-**This command closes an epic by verifying all stories are done, updating status, and optionally archiving context.**
-
-## What This Does
-
-1. **Verifies** all stories in the epic are status: done
-2. **Updates** epic status to `done` and completed_points
-3. **Updates** sprint summary totals
-4. **Optionally** transitions Jira epic to Done
-5. **Optionally** archives the epic context file
-
-## Prerequisites
-
-- Epic must exist in current sprint
-- All stories should be done (will warn if not)
-
-## Usage
-
-Provide the epic ID when invoking this command:
-- `/close-epic 9` - Close epic 9
-- `/close-epic epic-9` - Also accepts epic-N format
-
-## Workflow Steps
-
-### Step 1: Identify Epic
-
-If no epic ID provided, ask:
-> "Which epic would you like to close? (e.g., 9 or epic-9)"
-
-Parse the epic ID (strip "epic-" prefix if present).
-
-### Step 2: Verify Epic Exists
-
-Read `sprint/current-sprint.yaml` and find the epic block:
-- `id: epic-{N}`
-
-If not found, error: "Epic not found in current sprint"
-
-### Step 3: Check Story Completion
-
-For each story in the epic:
-1. Check `status` field
-2. Count done vs not-done
-
-**If all done:** Proceed to close
-**If some not done:** Warn user with list of incomplete stories, ask to confirm
-
-### Step 4: Update Epic Status
-
-Update the epic in `sprint/current-sprint.yaml`:
-```yaml
-status: done
-completed_points: {total of all story points}
-```
-
-### Step 5: Update Sprint Summary
-
-Recalculate and update the summary section:
-- `completed_points`: Sum of all done story points across all epics
-- `remaining_points`: total_points - completed_points
-- Update notes to reflect epic completion
-
-### Step 6: Jira Transition (Optional)
-
-If epic has `jira_key`, use `/jira move` skill:
-```bash
-# Check if Jira CLI available
-if command -v jira &> /dev/null; then
-    echo "Transition Jira epic to Done? (y/n)"
-    # If yes, use /jira move skill:
-    # jira issue move $JIRA_KEY "Done" --project MSSCI
-fi
-```
-
-**Note:** Always use `/jira` skill commands - see `.claude/skills/jira/skill.md` for syntax.
-
-### Step 7: Archive Context (Optional)
-
-If `.session/context-epic-{N}.md` exists:
-```bash
-# Ask user
-echo "Archive epic context file? (y/n)"
-# If yes: mv .session/context-epic-{N}.md sprint/archive/
-```
-
-### Step 8: Confirm Closure
-
-```
-Epic {N} closed successfully
-
-Summary:
-- Stories: {count} done
-- Points: {points} completed
-- Jira: {transitioned/skipped/no-key}
-- Context: {archived/kept/not-found}
-
-Sprint progress: {completed}/{total} points ({percentage}%)
-```
-
-## Example
-
-```bash
-# User invokes: /close-epic 9
-
-# Output:
-# Checking epic-9...
-# Found: Skill Discovery & Documentation Hub
-# Stories: 5/5 done (13 points)
-#
-# Updating epic status to done...
-# Updating sprint summary (31/45 points)...
-#
-# Jira key found: MSSCI-11512
-# Transition to Done? (y/n): y
-# Transitioning MSSCI-11512 to Done...
-#
-# Context file found: .session/context-epic-9.md
-# Archive to sprint/archive/? (y/n): n
-# Keeping context file in place.
-#
-# Epic 9 closed successfully!
-# Sprint progress: 31/45 points (69%)
-```
-
-## Notes
-
-- This is the counterpart to `/start-epic`
-- Safe to run multiple times (idempotent)
-- Does NOT delete any data, only updates status
-- Context archival is optional and reversible
-
----
-
-**Flow:** TDD cycle complete all stories `/close-epic` update sprint

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

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