@pennyfarthing/core 10.0.1 → 10.0.2

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

@@ -0,0 +1,77 @@
+---
+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.
+
+## Setup
+
+First, get the current theme's agent personas:
+
+```bash
+pennyfarthing theme show
+```
+
+Use the character names from the current theme for all agent perspectives below.
+
+## How It Works
+
+When a topic or problem is presented:
+
+1. **Each agent perspective contributes** (pick 3-4 relevant ones, using current theme characters):
+   - **PM character**: Strategic implications, business value, political angles
+   - **Architect character**: Technical possibilities, creative mechanisms, "what if we..."
+   - **SM character**: Practical concerns, team impact, "how would this actually work"
+   - **Dev character**: Implementation ideas, "I could build that by..."
+   - **TEA character**: Quality angles, "we could verify that with..."
+   - **UX-Designer character**: User experience, "users would love if..."
+   - **Tech-Writer character**: Communication, "we could explain it as..."
+   - **DevOps character**: Operational reality, "in production this would..."
+   - **Orchestrator character**: 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/patch.md

@@ -0,0 +1,210 @@
+---
+description: Interrupt-driven bug fix during active story work
+---
+
+# Patch Mode
+
+Quick fix for blocking issues during active story work. Branches from your FEATURE branch (not develop), fixes the issue, and restores workflow state.
+
+<purpose>
+Enable rapid bug fixes without abandoning current story context. Preserves workflow state and returns to previous work after fix is merged.
+</purpose>
+
+<when-to-use>
+- Blocking bug discovered during story implementation
+- Script error preventing progress
+- Path or config issue blocking development
+- Urgent UI fix needed before continuing
+- Any issue that blocks current work but isn't part of the story
+</when-to-use>
+
+<when-not-to-use>
+- For planned feature work (use `/sprint work`)
+- For quick maintenance (use `/chore`)
+- For standalone features (use `/standalone`)
+- When not actively working on a story
+</when-not-to-use>
+
+<usage>
+```bash
+# Start a patch (prompts for description)
+/patch
+
+# With description
+/patch "fix missing import in utils"
+
+# Alternative trigger
+/fix-blocker "script path not found"
+```
+</usage>
+
+<key-differences>
+| Aspect | `/patch` | `/trivial` | `/standalone` |
+|--------|----------|------------|---------------|
+| Branches from | Feature branch | develop | develop |
+| Merges to | Feature branch | develop | develop |
+| Preserves state | Yes (stack-based) | No | No |
+| Workflow | Dev only | SM → Dev → finish | SM → finish |
+| Use case | Mid-story fix | Quick new feature | Wrap dirty changes |
+</key-differences>
+
+<workflow>
+
+## Flow: Dev Only (No TEA, No Review)
+
+1. **Capture State** - Save current story/workflow to patch stack
+2. **Create Branch** - `patch/{description}-{timestamp}` from current feature branch
+3. **Fix Issue** - Dev implements minimal fix
+4. **Commit** - `fix(patch): {description} [from:{story_id}]`
+5. **Merge** - Merge patch branch back to feature branch
+6. **Restore** - Pop state from patch stack, continue story work
+
+</workflow>
+
+## Execution
+
+### Step 1: Capture Current State
+
+```bash
+# Verify we're on a feature branch
+CURRENT_BRANCH=$(git branch --show-current)
+if [[ ! "$CURRENT_BRANCH" =~ ^feat/ ]]; then
+  echo "ERROR: /patch requires active feature branch work"
+  echo "Current branch: $CURRENT_BRANCH"
+  echo "Use /standalone or /chore for fixes outside story work"
+  exit 1
+fi
+
+# Find active session
+SESSION_FILE=$(ls -t .session/*-session.md 2>/dev/null | head -1)
+if [ -z "$SESSION_FILE" ]; then
+  echo "ERROR: No active session found"
+  exit 1
+fi
+
+# Extract current state
+STORY_ID=$(grep -m1 "^**Story ID:**" "$SESSION_FILE" | sed 's/.*: //')
+WORKFLOW=$(grep -m1 "^**Workflow:**" "$SESSION_FILE" | sed 's/.*: //')
+PHASE=$(grep -m1 "^**Phase:**" "$SESSION_FILE" | sed 's/.*: //')
+AGENT=$(grep -m1 "^**Agent:**" "$SESSION_FILE" | sed 's/.*: //')
+
+echo "Saving state for $STORY_ID (phase: $PHASE)"
+```
+
+### Step 2: Push State to Patch Stack
+
+```bash
+# Create or append to patch stack
+STACK_FILE=".session/patch-stack.yaml"
+
+# Generate stack entry
+cat >> "$STACK_FILE" << EOF
+- story_id: "$STORY_ID"
+  workflow: "$WORKFLOW"
+  phase: "$PHASE"
+  agent: "$AGENT"
+  feature_branch: "$CURRENT_BRANCH"
+  timestamp: "$(date -Iseconds)"
+EOF
+
+echo "State pushed to patch stack"
+```
+
+### Step 3: Create Patch Branch
+
+```bash
+# Get description from args or prompt
+DESCRIPTION="${1:-}"
+if [ -z "$DESCRIPTION" ]; then
+  echo "Enter patch description:"
+  read DESCRIPTION
+fi
+
+# Generate branch name
+SLUG=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-30)
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+PATCH_BRANCH="patch/${SLUG}-${TIMESTAMP}"
+
+# Create branch from current position
+git checkout -b "$PATCH_BRANCH"
+echo "Created patch branch: $PATCH_BRANCH"
+```
+
+### Step 4: Dev Implements Fix
+
+The developer implements the minimal fix needed. This is a single-agent phase with no TEA or review required.
+
+### Step 5: Commit and Merge
+
+```bash
+# Stage and commit
+git add .
+git commit -m "fix(patch): ${DESCRIPTION} [from:${STORY_ID}]
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+
+# Merge back to feature branch
+git checkout "$CURRENT_BRANCH"
+git merge "$PATCH_BRANCH" --no-ff -m "Merge patch: ${DESCRIPTION}"
+
+# Delete patch branch
+git branch -d "$PATCH_BRANCH"
+```
+
+### Step 6: Restore State
+
+```bash
+# Pop from patch stack
+STACK_FILE=".session/patch-stack.yaml"
+
+# Get last entry and remove it
+# (In practice, use yq or Python script for proper YAML handling)
+
+echo "Patch complete. Restored to $STORY_ID phase: $PHASE"
+echo "Run /${AGENT} to continue story work"
+```
+
+## Nested Patches
+
+Patches can be nested - if a patch uncovers another blocking issue, run `/patch` again. The stack preserves each level:
+
+```yaml
+# .session/patch-stack.yaml
+- story_id: "75-3"
+  workflow: "tdd"
+  phase: "green"
+  agent: "dev"
+  feature_branch: "feat/MSSCI-14001-add-feature"
+  timestamp: "2026-02-03T10:30:00-05:00"
+
+- story_id: "75-3"
+  workflow: "patch"
+  phase: "fix"
+  agent: "dev"
+  feature_branch: "patch/fix-import-20260203-103500"
+  timestamp: "2026-02-03T10:45:00-05:00"
+```
+
+When patches complete, state is restored in LIFO order.
+
+## Safety
+
+- **Never patch on develop** - Patches branch from feature work
+- **Minimal scope** - Fix only the blocking issue
+- **No skip** - Can't skip patch; must complete or abort
+- **Stack limit** - Max 5 nested patches to prevent confusion
+
+## Comparison
+
+| Command | Tracking | Branch From | Merge To | State |
+|---------|----------|-------------|----------|-------|
+| `/patch` | Implicit | Feature | Feature | Preserved |
+| `/chore` | None | develop | develop | None |
+| `/standalone` | Jira | develop | develop | None |
+| `/sprint work` | Jira + Sprint | develop | develop | Full session |
+
+<related>
+- `/chore` - Quick commits without tracking
+- `/standalone` - Wrap changes into tracked Jira story
+- `/sprint work` - Start planned sprint story
+</related>

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,9 @@
+---
+description: Product Manager - Strategic planning and prioritization
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
+export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
+python3 -m pennyfarthing_scripts.cli agent start "pm"
+```

package/pennyfarthing-dist/commands/prime.md

@@ -0,0 +1,136 @@
+---
+description: Load essential project context at agent activation
+---
+
+<purpose>
+Quickly load essential context files to reduce agent cold-start overhead.
+Automatically invoked on agent activation via `pf agent start`.
+</purpose>
+
+<when-to-use>
+- Automatically on agent activation (`/sm`, `/tea`, `/dev`, `/reviewer`)
+- Manually to refresh context mid-session
+- To verify what context is available
+</when-to-use>
+
+<execution>
+
+## Running /prime
+
+Use the Python CLI:
+
+```bash
+# Load all essential context (default)
+python3 -m pennyfarthing_scripts.cli agent start "sm"
+
+# Minimal mode - fastest startup
+python3 -m pennyfarthing_scripts.cli agent start "sm" --minimal
+
+# Full mode - include domain docs
+python3 -m pennyfarthing_scripts.cli agent start "sm" --full
+
+# Skip persona loading
+python3 -m pennyfarthing_scripts.cli agent start "sm" --no-persona
+
+# JSON output (for Cyclist integration)
+python3 -m pennyfarthing_scripts.cli agent start "sm" --json
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--minimal` | Load only CLAUDE.md files (fastest startup) |
+| `--full` | Include domain docs from .claude/project/ |
+| `--quiet` | Suppress section headers (for automated use) |
+| `--agent <name>` | Load agent's sidecar patterns (learned project-specific patterns) |
+
+## What Gets Loaded
+
+Context is loaded in priority order:
+
+### Default Mode
+| Priority | Content | Source |
+|----------|---------|--------|
+| 1 | Project instructions | `CLAUDE.md` |
+| 2 | User instructions | `~/.claude/CLAUDE.md` (if exists) |
+| 3 | Sprint summary | `sprint/current-sprint.yaml` (key fields only) |
+| 4 | Active session | `.session/*-session.md` (first 50 lines) |
+| 5 | Agent sidecar | `.pennyfarthing/sidecars/{agent}/*.md` (if `--agent` provided) |
+| 6 | Shared context | `.pennyfarthing/guides/agent-behavior.md` (project info - all agents) |
+| 7 | Shared behavior | `.pennyfarthing/guides/agent-behavior.md` (protocols - all agents) |
+| 8 | Tactical guide | `.pennyfarthing/guides/agent-behavior.md` (for sm, tea, dev, reviewer only) |
+
+### Minimal Mode (`--minimal`)
+Only loads CLAUDE.md files (priority 1-2).
+
+### Full Mode (`--full`)
+Adds domain documentation from `.claude/project/CLAUDE-*.md` files.
+
+### Agent Sidecar (`--agent <name>`)
+When agent name is provided, loads the agent's project-specific patterns from their sidecar directory. This gives agents their learned patterns immediately on activation.
+
+### Agent Behavior Guide (automatic for all agents)
+All agents receive the shared context guide which includes project info, directory structure, git strategy, sprint system overview, and build commands.
+
+### Shared Behavior (automatic for all agents)
+All agents receive the shared behavior guide which includes confidence protocols, sidecar memory system documentation, reasoning modes, and exit protocols.
+
+### Tactical Guide (automatic for tactical agents)
+For tactical agents (sm, tea, dev, reviewer), additionally loads the tactical behavior guide which includes critical patterns for Bash tool usage, session file handling, and handoff protocols.
+
+</execution>
+
+<output-format>
+
+```
+# CLAUDE.md
+[Project instructions content...]
+
+# ~/.claude/CLAUDE.md (if exists)
+[User instructions content...]
+
+---
+# Sprint Context
+Sprint 7: Benchmark framework expansion, monorepo consolidation, rich agent telemetry
+Progress: 62/106 points
+
+---
+# Active Session
+[First 50 lines of session file...]
+```
+
+With `--quiet`, section headers are suppressed.
+
+</output-format>
+
+<integration>
+
+## Python CLI Integration
+
+The `/prime` command is automatically invoked when agents activate:
+
+1. User invokes `/sm`, `/tea`, `/dev`, or `/reviewer`
+2. `pf agent start <name>` runs
+3. Context is loaded: workflow state, agent definition, persona, behavior guide, sprint context, session, sidecars
+4. Agent starts with full context AND their learned patterns loaded
+
+This reduces the "cold start" problem where agents must discover context through multiple file reads.
+
+## Manual Refresh
+
+If context becomes stale mid-session, run `/prime` manually:
+
+```bash
+/prime        # Refresh standard context
+/prime --full # Include domain docs
+```
+
+</integration>
+
+<reference>
+- **CLI:** `pf agent start <name>` or `python3 -m pennyfarthing_scripts.cli agent start <name>`
+- **Loads:** Workflow state, agent definition, persona, behavior guide, sprint context, session, sidecars
+- **Sidecar location:** `.pennyfarthing/sidecars/{agent}/*.md`
+- **Behavior guide:** `.pennyfarthing/guides/agent-behavior.md` (all agents)
+</reference>

package/pennyfarthing-dist/commands/release.md

@@ -0,0 +1,74 @@
+---
+description: Interactive stepped release with verification gates
+---
+
+<purpose>
+Release a new version of Pennyfarthing using an interactive stepped workflow with gates at every critical point. An 11-step process that verifies each stage before proceeding.
+</purpose>
+
+<usage>
+```bash
+# Start the interactive release workflow
+/release
+
+# The workflow will ask for bump type (major/minor/patch) during preflight
+```
+</usage>
+
+<workflow>
+This command starts the `release` stepped workflow (BikeLane):
+
+1. **Preflight** — Clean state, compute version, conflict checks
+2. **Bump** — Update all version files, show diff ← GATE
+3. **Changelog** — Generate entries from commits (`/changelog`) ← GATE
+4. **README** — Audit feature counts, update content
+5. **CLAUDE.md** — Verify version, build commands, project structure
+6. **Retro** — Optional retrospective (`/retro`)
+7. **Commit** — Stage, commit, merge to develop, verify staging ← GATE
+8. **Merge** — Merge develop → main, create tag
+9. **Push & Tag** — Push branches + tag (point of no return) ← GATE
+10. **Publish** — npm publish all packages (core, cyclist, theme packs) ← GATE
+11. **Finalize** — GitHub release, summary
+
+Gates pause for user approval. You can abort, revise, or continue at each gate.
+</workflow>
+
+<instructions>
+Start the release stepped workflow:
+
+```bash
+# Start the workflow
+/workflow start release
+```
+
+If already in progress:
+```bash
+# Resume where you left off
+/workflow resume
+```
+
+To check status:
+```bash
+/workflow status
+```
+</instructions>
+
+<when-to-use>
+- After completing a sprint or set of features
+- When develop is stable and ready for production
+- Before deploying to production environments
+</when-to-use>
+
+<prerequisites>
+- Clean working directory (no uncommitted changes)
+- On develop branch
+- Origin remote configured
+- npm authentication configured (for publish step)
+- `gh` CLI authenticated (for GitHub release step)
+</prerequisites>
+
+<skills>
+- `/changelog` - For changelog format reference and auto-generation
+- `/retro` - For optional release retrospective
+- `/workflow` - For workflow management commands
+</skills>