@pennyfarthing/core 7.4.0 → 7.4.1

package/pennyfarthing-dist/skills/workflow/skill.md

@@ -0,0 +1,337 @@
+---
+name: workflow
+description: |
+  List available workflows, show current workflow details, and switch workflows mid-session. Use when checking available workflow types (TDD, trivial, agent-docs), viewing current workflow phase, switching to a different workflow pattern, or managing BikeLane stepped workflows.
+args: "[list|show [name]|set <name>|start <name> [--mode <mode>]|resume [name]|status]"
+---
+
+# /workflow - Workflow Management
+
+Pennyfarthing uses YAML-defined workflows to control agent sequences. The default TDD workflow (SM → TEA → Dev → Reviewer) can be customized or replaced with alternative flows. BikeLane stepped workflows provide progressive disclosure for planning and decision-making processes.
+
+## Commands
+
+### `/workflow` or `/workflow list`
+
+List all available workflows with type indicators.
+
+**Run:**
+```bash
+.pennyfarthing/scripts/core/run.sh workflow/list-workflows.sh
+```
+
+**Output:** Table of workflows with:
+- **Type**: `phased` (agent-driven) or `stepped` (progressive disclosure)
+- **Steps/Phases**: Number of steps or phases in the workflow
+- **Modes**: Available tri-modal options (create/validate/edit) if applicable
+- **Default**: Whether this is the default workflow
+- **Description**: Brief workflow description
+
+---
+
+### `/workflow show [name]`
+
+Show workflow details. If no name provided, shows current session's workflow.
+
+**Run:**
+```bash
+.pennyfarthing/scripts/core/run.sh workflow/show-workflow.sh [name]
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `name` | No | Workflow name (e.g., `tdd`, `trivial`). If omitted, shows current session's workflow. |
+
+**Examples:**
+```bash
+.pennyfarthing/scripts/core/run.sh workflow/show-workflow.sh          # Current session workflow
+.pennyfarthing/scripts/core/run.sh workflow/show-workflow.sh tdd      # Show TDD workflow
+.pennyfarthing/scripts/core/run.sh workflow/show-workflow.sh trivial  # Show trivial workflow
+```
+
+**Output:** Workflow description, phase flow diagram, phases table, and trigger conditions.
+
+---
+
+### `/workflow set <name>`
+
+Switch to a different workflow mid-session.
+
+**Warning:** Only do this when story requirements have fundamentally changed. Switching resets phase tracking.
+
+**Steps:**
+1. Verify workflow exists:
+   ```bash
+   .pennyfarthing/scripts/core/run.sh workflow/show-workflow.sh <name>
+   ```
+
+2. Update the session file's workflow field:
+   - Edit `.session/{story-id}-session.md`
+   - Change `**Workflow:**` line to new workflow name
+
+3. Continue with the new workflow's agent sequence
+
+---
+
+## BikeLane Stepped Workflow Commands
+
+BikeLane workflows use `type: stepped` and execute one step at a time with user gates.
+
+### `/workflow start <name> [--mode <mode>]`
+
+Start a stepped workflow. Creates a new session and begins at step 1.
+
+**Run:**
+```bash
+.pennyfarthing/scripts/core/run.sh workflow/start-workflow.sh <name> [--mode <mode>]
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `name` | Yes | Workflow name (e.g., `architecture`) |
+| `--mode` | No | Execution mode: `create` (default), `validate`, or `edit` |
+
+**Examples:**
+```bash
+/workflow start architecture              # Start in default (create) mode
+/workflow start architecture --mode validate  # Start in validate mode
+```
+
+---
+
+### `/workflow resume [name]`
+
+Resume an interrupted stepped workflow from the last completed step.
+
+**Run:**
+```bash
+.pennyfarthing/scripts/core/run.sh workflow/resume-workflow.sh [name]
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `name` | No | Workflow to resume. If omitted, detects from active session. |
+
+**Examples:**
+```bash
+/workflow resume                  # Resume active workflow
+/workflow resume architecture     # Resume specific workflow
+```
+
+---
+
+### `/workflow status`
+
+Show current stepped workflow progress.
+
+**Run:**
+```bash
+.pennyfarthing/scripts/core/run.sh workflow/workflow-status.sh
+```
+
+**Output:**
+- Current workflow name and type
+- Current step number and name
+- Steps completed
+- Mode (create/validate/edit)
+- Progress percentage
+
+---
+
+## Built-in Workflows
+
+### TDD (default for 3+ point features)
+
+```
+setup → red → green → review → finish
+SM → TEA → Dev → Reviewer → SM
+```
+
+- Full test-driven development cycle
+- TEA writes failing tests first
+- Dev implements to make tests pass
+- **Triggers:** `types: [feature, enhancement]`, `points.min: 3`
+
+### Trivial (for 1-2 point fixes)
+
+```
+setup → impl → review → finish
+SM → Dev → Reviewer → SM
+```
+
+- Skips TEA phase for quick fixes
+- Dev ensures existing tests still pass
+- **Triggers:** `types: [chore, fix, refactor]`, `points.max: 2`
+
+### Agent-Docs (for process documentation)
+
+```
+setup → analyze → impl → review → finish
+SM → Orchestrator → Orchestrator → Tech Writer → SM
+```
+
+- For agent file updates and process improvements
+- Tech Writer reviews for documentation quality
+- **Triggers:** `types: [docs, refactor, infrastructure]`, `labels: [agent-file]`
+
+### BDD (behavior-driven development)
+
+```
+setup → design → red → green → review → finish
+SM → UX-Designer → TEA → Dev → Reviewer → SM
+```
+
+- Adds UX design phase before testing
+- For UI components and user-facing features
+- **Triggers:** `types: [ui, ux, behavior]`, `tags: [bdd, ux-first]`
+
+### Architecture (stepped workflow)
+
+```
+initialize → context → patterns → components → interfaces → risks → document
+     1    →    2    →    3     →     4      →     5      →   6   →    7
+                [gate]              [gate]                  [gate]
+```
+
+- Progressive disclosure stepped workflow
+- 7 steps with gates at context, components, and risks
+- **Type:** `stepped` (BikeLane)
+- **Triggers:** `types: [architecture, design, adr]`, `tags: [architecture, stepped]`
+
+---
+
+## Workflow Routing Priority
+
+When multiple workflows match a story:
+
+1. **Explicit tag:** `workflow: docs` on story overrides everything
+2. **Trigger tags:** Story tags match workflow's `triggers.tags`
+3. **Type match:** Story type matches workflow's `triggers.types`
+4. **Points match:** Story points within `triggers.points` range
+5. **Default:** Workflow with `default: true` (tdd)
+
+---
+
+## File Locations
+
+| Location | Purpose |
+|----------|---------|
+| `pennyfarthing-dist/workflows/` | Built-in workflow definitions |
+| `.session/{story-id}-session.md` | Current story's workflow assignment |
+
+---
+
+## Quick Reference
+
+| Command | Script/Action |
+|---------|---------------|
+| `/workflow` | `list-workflows.sh` |
+| `/workflow list` | `list-workflows.sh` |
+| `/workflow show` | `show-workflow.sh` (current session) |
+| `/workflow show tdd` | `show-workflow.sh tdd` |
+| `/workflow set trivial` | Manual edit of session file |
+| `/workflow start architecture` | `start-workflow.sh architecture` |
+| `/workflow start architecture --mode validate` | `start-workflow.sh architecture --mode validate` |
+| `/workflow resume` | `resume-workflow.sh` |
+| `/workflow status` | `workflow-status.sh` |
+| `/workflow fix-phase 56-1 review` | `fix-session-phase.sh 56-1 review` |
+
+---
+
+## Session Phase Repair
+
+### `/workflow fix-phase <story-id> <target-phase> [--dry-run]`
+
+Fix session file when handoffs didn't update phase tracking properly. This corrects the `**Phase:**` field and adds missing handoff history rows.
+
+**When to use:**
+- SM detects wrong phase after handoff
+- `workflow-status-check` shows stale state
+- Phase History table is incomplete
+
+**Run:**
+```bash
+.pennyfarthing/scripts/core/run.sh workflow/fix-session-phase.sh <story-id> <target-phase> [--dry-run]
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `story-id` | Yes | Story ID (e.g., `56-1` or `MSSCI-12190`) |
+| `target-phase` | Yes | Target phase to set (e.g., `review`, `approved`, `finish`) |
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Show what would be done without executing |
+
+**Examples:**
+```bash
+# Preview what would change
+.pennyfarthing/scripts/core/run.sh workflow/fix-session-phase.sh 56-1 review --dry-run
+
+# Fix phase to review (after Dev completed)
+.pennyfarthing/scripts/core/run.sh workflow/fix-session-phase.sh 56-1 review
+
+# Fix phase to approved (after Reviewer approved)
+.pennyfarthing/scripts/core/run.sh workflow/fix-session-phase.sh 56-1 approved
+
+# Using Jira key
+.pennyfarthing/scripts/core/run.sh workflow/fix-session-phase.sh MSSCI-12190 approved
+```
+
+**Valid phases by workflow:**
+| Workflow | Phase Sequence |
+|----------|----------------|
+| `tdd` | setup → red → green → review → approved → finish |
+| `trivial` | setup → impl → review → approved → finish |
+
+**What it updates:**
+1. `**Phase:**` field to target phase
+2. `**Phase Started:**` to current timestamp
+3. Handoff History table with missing transitions
+
+---
+
+## Creating Custom Workflows
+
+See `pennyfarthing-dist/guides/workflow-schema.md` for the full YAML schema.
+
+Example documentation workflow:
+
+```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]
+```
+
+---
+
+## BikeLane Documentation
+
+For comprehensive documentation on creating stepped workflows, see:
+
+- **[docs/BIKELANE.md](../../docs/BIKELANE.md)** - Full BikeLane user guide
+- **[docs/adr/0005-bmad-workflow-import.md](../../docs/adr/0005-bmad-workflow-import.md)** - Technical ADR
+- **[pennyfarthing-dist/workflows/architecture.yaml](../workflows/architecture.yaml)** - Example implementation

