@pennyfarthing/core 10.3.1 → 11.0.0-alpha.0

package/pennyfarthing-dist/skills/pf-jira/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: jira
+description: Jira CLI commands for sprint management. Use when viewing, assigning, or updating Jira issues from the command line.
+args: "[view|check|claim|move|assign|create|sync|bidirectional|reconcile|link|search|sprint]"
+---
+
+# /pf-jira - Jira Issue Management
+
+<critical>
+Never fabricate or guess Jira IDs. Valid keys follow `MSSCI-XXXXX`. Old-style IDs like `31-18` are local sprint YAML placeholders.
+</critical>
+
+<run>
+pf jira <command> [args]
+</run>
+
+<output>
+Command-specific output. Most commands print status messages. Use `--dry-run` on mutating commands to preview changes.
+</output>
+
+## Quick Reference
+
+| Command | CLI | Purpose |
+|---------|-----|---------|
+| `/pf-jira view <key>` | `pf jira view <key>` | View issue details |
+| `/pf-jira check <key>` | `pf jira check <key>` | Check availability |
+| `/pf-jira claim <key>` | `pf jira claim <key> [--dry-run]` | Assign to self + In Progress |
+| `/pf-jira move <key> <status>` | `pf jira move <key> "<status>" [--dry-run]` | Transition status |
+| `/pf-jira assign <key> <user>` | `pf jira assign <key> <user> [--dry-run]` | Assign to user |
+| `/pf-jira link <p> <c> [type]` | `pf jira link <parent> <child> [type] [--dry-run]` | Link two issues |
+| `/pf-jira search "<jql>"` | `pf jira search "<jql>"` | Search by JQL |
+| `/pf-jira create epic <id>` | `pf jira create epic <id> [--dry-run]` | Create epic + stories |
+| `/pf-jira create story <ek> <sid>` | `pf jira create story <epic-key> <story-id> [--dry-run]` | Create single story |
+| `/pf-jira create standalone` | `pf jira create standalone "<title>" [opts]` | Create standalone story |
+| `/pf-jira sync <epic>` | `pf jira sync <epic> [--transition] [--points] [--all] [--dry-run]` | Sync epic to Jira |
+| `/pf-jira bidirectional` | `pf jira bidirectional [opts]` | Bidirectional sync |
+| `/pf-jira reconcile` | `pf jira reconcile [--fix]` | Reconciliation report |
+| `/pf-jira sprint add <sid> <key>` | `pf jira sprint add <sprint-id> <issue-key> [--dry-run]` | Add issue to sprint |
+
+### GitHub to Jira User Mapping
+
+| GitHub | Jira Email |
+|--------|------------|
+| slabgorb | keith.avery@1898andco.io |
+| arcaven | michael.pursifull@1898andco.io |
+| RoseSecurity | michael.rosenfeld@1898andco.io |
+| Zious11 | jared.richards@1898andco.io |
+| drbothen | joshua.magady@1898andco.io |
+
+### Prerequisites
+
+```bash
+brew install ankitpokhrel/jira-cli/jira-cli
+jira init
+export JIRA_API_TOKEN='your-token'
+```
+
+---
+
+**Detailed options and behavior:** [usage.md](usage.md)
+**Practical examples:** [examples.md](examples.md)

package/pennyfarthing-dist/skills/pf-jira/examples.md

