@pennyfarthing/core 9.0.0 → 9.0.3

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-01-discovery.md

@@ -11,6 +11,12 @@ prdPurpose: '../data/prd-purpose.md'
 
 # Step 1: Document Discovery & Confirmation
 
+<purpose>Handle fresh context validation by confirming PRD path, discovering and loading input documents from frontmatter, and initializing the validation report.</purpose>
+
+<instructions>Confirm PRD file path is valid; load complete PRD document and frontmatter; extract and reload input documents from inputDocuments array; create validation report with PRD metadata; confirm readiness to begin validation checks.</instructions>
+
+<output>Loaded PRD document with complete context, extracted and verified input documents, initialized validation report with PRD metadata, ready for format detection and validation checks.</output>
+
 ## STEP GOAL:
 
 Handle fresh context validation by confirming PRD path, discovering and loading input documents from frontmatter, and initializing the validation report.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-02-format-detection.md

@@ -11,6 +11,12 @@ validationReportPath: '{validation_report_path}'
 
 # Step 2: Format Detection & Structure Analysis
 
+<purpose>Detect if PRD follows BMAD format and route appropriately - classify as BMAD Standard, BMAD Variant, or Non-Standard format.</purpose>
+
+<instructions>Analyze PRD structure to detect format conformance; identify section presence and order; classify format type; for non-standard formats, offer optional parity check; update validation report with format classification; route to appropriate next validation step.</instructions>
+
+<output>PRD format classification (BMAD Standard/Variant/Non-Standard), structure analysis summary, validation report updated with format findings, ready for format-specific validation checks.</output>
+
 ## STEP GOAL:
 
 Detect if PRD follows BMAD format and route appropriately - classify as BMAD Standard / BMAD Variant / Non-Standard, with optional parity check for non-standard formats.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-02b-parity-check.md

@@ -10,6 +10,12 @@ validationReportPath: '{validation_report_path}'
 
 # Step 2B: Document Parity Check
 
+<purpose>Analyze non-standard PRD and identify gaps to achieve BMAD PRD parity, presenting user with options for how to proceed.</purpose>
+
+<instructions>Load and deeply analyze non-standard PRD structure; identify missing sections and gaps relative to BMAD standard; map existing content to BMAD sections; prepare parity analysis with specific recommendations; present user with conversion options (full conversion, selective upgrade, continue as-is).</instructions>
+
+<output>Detailed parity analysis documenting gaps between current format and BMAD standard, conversion recommendations with effort estimates, and user-selected approach for proceeding with validation.</output>
+
 ## STEP GOAL:
 
 Analyze non-standard PRD and identify gaps to achieve BMAD PRD parity, presenting user with options for how to proceed.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-03-density-validation.md

@@ -10,6 +10,12 @@ validationReportPath: '{validation_report_path}'
 
 # Step 3: Information Density Validation
 
+<purpose>Validate PRD meets BMAD information density standards by scanning for conversational filler, wordy phrases, and redundant expressions that violate conciseness principles.</purpose>
+
+<instructions>Analyze PRD content for information density violations; scan for anti-patterns including conversational filler, wordiness, redundancy, and verbose phrasing; calculate density metrics; document violations with location and severity; update validation report with findings; optionally suggest improvements.</instructions>
+
+<output>Density validation report with identified violations, severity classification, specific locations, density metrics, and optional improvement suggestions.</output>
+
 ## STEP GOAL:
 
 Validate PRD meets BMAD information density standards by scanning for conversational filler, wordy phrases, and redundant expressions that violate conciseness principles.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-04-brief-coverage-validation.md

@@ -11,6 +11,12 @@ validationReportPath: '{validation_report_path}'
 
 # Step 4: Product Brief Coverage Validation
 
+<purpose>Validate that PRD covers all content from Product Brief (if brief was used as input), mapping brief content to PRD sections and identifying gaps.</purpose>
+
+<instructions>Check if product brief exists in inputDocuments; if brief available, load it and analyze key content areas; map brief content to PRD sections; identify coverage gaps and unmapped content; calculate coverage percentage; update validation report with coverage findings.</instructions>
+
+<output>Coverage validation report with mapped brief content, identified coverage gaps, coverage percentage metric, and recommendations for addressing gaps.</output>
+
 ## STEP GOAL:
 
 Validate that PRD covers all content from Product Brief (if brief was used as input), mapping brief content to PRD sections and identifying gaps.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-05-measurability-validation.md

