@pennyfarthing/core 7.9.3 → 8.0.0

package/pennyfarthing-dist/commands/brainstorming.md

@@ -0,0 +1,91 @@
+---
+description: Structured problem-solving brainstorm session
+---
+
+# Brainstorm - Structured Problem-Solving Session
+
+You are facilitating a **structured brainstorming session** to solve a specific problem or explore a specific question.
+
+## Format
+
+Unlike party-mode (free-form), brainstorm follows a structured approach:
+
+### Phase 1: Problem Definition (2 min)
+- What exactly are we trying to solve?
+- What constraints exist?
+- What does success look like?
+
+### Phase 2: Divergent Thinking (5 min)
+Generate as many ideas as possible without judgment:
+- Quantity over quality
+- Build on others' ideas
+- No criticism yet
+- Wild ideas welcome
+
+### Phase 3: Clustering (2 min)
+Group similar ideas into themes:
+- Technical solutions
+- Process changes
+- UX improvements
+- Quick wins vs. long-term
+
+### Phase 4: Evaluation (3 min)
+Score top ideas on:
+- **Impact**: How much does this solve the problem? (1-5)
+- **Effort**: How hard to implement? (1-5, lower is easier)
+- **Risk**: What could go wrong? (1-5, lower is safer)
+
+### Phase 5: Selection (1 min)
+Choose 1-3 ideas to pursue based on:
+- Highest impact/effort ratio
+- Acceptable risk level
+- Alignment with current priorities
+
+## Output Template
+
+```markdown
+## Brainstorm: [Problem Statement]
+
+### Problem Definition
+- **Problem**: [Clear statement]
+- **Constraints**: [List]
+- **Success criteria**: [Measurable outcomes]
+
+### Ideas Generated
+| # | Idea | Theme | Impact | Effort | Risk |
+|---|------|-------|--------|--------|------|
+| 1 | ... | Technical | 4 | 3 | 2 |
+| 2 | ... | Process | 3 | 1 | 1 |
+...
+
+### Selected for Action
+1. **[Idea]** - [Why selected]
+   - Next step: [Concrete action]
+   - Owner: [Who/which agent]
+
+### Parked Ideas
+- [Ideas worth revisiting later]
+
+### Discarded
+- [Ideas and why they don't fit]
+```
+
+## Usage
+
+```
+/brainstorm How can we reduce ticket resolution time?
+/brainstorm What's the best way to implement real-time updates?
+/brainstorm Why are users abandoning the onboarding flow?
+```
+
+## Tips
+
+- Time-box each phase
+- Write everything down
+- Don't let one voice dominate
+- "Yes, and..." not "No, but..."
+- The obvious idea might be the right one
+
+---
+
+**WHAT PROBLEM SHALL WE SOLVE?**

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