@pennyfarthing/core 9.0.3 → 9.2.0

package/pennyfarthing-dist/workflows/project-setup/steps/step-08-theme-packs.md

@@ -0,0 +1,142 @@
+# Step 8: Install Additional Theme Packs (Optional)
+
+<purpose>
+Offer the user additional theme packs beyond the 26 base themes that ship with Pennyfarthing. Theme packs are optional npm packages that add themed personas with portraits.
+</purpose>
+
+<instructions>
+1. Explain the theme pack system
+2. Show available packs with descriptions
+3. Let user select which packs to install
+4. Install selected packs
+5. Verify themes are discovered
+</instructions>
+
+<output>
+- User informed about available theme packs
+- Selected packs installed (if any)
+- New themes discoverable via `/theme list`
+</output>
+
+## THEME PACK SYSTEM
+
+```
+🎭 Additional Theme Packs
+══════════════════════════
+
+Pennyfarthing ships with 26 base themes. Additional themes are available
+as optional packages - install the ones that interest you.
+
+Theme packs are discovered automatically once installed. No configuration
+needed beyond `npm install`.
+```
+
+## AVAILABLE PACKS
+
+Present the packs with descriptions and theme counts:
+
+```
+Available theme packs:
+
+[1] @pennyfarthing/themes-literary (15 themes)
+    Classic literature: Dickens, Shakespeare, Austen, Moby Dick,
+    Sherlock Holmes, Les Miserables, Great Gatsby, and more.
+    Pre-1950 books and author collections.
+
+[2] @pennyfarthing/themes-prestige-tv (17 themes)
+    Golden age television: Breaking Bad, The Sopranos, The Wire,
+    Mad Men, Deadwood, Succession, Twin Peaks, and more.
+
+[3] @pennyfarthing/themes-comedy (9 themes)
+    Comedy TV and film: The Office, Parks & Rec, Futurama,
+    The Simpsons, Monty Python, Ted Lasso, and more.
+
+[4] @pennyfarthing/themes-scifi (8 themes)
+    Sci-fi and cyberpunk deep cuts: Foundation, Babylon 5,
+    Neuromancer, Snow Crash, Star Trek TOS, and more.
+
+[5] @pennyfarthing/themes-realistic (14 themes)
+    Historical figures: Renaissance masters, jazz legends,
+    scientific revolutionaries, classical composers, and more.
+    Realistic portrait style.
+
+[6] @pennyfarthing/themes-superheroes (4 themes)
+    Superheroes and animated action: Marvel MCU, Legion of Doom,
+    Superfriends, Avatar: The Last Airbender.
+
+[7] @pennyfarthing/themes-mythology-fantasy (4 themes)
+    Mythology and fantasy: Greek mythology, Norse mythology,
+    His Dark Materials, The Witcher.
+
+[A] Install ALL packs (71 additional themes)
+[S] Skip - base themes are enough for now
+```
+
+## INSTALLATION
+
+Based on user selection, install the chosen packs:
+
+```bash
+# Install selected packs (example: literary + prestige-tv)
+npm install @pennyfarthing/themes-literary @pennyfarthing/themes-prestige-tv
+```
+
+### Install All
+
+```bash
+npm install \
+  @pennyfarthing/themes-literary \
+  @pennyfarthing/themes-prestige-tv \
+  @pennyfarthing/themes-comedy \
+  @pennyfarthing/themes-scifi \
+  @pennyfarthing/themes-realistic \
+  @pennyfarthing/themes-superheroes \
+  @pennyfarthing/themes-mythology-fantasy
+```
+
+## VERIFICATION
+
+After installation, verify themes are discovered:
+
+```bash
+# List all themes - should show base + installed packs
+pennyfarthing theme list
+```
+
+```
+✓ Theme packs installed
+
+Themes available:
+  Base themes:              26
+  {pack_name}:              {count}
+  ...
+  ─────────────────────────────
+  Total:                    {total}
+
+New themes are ready to use. Switch anytime with:
+  /theme set {theme-name}
+```
+
+## INSTALLING LATER
+
+```
+You can install theme packs anytime:
+
+  npm install @pennyfarthing/themes-literary
+  npm install @pennyfarthing/themes-prestige-tv
+  # etc.
+
+They're automatically discovered - no config changes needed.
+To see what's available: /theme list
+```
+
+## SUCCESS CRITERIA
+
+- User shown available theme packs
+- Selected packs installed (if any)
+- New themes verified as discoverable
+- User knows how to install more later
+
+## NEXT STEP
+
+After theme packs, proceed to `step-09-cyclist.md` to optionally install Cyclist visual terminal.

package/pennyfarthing-dist/workflows/project-setup/steps/step-09-cyclist.md

