@pennyfarthing/core 7.5.0 → 7.6.1

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 Pennyfarthing 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/jira-sync-story.sh 35-2-topology-editor
+
+# Transition to match Pennyfarthing status
+./scripts/run.sh jira/jira-sync-story.sh 35-2-topology-editor --transition
+
+# Add a comment
+./scripts/run.sh jira/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/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
+
+| Pennyfarthing | Jira |
+|-----------|------|
+| `backlog` | To Do |
+| `in-progress` | In Progress |
+| `review` | In Review |
+| `done` | Done |
+
+## Priority Mapping
+
+| Pennyfarthing | 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,373 @@
+---
+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. Create session with story details
+cd $CLAUDE_PROJECT_DIR
+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!**

package/pennyfarthing-dist/commands/tea.md

@@ -0,0 +1,7 @@
+---
+description: Test Engineer/Architect - Test strategy and TDD
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/phase-check-start.sh "tea"
+```

package/pennyfarthing-dist/commands/tech-writer.md

@@ -0,0 +1,7 @@
+---
+description: Technical Writer - Documentation creation and maintenance
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "tech-writer"
+```