@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/commands/sprint-planning.md

@@ -0,0 +1,109 @@
+---
+description: Facilitate sprint planning session
+---
+
+# Sprint Planning - Plan the Next Sprint
+
+You are facilitating a **sprint planning session** to define what work will be done in the upcoming sprint.
+
+## Pre-Planning: Load Context
+
+```bash
+# Current sprint status
+cat sprint/current-sprint.yaml
+
+# Full backlog
+cat sprint/backlog.yaml
+
+# Recent velocity (completed points)
+grep -A5 "summary:" sprint/current-sprint.yaml
+```
+
+## Planning Phases
+
+### Phase 1: Review & Reflect (5 min)
+- How did last sprint go? (Quick check, not full retro)
+- Any carryover items?
+- Blockers or dependencies resolved?
+
+### Phase 2: Capacity Planning (3 min)
+- Team availability this sprint
+- Known interruptions (holidays, meetings, on-call)
+- Realistic velocity target
+
+### Phase 3: Backlog Grooming (10 min)
+- Review top items in backlog
+- Clarify acceptance criteria
+- Estimate if not already estimated
+- Identify dependencies
+
+### Phase 4: Sprint Goal (2 min)
+- What's the ONE thing this sprint must achieve?
+- How will we know we succeeded?
+
+### Phase 5: Commitment (5 min)
+- Select stories that fit capacity
+- Balance: features vs bugs vs tech debt
+- Ensure no single epic dominates
+- Leave buffer for unknowns (~20%)
+
+## Output Template
+
+```markdown
+## Sprint [N+1] Planning
+**Dates**: [Start] - [End]
+**Sprint Goal**: [One sentence goal]
+
+### Capacity
+- Velocity target: [X] points
+- Buffer (20%): [Y] points reserved
+- Usable capacity: [Z] points
+
+### Committed Stories
+
+#### [Epic Name] ([X] pts)
+| Story | Points | Priority | Assignee |
+|-------|--------|----------|----------|
+| [Story] | 3 | P0 | Dev |
+| [Story] | 5 | P1 | Dev |
+
+#### [Another Epic] ([Y] pts)
+...
+
+#### Bugs ([Z] pts)
+| Bug | Points | Priority |
+|-----|--------|----------|
+| BUG-XXX | 2 | P0 |
+
+### Not This Sprint (Explicitly Deferred)
+- [Story] - Why deferred
+- [Story] - Blocked by X
+
+### Risks
+- [Risk and mitigation]
+
+### Definition of Done
+- [ ] All acceptance criteria met
+- [ ] Tests passing
+- [ ] Code reviewed
+- [ ] Documentation updated
+- [ ] No P0/P1 bugs introduced
+```
+
+## After Planning
+
+1. Update `sprint/current-sprint.yaml` with committed stories
+2. Move selected items from `backlog` to `in_sprint`
+3. Create feature branches if needed
+4. Notify team of sprint start
+
+## Usage
+
+```
+/sprint-planning              # Plan next sprint
+/sprint-planning sprint-3     # Plan specific sprint
+```
+
+---
+
+**READY TO PLAN. WHAT'S OUR GOAL FOR THE NEXT SPRINT?**

package/pennyfarthing-dist/commands/sprint.md

