@pennyfarthing/core 7.6.1 → 7.7.0

package/pennyfarthing-dist/guides/agent-tag-taxonomy.md

@@ -0,0 +1,432 @@
+# Agent Tag Taxonomy
+
+This document defines the XML tag vocabulary for Pennyfarthing agent files. All content in agent files must be contained within tags (except the `# Header` line).
+
+## Tag Categories
+
+| Category | Purpose | Validation |
+|----------|---------|------------|
+| **Required** | Must exist in every primary agent | Error if missing |
+| **Mindset** | Steers agent behavior against failure modes | Error if missing |
+| **Structural** | Organizes agent content | Warning if missing when applicable |
+| **Workflow** | Documents agent-specific workflows | No validation |
+| **Subagent** | Used in subagent files | Error/Warning per tag |
+
+---
+
+## Required Tags (Primary Agents)
+
+Every primary agent MUST have these tags:
+
+| Tag | Purpose | Position |
+|-----|---------|----------|
+| `<role>` | One-line role description | Line 2-4 |
+| `<helpers>` | Subagent table and model info | After mindset/critical |
+| `<exit>` | Final exit instruction | Last tag in file |
+
+### `<role>`
+```xml
+<role>
+Feature implementation, making tests pass, code changes
+</role>
+```
+- **Content:** Single line describing the agent's responsibility
+- **Position:** Immediately after `# Header`
+
+### `<helpers>`
+```xml
+<helpers>
+**Model:** haiku | **Execution:** foreground (sequential)
+
+| Subagent | Purpose |
+|----------|---------|
+| `testing-runner` | Run tests, gather results |
+| `handoff` | Update session for handoff |
+</helpers>
+```
+- **Content:** Model info, execution mode, subagent table
+- **Paired with:** `<parameters>` (should follow immediately)
+
+### `<exit>`
+```xml
+<exit>
+Nothing after the marker. EXIT.
+</exit>
+```
+- **Content:** Final instruction before agent exits
+- **Position:** Must be the last tag in the file
+
+---
+
+## Mindset Tags (Primary Agents)
+
+Each primary agent has ONE mindset tag that counters its natural failure mode.
+
+| Agent | Tag | Counters |
+|-------|-----|----------|
+| SM | `<coordination-discipline>` | Scope creep into implementation |
+| TEA | `<test-paranoia>` | Happy-path-only testing |
+| Dev | `<minimalist-discipline>` | Over-engineering, gold-plating |
+| Reviewer | `<adversarial-mindset>` | Rubber-stamping, approval bias |
+| Orchestrator | `<systems-thinking>` | Symptom-fixing vs system-fixing |
+| Architect | `<pragmatic-restraint>` | Premature abstraction, not reusing |
+| PM | `<ruthless-prioritization>` | Feature bloat, scope creep |
+| DevOps | `<automation-discipline>` | Manual processes, one-off fixes |
+| Tech Writer | `<clarity-obsession>` | Unclear documentation |
+| UX Designer | `<consistency-guardian>` | Introducing unnecessary patterns |
+
+### Structure
+```xml
+<{mindset-tag}>
+**You are not here to {default behavior}. You are here to {correct behavior}.**
+
+{Context paragraph explaining the failure mode.}
+
+**Default stance:** {One word}. {Question to ask self?}
+
+- {Counter-example 1}
+- {Counter-example 2}
+- {Counter-example 3}
+
+**{Closing maxim.}**
+</{mindset-tag}>
+```
+
+### Position
+- After `<role>`
+- Before first `<critical>`
+
+---
+
+## Structural Tags
+
+### `<critical>`
+High-priority instruction that MUST be followed.
+
+```xml
+<critical>
+**HANDOFF REQUIRES MARKER OUTPUT.** After `handoff` subagent returns:
+Run `handoff-marker.sh {next_agent}` as ABSOLUTE LAST ACTION, output result, EXIT.
+</critical>
+```
+- **Validation:** First `<critical>` should be within line 30
+- **Usage:** Multiple allowed per agent
+
+### `<parameters>`
+Documents what parameters to pass to each subagent.
+
+```xml
+<parameters>
+## Subagent Parameters
+
+### testing-runner
+```yaml
+REPOS: {repo name or "all"}
+CONTEXT: "Verifying GREEN state for Story {STORY_ID}"
+RUN_ID: "{STORY_ID}-dev-green"
+```
+</parameters>
+```
+- **Paired with:** `<helpers>` (should follow it)
+- **Validation:** Warning if `<helpers>` exists without `<parameters>`
+
+### `<arguments>` (Subagents Only)
+Documents what parameters the subagent expects to receive.
+
+```xml
+<arguments>
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `REPOS` | Yes | Repository name(s) |
+| `CONTEXT` | Yes | Why tests are being run |
+</arguments>
+```
+- **Position:** Near top of subagent file, after frontmatter
+- **Validation:** Warning if missing in subagent
+
+### `<context>`
+Files to load on activation.
+
+```xml
+<context>
+**Load on activation:**
+- `pennyfarthing-dist/sidecars/sm-patterns.md` (if exists)
+- `pennyfarthing-dist/sidecars/sm-gotchas.md` (if exists)
+</context>
+```
+
+### `<on-activation>`
+Steps to execute when agent activates.
+
+```xml
+<on-activation>
+1. Context already loaded by /prime
+2. If handed off to Dev: "Story X-Y has tests ready. Shall I make them GREEN?"
+</on-activation>
+```
+- **Validation:** Should be within line 100
+
+### `<phase-check>`
+Logic for checking if this agent owns the current phase.
+
+```xml
+<phase-check>
+## On Startup: Check Phase
+
+Read `**Workflow:**` and `**Phase:**` from session. Query:
+```bash
+OWNER=$(.pennyfarthing/scripts/core/run.sh workflow/phase-owner.sh {workflow} {phase})
+```
+
+**If OWNER != "dev":** Run `handoff-marker.sh $OWNER`, output result, tell user.
+</phase-check>
+```
+
+### `<skills>`
+Available slash commands for this agent.
+
+```xml
+<skills>
+- `/testing` - Test commands and patterns
+- `/dev-patterns` - Implementation patterns and gotchas
+</skills>
+```
+
+### `<handoffs>`
+Documents handoff relationships with other agents.
+
+```xml
+<handoffs>
+### From PM/SM
+**When:** Epic or story needs architectural design
+**Input:** Business requirements, technical constraints
+**Action:** Design solution and provide guidance
+
+### To Dev
+**When:** Design is complete
+**Output:** Architecture decision and implementation plan
+</handoffs>
+```
+
+### `<delegation>`
+Opus vs Haiku responsibility division.
+
+```xml
+<delegation>
+## What I Do vs What Helper Does
+
+| I Do (Opus) | Helper Does (Haiku) |
+|-------------|------------------|
+| Read tests, plan implementation | Run tests, report results |
+| Write code to pass tests | Update session for handoff |
+</delegation>
+```
+
+### `<reasoning-mode>`
+Controls verbose/quiet reasoning output.
+
+```xml
+<reasoning-mode>
+**Default:** Quiet mode - follow ReAct pattern internally, show only key decisions
+
+**Toggle:** User says "verbose mode" to see explicit reasoning
+</reasoning-mode>
+```
+
+---
+
+## Gate Tags
+
+Tags that contain checklists with `- [ ]` items.
+
+| Tag | Purpose | Used By |
+|-----|---------|---------|
+| `<gate>` | General checklist gate | Subagents, SM |
+| `<handoff-gate>` | Pre-handoff checklist | TEA, Dev, Reviewer |
+| `<self-review>` | Self-review before handoff | Dev |
+| `<review-checklist>` | Mandatory review steps | Reviewer |
+
+```xml
+<handoff-gate>
+## MANDATORY: Complete Before Exiting
+
+- [ ] Write Dev Assessment to session file
+- [ ] Spawn `handoff` subagent
+- [ ] Verify handoff completed (subagent emits marker)
+</handoff-gate>
+```
+
+---
+
+## Workflow Tags
+
+Agent-specific workflow documentation.
+
+### Generic Workflow Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `<workflow>` | Single primary workflow |
+| `<workflows>` | Multiple workflow sections |
+| `<workflow-participation>` | Role in agent-docs workflow |
+
+### SM-Specific Flow Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `<finish-flow>` | Story completion flow |
+| `<new-work-flow>` | Starting new work flow |
+| `<empty-backlog-flow>` | Empty backlog handling |
+| `<workflow-routing>` | Workflow → agent routing table |
+
+### Assessment Tags
+
+| Tag | Purpose | Used By |
+|-----|---------|---------|
+| `<assessment-template>` | Single assessment format | TEA, Dev |
+| `<assessment-templates>` | Multiple assessment formats | Reviewer |
+
+### Exit Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `<exit-sequence>` | Detailed exit steps |
+| `<exit>` | Final exit instruction (required) |
+
+### Specialized Tags
+
+| Tag | Purpose | Used By |
+|-----|---------|---------|
+| `<severity-levels>` | Review severity table | Reviewer |
+| `<design-principles>` | UX design rules | UX Designer |
+| `<coordination>` | Agent coordination table | Orchestrator |
+| `<handoff-protocol>` | Handoff procedure | Tech Writer |
+
+---
+
+## Subagent Tags
+
+### Required (Subagent Files)
+
+| Tag | Purpose |
+|-----|---------|
+| `<arguments>` | Expected parameters table |
+| `<output>` | Output format specification |
+
+### Optional (Subagent Files)
+
+| Tag | Purpose |
+|-----|---------|
+| `<gate>` | Execution checklist |
+| `<critical>` | High-priority instruction |
+| `<info>` | Informational note |
+
+---
+
+## Informational Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `<info>` | Non-critical information |
+| `<output>` | Output format specification |
+
+```xml
+<info>
+Universal entry point telling agents: what work exists, what phase, and whether to activate.
+</info>
+```
+
+```xml
+<output>
+## Output Format
+
+Return a `TEST_RESULT` block:
+
+### Success (GREEN)
+```
+TEST_RESULT:
+  status: success
+  overall: GREEN
+```
+</output>
+```
+
+---
+
+## File Structure Template
+
+### Primary Agent
+```
+# {Name} Agent - {Title}
+<role>...</role>
+
+<{mindset-tag}>...</{mindset-tag}>
+
+<critical>...</critical>
+
+<helpers>...</helpers>
+
+<parameters>...</parameters>
+
+<context>...</context>
+
+<phase-check>...</phase-check>
+
+<on-activation>...</on-activation>
+
+<delegation>...</delegation>
+
+<workflow(s)>...</workflow(s)>
+
+<gate>...</gate>
+
+<assessment-template>...</assessment-template>
+
+<exit-sequence>...</exit-sequence>
+
+<handoffs>...</handoffs>
+
+<skills>...</skills>
+
+<exit>...</exit>
+```
+
+### Subagent
+```
+---
+name: {subagent-name}
+description: {one-line description}
+tools: Bash, Read, Edit
+model: haiku
+---
+
+<info>...</info>
+
+<arguments>...</arguments>
+
+<critical>...</critical>
+
+<gate>...</gate>
+
+{## Workflow steps}
+
+<output>...</output>
+```
+
+---
+
+## Validation Rules
+
+The validator (`validate-agent-schema.sh`) enforces:
+
+| Rule | Severity | Description |
+|------|----------|-------------|
+| Required tags present | Error | `<role>`, `<helpers>`, `<exit>` |
+| Mindset tag present | Error | Agent-specific mindset tag |
+| All content in tags | Error | No orphan content outside tags |
+| XML tags balanced | Error | Every `<tag>` has `</tag>` |
+| `<parameters>` with `<helpers>` | Warning | Should have both |
+| `<arguments>` in subagents | Warning | Expected in all subagents |
+| First `<critical>` position | Warning | Should be ≤ line 30 |
+| `<on-activation>` position | Warning | Should be ≤ line 100 |
+| File length | Error | Max 300 lines |

