@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/commands/start-epic.md

@@ -0,0 +1,156 @@
+---
+description: Start an epic - move to current sprint and generate tech context
+---
+
+# Start Epic Workflow
+
+**This command prepares an epic for development by moving it to the current sprint and generating technical context.**
+
+## What This Does
+
+1. **Validates** the epic exists in backlog or current sprint
+2. **Moves** the epic to current sprint if not already there
+3. **Runs** the SM agent's `epic-tech-context` task to generate technical specifications
+
+## Prerequisites
+
+```bash
+cd $CLAUDE_PROJECT_DIR
+
+# Verify sprint files exist
+if [ ! -f "sprint/current-sprint.yaml" ] || [ ! -f "sprint/backlog.yaml" ]; then
+    echo "ERROR: Sprint files not found"
+    exit 1
+fi
+
+echo "Sprint files found - ready to start epic"
+```
+
+## Usage
+
+Provide the epic ID when invoking this command:
+- `epic-5` - Conductor epic (format: `epic-N`)
+
+## Workflow Steps
+
+### Step 0: Clean Previous Work Artifacts
+
+Before starting a new epic, clean up stale artifacts from previous work:
+
+```bash
+cd $CLAUDE_PROJECT_DIR
+
+# Run conservative cleanup (7+ day old artifacts)
+$CLAUDE_PROJECT_DIR/scripts/run.sh session-cleanup.sh --dry-run
+
+# If dry-run looks good, run actual cleanup
+$CLAUDE_PROJECT_DIR/scripts/run.sh session-cleanup.sh
+
+# Archive epic contexts for completed epics
+$CLAUDE_PROJECT_DIR/scripts/run.sh session-cleanup.sh --aggressive
+```
+
+This ensures a clean slate before starting new epic work and archives contexts from completed epics.
+
+### Step 1: Identify Epic
+
+Ask the user for the epic ID if not provided:
+> "Which epic would you like to start? (e.g., epic-5, sim-epic-10)"
+
+### Step 2: Check Epic Location
+
+```bash
+cd $CLAUDE_PROJECT_DIR
+
+# Check if epic is in current sprint
+if grep -q "^$EPIC_ID:" sprint/current-sprint.yaml; then
+    echo "Epic $EPIC_ID is already in current sprint"
+    EPIC_LOCATION="current"
+elif grep -q "^$EPIC_ID:" sprint/backlog.yaml; then
+    echo "Epic $EPIC_ID found in backlog - will move to current sprint"
+    EPIC_LOCATION="backlog"
+else
+    echo "ERROR: Epic $EPIC_ID not found in sprint files"
+    exit 1
+fi
+```
+
+### Step 3: Move Epic to Current Sprint (if needed)
+
+If the epic is in backlog:
+
+1. **Extract** the epic block from `sprint/backlog.yaml`
+2. **Add** the epic to `sprint/current-sprint.yaml` under the active work section
+3. **Update** the epic status from `backlog` or `planned` to `in-progress`
+4. **Remove** the epic from `sprint/backlog.yaml`
+
+**Format for current-sprint.yaml:**
+```yaml
+# Epic [N]: [Name] ([points] pts)
+# [Description]
+epic-N:
+  name: "[Epic Name]"
+  status: in-progress
+  points: [N]
+  priority: [High|Medium|Low]
+  repos: [api|ui|both]
+  stories:
+    # Stories will be added during tech context generation
+```
+
+### Step 4: Generate Epic Tech Context
+
+Invoke the SM agent with the `epic-tech-context` task:
+
+**Run:** `/sm` with task: `epic-tech-context` for epic `$EPIC_ID`
+
+The SM agent will:
+1. Load the epic details from current sprint
+2. Analyze the codebase for relevant files
+3. Generate technical context including:
+   - Current state analysis
+   - Technical approach
+   - File modifications needed
+   - API/UI changes
+   - Database changes
+   - Testing strategy
+   - Story breakdown with acceptance criteria
+4. Save context to `.session/context-epic-$EPIC_ID.md`
+
+### Step 5: Confirm Ready
+
+After tech context is generated:
+
+```
+✅ Epic $EPIC_ID is ready for development
+
+Next steps:
+1. Review the tech context: cat .session/context-epic-$EPIC_ID.md
+2. Start first story: /new-work
+3. SM will select from this epic's stories
+```
+
+## Example
+
+```bash
+# User invokes: /start-epic epic-5
+
+# Output:
+# → Checking epic-5 location...
+# → Epic epic-5 found in backlog
+# → Moving epic-5 to current sprint...
+# → Updating status to in-progress...
+# → Invoking SM for epic-tech-context...
+# → [SM generates technical context]
+# → ✅ Epic epic-5 is ready for development
+```
+
+## Notes
+
+- This command does NOT start a story - use `/new-work` for that
+- The epic tech context provides the foundation for story-level work
+- Stories within the epic will be worked via the normal TDD flow
+
+---
+
+**Flow:** `/start-epic` → SM (epic-tech-context) → `/new-work` → TDD cycle

