@pennyfarthing/core 7.5.0 → 7.6.1

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

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

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

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

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

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