@pennyfarthing/core 9.0.0 → 9.1.2

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

@@ -7,6 +7,14 @@ args: "[list|show [name]|set <name>|start <name> [--mode <mode>]|resume [name]|s
 
 # /workflow - Workflow Management
 
+<run>
+.pennyfarthing/scripts/workflow/list-workflows.sh
+</run>
+
+<output>
+Table of workflows with type indicators, steps/phases count, available modes, default status, and descriptions.
+</output>
+
 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
@@ -17,7 +25,7 @@ List all available workflows with type indicators.
 
 **Run:**
 ```bash
-.pennyfarthing/scripts workflow/list-workflows.sh
+.pennyfarthing/scripts/workflow/list-workflows.sh
 ```
 
 **Output:** Table of workflows with:
@@ -35,7 +43,7 @@ Show workflow details. If no name provided, shows current session's workflow.
 
 **Run:**
 ```bash
-.pennyfarthing/scripts workflow/show-workflow.sh [name]
+.pennyfarthing/scripts/workflow/show-workflow.sh [name]
 ```
 
 **Arguments:**
@@ -45,9 +53,9 @@ Show workflow details. If no name provided, shows current session's workflow.
 
 **Examples:**
 ```bash
-.pennyfarthing/scripts workflow/show-workflow.sh          # Current session workflow
-.pennyfarthing/scripts workflow/show-workflow.sh tdd      # Show TDD workflow
-.pennyfarthing/scripts workflow/show-workflow.sh trivial  # Show trivial workflow
+.pennyfarthing/scripts/workflow/show-workflow.sh          # Current session workflow
+.pennyfarthing/scripts/workflow/show-workflow.sh tdd      # Show TDD workflow
+.pennyfarthing/scripts/workflow/show-workflow.sh trivial  # Show trivial workflow
 ```
 
 **Output:** Workflow description, phase flow diagram, phases table, and trigger conditions.
@@ -63,7 +71,7 @@ Switch to a different workflow mid-session.
 **Steps:**
 1. Verify workflow exists:
    ```bash
-   .pennyfarthing/scripts workflow/show-workflow.sh <name>
+   .pennyfarthing/scripts/workflow/show-workflow.sh <name>
    ```
 
 2. Update the session file's workflow field:
@@ -84,7 +92,7 @@ Start a stepped workflow. Creates a new session and begins at step 1.
 
 **Run:**
 ```bash
-.pennyfarthing/scripts workflow/start-workflow.sh <name> [--mode <mode>]
+.pennyfarthing/scripts/workflow/start-workflow.sh <name> [--mode <mode>]
 ```
 
 **Arguments:**
@@ -107,7 +115,7 @@ Resume an interrupted stepped workflow from the last completed step.
 
 **Run:**
 ```bash
-.pennyfarthing/scripts workflow/resume-workflow.sh [name]
+.pennyfarthing/scripts/workflow/resume-workflow.sh [name]
 ```
 
 **Arguments:**
@@ -129,7 +137,7 @@ Show current stepped workflow progress.
 
 **Run:**
 ```bash
-.pennyfarthing/scripts workflow/workflow-status.sh
+.pennyfarthing/scripts/workflow/workflow-status.sh
 ```
 
 **Output:**
@@ -254,7 +262,7 @@ Fix session file when handoffs didn't update phase tracking properly. This corre
 
 **Run:**
 ```bash
-.pennyfarthing/scripts workflow/fix-session-phase.sh <story-id> <target-phase> [--dry-run]
+.pennyfarthing/scripts/workflow/fix-session-phase.sh <story-id> <target-phase> [--dry-run]
 ```
 
 **Arguments:**
