@pennyfarthing/core 9.2.0 → 9.4.0

package/pennyfarthing-dist/guides/xml-tags.md

@@ -1,627 +0,0 @@
-# XML Tag Taxonomy
-
-Pennyfarthing uses XML-style tags to structure agent definitions and skill documentation. These tags help LLMs identify and prioritize different types of content.
-
-## Priority Tags
-
-Tags that affect LLM behavior and attention.
-
-### `<critical>`
-
-**Purpose:** Non-negotiable rules that MUST be followed. LLMs should treat these as hard constraints.
-
-**Usage:** Gates, invariants, protocol requirements, things that break the system if ignored.
-
-```markdown
-<critical>
-**Never edit sprint YAML directly.** Use scripts.
-</critical>
-```
-
-**Examples:**
-- "Subagent output is NOT visible to Cyclist"
-- "NEVER mark acceptance criteria as complete" (for subagents)
-- "Write assessment BEFORE spawning handoff subagent"
-
-### `<gate>`
-
-**Purpose:** Prerequisites that MUST be verified before proceeding. Checklist-style validation.
-
-**Usage:** Entry/exit conditions for workflows, handoff requirements, quality gates.
-
-```markdown
-<gate>
-## Handoff Checklist
-1. Session file exists
-2. Acceptance criteria defined
-3. Feature branches created
-</gate>
-```
-
-**Difference from `<critical>`:** Gates are procedural checkpoints; critical items are invariant rules.
-
-### `<info>`
-
-**Purpose:** Contextual information that helps but doesn't constrain. Reference material.
-
-**Usage:** Background context, defaults, file locations, tips.
-
-```markdown
-<info>
-**Workflow:** SM → TEA → Dev → Reviewer → SM
-**Skills:** `/sprint`, `/jira`, `/testing`
-</info>
-```
-
-## Identity Tags
-
-Tags that define agent personality and role.
-
-### `<persona>`
-
-**Purpose:** Character personality from the active theme. Loaded at agent activation.
-
-**Usage:** Top of agent files, sets tone and style.
-
-```markdown
-<persona>
-Auto-loaded by `agent-session.sh start` from theme config.
-**Fallback if not loaded:** Supportive, methodical, detail-oriented
-</persona>
-```
-
-### `<role>`
-
-**Purpose:** Agent's position in the workflow and primary responsibility.
-
-**Usage:** Brief statement of what the agent does and when it's invoked.
-
-```markdown
-<role>
-Test specification, RED phase execution, handoff to Dev
-</role>
-```
-
-## Structure Tags
-
-Tags that organize agent content.
-
-### `<helpers>`
-
-**Purpose:** Describes Haiku subagents and their invocation pattern.
-
-**Usage:** Lists subagents, their purposes, and how to spawn them.
-
-### `<responsibilities>`
-
-**Purpose:** Bullet list of what this agent does vs delegates.
-
-### `<skills>`
-
-**Purpose:** Slash commands this agent commonly uses.
-
-### `<context>`
-
-**Purpose:** Guide files and sidecars to reference.
-
-### `<reasoning-mode>`
-
-**Purpose:** Verbose/quiet toggle for showing thought process.
-
-### `<on-activation>`
-
-**Purpose:** Startup checklist - what to do when agent is invoked.
-
-### `<exit>`
-
-**Purpose:** How to leave agent mode and cleanup.
-
-## Workflow Tags (TDD Agents)
-
-Tags used by agents participating in the TDD workflow cycle (SM, TEA, Dev, Reviewer).
-
-### `<phase-check>`
-
-**Purpose:** Verify agent owns the current workflow phase before proceeding. Prevents agents from acting on stories they shouldn't own.
-
-**Usage:** SM, TEA, Dev, Reviewer - runs `phase-owner.sh` on activation to determine correct owner.
-
-```markdown
-<phase-check>
-## On Startup: Check Phase
-
-Read `**Workflow:**` and `**Phase:**` from session. Query:
-```bash
-OWNER=$(.pennyfarthing/scripts/workflow/phase-owner.sh {workflow} {phase})
-```
-
-**If OWNER != "dev":** Run `handoff-marker.sh $OWNER`, output result, tell user.
-</phase-check>
-```
-
-### `<handoff-gate>`
-
-**Purpose:** Exit checklist that MUST be completed before handoff. Ensures assessment is written and subagent is spawned.
-
-**Usage:** TEA, Dev, Reviewer - mandatory checklist before exiting.
-
-```markdown
-<handoff-gate>
-## MANDATORY: Complete Before Exiting
-
-- [ ] Write Assessment to session file
-- [ ] Spawn `handoff` subagent
-- [ ] Verify handoff completed (subagent emits marker)
-</handoff-gate>
-```
-
-**Difference from `<gate>`:** `<handoff-gate>` is specifically for phase transitions; `<gate>` is for general prerequisites.
-
-### `<handoffs>`
-
-**Purpose:** Documents handoff relationships for strategic agents that coordinate but don't participate in the TDD cycle.
-
-**Usage:** PM, Architect, DevOps, Tech-Writer, UX-Designer, Orchestrator.
-
-```markdown
-<handoffs>
-### From PM/SM
-**When:** Epic needs architectural design
-**Input:** Business requirements, constraints
-**Action:** Design solution and provide guidance
-
-### To Dev
-**When:** Design is complete
-**Output:** Architecture decision and implementation plan
-</handoffs>
-```
-
-## Subagent Tags
-
-Tags used specifically by Haiku subagents for parameter contracts.
-
-### `<params>`
-
-**Purpose:** Define the parameter contract for subagents. Specifies what the calling agent must provide in the prompt.
-
-**Usage:** Subagents only (sm-setup, sm-finish, sm-handoff, sm-file-summary, handoff, testing-runner, reviewer-preflight).
-
-**Standard format (table):**
-```markdown
-<params>
-| Param | Required | Description |
-|-------|----------|-------------|
-| `STORY_ID` | Yes | Story identifier, e.g., "31-10" |
-| `WORKFLOW` | Yes | Workflow type: "tdd", "trivial", etc. |
-| `FILTER` | No | Test name pattern for filtered runs |
-</params>
-```
-
-**Note:** Use `<info>` for contextual information that isn't a parameter contract.
-
-### `<output>`
-
-**Purpose:** Define the standardized output format for subagents. Ensures calling agents receive both data AND instructions on what to do next.
-
-**Usage:** All subagents must use this format for their final output.
-
-**Standard format:**
-```markdown
-<output>
-## Output Format
-
-Return a `{SUBAGENT}_RESULT` block:
-
-### Success
-\`\`\`
-{SUBAGENT}_RESULT:
-  status: success
-  {data fields...}
-
-  next_steps:
-    - {instruction 1}
-    - {instruction 2}
-\`\`\`
-
-### Blocked
-\`\`\`
-{SUBAGENT}_RESULT:
-  status: blocked
-  error: "{description}"
-  fix: "{recommended action}"
-
-  next_steps:
-    - {what caller should do}
-\`\`\`
-</output>
-```
-
-**Required fields:**
-- `status`: `success` | `blocked` | `warning`
-- `next_steps`: Array of instructions for the calling agent
-
-**Why this matters:** Subagent output is NOT visible to users (only to the calling agent). Clear next steps ensure the caller knows exactly what to do with the result.
-
-## Specialized Tags (Single-Agent Use)
-
-Tags used by specific agents for their unique responsibilities.
-
-### `<adversarial-mindset>`
-
-**Purpose:** Sets skeptical review stance. Establishes the reviewer's critical, problem-hunting approach.
-
-**Usage:** Reviewer-only.
-
-```markdown
-<adversarial-mindset>
-**You are not here to approve code. You are here to find problems.**
-
-Assume the code is broken until you prove otherwise.
-**Default stance:** Skeptical. Suspicious. Looking for the flaw.
-</adversarial-mindset>
-```
-
-### `<review-checklist>`
-
-**Purpose:** Mandatory review steps the Reviewer must complete before making a judgment.
-
-**Usage:** Reviewer-only.
-
-```markdown
-<review-checklist>
-## MANDATORY Review Steps
-
-- [ ] **Trace data flow:** Pick a user input, follow it end-to-end
-- [ ] **Verify error handling:** What happens on failure?
-- [ ] **Security analysis:** Auth checks? Input sanitization?
-- [ ] **Make judgment:** APPROVE only if no Critical/High issues
-</review-checklist>
-```
-
-### `<self-review>`
-
-**Purpose:** Pre-handoff quality check for Dev to verify implementation before passing to Reviewer.
-
-**Usage:** Dev-only.
-
-```markdown
-<self-review>
-## Self-Review Before Handoff
-
-- [ ] Code is wired to front end or other components
-- [ ] Code follows project patterns
-- [ ] All acceptance criteria met
-- [ ] Tests passing (not skipped!)
-</self-review>
-```
-
-## Usage Guidelines
-
-1. **`<critical>` sparingly** - If everything is critical, nothing is. Reserve for true invariants.
-
-2. **`<gate>` for checkpoints** - Use when there's a clear pass/fail condition.
-
-3. **`<info>` generously** - Helpful context improves agent performance.
-
-4. **Order matters:**
-   ```
-   <persona>      # Who am I?
-   <role>         # What do I do?
-   <helpers>      # Who helps me?
-   <critical>     # What must I never violate?
-   <gate>         # What must I check?
-   <info>         # What's helpful to know?
-   ```
-
-5. **Close your tags** - Always use `</tag>` even though markdown parsers are lenient.
-
-## Tag Locations
-
-| Tag | Typical Location |
-|-----|------------------|
-| `<critical>` | Agent files, skill files, workflow instructions |
-| `<gate>` | Subagent files (handoff, finish, setup) |
-| `<info>` | Agent files, guide files |
-| `<persona>` | Agent files (top) |
-| `<role>` | Agent files (after persona) |
-
-## Session Tags
-
-Tags used in session files (`.session/{story-id}-session.md`) for workflow state tracking.
-
-### `<session>`
-
-**Purpose:** Root container for all session data.
-
-**Usage:** Wraps entire session file content.
-
-```markdown
-<session story="MSSCI-12345" workflow="tdd">
-  <!-- session content -->
-</session>
-```
-
-**Attributes:**
-- `story` - Story identifier (Jira key or local ID)
-- `workflow` - Workflow type: `tdd`, `trivial`, `bdd`, `agent-docs`
-
-### `<meta>`
-
-**Purpose:** Story metadata that doesn't change during the session.
-
-**Usage:** Inside `<session>`, contains static story info.
-
-```markdown
-<meta>
-  <jira>MSSCI-12345</jira>
-  <epic>MSSCI-12300</epic>
-  <points>3</points>
-  <started>2026-02-03</started>
-</meta>
-```
-
-### `<status>`
-
-**Purpose:** Machine-readable workflow state for agent navigation.
-
-**Usage:** Self-closing element updated at phase transitions.
-
-```markdown
-<status phase="green" next-agent="reviewer" handoff-ready="true"/>
-```
-
-**Attributes:**
-- `phase` - Current workflow phase (`setup`, `red`, `green`, `review`, `finish`)
-- `next-agent` - Agent to handle next (`sm`, `tea`, `dev`, `reviewer`)
-- `handoff-ready` - Whether current work is complete (`true`/`false`)
-
-### `<acceptance-criteria>`
-
-**Purpose:** Track AC completion status in machine-parseable format.
-
-**Usage:** Contains `<ac>` child elements.
-
-```markdown
-<acceptance-criteria>
-  <ac id="1" status="done">User can create account</ac>
-  <ac id="2" status="pending">Email validation works</ac>
-</acceptance-criteria>
-```
-
-### `<ac>`
-
-**Purpose:** Individual acceptance criterion.
-
-**Attributes:**
-- `id` - Numeric identifier (1, 2, 3...)
-- `status` - `pending`, `in-progress`, `done`, `blocked`
-
-### `<work-log>`
-
-**Purpose:** Container for chronological agent contributions.
-
-**Usage:** Contains `<entry>` and `<assessment>` elements.
-
-### `<entry>`
-
-**Purpose:** Standard work log entry from any agent.
-
-**Attributes:**
-- `agent` - Agent identifier (`sm`, `tea`, `dev`, `reviewer`)
-- `date` - Entry date (YYYY-MM-DD)
-- `phase` - Optional TDD phase (`red`, `green`, `refactor`)
-
-```markdown
-<entry agent="tea" date="2026-02-03" phase="red">
-  Wrote failing tests for all ACs.
-</entry>
-```
-
-### `<assessment>`
-
-**Purpose:** Formal verdict from Reviewer agent.
-
-**Attributes:**
-- `agent` - Must be `reviewer`
-- `verdict` - `approved`, `rejected`, `needs-work`
-
-```markdown
-<assessment agent="reviewer" verdict="approved">
-  All ACs verified, code follows patterns.
-</assessment>
-```
-
-**See also:** `guides/session-schema.md` for complete session file schema.
-
----
-
-## Skill Tags
-
-Tags used in skill files (`skills/{name}/SKILL.md`) for command documentation.
-
-### `<run>`
-
-**Purpose:** The exact command to execute for a skill command.
-
-**Usage:** One per command, contains shell command.
-
-```markdown
-<run>
-.pennyfarthing/scripts/sprint/sprint-status.sh [filter]
-</run>
-```
-
-### `<args>`
-
-**Purpose:** Document command arguments in table format.
-
-**Usage:** Follows `<run>`, contains markdown table.
-
-```markdown
-<args>
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `filter` | No | Filter by status: `todo`, `done` |
-</args>
-```
-
-### `<example>`
-
-**Purpose:** Show command usage with expected output.
-
-**Usage:** Realistic invocation followed by commented output.
-
-```markdown
-<example>
-.pennyfarthing/scripts/sprint/check-story.sh MSSCI-12038
-# Returns: {"type": "story", "available": true}
-</example>
-```
-
-### `<when>`
-
-**Purpose:** Document conditions for using a command and next steps.
-
-**Usage:** Trigger conditions or follow-up actions.
-
-```markdown
-<when>
-- Starting new development work
-- After promote, create Jira epic with `/jira create epic`
-</when>
-```
-
-### `<agent-activation>`
-
-**Purpose:** Command to load agent persona before using skill.
-
-**Usage:** Shell command for agent activation.
-
-```markdown
-<agent-activation>
-Load SM persona first:
-```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "sm"
-```
-</agent-activation>
-```
-
-**See also:** `guides/skill-schema.md` for complete skill file schema.
-
----
-
-## Workflow Step Tags
-
-Tags used in workflow step files (`workflows/{name}/steps/step-*.md`) for BikeLane navigation.
-
-### `<step-meta>`
-
-**Purpose:** Machine-readable step metadata for workflow navigation.
-
-**Usage:** Required at top of every step file.
-
-```markdown
-<step-meta>
-number: 1
-name: initialize
-gate: false
-next: step-02-context
-</step-meta>
-```
-
-**Fields:**
-- `number` - Step number (integer)
-- `name` - Step identifier (kebab-case)
-- `gate` - Whether step has checkpoint (boolean)
-- `next` - Next step filename (optional)
-
-### `<purpose>`
-
-**Purpose:** Explain what the step accomplishes.
-
-**Usage:** Clear, concise goal statement.
-
-```markdown
-<purpose>
-Set up the architecture session by gathering inputs and establishing context.
-</purpose>
-```
-
-### `<prerequisites>`
-
-**Purpose:** What must be true before starting this step.
-
-**Usage:** Bullet list of requirements.
-
-```markdown
-<prerequisites>
-- PRD document exists
-- Previous step completed
-</prerequisites>
-```
-
-### `<instructions>`
-
-**Purpose:** Step-by-step execution guide.
-
-**Usage:** Numbered list of actions.
-
-```markdown
-<instructions>
-1. Read the PRD document
-2. Identify architectural concerns
-3. Document recommendation
-</instructions>
-```
-
-### `<actions>`
-
-**Purpose:** Specific file and script operations.
-
-**Usage:** Prefixed bullet list (Check:, Read:, Write:, Run:).
-
-```markdown
-<actions>
-- Read: `{planning_artifacts}/*prd*.md`
-- Write: `{output_file}` with session content
-</actions>
-```
-
-### `<collaboration-menu>`
-
-**Purpose:** Present user options after step completion.
-
-**Usage:** Standard menu with keyboard shortcuts.
-
-```markdown
-<collaboration-menu>
-- **[C] Continue** - Proceed to next step
-- **[R] Revise** - Make changes
-- **[H] Help** - Get guidance
-</collaboration-menu>
-```
-
-### `<next-step>`
-
-**Purpose:** Explicit navigation to the next step.
-
-**Usage:** Instruction on which file to load.
-
-```markdown
-<next-step>
-After gate passes, proceed to step-02-context.md
-</next-step>
-```
-
-**See also:** `guides/workflow-step-schema.md` for complete workflow step schema.
-
----
-
-## Adding New Tags
-
-Before adding a new tag type:
-
-1. Check if existing tags cover the use case
-2. Document the tag's purpose and priority level
-3. Update this file
-4. Be consistent across all files using the tag

package/pennyfarthing-dist/output-styles/teaching.md

@@ -1,33 +0,0 @@
-# Teaching Output Style
-
-Explain your reasoning and teach as you go. Help the user learn, not just complete tasks.
-
-## Guidelines
-
-- **Show your work** - Explain the reasoning behind each decision
-- **Teach patterns** - Point out reusable patterns and principles
-- **Suggest alternatives** - Mention other valid approaches and their trade-offs
-- **Ask questions** - Help the user think through problems themselves
-- **Build understanding** - Connect new concepts to things the user likely knows
-
-## When making changes
-
-- Explain why this approach was chosen over alternatives
-- Point out the underlying principle or pattern
-- Suggest how this knowledge applies elsewhere
-- Offer tips for recognizing similar situations
-
-## When debugging
-
-- Walk through the diagnostic process
-- Explain how to identify the root cause
-- Teach the debugging technique, not just the fix
-- Share mental models for thinking about the problem
-
-## Tone
-
-- Collaborative, not lecturing
-- Curious and exploratory
-- Encouraging of questions
-
-This style helps users grow their skills while getting work done.

package/pennyfarthing-dist/output-styles/terse.md

@@ -1,20 +0,0 @@
-# Terse Output Style
-
-Be concise and minimal. Get to the point quickly.
-
-## Guidelines
-
-- **Brief responses** - Say only what's necessary
-- **Skip explanations** - Assume the user understands context
-- **No pleasantries** - Skip greetings and filler
-- **Actions over words** - Do the work, report results briefly
-- **Essential info only** - Omit nice-to-know details
-
-## Format
-
-- Use bullet points over paragraphs
-- One-line summaries preferred
-- Code output without lengthy commentary
-- Error messages without excessive context
-
-This style is for experienced users who want fast, efficient interactions.

package/pennyfarthing-dist/output-styles/verbose.md

@@ -1,28 +0,0 @@
-# Verbose Output Style
-
-Provide detailed, educational explanations throughout your responses.
-
-## Guidelines
-
-- **Explain your reasoning** - Walk through your thought process step by step
-- **Provide context** - Explain why something works the way it does, not just what it does
-- **Include examples** - Show concrete examples when explaining concepts
-- **Document decisions** - Explain trade-offs and alternatives considered
-- **Be thorough** - Cover edge cases, potential issues, and related considerations
-
-## When working on code
-
-- Explain what each change does and why it's needed
-- Describe how the change fits into the larger architecture
-- Point out patterns being followed or established
-- Note any potential side effects or dependencies
-- Suggest related improvements when relevant
-
-## When answering questions
-
-- Provide comprehensive answers with supporting details
-- Include relevant background information
-- Reference documentation or sources when helpful
-- Offer to elaborate on any points that might need clarification
-
-This style is ideal for learning, onboarding, or when you want to deeply understand decisions being made.