@pennyfarthing/core 9.0.3 → 9.1.2

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.

package/pennyfarthing-dist/workflows/project-setup/steps/step-03-repos-yaml.md

@@ -0,0 +1,159 @@
+# Step 3: Generate repos.yaml
+
+<purpose>
+Generate the repos.yaml configuration file based on discovered project structure, with user refinement.
+</purpose>
+
+<instructions>
+1. Transform discovery data into repos.yaml format
+2. Present draft configuration to user
+3. Allow user to edit/refine entries
+4. Write finalized repos.yaml to project root
+</instructions>
+
+<output>
+- repos.yaml file created at project root
+- All repositories properly configured
+- Commands and metadata accurate
+- User has approved the configuration
+</output>
+
+## REPOS.YAML STRUCTURE
+
+```yaml
+# Repository Configuration for {project_name}
+# Generated by Pennyfarthing project-setup workflow
+
+repos:
+  {repo_key}:
+    path: {relative_path}           # Path from project root
+    type: {api|ui|cli|library|orchestrator|framework}
+    description: {brief_description}
+    language: {typescript|python|rust|go|java}
+
+    # Commands (optional - omit if not applicable)
+    test_command: {command}
+    build_command: {command}
+    lint_command: {command}
+    dev_command: {command}
+
+    # Additional metadata (optional)
+    framework: {express|react|fastapi|etc}
+    notes: |
+      Any special notes about this repo.
+
+# Architecture notes:
+# Add any project-wide architectural notes here
+```
+
+## GENERATION RULES
+
+### Repo Keys
+- Use lowercase, descriptive names
+- For monorepos: use package names (`api`, `ui`, `shared`)
+- For orchestrators: use `orchestrator` for root, repo names for subrepos
+
+### Path Rules
+- Root repo: use `.`
+- Subrepos: use relative path from project root
+- Monorepo packages: use package path (`packages/api`)
+
+### Type Classification
+
+| Type | When to Use |
+|------|-------------|
+| `orchestrator` | Root of multi-repo project with sprint/ |
+| `api` | Backend service, REST/GraphQL endpoints |
+| `ui` | Frontend application |
+| `cli` | Command-line tool |
+| `library` | Shared code, npm package |
+| `framework` | Distributable framework (like pennyfarthing) |
+
+### Command Extraction
+
+Extract from discovered package.json scripts:
+```javascript
+{
+  "scripts": {
+    "test": "jest",      // → test_command: npm test
+    "build": "tsc",      // → build_command: npm run build
+    "lint": "eslint",    // → lint_command: npm run lint
+    "dev": "nodemon"     // → dev_command: npm run dev
+  }
+}
+```
+
+## INTERACTIVE REFINEMENT
+
+Present the generated repos.yaml and ask:
+
+```
+📄 Generated repos.yaml
+════════════════════════
+
+{yaml_content}
+
+Options:
+[A] Accept and write to {output_repos}
+[E] Edit a specific repo entry
+[N] Add a new repo entry
+[D] Delete a repo entry
+[P] Preview in different format
+```
+
+### Edit Flow
+If user selects [E]:
+1. List repo keys
+2. Ask which to edit
+3. Show current values
+4. Accept new values
+5. Return to main menu
+
+## EXAMPLE OUTPUT
+
+For a typical api+ui project:
+
+```yaml
+# Repository Configuration for my-project
+# Generated by Pennyfarthing project-setup workflow
+
+repos:
+  orchestrator:
+    path: .
+    type: orchestrator
+    description: Project coordination and sprint management
+    language: javascript
+
+  api:
+    path: my-project-api
+    type: api
+    description: Backend REST API
+    language: typescript
+    framework: express
+    test_command: npm test
+    build_command: npm run build
+    lint_command: npm run lint
+
+  ui:
+    path: my-project-ui
+    type: ui
+    description: React frontend application
+    language: typescript
+    framework: react
+    test_command: npm test
+    build_command: npm run build
+    lint_command: npm run lint
+    dev_command: npm run dev
+```
+
+## SUCCESS CRITERIA
+
+✅ repos.yaml accurately reflects project structure
+✅ All detected repos included
+✅ Commands verified and correct
+✅ User has reviewed and approved
+✅ File written to project root
+
+## NEXT STEP
+
+After repos.yaml is written and approved, proceed to `step-04-claude-md.md` to generate the CLAUDE.md file.

package/pennyfarthing-dist/workflows/project-setup/steps/step-04-claude-md.md

