@pennyfarthing/core 7.0.2 → 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/templates/settings.local.json.template

@@ -85,6 +85,6 @@
   },
   "statusLine": {
     "type": "command",
-    "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/statusline.sh"
+    "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/misc/statusline.sh"
   }
 }

package/pennyfarthing-dist/workflows/agent-docs.yaml

@@ -23,7 +23,7 @@ workflow:
         type: manual
         condition: Changes identified and documented
 
-    - name: implement
+    - name: impl
       agent: orchestrator
       input: [audit_report, proposed_changes]
       output: [updated_files]

package/pennyfarthing-dist/workflows/architecture/steps/step-01-initialize.md

@@ -0,0 +1,101 @@
+# Step 1: Initialize Architecture Session
+
+<step-meta>
+number: 1
+name: initialize
+gate: false
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- DETECT existing workflow state before initialization
+- NEVER generate content without user input
+- ALWAYS treat this as collaborative discovery between architectural peers
+- FOCUS on initialization only - don't look ahead to future steps
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Initialize document and update frontmatter
+- Set up frontmatter `stepsCompleted: [1]` before loading next step
+- FORBIDDEN to load next step until setup is complete
+
+## Purpose
+
+Set up the architecture decision session by gathering inputs and establishing context.
+
+## Continuation Detection
+
+**First, check for existing workflow:**
+
+1. Look for existing `{output_file}`
+2. If exists, read complete file including frontmatter
+3. If frontmatter has `stepsCompleted` array → **Load `./step-01b-continue.md`**
+4. If not exists → proceed with fresh initialization below
+
+## Instructions
+
+1. **Verify required inputs exist**:
+   - Product Requirements Document (PRD) or feature brief
+   - Any existing architecture documentation
+   - Relevant ADRs from `docs/adr/`
+
+2. **Create session workspace**:
+   - Output file: `{output_file}`
+   - Working notes in session file
+
+3. **Identify stakeholders and constraints**:
+   - Who needs to approve this decision?
+   - What are the timeline constraints?
+   - Are there budget or resource limitations?
+
+## Actions
+
+- Check: `{output_file}` for existing workflow (continuation detection)
+- Read: `{planning_artifacts}/*prd*.md` or `{planning_artifacts}/*brief*.md`
+- Read: `docs/adr/*.md` (scan for relevant prior decisions)
+- Read: Existing architecture docs if referenced
+
+## Output
+
+Add to session file:
+
+```markdown
+## Architecture Session: {project_name}
+
+### Inputs Gathered
+- PRD: [path or "not found"]
+- Existing ADRs: [list relevant ones]
+- Constraints: [timeline, budget, resources]
+
+### Stakeholders
+- Decision maker: [name/role]
+- Reviewers: [list]
+```
+
+## Collaboration Menu
+
+After completing initialization, present options:
+
+- **[C] Continue** - Inputs gathered, proceed to Context Analysis
+- **[A] Advanced Elicitation** - Use discovery protocols to find additional context
+- **[R] Revise** - Need to locate missing inputs before proceeding
+
+## Success Metrics
+
+- Existing workflow detected and handed off to step-01b correctly
+- Fresh workflow initialized with proper setup
+- Input documents discovered and loaded
+- PRD requirement validated and communicated
+- User confirmed document setup before proceeding
+
+## Failure Modes
+
+- Proceeding with fresh initialization when existing workflow exists
+- Not detecting PRD requirement
+- Not confirming inputs with user before proceeding
+
+## Next Step
+
+After user selects [C], proceed to Context Analysis to understand the technical landscape.

package/pennyfarthing-dist/workflows/architecture/steps/step-01b-continue.md

