@pennyfarthing/core 7.5.0 → 7.6.1

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,7 @@
+---
+description: Product Manager - Strategic planning and prioritization
+---
+
+```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"
+```

package/pennyfarthing-dist/commands/prime.md

@@ -0,0 +1,140 @@
+---
+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 agent-session.sh.
+</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 prime.sh script:
+
+```bash
+# Load all essential context (default)
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh
+
+# Minimal mode - CLAUDE.md only (fastest)
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --minimal
+
+# Full mode - include domain docs
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --full
+
+# Quiet mode - suppress headers (used by agent-session.sh)
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --quiet
+
+# With agent sidecar loading
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/prime.sh --agent reviewer
+```
+
+## 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>
+
+## agent-session.sh Integration
+
+The `/prime` command is automatically invoked when agents activate:
+
+1. User invokes `/sm`, `/tea`, `/dev`, or `/reviewer`
+2. `agent-session.sh start` runs
+3. Persona XML is output
+4. `/prime --quiet --agent <agent-name>` loads context automatically
+5. 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. The `--agent` flag ensures each agent gets their project-specific sidecar patterns immediately.
+
+## Manual Refresh
+
+If context becomes stale mid-session, run `/prime` manually:
+
+```bash
+/prime        # Refresh standard context
+/prime --full # Include domain docs
+```
+
+</integration>
+
+<reference>
+- **Script:** `.pennyfarthing/scripts/prime.sh`
+- **Called by:** agent-session.sh on agent start (with `--agent` flag)
+- **Loads:** CLAUDE.md, sprint, session, sidecar, shared context, shared behavior, tactical guide
+- **Sidecar location:** `.pennyfarthing/sidecars/{agent}/*.md`
+- **Shared context:** `.pennyfarthing/guides/agent-behavior.md` (all agents)
+- **Shared behavior:** `.pennyfarthing/guides/agent-behavior.md` (all agents)
+- **Tactical guide:** `.pennyfarthing/guides/agent-behavior.md` (sm, tea, dev, reviewer only)
+</reference>

package/pennyfarthing-dist/commands/release.md

