@pennyfarthing/core 9.2.0 → 9.3.0

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

@@ -1,77 +0,0 @@
----
-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

@@ -1,210 +0,0 @@
----
-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

@@ -1,193 +0,0 @@
----
-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

@@ -1,9 +0,0 @@
----
-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

@@ -1,136 +0,0 @@
----
-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

@@ -1,58 +0,0 @@
----
-description: Merge develop to main and push (optional version bump)
----
-
-```bash
-./scripts/git/release.sh "$@"
-```
-
-<purpose>
-Release current develop branch to main and push to origin.
-</purpose>
-
-<usage>
-```bash
-# Just merge and push (no version change)
-/release
-
-# With version bump
-/release --bump patch    # 1.5.0 -> 1.5.1
-/release --bump minor    # 1.5.0 -> 1.6.0
-/release --bump major    # 1.5.0 -> 2.0.0
-
-# Preview what would happen
-/release --dry-run
-/release --bump patch --dry-run
-```
-</usage>
-
-<workflow>
-1. Pre-flight checks (clean working directory, branches exist)
-2. Pull latest develop and main
-3. Merge develop into main (fast-forward when possible)
-4. Push main to origin
-5. Push develop to origin
-6. Push any tags
-
-If `--bump` specified, delegates to `deploy.sh` which also:
-- Bumps VERSION file
-- Commits version change
-- Creates annotated git tag
-- Creates GitHub release from the tag (requires `gh` CLI)
-</workflow>
-
-<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 (or will switch to it)
-- Origin remote configured
-</prerequisites>
-
-<skills>
-- `/changelog` - For changelog format reference, auto-generation patterns, and version bump decisions
-</skills>