@@ -10,6 +10,12 @@ validationReportPath: '{validation_report_path}'
 
 # Step 5: Measurability Validation
 
+<purpose>Validate that all Functional Requirements (FRs) and Non-Functional Requirements (NFRs) are measurable, testable, and follow proper format without implementation details.</purpose>
+
+<instructions>Extract all FRs and NFRs from PRD; analyze each requirement for measurability indicators (numeric targets, acceptance criteria, pass/fail conditions); check for implementation leakage; identify non-measurable requirements; classify severity of measurability issues; update validation report.</instructions>
+
+<output>Measurability validation report with analysis of each requirement, identification of non-measurable requirements, severity classification, implementation leakage findings, and recommendations for improvement.</output>
+
 ## STEP GOAL:
 
 Validate that all Functional Requirements (FRs) and Non-Functional Requirements (NFRs) are measurable, testable, and follow proper format without implementation details.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-06-traceability-validation.md

@@ -10,6 +10,12 @@ validationReportPath: '{validation_report_path}'
 
 # Step 6: Traceability Validation
 
+<purpose>Validate the traceability chain from Executive Summary → Success Criteria → User Journeys → Functional Requirements is intact, ensuring every requirement traces back to a user need or business objective.</purpose>
+
+<instructions>Extract vision, success criteria, user journeys, and requirements from PRD; map traceability links from requirements back to journeys, success criteria, and vision; identify orphaned requirements without traceability; verify bidirectional traceability; calculate traceability completeness; update validation report.</instructions>
+
+<output>Traceability validation report with traceability chain visualization, identified gaps and orphaned requirements, bidirectional traceability verification, traceability coverage metrics.</output>
+
 ## STEP GOAL:
 
 Validate the traceability chain from Executive Summary → Success Criteria → User Journeys → Functional Requirements is intact, ensuring every requirement traces back to a user need or business objective.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-07-implementation-leakage-validation.md

@@ -10,6 +10,12 @@ validationReportPath: '{validation_report_path}'
 
 # Step 7: Implementation Leakage Validation
 
+<purpose>Ensure Functional Requirements and Non-Functional Requirements don't include implementation details - they should specify WHAT, not HOW.</purpose>
+
+<instructions>Extract all FRs and NFRs from PRD; scan each requirement for implementation keywords and patterns (specific technologies, frameworks, methodologies, HOW details); identify leakage violations; classify by severity; calculate leakage percentage; update validation report with findings and recommendations.</instructions>
+
+<output>Implementation leakage validation report with identified violations, severity classification, specific examples of leakage, leakage metrics, and recommendations for abstraction improvements.</output>
+
 ## STEP GOAL:
 
 Ensure Functional Requirements and Non-Functional Requirements don't include implementation details - they should specify WHAT, not HOW.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-08-domain-compliance-validation.md

@@ -12,6 +12,12 @@ domainComplexityData: '../data/domain-complexity.csv'
 
 # Step 8: Domain Compliance Validation
 
+<purpose>Validate domain-specific requirements are present for high-complexity domains (Healthcare, Fintech, GovTech, etc.), ensuring regulatory and compliance requirements are properly documented.</purpose>
+
+<instructions>Determine project domain from PRD frontmatter; check domain complexity level from CSV data; for high-complexity domains, verify domain-specific requirements section exists and covers applicable regulations; analyze compliance coverage; identify compliance gaps; update validation report.</instructions>
+
+<output>Domain compliance validation report with complexity assessment, identified compliance requirements, coverage analysis, compliance gaps, and recommendations for domain-specific improvements.</output>
+
 ## STEP GOAL:
 
 Validate domain-specific requirements are present for high-complexity domains (Healthcare, Fintech, GovTech, etc.), ensuring regulatory and compliance requirements are properly documented.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-09-project-type-validation.md

@@ -12,6 +12,12 @@ projectTypesData: '../data/project-types.csv'
 
 # Step 9: Project-Type Compliance Validation
 
+<purpose>Validate project-type specific requirements are properly documented - different project types (api_backend, web_app, mobile_app, etc.) have different required and excluded sections.</purpose>
+
+<instructions>Determine project type from PRD frontmatter; load project-type requirements from CSV data; verify all required sections for project type are present; check for prohibited sections; analyze type-specific requirement coverage; identify gaps; update validation report.</instructions>
+
+<output>Project-type compliance validation report with required/optional section verification, identified gaps, type-specific coverage analysis, and recommendations for project-type conformance.</output>
+
 ## STEP GOAL:
 
 Validate project-type specific requirements are properly documented - different project types (api_backend, web_app, mobile_app, etc.) have different required and excluded sections.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-10-smart-validation.md

@@ -11,6 +11,12 @@ advancedElicitationTask: '{project_root}/_bmad/core/workflows/advanced-elicitati
 
 # Step 10: SMART Requirements Validation
 
+<purpose>Validate Functional Requirements meet SMART quality criteria (Specific, Measurable, Attainable, Relevant, Traceable), ensuring high-quality requirements that can be implemented and tested.</purpose>
+
+<instructions>Extract all functional requirements from PRD; evaluate each requirement against SMART criteria; assess specificity, measurability, attainability, relevance, and traceability; score each requirement on SMART completeness; identify low-scoring requirements; calculate overall quality metrics; update validation report.</instructions>
+
+<output>SMART validation report with individual requirement scores, identified low-quality requirements, SMART criteria assessment, quality metrics, and improvement recommendations for each criterion.</output>
+
 ## STEP GOAL:
 
 Validate Functional Requirements meet SMART quality criteria (Specific, Measurable, Attainable, Relevant, Traceable), ensuring high-quality requirements.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-11-holistic-quality-validation.md

@@ -11,6 +11,12 @@ advancedElicitationTask: '{project_root}/_bmad/core/workflows/advanced-elicitati
 
 # Step 11: Holistic Quality Assessment
 
+<purpose>Assess the PRD as a cohesive, compelling document - evaluating document flow, dual audience effectiveness (humans and LLMs), BMAD PRD principles compliance, and overall quality rating.</purpose>
+
+<instructions>Review PRD holistically for flow and coherence; assess readability and clarity for human audience; evaluate machine-readability and AI-assistant usefulness; evaluate alignment with BMAD principles; identify strengths and improvement opportunities; provide overall quality rating and recommendations; update validation report.</instructions>
+
+<output>Holistic quality assessment report with document flow analysis, audience effectiveness evaluation, BMAD principles alignment, identified strengths and weaknesses, overall quality rating, and strategic improvement recommendations.</output>
+
 ## STEP GOAL:
 
 Assess the PRD as a cohesive, compelling document - evaluating document flow, dual audience effectiveness (humans and LLMs), BMAD PRD principles compliance, and overall quality rating.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-12-completeness-validation.md

@@ -11,6 +11,12 @@ validationReportPath: '{validation_report_path}'
 
 # Step 12: Completeness Validation
 
+<purpose>Final comprehensive completeness check - validate no template variables remain, each section has required content, section-specific completeness requirements are met, and frontmatter is properly populated.</purpose>
+
+<instructions>Scan PRD for remaining template variables and placeholders; verify all required sections have substantial content; check section-specific completeness requirements; validate frontmatter contains all required metadata; calculate completeness percentage; identify missing elements; update validation report with completeness findings.</instructions>
+
+<output>Completeness validation report with template variable scan results, section-by-section completeness assessment, frontmatter validation, completeness percentage metric, and list of outstanding items.</output>
+
 ## STEP GOAL:
 
 Final comprehensive completeness check - validate no template variables remain, each section has required content, section-specific completeness, and frontmatter is properly populated.

package/pennyfarthing-dist/workflows/prd/steps-v/step-v-13-report-complete.md

@@ -9,6 +9,12 @@ prdFile: '{prd_file_path}'
 
 # Step 13: Validation Report Complete
 
+<purpose>Finalize validation report, summarize all findings from validation steps, present summary to user conversationally, and offer actionable next steps including editing or publication.</purpose>
+
+<instructions>Aggregate all validation step findings into comprehensive report; create executive summary with key metrics and recommendations; prepare conversational presentation for user; identify critical issues, major issues, and minor issues; recommend prioritized remediation path; offer next steps including editing workflow or publication options.</instructions>
+
+<output>Complete validation report with executive summary, aggregated findings from all validation checks, severity classification of issues, prioritized remediation recommendations, and options for next workflow steps.</output>
+
 ## STEP GOAL:
 
 Finalize validation report, summarize all findings from steps 1-12, present summary to user conversationally, and offer actionable next steps.

package/pennyfarthing-dist/workflows/product-brief/steps/step-01-init.md

@@ -10,6 +10,24 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 productBriefTemplate: '../product-brief.template.md'
 ---
 
+<purpose>
+Initialize the product brief workflow by detecting continuation state and setting up the document structure for collaborative product discovery.
+</purpose>
+
+<instructions>
+1. Check for existing workflow state by looking for the output document
+2. If document exists with stepsCompleted, hand off to step-01b for continuation
+3. If fresh workflow, discover input documents and create initial document from template
+4. Update frontmatter with discovered documents
+5. Present results to user and proceed to next step
+</instructions>
+
+<output>
+- Initialized product brief document at {outputFile}
+- Frontmatter updated with stepsCompleted: [1] and inputDocuments array
+- User confirmation of document setup and discovered input documents
+</output>
+
 # Step 1: Product Brief Initialization
 
 ## STEP GOAL:

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

@@ -6,6 +6,25 @@ description: 'Resume the product brief workflow from where it was left off, ensu
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 ---
 
+<purpose>
+Resume the product brief workflow from where it was left off, ensuring smooth continuation with full context restoration.
+</purpose>
+
+<instructions>
+1. Analyze current workflow state from document frontmatter
+2. Reload all previously loaded input documents for context
+3. Present progress report and determine next step based on lastStep value
+4. If workflow complete, suggest next workflow options
+5. If workflow incomplete, load appropriate next step file
+</instructions>
+
+<output>
+- Current workflow state analyzed and presented to user
+- All input documents reloaded for context continuity
+- Next step identified and ready to load
+- User confirmation before proceeding to next step
+</output>
+
 # Step 1B: Product Brief Continuation
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/product-brief/steps/step-02-vision.md

@@ -11,6 +11,28 @@ advancedElicitationTask: '{project_root}/_bmad/core/workflows/advanced-elicitati
 partyModeWorkflow: '{project_root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 
+<purpose>
+Conduct comprehensive product vision discovery to define the core problem, solution, and unique value proposition through collaborative analysis.
+</purpose>
+
+<instructions>
+1. Begin vision discovery conversation exploring the core problem
+2. Explore problem understanding from multiple angles
+3. Analyze existing solutions and gaps
+4. Collaborate on solution vision and differentiators
+5. Generate Executive Summary and Core Vision content
+6. Present A/P/C menu for optional advanced elicitation or party mode
+7. Save content to document when user selects C
+</instructions>
+
+<output>
+- Executive Summary capturing product essence
+- Core Vision section with problem statement and solution
+- Unique Differentiators section highlighting competitive advantage
+- Document updated at {outputFile} with stepsCompleted: [1, 2]
+- User ready to proceed to target user discovery
+</output>
+
 # Step 2: Product Vision Discovery
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/product-brief/steps/step-03-users.md

@@ -11,6 +11,28 @@ advancedElicitationTask: '{project_root}/_bmad/core/workflows/advanced-elicitati
 partyModeWorkflow: '{project_root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 
+<purpose>
+Define target users with rich personas and map their key interactions with the product through collaborative user research and journey mapping.
+</purpose>
+
+<instructions>
+1. Begin user discovery conversation identifying who experiences the problem
+2. Develop rich personas for primary user segments
+3. Explore secondary user segments and their roles
+4. Map user journeys through discovery, onboarding, core usage, and success moments
+5. Generate Target Users content with personas and journey maps
+6. Present A/P/C menu for optional advanced elicitation or party mode
+7. Save content to document when user selects C
+</instructions>
+
+<output>
+- Target Users section with Primary and Secondary user personas
+- User Journey section mapping key interaction points
+- Rich persona descriptions with motivations and goals
+- Document updated at {outputFile} with stepsCompleted: [1, 2, 3]
+- User ready to proceed to success metrics definition
+</output>
+
 # Step 3: Target Users Discovery
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/product-brief/steps/step-04-metrics.md

@@ -11,6 +11,29 @@ advancedElicitationTask: '{project_root}/_bmad/core/workflows/advanced-elicitati
 partyModeWorkflow: '{project_root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 
+<purpose>
+Define comprehensive success metrics that include user success, business objectives, and key performance indicators through collaborative metric definition aligned with product vision and user value.
+</purpose>
+
+<instructions>
+1. Begin success metrics discovery from user perspective
+2. Define measurable user success metrics and outcomes
+3. Explore business objectives and success criteria
+4. Develop specific, measurable KPIs with targets and timeframes
+5. Ensure metrics align with product vision and drive decisions
+6. Generate Success Metrics content with user, business, and KPI sections
+7. Present A/P/C menu for optional advanced elicitation or party mode
+8. Save content to document when user selects C
+</instructions>
+
+<output>
+- Success Metrics section defining user success outcomes
+- Business Objectives section with strategic goals
+- Key Performance Indicators section with measurable targets
+- Document updated at {outputFile} with stepsCompleted: [1, 2, 3, 4]
+- User ready to proceed to MVP scope definition
+</output>
+
 # Step 4: Success Metrics Definition
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/product-brief/steps/step-05-scope.md

@@ -11,6 +11,30 @@ advancedElicitationTask: '{project_root}/_bmad/core/workflows/advanced-elicitati
 partyModeWorkflow: '{project_root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 
+<purpose>
+Define MVP scope with clear boundaries and outline future vision through collaborative scope negotiation that balances ambition with realism.
+</purpose>
+
+<instructions>
+1. Begin scope definition conversation focused on MVP mindset
+2. Define core features essential for solving the problem
+3. Establish out-of-scope boundaries and deferred features
+4. Define MVP success criteria and validation gates
+5. Explore future vision and long-term capabilities
+6. Generate MVP Scope content with core features and future vision
+7. Present A/P/C menu for optional advanced elicitation or party mode
+8. Save content to document when user selects C
+</instructions>
+
+<output>
+- MVP Scope section with Core Features defined
+- Out of Scope for MVP section with clear boundaries
+- MVP Success Criteria section with validation gates
+- Future Vision section with long-term capabilities
+- Document updated at {outputFile} with stepsCompleted: [1, 2, 3, 4, 5]
+- User ready to proceed to workflow completion
+</output>
+
 # Step 5: MVP Scope Definition
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/product-brief/steps/step-06-complete.md

@@ -6,6 +6,28 @@ description: 'Complete the product brief workflow, update status files, and sugg
 outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 ---
 
+<purpose>
+Complete the product brief workflow, update status files, and provide guidance on logical next steps for continued product development.
+</purpose>
+
+<instructions>
+1. Announce workflow completion and summarize accomplishments
+2. Update main workflow status file with completion information
+3. Validate product brief completeness and consistency
+4. Suggest logical next workflow steps (PRD, UX design, etc.)
+5. Present completion menu and provide next step guidance
+6. End workflow session gracefully
+</instructions>
+
+<output>
+- Completion announcement with summary of accomplishments
+- Workflow status file updated with completion timestamp
+- Quality validation results confirming completeness and consistency
+- Next step recommendations provided to user
+- Final document location: {outputFile}
+- Workflow marked as complete
+</output>
+
 # Step 6: Product Brief Completion
 
 ## STEP GOAL:

package/pennyfarthing-dist/workflows/project-context/steps/step-01-discover.md

@@ -1,5 +1,27 @@
 # Step 1: Context Discovery & Initialization
 
+<purpose>
+Discover the project's technology stack, existing patterns, and critical implementation rules that AI agents must follow when writing code.
+</purpose>
+
+<instructions>
+1. Check for existing project context (project-context.md)
+2. Discover project technology stack from package files and config
+3. Identify existing code patterns, naming conventions, and organization
+4. Extract critical implementation rules that AI agents need
+5. Initialize project context document with discovered information
+6. Present discovery summary to user
+</instructions>
+
+<output>
+- Existing project context detection status
+- Identified technology stack with versions
+- Found implementation patterns and conventions
+- Initialized project context document
+- Discovery summary presented to user
+- User ready to proceed to step-02
+</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

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

@@ -1,5 +1,36 @@
 # Step 2: Context Rules Generation
 
+<purpose>
+Collaboratively generate specific, critical rules that AI agents must follow when implementing code in this project, organized by technology stack, language, framework, testing, code quality, workflow, and anti-patterns.
+</purpose>
+
+<instructions>
+1. Document exact technology stack and versions from discovery
+2. Generate language-specific rules for unobvious patterns
+3. Generate framework-specific rules for project conventions
+4. Generate testing rules for consistency
+5. Generate code quality and style rules
+6. Generate development workflow rules
+7. Identify critical don't-miss rules and anti-patterns
+8. Present A/P/C menu after each category for user validation
+9. Append validated rules to project context file
+10. Update frontmatter with completed sections
+</instructions>
+
+<output>
+- Technology stack and versions documented
+- Language-specific rules for each category
+- Framework-specific rules for project patterns
+- Testing rules for consistency
+- Code quality and style rules
+- Development workflow rules
+- Critical anti-pattern rules documented
+- A/P/C menu selections processed
+- Rules appended to project context file
+- Frontmatter updated with sections_completed
+- Ready to proceed to step-03
+</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/project-context/steps/step-03-complete.md

@@ -1,5 +1,33 @@
 # Step 3: Context Completion & Finalization
 
+<purpose>
+Complete the project context file, optimize it for LLM efficiency, validate all critical rules are captured and actionable, and provide guidance for usage and maintenance.
+</purpose>
+
+<instructions>
+1. Review complete context file for content and structure analysis
+2. Optimize content for LLM context efficiency
+3. Remove redundant or obvious information
+4. Ensure final structure follows optimized format
+5. Present completion summary to user based on skill level
+6. Update frontmatter with completion status
+7. Add usage guidelines section for agents and humans
+8. Validate all critical rules are complete
+9. Provide clear next steps for agent integration and maintenance
+</instructions>
+
+<output>
+- Complete context file reviewed and optimized
+- Content optimized for LLM efficiency
+- Final structure validated
+- Completion summary presented to user
+- Frontmatter updated with status: 'complete'
+- Usage guidelines section appended
+- Validation checklist completed
+- File ready for AI agent consumption
+- Next steps provided for maintenance and evolution
+</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/quick-dev/steps/step-01-mode-detection.md

@@ -8,6 +8,27 @@ nextStepFile_modeA: './step-03-execute.md'
 nextStepFile_modeB: './step-02-context-gathering.md'
 ---
 
+<purpose>
+Determine whether the user has provided a tech-spec file (Mode A) or direct task instructions (Mode B). Capture baseline commit, load project context if available, and evaluate escalation threshold to decide whether the request fits in Quick Dev or needs broader planning workflows.
+</purpose>
+
+<instructions>
+1. Capture the baseline commit hash (or "NO_GIT" if not a git repo)
+2. Load project context if exists in the codebase
+3. Parse user input to determine Mode A (tech-spec path provided) or Mode B (direct task description)
+4. For Mode B, evaluate escalation signals and present appropriate choices
+5. Set state variables for all subsequent steps
+6. Provide explicit NEXT directive indicating which step to load or workflow to exit to
+</instructions>
+
+<output>
+- `{baseline_commit}` - Git HEAD at workflow start (or "NO_GIT")
+- `{execution_mode}` - Either "tech-spec" or "direct"
+- `{tech_spec_path}` - Path to tech-spec file (only if Mode A)
+- `{project_context}` - Loaded project context if available
+- Explicit NEXT directive showing the next step to load or workflow to exit to
+</output>
+
 # Step 1: Mode Detection
 
 **Goal:** Determine execution mode, capture baseline, handle escalation if needed.

package/pennyfarthing-dist/workflows/quick-dev/steps/step-02-context-gathering.md

@@ -7,6 +7,29 @@ thisStepFile: './step-02-context-gathering.md'
 nextStepFile: './step-03-execute.md'
 ---
 
+<purpose>
+Gather sufficient context for Mode B (direct instructions) to create a realistic mental plan of tasks. Identify affected files, detect existing code patterns, note dependencies, and create preliminary acceptance criteria based on the user's request.
+</purpose>
+
+<instructions>
+1. Search codebase to identify files relevant to the user's task description
+2. Examine those files to discover existing patterns, conventions, and error handling approaches
+3. Identify dependencies (libraries, modules, configs) that may be affected
+4. Synthesize gathered information into a mental plan with ordered tasks and inferred acceptance criteria
+5. Present the plan to the user for confirmation before proceeding to execution
+6. Accept user feedback (y/n/adjust) and continue or refine the plan accordingly
+</instructions>
+
+<output>
+- List of files to modify (with their purposes)
+- Key patterns identified in the codebase
+- Dependencies and related files that might be affected
+- Mental plan with ordered tasks
+- Inferred acceptance criteria from the user request
+- User confirmation to proceed (y/n/adjust)
+- Explicit NEXT directive to step-03-execute.md once confirmed
+</output>
+
 # Step 2: Context Gathering (Direct Mode)
 
 **Goal:** Quickly gather context for direct instructions - files, patterns, dependencies.

package/pennyfarthing-dist/workflows/quick-dev/steps/step-03-execute.md

@@ -7,6 +7,31 @@ thisStepFile: './step-03-execute.md'
 nextStepFile: './step-04-self-check.md'
 ---
 
+<purpose>
+Execute all planned tasks in sequence without pausing for approval between tasks. Write code following identified patterns, run tests to verify functionality, and only halt for blocking issues that require user guidance.
+</purpose>
+
+<instructions>
+1. For each task in the plan (from tech-spec or mental plan):
+   - Load relevant source files to understand context
+   - Implement changes following existing code patterns
+   - Write or update tests to verify the specific acceptance criteria for this task
+   - Mark task complete and move to the next task immediately
+2. Handle errors pragmatically: retry, look for patterns, test incrementally
+3. Only halt and request guidance if facing a blocking issue (3+ failures, ambiguous decision)
+4. Track all completed work for the next step (self-check)
+5. Once all tasks are complete (or blocked), proceed to step-04-self-check.md
+</instructions>
+
+<output>
+- Implemented code changes for all tasks
+- Tests written and passing for new/modified functionality
+- All existing tests still passing
+- List of completed tasks checked off
+- Any blocking issues documented with clear explanation
+- Ready to transition to self-check phase
+</output>
+
 # Step 3: Execute Implementation
 
 **Goal:** Implement all tasks, write tests, follow patterns, handle errors.

package/pennyfarthing-dist/workflows/quick-dev/steps/step-04-self-check.md

@@ -7,6 +7,28 @@ thisStepFile: './step-04-self-check.md'
 nextStepFile: './step-05-adversarial-review.md'
 ---
 
+<purpose>
+Perform a comprehensive self-audit of the implementation before external review. Verify that all tasks are complete, tests pass, acceptance criteria are satisfied, and code follows project patterns. Update tech-spec status if in Mode A. Provide a clear summary for the adversarial review phase.
+</purpose>
+
+<instructions>
+1. Verify all tasks marked complete with no skipped work
+2. Run full test suite and confirm all tests passing
+3. For each acceptance criterion, verify it is demonstrably satisfied
+4. Review all modified code to ensure it follows existing patterns and project-context rules
+5. If Mode A (tech-spec): load tech-spec file, mark all tasks as [x], update status to "Implementation Complete", save
+6. Present implementation summary to transition to review phase
+7. Load step-05-adversarial-review.md to proceed
+</instructions>
+
+<output>
+- Verification checklist: Tasks ✓, Tests ✓, AC ✓, Patterns ✓
+- Test suite run results (all passing)
+- Tech-spec updated with completion status (Mode A only)
+- Implementation summary showing what was built, files modified, and test status
+- Transition message to adversarial review phase
+</output>
+
 # Step 4: Self-Check
 
 **Goal:** Audit completed work against tasks, tests, AC, and patterns before external review.