@pennyfarthing/core 9.0.0 → 9.1.2

package/pennyfarthing-dist/workflows/ux-design/steps/step-03-core-experience.md

@@ -1,5 +1,11 @@
 # Step 3: Core Experience Definition
 
+<purpose>Define the core user experience, platform requirements, and what makes interactions effortless through collaborative discovery of the primary user action and critical success moments.</purpose>
+
+<instructions>Identify the ONE core user action. Explore platform requirements (web, mobile, desktop). Identify effortless interactions and critical success moments. Synthesize experience principles. Generate core experience content with defining experience, platform strategy, effortless interactions, critical success moments, and experience principles sections. Present A/P/C menu. Save when user selects C.</instructions>
+
+<output>Core user experience content appended to specification including platform strategy and guiding experience principles, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-04-emotional-response.md

@@ -1,5 +1,11 @@
 # Step 4: Desired Emotional Response
 
+<purpose>Define desired emotional responses users should feel when using the product through collaborative exploration of emotional goals and emotional journey mapping.</purpose>
+
+<instructions>Explore core emotional goals. Identify emotional journey mapping across user lifecycle stages. Define micro-emotions (confidence vs confusion, trust vs skepticism). Connect emotions to UX design decisions. Validate emotional goals alignment with product vision. Generate emotional response content with primary goals, journey mapping, micro-emotions, design implications, and emotional design principles sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>Emotional response content appended to specification including emotional design principles and UX implications, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-05-inspiration.md

@@ -1,5 +1,11 @@
 # Step 5: UX Pattern Analysis & Inspiration
 
+<purpose>Analyze inspiring products and UX patterns to inform design decisions for the current project through collaborative identification of successful patterns and extraction of transferable lessons.</purpose>
+
+<instructions>Identify 2-3 favorite apps users already use. Analyze UX patterns and principles for each. Extract transferable patterns for navigation, interaction, and visual design. Identify anti-patterns to avoid. Define design inspiration strategy (adopt, adapt, avoid). Generate inspiration analysis content with product analysis, transferable patterns, anti-patterns, and strategy sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>Inspiration analysis content appended to specification including design inspiration strategy with patterns to adopt, adapt, and avoid, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-06-design-system.md

@@ -1,5 +1,11 @@
 # Step 6: Design System Choice
 
+<purpose>Choose appropriate design system approach (custom, established, or themeable) based on project requirements, constraints, and team considerations through collaborative decision-making.</purpose>
+
+<instructions>Present design system options (custom, established, themeable). Analyze project requirements (platform, timeline, team size, brand, technical constraints). Explore specific design system options recommended for the platform. Facilitate decision process through framework questions. Finalize choice with clear rationale. Generate design system content with choice, rationale, implementation approach, and customization strategy sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>Design system choice content appended to specification including rationale and implementation approach, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-07-defining-experience.md

@@ -1,5 +1,11 @@
 # Step 7: Defining Core Experience
 
+<purpose>Define the core interaction that, if nailed perfectly, makes everything else follow through collaborative exploration of user mental models, success criteria, and interaction mechanics.</purpose>
+
+<instructions>Identify the defining experience (core action users describe to friends). Explore user mental model and current solutions. Define success criteria (when users say it just works). Identify novel vs established patterns. Design experience mechanics (initiation, interaction, feedback, completion). Generate defining experience content with experience description, mental model analysis, success criteria, novel patterns evaluation, and mechanics sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>Defining experience content appended to specification including detailed experience mechanics and success criteria, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-08-visual-foundation.md

@@ -1,5 +1,11 @@
 # Step 8: Visual Foundation
 
+<purpose>Establish visual design foundation including color themes, typography systems, and spacing/layout foundations through collaborative exploration of brand guidelines and design principles.</purpose>
+
+<instructions>Assess brand guidelines. If no brand exists, generate color theme options and HTML visualizer. Define typography system (tone, readability, hierarchy). Establish spacing and layout foundation (density, grid system). Create visual foundation strategy with color system, typography, spacing, and accessibility sections. Generate visual foundation content. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>Visual design foundation content appended to specification including color system, typography system, spacing/layout foundation, and accessibility considerations, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-09-design-directions.md