@@ -0,0 +1,245 @@
+# Step 9: Install Cyclist (Optional)
+
+<purpose>
+Optionally install Cyclist, the visual terminal interface for Claude Code. Cyclist provides a graphical interface with panels for sprint tracking, workflow visualization, and enhanced tool display.
+</purpose>
+
+<instructions>
+1. Explain what Cyclist provides
+2. Check if Cyclist is already installed
+3. Offer installation options
+4. Guide through setup if desired
+5. Verify installation works
+</instructions>
+
+<output>
+- User informed about Cyclist features
+- Cyclist installed if user requested
+- Basic verification completed
+- User knows how to launch Cyclist
+</output>
+
+## WHAT IS CYCLIST?
+
+```
+🚴 Cyclist - Visual Terminal for Claude Code
+═════════════════════════════════════════════
+
+Cyclist provides a graphical interface that enhances Claude Code with:
+
+┌─────────────────────────────────────────────────────────────────────┐
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                │
+│  │ Sprint Panel │ │ Workflow     │ │ Changed      │                │
+│  │              │ │ Panel        │ │ Files        │                │
+│  │ • Status     │ │              │ │              │                │
+│  │ • Stories    │ │ • Phase      │ │ • Diffs      │                │
+│  │ • Progress   │ │ • Handoffs   │ │ • Staging    │                │
+│  └──────────────┘ └──────────────┘ └──────────────┘                │
+│  ┌───────────────────────────────────────────────────────────────┐ │
+│  │                     Message Panel                              │ │
+│  │                                                                │ │
+│  │  Claude: I'll help you implement that feature...               │ │
+│  │                                                                │ │
+│  │  [Tool Call] Reading src/components/App.tsx                    │ │
+│  │  [Tool Call] Writing src/components/Feature.tsx                │ │
+│  │                                                                │ │
+│  └───────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+
+Features:
+  • 📊 Sprint panel - Live sprint status and story tracking
+  • 🔄 Workflow panel - BikeLane phase visualization
+  • 📁 Changed files panel - Git diff integration
+  • 🎨 Themed personas - Character portraits and styles
+  • 🛠️ Tool visualization - Enhanced tool call display
+  • ⌨️ Quick actions - One-click workflow commands
+```
+
+## INSTALLATION CHECK
+
+```bash
+# Check if Cyclist is installed
+npm list @pennyfarthing/cyclist 2>/dev/null || echo "Not installed"
+
+# Check for global installation
+which cyclist 2>/dev/null || echo "No global cyclist"
+
+# Check for local installation
+ls -la node_modules/@pennyfarthing/cyclist 2>/dev/null || echo "Not in node_modules"
+```
+
+## INSTALLATION OPTIONS
+
+```
+🚴 Cyclist Installation
+═══════════════════════
+
+Cyclist is the visual terminal for Pennyfarthing. Would you like to install it?
+
+[1] Install Cyclist (recommended)
+    npm install @pennyfarthing/cyclist
+    Adds ~160MB to node_modules
+
+[2] Install globally
+    npm install -g @pennyfarthing/cyclist
+    Available system-wide
+
+[3] Use standalone app (macOS)
+    Download Cyclist.app from releases
+    No npm installation needed
+
+[4] Skip - I'll use terminal only
+    Cyclist is optional, CLI works fine without it
+
+[5] Learn more about Cyclist
+    Show detailed feature breakdown
+```
+
+### Installation Flow
+
+If user selects [1] or [2]:
+
+```bash
+# Local installation
+npm install @pennyfarthing/cyclist
+
+# Or global installation
+npm install -g @pennyfarthing/cyclist
+```
+
+### Post-Installation Setup
+
+```
+✓ Cyclist installed successfully
+
+Quick setup:
+  1. Add to justfile (if created):
+     cyclist:
+         npx cyclist
+
+  2. Or run directly:
+     npx cyclist
+
+  3. Or add to package.json scripts:
+     "cyclist": "cyclist"
+```
+
+## VERIFICATION
+
+After installation:
+
+```bash
+# Verify installation
+npx cyclist --version
+
+# Quick test (opens Cyclist)
+npx cyclist --help
+```
+
+```
+✓ Cyclist v9.1.1 installed
+
+Launching Cyclist for verification...
+
+{Cyclist window opens or web preview starts}
+
+Did Cyclist launch correctly?
+[Y] Yes, it works
+[N] No, troubleshoot
+[S] Skip verification
+```
+
+### Troubleshooting
+
+If issues:
+
+```
+🔧 Cyclist Troubleshooting
+═══════════════════════════
+
+Common issues:
+
+1. "Cannot find module" error
+   → Run: npm install @pennyfarthing/cyclist
+
+2. Port already in use
+   → Kill existing process: lsof -i :3457 | kill
+
+3. Electron not found
+   → Cyclist needs Electron: npm install electron
+
+4. Blank window
+   → Check browser console for errors
+   → Try: npx cyclist --no-sandbox
+
+[R] Retry installation
+[M] More troubleshooting options
+[S] Skip Cyclist for now
+```
+
+## JUSTFILE INTEGRATION
+
+If justfile was created in step 6, offer to add Cyclist recipe:
+
+```
+Add Cyclist recipe to justfile?
+
+[Y] Yes, add recipe:
+    cyclist:
+        npx cyclist
+
+[N] No, I'll launch it manually
+```
+
+## CYCLIST FEATURES DEEP DIVE
+
+If user selects "Learn more":
+
+```
+🚴 Cyclist Features
+════════════════════
+
+PANELS (draggable, resizable):
+┌────────────────┬─────────────────────────────────────────────┐
+│ Panel          │ Features                                    │
+├────────────────┼─────────────────────────────────────────────┤
+│ Message        │ Conversation display, streaming, markdown   │
+│ Sprint         │ Current sprint, stories, progress bars      │
+│ Workflow       │ BikeLane phases, handoff detection          │
+│ Changed Files  │ Git status, staged/unstaged, diffs          │
+│ Acceptance     │ Story AC checkboxes                         │
+│ Todos          │ Task list tracking                          │
+│ Background     │ Background task monitoring                  │
+│ Debug          │ OTEL spans, performance data                │
+│ Git            │ Branch info, commit history                 │
+│ Settings       │ Theme, fonts, colors                        │
+└────────────────┴─────────────────────────────────────────────┘
+
+TOOL VISUALIZATION:
+  • Collapsible tool calls with intent summaries
+  • Stacked consecutive tool calls
+  • Color-coded by tool type
+  • Execution time display
+
+PERSONA INTEGRATION:
+  • Character portraits for each agent
+  • Theme-specific colors and styles
+  • Agent popup with role info
+
+QUICK ACTIONS:
+  • Detected from CYCLIST markers
+  • One-click workflow commands
+  • Handoff buttons
+```
+
+## SUCCESS CRITERIA
+
+✅ User informed about Cyclist features
+✅ Installation completed (if requested)
+✅ Verification passed (if installed)
+✅ Justfile updated (if applicable)
+✅ User knows how to launch Cyclist
+
+## NEXT STEP
+
+After Cyclist setup, proceed to `step-10-complete.md` to finalize project setup and run validation.

