@pennyfarthing/core 10.0.1 → 10.0.2

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

@@ -0,0 +1,412 @@
+# 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

@@ -0,0 +1,257 @@
+# 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