@pennyfarthing/core 7.9.0 → 7.9.2

package/pennyfarthing-dist/guides/workflow-schema.md

@@ -1,257 +0,0 @@
-# Workflow Definition Schema
-
-This guide defines the YAML schema for custom workflows in Pennyfarthing.
-
-## Overview
-
-Workflows define agent sequences for different work types. Instead of the hardcoded TDD flow (SM → TEA → Dev → Reviewer), you can create custom flows for documentation, debugging, devops, and more.
-
-## File Location
-
-Workflows are defined in `.claude/workflows/*.yaml`
-
-## Schema
-
-```yaml
-workflow:
-  name: string          # Required: unique identifier
-  description: string   # Optional: human-readable purpose
-  version: string       # Optional: semver for tracking changes
-
-  phases:               # Required: at least one phase
-    - name: string      # Required: phase identifier
-      agent: string     # Required: agent to invoke (sm, tea, dev, reviewer, etc.)
-      input: string[]   # Optional: what this phase receives
-      output: string[]  # Optional: what this phase produces
-      gate:             # Optional: conditions to proceed
-        type: string    # Required if gate present: approval, tests_pass, tests_fail, manual
-        condition: string  # Optional: additional condition description
-
-  triggers:             # Optional: when to use this workflow
-    tags: string[]      # Optional: story tags that match
-    types: string[]     # Optional: story types (feature, bug, chore, docs)
-    points:             # Optional: point-based routing
-      min: number       # Optional: minimum points
-      max: number       # Optional: maximum points
-    default: boolean    # Optional: use as fallback workflow
-
-  permissions:          # Optional: required permissions for this workflow
-    - tool: string      # Required: tool name (Bash, Read, WebFetch, etc.)
-      scope: string     # Required: scope pattern (e.g., "npm test", "*.github.com")
-      reason: string    # Required: human-readable reason for the permission
-```
-
-## Required Fields
-
-| Field | Description |
-|-------|-------------|
-| `workflow.name` | Unique identifier for the workflow |
-| `workflow.phases` | Array with at least one phase |
-| `phases[].name` | Identifier for the phase |
-| `phases[].agent` | Agent to invoke (sm, tea, dev, reviewer, architect, pm, tech-writer, ux-designer, devops) |
-
-## Optional Fields
-
-| Field | Description |
-|-------|-------------|
-| `workflow.description` | Human-readable purpose |
-| `workflow.version` | Semver version string |
-| `phases[].input` | Array of inputs from previous phases |
-| `phases[].output` | Array of outputs for next phases |
-| `phases[].gate` | Conditions to proceed to next phase |
-| `workflow.triggers` | Rules for automatic workflow selection |
-| `workflow.permissions` | Array of permission presets required by the workflow |
-
-## Gate Types
-
-| Type | Description |
-|------|-------------|
-| `tests_pass` | All tests must pass |
-| `tests_fail` | Tests must be failing (RED phase) |
-| `approval` | Requires reviewer approval |
-| `manual` | Manual confirmation required |
-
-## Permission Presets
-
-Workflows can declare required permissions that are checked at workflow start. If any permissions are missing, the user is prompted to grant them before proceeding.
-
-### Permission Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `tool` | Yes | Tool name: `Bash`, `Read`, `Write`, `Edit`, `WebFetch`, `WebSearch`, `Glob`, `Grep`, `Task` |
-| `scope` | Yes | Scope pattern for the permission (e.g., `"npm test"`, `"*.github.com"`, `"src/**/*"`) |
-| `reason` | Yes | Human-readable explanation shown when prompting user |
-
-### Permission Checking
-
-On workflow start:
-1. System reads workflow's `permissions` array
-2. Compares against cached grants in `.claude/settings.local.json`
-3. For each missing permission, prompts user with the `reason`
-4. Granted permissions are cached for the session
-
-### Example: TDD Workflow with Permissions
-
-```yaml
-workflow:
-  name: tdd-with-permissions
-  description: TDD workflow with pre-declared permissions
-  version: "1.0.0"
-
-  permissions:
-    - tool: Bash
-      scope: "npm test|npm run build"
-      reason: "TDD workflow requires running tests and builds"
-    - tool: Read
-      scope: "src/**/*"
-      reason: "Need to read source files for implementation"
-
-  phases:
-    - name: setup
-      agent: sm
-    - name: red
-      agent: tea
-      gate:
-        type: tests_fail
-    - name: green
-      agent: dev
-      gate:
-        type: tests_pass
-    - name: review
-      agent: reviewer
-      gate:
-        type: approval
-    - name: finish
-      agent: sm
-```
-
-## Examples
-
-### TDD Workflow
-
-The standard test-driven development flow:
-
-```yaml
-workflow:
-  name: tdd
-  description: Test-driven development with code review
-  version: "1.0.0"
-
-  phases:
-    - name: setup
-      agent: sm
-      output: [session_file, branches]
-
-    - name: red
-      agent: tea
-      input: [session_file]
-      output: [failing_tests]
-      gate:
-        type: tests_fail
-
-    - name: green
-      agent: dev
-      input: [failing_tests]
-      output: [implementation, passing_tests]
-      gate:
-        type: tests_pass
-
-    - name: review
-      agent: reviewer
-      input: [implementation]
-      output: [approval]
-      gate:
-        type: approval
-
-    - name: finish
-      agent: sm
-      input: [approval]
-      output: [archived_session]
-
-  triggers:
-    types: [feature]
-    default: true
-```
-
-### Trivial Workflow
-
-For small fixes that skip TEA:
-
-```yaml
-workflow:
-  name: trivial
-  description: Quick fixes without full TDD ceremony
-  version: "1.0.0"
-
-  phases:
-    - name: setup
-      agent: sm
-    - name: implement
-      agent: dev
-      gate:
-        type: tests_pass
-    - name: review
-      agent: reviewer
-      gate:
-        type: approval
-    - name: finish
-      agent: sm
-
-  triggers:
-    types: [chore, fix]
-    points:
-      max: 2
-```
-
-### Documentation Workflow
-
-For docs-only work:
-
-```yaml
-workflow:
-  name: docs
-  description: Documentation updates
-  version: "1.0.0"
-
-  phases:
-    - name: setup
-      agent: sm
-    - name: write
-      agent: tech-writer
-      output: [documentation]
-    - name: review
-      agent: reviewer
-      gate:
-        type: approval
-    - name: finish
-      agent: sm
-
-  triggers:
-    types: [docs]
-    tags: [documentation]
-```
-
-## Trigger Priority
-
-When multiple workflows match a story, the routing engine uses this priority:
-
-1. Explicit `workflow:` tag on story
-2. Most specific trigger match (tags > types > points)
-3. `default: true` workflow as fallback
-
-## Validation
-
-Workflows are validated at load time. Invalid workflows will report errors with field paths:
-
-```
-Error: workflow.phases[1].agent is required
-Error: workflow.triggers.points min (10) cannot be greater than max (5)
-```
-
-## Related
-
-- Story 31-2: Workflow loader and validator
-- Story 31-3: Story-to-workflow routing engine
-- Story 31-5: /workflow skill for listing and switching
-- Story MSSCI-11710: Permission presets by workflow