package/pennyfarthing-dist/commands/sync-epic-to-jira.md

@@ -0,0 +1,184 @@
+---
+description: Sync Pennyfarthing epic to Jira MSSCI project using jira CLI
+---
+
+# Sync Epic to Jira Workflow
+
+This workflow syncs a Pennyfarthing epic and its stories to Jira using the `jira` CLI tool.
+
+**IMPORTANT:** All Pennyfarthing issues MUST be labeled with `pennyfarthing` to distinguish them from Conductor work.
+
+## Prerequisites
+
+- `jira` CLI installed: `brew install ankitpokhrel/jira-cli/jira-cli`
+- `jira` CLI configured: `jira init`
+- Epic exists in `sprint/current-sprint.yaml`
+
+**For complete jira CLI reference, see the `jira` skill** (`.claude/skills/jira/SKILL.md`). The examples below are quick references; the skill has troubleshooting, user mappings, and edge cases.
+
+## Label Requirement
+
+All Pennyfarthing epics and stories must include the `pennyfarthing` label:
+```bash
+-l pennyfarthing
+```
+
+## Quick Sync
+
+### Sync a Single Story
+
+```bash
+# View story status
+./scripts/run.sh jira-sync-story.sh 35-2-topology-editor
+
+# Transition to match Conductor status
+./scripts/run.sh jira-sync-story.sh 35-2-topology-editor --transition
+
+# Add a comment
+./scripts/run.sh jira-sync-story.sh 35-2-topology-editor --comment "Started development"
+```
+
+### Sync All Stories in Epic
+
+```bash
+# For each story in the epic, sync status
+for story in $(yq '.epic-35.stories | keys | .[]' sprint/current-sprint.yaml); do
+    ./scripts/run.sh jira-sync-story.sh "$story" --transition
+done
+```
+
+## Manual Jira CLI Commands
+
+**IMPORTANT:** Most commands require `-p MSSCI` (project flag) even when the issue key contains the project prefix.
+
+### View Issue
+
+```bash
+jira issue view MSSCI-123
+```
+
+### Create Story
+
+```bash
+jira issue create \
+    -p MSSCI \
+    -tStory \
+    -s"Story 1-5: Add Epic Context Guardrail" \
+    -b"Description here" \
+    -yHigh \
+    -l pennyfarthing \
+    --no-input
+```
+
+### Create Epic
+
+```bash
+jira issue create \
+    -p MSSCI \
+    -tEpic \
+    -s"Epic 1: Agentic Best Practices Implementation" \
+    -b"Epic description" \
+    -l pennyfarthing \
+    --no-input
+```
+
+### Link Story to Epic
+
+```bash
+# Use --parent to link a story to its epic
+jira issue create \
+    -p MSSCI \
+    -tStory \
+    -s"Story Title" \
+    --parent MSSCI-EPIC_KEY \
+    -l pennyfarthing \
+    --no-input
+```
+
+### Assign Issue
+
+```bash
+# Assign to self
+jira issue assign -p MSSCI MSSCI-123 "$(jira me)"
+
+# Assign to someone else
+jira issue assign -p MSSCI MSSCI-123 "john.doe@1898andco.io"
+```
+
+### Transition Issue
+
+```bash
+jira issue move MSSCI-123 "In Progress" -p MSSCI
+jira issue move MSSCI-123 "In Review" -p MSSCI
+jira issue move MSSCI-123 "Done" -p MSSCI
+```
+
+### Add Comment
+
+```bash
+jira issue comment add MSSCI-123 "Development started on branch feat/35-2"
+```
+
+### Link Issues
+
+```bash
+jira issue link MSSCI-123 MSSCI-124 "Blocks"
+```
+
+### List Issues
+
+```bash
+# All in-progress stories
+jira issue list -s "In Progress"
+
+# Stories in current sprint
+jira sprint list --current
+
+# Stories assigned to me
+jira issue list -a$(jira me)
+```
+
+## Status Mapping
+
+| Conductor | Jira |
+|-----------|------|
+| `backlog` | To Do |
+| `in-progress` | In Progress |
+| `review` | In Review |
+| `done` | Done |
+
+## Priority Mapping
+
+| Conductor | Jira |
+|-----------|------|
+| `P0` | Highest |
+| `P1` | High |
+| `P2` | Medium |
+
+## Troubleshooting
+
+**jira CLI not configured:**
+```bash
+jira init
+# Follow prompts to authenticate
+```
+
+**Issue not found:**
+- Check the Jira key is correct
+- Verify you have access to the project
+
+**Transition not available:**
+- Some transitions require specific conditions
+- Check the Jira workflow for allowed transitions
+
+## Related Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `jira-claim-story.sh` | Check/claim story assignment |
+| `jira-sync-story.sh` | Sync single story status |
+| `sync-epic-to-jira.sh` | Generate sync report for epic |
+
+---
+
+**Last Updated**: 2025-12-16