@@ -1,5 +1,11 @@
 # Step 9: Design Direction Mockups
 
+<purpose>Generate comprehensive design direction mockups showing different visual approaches for the product through collaborative exploration and selection of visual directions.</purpose>
+
+<instructions>Generate 6-8 design direction variations exploring layout, interactions, colors, density, and navigation. Create HTML design direction showcase at {planning_artifacts}/ux-design-directions.html with interactive elements. Present design exploration framework with evaluation criteria. Facilitate selection (pick favorite, combine elements, request modifications). Document design direction decision with rationale. Generate design direction content with directions explored, chosen direction, design rationale, and implementation approach sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>Design direction content appended to specification including chosen visual direction with clear rationale and implementation approach. HTML mockup showcase created with interactive design direction visualizer, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-10-user-journeys.md

@@ -1,5 +1,11 @@
 # Step 10: User Journey Flows
 
+<purpose>Design detailed user journey flows for critical user interactions through collaborative definition of flows with Mermaid diagrams and optimization for efficiency and delight.</purpose>
+
+<instructions>Load PRD user journeys as foundation. For each critical journey, design detailed flow (entry points, information needs, decisions, feedback, success definition). Create flow diagrams using Mermaid showing entry points, decision branches, success/failure paths, and error recovery. Optimize flows for efficiency and delight. Document journey patterns extracted across flows. Generate user journey content with journey descriptions, flow diagrams, journey patterns, and flow optimization principles sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>User journey flows content appended to specification including detailed Mermaid flow diagrams for all critical journeys, journey patterns, and optimization principles, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-11-component-strategy.md

@@ -1,5 +1,11 @@
 # Step 11: Component Strategy
 
+<purpose>Define component library strategy and design custom components not covered by the chosen design system through collaborative analysis of component needs and implementation planning.</purpose>
+
+<instructions>Analyze design system coverage (available vs needed). Design each custom component with purpose, content, actions, states, variants, and accessibility. Document component specifications. Define overall component strategy (foundation components, custom components, implementation approach). Plan implementation roadmap (phase 1 core, phase 2 supporting, phase 3 enhancement). Generate component strategy content with design system analysis, custom component specifications, implementation strategy, and roadmap sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>Component strategy content appended to specification including custom component specifications with accessibility considerations, implementation roadmap prioritized by criticality, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-12-ux-patterns.md

@@ -1,5 +1,11 @@
 # Step 12: UX Consistency Patterns
 
+<purpose>Establish UX consistency patterns for common situations like buttons, forms, navigation, and feedback through collaborative definition of pattern categories and design guidelines.</purpose>
+
+<instructions>Identify critical pattern categories (button hierarchy, feedback, forms, navigation, modals, empty states, search). Define patterns for critical categories with considerations (hierarchy, feedback, error recovery, accessibility, mobile). Establish pattern guidelines with when to use, visual design, behavior, accessibility, mobile considerations, and variants. Ensure design system integration. Generate pattern documentation with clear usage guidelines and visual examples. Generate UX patterns content with button hierarchy, feedback patterns, form patterns, navigation patterns, and additional patterns sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>UX consistency patterns content appended to specification including pattern guidelines for all critical categories with accessibility and mobile considerations, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-13-responsive-accessibility.md

@@ -1,5 +1,11 @@
 # Step 13: Responsive Design & Accessibility
 
+<purpose>Define responsive design strategy and accessibility requirements ensuring the product works beautifully across all devices and is accessible to all users.</purpose>
+
+<instructions>Define responsive strategy for desktop (layout, features), tablet (gestures, density), and mobile (navigation, collapse, priority). Establish breakpoint strategy (standard vs custom, mobile-first vs desktop-first). Design accessibility strategy (WCAG level A/AA/AAA, color contrast, keyboard navigation, screen reader, touch targets). Define testing strategy (responsive testing, accessibility testing, user testing). Document implementation guidelines (responsive development, accessibility development). Generate responsive and accessibility content with strategy, breakpoint strategy, accessibility strategy, testing strategy, and implementation guidelines sections. Present A/P/C menu. Save when C selected.</instructions>
+
+<output>Responsive and accessibility content appended to specification including comprehensive testing strategy and implementation guidelines for responsive design and accessibility compliance, with user confirmation and frontmatter updated.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - 🛑 NEVER generate content without user input

