@pennyfarthing/core 9.0.0 → 9.1.2

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/project-setup/steps/step-01-discover.md

@@ -0,0 +1,157 @@
+# Step 1: Project Discovery
+
+<purpose>
+Discover the project structure, detect repositories, identify tech stack, and gather information needed to configure Pennyfarthing.
+</purpose>
+
+<instructions>
+1. Scan project root for repository structure
+2. Detect package managers and languages
+3. Identify monorepo vs single-repo structure
+4. Find test/build/lint commands
+5. Present discovery summary for user confirmation
+</instructions>
+
+<output>
+- Project structure map
+- Detected repositories with paths
+- Tech stack (languages, frameworks, package managers)
+- Extracted commands (test, build, lint)
+- User-confirmed discovery ready for repos.yaml generation
+</output>
+
+## DISCOVERY TASKS
+
+### 1. Detect Repository Structure
+
+Scan for git repositories and orchestrator patterns:
+
+```bash
+# Find all .git directories (indicates repos)
+find . -name ".git" -type d -maxdepth 3 2>/dev/null
+
+# Check if this is a monorepo
+ls -la pnpm-workspace.yaml lerna.json turborepo.json package.json 2>/dev/null
+
+# Check for orchestrator pattern (sprint/, .session/ directories)
+ls -la sprint/ .session/ 2>/dev/null
+
+# Check .gitignore for ignored subrepo patterns
+grep -E "^[a-zA-Z].*-api/?$|^[a-zA-Z].*-ui/?$|^[a-zA-Z]+/$" .gitignore 2>/dev/null
+```
+
+**Classify structure:**
+- **Single repo**: Only `./.git` exists, no sprint/
+- **Monorepo**: Workspace config found (pnpm-workspace.yaml, lerna.json, etc.)
+- **Orchestrator**: Has sprint/ and/or multiple `.git` directories (subrepos)
+
+### 1a. Detect Orchestrator Pattern (Critical)
+
+The orchestrator pattern uses gitignored subrepos:
+
+```
+my-project/                    # Orchestrator (git repo)
+├── .gitignore                 # Contains: my-project-api/, my-project-ui/
+├── sprint/                    # Sprint tracking (key indicator)
+├── .session/                  # Work sessions
+├── my-project-api/            # Subrepo (separate git, gitignored)
+│   └── .git/
+└── my-project-ui/             # Subrepo (separate git, gitignored)
+    └── .git/
+```
+
+**Detection steps:**
+1. Check for `sprint/` directory → indicates orchestrator
+2. Parse `.gitignore` for directory patterns (ending in `/`)
+3. Check if those directories exist AND have their own `.git`
+4. These are subrepos, not just ignored directories
+
+**Example .gitignore patterns to look for:**
+```gitignore
+# Subrepos (cloned separately)
+conductor-api/
+conductor-ui/
+
+# OR with wildcards
+*-api/
+*-ui/
+```
+
+**Important:** Subrepos may not exist yet (not cloned). The .gitignore tells us what SHOULD be there.
+
+### 2. Detect Tech Stack
+
+For each repository/directory, check for:
+
+| File | Indicates | Extract |
+|------|-----------|---------|
+| `package.json` | Node.js/JavaScript/TypeScript | name, scripts, dependencies |
+| `Cargo.toml` | Rust | name, version |
+| `pyproject.toml` / `requirements.txt` | Python | name, dependencies |
+| `go.mod` | Go | module name |
+| `pom.xml` / `build.gradle` | Java | project info |
+| `tsconfig.json` | TypeScript | compiler options |
+
+### 3. Extract Commands
+
+From `package.json` scripts or equivalent:
+
+```yaml
+test_command: npm test | pnpm test | cargo test | pytest
+build_command: npm run build | cargo build | python setup.py build
+lint_command: npm run lint | cargo clippy | ruff check
+dev_command: npm run dev | cargo watch
+```
+
+### 4. Identify Project Type
+
+Based on discovery, classify:
+
+| Type | Indicators |
+|------|------------|
+| `api` | Express, FastAPI, Gin, Actix endpoints |
+| `ui` | React, Vue, Svelte, frontend frameworks |
+| `cli` | bin entry in package.json, main.rs with clap |
+| `library` | exports, no bin entry |
+| `orchestrator` | sprint/, .session/, multiple subrepos |
+| `framework` | distributable content, templates |
+
+### 5. Present Discovery Summary
+
+```
+📁 Project Discovery Summary
+════════════════════════════
+
+Project Name: {detected_name}
+Structure: {single|monorepo|orchestrator}
+
+Repositories Found:
+┌────────────────┬──────────┬────────────┬─────────────────┐
+│ Path           │ Type     │ Language   │ Framework       │
+├────────────────┼──────────┼────────────┼─────────────────┤
+│ .              │ {type}   │ {lang}     │ {framework}     │
+│ packages/api   │ api      │ TypeScript │ Express         │
+│ packages/ui    │ ui       │ TypeScript │ React           │
+└────────────────┴──────────┴────────────┴─────────────────┘
+
+Detected Commands:
+  test:  {test_command}
+  build: {build_command}
+  lint:  {lint_command}
+
+[C] Confirm and continue to repos.yaml generation
+[E] Edit - let me provide corrections
+[R] Rescan with different parameters
+```
+
+## SUCCESS CRITERIA
+
+✅ All git repositories detected
+✅ Tech stack accurately identified
+✅ Commands extracted from package files
+✅ Project type classified
+✅ User confirms discovery is accurate
+
+## NEXT STEP
+
+After user confirms with [C], proceed to `step-02-clone-repos.md` to optionally clone subrepos and set up the orchestrator pattern.

