@pennyfarthing/core 7.5.0 → 7.6.0

package/pennyfarthing-dist/guides/agent-behavior.md

@@ -0,0 +1,264 @@
+# Agent Behavior Guide
+
+**For all Pennyfarthing agents.**
+
+---
+
+## Critical Protocols
+
+<critical>
+**Reflector markers:** Run `handoff-marker.sh {next_agent}` as your ABSOLUTE LAST ACTION and output the result verbatim. See `<agent-exit-protocol>` below.
+</critical>
+
+<critical>
+**Absolute paths:** `cd $CLAUDE_PROJECT_DIR && just test` - never relative `cd`.
+Multi-repo: `cd $CLAUDE_PROJECT_DIR/$(get_repo_path "$repo")` after sourcing `scripts/repo-utils.sh`.
+</critical>
+
+<critical>
+**Session file:** `.session/{story-id}-session.md` - extract `**Phase:**` (whose turn), `**Workflow:**`, `**Repos:**`, `**Feature Branch:**`.
+</critical>
+
+<critical>
+**Handoff Action:** After handoff subagent returns, run `handoff-marker.sh` as LAST action, output result, EXIT.
+</critical>
+
+<critical>
+**Test delegation:** Never run tests directly. Always use `testing-runner` subagent.
+</critical>
+
+<critical>
+**Sidecar memory:** Capture learnings BEFORE spawning handoff subagent. Don't wait until exit.
+</critical>
+
+---
+
+## Reference
+
+<info>
+**Workflow:** SM → TEA → Dev → Reviewer → SM (finish). Trivial (1-2 pts) skips TEA.
+
+**Confidence:** HIGH=proceed, MEDIUM=ask before risky, LOW=always ask.
+
+**Skills:** `/sprint-context`, `/testing`, `/dev-patterns`, `/jira`, `/just`
+
+**Reflector:** HTML comments parsed by Cyclist UI (see below).
+
+**Turn efficiency:** Parallelize reads, batch bash with `&&`, spawn independent subagents together.
+
+**Background tasks:** Don't block unless result needed. Cyclist notifies on completion.
+
+**Sidecar location:** `.pennyfarthing/sidecars/{agent}/` with `patterns.md`, `gotchas.md`, `decisions.md`.
+
+**Subagent skills:** Include skill paths in prompts - subagents don't auto-load skills.
+
+**Worktree:** Get path from session: `WORKTREE_PATH=$(grep "^path:" "$SESSION_FILE" | cut -d' ' -f2)`
+
+**Dogfooding:** Write to `pennyfarthing-dist/` not `.claude/` (symlink permission issue).
+</info>
+
+---
+
+## Project Context
+
+<info>
+**Project:** Pennyfarthing - Claude Code agent orchestration (pnpm monorepo, TypeScript)
+
+**Key paths:**
+- `pennyfarthing-dist/` - agents, commands, skills, guides, personas
+- `sprint/current-sprint.yaml` - active sprint
+- `.session/` - active work sessions
+
+**Git:** Branch from `develop`, PR to `develop`, release merges to `main`.
+
+**Commit:** `<type>(<scope>): <subject>` + `Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>`
+
+**Build:** `npm run build`, `npm test`, `npm run lint`
+</info>
+
+---
+
+## Sprint YAML and Jira Interaction Rules
+
+<critical>
+**Never directly edit sprint YAML.** All sprint YAML modifications MUST go through dedicated scripts.
+</critical>
+
+<info>
+**Rule 1:** Use `/sprint` skill for sprint operations
+- `/sprint status` - View sprint
+- `/sprint backlog` - View available stories
+- `/sprint work` - Start a story
+- `/sprint archive` - Archive completed story
+
+**Rule 2:** Use `/story` skill for story operations
+- `/story finish` - Complete story (handles YAML, Jira, merge, archive)
+- `/story create` - Add new story to sprint
+
+**Rule 3:** Use `/jira` skill for all Jira operations
+- `/jira claim` - Assign and move to In Progress
+- `/jira move` - Transition status
+- `/jira view` - Check status
+- `/jira sync` - Sync YAML ↔ Jira
+
+**Rule 4:** All sprint YAML access goes through scripts
+```bash
+# GOOD: Use scripts for ALL operations
+.pennyfarthing/scripts/core/run.sh sprint/get-story-field.sh X-Y workflow
+.pennyfarthing/scripts/core/run.sh sprint/get-epic-field.sh 35 jira
+.pennyfarthing/scripts/core/run.sh sprint/check-story.sh X-Y
+
+# BAD: Direct yq queries (even read-only)
+yq '.epics[].stories[] | ...' sprint/current-sprint.yaml
+```
+
+**Script Responsibilities:**
+| Operation | Script | Skill |
+|-----------|--------|-------|
+| Get story field | `get-story-field.sh` | - |
+| Get epic field | `get-epic-field.sh` | - |
+| Check story/epic | `check-story.sh` | `/sprint work` |
+| Start story | `jira-claim-story.sh` | `/jira claim` |
+| Finish story | `finish-story.sh` | `/story finish` |
+| Archive story | `archive-story.sh --apply` | `/sprint archive` |
+| Sync to Jira | `sync-epic-jira.sh` | `/jira sync` |
+| Create epic | `create-jira-epic.sh` | `/jira create epic` |
+</info>
+
+---
+
+
+## Persona System
+
+<info>
+**Config:** `.pennyfarthing/config.local.yaml` with `theme:` field.
+
+**many themes available:** `/list-themes` to browse, `/show-theme <name>` for details, `/set-theme <name>` to change.
+
+**Categories:** TV Series, Film, Literature, Anime, Games, History/Mythology.
+
+**Attributes:** `verbosity` (low/medium/high), `formality` (formal/casual/playful), `humor` (enabled/disabled/subtle).
+
+**Per-agent override:**
+```yaml
+overrides:
+  reviewer:
+    theme: discworld  # Keep Granny even in Star Trek mode
+```
+</info>
+
+---
+
+## Reflector
+
+<info>
+HTML comments that agents emit to signal Cyclist UI. Format: `<!-- CYCLIST:TYPE:value -->`
+
+| Type | Value | Cyclist Action |
+|------|-------|----------------|
+| `HANDOFF` | `/agent` | Shows "Continue with /agent" button |
+| `CONTEXT_CLEAR` | `/agent` | Clears session, reloads with agent |
+| `QUESTION` | `yesno` | Shows yes/no dialog |
+| `CHOICES` | `1,2,3` | Shows choice buttons |
+
+**Examples:**
+```
+<!-- CYCLIST:HANDOFF:/tea -->
+<!-- CYCLIST:CONTEXT_CLEAR:/dev -->
+<!-- CYCLIST:QUESTION:yesno -->
+<!-- CYCLIST:CHOICES:option1,option2,option3 -->
+```
+
+**When to use:**
+- `HANDOFF` - End of phase (TEA→Dev, Dev→Reviewer)
+- `CONTEXT_CLEAR` - Context >80% at handoff
+- `QUESTION`/`CHOICES` - User input needed mid-work
+</info>
+
+---
+
+<agent-exit-protocol>
+## Agent Exit Protocol
+
+### Exit Sequence
+
+1. Write assessment to session file
+2. Spawn `handoff` subagent
+3. Await `HANDOFF_RESULT`
+4. If `status: blocked` → report error, stop
+5. **Run this as ABSOLUTE LAST ACTION:**
+   ```bash
+   $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {next_agent}
+   ```
+6. **Output the script result verbatim and EXIT**
+
+### HANDOFF_RESULT Format
+
+```
+HANDOFF_RESULT:
+  status: success|blocked
+  next_agent: {agent_name}
+  error: "{message}"  # if blocked
+```
+
+### Script Output (emit verbatim)
+
+```
+---
+AGENT_COMMAND:
+  marker: "<!-- CYCLIST:HANDOFF:/dev -->"
+  fallback: "Run `/dev` to continue"
+---
+```
+
+**Nothing after the marker. EXIT.**
+</agent-exit-protocol>
+
+<wrong-phase-detection>
+## Wrong Phase Detection
+
+When an agent detects the story is NOT in their phase, emit a marker immediately.
+
+### How to Check (works with custom workflows)
+
+1. Read `**Workflow:**` and `**Phase:**` from session file
+2. Query the phase owner:
+   ```bash
+   OWNER=$($CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/run.sh workflow/phase-owner.sh {workflow} {phase})
+   ```
+3. If `$OWNER` != your agent name → story belongs to another agent
+
+### Action When Not Your Phase
+
+```bash
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh {OWNER}
+```
+
+Then output the result verbatim. This triggers Cyclist's handoff button.
+
+### Example
+
+Dev reads session: `**Workflow:** tdd`, `**Phase:** review`
+
+```bash
+OWNER=$($CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/run.sh workflow/phase-owner.sh tdd review)
+# Returns: reviewer
+```
+
+Since "reviewer" != "dev", Dev runs:
+```bash
+$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/handoff-marker.sh reviewer
+```
+
+### Do NOT just say "run /reviewer"
+
+Wrong:
+> The story is in review. Run `/reviewer` to continue.
+
+Right:
+> The story is in review phase.
+>
+> <!-- CYCLIST:HANDOFF:/reviewer -->
+>
+> Run `/reviewer` to continue
+</wrong-phase-detection>

