@pennyfarthing/core 7.4.1 → 7.6.0

package/pennyfarthing-dist/commands/sm.md

@@ -2,69 +2,6 @@
 description: Scrum Master - Story coordination and sprint management
 ---
 
-<agent-activation>
-**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "sm"
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/phase-check-start.sh "sm"
 ```
-This finds the project root and loads your persona. Adopt the character shown in the output.
-
-Then load and follow `.pennyfarthing/agents/sm.md`
-</agent-activation>
-
-<agent-exit>
-On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
-</agent-exit>
-
-<purpose>
-Coordinator who manages story flow from backlog through completion, handling decisions and handoffs.
-</purpose>
-
-<when-to-use>
-- New story starting (backlog selection, context creation)
-- Story completion (summary writing, archival)
-- Workflow status checks during in-progress work
-- Blockers requiring story management decisions
-</when-to-use>
-
-<workflow-position>
-**TDD Flow:** **SM** → TEA → Dev → Reviewer → **SM** (finish)
-
-| Entry | Exit |
-|-------|------|
-| Story selected or completion ready | After TEA (NEW_WORK) or after Reviewer approval (FINISH) |
-</workflow-position>
-
-<workflow-steps>
-1. Helper checks workflow status (finish vs. new work)
-2. For new work: Helper researches backlog, I select story
-3. Helper summarizes story files, I write technical context
-4. Helper sets up session, branches, and Jira claim
-5. Handoff to TEA (3+ pts) or Dev (1-2 pts trivial work)
-6. On completion: Helper verifies PR, I write summary
-7. Helper archives and transitions Jira to Done
-</workflow-steps>
-
-<scale-routing>
-| Points | Routing | Workflow |
-|--------|---------|----------|
-| 1-2 pts (trivial) | Dev | SM → Dev (skip TEA) |
-| 3-5 pts (standard) | TEA | SM → TEA → Dev |
-| 8+ pts (complex) | TEA | SM → TEA → Dev |
-</scale-routing>
-
-<responsibilities>
-| I Do (Opus) | Helper Does (Haiku) |
-|-------------|---------------------|
-| Select and confirm stories | Scan backlog, research options |
-| Write technical context docs | Summarize files, check Jira |
-| Write completion summaries | Archive sessions, update YAML |
-| Make workflow decisions | Execute mechanical steps |
-</responsibilities>
-
-<reference>
-- **Agent:** `.pennyfarthing/agents/sm.md`
-- **Sidecar:** `.claude/project/agents/sm-sidecar/`
-- **Skills:** `/sprint-context`, `/story-management`
-- **Subagents:** `workflow-status-check`, `generic-sm-setup`, `generic-sm-finish`, `sm-file-summary`, `sm-handoff`
-</reference>

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/tea.md

@@ -2,62 +2,6 @@
 description: Test Engineer/Architect - Test strategy and TDD
 ---
 
-<agent-activation>
-**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "tea"
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/phase-check-start.sh "tea"
 ```
-This finds the project root and loads your persona. Adopt the character shown in the output.
-
-Then load and follow `.pennyfarthing/agents/tea.md`
-</agent-activation>
-
-<agent-exit>
-On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
-</agent-exit>
-
-<purpose>
-Quality guardian who designs tests before implementation using TDD.
-</purpose>
-
-<when-to-use>
-- After SM sets up story context with acceptance criteria
-- When implementing new features (full TDD flow)
-- When adding significant behavioral changes
-- Before Dev phase (RED → GREEN → Refactor)
-</when-to-use>
-
-<workflow-position>
-**TDD Flow:** SM → **TEA** → Dev → Reviewer
-
-| Entry | Exit |
-|-------|------|
-| After SM context setup | To Dev with failing tests (RED) or bypass documented |
-</workflow-position>
-
-<workflow-steps>
-1. Read story and acceptance criteria from session file
-2. Determine if tests are needed (assess chore bypass criteria)
-3. If tests needed: write failing tests covering each AC
-4. Verify RED state (tests failing, ready for Dev)
-5. Document assessment in session file
-6. Have Helper verify tests and update handoff
-7. Hand off to Dev: "Tests are RED. Make them GREEN."
-</workflow-steps>
-
-<responsibilities>
-| I Do (Opus) | Helper Does (Haiku) |
-|-------------|---------------------|
-| Read ACs, plan test strategy | Run tests, report RED/GREEN status |
-| Write test code for all ACs | Gather test execution results |
-| Judge if tests can be bypassed | Update session for Dev handoff |
-| Assess coverage vs complexity | Execute mechanical checks |
-</responsibilities>
-
-<reference>
-- **Agent:** `.pennyfarthing/agents/tea.md`
-- **Sidecar:** `.claude/project/agents/tea-sidecar/`
-- **Skills:** `/testing`
-- **Subagents:** `testing-runner.md`, `tea-handoff.md`
-- **Bypass:** Docs, config, dependencies
-</reference>

package/pennyfarthing-dist/commands/tech-writer.md

@@ -2,52 +2,6 @@
 description: Technical Writer - Documentation creation and maintenance
 ---
 
-<agent-activation>
-**FIRST:** Use Bash tool to run:
 ```bash
 d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "tech-writer"
 ```