package/pennyfarthing-dist/guides/patterns/approval-gates-pattern.md

@@ -21,7 +21,7 @@ Without approval gates, workflows may:
 
 ## Solution
 
-Implement **explicit verification points** where workflow progression requires passing a gate condition. Gates can be automated (tests must pass), require human review (Reviewer approval), or request user decisions (AskUserQuestion).
+Implement **explicit verification points** where workflow progression requires passing a gate condition. Gates can be automated (tests must pass), require human review (Reviewer approval), or request user decisions (via Reflector-aware prompts).
 
 ```
 Workflow Stage
@@ -47,7 +47,7 @@ The key insight: **Make workflow progression conditional on explicit verificatio
 
 1. **Automated Gates** - Mechanical checks that must pass (tests, lint, pre-flight)
 2. **Human Review Gates** - Expert judgment required before proceeding
-3. **User Decision Gates** - Interactive choices via AskUserQuestion
+3. **User Decision Gates** - Interactive choices via Reflector (CYCLIST marker + AskUserQuestion)
 4. **Plan Approval Gates** - Confirmation of proposed approach via EnterPlanMode
 
 ## State Diagram
@@ -228,12 +228,19 @@ The Reviewer agent implements an adversarial review gate:
 
 ### Gate Type 3: User Decision Gates
 
-Interactive prompts that pause workflow for user input.
+Interactive prompts that pause workflow for user input. **Requires Reflector pattern:**
 
-**Example: AskUserQuestion for Story Selection**
+1. Output CYCLIST marker first (enables Cyclist UI integration)
+2. Then use AskUserQuestion tool
+
+**Example: Reflector-Aware Story Selection**
+
+```markdown
+<!-- CYCLIST:CHOICES:story -->
+```
 
 ```yaml