@@ -271,16 +279,16 @@ Fix session file when handoffs didn't update phase tracking properly. This corre
 **Examples:**
 ```bash
 # Preview what would change
-.pennyfarthing/scripts workflow/fix-session-phase.sh 56-1 review --dry-run
+.pennyfarthing/scripts/workflow/fix-session-phase.sh 56-1 review --dry-run
 
 # Fix phase to review (after Dev completed)
-.pennyfarthing/scripts workflow/fix-session-phase.sh 56-1 review
+.pennyfarthing/scripts/workflow/fix-session-phase.sh 56-1 review
 
 # Fix phase to approved (after Reviewer approved)
-.pennyfarthing/scripts workflow/fix-session-phase.sh 56-1 approved
+.pennyfarthing/scripts/workflow/fix-session-phase.sh 56-1 approved
 
 # Using Jira key
-.pennyfarthing/scripts workflow/fix-session-phase.sh MSSCI-12190 approved
+.pennyfarthing/scripts/workflow/fix-session-phase.sh MSSCI-12190 approved
 ```
 
 **Valid phases by workflow:**

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

@@ -5,6 +5,14 @@ description: yq is a YAML processor. Use this skill when reading, modifying, or
 
 # yq - YAML Processor Skill
 
+<run>
+yq [expression] [file]
+</run>
+
+<output>
+YAML/JSON output depending on specified format
+</output>
+
 ## 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+).

package/pennyfarthing-dist/templates/settings.local.json.template

@@ -74,6 +74,15 @@
           }
         ]
       },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/hooks/schema-validation.sh"
