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/skill-schema.md DELETED Viewed

@@ -1,412 +0,0 @@
-# Skill File XML Schema
-Skill files document slash commands and their usage. A consistent XML schema ensures agents can reliably parse commands, arguments, and execution patterns.
-## File Location
-```
-skills/{skill-name}/SKILL.md
-```
-**Examples:**
-- `skills/sprint/SKILL.md`
-- `skills/testing/SKILL.md`
-- `skills/jira/SKILL.md`
-## Complete Schema
-```markdown
----
-name: skill-name
-description: |
-  One-line or multiline description of what this skill does.
-  IMPORTANT notes can go here.
-args: "[command|arg1|arg2]"
----
-# /skill-name - Human Readable Title
-<critical>
-Non-negotiable rules for this skill.
-**Never** do X. **Always** do Y.
-</critical>
-## Commands
-### `/skill-name` or `/skill-name command`
-Description of what this command does.
-<run>
-.pennyfarthing/scripts/path/to/script.sh [args]
-</run>
-<args>
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `arg1` | Yes | What this argument does |
-| `arg2` | No | Optional argument |
-</args>
-<example>
-.pennyfarthing/scripts/path/to/script.sh value1
-# Returns: expected output format
-</example>
-<output>
-What the command returns and how to interpret it.
-</output>
-<when>
-Conditions for using this command.
-What to do next after running it.
-</when>
----
-### `/skill-name another-command`
-Another command description...
-## Agent Activation
-<agent-activation>
-Load agent persona first:
-```bash
-d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/agent-session.sh" start "agent-name"
-```
-</agent-activation>
-## Quick Reference
-| Command | Script/Action |
-|---------|---------------|
-| `/skill-name` | `script.sh` |
-| `/skill-name cmd` | `script.sh cmd` |
-## Related Skills
-| Skill | Purpose |
-|-------|---------|
-| `/other-skill` | Related functionality |
-```
-## Element Reference
-### YAML Frontmatter (Required)
-Every skill file must have YAML frontmatter:
-```yaml
----
-name: skill-name          # Required: lowercase, hyphenated
-description: |            # Required: what this skill does
-  Description text...
-args: "[arg1|arg2]"       # Optional: argument summary
----
-```
-**Fields:**
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Skill identifier, matches directory name |
-| `description` | Yes | Human-readable description |
-| `args` | No | Argument syntax summary |
----
-### `<critical>`
-**Purpose:** Non-negotiable rules that MUST be followed. LLMs treat these as hard constraints.
-**When to Use:**
-- Rules that break the system if ignored
-- Security constraints
-- Data integrity requirements
-**Example:**
-```xml
-<critical>
-**Never manually edit** `sprint/current-sprint.yaml`. Use scripts.
-</critical>
-```
-**Note:** Use sparingly. If everything is critical, nothing is.
----
-### `<run>`
-**Purpose:** The exact command to execute for this skill command.
-**Required:** Yes, for every command that has a script.
-**Content:** Single shell command or script invocation.
-**Example:**
-```xml
-<run>
-.pennyfarthing/scripts/sprint/sprint-status.sh [filter]
-</run>
-```
-**Guidelines:**
-- Use `.pennyfarthing/scripts/` paths (never `pennyfarthing-dist/`)
-- Include argument placeholders in `[brackets]`
-- One command per `<run>` block
----
-### `<args>`
-**Purpose:** Document the arguments a command accepts.
-**Required:** Yes, if command takes arguments.
-**Format:** Markdown table with standard columns.
-**Example:**
-```xml
-<args>
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `story-id` | Yes | Story ID (e.g., `35-2` or `MSSCI-12345`) |
-| `--verbose` | No | Show detailed output |
-</args>
-```
-**Columns:**
-| Column | Description |
-|--------|-------------|
-| `Arg` | Argument name (backtick-wrapped) |
-| `Required` | `Yes` or `No` |
-| `Description` | What this argument does |
----
-### `<example>`
-**Purpose:** Show how to use the command with expected output.
-**Required:** Recommended for all commands.
-**Content:** Command invocation followed by commented output.
-**Example:**
-```xml
-<example>
-.pennyfarthing/scripts/sprint/check-story.sh MSSCI-12038
-# Returns: {"type": "story", "available": true, "title": "...", ...}
-</example>
-```
-**Guidelines:**
-- Show realistic values
-- Include the expected return format
-- Multiple examples are fine
----
-### `<output>`
-**Purpose:** Describe what the command returns and how to interpret it.
-**Required:** Yes, for every command.
-**Content:** Description of output format, fields, and interpretation.
-**Example:**
-```xml
-<output>
-Sprint metadata, stories by status (grouped under epic headers), points breakdown.
-When filtered, only shows epics with matching stories.
-</output>
-```
----
-### `<when>`
-**Purpose:** Document when to use this command and what to do next.
-**Required:** If there are specific conditions or next steps.
-**Content:** Conditions that trigger this command, or follow-up actions.
-**Example:**
-```xml
-<when>
-- Starting new development work
-- `/new-work` is an alias for this command
-Next steps after promote:
-- Review appended YAML in current-sprint.yaml
-- Create Jira epic: `/jira create epic <epic-id>`
-</when>
-```
----
-### `<agent-activation>`
-**Purpose:** Command to load an agent persona before using skill commands.
-**Required:** Only if skill requires agent activation.
-**Content:** The shell command to activate the agent.
-**Example:**
-```xml
-<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>
-```
----
-## Complete Example
-Here's a well-structured skill file following the schema:
-```markdown
----
-name: story
-description: |
-  Story creation, sizing, and completion workflow. Use when creating new stories,
-  estimating points, or finishing completed work.
-args: "[create|size|finish]"
----
-# /story - Story Management
-<critical>
-All story operations require SM agent activation.
-**Never** create stories outside of sprint context.
-</critical>
-## Commands
-### `/story create <title>`
-Create a new story in the current epic.
-<run>
-.pennyfarthing/scripts/story/create-story.sh "<title>"
-</run>
-<args>
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `title` | Yes | Story title (quoted if contains spaces) |
-</args>
-<example>
-.pennyfarthing/scripts/story/create-story.sh "Add user authentication"
-# Returns: {"id": "36-5", "title": "Add user authentication", "status": "backlog"}
-</example>
-<output>
-JSON with new story ID, title, and initial status.
-Story is created in backlog status within the active epic.
-</output>
-<when>
-After creating, use `/story size <id>` to estimate points.
-</when>
----
-### `/story finish <story-id>`
-Complete a story after PR merge.
-<run>
-.pennyfarthing/scripts/story/finish-story.sh <story-id>
-</run>
-<args>
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `story-id` | Yes | Story to finish (e.g., `36-5`) |
-</args>
-<example>
-.pennyfarthing/scripts/story/finish-story.sh 36-5
-# Archives story, updates Jira, cleans session files
-</example>
-<output>
-Confirmation of archive location and cleanup actions.
-</output>
-<when>
-Use after PR is merged and story work is complete.
-</when>
----
-## Agent Activation
-<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>
-## Quick Reference
-| Command | Script |
-|---------|--------|
-| `/story create <title>` | `create-story.sh` |
-| `/story size <id>` | `size-story.sh` |
-| `/story finish <id>` | `finish-story.sh` |
-## Related Skills
-| Skill | Purpose |
-|-------|---------|
-| `/sprint` | Sprint management |
-| `/jira` | Jira operations |
-```
----
-## Tag Summary
-| Tag | Purpose | Required |
-|-----|---------|----------|
-| `<critical>` | Non-negotiable rules | If applicable |
-| `<run>` | Command to execute | Yes, per command |
-| `<args>` | Argument table | If command takes args |
-| `<example>` | Usage with output | Recommended |
-| `<output>` | Return value description | Yes, per command |
-| `<when>` | Conditions/next steps | If applicable |
-| `<agent-activation>` | Agent loading | If skill requires agent |
----
-## Migration Checklist
-When updating existing skill files:
-- [ ] Add YAML frontmatter if missing
-- [ ] Wrap critical rules in `<critical>` tags
-- [ ] Add `<run>` for each command
-- [ ] Add `<args>` table for commands with arguments
-- [ ] Add `<example>` with realistic values
-- [ ] Add `<output>` describing return format
-- [ ] Add `<when>` for conditional commands
-- [ ] Add `<agent-activation>` if agent is required
----
-## Related Files
-| File | Purpose |
-|------|---------|
-| `guides/xml-tags.md` | Complete XML tag taxonomy |
-| `skills/sprint/SKILL.md` | Reference implementation |
-| `skill-registry.yaml` | Skill registration |

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

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