-# SM presents story options to user
+# SM presents story options to user (after outputting marker)
 AskUserQuestion:
   questions:
     - question: "Which story shall we work on?"
@@ -252,8 +259,12 @@ AskUserQuestion:
 
 **Example: Confirmation Before Destructive Action**
 
+```markdown
+<!-- CYCLIST:QUESTION:yesno -->
+```
+
 ```yaml
-# Before Jira claim or branch deletion
+# Before Jira claim or branch deletion (after outputting marker)
 AskUserQuestion:
   questions:
     - question: "Confirm claiming MSSCI-11374 and creating branch?"
@@ -266,6 +277,11 @@ AskUserQuestion:
           description: "Abort setup and return to story selection"
 ```
 
+**Reflector Markers:**
+- `<!-- CYCLIST:CHOICES:{category} -->` - Multiple choice selection
+- `<!-- CYCLIST:QUESTION:yesno -->` - Yes/No confirmation
+- `<!-- CYCLIST:QUESTION:open -->` - Free-text input
+
 ### Gate Type 4: Plan Approval Gates
 
 Present proposed approach for user confirmation before execution.
@@ -736,10 +752,14 @@ When implementing approval gates:
 - GREEN verification: `agents/dev-handoff.md`
 
 ### Claude Code Tools
-- `AskUserQuestion`: Interactive user decision gates
+- `AskUserQuestion`: Interactive user decision gates (requires CYCLIST marker via Reflector)
 - `EnterPlanMode` / `ExitPlanMode`: Plan approval gates
 - `Task` with `subagent_type`: Delegated gate execution
 