package/pennyfarthing-dist/commands/sync-work-with-sprint.md

@@ -0,0 +1,376 @@
+---
+description: Sync Pennyfarthing work session with unified sprint status
+---
+
+# Sync Work Session with Sprint Status
+
+This workflow helps you coordinate your Pennyfarthing work session with the unified sprint status tracking.
+
+## Prerequisites
+
+- [ ] Active work session exists (`.session/{STORY_ID}-session.md`)
+- [ ] You know which story/epic you're working on
+
+## Unified Sprint Status
+
+**Location:** `sprint/sprint-status.yaml`
+
+This single file tracks work across both API and UI repos, making coordination simple.
+
+## Steps
+
+### 1. View Current Sprint Status
+
+Check the unified sprint status:
+
+```bash
+cat sprint/sprint-status.yaml
+```
+
+**Current Sprint 1 - Coordinated Development Setup:**
+- Epic 1: Coordinated Development Setup - IN PROGRESS (2/5 done)
+  - 1-1: Pennyfarthing Solo Dev Setup - done
+  - 1-2: Cross-Repo Workflows - done
+  - 1-3: Environment Configuration - backlog
+  - 1-4: API Connection Verification - backlog
+  - 1-5: Development Documentation - backlog
+
+- Epic 2: Critical Bug Fixes - BACKLOG (plan as needed)
+- Epic 3: Core Feature Development - BACKLOG (plan as needed)
+
+### 2. Update Pennyfarthing Session with Story Info
+
+Edit `.session/{STORY_ID}-session.md` to include story details:
+
+```markdown
+# Feature: [Story Title]
+
+**Story ID:** [Epic-Story] (e.g., 1-3, 1-4)
+**Repos:** [X] API  [X] UI  [X] Both
+**Date:** [YYYY-MM-DD]
+**Epic:** [Epic Number and Name]
+**Priority:** [P0/P1/P2]
+**Points:** [Story Points]
+
+## Goal
+[Copy from sprint status story description]
+
+## Story Context
+**Sprint Status:** sprint/sprint-status.yaml
+**Story Line:** [Line number in sprint status]
+
+## Scope
+- [ ] [Task from story]
+- [ ] [Task from story]
+- [ ] [Task from story]
+
+## API Changes
+- Files: [from story prerequisites]
+- Endpoints: [from story description]
+
+## UI Changes
+- Files: [from story prerequisites]
+- Components: [from story description]
+
+## Prerequisites
+[Copy from sprint status]
+
+## Acceptance Criteria
+[Copy from story file if exists]
+
+## Quick Notes
+[Your implementation notes]
+
+## Done
+- [ ] Tests pass
+- [ ] Works as expected
+- [ ] Committed
+- [ ] Sprint status updated
+
+## Next
+[Next story in epic or next epic]
+```
+
+### 3. Update Sprint Status to "in-progress"
+
+When you start work, update the sprint status file:
+
+**For API work:**
+```bash
+cd $CLAUDE_PROJECT_DIR/API
+
+# Edit sprint status
+# Change story status from 'backlog' to 'in-progress'
+# Example: 2-2-okta-sso-integration: in-progress
+```
+
+**For UI work:**
+```bash
+cd $CLAUDE_PROJECT_DIR/UI
+
+# Edit sprint status
+# Change story status from 'backlog' to 'in-progress'
+# Example: 5-2-environment-configuration-validation: in-progress
+```
+
+### 4. Work on the Story
+
+Follow your Pennyfarthing session and check off tasks as you complete them.
+
+### 5. Update Sprint Status to "done"
+
+When work is complete:
+
+**For API work:**
+```bash
+cd $CLAUDE_PROJECT_DIR/API
+
+# Edit sprint status
+# Change: 2-2-okta-sso-integration: done
+# Add completion date if tracking
+```
+
+**For UI work:**
+```bash
+cd $CLAUDE_PROJECT_DIR/UI
+
+# Edit sprint status
+# Change: 5-2-environment-configuration-validation: done
+# Add completion date and commit SHA if tracking
+```
+
+### 6. Commit Sprint Status Updates
+
+```bash
+# API
+cd $CLAUDE_PROJECT_DIR/API
+git add docs/sprint-artifacts/sprint-status.yaml
+git commit -m "chore: update sprint status for story [ID]"
+
+# UI
+cd $CLAUDE_PROJECT_DIR/UI
+git add docs/sprint-artifacts/sprint-status.yaml
+git commit -m "chore: update sprint status for story [ID]"
+```
+
+### 7. Archive Pennyfarthing Session
+
+```bash
+cd $CLAUDE_PROJECT_DIR
+# Invoke /sm and run finish-story task
+# Archive with story ID: story-5-2-env-config-20241202.md
+```
+
+## Current Sprint Focus
+
+### API - Next Stories to Work On
+
+**Epic 2: Authentication (In Progress)**
+- 2-2-okta-sso-integration: backlog → Ready to start
+- 2-5-mfa-multi-factor-authentication: backlog → After 2-2
+
+### UI - Next Stories to Work On
+
+**Epic 1: Dev Tooling (In Progress - 1/8 done)**
+- 1-3-environment-configuration-files: backlog → Priority P0
+- 1-4-root-level-development-orchestration: backlog → Priority P1
+- 1-5-cross-repo-scripts: backlog → Priority P1
+- 1-6-api-contract-synchronization: backlog → Priority P1
+
+**Epic 5: Bug Fixes (In Progress - 1/10 done)**
+- 5-2-environment-configuration-validation: backlog → Priority P0
+- 5-3-route-validation-and-navigation-testing: backlog → Priority P1
+- 5-4-api-integration-testing: backlog → Priority P0
+
+## Story Status Workflow
+
+```
+backlog → in-progress → review → done
+```
+
+**Status Definitions:**
+- `backlog`: Story exists but not started
+- `drafted`: Story file created (if applicable)
+- `ready-for-dev`: Story approved and contexted
+- `in-progress`: Actively working (update when you start)
+- `review`: Under review (code review)
+- `done`: Completed (update when finished)
+
+## Example: Complete Story Workflow
+
+### Story: UI 5-2 Environment Configuration Validation
+
+```bash
+# 1. Start work session
+cd $CLAUDE_PROJECT_DIR
+./scripts/run.sh new-work.sh
+
+# 2. Edit session with story details
+cat > .session/{STORY_ID}-session.md << 'EOF'
+# Feature: Environment Configuration Validation
+
+**Story ID:** 5-2
+**Repos:** [ ] API  [X] UI  [ ] Both
+**Date:** 2024-12-02
+**Epic:** Epic 5 - Bug Fixes & Split Issues Resolution
+**Priority:** P0
+**Points:** 3
+
+## Goal
+Validate environment configuration files and ensure proper loading
+
+## Story Context
+**UI Story:** UI/docs/sprint-artifacts/sprint-status.yaml#L229
+**Prerequisites:** Epic 1 (Dev Tooling)
+
+## Scope
+- [ ] Validate .env files exist
+- [ ] Check required environment variables
+- [ ] Add runtime validation
+- [ ] Update documentation
+
+## UI Changes
+- Files: src/config/env.ts, src/utils/validation.ts
+- Components: ErrorBoundary updates
+
+## Quick Notes
+- Check for missing API_BASE_URL
+- Validate WebSocket URL format
+- Add helpful error messages
+
+## Done
+- [ ] Tests pass
+- [ ] Works as expected
+- [ ] Committed
+- [ ] Sprint status updated
+
+## Next
+Story 5-3: Route validation
+EOF
+
+# 3. Update sprint status to in-progress
+cd UI
+# Edit: 5-2-environment-configuration-validation: in-progress
+
+# 4. Do the work
+# ... implement validation ...
+
+# 5. Commit work
+git add .
+git commit -m "feat: add environment configuration validation (story 5-2)"
+
+# 6. Update sprint status to done
+# Edit: 5-2-environment-configuration-validation: done
+
+# 7. Commit sprint status
+git add docs/sprint-artifacts/sprint-status.yaml
+git commit -m "chore: mark story 5-2 as done"
+
+# 8. Archive session
+cd ..
+# Invoke /sm and run finish-story task
+# Archive as: story-5-2-env-validation-20241202.md
+```
+
+## Tips
+
+### Link Story Files
+
+If a story has a detailed `.md` file, reference it:
+
+```markdown
+## Story Context
+**Story File:** UI/docs/sprint-artifacts/stories/5-2-environment-configuration-validation.md
+**Sprint Status:** UI/docs/sprint-artifacts/sprint-status.yaml#L229
+```
+
+### Track Story Points
+
+Include story points in your session for velocity tracking:
+
+```markdown
+**Points:** 3
+**Estimated Hours:** 4-6
+**Actual Hours:** [fill in when done]
+```
+
+### Cross-Repo Stories
+
+For stories that span both repos:
+
+```markdown
+**Repos:** [X] API  [X] UI  [X] Both
+
+## API Story
+**ID:** 2-2-okta-sso-integration
+**Status:** API/docs/sprint-artifacts/sprint-status.yaml#L50
+
+## UI Story
+**ID:** 3-2-client-context-propagation
+**Status:** UI/docs/sprint-artifacts/sprint-status.yaml#L147
+```
+
+### Epic Progress Tracking
+
+Track epic progress in your session:
+
+```markdown
+## Epic Progress
+**Epic 5:** Bug Fixes (1/10 stories done, 5/47 points)
+**This Story:** 5-2 (3 points)
+**After This:** 2/10 stories, 8/47 points (17%)
+```
+
+## Integration with Workflows
+
+### With /create-branches-from-story
+
+```bash
+# 1. Create branches with story ID
+@/create-branches-from-story
+# Branch: feature/5-2-env-config-validation
+
+# 2. Session already created, add story details
+# Edit .session/{STORY_ID}-session.md with sprint info
+
+# 3. Update sprint status to in-progress
+
+# 4. Work, commit, update to done
+```
+
+### With /new-work
+
+```bash
+# 1. Start session
+@/new-work
+
+# 2. Look up story in sprint status
+
+# 3. Fill in session with story details
+
+# 4. Update sprint status
+```
+
+## Quick Reference
+
+```bash
+# View API sprint status
+cat API/docs/sprint-artifacts/sprint-status.yaml | grep -A 2 "epic-[0-9]:"
+
+# View UI sprint status
+cat UI/docs/sprint-artifacts/sprint-status.yaml | grep -A 2 "epic-[0-9]:"
+
+# Find story by ID
+grep "5-2-" UI/docs/sprint-artifacts/sprint-status.yaml
+
+# Update story status
+# Edit sprint-status.yaml: change 'backlog' to 'in-progress' or 'done'
+
+# Commit sprint status
+git add docs/sprint-artifacts/sprint-status.yaml
+git commit -m "chore: update sprint status for story [ID]"
+```
+
+---
+
+**Your Pennyfarthing session is now synced with sprint tracking!**