@pennyfarthing/core 7.4.1 → 7.5.0

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

@@ -1,238 +0,0 @@
-# Agent Behavior Guide
-
-**For all Pennyfarthing agents.**
-
----
-
-## Critical Protocols
-
-<critical>
-**Reflector markers:** Subagent output is NOT visible to Cyclist. After handoff subagent returns `AGENT_COMMAND`, output the `marker` string verbatim. See `<agent-command-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:** When `handoff` returns `AGENT_COMMAND`, output `marker` verbatim then `fallback`. Don't ask permission.
-</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-command-protocol>
-## AGENT_COMMAND Protocol
-
-<critical>
-**Subagent output is NOT visible to Cyclist.** Tool results are not parsed for markers.
-Handoff subagents return an `AGENT_COMMAND` block with a pre-rendered `marker` string.
-The **calling agent** outputs the `marker` verbatim - no parsing or mapping required.
-</critical>
-
-### How It Works
-
-1. Agent writes assessment to session file FIRST
-2. Agent spawns `handoff` subagent
-3. Subagent runs `handoff-marker.sh {next-agent}` to generate `AGENT_COMMAND` block
-4. Subagent returns the block with pre-rendered `marker` string
-5. **Agent outputs `marker` verbatim, then outputs `fallback` message**
-
-**Single Source of Truth:** The `handoff-marker.sh` script is the authoritative source for marker format. It handles environment detection (IS_CYCLIST, USE_TIREPUMP) automatically.
-
-### AGENT_COMMAND Format
-
-```
----
-AGENT_COMMAND:
-  marker: "{PRE_RENDERED_MARKER_STRING}"
-  fallback: "Run `/{agent}` to continue"
----
-```
-
-The `marker` field contains the exact string to output (or empty string if no marker needed).
-The `fallback` field contains human-readable instructions.
-
-### Agent Action
-
-**Simple rule: Output `marker` then `fallback`. That's it.**
-
-1. If `error: true` → Report the `fallback` message as an error
-2. Otherwise → Output `marker` verbatim (if non-empty), then output `fallback`
-
-### Example
-
-Subagent returns:
-```
----
-AGENT_COMMAND:
-  marker: "<!-- CYCLIST:HANDOFF:/dev -->"
-  fallback: "Run `/dev` to continue"
----
-```
-
-Agent outputs in their direct text (not a tool call):
-```
-<!-- CYCLIST:HANDOFF:/dev -->
-
-Run `/dev` to continue
-```
-
-**CRITICAL:** The marker MUST appear in the agent's direct text output, not in a tool result.
-</agent-command-protocol>

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

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

@@ -1,162 +0,0 @@
-# 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)