@@ -0,0 +1,163 @@
+# Jira CLI — Examples
+
+## Viewing & Checking
+
+```bash
+# View issue details
+pf jira view MSSCI-12345
+
+# Check if story is available to claim
+pf jira check MSSCI-12345
+
+# Search by JQL
+pf jira search "project=MSSCI AND type=Epic"
+pf jira search "project=MSSCI AND parent=MSSCI-10980"
+pf jira search "project=MSSCI AND summary~'feedback rules'"
+```
+
+## Claiming & Assigning
+
+```bash
+# Claim story (assign to self + In Progress)
+pf jira claim MSSCI-12345
+
+# Assign to user by email
+pf jira assign MSSCI-12345 keith.avery@1898andco.io
+
+# Assign by GitHub username (auto-mapped)
+pf jira assign MSSCI-12345 slabgorb
+
+# Preview
+pf jira claim MSSCI-12345 --dry-run
+pf jira assign MSSCI-12345 slabgorb --dry-run
+```
+
+## Transitions
+
+```bash
+# Move to In Progress
+pf jira move MSSCI-12345 "In Progress"
+
+# Move to Done
+pf jira move MSSCI-12345 "Done"
+
+# Move to In Review
+pf jira move MSSCI-12345 "In Review"
+
+# Move back to To Do
+pf jira move MSSCI-12345 "To Do"
+
+# Preview
+pf jira move MSSCI-12345 "Done" --dry-run
+```
+
+## Creating Issues
+
+```bash
+# Create epic + all child stories from sprint YAML
+pf jira create epic epic-63
+pf jira create epic 63
+pf jira create epic 63 --dry-run
+
+# Create single story under an epic
+pf jira create story MSSCI-12077 63-7
+pf jira create story MSSCI-12077 63-7 --dry-run
+
+# Create standalone story (create + sprint + Done)
+pf jira create standalone "Fix sprint script shard support"
+pf jira create standalone "Fix sprint script shard support" --points 3
+pf jira create standalone "Add drift detection" -d "Detects YAML drift"
+pf jira create standalone "Quick fix" --dry-run
+```
+
+## Linking Issues
+
+```bash
+# Block relationship
+pf jira link MSSCI-12345 MSSCI-12346 "Blocks"
+
+# Parent-child
+pf jira link MSSCI-12345 MSSCI-12346 "Parent-Child"
+
+# Related (default)
+pf jira link MSSCI-12345 MSSCI-12346
+pf jira link MSSCI-12345 MSSCI-12346 "Relates"
+
+# Duplicate
+pf jira link MSSCI-12345 MSSCI-12346 "Duplicate"
+```
+
+## Syncing
+
+```bash
+# Sync epic to Jira (all fields)
+pf jira sync MSSCI-11952 --all
+
+# Sync only status transitions
+pf jira sync 63 --transition
+
+# Sync only story points
+pf jira sync 63 --points
+
+# Preview
+pf jira sync 63 --all --dry-run
+
+# Bidirectional sync (Jira wins by default)
+pf jira bidirectional --all
+pf jira bidirectional --all --dry-run
+
+# YAML wins on conflicts
+pf jira bidirectional --status --yaml-wins
+
+# Sync specific fields
+pf jira bidirectional --status --points --assignee
+
+# Target specific sprint
+pf jira bidirectional --all --sprint 276
+```
+
+## Reconciliation
+
+```bash
+# Report mismatches
+pf jira reconcile
+
+# Auto-fix (add missing stories to sprint)
+pf jira reconcile --fix
+```
+
+## Sprint Management
+
+```bash
+# Add issue to sprint
+pf jira sprint add 276 MSSCI-11999
+
+# Preview
+pf jira sprint add 276 MSSCI-11999 --dry-run
+```
+
+## Common Workflows
+
+### New story from sprint YAML to Jira
+```bash
+# 1. Add story to sprint YAML
+pf sprint story add 91 "New feature" 3
+
+# 2. Create in Jira under existing epic
+pf jira create story MSSCI-14298 91-5
+
+# 3. Claim it
+pf jira claim MSSCI-15050
+```
+
+### End-of-sprint reconciliation
+```bash
+# 1. Check for mismatches
+pf jira reconcile
+
+# 2. Sync all completed stories
+pf jira bidirectional --all
+
+# 3. Fix any remaining issues
+pf jira reconcile --fix
+```

package/pennyfarthing-dist/skills/pf-jira/usage.md