@@ -0,0 +1,93 @@
+# Step 1b: Workflow Continuation Handler
+
+<step-meta>
+number: 1b
+name: continue
+gate: false
+</step-meta>
+
+## Mandatory Execution Rules
+
+- DETECT existing workflow state from output document frontmatter
+- READ complete document to understand current progress
+- PRESENT continuation options to user before proceeding
+- NEVER proceed without user confirmation
+
+## Purpose
+
+Handle workflow resumption when an existing architecture document is detected. This step is invoked automatically when step 1 finds an existing document with `stepsCompleted` in frontmatter.
+
+## Detection Trigger
+
+Step 1 redirects here when:
+1. Output file `{output_file}` already exists
+2. Document has frontmatter with `stepsCompleted` array
+3. Workflow was previously started but not completed
+
+## Instructions
+
+1. **Read Existing State**:
+   - Parse frontmatter for `stepsCompleted` array
+   - Identify last completed step
+   - Load document content to understand current progress
+
+2. **Analyze Progress**:
+   - Which steps are complete?
+   - What decisions have been made?
+   - Are there any inconsistencies?
+
+3. **Present Continuation Options**:
+   Based on current state, offer user choices:
+
+## Actions
+
+- Read: `{output_file}` completely (including frontmatter)
+- Parse: `stepsCompleted` from frontmatter
+- Analyze: Current document state
+
+## Output
+
+Present to user:
+
+```markdown
+## Workflow Continuation
+
+**Document found:** {output_file}
+**Steps completed:** {stepsCompleted}
+**Last step:** {last_step_name}
+
+### Current Document State
+{summary of what's been decided so far}
+
+### Continuation Options
+
+- **[C] Continue** - Resume from step {next_step}
+- **[R] Restart** - Start fresh (will archive existing document)
+- **[V] View** - Show complete document before deciding
+```
+
+## Continuation Flow
+
+After user selects [C]:
+1. Load the next incomplete step file
+2. Resume workflow from that point
+3. Continue normal step progression
+
+After user selects [R]:
+1. Archive existing document to `{output_file}.backup-{timestamp}`
+2. Return to step 1 for fresh initialization
+3. Proceed with new workflow
+
+## Success Metrics
+
+- Existing workflow detected and state loaded correctly
+- User informed of current progress
+- Continuation or restart handled smoothly
+- No data loss (archive before restart)
+
+## Failure Modes
+
+- Proceeding without user confirmation
+- Not loading complete existing document
+- Losing work by overwriting without archive
+- Misreading stepsCompleted array

package/pennyfarthing-dist/workflows/architecture/steps/step-02-context.md

@@ -0,0 +1,115 @@
+# Step 2: Context Analysis
+
+<step-meta>
+number: 2
+name: context-analysis
+gate: true
+</step-meta>
+
+## Mandatory Execution Rules
+
+- READ the complete step file before taking any action
+- ANALYZE loaded documents, don't assume or generate requirements
+- ALWAYS treat this as collaborative discovery between architectural peers
+- FOCUS on understanding project scope and requirements for architecture
+
+## Execution Protocols
+
+- Show your analysis before taking any action
+- Present A/P/C menu after generating context analysis
+- ONLY save when user chooses [C] Continue
+- Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- FORBIDDEN to load next step until [C] is selected
+
+## Purpose
+
+Analyze the project context and identify architectural concerns that will shape the decision.
+
+## Instructions
+
+1. **Extract Technical Constraints** from the PRD:
+   - Performance requirements (latency, throughput, scale)
+   - Security and compliance requirements
+   - Integration requirements with existing systems
+   - Technology mandates or restrictions
+
+2. **Map the Current Landscape**:
+   - What systems already exist?
+   - What are the integration points?
+   - What patterns are already in use?
+
+3. **Identify Key Concerns**:
+   - Scalability needs
+   - Reliability requirements
+   - Maintainability considerations
+   - Cost constraints
+
+## Actions
+
+- Read: `{planning_artifacts}/*prd*.md`
+- Read: `**/project-context.md` (if exists)
+- Grep: Search codebase for existing patterns
+
+## Output
+
+Add to session file:
+
+```markdown
+## Architecture Context
+
+### Technical Constraints
+- Performance: [requirements from PRD]
+- Security: [requirements]
+- Integration: [required touchpoints]
+
+### Current Landscape
+- Existing systems: [list]
+- Patterns in use: [list]
+- Tech stack: [languages, frameworks]
+
+### Key Concerns
+1. [Concern]: [Why it matters]
+2. [Concern]: [Why it matters]
+```
+
+<!-- GATE -->
+
+## Collaboration Menu (A/P/C)
+
+After generating context analysis, present choices:
+
+- **[A] Advanced Elicitation** - Use discovery protocols to develop deeper insights about project context and architectural implications
+- **[P] Party Mode** - Bring multiple perspectives to analyze project requirements from different architectural angles
+- **[C] Continue** - Save the content to the document and proceed to pattern selection
+- **[R] Revise** - Need to gather more information or clarify constraints
+
+## Advanced Elicitation Mode
+
+When user selects [A]:
+1. Ask probing questions about non-obvious constraints
+2. Explore edge cases and failure scenarios
+3. Identify implicit assumptions in requirements
+4. Dig deeper into integration complexity
+
+## Party Mode
+
+When user selects [P]:
+1. Present analysis from multiple viewpoints:
+   - **Security architect**: What could go wrong?
+   - **Performance engineer**: Where are the bottlenecks?
+   - **Operations**: How will this run in production?
+   - **Developer experience**: How maintainable is this?
+2. Synthesize perspectives into unified understanding
+
+## Success Metrics
+
+- Technical constraints extracted from PRD
+- Current landscape mapped accurately
+- Key concerns identified with rationale
+- User confirmed context before proceeding
+
+## Failure Modes
+
+- Generating requirements not found in documents
+- Proceeding without user confirmation
+- Missing critical constraints from PRD