@pennyfarthing/core 7.4.0 → 7.4.1

package/pennyfarthing-dist/commands/job-fair.md

@@ -0,0 +1,102 @@
+---
+description: Discover which characters in a theme excel at each role
+argument-hint: <theme> [--runs N] [--roles <list>]
+---
+
+# Job Fair
+
+Run every character in a theme against benchmarks to find hidden talents.
+
+## Usage
+
+```
+/job-fair <theme>
+/job-fair <theme> --runs 2
+/job-fair <theme> --roles dev,reviewer
+```
+
+## On Invoke
+
+**Arguments:** $ARGUMENTS
+
+### Step 1: Parse and Validate
+
+```bash
+# Theme is first positional arg (strip any --flags)
+THEME=$(echo "$ARGUMENTS" | awk '{print $1}' | sed 's/^--theme[= ]//')
+
+# Check theme exists
+ls pennyfarthing-dist/personas/themes/${THEME}.yaml
+```
+
+If not found, list available themes and stop.
+
+Extract `--runs N` (default: 4) and `--roles x,y` (default: all with baselines).
+
+### Step 2: Load Characters
+
+Read `pennyfarthing-dist/personas/themes/${THEME}.yaml` and list agents:
+
+| Role | Character |
+|------|-----------|
+| sm | {agents.sm.character} |
+| dev | {agents.dev.character} |
+| ... | ... |
+
+### Step 3: Find Baselines
+
+Pick ONE scenario per role from `internal/results/baselines/`:
+
+```bash
+# For each role, find first available baseline
+for role in dev reviewer tea sm architect; do
+  baseline=$(ls -d internal/results/baselines/*/${role} 2>/dev/null | head -1)
+  if [ -n "$baseline" ]; then
+    scenario=$(basename $(dirname "$baseline"))
+    summary="$baseline/summary.yaml"
+    # Read statistics.mean and statistics.n from summary.yaml
+  fi
+done
+```
+
+Show table:
+
+| Role | Scenario | Baseline | n |
+|------|----------|----------|---|
+| dev | race-condition-cache | 76.8 | 10 |
+
+### Step 4: Confirm
+
+Show: `{characters} × {roles} × {runs} = {total} runs`
+
+Ask user to confirm or cancel.
+
+### Step 5: Execute
+
+For each role, for each character:
+
+```bash
+# Native role
+scripts/solo-runner.sh "${THEME}:${role}" "${scenario}" ${runs}
+
+# Cross-role (character playing different role)
+scripts/solo-runner.sh "${THEME}:${native_role}" "${scenario}" ${runs} --as ${target_role}
+```
+
+Show progress as each completes.
+
+### Step 6: Report Results
+
+Show champions per role and full matrix:
+
+| Character | dev | reviewer | tea | sm | Avg |
+|-----------|-----|----------|-----|-----|-----|
+| ... | ... | ... | ... | ... | ... |
+
+Save to `internal/results/job-fair/${THEME}-${timestamp}/summary.yaml`
+
+## Reference
+
+- Theme files: `pennyfarthing-dist/personas/themes/*.yaml`
+- Baselines: `internal/results/baselines/{scenario}/{role}/summary.yaml`
+- Solo runner: `scripts/solo-runner.sh`

package/pennyfarthing-dist/commands/list-themes.md

@@ -0,0 +1,21 @@
+---
+description: List all available persona themes
+---
+
+# List Themes
+
+Show all available persona themes with the current theme highlighted.
+
+## Instructions
+
+Run the list-themes script and display the output directly to the user:
+
+```bash
+$CLAUDE_PROJECT_DIR/pennyfarthing-dist/scripts/list-themes.sh
+```
+
+**IMPORTANT:** Copy the script output into your response text so the user sees it in the console. Bash tool output may be collapsed in the UI.
+
+The output shows:
+- Current theme marked with `*`
+- Tier in brackets: `[S]` elite, `[A]` excellent, `[B]` strong, `[C]` good, `[D]` below average, `[U]` unbenchmarked

package/pennyfarthing-dist/commands/orchestrator.md

