@pennyfarthing/core 10.0.1 → 10.0.2

package/pennyfarthing-dist/commands/standalone.md

@@ -0,0 +1,194 @@
+---
+description: Wrap current changes into a standalone Jira story, branch, PR, and merge
+---
+
+# Standalone Story
+
+Quickly wrap dirty changes into a tracked Jira story without the full sprint/workflow ceremony. Creates a Jira ticket, feature branch, commits, pushes, creates PR, and merges.
+
+<purpose>
+Fast path for shipping completed work that deserves tracking but doesn't need story setup upfront.
+</purpose>
+
+<when-to-use>
+- You've done exploratory work that turned into something shippable
+- A bug fix or feature emerged during other work
+- Process improvements that should be tracked
+- Any change worth a Jira ticket but not a full sprint story
+</when-to-use>
+
+<usage>
+```bash
+# Interactive: prompts for title and description
+/standalone
+
+# With title
+/standalone "Add drift detection script"
+
+# With title and points
+/standalone "Add drift detection script" 2
+```
+</usage>
+
+<workflow>
+1. Verify dirty files exist (abort if clean)
+2. Show changes and confirm with user
+3. Create Jira story (prompts for title/description if not provided)
+4. Add story to current sprint and mark Done
+5. Create feature branch: `feat/MSSCI-XXXXX-{slug}`
+6. Stage and commit changes
+7. Push branch
+8. Create PR with summary
+9. Merge PR (squash) and delete branch
+10. Return to develop
+</workflow>
+
+## Execution
+
+### Step 1: Pre-Flight
+
+```bash
+# Abort if clean
+git diff --quiet && git diff --cached --quiet && {
+  echo "ERROR: No changes to commit."
+  exit 1
+}
+
+echo "=== Changes to Commit ==="
+git status --short
+git diff --stat
+```
+
+### Step 2: Gather Story Info
+
+If title not provided, prompt:
+- **Title:** Short summary (becomes Jira summary and commit message)
+- **Description:** What was done (becomes Jira description and PR body)
+- **Points:** Story points (default: 2)
+
+```bash
+# Defaults
+TITLE="${1:-}"
+POINTS="${2:-2}"
+
+if [ -z "$TITLE" ]; then
+  # Prompt user for title
+  echo "Enter story title:"
+  read TITLE
+fi
+
+# Generate description from changed files
+CHANGED_FILES=$(git status --porcelain | awk '{print $2}')
+DESCRIPTION="## Changes
+$(git diff --stat)
+
+## Files
+$(echo "$CHANGED_FILES" | head -20)"
+```
+
+### Step 3: Create Jira Story
+
+```bash
+# Create Jira story
+JIRA_OUTPUT=$(jira issue create \
+  --project MSSCI \
+  --type Story \
+  --summary "$TITLE" \
+  --body "$DESCRIPTION" \
+  --label pennyfarthing \
+  --custom story-points="$POINTS" \
+  --no-input 2>&1)
+
+JIRA_KEY=$(echo "$JIRA_OUTPUT" | grep -oE 'MSSCI-[0-9]+' | head -1)
+
+if [ -z "$JIRA_KEY" ]; then
+  echo "ERROR: Failed to create Jira story"
+  echo "$JIRA_OUTPUT"
+  exit 1
+fi
+
+echo "Created: $JIRA_KEY"
+
+# Add to sprint and mark done
+jira sprint add 276 "$JIRA_KEY"
+jira issue move "$JIRA_KEY" "Done"
+```
+
+### Step 4: Create Branch and Commit
+
+```bash
+# Generate slug from title
+SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-30)
+
+# Stash, update develop, create branch
+git stash push -m "standalone-wip-$(date +%s)"
+git checkout develop && git pull origin develop
+BRANCH="feat/${JIRA_KEY}-${SLUG}"
+git checkout -b "$BRANCH"
+git stash pop
+
+# Stage and commit
+git add .
+git commit -m "feat: ${TITLE} (${JIRA_KEY})
+
+${DESCRIPTION}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+```
+
+### Step 5: Push and Create PR
+
+```bash
+git push -u origin "$BRANCH"
+
+gh pr create \
+  --title "feat: ${TITLE} (${JIRA_KEY})" \
+  --body "## Summary
+${DESCRIPTION}
+
+## Jira
+[${JIRA_KEY}](https://1898andco.atlassian.net/browse/${JIRA_KEY})
+
+## Test plan
+- [x] Changes verified locally
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)"
+```
+
+### Step 6: Merge and Cleanup
+
+```bash
+# Get PR number and merge
+PR_URL=$(gh pr view --json url -q '.url')
+gh pr merge --squash --delete-branch
+
+# Return to develop
+git checkout develop
+git pull origin develop
+
+echo "✅ Done: $JIRA_KEY merged"
+echo "   Jira: https://1898andco.atlassian.net/browse/$JIRA_KEY"
+echo "   PR: $PR_URL"
+```
+
+## Safety
+
+- **NEVER commit directly to develop**
+- **Never force push**
+- **Never commit secrets** (.env, credentials)
+- **Abort if working directory is clean**
+- **Confirm changes before proceeding**
+
+## Comparison
+
+| Command | Tracking | Branch | PR | Use For |
+|---------|----------|--------|-----|---------|
+| `/chore` | None | chore/* | No | Quick maintenance |
+| `/standalone` | Jira | feat/* | Yes | Trackable features |
+| `/sprint work` | Jira + Sprint | feat/* | Yes | Planned sprint work |
+
+<related>
+- `/chore` - Quick commits without Jira tracking
+- `/sprint work` - Full sprint workflow with story setup
+- `/git-cleanup` - Organize multiple changes into groups
+</related>

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

@@ -0,0 +1,168 @@
+---
+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` - Pennyfarthing 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/misc/session-cleanup.sh --dry-run
+
+# If dry-run looks good, run actual cleanup
+$CLAUDE_PROJECT_DIR/scripts/misc/session-cleanup.sh
+
+# Archive epic contexts for completed epics
+$CLAUDE_PROJECT_DIR/scripts/misc/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]
+  # ===========================================================================
+  - id: MSSCI-XXXXX
+    type: epic
+    title: "Epic: [Name]"
+    points: [total_pts]
+    completed_points: 0
+    priority: P1
+    status: in_progress
+    stories:
+      # Stories added during tech context generation
+      - id: MSSCI-XXXXX
+        title: "[Story title]"
+        points: [N]
+        priority: P2
+        status: backlog
+        repos: [cyclist|pennyfarthing|both]
+        workflow: [tdd|trivial|agent-docs]
+        acceptance_criteria:
+          - [AC 1]
+          - [AC 2]
+```
+
+### 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 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/jira/jira-sync-story.sh 35-2-topology-editor
+
+# Transition to match Pennyfarthing status
+./scripts/jira/jira-sync-story.sh 35-2-topology-editor --transition
+
+# Add a comment
+./scripts/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/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