+          }
+        ]
+      },
       {
         "matcher": "Edit|Write|Bash|Task",
         "hooks": [

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

@@ -1,5 +1,17 @@
 # Step 1: Initialize Architecture Session
 
+<purpose>
+Set up the architecture decision session by gathering inputs, detecting existing workflows, and establishing initial context for collaborative architectural discovery.
+</purpose>
+
+<instructions>
+Check for existing workflow and either resume from continuation or initialize fresh session. Gather required inputs (PRD, existing documentation, constraints), identify stakeholders, and present collaboration options to proceed.
+</instructions>
+
+<output>
+Session workspace initialized with frontmatter and either workflow continuation state or fresh initialization summary including discovered inputs, stakeholders, and ready-to-continue status.
+</output>
+
 <step-meta>
 number: 1
 name: initialize

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

@@ -1,5 +1,17 @@
 # Step 1b: Workflow Continuation Handler
 
+<purpose>
+Detect existing architecture workflow state from session file and provide user with options to continue, restart, or review previous progress before proceeding.
+</purpose>
+
+<instructions>
+Read the existing output file and parse frontmatter to identify completed steps and current progress. Analyze the document state, summarize decisions made so far, and present continuation options with data loss prevention (archiving).
+</instructions>
+
+<output>
+Workflow continuation information displayed with summary of completed steps, current document state, and user-selectable options (Continue/Restart/View) with archive confirmation if restarting.
+</output>
+
 <step-meta>
 number: 1b
 name: continue

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

@@ -1,5 +1,17 @@
 # Step 2: Context Analysis
 
+<purpose>
+Analyze project context and requirements to identify technical constraints, current system landscape, and key architectural concerns that will drive pattern selection and design decisions.
+</purpose>
+
+<instructions>
+Extract technical constraints from PRD (performance, security, integration requirements). Map existing systems and patterns. Identify scalability, reliability, maintainability, and cost concerns. Generate analysis and present A/P/C collaboration menu for refinement.
+</instructions>
+
+<output>
+Architecture Context section in session file with Technical Constraints, Current Landscape overview, and Key Concerns documented. Update frontmatter stepsCompleted array after user confirms [C].
+</output>
+
 <step-meta>
 number: 2
 name: context-analysis

package/pennyfarthing-dist/workflows/architecture/steps/step-03-patterns.md

@@ -1,5 +1,17 @@
 # Step 3: Pattern Selection
 
+<purpose>
+Identify and evaluate architectural patterns that address identified concerns with verification of current technology versions, trade-off analysis, and selection of patterns that best fit the project requirements.
+</purpose>
+
+<instructions>
+Survey applicable patterns (microservices, event-driven, CQRS, circuit breakers, etc.) based on context concerns. Search web for current stable versions and best practices. Evaluate trade-offs (complexity, team familiarity, overhead, system fit). Select 1-3 primary patterns with rationale.
+</instructions>
+
+<output>
+Pattern Analysis section with Technology Versions table, Candidate Patterns comparison, Selected Pattern(s) with justification, and Rejected Alternatives. Update frontmatter stepsCompleted array after user confirms [C].
+</output>
+
 <step-meta>
 number: 3
 name: pattern-selection

package/pennyfarthing-dist/workflows/architecture/steps/step-04-components.md

@@ -1,5 +1,17 @@
 # Step 4: Component Design
 
+<purpose>
+Define major system components, their responsibilities, boundaries, and dependencies based on selected patterns. Establish implementation consistency rules that prevent AI agents from making conflicting architectural choices.
+</purpose>
+
+<instructions>
+Identify primary components from selected patterns with clear responsibilities and data ownership. Define component boundaries and communication protocols. Map component dependencies. Document explicit consistency rules for AI implementation to ensure compatible implementations across different agents.
+</instructions>
+
+<output>
+Component Design section with ASCII/Mermaid component diagram, Component Responsibilities table, Boundary Decisions, and Implementation Consistency Rules. Update frontmatter stepsCompleted array after user confirms [C].
+</output>
+
 <step-meta>
 number: 4
 name: component-design

package/pennyfarthing-dist/workflows/architecture/steps/step-05-interfaces.md

@@ -1,5 +1,17 @@
 # Step 5: Interface Definition
 
+<purpose>
+Define APIs, internal contracts, and communication patterns between components. Establish naming conventions, error handling, and versioning strategies that ensure explicit, unambiguous contracts for consistent implementation.
+</purpose>
+
+<instructions>
+Define external APIs with authentication and request/response formats. Specify internal component communication (synchronous/asynchronous) with exact message formats. Establish naming conventions, error codes, and versioning strategy. Document contract enforcement rules explicit enough for independent implementations.
+</instructions>
+
+<output>
+Interface Definitions section with External APIs table, Internal Communication protocols, Conventions documented, and Contract Enforcement rules. Update frontmatter stepsCompleted array after user confirms [C].
+</output>
+
 <step-meta>
 number: 5
 name: interface-definition

package/pennyfarthing-dist/workflows/architecture/steps/step-06-risks.md

@@ -1,5 +1,17 @@
 # Step 6: Risk Assessment
 
+<purpose>
+Identify technical risks, failure modes, and mitigation strategies. Include risks specific to AI-assisted implementation such as ambiguous requirements or inconsistent interpretations that could cause implementation divergence.
+</purpose>
+
+<instructions>
+Identify technical risks (bottlenecks, single points of failure, security, data consistency, operational complexity). Assess impact/likelihood for each. Define mitigations and monitoring/alerting strategies. Identify AI implementation risks where agents might misinterpret requirements or diverge on implementation.
+</instructions>
+
+<output>
+Risk Assessment section with Technical Risks table, Failure Modes with recovery procedures, Security Considerations, AI Implementation Risks, and Operational Readiness plan. Update frontmatter stepsCompleted array after user confirms [C].
+</output>
+
 <step-meta>
 number: 6
 name: risk-assessment

package/pennyfarthing-dist/workflows/architecture/steps/step-07-document.md

@@ -1,5 +1,17 @@
 # Step 7: Decision Documentation
 
+<purpose>
+Consolidate all architecture decisions from previous steps into a formal Architecture Decision Record (ADR) or specification. Validate completeness and finalize the decision document for stakeholder review.
+</purpose>
+
+<instructions>
+Validate all previous step outputs are complete before proceeding. Choose appropriate document type (ADR/Architecture Spec/Design Doc). Compile comprehensive decision record including context, drivers, options, outcome, components, interfaces, risks, and consistency rules. Write to appropriate location with proper linking.
+</instructions>
+
+<output>
+Finalized architecture decision document (ADR or spec format) stored in docs/adr/ or appropriate location, with complete sections from all previous steps, validation confirmation, and completion summary. Update frontmatter stepsCompleted array with all steps completed.
+</output>
+
 <step-meta>
 number: 7
 name: documentation

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-01-validate-prerequisites.md

@@ -17,6 +17,31 @@ epicsTemplate: './templates/epics-template.md'
 # partyModeWorkflow: '{project_root}/.pennyfarthing/workflows/party-mode/workflow.yaml'
 ---
 
+<purpose>
+To validate that all required input documents exist and extract all requirements (FRs, NFRs, and additional requirements from UX/Architecture) needed for epic and story creation. This is a prerequisite step that ensures the foundation is solid before proceeding to epic design.
+</purpose>
+
+<instructions>
+1. Welcome the user to the comprehensive epic and story creation process
+2. Validate that required documents exist (PRD.md, Architecture.md, and optionally UX Design.md)
+3. Extract all Functional Requirements (FRs) from the PRD document
+4. Extract all Non-Functional Requirements (NFRs) from the PRD document
+5. Extract additional technical requirements from the Architecture document
+6. Extract UX requirements from the UX Design document (if it exists)
+7. Initialize the output template with extracted requirements
+8. Present extracted requirements to the user for review and confirmation
+9. Wait for user confirmation (C) before proceeding to the next step
+</instructions>
+
+<output>
+- Complete list of Functional Requirements (FRs) extracted from PRD
+- Complete list of Non-Functional Requirements (NFRs) extracted from PRD
+- Additional technical requirements from Architecture document
+- Additional UX requirements from UX Design document (if applicable)
+- Initialized epics.md file with all extracted requirements populated in the template
+- User confirmation that requirements are accurate and complete
+</output>
+
 # Step 1: Validate Prerequisites and Extract Requirements
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-02-design-epics.md

@@ -19,6 +19,29 @@ outputFile: '{planning_artifacts}/epics.md'
 epicsTemplate: './templates/epics-template.md'
 ---
 
+<purpose>
+To design and get explicit user approval for the epics_list that will organize all extracted requirements into user-value-focused epics. Each epic must be standalone, deliver complete functionality for its domain, and enable future epics without requiring them to function.
+</purpose>
+
+<instructions>
+1. Load and review the extracted requirements from the previous step
+2. Explain epic design principles (user-value first, incremental delivery, dependency-free within epic)
+3. Identify user value themes by analyzing the functional requirements
+4. Propose epic structure collaboratively with the user
+5. Create the epics_list showing epic titles, user outcomes, and FR coverage
+6. Create a requirements coverage map showing how each FR maps to an epic
+7. Present the epic list for user review and refinement
+8. Get user confirmation and explicit approval (C) before proceeding
+</instructions>
+
+<output>
+- Approved epics_list organized by user value with epic titles and goals
+- Functional requirement coverage map showing FR to epic mapping
+- Verified coverage of all extracted requirements
+- Epic structure validated for standalone operation and dependency flow
+- User explicit approval to proceed to story creation
+</output>
+
 # Step 2: Design Epic List
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-03-create-stories.md

@@ -19,6 +19,32 @@ outputFile: '{planning_artifacts}/epics.md'
 epicsTemplate: './templates/epics-template.md'
 ---
 
+<purpose>
+To generate all epics with their complete story breakdowns following the template structure exactly. Each story must be appropriately sized for single dev agent completion, have clear acceptance criteria using Given/When/Then format, and maintain proper story dependencies that flow sequentially without forward references.
+</purpose>
+
+<instructions>
+1. Load the approved epic structure from the previous step
+2. Explain story creation guidelines and the database/entity creation principle
+3. Process each epic sequentially in order
+4. For each epic: display overview, work with user to break down into stories, generate each story with acceptance criteria
+5. For each story: create title, user story (As a/I want/So that), and specific testable acceptance criteria
+6. Collaborate with user after each story to verify correctness and scope
+7. Append approved stories to the output file following template structure
+8. Verify all FRs are covered by stories and all placeholders are replaced
+9. Get user confirmation (C) before proceeding to final validation
+</instructions>
+
+<output>
+- Complete epics section with all approved epics
+- All stories for each epic with proper numbering (Epic N, Story M)
+- User story statements in As a/I want/So that format for each story
+- Acceptance Criteria using Given/When/Then format for each story
+- Verification that all FRs are covered by at least one story
+- Completed epics.md file following template structure exactly
+- User confirmation to proceed to final validation
+</output>
+
 # Step 3: Generate Epics and Stories
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-04-final-validation.md

@@ -19,6 +19,30 @@ outputFile: '{planning_artifacts}/epics.md'
 epicsTemplate: './templates/epics-template.md'
 ---
 
+<purpose>
+To validate that all requirements are completely covered by stories, verify story quality and dependencies are correct, ensure the document follows the template structure exactly, and confirm everything is ready for development work.
+</purpose>
+
+<instructions>
+1. Load the complete epic and story breakdown from the previous step
+2. Perform FR coverage validation to ensure every FR is covered by at least one story
+3. Validate architecture implementation requirements (starter template, database setup)
+4. Validate story quality (completable by single dev agent, clear acceptance criteria, no forward dependencies)
+5. Validate epic structure for user value and proper dependencies
+6. Perform critical dependency validation (epic independence and within-epic story flow)
+7. Update any remaining placeholders and verify formatting
+8. Get user confirmation (C) to proceed to import step
+</instructions>
+
+<output>
+- Verification that every FR has story coverage
+- Confirmation of proper architecture requirements implementation
+- Validation that stories are appropriately sized and have clear acceptance criteria
+- Confirmation of proper story dependencies (only depend on previous stories)
+- Final epics.md file with all placeholders replaced and formatting verified
+- User confirmation that document is complete and ready for development
+</output>
+
 # Step 4: Final Validation
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-05-import-to-future.md

@@ -15,6 +15,29 @@ futureYaml: '{project_root}/sprint/future.yaml'
 importScript: '{project_root}/.pennyfarthing/scripts/sprint/import-epic-to-future.sh'
 ---
 
+<purpose>
+To import the validated and complete epics and stories from the epics.md document into the sprint/future.yaml backlog system, making them available for sprint planning and story promotion. This is the final step that makes the epics accessible through the sprint management system.
+</purpose>
+
+<instructions>
+1. Determine the initiative name from the epics document (prompt user if not obvious)
+2. Run the import script in dry-run mode to show what will be added
+3. Display the preview to the user showing epic numbers, initiative structure, and story IDs
+4. Get user confirmation that the preview looks correct
+5. If confirmed, run the import script without dry-run to apply changes to future.yaml
+6. Verify the import by checking that epic appears in future.yaml with correct numbering
+7. Display completion message with epic number, initiative name, and story count
+</instructions>
+
+<output>
+- Initiative imported to sprint/future.yaml
+- Epic assigned with correct sequential number (epic-N)
+- All stories with proper IDs (epic-N-story-M format)
+- Dry-run preview showing exactly what will be imported
+- Verification that epic and stories are accessible via sprint commands
+- Completion message with next steps for sprint planning
+</output>
+
 # Step 5: Import to Future Backlog
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-01-analyze.md

@@ -1,54 +1,62 @@
 # Step 1: Analyze Current State
 
-Gather the current git state across all configured repositories.
+<purpose>
+Gather the current git state across all configured repositories and build a complete picture of uncommitted changes across ALL repos.
+</purpose>
+
+<instructions>
+1. Run the multi-repo git status script to show branch, staged/unstaged changes, and unpushed commits
+2. For each repo with changes, gather detailed diffs and commit patterns
+3. Check for active work sessions to understand context
+4. Verify pre-flight checks (no merge conflicts, develop branches up to date, no secrets)
+5. Present findings in structured format with analysis results by repo
+</instructions>
+
+<output>
+Analysis results grouped by repo including:
+- Current branch name
+- Count of unpushed commits
+- List of uncommitted changes with status (M/A/D/??)
+- Any warnings or issues found
+- Ready for user choice: [A] to analyze specific repo, or [C] to continue
+</output>
 
 ## Objective
 
-Build a complete picture of:
-- Uncommitted changes in each repo
-- Unpushed commits on develop
-- Active worktrees and their state
-- Active work sessions that might explain changes
+Build a complete picture of uncommitted changes across ALL repos defined in `.claude/project/pennyfarthing-settings.yaml`.
 
 ## Execution
 
-### 1.0 Check Stash (CRITICAL - DO THIS FIRST)
+### 1.1 Gather Git Status (All Repos)
+
+**CRITICAL: Use the multi-repo script, not plain `git status`.**
 
 ```bash
-echo "=== Stash Status (CRITICAL) ==="
-git stash list
+.pennyfarthing/scripts/git/git-status-all.sh
 ```
 
-**If stash has ANY entries:**
-1. Show the stash contents to user
-2. Ask: "Stash contains saved work. Clear it completely before proceeding?"
-3. If user agrees: `git stash clear`
-4. If user declines: **STOP** - do not proceed with cleanup
+This shows branch, staged/unstaged changes, and unpushed commits for **all repos** defined in the project configuration.
 
-**This prevents:**
-- Losing work that was stashed from a previous interrupted cleanup
-- Confusion about what changes belong to what
-- Accidentally clearing someone else's stashed work
+### 1.2 For Each Repo with Changes
 
-### 1.1 Gather Git Status (All Repos)
+For repos with uncommitted changes, gather more detail:
 
 ```bash
-.pennyfarthing/scripts/git/git-status-all.sh
-```
+# Show full diff for a specific repo
+git -C {repo_path} diff
 
-This shows branch, staged/unstaged changes, and unpushed commits for all repos.
+# Check the branch
+git -C {repo_path} branch --show-current
+```
 
-### 1.2 Check Recent Commit Patterns
+### 1.3 Check Recent Commit Patterns
 
 ```bash
-echo "=== Recent Commits (for message style) ==="
-git log --oneline -10
-echo ""
-echo "=== Recent Branches ==="
-git branch --sort=-committerdate | head -10
+# In each repo with changes, check commit style
+git -C {repo_path} log --oneline -5
 ```
 
-### 1.3 Check Active Work Sessions
+### 1.4 Check Active Work Sessions
 
 ```bash
 echo "=== Active Work Sessions ==="
@@ -57,21 +65,12 @@ ls -la .session/*.md 2>/dev/null || echo "No active sessions"
 
 If sessions exist, read headers to understand what work is in progress.
 
-### 1.4 Check Worktree Status
-
-```bash
-echo "=== Worktree Status ==="
-.pennyfarthing/scripts/git/worktree-manager.sh status 2>/dev/null || echo "No worktrees"
-```
-
-### 1.5 Pre-flight Checks
-
-**Before proceeding, verify:**
+## Pre-flight Checks
 
 | Check | Status | Action if Failed |
 |-------|--------|------------------|
 | No merge conflicts | ☐ | Resolve conflicts first |
-| develop is up to date | ☐ | `git pull origin develop` |
+| Each repo's develop up to date | ☐ | `git -C {repo} pull origin develop` |
 | No uncommitted secrets | ☐ | Add to .gitignore |
 
 ## Output Format
@@ -81,7 +80,7 @@ Present findings in this structure:
 ```
 ## Analysis Results
 
-### Repo: {repo_name}
+### Repo: {repo_name} (path: {repo_path})
 Branch: {current_branch}
 Unpushed: {count} commits
 
@@ -89,6 +88,9 @@ Unpushed: {count} commits
 - {file_path} ({status: M/A/D/??})
 - ...
 
+### Repo: {another_repo}
+...
+
 ### Warnings
 - {any issues found}
 ```