@@ -0,0 +1,186 @@
+# Step 4: Generate CLAUDE.md
+
+<purpose>
+Generate the project's CLAUDE.md file - the primary instruction file that Claude Code reads on every session. This file defines project-specific rules, structure, and workflows.
+</purpose>
+
+<instructions>
+1. Analyze repos.yaml and discovered tech stack
+2. Generate CLAUDE.md with project-specific content
+3. Include correct commands, structure, and workflows
+4. Allow user to review and refine
+5. Write to project root
+</instructions>
+
+<output>
+- CLAUDE.md file created at project root
+- Accurate project structure documented
+- Correct build/test/lint commands
+- Appropriate workflow guidance
+- User has approved the content
+</output>
+
+## CLAUDE.MD STRUCTURE
+
+```markdown
+# CLAUDE.md - {Project Name}
+
+This file provides guidance to Claude Code when working on this project.
+
+## Project Overview
+
+{Brief description of what the project does}
+
+**Type:** {orchestrator|api|ui|cli|library|framework}
+**Node:** {version if applicable}
+**Type:** {ES module|CommonJS}
+
+## Repository Structure
+
+{if orchestrator}
+```
+{project_name}/              # Orchestrator
+├── .claude/                 # Claude Code configuration
+├── .pennyfarthing/          # Pennyfarthing framework
+├── sprint/                  # Sprint tracking
+├── .session/                # Active work sessions
+├── {subrepo1}/              # {description}
+└── {subrepo2}/              # {description}
+```
+{/if}
+
+{if monorepo}
+```
+{project_name}/
+├── packages/
+│   ├── {package1}/          # {description}
+│   └── {package2}/          # {description}
+├── .claude/
+└── .pennyfarthing/
+```
+{/if}
+
+{if single_repo}
+```
+{project_name}/
+├── src/                     # Source code
+├── tests/                   # Tests
+├── .claude/
+└── .pennyfarthing/
+```
+{/if}
+
+## Build Commands
+
+```bash
+{build_command}              # Build the project
+{test_command}               # Run tests
+{lint_command}               # Run linter
+{dev_command}                # Start development
+```
+
+## Development Workflow
+
+{if has_sprint}
+- `/sm` - Scrum Master (story management)
+- `/tea` - Test Engineer/Architect
+- `/dev` - Developer
+- `/reviewer` - Code Reviewer
+{/if}
+
+## Git Workflow
+
+- **Feature branches:** `feat/{story}-{description}`
+- **Bug fixes:** `fix/{issue}-{description}`
+- **PRs target:** `develop` (or `main` if no develop)
+
+## Testing
+
+```bash
+{test_command}                        # Run all tests
+{test_command} -- --grep "pattern"    # Run specific tests
+```
+
+## Important Notes
+
+{Project-specific notes, gotchas, conventions}
+```
+
+## GENERATION LOGIC
+
+### 1. Extract from repos.yaml
+
+Read the repos.yaml created in step 2:
+- Project name from orchestrator/root repo
+- Type from repo classification
+- Commands from each repo
+
+### 2. Detect Additional Context
+
+Scan for:
+- `tsconfig.json` → TypeScript config details
+- `jest.config.*` → Test framework config
+- `.eslintrc.*` → Linting config
+- `Dockerfile` → Container info
+- CI config (`.github/workflows/`, `.gitlab-ci.yml`)
+
+### 3. Include Pennyfarthing Integration
+
+If sprint/ exists:
+```markdown
+## Sprint Management
+
+- `/sprint status` - View current sprint
+- `/sprint backlog` - Available stories
+- `/sprint work` - Start a story
+```
+
+### 4. Add Project-Specific Sections
+
+Based on tech stack:
+
+**For TypeScript projects:**
+```markdown
+## TypeScript
+
+- Use `.js` extensions in imports
+- Strict mode enabled
+- ES modules (`"type": "module"`)
+```
+
+**For React projects:**
+```markdown
+## React Patterns
+
+- Functional components with hooks
+- Component files in `src/components/`
+- Tests co-located with components
+```
+
+## INTERACTIVE REFINEMENT
+
+```
+📄 Generated CLAUDE.md
+═══════════════════════
+
+{preview of generated content}
+
+Options:
+[A] Accept and write to CLAUDE.md
+[E] Edit a section
+[S] Add a new section
+[R] Regenerate with different focus
+[P] Preview full content
+```
+
+## SUCCESS CRITERIA
+
+✅ CLAUDE.md accurately describes project
+✅ Commands are correct and tested
+✅ Structure matches actual project
+✅ Workflows appropriate for project type
+✅ User has reviewed and approved
+
+## NEXT STEP
+
+After CLAUDE.md is written, proceed to `step-05-shared-context.md` to populate the shared-context.md file.