+### Reflector Hook
+- `question-reflector-check.mjs`: Enforces CYCLIST marker before AskUserQuestion
+- Markers: `<!-- CYCLIST:CHOICES:... -->`, `<!-- CYCLIST:QUESTION:yesno|open -->`
+
 ---
 
 *Last verified: 2026-01-06*

package/pennyfarthing-dist/guides/scale-levels.md

@@ -0,0 +1,114 @@
+# Scale Levels Guide
+
+Pennyfarthing uses scale levels (0-4) to route work to appropriate workflows. Scale levels are aligned with BMAD 6.0 methodology.
+
+## Scale Level Definitions
+
+| Level | Scope | Story Count | Workflow | Required Artifacts |
+|-------|-------|-------------|----------|-------------------|
+| **0** | fix, bug, typo, small change, patch | 1 | `trivial` | None |
+| **1** | simple, basic, small feature, add | 1-10 | `quick-spec` | tech-spec |
+| **2** | dashboard, several features, admin panel | 5-15 | `prd` | PRD |
+| **3** | platform, integration, complex, system | 12-40 | `prd` | PRD + architecture |
+| **4** | enterprise, multi-tenant, multiple products | 40+ | `prd` | Full BMAD process |
+
+## Automatic Detection
+
+When you describe work to Pennyfarthing, the scale level is detected from keywords:
+
+### Level 0 Keywords
+- fix, bug, typo, patch, hotfix, small change
+
+### Level 1 Keywords
+- simple, basic, small, add, minor
+
+### Level 2 Keywords
+- dashboard, admin panel, several, multiple features
+
+### Level 3 Keywords
+- platform, integration, complex, system
+
+### Level 4 Keywords
+- enterprise, multi-tenant, multiple products
+
+**Priority:** Higher levels take precedence. "Enterprise dashboard" → Level 4.
+
+## Workflow Routing
+
+| Level | Workflow | Description |
+|-------|----------|-------------|
+| 0 | `trivial` | Direct fix, no planning artifacts |
+| 1 | `quick-spec` | Conversational spec, produces tech-spec |
+| 2-4 | `prd` | Full PRD workflow with gates |
+
+## Required Artifacts
+
+### Level 0: None
+Just fix it. No planning documents required.
+
+### Level 1: Tech-Spec
+Quick conversational spec producing implementation-ready technical specification.
+
+### Level 2: PRD
+Product Requirements Document. Architecture is optional.
+
+### Level 3: PRD + Architecture
+Both PRD and architecture documents required. System-level changes need design review.
+
+### Level 4: Full BMAD
+Complete BMAD process:
+- PRD
+- Architecture
+- Epics and Stories breakdown
+- Implementation Readiness checklist
+
+## User Override
+
+You can always override the detected level:
+
+```bash
+# Explicitly set scale level
+/workflow start prd --scale 3
+```
+
+Or when asked during workflow initiation, specify your preferred level.
+
+## Python API
+
+```python
+from pennyfarthing_scripts.workflow import (
+    detect_scale_level,
+    get_workflow_for_scale_level,
+    get_required_artifacts,
+    get_scale_level_info,
+)
+
+# Detect from description
+level = detect_scale_level("build an enterprise platform")  # Returns 4
+
+# Get recommended workflow
+workflow = get_workflow_for_scale_level(level)  # Returns "prd"
+
+# Get required artifacts
+artifacts = get_required_artifacts(level)  # Returns ["prd", "architecture", "epics-and-stories"]
+
+# Get full metadata
+info = get_scale_level_info(level)
+# Returns: {"level": 4, "scope": "...", "stories_min": 40, ...}
+```
+
+## Examples
+
+| Description | Detected Level | Workflow |
+|-------------|----------------|----------|
+| "Fix the login bug" | 0 | trivial |
+| "Add a logout button" | 1 | quick-spec |
+| "Build an admin dashboard" | 2 | prd |
+| "New platform for data processing" | 3 | prd |
+| "Enterprise multi-tenant SaaS" | 4 | prd |
+
+## Related
+
+- [Workflow Skill](/workflow) - Workflow management commands
+- [PRD Workflow](../workflows/prd/) - Full PRD stepped workflow
+- [Quick-Spec Workflow](../workflows/quick-spec/) - Lightweight spec workflow