package/pennyfarthing-dist/workflows/ux-design/steps/step-14-complete.md

@@ -1,5 +1,11 @@
 # Step 14: Workflow Completion
 
+<purpose>Complete the UX design workflow, validate the specification, update status tracking, and provide next step guidance to the user.</purpose>
+
+<instructions>Announce workflow completion with all accomplished sections. Update workflow status file with completion information and timestamp. Perform document quality check (completeness, consistency). Suggest next steps (wireframes, prototypes, architecture, Figma design). Provide final completion confirmation with core deliverables list. Set lastStep = 14 in frontmatter. Do NOT load additional steps.</instructions>
+
+<output>Workflow completion announced with comprehensive summary of accomplished sections. Workflow status file updated. Next step options provided to user. UX design specification validated and ready for implementation. Specification location: {planning_artifacts}/ux-design-specification.md with supporting visual assets at {planning_artifacts}/ux-color-themes.html and {planning_artifacts}/ux-design-directions.html.</output>
+
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
 - ✅ THIS IS A FINAL STEP - Workflow completion required

package/pennyfarthing_scripts/migration/__init__.py

@@ -0,0 +1,39 @@
+"""
+XML Schema Migration Tools for Pennyfarthing.
+
+This module provides tools to migrate and validate Pennyfarthing files
+to conform to the XML schema definitions:
+- Session files -> guides/session-schema.md
+- Skill files -> guides/skill-schema.md
+- Workflow step files -> guides/workflow-step-schema.md
+
+Usage:
+    python -m pennyfarthing_scripts.migration [command] [options]
+
+Commands:
+    session   Migrate session files to XML format
+    skill     Audit/migrate skill files
+    step      Audit/migrate workflow step files
+    validate  Validate files against schemas
+"""
+
+from pennyfarthing_scripts.migration.session import (
+    SessionFile,
+    convert_session_file,
+    parse_markdown_session,
+)
+from pennyfarthing_scripts.migration.skill import audit_skill_file, audit_skills
+from pennyfarthing_scripts.migration.step import audit_step_file, audit_workflow_steps
+from pennyfarthing_scripts.migration.validate import validate_all, validate_file
+
+__all__ = [
+    "SessionFile",
+    "convert_session_file",
+    "parse_markdown_session",
+    "audit_skill_file",
+    "audit_skills",
+    "audit_step_file",
+    "audit_workflow_steps",
+    "validate_file",
+    "validate_all",
+]