@@ -0,0 +1,58 @@
+---
+description: Merge develop to main and push (optional version bump)
+---
+
+```bash
+./scripts/run.sh 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>

package/pennyfarthing-dist/commands/repo-status.md

@@ -0,0 +1,49 @@
+---
+description: Check git status of all project repos
+---
+
+# Repository Status Check
+
+Check the git status of all project repos at once.
+
+## Configuration
+
+Repos are configured in `.claude/project/repos.yaml`. The script automatically reads this configuration.
+
+## Instructions
+
+Run this command to show the status of all repos:
+
+```bash
+$CLAUDE_PROJECT_DIR/scripts/run.sh git/git-status-all.sh
+```
+
+For a brief one-line-per-repo summary:
+
+```bash
+$CLAUDE_PROJECT_DIR/scripts/run.sh git/git-status-all.sh --brief
+```
+
+## What It Shows
+
+For each configured repo:
+- Current branch
+- Whether there are uncommitted changes
+- Whether the repo is ahead/behind origin
+- Unpushed commits (if any)
+
+## Adding More Repos
+
+To add repos, edit `.claude/project/repos.yaml`:
+
+```yaml
+repos:
+  my-api:
+    path: my-api        # relative to project root
+    type: api
+    language: go
+  my-ui:
+    path: my-ui
+    type: ui
+    language: typescript
+```

package/pennyfarthing-dist/commands/retro.md

@@ -0,0 +1,200 @@
+---
+description: Facilitate a sprint retrospective
+---
+
+# Retro - Sprint Retrospective
+
+You are facilitating a **sprint retrospective** to reflect on what happened, learn from it, and improve.
+
+## Pre-Retro: Load Context
+
+First, load the sprint data:
+```bash
+# Check sprint status
+cat sprint/current-sprint.yaml
+
+# Check completed work
+ls -la sprint/archive/
+
+# Check any session handoffs
+cat .session/{STORY_ID}-session.md 2>/dev/null || echo "No active work"
+```
+
+## Retro Format: 4 Ls
+
+### 1. Liked (What went well?)
+- What worked?
+- What should we keep doing?
+- What made us proud?
+
+### 2. Learned (What did we discover?)
+- New techniques or approaches
+- Things we didn't know before
+- Surprises (good or bad)
+
+### 3. Lacked (What was missing?)
+- Resources we needed
+- Information gaps
+- Tools or processes that would have helped
+
+### 4. Longed For (What do we wish we had?)
+- Improvements for next time
+- Things to try
+- Experiments to run
+
+## Output Template
+
+```markdown
+## Sprint [N] Retrospective
+**Date**: [Date]
+**Sprint Goal**: [Goal from sprint file]
+**Velocity**: [Planned] planned / [Completed] completed
+
+### Liked
+- [Thing that went well]
+- [Another positive]
+
+### Learned
+- [Discovery or insight]
+- [Technical learning]
+
+### Lacked
+- [Missing resource/info]
+- [Gap identified]
+
+### Longed For
+- [Improvement idea]
+- [Experiment to try]
+
+### Action Items
+| Action | Owner | Due |
+|--------|-------|-----|
+| [Specific action] | [Agent/Person] | [Next sprint] |
+
+### Metrics
+- Stories completed: X/Y
+- Bugs fixed: N
+- Tech debt addressed: [List]
+- Tests added: N
+```
+
+## Sidecar Maintenance
+
+Review and consolidate agent sidecars during retro:
+
+### 1. Review Sidecar Entries
+
+```bash
+echo "=== Sidecar Entries This Sprint ==="
+for agent in dev tea sm reviewer architect; do
+    SIDECAR=".claude/project/agents/${agent}-sidecar"
+    if [ -d "$SIDECAR" ]; then
+        echo "--- $agent ---"
+        for file in "$SIDECAR"/*.md; do
+            [ -f "$file" ] && grep -l "$(date +%Y)" "$file" 2>/dev/null && cat "$file"
+        done
+    fi
+done
+```
+
+### 2. Consolidate Learnings
+
+For each sidecar entry, ask:
+- **Still relevant?** Keep if yes, remove if no
+- **Needs updating?** Refine based on experience
+- **Promote to docs?** If it's general knowledge, move to project docs
+
+### 3. Prune Stale Entries
+
+Remove entries that:
+- Were one-time fixes
+- No longer apply (code changed)
+- Have been superseded by newer learnings
+
+### 4. Cross-Pollinate
+
+If Dev learned something TEA should know:
+- Add reference to TEA's sidecar
+- Or move to shared docs if both need it
+
+### Sidecar Health Check
+
+```bash
+echo "=== Sidecar Health ==="
+for agent in dev tea sm reviewer; do
+    SIDECAR=".claude/project/agents/${agent}-sidecar"
+    if [ -d "$SIDECAR" ]; then
+        ENTRIES=$(grep -c "^## " "$SIDECAR"/*.md 2>/dev/null | awk -F: '{sum+=$2} END {print sum}')
+        echo "$agent: $ENTRIES entries"
+    fi
+done
+```
+
+**Target:** 5-15 entries per agent. More = too noisy. Fewer = not capturing enough.
+
+---
+
+## Session Artifact Cleanup
+
+During retro, clean up accumulated session artifacts from the sprint:
+
+### 1. Preview Cleanup
+
+```bash
+# See what would be cleaned (dry-run)
+$CLAUDE_PROJECT_DIR/scripts/run.sh misc/session-cleanup.sh --dry-run --aggressive
+```
+
+Review the output. Look for:
+- Files that should NOT be cleaned (active work artifacts)
+- Unexpectedly large number of files (indicates cleanup wasn't running properly)
+
+### 2. Execute Cleanup
+
+```bash
+# Run full cleanup with aggressive mode (archives completed epic contexts)
+$CLAUDE_PROJECT_DIR/scripts/run.sh misc/session-cleanup.sh --aggressive
+```
+
+This removes:
+- Old test result files (7+ days): `test-*.log`, `test-*.md`
+- Old TEA artifacts: `tea-*.md`, `*-red-*.md`, `*-green-*.md`
+- Completed handoff files: `*-handoff*.md`, `*-handoff*.txt`
+- Old lint logs: `lint-*.log`
+- Rotates `session-log.txt` to last 1000 lines
+- Archives epic contexts for completed epics
+
+### 3. Verify Clean State
+
+```bash
+# Check remaining files
+ls -la .session/
+
+# Should only see:
+# - .gitkeep
+# - session-log.txt (rotated)
+# - agents/ directory
+# - Any active work artifacts
+```
+
+---
+
+## Follow-Up Actions
+
+After the retro:
+1. Update sprint/current-sprint.yaml with lessons learned
+2. Create stories for improvement actions
+3. Archive the retro in sprint/archive/
+4. Commit sidecar updates
+5. Verify session cleanup completed successfully
+
+## Usage
+
+```
+/retro                    # Run retro for current sprint
+/retro sprint-1          # Run retro for specific sprint
+```
+
+---
+
+**TIME TO REFLECT. WHAT SPRINT ARE WE REVIEWING?**

package/pennyfarthing-dist/commands/reviewer.md

@@ -0,0 +1,7 @@
+---
+description: Code Reviewer - Critical code review and quality enforcement
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/phase-check-start.sh "reviewer"
+```