@pennyfarthing/core 10.4.0 → 11.0.0

package/pennyfarthing-dist/skills/pf-sprint/usage.md

@@ -0,0 +1,293 @@
+# Sprint CLI — Detailed Usage
+
+## Top-Level Commands
+
+### `pf sprint status [FILTER]`
+
+| Arg | Required | Type | Description |
+|-----|----------|------|-------------|
+| `FILTER` | No | Choice | `backlog`, `todo`, `in-progress`, `review`, `done` |
+
+Returns sprint metadata, stories grouped by epic, points breakdown.
+
+### `pf sprint backlog`
+
+No arguments. Shows stories with `backlog`, `ready`, or `planning` status grouped by epic.
+
+### `pf sprint work [STORY_ID] [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `STORY_ID` | No | Story ID, or `next` for highest priority |
+| `--dry-run` | No | Preview without making changes |
+
+Without argument: shows backlog. With `next`: auto-selects highest priority.
+
+### `pf sprint archive <STORY_ID> [PR_NUMBER] [--apply] [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `STORY_ID` | Yes | Story ID to archive |
+| `PR_NUMBER` | No | PR number if merged via PR |
+| `--apply` | No | Also remove from current-sprint.yaml |
+| `--dry-run` | No | Preview without making changes |
+
+### `pf sprint new <YYWW> <JIRA_ID> <START> <END> <GOAL> [--dry-run]`
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `YYWW` | Yes | Sprint identifier (e.g., `2607`) |
+| `JIRA_ID` | Yes | Jira sprint ID number |
+| `START` | Yes | Start date `YYYY-MM-DD` |
+| `END` | Yes | End date `YYYY-MM-DD` |
+| `GOAL` | Yes | Sprint goal (quoted string) |
+| `--dry-run` | No | Preview without making changes |
+
+Creates `sprint/current-sprint.yaml` and `sprint/archive/sprint-{YYWW}-completed.yaml`.
+
+### `pf sprint future [EPIC_ID]`
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `EPIC_ID` | No | Show detailed stories for a specific epic |
+
+Without arg: initiative summary. With arg: full epic detail with stories.
+
+### `pf sprint info`
+
+No arguments. Returns sprint header fields plus computed totals as JSON.
+
+### `pf sprint metrics [--json]`
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output in JSON format |
+
+Shows points, stories, timeline, and velocity tracking.
+
+### `pf sprint check <ID>`
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `ID` | Yes | Story ID, epic ID, or `next` |
+
+Returns JSON with `type` (`story`, `epic`, `next`, `not_found`), availability, and details.
+
+### `pf sprint validate [SUBCOMMAND] [--fix] [--strict]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| Subcommand | No | `sprint`, `schema`, `agent`, `workflow` (omit for all) |
+| `--fix` | No | Auto-fix format issues |
+| `--strict` | No | Treat warnings as errors |
+
+---
+
+## Story Commands
+
+### `pf sprint story show <STORY_ID> [--json]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `STORY_ID` | Yes | Story ID (e.g., `MSSCI-12664` or `67-1`) |
+| `--json` | No | Output as JSON |
+
+### `pf sprint story add <EPIC_ID> <TITLE> <POINTS> [options]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | Yes | Parent epic (e.g., `76`) |
+| `TITLE` | Yes | Story title (quoted) |
+| `POINTS` | Yes | Story points (integer) |
+| `--type` | No | `feature` (default), `bug`, `chore`, `refactor` |
+| `--priority` | No | `p0`, `p1` (default), `p2`, `p3` (case-insensitive) |
+| `--workflow` | No | `tdd` (default), `trivial`, `bdd` |
+| `--jira` | No | Jira issue key |
+| `--initiative` | No | Add as standalone story to initiative slug instead |
+| `--repos` | No | Repository scope (default: `pennyfarthing`) |
+| `--sprint-file` | No | Path to sprint YAML file |
+| `--dry-run` | No | Preview without making changes |
+
+When using `--initiative`, positional args shift: `<TITLE> <POINTS>` (no epic ID).
+
+### `pf sprint story update <STORY_ID> [options]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `STORY_ID` | Yes | Story ID (e.g., `76-4`) |
+| `--status` | No | `backlog`, `ready`, `in_progress`, `done`, `canceled` |
+| `--points` | No | New points value |
+| `--priority` | No | New priority |
+| `--assigned-to` | No | Assignee email |
+| `--workflow` | No | New workflow type |
+| `--completed` | No | Completed date (ISO format) |
+| `--started` | No | Started date (ISO format) |
+| `--sprint-file` | No | Path to sprint YAML file |
+| `--dry-run` | No | Preview without making changes |
+
+Auto-sets `completed` date when status is `done`. Auto-sets `started` and `assigned_to` when status is `in_progress`.
+
+### `pf sprint story field <STORY_ID> <FIELD>`
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `STORY_ID` | Yes | Story ID (e.g., `79-1` or `MSSCI-12345`) |
+| `FIELD` | Yes | Field name: `workflow`, `status`, `jira`, `points`, `title`, `repos`, `priority` |
+
+Returns field value or `null`. Defaults: `workflow=tdd`, `status=backlog`, `repos=pennyfarthing`.
+
+### `pf sprint story size [POINTS]`
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `POINTS` | No | Specific point value |
+
+### `pf sprint story template [TYPE]`
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `TYPE` | No | `feature`, `bug`, `refactor`, `chore` |
+
+### `pf sprint story finish <STORY_ID> [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `STORY_ID` | Yes | Story ID (e.g., `83-2`) |
+| `--dry-run` | No | Show steps without executing |
+
+Requires: session file exists, PR approved, reviewer phase complete.
+
+### `pf sprint story claim <STORY_ID> [--claim/--unclaim] [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `STORY_ID` | Yes | Story ID / Jira key |
+| `--claim/--unclaim` | No | Claim (default) or unclaim |
+| `--dry-run` | No | Preview without making changes |
+
+---
+
+## Epic Commands
+
+### `pf sprint epic show <EPIC_ID> [--json]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | Yes | Epic ID (e.g., `epic-42`, `42`, or `MSSCI-14298`) |
+| `--json` | No | Output as JSON |
+
+Searches both current sprint and future initiative shards.
+
+### `pf sprint epic add <EPIC_ID> <TITLE> [options]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | Yes | Epic ID (e.g., `epic-85`) |
+| `TITLE` | Yes | Epic title |
+| `--priority` | No | `p0`, `p1` (default), `p2`, `p3` (case-insensitive) |
+| `--status` | No | `backlog` (default), `ready`, `in_progress` |
+| `--repos` | No | Repository scope (default: `pennyfarthing`) |
+| `--jira` | No | Jira epic key |
+| `--description` / `-d` | No | Epic description |
+| `--sprint-file` | No | Path to sprint YAML file |
+| `--dry-run` | No | Preview without making changes |
+
+### `pf sprint epic update <EPIC_ID> [options]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | Yes | Epic ID (e.g., `103`, `epic-103`, or `MSSCI-14951`) |
+| `--status` | No | `backlog`, `canceled`, `done`, `in_progress` |
+| `--priority` | No | New priority (e.g., `P0`, `P1`) |
+| `--sprint-file` | No | Path to sprint YAML file |
+| `--dry-run` | No | Preview without making changes |
+
+### `pf sprint epic promote <EPIC_ID> [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | Yes | Epic ID (e.g., `epic-41` or `41`) |
+| `--dry-run` | No | Preview without making changes |
+
+Moves epic from initiative shard to current-sprint.yaml. Detects ID collisions. Validates before writing.
+
+### `pf sprint epic archive [EPIC_ID] [--dry-run] [--jira]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | No | Specific epic (omit to scan all completed) |
+| `--dry-run` | No | Preview without making changes |
+| `--jira` | No | Also update Jira epic status to Done |
+
+### `pf sprint epic cancel <EPIC_ID> [--jira] [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | Yes | Epic ID (e.g., `epic-42` or `MSSCI-14298`) |
+| `--jira` | No | Also cancel in Jira |
+| `--dry-run` | No | Preview without making changes |
+
+### `pf sprint epic import <FILE> [INITIATIVE] [--marker TAG] [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `FILE` | Yes | Path to BMAD epics-and-stories markdown |
+| `INITIATIVE` | No | Initiative name (extracted from file if omitted) |
+| `--marker` | No | Marker tag for stories (default: `imported`) |
+| `--dry-run` | No | Preview without making changes |
+
+### `pf sprint epic remove <EPIC_ID> [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | Yes | Epic ID (e.g., `epic-41`) |
+| `--dry-run` | No | Preview without making changes |
+
+### `pf sprint epic field <EPIC_ID> <FIELD>`
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `EPIC_ID` | Yes | Epic ID (e.g., `epic-35` or `35`) |
+| `FIELD` | Yes | Field name: `jira`, `title`, `description`, `status` |
+
+---
+
+## Initiative Commands
+
+### `pf sprint initiative show <NAME> [--json]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | Yes | Initiative slug (e.g., `benchmark-reliability`) |
+| `--json` | No | Output as JSON |
+
+### `pf sprint initiative cancel <NAME> [--jira] [--dry-run]`
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | Yes | Initiative slug |
+| `--jira` | No | Also cancel epics in Jira |
+| `--dry-run` | No | Preview without making changes |
+
+---
+
+## File Locations
+
+| File | Purpose |
+|------|---------|
+| `sprint/current-sprint.yaml` | Active/backlog work |
+| `sprint/archive/sprint-{YYWW}-completed.yaml` | Completed stories |
+| `sprint/initiative-*.yaml` | Future initiative shards |
+| `sprint/epic-*.yaml` | Epic shard files |
+| `sprint/future.yaml` | Future initiative index |
+
+## YAML Constraints
+
+| Field | Valid Values |
+|-------|-------------|
+| Sprint name | `"TO Sprint YYWW"` |
+| Status | `backlog`, `ready`, `in_progress`, `done`, `canceled` |
+| Workflow | `tdd`, `trivial`, `bdd`, `tdd-tandem`, `bdd-tandem`, `agent-docs` |
+| Priority | `P0`, `P1`, `P2`, `P3` |
+
+Note: `tdd-tandem` and `bdd-tandem` are valid workflow values in YAML but the `pf sprint story add --workflow` CLI choice is limited to `tdd`, `trivial`, `bdd`. Set tandem workflows via `pf sprint story update --workflow tdd-tandem`.