package/pennyfarthing_scripts/migration/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for python -m pennyfarthing_scripts.migration
+"""
+
+import sys
+
+from pennyfarthing_scripts.migration.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())

package/pennyfarthing_scripts/migration/cli.py

@@ -0,0 +1,304 @@
+"""
+Migration CLI - Click-based CLI for XML schema migration tools.
+
+Usage:
+    pf migration [COMMAND] [ARGS]...
+    python -m pennyfarthing_scripts.migration [COMMAND] [ARGS]...
+
+Commands:
+    session   Migrate session files to XML format
+    skill     Audit skill files for required tags
+    step      Audit workflow step files
+    validate  Validate files against XML schemas
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from pennyfarthing_scripts.common.output import error, info, success, warn
+
+
+def _find_project_root() -> Path:
+    """Find project root by looking for .pennyfarthing directory."""
+    cwd = Path.cwd()
+
+    # Walk up looking for .pennyfarthing
+    for parent in [cwd, *cwd.parents]:
+        if (parent / ".pennyfarthing").exists():
+            return parent
+
+    # Fall back to cwd
+    return cwd
+
+
+@click.group()
+def migration():
+    """XML schema migration tools.
+
+    \b
+    Commands:
+      session   - Migrate session files to XML format
+      skill     - Audit skill files for required tags
+      step      - Audit workflow step files
+      validate  - Validate files against schemas
+    """
+    pass
+
+
+@migration.command()
+@click.argument("file", required=False, type=click.Path(exists=True))
+@click.option("--dry-run", is_flag=True, help="Show what would be done without writing")
+@click.option("--all", "convert_all", is_flag=True, help="Convert all session files")
+def session(file: str | None, dry_run: bool, convert_all: bool):
+    """Migrate session files to XML format.
+
+    \b
+    Arguments:
+      FILE  - Specific session file to convert (optional)
+
+    \b
+    Examples:
+      pf migration session --dry-run .session/archive/MSSCI-12142-session.md
+      pf migration session --all --dry-run
+      pf migration session --all
+    """
+    from pennyfarthing_scripts.migration.session import (
+        convert_session_file,
+        find_session_files,
+    )
+
+    root = _find_project_root()
+
+    if file:
+        file_path = Path(file)
+        result = convert_session_file(file_path, dry_run=dry_run)
+
+        if result.get("skipped"):
+            info(f"{file_path.name}: Already in XML format")
+        elif result.get("success"):
+            if dry_run:
+                click.echo(f"\n=== Would convert {file_path.name} to: ===\n")
+                click.echo(result.get("content"))
+                click.echo("\n=== End ===")
+            else:
+                success(f"Converted: {file_path.name}")
+        else:
+            error(result.get("message", "Conversion failed"))
+            raise click.Abort()
+
+    elif convert_all:
+        files = find_session_files(root)
+        if not files:
+            warn("No session files found")
+            return
+
+        info(f"Found {len(files)} session files")
+        converted = 0
+        skipped = 0
+
+        for file_path in files:
+            result = convert_session_file(file_path, dry_run=dry_run)
+
+            if result.get("skipped"):
+                skipped += 1
+            elif result.get("success"):
+                converted += 1
+                if dry_run:
+                    info(f"Would convert: {file_path.name}")
+                else:
+                    success(f"Converted: {file_path.name}")
+            else:
+                error(f"Failed: {file_path.name} - {result.get('message')}")
+
+        click.echo("")
+        info(f"Summary: {converted} converted, {skipped} already XML")
+
+    else:
+        # Show available files
+        files = find_session_files(root)
+        if not files:
+            warn("No session files found")
+            return
+
+        info(f"Session files found: {len(files)}")
+        for f in files[:10]:
+            click.echo(f"  {f.relative_to(root)}")
+        if len(files) > 10:
+            click.echo(f"  ... and {len(files) - 10} more")
+        click.echo("")
+        info("Use --all to convert all, or specify a file path")
+
+
+@migration.command()
+@click.argument("skill_name", required=False)
+@click.option("--report", is_flag=True, help="Generate detailed report")
+def skill(skill_name: str | None, report: bool):
+    """Audit skill files for required XML tags.
+
+    \b
+    Arguments:
+      SKILL_NAME  - Specific skill to audit (optional)
+
+    \b
+    Examples:
+      pf migration skill --report
+      pf migration skill sprint
+    """
+    from pennyfarthing_scripts.migration.skill import audit_skills
+
+    root = _find_project_root()
+    results = audit_skills(root, skill_name=skill_name)
+
+    if results["summary"].get("error"):
+        error(results["summary"]["error"])
+        raise click.Abort()
+
+    # Print results
+    for result in results["results"]:
+        if result.status == "OK":
+            success(f"{result.skill_name}: All tags present")
+        elif result.status == "PARTIAL":
+            warn(f"{result.skill_name}: Missing recommended: {', '.join(result.missing_recommended)}")
+        else:
+            error(f"{result.skill_name}: Missing required: {', '.join(result.missing_required)}")
+
+        if report and (result.missing_required or result.missing_recommended):
+            click.echo(f"    Present: {', '.join(result.present_tags)}")
+
+    # Print summary
+    summary = results["summary"]
+    click.echo("")
+    info("=== Summary ===")
+    click.echo(f"  Total:       {summary['total']}")
+    click.echo(f"  Valid:       {summary['valid']}")
+    click.echo(f"  Partial:     {summary['partial']}")
+    click.echo(f"  Needs work:  {summary['needs_update']}")
+
+    if summary["needs_update"] > 0:
+        click.echo("")
+        info("Skills needing updates:")
+        for result in results["results"]:
+            if not result.is_valid:
+                click.echo(f"  - {result.skill_name}")
+
+
+@migration.command()
+@click.argument("workflow_name", required=False)
+@click.option("--report", is_flag=True, help="Generate detailed report")
+def step(workflow_name: str | None, report: bool):
+    """Audit workflow step files for required XML tags.
+
+    \b
+    Arguments:
+      WORKFLOW_NAME  - Specific workflow to audit (optional)
+
+    \b
+    Examples:
+      pf migration step --report
+      pf migration step architecture
+    """
+    from pennyfarthing_scripts.migration.step import audit_workflow_steps
+
+    root = _find_project_root()
+    results = audit_workflow_steps(root, workflow_name=workflow_name)
+
+    # Print results by workflow
+    for workflow in results["workflows"]:
+        info(f"Workflow: {workflow.workflow_name} ({workflow.total_steps} steps)")
+
+        for result in workflow.step_results:
+            if result.status == "OK":
+                if report:
+                    success(f"  {result.step_name}: OK")
+            elif result.status == "PARTIAL":
+                warn(f"  {result.step_name}: Missing recommended: {', '.join(result.missing_recommended)}")
+            else:
+                error(f"  {result.step_name}: Missing required: {', '.join(result.missing_required)}")
+
+    # Print summary
+    summary = results["summary"]
+    click.echo("")
+    info("=== Summary ===")
+    click.echo(f"  Workflows:   {summary['total_workflows']}")
+    click.echo(f"  Step files:  {summary['total_files']}")
+    click.echo(f"  Valid:       {summary['valid']}")
+    click.echo(f"  Needs work:  {summary['needs_update']}")
+
+    if summary["needs_update"] > 0:
+        click.echo("")
+        info("Workflows with missing required tags:")
+        for workflow in results["workflows"]:
+            if workflow.needs_update > 0:
+                click.echo(f"  - {workflow.workflow_name} ({workflow.needs_update} files)")
+
+
+@migration.command()
+@click.option(
+    "--type",
+    "file_type",
+    type=click.Choice(["session", "skill", "step", "all"]),
+    default="all",
+    help="Type of files to validate",
+)
+@click.option("--strict", is_flag=True, help="Treat warnings as errors")
+def validate(file_type: str, strict: bool):
+    """Validate files against XML schemas.
+
+    \b
+    Examples:
+      pf migration validate
+      pf migration validate --type skill
+      pf migration validate --strict
+    """
+    from pennyfarthing_scripts.migration.validate import validate_all
+
+    root = _find_project_root()
+    summary = validate_all(root, file_type=file_type, strict=strict)
+
+    # Print results
+    for result in summary.results:
+        rel_path = result.file_path.relative_to(root) if root in result.file_path.parents else result.file_path
+        if result.status == "PASS":
+            success(f"{rel_path}")
+        elif result.status == "WARN":
+            warn(f"{rel_path}")
+            for w in result.warnings:
+                click.echo(f"    - {w}")
+        else:
+            error(f"{rel_path}")
+            for e in result.errors:
+                click.echo(f"    - {e}")
+
+    # Print summary
+    click.echo("")
+    info("=== Summary ===")
+    click.echo(f"  Passed:   {summary.passed}")
+    click.echo(f"  Warnings: {summary.warnings}")
+    click.echo(f"  Errors:   {summary.errors}")
+
+    if not summary.success:
+        raise click.Abort()
+
+    if strict and summary.warnings > 0:
+        error("Warnings treated as errors in strict mode")
+        raise click.Abort()
+
+
+# Alias for backwards compatibility
+cli = migration
+
+
+def main(args: list[str] | None = None) -> int:
+    """Entry point."""
+    try:
+        migration(args)
+        return 0
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else 0
+
+
+if __name__ == "__main__":
+    migration()