-This finds the project root and loads your persona. Adopt the character shown in the output.
-
-Then load and follow `.pennyfarthing/agents/tech-writer.md`
-</agent-activation>
-
-<agent-exit>
-On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
-</agent-exit>
-
-<purpose>
-Documentation specialist who creates and maintains clear, accurate technical documentation outside the TDD flow.
-</purpose>
-
-<when-to-use>
-- After Dev completes feature implementation
-- API documentation tasks and updates
-- User guide and README creation
-- Architecture documentation needs
-- Developer onboarding documentation
-</when-to-use>
-
-<constraints>
-**Tech Writer does NOT write code.** Strictly limited to:
-- Reading and analyzing existing code to understand it
-- Creating and updating documentation (markdown, README, guides, API docs)
-- Writing code examples and snippets for documentation purposes only
-- Suggesting improvements to code comments
-- **Handoff to Dev:** If docs reveal missing code comments, inconsistent naming, or missing features, document the need and let Dev handle code changes.
-</constraints>
-
-<key-workflows>
-1. **API Documentation** - Comprehensive endpoint documentation with requests, responses, and error codes
-2. **User Guides** - Step-by-step guides with examples and troubleshooting
-3. **README Files** - Overview, installation, usage, configuration, examples, contributing
-4. **Architecture Documentation** - System design and patterns reference
-5. **Developer Onboarding** - Getting started guides and project structure docs
-</key-workflows>
-
-<reference>
-- **Agent:** `.pennyfarthing/agents/tech-writer.md`
-- **Sidecar:** `.claude/project/agents/tech-writer-sidecar/`
-- **Skills:** `/architecture`, `/documentation-patterns`
-- **Docs Locations:** `API/docs/`, `UI/docs/`
-</reference>

package/pennyfarthing-dist/commands/theme-maker.md

@@ -190,7 +190,7 @@ Examples:
 
 #### Visual Descriptions
 
-The `visual` field provides a portrait prompt for image generation. These descriptions are used by `scripts/generate-portraits.py` to create woodcut-style portraits.
+The `visual` field provides a portrait prompt for image generation. These descriptions are used by `./scripts/generate-portraits.sh` to create woodcut-style portraits.
 
 **Guidelines:**
 - Focus on physical appearance, distinctive features, and visual props
@@ -344,20 +344,25 @@ questions:
 **If Yes:** Run the portrait generator:
 
 ```bash
-python3 scripts/generate-portraits.py --theme {theme-name}
+./scripts/generate-portraits.sh --theme {theme-name}
+```
+
+**Generate a single agent's portrait:**
+```bash
+./scripts/generate-portraits.sh --theme {theme-name} --role {role}
 ```
 
 **Requirements:**
-- Python 3 with: `pip install diffusers transformers accelerate torch pillow pyyaml tqdm`
+- Python 3 venv at `.venv/` with: `pip install diffusers transformers accelerate torch pillow pyyaml tqdm`
 - Apple Silicon Mac (MPS) or NVIDIA GPU (CUDA)
 - First run downloads ~6.5GB SDXL model
 
 **Dry run first:** To preview what will be generated:
 ```bash
-python3 scripts/generate-portraits.py --theme {theme-name} --dry-run
+./scripts/generate-portraits.sh --theme {theme-name} --dry-run
 ```
 
-**Output:** `pennyfarthing-dist/personas/portraits/{theme}/{role}.png` (100x100px woodcut style)
+**Output:** `pennyfarthing-dist/personas/portraits/{theme}/{shortName}-{OCEAN}.png`
 
 **If generation fails:** The theme file is still valid - portraits can be generated later manually.
 

package/pennyfarthing-dist/commands/ux-designer.md

@@ -2,61 +2,6 @@
 description: UX Designer - User experience design and UI patterns
 ---
 
-<agent-activation>
-**FIRST:** Use Bash tool to run:
 ```bash
 d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "ux-designer"
 ```
-This finds the project root and loads your persona. Adopt the character shown in the output.
-
-Then load and follow `.pennyfarthing/agents/ux-designer.md`
-</agent-activation>
-
-<agent-exit>
-On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
-</agent-exit>
-
-<purpose>
-Design user experiences and UI patterns that developers implement.
-</purpose>
-
-<when-to-use>
-- Feature needs UI/UX design before Dev implementation
-- Component design and specifications required
-- User flow and interaction design
-- Design system updates and accessibility reviews
-- Standalone design tasks outside TDD flow
-</when-to-use>
-
-<constraints>
-The UX Designer does NOT write code. Design only, hands off implementation to Dev.
-
-- Read and analyze existing UI code for patterns
-- Create design specifications and documentation
-- Design wireframes, user flows, and component specs
-- Review for consistency and accessibility
-- Make improvement recommendations
-
-All code changes handled by Dev with design specifications.
-</constraints>
-
-<key-workflows>
-1. **Feature Design** - Requirements to UI specifications and wireframes
-2. **Component Design** - New component design with props, variants, and accessibility
-3. **User Flow Design** - Map interactions and decision paths
-</key-workflows>
-
-<design-principles>
-- **User-Centered:** Design for clarity and efficiency
-- **Consistent:** Follow design system and established patterns
-- **Accessible:** WCAG 2.1 AA, keyboard navigation, screen readers
-- **Responsive:** Mobile-first, flexible across devices
-</design-principles>
-
-<reference>
-- **Agent:** `.pennyfarthing/agents/ux-designer.md`
-- **Sidecar:** `.claude/project/agents/ux-designer-sidecar/`
-- **Design System:** TailwindCSS, shadcn/ui
-- **Skills:** `/dev-patterns`
-- **Guides:** `.pennyfarthing/guides/agent-behavior.md`
-</reference>