package/pennyfarthing-dist/guides/worktree-mode.md

@@ -1,113 +0,0 @@
-# Worktree Mode
-
-Work on multiple stories in parallel using git worktrees.
-
-## When to Use
-
-- Working on a second story while waiting for PR review
-- Urgent bug fix while feature work is in progress
-- Comparing implementations side-by-side
-
-## Quick Start
-
-```
-/parallel-work
-```
-
-This creates a worktree, sets up the session, and starts the TDD flow.
-
-## How It Works
-
-### Session Files
-
-```
-.session/
-├── 5-2-session.md               # Story 5-2 (main checkout)
-└── 5-3a-session.md              # Story 5-3a (worktree)
-```
-
-Naming convention: `{story-id}-session.md`
-Worktree info is stored INSIDE the session file, not in the filename.
-
-### Worktree Directory Structure
-
-```
-worktrees/
-└── wt-5-3a/
-    ├── Pennyfarthing-api/    # API repo worktree
-    └── Pennyfarthing-ui/     # UI repo worktree
-```
-
-### Session File Format
-
-Worktree sessions include a context section:
-
-```yaml
-## Worktree Context
-worktree: wt-5-3a
-path: /path/to/worktrees/wt-5-3a
-api_port: 8082
-ui_port: 5175
-```
-
-Agents read this to know:
-- They're in a worktree
-- Where the worktree lives
-- Which ports to use
-
-## Agent Detection
-
-Agents detect worktree context from the session file:
-
-```bash
-# Check if worktree session
-if grep -q "^worktree:" "$SESSION_FILE"; then
-    WORKTREE_NAME=$(grep "^worktree:" "$SESSION_FILE" | cut -d' ' -f2)
-    WORKTREE_PATH=$(grep "^path:" "$SESSION_FILE" | cut -d' ' -f2)
-fi
-```
-
-No filename parsing needed.
-
-## Port Management
-
-Each worktree gets offset ports to avoid conflicts:
-
-| Worktree | API Port | UI Port | WebSocket |
-|----------|----------|---------|-----------|
-| main     | 8080     | 5173    | 8081      |
-| wt-1     | 8082     | 5175    | 8083      |
-| wt-2     | 8084     | 5177    | 8085      |
-
-Ports are stored in the session file and passed to agents.
-
-## Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/parallel-work` | Start a new parallel work session |
-| `./scripts/run.sh git/worktree-manager.sh list` | Show active worktrees |
-| `./scripts/run.sh git/worktree-manager.sh remove <name>` | Clean up a worktree |
-
-## TDD Flow in Worktrees
-
-Same flow as main checkout:
-
-```
-/parallel-work → SM → TEA → Dev → Reviewer → SM (finish)
-```
-
-Agents use worktree paths from session file for all operations.
-
-## Cleanup
-
-When story is complete, SM archives the session and the worktree can be removed:
-
-```bash
-./scripts/run.sh git/worktree-manager.sh remove wt-5-3a
-```
-
-This removes:
-- Git worktrees
-- Session file
-- Port allocations

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

@@ -1,335 +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/core/run.sh 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) |
-
-## 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