@@ -0,0 +1,213 @@
+# Jira CLI — Detailed Usage
+
+All commands use `pf jira <command>` as the entry point. REST API is used where possible — no interactive prompt issues.
+
+## Commands
+
+### View Issue
+
+```bash
+pf jira view <KEY>
+```
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `KEY` | Yes | Jira issue key (e.g., `MSSCI-12345`) |
+
+Delegates to `jira issue view`. Shows summary, status, assignee, description, linked issues.
+
+### Check Availability
+
+```bash
+pf jira check <KEY>
+```
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `KEY` | Yes | Jira issue key |
+
+Exit codes: `0` = available, `1` = assigned, `2` = not found, `3` = error.
+
+### Claim Story
+
+```bash
+pf jira claim <KEY> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `KEY` | Yes | Jira issue key |
+| `--dry-run` | No | Preview without making changes |
+
+Assigns to self and moves to In Progress.
+
+### Move Issue
+
+```bash
+pf jira move <KEY> "<STATUS>" [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `KEY` | Yes | Jira issue key |
+| `STATUS` | Yes | Target status: `To Do`, `In Progress`, `In Review`, `Done` |
+| `--dry-run` | No | Preview without making changes |
+
+Checks current status first — skips if already there.
+
+### Assign Issue
+
+```bash
+pf jira assign <KEY> <USER> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `KEY` | Yes | Jira issue key |
+| `USER` | Yes | Email or GitHub username (auto-mapped) |
+| `--dry-run` | No | Preview without making changes |
+
+Checks current assignee — skips if already assigned.
+
+### Link Issues
+
+```bash
+pf jira link <PARENT_KEY> <CHILD_KEY> [LINK_TYPE] [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `PARENT_KEY` | Yes | Inward issue (parent/blocker) |
+| `CHILD_KEY` | Yes | Outward issue (child/blocked) |
+| `LINK_TYPE` | No | `Relates` (default), `Blocks`, `Parent-Child`, `Duplicate` |
+| `--dry-run` | No | Preview without making changes |
+
+### Search Issues
+
+```bash
+pf jira search "<JQL>"
+```
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `JQL` | Yes | JQL query string |
+
+Delegates to `jira issue list --jql`.
+
+### Create Epic
+
+```bash
+pf jira create epic <EPIC_ID> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_ID` | Yes | Epic ID from sprint YAML (e.g., `epic-63` or `63`) |
+| `--dry-run` | No | Preview without creating |
+
+Creates Jira epic and all child stories without existing Jira keys. Updates sprint YAML atomically.
+
+### Create Story
+
+```bash
+pf jira create story <EPIC_JIRA_KEY> <STORY_ID> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC_JIRA_KEY` | Yes | Parent epic Jira key (e.g., `MSSCI-12077`) |
+| `STORY_ID` | Yes | Local story ID (e.g., `63-7`) |
+| `--dry-run` | No | Preview without creating |
+
+Sets priority, points, sprint membership. Updates YAML.
+
+### Create Standalone
+
+```bash
+pf jira create standalone "<TITLE>" [--points N] [-d DESC] [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `TITLE` | Yes | Story summary |
+| `--points` | No | Story points (default: 2) |
+| `-d` / `--description` | No | Story description |
+| `--dry-run` | No | Preview without creating |
+
+Creates story, adds to current sprint, transitions to Done. All via REST API.
+
+### Sync Epic
+
+```bash
+pf jira sync <EPIC> [--transition] [--points] [--all] [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `EPIC` | Yes | Epic ID or Jira key |
+| `--transition` | No | Sync status to Jira |
+| `--points` | No | Sync story points |
+| `--all` | No | Sync all fields (transition + points) |
+| `--dry-run` | No | Preview without applying |
+
+### Bidirectional Sync
+
+```bash
+pf jira bidirectional [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--yaml-wins` | Prefer YAML values on conflict (default: Jira wins) |
+| `--status` | Sync status field |
+| `--points` | Sync story points |
+| `--assignee` | Sync assignee field (Jira to YAML only) |
+| `--all` | Sync all fields |
+| `--sprint <ID>` | Target specific sprint |
+| `--dry-run` | Preview without applying |
+
+### Reconcile
+
+```bash
+pf jira reconcile [--fix]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--fix` | Apply automatic fixes (add missing stories to sprint) |
+
+Reports: status mismatches, missing Jira keys, orphans, sprint membership gaps.
+
+### Sprint Add
+
+```bash
+pf jira sprint add <SPRINT_ID> <ISSUE_KEY> [--dry-run]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `SPRINT_ID` | Yes | Jira sprint ID number |
+| `ISSUE_KEY` | Yes | Jira issue key |
+| `--dry-run` | No | Preview without making changes |
+
+---
+
+## GitHub to Jira User Mapping
+
+| GitHub Username | Jira Email |
+|-----------------|------------|
+| slabgorb | keith.avery@1898andco.io |
+| arcaven | michael.pursifull@1898andco.io |
+| RoseSecurity | michael.rosenfeld@1898andco.io |
+| Zious11 | jared.richards@1898andco.io |
+| drbothen | joshua.magady@1898andco.io |
+
+## Prerequisites
+
+```bash
+brew install ankitpokhrel/jira-cli/jira-cli
+jira init
+export JIRA_API_TOKEN='your-token'
+```
+
+Create token at: https://id.atlassian.com/manage-profile/security/api-tokens