package/pennyfarthing-dist/skills/pf-story/skill.md

@@ -0,0 +1,27 @@
+---
+name: story
+description: |
+  DEPRECATED: Use /pf-sprint story instead.
+  Story commands have been consolidated under /pf-sprint.
+args: "[size|template|create|finish] [options]"
+deprecated: true
+redirect: sprint
+---
+
+# /pf-story - DEPRECATED
+
+Story commands have been consolidated into `/pf-sprint`. Use the new commands:
+
+| Old Command | New Command |
+|-------------|-------------|
+| `/story size [points]` | `/pf-sprint story size [points]` |
+| `/story template [type]` | `/pf-sprint story template [type]` |
+| `/story create <epic-id> ...` | `/pf-sprint story add <epic-id> ...` |
+| `/story finish <story-id>` | `/pf-sprint story finish <story-id>` |
+
+## Related Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/pf-sprint` | All sprint, story, and epic operations |
+| `/pf-jira` | Jira operations (create, sync, claim) |

package/pennyfarthing-dist/skills/{systematic-debugging → pf-systematic-debugging}/SKILL.md

@@ -3,7 +3,7 @@ name: systematic-debugging
 description: Systematic debugging approach for isolating and fixing issues. Use when debugging failures, investigating errors, bisecting regressions, or validating fixes.
 ---
 