package/pennyfarthing-dist/skills/yq/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: yq
+description: yq is a YAML processor. Use this skill when reading, modifying, or querying YAML files from the command line.
+---
+
+# yq - YAML Processor Skill
+
+## Overview
+
+`yq` is a lightweight and portable command-line YAML processor. It's like `jq` but for YAML. This skill covers the mikefarah/yq version (v4+).
+
+## Installation
+
+```bash
+# macOS
+brew install yq
+
+# Check version (should be v4+)
+yq --version
+```
+
+## Basic Operations
+
+### Read a Value
+
+```bash
+# Read a top-level key
+yq '.theme' config.yaml
+# Output: discworld
+
+# Read nested value
+yq '.agents.sm.character' personas.yaml
+# Output: Captain Carrot Ironfoundersson
+
+# Read with default if missing
+yq '.missing // "default"' config.yaml
+# Output: default
+```
+
+### Read Entire Section
+
+```bash
+# Get all properties of a key
+yq '.agents.sm' personas.yaml
+# Output: the entire sm object as YAML
+
+# Output as JSON
+yq -o json '.agents.sm' personas.yaml
+```
+
+### Check if Key Exists
+
+```bash
+# Returns "true" or "false"
+yq '.agents.sm | has("helper")' personas.yaml
+
+# Returns null if doesn't exist
+yq '.agents.missing' personas.yaml
+# Output: null
+```
+
+## Modifying YAML
+
+### In-Place Edit
+
+```bash
+# Edit file in place
+yq -i '.theme = "startrek"' config.yaml
+
+# Add a new key
+yq -i '.newkey = "value"' config.yaml
+
+# Delete a key
+yq -i 'del(.unwanted)' config.yaml
+```
+
+### Output to Stdout (Non-Destructive)
+
+```bash
+# Modify and output to stdout (file unchanged)
+yq '.count = 42' config.yaml
+
+# Pipe to new file
+yq '.theme = "newtheme"' config.yaml > new-config.yaml
+```
+
+## Common Patterns
+
+### Iterate Over Arrays
+
+```bash
+# List all items
+yq '.stories[]' sprint.yaml
+
+# Get specific field from each item
+yq '.stories[].title' sprint.yaml
+
+# Filter items
+yq '.stories[] | select(.status == "in-progress")' sprint.yaml
+```
+
+### Iterate Over Object Keys
+
+```bash
+# Get all agent names
+yq '.agents | keys' personas.yaml
+# Output:
+# - sm
+# - tea
+# - dev
+# - reviewer
+
+# Iterate with key-value
+yq '.agents | to_entries | .[] | .key + ": " + .value.character' personas.yaml
+```
+
+### Merge Files
+
+```bash
+# Merge two YAML files (second overwrites first)
+yq '. *= load("overrides.yaml")' base.yaml
+
+# Merge specific key
+yq '.agents.sm *= load("sm-overrides.yaml")' personas.yaml
+```
+
+### Extract to Environment Variables
+
+```bash
+# Export as shell variables
+eval $(yq -o shell '.database' config.yaml)
+# Creates: $host, $port, $name
+
+# Specific format
+yq '.theme' config.yaml | xargs -I{} echo "THEME={}"
+```
+
+## Working with Multi-Document YAML
+
+```bash
+# Select specific document (0-indexed)
+yq 'select(document_index == 0)' multi.yaml
+
+# Process all documents
+yq '... | select(has("kind"))' k8s-manifests.yaml
+```
+
+## String Operations
+
+```bash
+# Uppercase
+yq '.name | upcase' config.yaml
+
+# String contains
+yq '.agents | to_entries | .[] | select(.value.style | contains("honest"))' personas.yaml
+
+# String interpolation
+yq '"Theme is: " + .theme' config.yaml
+```
+
+## Conditional Logic
+
+```bash
+# If-then-else
+yq 'if .count > 10 then "many" else "few" end' config.yaml
+
+# Select with condition
+yq '.stories[] | select(.points >= 5)' sprint.yaml
+
+# Null coalescing
+yq '.optional // "default"' config.yaml
+```
+
+## Output Formats
+
+```bash
+# YAML (default)
+yq '.data' file.yaml
+
+# JSON
+yq -o json '.data' file.yaml
+
+# Properties format
+yq -o props '.data' file.yaml
+
+# CSV (for arrays)
+yq -o csv '.items' file.yaml
+```
+
+## Common Use Cases in Pennyfarthing
+
+### Read Persona Config
+
+```bash
+# Get current theme
+yq '.theme' .claude/persona-config.yaml
+
+# Get agent persona
+THEME=$(yq '.theme' .claude/persona-config.yaml)
+yq ".agents.sm" personas/themes/${THEME}.yaml
+```
+
+### Query Sprint Data
+
+```bash
+# Get current sprint stories
+yq '.stories[] | select(.status == "todo")' sprint/current-sprint.yaml
+
+# Count stories by status
+yq '[.stories[].status] | group_by(.) | map({(.[0]): length}) | add' sprint/current-sprint.yaml
+```
+
+### Update Session Files
+
+```bash
+# Update status in YAML frontmatter (if using YAML)
+yq -i '.status = "in-progress"' .session/current_work.yaml
+```
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Read value | `yq '.key' file.yaml` |
+| Read nested | `yq '.parent.child' file.yaml` |
+| Set value | `yq -i '.key = "value"' file.yaml` |
+| Delete key | `yq -i 'del(.key)' file.yaml` |
+| Array length | `yq '.array | length' file.yaml` |
+| Filter array | `yq '.array[] \| select(.field == "value")' file.yaml` |
+| Output JSON | `yq -o json '.' file.yaml` |
+| Merge files | `yq '. *= load("other.yaml")' base.yaml` |
+| Default value | `yq '.key // "default"' file.yaml` |
+
+## Troubleshooting
+
+### "null" Output
+
+The key doesn't exist. Use `// "default"` for fallback:
+```bash
+yq '.missing // "not found"' file.yaml
+```
+
+### Quotes in Output
+
+yq preserves YAML formatting. Use `-r` (raw) for unquoted strings:
+```bash
+yq -r '.theme' config.yaml
+```
+
+### Boolean as String
+
+YAML booleans (`true`/`false`) are parsed as booleans. Compare accordingly:
+```bash
+# CORRECT
+yq '.enabled == true' config.yaml
+
+# WRONG (comparing to string)
+yq '.enabled == "true"' config.yaml
+```
+
+## Reference
+
+- **Official Docs:** https://mikefarah.gitbook.io/yq/
+- **GitHub:** https://github.com/mikefarah/yq