package/pennyfarthing-dist/workflows/project-setup/steps/step-10-complete.md

@@ -0,0 +1,204 @@
+# Step 10: Complete Setup & Validation
+
+<purpose>
+Finalize the project setup, run validation checks, and provide the user with a summary of everything configured. Ensure the project is ready for development.
+</purpose>
+
+<instructions>
+1. Run pennyfarthing doctor to validate installation
+2. Summarize all configurations created
+3. Provide quick-start guide
+4. Offer next steps and resources
+</instructions>
+
+<output>
+- All validation checks pass
+- Configuration summary presented
+- Quick-start guide provided
+- User ready to begin development
+</output>
+
+## VALIDATION
+
+### Run Doctor
+
+```bash
+pennyfarthing doctor
+```
+
+Expected output:
+```
+🔧 Pennyfarthing Health Check
+════════════════════════════
+
+✓ .pennyfarthing/ directory exists
+✓ Manifest found (v9.1.1)
+✓ Symlinks valid
+✓ Sprint directory exists
+✓ Session directory exists
+✓ Git hooks installed
+✓ Settings configured
+
+All checks passed!
+```
+
+### Manual Validation Checklist
+
+```
+📋 Setup Validation
+════════════════════
+
+Configuration files:
+  {✓|✗} repos.yaml          - Repository configuration
+  {✓|✗} CLAUDE.md           - Project instructions
+  {✓|✗} shared-context.md   - Agent shared context
+  {✓|✗} justfile            - Task runner
+  {✓|✗} persona-config.yaml - Theme configuration
+
+Directories:
+  {✓|✗} .pennyfarthing/     - Framework installation
+  {✓|✗} .claude/            - Claude Code config
+  {✓|✗} sprint/             - Sprint tracking
+  {✓|✗} .session/           - Work sessions
+
+Optional:
+  {✓|✗} Cyclist installed
+  {✓|✗} Subrepos cloned
+```
+
+## CONFIGURATION SUMMARY
+
+```
+📊 Project Setup Summary
+═════════════════════════
+
+Project: {project_name}
+Type: {orchestrator|monorepo|single}
+Theme: {selected_theme}
+
+Repositories Configured:
+┌────────────────┬──────────┬────────────────────────┐
+│ Name           │ Type     │ Path                   │
+├────────────────┼──────────┼────────────────────────┤
+│ orchestrator   │ orch     │ .                      │
+│ api            │ api      │ {project}-api/         │
+│ ui             │ ui       │ {project}-ui/          │
+└────────────────┴──────────┴────────────────────────┘
+
+Files Created:
+  • repos.yaml           - Repository configuration
+  • CLAUDE.md            - Project instructions for Claude
+  • shared-context.md    - Shared agent context (updated)
+  • justfile             - Task runner with recipes
+  • persona-config.yaml  - Theme: {theme}
+
+Commands Available:
+  just test-all          - Run all tests
+  just build-all         - Build all repos
+  just dev               - Start development
+  just cyclist           - Launch Cyclist (if installed)
+```
+
+## QUICK-START GUIDE
+
+```
+🚀 Quick Start Guide
+════════════════════
+
+1. START DEVELOPMENT
+   just dev              # Start dev servers
+   # OR
+   just dev-api          # Start just API
+   just dev-ui           # Start just UI
+
+2. RUN TESTS
+   just test-all         # Test everything
+   just test-api         # Test API only
+
+3. USE PENNYFARTHING AGENTS
+   /sm                   # Scrum Master - manage stories
+   /sprint status        # View sprint
+   /sprint work          # Start a story
+
+4. WORKFLOW
+   Story flow: SM → TEA → Dev → Reviewer → SM
+
+5. LAUNCH CYCLIST (if installed)
+   just cyclist          # Visual terminal
+   # OR
+   npx cyclist
+
+6. GET HELP
+   /help                 # Context-aware help
+   pennyfarthing doctor  # Check installation
+```
+
+## NEXT STEPS
+
+```
+📌 Recommended Next Steps
+═════════════════════════
+
+IMMEDIATE:
+  □ Review CLAUDE.md and customize for your project
+  □ Add project-specific notes to shared-context.md
+  □ Create your first sprint in sprint/current-sprint.yaml
+
+WHEN READY:
+  □ Run /sm to start managing work
+  □ Create stories with /story create
+  □ Begin TDD workflow with /tea
+
+CUSTOMIZATION:
+  □ Add custom skills in .claude/project/skills/
+  □ Add custom commands in .claude/project/commands/
+  □ Configure agent sidecars in .pennyfarthing/sidecars/
+
+RESOURCES:
+  □ Docs: https://github.com/1898andCo/pennyfarthing
+  □ Issues: https://github.com/1898andCo/pennyfarthing/issues
+  □ Skill help: /help {skill_name}
+```
+
+## FINAL MESSAGE
+
+```
+✨ Setup Complete!
+══════════════════
+
+Your Pennyfarthing project is ready for development.
+
+{if theme_selected}
+Your agents now use the '{theme}' theme.
+{agent_character} says: "{theme_greeting}"
+{/if}
+
+Quick commands:
+  /sm              - Start managing work
+  /sprint status   - View sprint
+  /help            - Get help
+
+{if cyclist_installed}
+Launch Cyclist for the visual experience:
+  just cyclist
+{/if}
+
+Happy coding! 🚴
+```
+
+## WORKFLOW COMPLETE
+
+This workflow is now complete. The user has:
+
+✅ Discovered and configured repositories
+✅ Cloned any needed subrepos
+✅ Generated repos.yaml
+✅ Created CLAUDE.md
+✅ Populated shared-context.md
+✅ Created justfile with recipes
+✅ Selected a persona theme
+✅ Optionally installed additional theme packs
+✅ Optionally installed Cyclist
+✅ Validated the setup
+
+The project is ready for development with Pennyfarthing.

