@pennyfarthing/core 7.9.3 → 7.9.5

package/pennyfarthing-dist/commands/check.md

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

@@ -0,0 +1,178 @@
+---
+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.**
+
+1. Verify dirty files exist (abort if clean)
+2. Determine variant (chore/doc/ux) from first arg
+3. Create branch from develop: `{variant}/{timestamp}`
+4. Stage all changes
+5. Generate or use provided commit message
+6. Commit with conventional format
+7. Merge to develop locally
+8. Push develop
+9. 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
+
+```bash
+# Stash current changes
+git stash push -m "${BRANCH_TYPE}-wip-$(date +%s)"
+
+# Update develop and create branch
+git checkout develop && git pull origin develop
+BRANCH="${BRANCH_TYPE}/$(date +%Y%m%d-%H%M%S)"
+git checkout -b "$BRANCH"
+
+# Restore changes
+git stash pop
+
+# Stage and commit
+git add .
+git commit -m "${PREFIX}: ${MESSAGE}
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# Merge and push
+git checkout 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

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

@@ -0,0 +1,184 @@
+---
+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: 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 2: Parse and Present Options
+
+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 3: Restore Checkpoint
+
+Source the checkpoint utilities and restore:
+
+```bash
+# Source checkpoint utilities
+source "${PROJECT_ROOT:-.}/.pennyfarthing/scripts/utils/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 4: 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 5: 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 |
+|---------------|---------|---------|
+| `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. Agent saves checkpoint: `checkpoint_save "phase:X-Y" "dev"`
+4. User starts new Claude session
+5. User runs `/continue-session`
+6. Checkpoint restored, agent resumes
+</integration>
+
+<reference>
+- **Checkpoint API:** `scripts/utils/checkpoint.sh`
+- **Circuit Breaker:** `scripts/hooks/context-circuit-breaker.sh`
+- **Related:** `/work`, `/new-work`
+- **Session Files:** `.session/{story-id}-session.md`
+</reference>