@pennyfarthing/core 10.0.0 → 10.0.2

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,218 @@
+---
+description: Quick commit for small changes without full git-cleanup ceremony
+---
+
+# Quick Chore Commit
+
+Quickly commit dirty changes without the full `/git-cleanup` ceremony. Checks **all repos** (orchestrator + subrepos), creates branches, commits, merges to develop, and pushes.
+
+<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.
+
+**CRITICAL: Always check ALL repos, not just the orchestrator.** Most changes are in subrepos (e.g., `pennyfarthing/`). Use `git -C {repo_path}` for subrepo operations.
+
+1. Check ALL repos for dirty files (orchestrator + subrepos from `repos.yaml`)
+2. Abort if all repos are clean
+3. Determine variant (chore/doc/ux) from first arg
+4. For EACH dirty repo, independently:
+   a. Create branch from current HEAD: `{variant}/{timestamp}`
+   b. Stage and commit all changes
+   c. Fetch origin and rebase onto latest develop
+   d. Switch to develop, merge the branch
+   e. Push develop
+   f. Delete local branch
+</workflow>
+
+## Execution
+
+### Step 1: Multi-Repo Pre-Flight
+
+**ALWAYS check all repos.** Read `repos.yaml` for repo paths.
+
+```bash
+# Check ALL repos for dirty changes
+# Orchestrator root (.)
+git status --short
+
+# Subrepos (e.g., pennyfarthing/)
+git -C pennyfarthing status --short 2>/dev/null
+
+# Or use the multi-repo status script:
+.pennyfarthing/scripts/git/git-status-all.sh --brief
+```
+
+Collect which repos have changes. If ALL repos are clean, abort with "No changes to commit."
+
+**Common case:** Only the subrepo (`pennyfarthing/`) has changes. The orchestrator is clean. This is normal — framework development happens in the subrepo.
+
+### 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: For Each Dirty Repo — Generate Message, Branch, Commit, Merge, Push
+
+Repeat steps 3a–3d for each repo that has dirty changes. Use `git -C {repo_path}` for subrepo operations, or `cd` into the subrepo temporarily.
+
+#### Step 3a: Generate Message (if user didn't provide one)
+
+Generate a message based on the changed files **in that specific repo**.
+
+```bash
+if [ -z "$MESSAGE" ]; then
+  CHANGED_FILES=$(git -C {repo_path} 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
+```
+
+**For subrepos:** Also review the diff to generate a meaningful message. Prefer descriptive messages over generic ones (e.g., "migrate TTY panel to WebSocket" over "minor updates to 3 files").
+
+#### Step 3b: Branch and Commit
+
+**IMPORTANT: Do NOT use git stash.** Stash + pull + pop can silently revert changes when upstream modifies the same files.
+
+```bash
+# For subrepos, cd into the repo first (or use git -C throughout)
+cd {repo_path}
+
+# 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
+```
+
+#### Step 3c: Return to orchestrator root
+
+```bash
+cd {orchestrator_root}
+```
+
+### Step 4: Verify
+
+After all repos are processed:
+```bash
+.pennyfarthing/scripts/git/git-status-all.sh --brief
+```
+
+All repos should show clean.
+
+## Safety
+
+- **NEVER commit directly to develop** (use branches)
+- **Never force push**
+- **Never commit secrets** (.env, credentials)
+- **Abort if ALL repos are clean**
+- **ALWAYS use `git -C {repo_path}` for subrepo operations**
+
+## 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
+- `/repo-status` - Check status across all repos
+</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