-# Systematic Debugging Skill
+# /pf-systematic-debugging - Systematic Debugging Skill
 
 <run>systematic-debugging</run>
 
@@ -428,7 +428,7 @@ mcp__playwright__browser_navigate to http://localhost:3000/
 | `browser_console_messages` | Check for JS errors |
 | `browser_network_requests` | Debug API calls |
 
-See: `/workflow interactive-debug` for full workflow.
+See: `/pf-workflow interactive-debug` for full workflow.
 
 ---
 
@@ -436,10 +436,9 @@ See: `/workflow interactive-debug` for full workflow.
 
 | Skill | How It Complements |
 |-------|-------------------|
-| `/testing` | Run tests to verify fixes |
-| `/dev-patterns` | Avoid common pitfalls |
-| `/agentic-patterns` | ReAct pattern for systematic investigation |
-| `/workflow interactive-debug` | UI debugging with Playwright MCP |
+| `/pf-testing` | Run tests to verify fixes |
+| `/pf-agentic-patterns` | ReAct pattern for systematic investigation |
+| `/pf-workflow interactive-debug` | UI debugging with Playwright MCP |
 
 ---
 

package/pennyfarthing-dist/skills/pf-theme/examples.md

@@ -0,0 +1,92 @@
+# Theme — Examples
+
+## Browsing Themes
+
+```bash
+# List all available themes with tiers
+pf theme list
+
+# Show current theme
+pf theme show
+
+# Show specific theme
+pf theme show blade-runner
+
+# Show full details (OCEAN, quirks, catchphrases)
+pf theme show blade-runner --full
+pf theme show fifth-element --full
+```
+
+## Changing Theme
+
+```bash
+# Set theme
+pf theme set blade-runner
+
+# Preview without changing
+pf theme set blade-runner --dry-run
+
+# Refresh agent persona after change
+pf agent start "sm"
+```
+
+## Creating Custom Themes
+
+```bash
+# Create from current theme
+pf theme create my-team
+
+# Create from specific base
+pf theme create my-team --base blade-runner
+
+# Create as user-level (available across projects)
+pf theme create my-team --user
+
+# Create from specific base as user-level
+pf theme create my-team --base fifth-element --user
+
+# Preview
+pf theme create my-team --base blade-runner --dry-run
+```
+
+After creation:
+1. Edit the theme file to customize agents
+2. Run `pf theme set my-team` to activate
+
+## Theme Maker (Interactive)
+
+Use `/theme maker` in Claude Code. The wizard walks through:
+
+1. **Name** — lowercase, hyphens allowed (e.g., `my-universe`)
+2. **Mode** — AI-Driven, Guided, or Manual
+3. **Characters** — 10 agent personas generated
+
+### AI-Driven Mode
+Describe a concept or universe, all 10 personas generated automatically.
+
+### Guided Mode
+Describe a universe, get 3-4 character suggestions per agent, pick your favorites.
+
+### Manual Mode
+Specify character name, style, and quote for each agent. Skip agents for defaults.
+
+### After Creation
+```bash
+# Activate the new theme
+pf theme set my-universe
+
+# Generate portraits (optional, requires GPU)
+./scripts/generate-portraits.sh --theme my-universe
+./scripts/generate-portraits.sh --theme my-universe --dry-run
+./scripts/generate-portraits.sh --theme my-universe --role dev
+```
+
+## Theme Name Rules
+
+- Lowercase letters and numbers only
+- Must start with a letter
+- Hyphens allowed (no underscores or spaces)
+- No conflicts with existing themes
+
+Valid: `blade-runner`, `my-team-2`, `scifi`
+Invalid: `Blade_Runner`, `my team`, `2fast`

