npm - @pennyfarthing/core - Versions diffs - 9.2.0 → 9.3.0 - Mend

@pennyfarthing/core 9.2.0 → 9.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1039) hide show

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

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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 DELETED Viewed

@@ -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.