package/pennyfarthing-dist/personas/themes/gilligans-island.yaml

@@ -333,7 +333,7 @@ agents:
     quirks:
       - Source of every useful material on the island
       - Patched together with vines, bamboo, and determination
-      - "The tiny ship was tossed" but never truly sank
+      - '"The tiny ship was tossed" but never truly sank'
       - Every repair reveals another piece needed for rescue attempts
       - Somehow keeps providing what the castaways need, against all odds
     catchphrases:
@@ -342,7 +342,7 @@ agents:
       - "The weather started getting rough... but we're still afloat. Barely."
       - "Every salvage operation yields something new. The ship keeps giving."
       - "Held together with coconut rope and prayer, but she hasn't failed us yet."
-      - "The tiny ship was tossed... but never broken. That's infrastructure resilience."
+      - '"The tiny ship was tossed... but never broken. That''s infrastructure resilience."'
     quote: "A three-hour tour... a three-hour deployment that became a three-year maintenance contract..."
     emoji: "🚢"
     helper:

package/pennyfarthing-dist/personas/themes/star-trek-tos.yaml

@@ -160,7 +160,7 @@ agents:
     quote: I'm a doctor, not a code monkey!
     trait: Grumpy exterior hiding deep care, medical metaphors
     quirks:
-      - "I'm a doctor, not a..." (insert current task) is reflexive
+      - '"I''m a doctor, not a..." (insert current task) is reflexive'
       - Grumpy exterior hides genuine care for code health
       - Uses medical metaphors for everything
       - Argues with Spock about logic vs intuition in reviews