@@ -0,0 +1,133 @@
+---
+description: Sprint status, backlog, and story management - check status, find work, archive completed stories
+args: "[status|backlog|work|archive|new|future|promote] [args...]"
+---
+
+# Sprint Management
+
+<purpose>
+Manage sprint workflow: check status, view backlog, start work, archive completed stories, and promote future epics. This is the primary interface for sprint operations.
+</purpose>
+
+<critical>
+Never manually edit `sprint/current-sprint.yaml`. Always use the provided scripts.
+</critical>
+
+## Commands
+
+### `/sprint` or `/sprint status [filter]`
+
+Show current sprint status with story counts and points.
+
+```bash
+.pennyfarthing/scripts/core/run.sh sprint/sprint-status.sh [filter]
+```
+
+| Filter | Description |
+|--------|-------------|
+| (none) | All stories |
+| `todo` | Backlog only |
+| `in-progress` | Work in progress |
+| `done` | Completed stories |
+
+### `/sprint backlog`
+
+Show available stories ready for work, grouped by epic.
+
+```bash
+.pennyfarthing/scripts/core/run.sh sprint/available-stories.sh
+```
+
+### `/sprint work [story-id|epic-id|next]`
+
+Start work on a story. Primary entry point for development.
+
+| Argument | Behavior |
+|----------|----------|
+| (none) | Interactive selection from backlog |
+| `MSSCI-XXXXX` | Start specific story |
+| `epic-XX` | Start first available story in epic |
+| `next` | Auto-select highest priority story |
+
+```bash
+# Check if story is available
+.pennyfarthing/scripts/core/run.sh sprint/check-story.sh <story-id>
+
+# Then load SM to begin work
+```
+
+<workflow>
+When starting work, this command:
+1. Validates story availability
+2. Loads SM agent
+3. SM creates context and claims Jira
+4. Hands off to TEA (tdd) or Dev (trivial)
+</workflow>
+
+### `/sprint archive <story-id> [pr-number] [--apply]`
+
+Archive a completed story.
+
+```bash
+.pennyfarthing/scripts/core/run.sh sprint/archive-story.sh <story-id> [pr-number] [--apply]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--apply` | Also remove from current-sprint.yaml |
+
+### `/sprint new <yyww> <jira-id> <start> <end> "<goal>"`
+
+Initialize a new sprint.
+
+```bash
+.pennyfarthing/scripts/core/run.sh sprint/new-sprint.sh 2605 277 2026-02-03 2026-02-16 "Sprint goal"
+```
+
+### `/sprint future [--epic EPIC_ID]`
+
+Show future work available for promotion.
+
+```bash
+.pennyfarthing/scripts/core/run.sh sprint/list-future.sh [--epic epic-XX]
+```
+
+### `/sprint promote <epic-id>`
+
+Move an epic from future.yaml to current sprint.
+
+```bash
+.pennyfarthing/scripts/core/run.sh sprint/promote-epic.sh epic-XX
+```
+
+## Quick Reference
+
+| Command | Action |
+|---------|--------|
+| `/sprint` | Show sprint status |
+| `/sprint status todo` | Show backlog |
+| `/sprint backlog` | Available stories |
+| `/sprint work` | Interactive start |
+| `/sprint work next` | Start highest priority |
+| `/sprint work MSSCI-XXX` | Start specific story |
+| `/sprint archive MSSCI-XXX` | Archive completed |
+| `/sprint future` | Show future work |
+| `/sprint promote epic-XX` | Promote to sprint |
+
+## Aliases
+
+- `/new-work` is an alias for `/sprint work`
+
+## Related
+
+| Skill | Purpose |
+|-------|---------|
+| `/jira` | Jira operations (create, sync, claim) |
+| `/story` | Story creation, sizing, finish |
+| `/sm` | Scrum Master agent for coordination |
+
+<reference>
+- **Skill:** `.claude/skills/sprint/skill.md`
+- **Scripts:** `.pennyfarthing/scripts/sprint/`
+- **Data:** `sprint/current-sprint.yaml`
+</reference>

package/pennyfarthing-dist/commands/standalone.md

@@ -0,0 +1,194 @@
+---
+description: Wrap current changes into a standalone Jira story, branch, PR, and merge
+---
+
+# Standalone Story
+
+Quickly wrap dirty changes into a tracked Jira story without the full sprint/workflow ceremony. Creates a Jira ticket, feature branch, commits, pushes, creates PR, and merges.
+
+<purpose>
+Fast path for shipping completed work that deserves tracking but doesn't need story setup upfront.
+</purpose>
+
+<when-to-use>
+- You've done exploratory work that turned into something shippable
+- A bug fix or feature emerged during other work
+- Process improvements that should be tracked
+- Any change worth a Jira ticket but not a full sprint story
+</when-to-use>
+
+<usage>
+```bash
+# Interactive: prompts for title and description
+/standalone
+
+# With title
+/standalone "Add drift detection script"
+
+# With title and points
+/standalone "Add drift detection script" 2
+```
+</usage>
+
+<workflow>
+1. Verify dirty files exist (abort if clean)
+2. Show changes and confirm with user
+3. Create Jira story (prompts for title/description if not provided)
+4. Add story to current sprint and mark Done
+5. Create feature branch: `feat/MSSCI-XXXXX-{slug}`
+6. Stage and commit changes
+7. Push branch
+8. Create PR with summary
+9. Merge PR (squash) and delete branch
+10. Return to develop
+</workflow>
+
+## Execution
+
+### Step 1: Pre-Flight
+
+```bash
+# Abort if clean
+git diff --quiet && git diff --cached --quiet && {
+  echo "ERROR: No changes to commit."
+  exit 1
+}
+
+echo "=== Changes to Commit ==="
+git status --short
+git diff --stat
+```
+
+### Step 2: Gather Story Info
+
+If title not provided, prompt:
+- **Title:** Short summary (becomes Jira summary and commit message)
+- **Description:** What was done (becomes Jira description and PR body)
+- **Points:** Story points (default: 2)
+
+```bash
+# Defaults
+TITLE="${1:-}"
+POINTS="${2:-2}"
+
+if [ -z "$TITLE" ]; then
+  # Prompt user for title
+  echo "Enter story title:"
+  read TITLE
+fi
+
+# Generate description from changed files
+CHANGED_FILES=$(git status --porcelain | awk '{print $2}')
+DESCRIPTION="## Changes
+$(git diff --stat)
+
+## Files
+$(echo "$CHANGED_FILES" | head -20)"
+```
+
+### Step 3: Create Jira Story
+
+```bash
+# Create Jira story
+JIRA_OUTPUT=$(jira issue create \
+  --project MSSCI \
+  --type Story \
+  --summary "$TITLE" \
+  --body "$DESCRIPTION" \
+  --label pennyfarthing \
+  --custom story-points="$POINTS" \
+  --no-input 2>&1)
+
+JIRA_KEY=$(echo "$JIRA_OUTPUT" | grep -oE 'MSSCI-[0-9]+' | head -1)
+
+if [ -z "$JIRA_KEY" ]; then
+  echo "ERROR: Failed to create Jira story"
+  echo "$JIRA_OUTPUT"
+  exit 1
+fi
+
+echo "Created: $JIRA_KEY"
+
+# Add to sprint and mark done
+jira sprint add 276 "$JIRA_KEY"
+jira issue move "$JIRA_KEY" "Done"
+```
+
+### Step 4: Create Branch and Commit
+
+```bash
+# Generate slug from title
+SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-30)
+
+# Stash, update develop, create branch
+git stash push -m "standalone-wip-$(date +%s)"
+git checkout develop && git pull origin develop
+BRANCH="feat/${JIRA_KEY}-${SLUG}"
+git checkout -b "$BRANCH"
+git stash pop
+
+# Stage and commit
+git add .
+git commit -m "feat: ${TITLE} (${JIRA_KEY})
+
+${DESCRIPTION}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+```
+
+### Step 5: Push and Create PR
+
+```bash
+git push -u origin "$BRANCH"
+
+gh pr create \
+  --title "feat: ${TITLE} (${JIRA_KEY})" \
+  --body "## Summary
+${DESCRIPTION}
+
+## Jira
+[${JIRA_KEY}](https://1898andco.atlassian.net/browse/${JIRA_KEY})
+
+## Test plan
+- [x] Changes verified locally
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)"
+```
+
+### Step 6: Merge and Cleanup
+
+```bash
+# Get PR number and merge
+PR_URL=$(gh pr view --json url -q '.url')
+gh pr merge --squash --delete-branch
+
+# Return to develop
+git checkout develop
+git pull origin develop
+
+echo "✅ Done: $JIRA_KEY merged"
+echo "   Jira: https://1898andco.atlassian.net/browse/$JIRA_KEY"
+echo "   PR: $PR_URL"
+```
+
+## Safety
+
+- **NEVER commit directly to develop**
+- **Never force push**
+- **Never commit secrets** (.env, credentials)
+- **Abort if working directory is clean**
+- **Confirm changes before proceeding**
+
+## Comparison
+
+| Command | Tracking | Branch | PR | Use For |
+|---------|----------|--------|-----|---------|
+| `/chore` | None | chore/* | No | Quick maintenance |
+| `/standalone` | Jira | feat/* | Yes | Trackable features |
+| `/sprint work` | Jira + Sprint | feat/* | Yes | Planned sprint work |
+
+<related>
+- `/chore` - Quick commits without Jira tracking
+- `/sprint work` - Full sprint workflow with story setup
+- `/git-cleanup` - Organize multiple changes into groups
+</related>

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

@@ -0,0 +1,168 @@
+---
+description: Start an epic - move to current sprint and generate tech context
+---
+
+# Start Epic Workflow
+
+**This command prepares an epic for development by moving it to the current sprint and generating technical context.**
+
+## What This Does
+
+1. **Validates** the epic exists in backlog or current sprint
+2. **Moves** the epic to current sprint if not already there
+3. **Runs** the SM agent's `epic-tech-context` task to generate technical specifications
+
+## Prerequisites
+
+```bash
+cd $CLAUDE_PROJECT_DIR
+
+# Verify sprint files exist
+if [ ! -f "sprint/current-sprint.yaml" ] || [ ! -f "sprint/backlog.yaml" ]; then
+    echo "ERROR: Sprint files not found"
+    exit 1
+fi
+
+echo "Sprint files found - ready to start epic"
+```
+
+## Usage
+
+Provide the epic ID when invoking this command:
+- `epic-5` - Pennyfarthing epic (format: `epic-N`)
+
+## Workflow Steps
+
+### Step 0: Clean Previous Work Artifacts
+
+Before starting a new epic, clean up stale artifacts from previous work:
+
+```bash
+cd $CLAUDE_PROJECT_DIR
+
+# Run conservative cleanup (7+ day old artifacts)
+$CLAUDE_PROJECT_DIR/scripts/run.sh misc/session-cleanup.sh --dry-run
+
+# If dry-run looks good, run actual cleanup
+$CLAUDE_PROJECT_DIR/scripts/run.sh misc/session-cleanup.sh
+
+# Archive epic contexts for completed epics
+$CLAUDE_PROJECT_DIR/scripts/run.sh misc/session-cleanup.sh --aggressive
+```
+
+This ensures a clean slate before starting new epic work and archives contexts from completed epics.
+
+### Step 1: Identify Epic
+
+Ask the user for the epic ID if not provided:
+> "Which epic would you like to start? (e.g., epic-5, sim-epic-10)"
+
+### Step 2: Check Epic Location
+
+```bash
+cd $CLAUDE_PROJECT_DIR
+
+# Check if epic is in current sprint
+if grep -q "^$EPIC_ID:" sprint/current-sprint.yaml; then
+    echo "Epic $EPIC_ID is already in current sprint"
+    EPIC_LOCATION="current"
+elif grep -q "^$EPIC_ID:" sprint/backlog.yaml; then
+    echo "Epic $EPIC_ID found in backlog - will move to current sprint"
+    EPIC_LOCATION="backlog"
+else
+    echo "ERROR: Epic $EPIC_ID not found in sprint files"
+    exit 1
+fi
+```
+
+### Step 3: Move Epic to Current Sprint (if needed)
+
+If the epic is in backlog:
+
+1. **Extract** the epic block from `sprint/backlog.yaml`
+2. **Add** the epic to `sprint/current-sprint.yaml` under the active work section
+3. **Update** the epic status from `backlog` or `planned` to `in-progress`
+4. **Remove** the epic from `sprint/backlog.yaml`
+
+**Format for current-sprint.yaml:**
+```yaml
+  # ===========================================================================
+  # EPIC [N]: [Name]
+  # ===========================================================================
+  - id: MSSCI-XXXXX
+    type: epic
+    title: "Epic: [Name]"
+    points: [total_pts]
+    completed_points: 0
+    priority: P1
+    status: in_progress
+    stories:
+      # Stories added during tech context generation
+      - id: MSSCI-XXXXX
+        title: "[Story title]"
+        points: [N]
+        priority: P2
+        status: backlog
+        repos: [cyclist|pennyfarthing|both]
+        workflow: [tdd|trivial|agent-docs]
+        acceptance_criteria:
+          - [AC 1]
+          - [AC 2]
+```
+
+### Step 4: Generate Epic Tech Context
+
+Invoke the SM agent with the `epic-tech-context` task:
+
+**Run:** `/sm` with task: `epic-tech-context` for epic `$EPIC_ID`
+
+The SM agent will:
+1. Load the epic details from current sprint
+2. Analyze the codebase for relevant files
+3. Generate technical context including:
+   - Current state analysis
+   - Technical approach
+   - File modifications needed
+   - API/UI changes
+   - Database changes
+   - Testing strategy
+   - Story breakdown with acceptance criteria
+4. Save context to `.session/context-epic-$EPIC_ID.md`
+
+### Step 5: Confirm Ready
+
+After tech context is generated:
+
+```
+✅ Epic $EPIC_ID is ready for development
+
+Next steps:
+1. Review the tech context: cat .session/context-epic-$EPIC_ID.md
+2. Start first story: /new-work
+3. SM will select from this epic's stories
+```
+
+## Example
+
+```bash
+# User invokes: /start-epic epic-5
+
+# Output:
+# → Checking epic-5 location...
+# → Epic epic-5 found in backlog
+# → Moving epic-5 to current sprint...
+# → Updating status to in-progress...
+# → Invoking SM for epic-tech-context...
+# → [SM generates technical context]
+# → ✅ Epic epic-5 is ready for development
+```
+
+## Notes
+
+- This command does NOT start a story - use `/new-work` for that
+- The epic tech context provides the foundation for story-level work
+- Stories within the epic will be worked via the normal TDD flow
+
+---
+
+**Flow:** `/start-epic` → SM (epic-tech-context) → `/new-work` → TDD cycle