package/pennyfarthing-dist/workflows/project-setup/workflow.yaml

@@ -0,0 +1,41 @@
+# project-setup Workflow - Interactive Project Configuration
+# A BikeLane stepped workflow for configuring Pennyfarthing projects
+
+workflow:
+  name: project-setup
+  description: Interactive workflow for configuring a new Pennyfarthing project. Discovers repos, generates CLAUDE.md, populates shared-context.md, and configures themes.
+  version: "1.0.0"
+  type: stepped
+
+  # Step configuration
+  steps:
+    path: ./steps/
+    pattern: step-*.md
+
+  # Variables available in step files
+  variables:
+    project_root: .
+    claude_dir: .claude
+    pennyfarthing_dir: .pennyfarthing
+    output_repos: repos.yaml
+    output_claude_md: CLAUDE.md
+    output_shared_context: .claude/project/docs/shared-context.md
+
+  # Agent assignment - DevOps handles infrastructure setup
+  agent: devops
+
+  # Triggers - when to suggest this workflow
+  triggers:
+    types: [project-setup, init, setup]
+    tags: [setup, initialization, repos, claude-md]
+    conditions:
+      - no_repos_yaml: true
+      - no_claude_md: true
+
+  # Post-init hook suggestion
+  post_init_message: |
+    Run `/setup` to complete project configuration:
+    - Detect and configure repos
+    - Generate CLAUDE.md
+    - Populate shared-context.md
+    - Select persona theme