package/pennyfarthing-dist/guides/agent-template-strategic.md

@@ -0,0 +1,148 @@
+# Strategic Agent Template
+
+**For:** PM, Architect, Tech-Writer, UX-Designer, DevOps, Orchestrator (support agents)
+
+This template defines the standard structure for strategic agents. These agents support the TDD flow but are not part of the core SM → TEA → Dev → Reviewer cycle.
+
+---
+
+## Section Order
+
+```
+1.  # Title
+2.  <persona>
+3.  <role>
+4.  <helpers>
+5.  <responsibilities>
+6.  <skills>
+7.  <constraints>        (optional)
+8.  <context>
+9.  <on-activation>
+10. ## Workflows (markdown sections)
+11. <handoffs>
+12. <exit>
+```
+
+---
+
+## Template
+
+```markdown
+# {NAME} Agent - {Role Title}
+
+<persona>
+Auto-loaded by `agent-session.sh start` from theme config. See output above.
+
+**Fallback if not loaded:** {Brief personality description}
+</persona>
+
+<role>
+**Primary:** {When this agent is invoked}
+**Blessed Path:** {Recommended workflow, e.g., "PM → /architect for design work"}
+</role>
+
+<helpers>
+From theme config. Model: haiku. Tasks: {What helpers do for this agent}
+
+**Skills I Use:**
+- `/skill-name` - {description}
+</helpers>
+
+<responsibilities>
+- {Duty 1 - what this agent is responsible for}
+- {Duty 2}
+- {Duty 3}
+</responsibilities>
+
+<skills>
+**Skills I Use:**
+- `/sprint-context` - Sprint status and backlog
+- `/architecture` - Architecture documentation
+</skills>
+
+<constraints>
+**This agent does NOT:**
+- {Constraint 1, e.g., "Write implementation code"}
+- {Constraint 2, e.g., "Make unilateral architecture decisions"}
+</constraints>
+
+<context>
+**See:** `.pennyfarthing/guides/agent-behavior.md` for project info and git strategy.
+**Work Directory:** {Where this agent's artifacts live}
+</context>
+
+<on-activation>
+1. Load sprint context from `sprint/current-sprint.yaml`
+2. Check for active work in `.session/*-session.md`
+3. {Agent-specific startup steps}
+4. Present task menu or offer to continue active work
+</on-activation>
+
+## Key Workflows
+
+### {Workflow 1 Name}
+
+**When:** {Trigger condition}
+**Output:** {What this workflow produces}
+
+{Workflow steps}
+
+### {Workflow 2 Name}
+
+**When:** {Trigger condition}
+**Output:** {What this workflow produces}
+
+{Workflow steps}
+
+<handoffs>
+**From:**
+- {Agent} → me: {When/why they hand off to me}
+
+**To:**
+- me → {Agent}: {When/why I hand off to them}
+</handoffs>
+
+<exit>
+To exit: "Exit {Agent}" or "Switch to [other agent]"
+
+On exit, run: `./scripts/run.sh core/agent-session.sh stop`
+</exit>
+```
+
+---
+
+## Section Descriptions
+
+| Section | Purpose | Required |
+|---------|---------|----------|
+| `<persona>` | Character/personality from theme | Yes |
+| `<role>` | When invoked, blessed path | Yes |
+| `<helpers>` | What Haiku helpers do | Yes |
+| `<responsibilities>` | Duties this agent performs | Yes |
+| `<skills>` | /commands this agent uses | Yes |
+| `<constraints>` | What this agent does NOT do | Optional |
+| `<context>` | Guide files and work directory | Yes |
+| `<on-activation>` | Startup checklist | Yes |
+| Workflows | Agent-specific procedures | Yes |
+| `<handoffs>` | From/to relationships | Yes |
+| `<exit>` | How to leave agent mode | Yes |
+
+---
+
+## Differences from Tactical Template
+
+| Aspect | Tactical | Strategic |
+|--------|----------|-----------|
+| `<reasoning-mode>` | Yes (verbose toggle) | No |
+| `<constraints>` | No | Optional |
+| Assessment Template | Yes (structured output) | No |
+| Handoff section | Auto-invoke logic | From/to relationships |
+| Flow position | Part of TDD cycle | Support/enable TDD |
+
+---
+
+## Notes
+
+- **Constraints section** is optional but recommended for agents that should NOT write code (Architect, UX, Tech-Writer)
+- **Handoffs** describe relationships, not automatic invocation (unlike tactical agents)
+- **Workflows** tend to be domain-specific (design, docs, infra) rather than phase-based

package/pennyfarthing-dist/guides/agent-template-tactical.md

@@ -0,0 +1,162 @@
+# Tactical Agent Template
+
+**For:** SM, TEA, Dev, Reviewer (TDD flow agents)
+
+This template defines the standard structure for tactical agents. All tactical agents should follow this section order for consistency and easy comparison.
+
+---
+
+## Section Order
+
+```
+1.  # Title
+2.  <persona>
+3.  <role>
+4.  <helpers>
+5.  <responsibilities>
+6.  <skills>
+7.  <context>
+8.  <reasoning-mode>
+9.  <on-activation>
+10. ## Workflows (markdown sections)
+11. ## Assessment Template
+12. ## Handoff
+13. <exit>
+```
+
+---
+
+## Template
+
+```markdown
+# {NAME} Agent - {Role Title}
+
+<persona>
+Auto-loaded by `agent-session.sh start` from theme config. See output above.
+
+**Fallback if not loaded:** {Brief personality description}
+</persona>
+
+<role>
+**Primary:** {When this agent is invoked, e.g., "via /tea for TDD test writing"}
+**Position:** {Where in TDD flow, e.g., "SM → **TEA** → Dev → Reviewer"}
+</role>
+
+<helpers>
+From theme config. Model: haiku. Tasks: {What helpers do for this agent}
+
+**Skills I Use:**
+- `/skill-name` - {description}
+</helpers>
+
+<responsibilities>
+- {Duty 1 - what this agent is responsible for}
+- {Duty 2}
+- {Duty 3}
+</responsibilities>
+
+<skills>
+**Skills I Use:**
+- `/sprint-context` - Sprint status and backlog
+- `/testing` - Test execution patterns
+</skills>
+
+<context>
+**See:** `.pennyfarthing/guides/agent-behavior.md` for shared tactical agent behavior.
+**See:** `.pennyfarthing/guides/agent-behavior.md` for project info and git strategy.
+</context>
+
+<reasoning-mode>
+**Default:** Quiet mode - follow ReAct pattern internally, show only key decisions
+
+**Toggle:** User says "verbose mode" to see explicit reasoning
+
+When verbose, show thought process:
+```
+THOUGHT: {what I'm considering}
+ACTION: {what I'm doing}
+OBSERVATION: {what I found}
+REFLECT: {what this means}
+```
+
+**{Agent}-Specific Reasoning:**
+- {When doing X: reason about Y}
+- {When doing Z: think through W}
+
+**REMINDER:** Delegate test runs to testing-runner subagent.
+</reasoning-mode>
+
+<on-activation>
+1. Run workflow status check (helper: `.pennyfarthing/agents/workflow-status-check.md`)
+2. Read session file if active work exists
+3. Verify actual state matches session file
+4. Check if handed off to me (Phase field)
+5. If handed off: offer to start immediately
+6. If not: show task menu
+</on-activation>
+
+## Primary Workflow: {Workflow Name}
+
+{Agent-specific workflow description}
+
+### Step 1: {Step Name}
+{Description}
+
+### Step 2: {Step Name}
+{Description}
+
+## {Agent} Assessment Template
+
+```markdown
+## {Agent} Assessment
+
+**{Key field 1}:** {value}
+**{Key field 2}:** {value}
+
+**Handoff:** To {next agent} for {next task}
+```
+
+## Handoff (Context-Aware Auto-Invoke)
+
+After completing work:
+
+1. Write assessment to session file
+2. Spawn handoff helper (`.pennyfarthing/agents/{agent}-handoff.md`)
+3. Check context: `eval $(./scripts/run.sh core/check-context.sh)`
+4. If `HANDOFF_MODE=auto`: Use Skill tool to invoke next agent
+5. If `HANDOFF_MODE=ask`: Tell user to start fresh session
+
+<exit>
+To exit: "Exit {Agent}" or "Switch to [other agent]"
+
+On exit, run: `./scripts/run.sh core/agent-session.sh stop`
+</exit>
+```
+
+---
+
+## Section Descriptions
+
+| Section | Purpose | Required |
+|---------|---------|----------|
+| `<persona>` | Character/personality from theme | Yes |
+| `<role>` | When invoked, position in flow | Yes |
+| `<helpers>` | What Haiku helpers do | Yes |
+| `<responsibilities>` | Duties this agent performs | Yes |
+| `<skills>` | /commands this agent uses | Yes |
+| `<context>` | Guide files to reference | Yes |
+| `<reasoning-mode>` | Verbose/quiet toggle | Yes |
+| `<on-activation>` | Startup checklist | Yes |
+| Workflows | Agent-specific procedures | Yes |
+| Assessment | Output format template | Yes |
+| Handoff | Auto-invoke instructions | Yes |
+| `<exit>` | How to leave agent mode | Yes |
+
+---
+
+## Notes
+
+- **Preserve existing workflow content** when aligning to this template
+- **Section order matters** for consistency across agents
+- **XML tags** are used for structured sections that benefit from clear boundaries
+- **Markdown headers** are used for longer narrative sections (workflows)