package/pennyfarthing-dist/skills/pf-theme/skill.md

@@ -0,0 +1,42 @@
+---
+name: theme
+description: Manage persona themes - list available themes, show current/specific theme details, set active theme, create themes, and run the interactive theme maker wizard.
+args: "[list|show|set|create|maker] [options]"
+---
+
+# /theme - Theme Management
+
+Manage persona themes for agent characters.
+
+## Quick Reference
+
+| Command | CLI | Purpose |
+|---------|-----|---------|
+| `/theme` | `pf theme show` | Show current theme |
+| `/theme list` | `pf theme list` | List all available themes |
+| `/theme show [name]` | `pf theme show [name] [--full]` | Show theme details |
+| `/theme set <name>` | `pf theme set <name> [--dry-run]` | Set active theme |
+| `/theme create <name>` | `pf theme create <name> [--base X] [--user] [--dry-run]` | Create from base theme |
+| `/theme maker` | *(interactive wizard)* | AI-driven theme creation |
+
+### After Setting a Theme
+
+Refresh the current agent persona:
+```bash
+pf agent start "sm"
+```
+Adopt the new character immediately.
+
+### Theme Locations
+
+| Location | Purpose |
+|----------|---------|
+| `pennyfarthing-dist/personas/themes/` | Built-in themes (96+) |
+| `.claude/pennyfarthing/themes/` | Project-level custom themes |
+| `~/.claude/pennyfarthing/themes/` | User-level custom themes |
+| `.pennyfarthing/config.local.yaml` | Active theme selection |
+
+---
+
+**Detailed options and behavior:** [usage.md](usage.md)
+**Practical examples and theme maker guide:** [examples.md](examples.md)

package/pennyfarthing-dist/skills/pf-theme/usage.md