package/pennyfarthing-dist/workflows/project-setup/steps/step-02-clone-repos.md

@@ -0,0 +1,217 @@
+# Step 2: Clone Subrepos (Optional)
+
+<purpose>
+Allow users to clone subrepos to set up or complete an orchestrator pattern. This step enables real-time repo cloning during project setup.
+</purpose>
+
+<instructions>
+1. Analyze discovery results for missing subrepos
+2. Check .gitignore for expected but missing repos
+3. Offer to clone missing repos or add new ones
+4. Update .gitignore with new repo patterns
+5. Re-scan after cloning to update discovery
+</instructions>
+
+<output>
+- Subrepos cloned as needed
+- .gitignore updated with new patterns
+- Discovery data refreshed with new repos
+- User ready to proceed to repos.yaml generation
+</output>
+
+## ORCHESTRATOR PATTERN SETUP
+
+### Detecting Missing Subrepos
+
+From step 1, we may have found:
+- Patterns in .gitignore that don't have corresponding directories
+- A sprint/ directory but no subrepos
+- An incomplete orchestrator setup
+
+```
+⚠️  Orchestrator Pattern Detected - Missing Subrepos
+
+Expected (from .gitignore):
+  ❌ conductor-api/     (not found)
+  ❌ conductor-ui/      (not found)
+
+Found:
+  ✓ sprint/            (orchestrator confirmed)
+  ✓ .pennyfarthing/    (framework installed)
+```
+
+### Clone Options Menu
+
+```
+📦 Subrepo Setup
+════════════════
+
+This appears to be an orchestrator project. Would you like to:
+
+[C] Clone missing subrepos
+    - conductor-api from git@github.com:org/conductor-api.git
+    - conductor-ui from git@github.com:org/conductor-ui.git
+
+[A] Add a new subrepo
+    - Enter repo URL to clone
+
+[S] Skip - configure repos.yaml with placeholders
+
+[N] Not an orchestrator - this is a standalone project
+```
+
+### Clone Workflow
+
+If user selects [C] or [A]:
+
+#### 1. Gather Repository Information
+
+```
+🔗 Clone Subrepo
+════════════════
+
+Repository URL: {user enters URL}
+  Example: git@github.com:org/project-api.git
+  Example: https://github.com/org/project-ui.git
+
+Local directory name: {auto-detect or user enters}
+  Suggested: {project}-api (from URL)
+
+Branch to clone: {default: main or develop}
+  [Enter] for default, or specify branch
+```
+
+#### 2. Execute Clone
+
+```bash
+# Clone the repository
+git clone {url} {directory_name}
+
+# Optionally checkout specific branch
+cd {directory_name} && git checkout {branch}
+```
+
+#### 3. Update .gitignore
+
+After successful clone, offer to update .gitignore:
+
+```
+✓ Cloned {repo_name} to {directory}/
+
+Add to .gitignore? [Y/n]
+```
+
+If yes, append:
+```gitignore
+# Subrepo - clone separately
+{directory_name}/
+```
+
+#### 4. Detect Repo Type
+
+After cloning, analyze the new repo:
+
+```
+📊 Analyzing {directory_name}...
+
+Detected:
+  Type: api
+  Language: TypeScript
+  Framework: Express
+  Test command: npm test
+  Build command: npm run build
+
+Is this correct? [Y/n/e]
+```
+
+### Setting Up New Orchestrator
+
+If no orchestrator pattern exists but user wants one:
+
+```
+🏗️  Create Orchestrator Pattern
+═══════════════════════════════
+
+This will set up your project as an orchestrator:
+
+1. Create sprint/ directory structure
+2. Create .session/ for work tracking
+3. Add Pennyfarthing workflow support
+
+Subrepos to include:
+  [ ] Add API repo
+  [ ] Add UI repo
+  [ ] Add other repo
+
+[P] Proceed with orchestrator setup
+[S] Skip - keep as single repo
+```
+
+### Common Orchestrator Patterns
+
+Offer templates based on project type:
+
+```
+📋 Orchestrator Templates
+═════════════════════════
+
+[1] API + UI (most common)
+    - {project}-api/ (backend)
+    - {project}-ui/ (frontend)
+
+[2] API + UI + Shared (monorepo-like)
+    - {project}-api/
+    - {project}-ui/
+    - {project}-shared/
+
+[3] Microservices
+    - {project}-gateway/
+    - {project}-service-a/
+    - {project}-service-b/
+
+[4] Custom - define your own repos
+```
+
+## RE-SCAN AFTER CHANGES
+
+After any cloning or setup:
+
+```bash
+# Re-run discovery
+find . -name ".git" -type d -maxdepth 3
+
+# Update tech stack detection
+# (runs same detection as step 1)
+```
+
+Present updated discovery:
+
+```
+📁 Updated Project Structure
+════════════════════════════
+
+Repositories:
+┌────────────────┬──────────┬────────────┐
+│ Path           │ Type     │ Status     │
+├────────────────┼──────────┼────────────┤
+│ .              │ orch     │ existing   │
+│ conductor-api/ │ api      │ ✓ cloned   │
+│ conductor-ui/  │ ui       │ ✓ cloned   │
+└────────────────┴──────────┴────────────┘
+
+[C] Continue to repos.yaml generation
+[A] Add another repo
+[R] Remove a repo from tracking
+```
+
+## SUCCESS CRITERIA
+
+✅ All desired subrepos cloned
+✅ .gitignore properly updated
+✅ Discovery data refreshed
+✅ Repo types correctly identified
+✅ User ready to proceed
+
+## NEXT STEP
+
+After repos are cloned and discovery is refreshed, proceed to `step-03-repos-yaml.md` to generate the repos.yaml configuration.