@@ -0,0 +1,56 @@
+---
+description: Orchestrator - Coordinator of all agents and meta operations
+---
+
+<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 "orchestrator"
+```
+This finds the project root and loads your persona. Adopt the character shown in the output.
+
+Then load and follow `.pennyfarthing/agents/orchestrator.md`
+</agent-activation>
+
+<agent-exit>
+On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
+</agent-exit>
+
+<purpose>
+Process architect who coordinates agents, improves workflows, and maintains system health.
+</purpose>
+
+<when-to-use>
+- Process improvement and bottleneck analysis
+- Agent behavior updates and alignment
+- Skill creation or maintenance
+- Sprint retrospectives and learnings capture
+- Meta-level workflow debugging
+</when-to-use>
+
+<not-for>
+- Story implementation (use `/dev`)
+- Code review (use `/reviewer`)
+- Bug fixes (use `/dev`)
+- Sprint planning (use `/pm` or `/sm`)
+</not-for>
+
+<meta-operations>
+**Process Improvement:** Analyze workflow bottlenecks, propose agent behavior updates, refine handoffs
+
+**Agent Coordination:** Ensure agent files are consistent, resolve behavior conflicts, maintain alignment
+
+**Skill Maintenance:** Create skills for common patterns, update existing knowledge, remove deprecated skills
+
+**Retrospective Analysis:** Review completed sprints, capture learnings, update agent sidecars
+
+**System Debugging:** Fix process issues when normal workflow breaks
+</meta-operations>
+
+<reference>
+- **Agent:** `.pennyfarthing/agents/orchestrator.md`
+- **Sidecar:** `.claude/project/agents/orchestrator-sidecar/`
+- **Skills:** `/sprint-context`
+- **Agent Files:** All `.pennyfarthing/agents/*.md`, `.core/commands/*.md`
+- **Documentation:** Workflow specs, agent responsibilities, handoff protocols
+</reference>

package/pennyfarthing-dist/commands/parallel-work.md

@@ -0,0 +1,71 @@
+---
+description: Start parallel work in a new worktree
+---
+
+```bash
+./scripts/run.sh core/agent-session.sh start "parallel-work"
+```
+
+<parallel-work-flow>
+## Parallel Work Setup
+
+Start a new story in a worktree while keeping main checkout intact.
+
+### Step 1: Create Worktree
+
+```bash
+# Get story info from user
+read -p "Story ID (e.g., 5-3a): " STORY_ID
+read -p "Branch name (e.g., feat/5-3a-feature): " BRANCH_NAME
+
+# Create worktree
+WORKTREE_NAME="wt-${STORY_ID}"
+./scripts/run.sh git/worktree-manager.sh create "$WORKTREE_NAME" "$BRANCH_NAME"
+
+# Get port configuration
+eval $(./scripts/run.sh git/worktree-manager.sh ports "$WORKTREE_NAME")
+```
+
+### Step 2: Create Session File
+
+Create `.session/${STORY_ID}-session.md` with:
+
+```markdown
+# Story ${STORY_ID}: [Title]
+
+## Worktree Context
+worktree: ${WORKTREE_NAME}
+path: ${WORKTREE_PATH}
+api_port: ${API_PORT}
+ui_port: ${UI_PORT}
+
+## Story Info
+- **Epic:** [from sprint]
+- **Points:** [from sprint]
+- **Repos:** Both
+
+## Phase
+sm
+
+## Status
+setup
+
+## Acceptance Criteria
+- [ ] AC1
+- [ ] AC2
+```
+
+### Step 3: Hand to SM
+
+Invoke SM to complete story setup in the worktree context.
+</parallel-work-flow>
+
+<agent-activation>
+1. Load persona from theme config → `agents.sm`
+2. Load and follow `.pennyfarthing/agents/sm.md`
+3. SM will detect worktree session and work in that context
+</agent-activation>
+
+<agent-exit>
+On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
+</agent-exit>

package/pennyfarthing-dist/commands/party-mode.md

@@ -0,0 +1,67 @@
+---
+description: Free-form creative brainstorming with all agents
+---
+
+# Party Mode - Creative Brainstorming Session
+
+You are now in **PARTY MODE** - a free-form creative brainstorming session where all Pennyfarthing agents contribute ideas without the usual constraints.
+
+## The Vibe
+
+This is the "yes, and..." mode. No idea is too wild. We're exploring possibilities, not committing to implementations. The goal is to generate creative solutions and novel approaches.
+
+## How It Works
+
+When a topic or problem is presented:
+
+1. **Each agent perspective contributes** (pick 3-4 relevant ones):
+   - **Vetinari (PM)**: Strategic implications, business value, political angles
+   - **Leonard (Architect)**: Technical possibilities, creative mechanisms, "what if we..."
+   - **Vimes (Manager)**: Practical concerns, team impact, "how would this actually work"
+   - **Carrot (Dev)**: Implementation ideas, "I could build that by..."
+   - **Igor (TEA)**: Quality angles, "we could verify that with..."
+   - **Sybil (UX)**: User experience, "users would love if..."
+   - **Sacharissa (Tech Writer)**: Communication, "we could explain it as..."
+   - **Lu-Tze (DevOps)**: Operational reality, "in production this would..."
+   - **DEATH (Pennyfarthing Master)**: THE LONG VIEW. WHAT MATTERS IN THE END.
+
+2. **Build on each other's ideas** - "Yes, and what if we also..."
+
+3. **No shooting down ideas** - Save criticism for later. Capture everything.
+
+4. **Wild ideas welcome** - The crazy idea might spark the brilliant one
+
+## Output Format
+
+After the brainstorm, summarize:
+
+```markdown
+## Party Mode Results: [Topic]
+
+### Ideas Generated
+1. [Idea] - sparked by [agent perspective]
+2. [Idea] - built on idea #1 by adding...
+...
+
+### Most Promising
+- [Top 3 ideas worth exploring further]
+
+### Wild Cards
+- [Crazy ideas that might have something to them]
+
+### Next Steps
+- [ ] Explore [idea] with /architect
+- [ ] Prototype [idea] with /dev
+- [ ] Get user feedback on [idea]
+```
+
+## Activation
+
+To start party mode, present a topic:
+- "Let's party mode on: how to improve the dashboard"
+- "Party mode: what if we had real-time collaboration?"
+- "Creative session: solving the notification spam problem"
+
+---
+
+**THE PARTY HAS STARTED. WHAT SHALL WE BRAINSTORM?**

package/pennyfarthing-dist/commands/permissions.md

@@ -0,0 +1,193 @@
+---
+description: View and manage runtime permission grants - list, grant, revoke, or show details
+---
+
+# Permission Management
+
+Manage runtime permission grants for tool access control.
+
+## Usage
+
+```
+/permissions              # List all active grants
+/permissions grant <tool> "<scope>" [--type <type>]  # Add permission
+/permissions revoke <tool>  # Remove all grants for tool
+/permissions show <tool>    # Show details for tool
+```
+
+## Subcommands
+
+### List Grants (default)
+
+When invoked without arguments, list all active permission grants:
+
+```bash
+# Read grants from settings
+cat .claude/settings.local.json 2>/dev/null | jq -r '
+  if .permissions.grants then
+    .permissions.grants[] |
+    "  \(.tool): \(.scope) [\(.grant_type)] - granted \(.granted_at)"
+  else
+    empty
+  end
+' || echo "No grants found"
+```
+
+**Output format:**
+```
+Active Permission Grants:
+  WebFetch: *.github.com [session] - granted 2026-01-13T15:00:00Z
+  Bash: git * [always] - granted 2026-01-13T14:30:00Z
+```
+
+If no grants exist, display: "No active permission grants."
+
+### Grant Tool Access
+
+Add a permission grant:
+
+```
+/permissions grant <tool> "<scope>" [--type <once|session|always>]
+```
+
+**Parameters:**
+- `<tool>` - Tool name (WebFetch, Bash, Read, Edit, Write, Grep, Glob, etc.)
+- `"<scope>"` - Scope pattern in quotes (e.g., `"*.github.com"`, `"git *"`)
+- `--type` - Grant duration: `once`, `session` (default), or `always`
+
+**Implementation:**
+
+1. Validate tool name is a known Claude Code tool
+2. Create grant object with timestamp:
+   ```json
+   {
+     "tool": "<tool>",
+     "scope": "<scope>",
+     "grant_type": "<type>",
+     "granted_at": "<ISO timestamp>"
+   }
+   ```
+3. Read existing settings, append to `permissions.grants` array
+4. Write updated settings back to `.claude/settings.local.json`
+5. Report success
+
+**Example:**
+```bash
+# Create/update grant
+jq --arg tool "WebFetch" \
+   --arg scope "*.github.com" \
+   --arg type "session" \
+   --arg time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+   '.permissions.grants += [{"tool": $tool, "scope": $scope, "grant_type": $type, "granted_at": $time}]' \
+   .claude/settings.local.json > .claude/settings.local.json.tmp \
+   && mv .claude/settings.local.json.tmp .claude/settings.local.json
+```
+
+### Revoke Tool Access
+
+Remove all grants for a specific tool:
+
+```
+/permissions revoke <tool>
+```
+
+**Implementation:**
+
+1. Read current grants from settings
+2. Filter out grants matching the tool name
+3. Write updated grants back
+4. Report how many grants were removed
+
+**Example:**
+```bash
+# Remove grants for tool
+jq --arg tool "WebFetch" \
+   '.permissions.grants = (.permissions.grants // [] | map(select(.tool != $tool)))' \
+   .claude/settings.local.json > .claude/settings.local.json.tmp \
+   && mv .claude/settings.local.json.tmp .claude/settings.local.json
+```
+
+### Show Grant Details
+
+Display detailed information about grants for a specific tool:
+
+```
+/permissions show <tool>
+```
+
+**Output includes:**
+- All grants for the specified tool
+- Scope patterns
+- Grant types
+- Timestamps
+- Remaining uses (for `once` type)
+
+**Example:**
+```bash
+cat .claude/settings.local.json | jq --arg tool "WebFetch" '
+  .permissions.grants // [] | map(select(.tool == $tool))
+'
+```
+
+## Grant Types
+
+| Type | Duration | Persistence |
+|------|----------|-------------|
+| `once` | Single use, then removed | Memory only |
+| `session` | Until conversation ends | Memory only |
+| `always` | Persists forever | `.claude/settings.local.json` |
+
+## Storage
+
+Grants are stored in `.claude/settings.local.json` under `permissions.grants`:
+
+```json
+{
+  "permissions": {
+    "allow": ["Read", "Bash", ...],
+    "grants": [
+      {
+        "tool": "WebFetch",
+        "scope": "*.github.com",
+        "grant_type": "session",
+        "granted_at": "2026-01-13T15:00:00Z"
+      }
+    ]
+  }
+}
+```
+
+## Valid Tool Names
+
+- `Read`, `Write`, `Edit`
+- `Bash`
+- `Glob`, `Grep`
+- `WebFetch`, `WebSearch`
+- `Task`
+- `Skill`
+- `NotebookEdit`
+
+## Examples
+
+```bash
+# List all grants
+/permissions
+
+# Grant WebFetch access to GitHub (session-scoped)
+/permissions grant WebFetch "*.github.com"
+
+# Grant Bash access to git commands (permanent)
+/permissions grant Bash "git *" --type always
+
+# Show all WebFetch grants
+/permissions show WebFetch
+
+# Revoke all Bash grants
+/permissions revoke Bash
+```
+
+## Reference
+
+- **Skill:** `.claude/skills/permissions/skill.md`
+- **Settings:** `.claude/settings.local.json`
+- **Related:** Story 33-1 (Permission Request Protocol), Story 33-3 (Cyclist Permission UI)

package/pennyfarthing-dist/commands/pm.md

@@ -0,0 +1,60 @@
+---
+description: Product Manager - Strategic planning and prioritization
+---
+
+<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 "pm"
+```
+This finds the project root and loads your persona. Adopt the character shown in the output.
+
+Then load and follow `.pennyfarthing/agents/pm.md`
+</agent-activation>
+
+<agent-exit>
+On exit: Capture learnings to sidecar, run `run.sh core/agent-session.sh stop`
+</agent-exit>
+
+<purpose>
+Strategic planning and prioritization leader who sets direction outside the TDD flow.
+</purpose>
+
+<when-to-use>
+- Sprint planning and goal setting
+- Backlog grooming and epic prioritization
+- Roadmap planning (2-3 sprints ahead)
+- Value assessment and feature scoping
+- Stakeholder communication on priorities
+</when-to-use>
+
+<not-for>
+- NOT in TDD flow (SM → TEA → Dev → Reviewer handles implementation)
+- NOT for tactical bug fixes or test writing
+- NOT for code review or technical architecture decisions
+</not-for>
+
+<key-workflows>
+**1. Sprint Planning** - Review velocity, select stories, set sprint goal
+**2. Backlog Grooming** - Prioritize epics, refine stories, assess dependencies
+**3. Epic Prioritization** - Rank candidates by business value, risk, effort, strategic fit
+**4. Story Scoping** - Define acceptance criteria and acceptance tests
+**5. Roadmap Planning** - Plan 2-3 sprint horizon aligned with business goals
+</key-workflows>
+
+<responsibilities>
+- Assess and prioritize work (business value vs. effort)
+- Plan sprints that feed into the TDD flow
+- Evaluate epics by value, risk, dependencies
+- Communicate decisions to stakeholders
+- Manage scope and prevent scope creep
+- Identify quick wins and strategic features
+- Plan roadmap aligned with business goals
+</responsibilities>
+
+<reference>
+- **Agent:** `.pennyfarthing/agents/pm.md`
+- **Sidecar:** `.claude/project/agents/pm-sidecar/`
+- **Skills:** `/sprint-context`
+- **Handoffs:** SM (tech context), Architect (design), Dev (ready stories)
+</reference>