@@ -0,0 +1,149 @@
+# Theme — Detailed Usage
+
+## Commands
+
+### List Themes
+
+```bash
+pf theme list
+```
+
+No arguments. Shows all available themes with:
+- Current theme marked with `*`
+- Tier in brackets: `[S]` elite, `[A]` excellent, `[B]` strong, `[C]` good, `[D]` below average, `[U]` unbenchmarked
+
+Copy output into response text — Bash tool output may be collapsed in the UI.
+
+### Show Theme
+
+```bash
+pf theme show [NAME] [--full]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | No | Theme name. Defaults to current theme. |
+| `--full` | No | Include OCEAN scores, quirks, catchphrases, helpers |
+
+Copy output into response text.
+
+### Set Theme
+
+```bash
+pf theme set <NAME> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | Yes | Theme name to activate |
+| `--dry-run` | No | Preview without making changes |
+
+Updates `.pennyfarthing/config.local.yaml` with theme name and character map.
+
+After setting, refresh agent persona:
+```bash
+pf agent start "sm"
+```
+Adopt the new character immediately.
+
+### Create Theme
+
+```bash
+pf theme create <NAME> [--base <THEME>] [--user] [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | Yes | New theme name (lowercase, hyphens allowed) |
+| `--base` | No | Base theme to copy from (defaults to current theme) |
+| `--user` | No | Create as user-level theme (`~/.claude/pennyfarthing/themes/`) |
+| `--dry-run` | No | Preview without making changes |
+
+Validation rules for name:
+- Lowercase letters and numbers only
+- Must start with a letter
+- Hyphens allowed (no underscores or spaces)
+- No conflicts with existing themes
+
+Creates file at:
+- Project-level: `.claude/pennyfarthing/themes/{name}.yaml`
+- User-level (with `--user`): `~/.claude/pennyfarthing/themes/{name}.yaml`
+
+### Theme Maker (Interactive)
+
+`/theme maker` is an interactive wizard — no CLI command. It walks through:
+
+1. **Theme name** — validated per rules above
+2. **Mode selection** — AI-Driven, Guided, or Manual
+3. **Character generation** — all 10 agent personas
+
+For each agent, generates: `character`, `shortName`, `visual`, `ocean`, `style`, `expertise`, `role`, `trait`, `quote`, `emoji`, `helper`.
+
+---
+
+## Agent Roles Reference
+
+| Agent | Role | Character Should Be |
+|-------|------|---------------------|
+| orchestrator | Meta-coordinator | Pattern-seer, guide |
+| sm | Scrum Master | Leader, coordinator |
+| tea | Test Engineer | Analyst, detail-oriented |
+| dev | Developer | Builder, practical |
+| reviewer | Code Reviewer | Critical, high standards |
+| architect | System Architect | Big-picture thinker |
+| pm | Product Manager | Strategic, stakeholder manager |
+| tech-writer | Documentation | Clear communicator |
+| ux-designer | UX Design | User advocate |
+| devops | Infrastructure | Reliable, systems runner |
+| ba | Business Analyst | Requirements discovery |
+
+## OCEAN Profile Guidelines
+
+| Agent | Profile | Rationale |
+|-------|---------|-----------|
+| orchestrator | High O (4-5), Moderate C (3-4) | Pattern-seer needs openness |
+| sm | High A (4-5), Moderate C (3-4) | Coordination requires agreeableness |
+| tea | High C (4-5), High O (4-5) | Testing needs conscientiousness + creativity |
+| dev | High C (4-5), Moderate O (3-4) | Building needs discipline |
+| reviewer | High C (4-5), Low A (2-3) | Critical review prioritizes standards |
+| architect | High O (4-5), High C (4-5) | Design needs vision + structure |
+| pm | High E (4-5), High A (4-5) | Stakeholder mgmt needs sociability |
+| tech-writer | High C (4-5), Low N (1-2) | Documentation needs precision |
+| ux-designer | High A (4-5), High O (4-5) | User advocacy needs empathy |
+| devops | High C (4-5), Low N (1-2) | Operations needs reliability |
+
+## Theme File Structure
+
+```yaml
+theme:
+  name: theme-name
+  description: "Brief description"
+  source: "Source universe"
+  pennyfarthing_version: "10.4.0"
+  created: 2026-01-01
+
+agents:
+  sm:
+    character: Character Name
+    shortName: Short
+    visual: "Portrait prompt description"
+    ocean: { O: 3, C: 4, E: 2, A: 3, N: 2 }
+    style: Communication style
+    expertise: Areas of expertise
+    role: Role in universe
+    trait: Key trait
+    quote: "Signature quote"
+    emoji: "X"
+    helper:
+      name: Helper Name
+      style: "Helper communication style"
+```
+
+## Theme Locations
+
+| Location | Purpose |
+|----------|---------|
+| `pennyfarthing-dist/personas/themes/` | Built-in themes (96+) |
+| `.claude/pennyfarthing/themes/` | Project-level custom |
+| `~/.claude/pennyfarthing/themes/` | User-level custom |
+| `.pennyfarthing/config.local.yaml` | Active theme selection |