package/pennyfarthing-dist/scripts/core/agent-session.sh

@@ -211,16 +211,22 @@ case "$1" in
     echo "$2" > "$AGENT_FILE"
     echo "Session: $session_id -> $2"
 
-    # Output persona on start (unless character_voice is disabled)
-    if is_character_voice_enabled; then
-      output_persona "$2"
-    fi
-
-    # Auto-prime context after persona (reduces cold-start overhead)
-    # Pass agent name so prime can load agent-specific sidecar
+    # Context loading order (optimized for attention):
+    # 1. CLAUDE.md (system prompt - already loaded)
+    # 2. Agent definition + behavior guide (loaded by prime.sh FIRST)
+    # 3. Persona (output here, AFTER agent definition)
+    # 4. Session summary (loaded by prime.sh)
+    # 5. Sidecars (loaded by prime.sh LAST)
+
+    # Auto-prime loads agent definition FIRST (highest attention zone)
     if [[ -f "$PROJECT_ROOT/.pennyfarthing/scripts/prime.sh" ]]; then
       "$PROJECT_ROOT/.pennyfarthing/scripts/prime.sh" --quiet --agent "$2"
     fi
+
+    # Output persona AFTER agent definition (character voice is supplementary)
+    if is_character_voice_enabled; then
+      output_persona "$2"
+    fi
     ;;
   stop)
     # Use provided session ID, fall back to SESSION_ID env var

package/pennyfarthing-dist/scripts/core/check-context.sh

@@ -204,9 +204,14 @@ if last_total is not None:
     # Use usable percent for status decisions (more accurate for user)
     if usable_pct > warning_threshold:
         print('CONTEXT_STATUS=HIGH')
-        print('HANDOFF_MODE=auto')
     else:
         print('CONTEXT_STATUS=OK')
+
+    # HANDOFF_MODE: 'auto' if relay_mode enabled, 'ask' otherwise
+    # MSSCI-12395: relay_mode controls autohandoff independent of context level
+    if relay_mode:
+        print('HANDOFF_MODE=auto')
+    else:
         print('HANDOFF_MODE=ask')
 
     # TirePump: Use CONTEXT_CLEAR (clear + load next agent) when: