@pennyfarthing/core 7.4.1 → 7.5.0

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/output-styles/teaching.md

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

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

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