@pennyfarthing/core 10.0.1 → 10.0.2

package/pennyfarthing-dist/guides/workflow-step-schema.md

@@ -0,0 +1,512 @@
+# Workflow Step File XML Schema
+
+Workflow step files define individual steps in BikeLane stepped workflows. A consistent XML schema enables reliable step parsing, gate enforcement, and navigation.
+
+## File Location
+
+```
+workflows/{workflow-name}/steps/step-{NN}-{name}.md
+workflows/{workflow-name}/steps-{mode}/step-{NN}-{name}.md
+```
+
+**Examples:**
+- `workflows/architecture/steps/step-01-initialize.md`
+- `workflows/prd/steps-c/step-05-domain.md` (create mode)
+- `workflows/research/steps-market/step-02-customer-insights.md`
+
+## Complete Schema
+
+```markdown
+# Step N: Step Title
+
+<step-meta>
+number: 1
+name: initialize
+gate: false
+next: step-02-context
+</step-meta>
+
+<purpose>
+What this step accomplishes in the workflow.
+</purpose>
+
+<prerequisites>
+- Required input 1
+- Required input 2
+- Previous step must be complete
+</prerequisites>
+
+<instructions>
+1. First action to take
+2. Second action to take
+3. Third action to take
+</instructions>
+
+<actions>
+- Check: `{file_path}` for condition
+- Read: `{input_path}/*.md`
+- Write: `{output_file}`
+- Run: `.pennyfarthing/scripts/path/to/script.sh`
+</actions>
+
+<output>
+What to produce at end of this step.
+Document format, required sections, etc.
+</output>
+
+<gate>
+## Completion Criteria
+- [ ] Criterion 1 met
+- [ ] Criterion 2 met
+- [ ] User confirmed output
+</gate>
+
+<collaboration-menu>
+- **[C] Continue** - Proceed to next step
+- **[R] Revise** - Make changes to output
+- **[H] Help** - Get guidance on this step
+- **[S] Skip** - Skip optional step
+</collaboration-menu>
+
+<next-step>
+After gate passes, proceed to step-02-context.md
+</next-step>
+
+## Failure Modes
+
+- Not checking prerequisites before starting
+- Skipping user confirmation at gate
+- Proceeding without all criteria met
+
+## Success Metrics
+
+- All gate criteria checked
+- User confirmed satisfaction
+- Output matches expected format
+```
+
+## Element Reference
+
+### Step Title (Required)
+
+Every step file must start with a markdown heading:
+
+```markdown
+# Step N: Descriptive Title
+```
+
+**Format:** `# Step {number}: {title}`
+
+---
+
+### `<step-meta>` (Required)
+
+**Purpose:** Machine-readable step metadata for BikeLane navigation.
+
+**Fields:**
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `number` | Yes | Integer | Step number (1, 2, 3...) |
+| `name` | Yes | String | Step identifier (kebab-case) |
+| `gate` | Yes | Boolean | Whether step has a gate checkpoint |
+| `next` | No | String | Next step filename (without .md) |
+
+**Example:**
+```xml
+<step-meta>
+number: 3
+name: patterns
+gate: true
+next: step-04-components
+</step-meta>
+```
+
+**Note:** The `next` field enables automatic navigation. Omit for final steps.
+
+---
+
+### `<purpose>`
+
+**Purpose:** Explain what this step accomplishes in the workflow.
+
+**Required:** Yes
+
+**Content:** Clear, concise explanation of the step's goal.
+
+**Example:**
+```xml
+<purpose>
+Set up the architecture decision session by gathering inputs and establishing context.
+This step validates prerequisites and prepares the working document.
+</purpose>
+```
+
+---
+
+### `<prerequisites>`
+
+**Purpose:** What must be true before starting this step.
+
+**Required:** Yes, if step has dependencies.
+
+**Content:** Bullet list of requirements.
+
+**Example:**
+```xml
+<prerequisites>
+- PRD document exists at `{planning_artifacts}/prd.md`
+- Previous step (discovery) completed
+- User has approved problem statement
+</prerequisites>
+```
+
+---
+
+### `<instructions>`
+
+**Purpose:** Step-by-step guide for executing this workflow step.
+
+**Required:** Yes
+
+**Content:** Numbered list of actions.
+
+**Example:**
+```xml
+<instructions>
+1. Read the PRD document to understand requirements
+2. Identify key architectural concerns
+3. List candidate patterns that address concerns
+4. Evaluate trade-offs for each pattern
+5. Document recommendation with rationale
+</instructions>
+```
+
+**Guidelines:**
+- Use imperative voice ("Read", "Identify", "Document")
+- Keep steps atomic and actionable
+- Order reflects execution sequence
+
+---
+
+### `<actions>`
+
+**Purpose:** Specific file and script operations for this step.
+
+**Required:** Recommended for steps with file operations.
+
+**Content:** Bullet list with action type prefix.
+
+**Action Types:**
+| Prefix | Description |
+|--------|-------------|
+| `Check:` | Verify condition exists |
+| `Read:` | Load file(s) for input |
+| `Write:` | Create or update file |
+| `Run:` | Execute script |
+| `Create:` | Create new file/directory |
+| `Delete:` | Remove file (cleanup) |
+
+**Example:**
+```xml
+<actions>
+- Check: `{output_file}` for existing workflow (continuation detection)
+- Read: `{planning_artifacts}/*prd*.md`
+- Read: `docs/adr/*.md` (scan for relevant prior decisions)
+- Write: `{output_file}` with architecture session content
+</actions>
+```
+
+**Variable Placeholders:**
+| Variable | Description |
+|----------|-------------|
+| `{output_file}` | Workflow output document |
+| `{planning_artifacts}` | Planning docs directory |
+| `{project_root}` | Project root directory |
+| `{story_id}` | Current story ID |
+
+---
+
+### `<output>`
+
+**Purpose:** What this step produces.
+
+**Required:** Yes
+
+**Content:** Description of deliverable, format, required sections.
+
+**Example:**
+```xml
+<output>
+Add to session file:
+
+```markdown
+## Architecture Session: {project_name}
+
+### Patterns Evaluated
+| Pattern | Pros | Cons | Fit |
+|---------|------|------|-----|
+| Pattern A | ... | ... | High |
+| Pattern B | ... | ... | Medium |
+
+### Recommendation
+[Selected pattern with rationale]
+```
+</output>
+```
+
+---
+
+### `<gate>`
+
+**Purpose:** Checkpoint criteria that must be met before proceeding.
+
+**Required:** If `gate: true` in step-meta.
+
+**Content:** Checklist of completion criteria.
+
+**Example:**
+```xml
+<gate>
+## Completion Criteria
+- [ ] At least 3 patterns evaluated
+- [ ] Trade-offs documented for each
+- [ ] User confirmed recommendation
+- [ ] No blocking questions remain
+</gate>
+```
+
+**Guidelines:**
+- Use checkbox format for trackable criteria
+- Include user confirmation if step requires approval
+- Keep criteria objective and verifiable
+
+---
+
+### `<collaboration-menu>`
+
+**Purpose:** Present user options after step completion.
+
+**Required:** Recommended for interactive workflows.
+
+**Content:** Standard menu options with keyboard shortcuts.
+
+**Standard Options:**
+| Option | Description |
+|--------|-------------|
+| `[C] Continue` | Proceed to next step |
+| `[R] Revise` | Make changes to current output |
+| `[H] Help` | Get guidance or clarification |
+| `[S] Skip` | Skip optional step |
+| `[B] Back` | Return to previous step |
+| `[A] Advanced` | Access additional features |
+
+**Example:**
+```xml
+<collaboration-menu>
+- **[C] Continue** - Proceed to Component Design
+- **[R] Revise** - Update pattern selection
+- **[H] Help** - Get guidance on pattern trade-offs
+- **[B] Back** - Return to Context Analysis
+</collaboration-menu>
+```
+
+---
+
+### `<next-step>`
+
+**Purpose:** Explicit navigation to the next step.
+
+**Required:** Recommended for clarity.
+
+**Content:** Instruction on which file to load next.
+
+**Example:**
+```xml
+<next-step>
+After gate passes, proceed to step-04-components.md for Component Design.
+</next-step>
+```
+
+---
+
+## Optional Sections
+
+### Failure Modes
+
+**Purpose:** Common mistakes to avoid.
+
+**Format:** Plain markdown section (not XML-tagged).
+
+```markdown
+## Failure Modes
+
+- Proceeding with fresh initialization when existing workflow exists
+- Not detecting PRD requirement
+- Not confirming inputs with user before proceeding
+```
+
+### Success Metrics
+
+**Purpose:** How to know the step succeeded.
+
+**Format:** Plain markdown section (not XML-tagged).
+
+```markdown
+## Success Metrics
+
+- All gate criteria checked
+- User confirmed satisfaction
+- Output matches expected format
+```
+
+### Continuation Detection
+
+**Purpose:** Logic for resuming an interrupted workflow.
+
+**Format:** Plain markdown section.
+
+```markdown
+## Continuation Detection
+
+1. Look for existing `{output_file}`
+2. If exists, read complete file including frontmatter
+3. If frontmatter has `stepsCompleted` array → Load `./step-01b-continue.md`
+4. If not exists → proceed with fresh initialization
+```
+
+---
+
+## Complete Example
+
+```markdown
+# Step 3: Pattern Selection
+
+<step-meta>
+number: 3
+name: patterns
+gate: true
+next: step-04-components
+</step-meta>
+
+<purpose>
+Evaluate architectural patterns that address the identified concerns and select the most appropriate approach.
+</purpose>
+
+<prerequisites>
+- Context analysis complete (step 2)
+- Key concerns documented
+- Constraints understood
+</prerequisites>
+
+<instructions>
+1. Review concerns identified in context analysis
+2. Identify candidate patterns (minimum 3)
+3. Evaluate each pattern against constraints
+4. Document trade-offs for each option
+5. Select recommended pattern with rationale
+6. Present options to user for confirmation
+</instructions>
+
+<actions>
+- Read: `{output_file}` for context analysis
+- Read: `docs/patterns/*.md` for pattern library
+- Write: Pattern evaluation matrix to `{output_file}`
+</actions>
+
+<output>
+Add to architecture document:
+
+```markdown
+## Pattern Evaluation
+
+### Candidate Patterns
+1. **Pattern A** - [brief description]
+2. **Pattern B** - [brief description]
+3. **Pattern C** - [brief description]
+
+### Evaluation Matrix
+| Pattern | Scalability | Complexity | Team Familiarity | Fit |
+|---------|-------------|------------|------------------|-----|
+| A | High | Medium | High | Best |
+| B | Medium | Low | High | Good |
+| C | High | High | Low | Poor |
+
+### Recommendation
+[Selected pattern] because [rationale]
+```
+</output>
+
+<gate>
+## Completion Criteria
+- [ ] At least 3 patterns evaluated
+- [ ] Trade-offs documented for each
+- [ ] Recommendation includes rationale
+- [ ] User confirmed pattern selection
+</gate>
+
+<collaboration-menu>
+- **[C] Continue** - Proceed to Component Design
+- **[R] Revise** - Re-evaluate pattern options
+- **[H] Help** - Get guidance on pattern trade-offs
+- **[B] Back** - Return to Context Analysis
+</collaboration-menu>
+
+<next-step>
+After user confirms pattern selection, proceed to step-04-components.md for Component Design.
+</next-step>
+
+## Failure Modes
+
+- Selecting pattern without evaluating alternatives
+- Ignoring team familiarity constraints
+- Not getting user confirmation
+
+## Success Metrics
+
+- Multiple patterns evaluated objectively
+- Selection justified with clear rationale
+- User confirmed recommended approach
+```
+
+---
+
+## Tag Summary
+
+| Tag | Purpose | Required |
+|-----|---------|----------|
+| `<step-meta>` | Step metadata | Yes |
+| `<purpose>` | Step goal | Yes |
+| `<prerequisites>` | Requirements | If applicable |
+| `<instructions>` | Step-by-step guide | Yes |
+| `<actions>` | File operations | Recommended |
+| `<output>` | Deliverable description | Yes |
+| `<gate>` | Completion criteria | If gate:true |
+| `<collaboration-menu>` | User options | Recommended |
+| `<next-step>` | Navigation hint | Recommended |
+
+---
+
+## Migration Checklist
+
+When updating existing step files:
+
+- [ ] Ensure `# Step N: Title` header present
+- [ ] Add `<step-meta>` with all required fields
+- [ ] Wrap purpose in `<purpose>` tags
+- [ ] Wrap prerequisites in `<prerequisites>` tags
+- [ ] Wrap instructions in `<instructions>` tags
+- [ ] Add `<actions>` for file operations
+- [ ] Wrap output template in `<output>` tags
+- [ ] Add `<gate>` if step has checkpoint
+- [ ] Add `<collaboration-menu>` with standard options
+- [ ] Add `<next-step>` navigation hint
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `guides/xml-tags.md` | Complete XML tag taxonomy |
+| `guides/workflow-schema.md` | Workflow YAML configuration |
+| `workflows/architecture/steps/step-01-initialize.md` | Reference implementation |

package/pennyfarthing-dist/guides/worktree-mode.md

@@ -0,0 +1,113 @@
+# Worktree Mode
+
+Work on multiple stories in parallel using git worktrees.
+
+## When to Use
+
+- Working on a second story while waiting for PR review
+- Urgent bug fix while feature work is in progress
+- Comparing implementations side-by-side
+
+## Quick Start
+
+```
+/parallel-work
+```
+
+This creates a worktree, sets up the session, and starts the TDD flow.
+
+## How It Works
+
+### Session Files
+
+```
+.session/
+├── 5-2-session.md               # Story 5-2 (main checkout)
+└── 5-3a-session.md              # Story 5-3a (worktree)
+```
+
+Naming convention: `{story-id}-session.md`
+Worktree info is stored INSIDE the session file, not in the filename.
+
+### Worktree Directory Structure
+
+```
+worktrees/
+└── wt-5-3a/
+    ├── Pennyfarthing-api/    # API repo worktree
+    └── Pennyfarthing-ui/     # UI repo worktree
+```
+
+### Session File Format
+
+Worktree sessions include a context section:
+
+```yaml
+## Worktree Context
+worktree: wt-5-3a
+path: /path/to/worktrees/wt-5-3a
+api_port: 8082
+ui_port: 5175
+```
+
+Agents read this to know:
+- They're in a worktree
+- Where the worktree lives
+- Which ports to use
+
+## Agent Detection
+
+Agents detect worktree context from the session file:
+
+```bash
+# Check if worktree session
+if grep -q "^worktree:" "$SESSION_FILE"; then
+    WORKTREE_NAME=$(grep "^worktree:" "$SESSION_FILE" | cut -d' ' -f2)
+    WORKTREE_PATH=$(grep "^path:" "$SESSION_FILE" | cut -d' ' -f2)
+fi
+```
+
+No filename parsing needed.
+
+## Port Management
+
+Each worktree gets offset ports to avoid conflicts:
+
+| Worktree | API Port | UI Port | WebSocket |
+|----------|----------|---------|-----------|
+| main     | 8080     | 5173    | 8081      |
+| wt-1     | 8082     | 5175    | 8083      |
+| wt-2     | 8084     | 5177    | 8085      |
+
+Ports are stored in the session file and passed to agents.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/parallel-work` | Start a new parallel work session |
+| `.pennyfarthing/scripts/git/worktree-manager.sh list` | Show active worktrees |
+| `.pennyfarthing/scripts/git/worktree-manager.sh remove <name>` | Clean up a worktree |
+
+## TDD Flow in Worktrees
+
+Same flow as main checkout:
+
+```
+/parallel-work → SM → TEA → Dev → Reviewer → SM (finish)
+```
+
+Agents use worktree paths from session file for all operations.
+
+## Cleanup
+
+When story is complete, SM archives the session and the worktree can be removed:
+
+```bash
+.pennyfarthing/scripts/git/worktree-manager.sh remove wt-5-3a
+```
+
+This removes:
+- Git worktrees
+- Session file
+- Port allocations