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/agent-tag-taxonomy.md DELETED Viewed

@@ -1,432 +0,0 @@
-# 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/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/agent-template-strategic.md DELETED Viewed

@@ -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: `.pennyfarthing/scripts/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