npm - @houseofwolvesllc/claude-scrum-skill - Versions diffs - 1.5.0 → 1.6.0 - Mend

@houseofwolvesllc/claude-scrum-skill 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +277 -236
package/bin/install.js +31 -0
package/package.json +1 -1
package/skills/project-cleanup/SKILL.md +32 -59
package/skills/project-emulate/SKILL.md +1 -1
package/skills/project-orchestrate/SKILL.md +257 -58
package/skills/project-scaffold/SKILL.md +364 -4
package/skills/project-spec/SKILL.md +60 -0
package/skills/project-spec/templates/spec-template.md +63 -0
package/skills/shared/config.json +14 -0
package/skills/{project-scaffold → shared}/references/CONVENTIONS.md +16 -0
package/skills/shared/references/PERSONAS.md +270 -0
package/skills/shared/references/PROVIDERS.md +471 -0
package/skills/sprint-plan/SKILL.md +124 -6
package/skills/sprint-release/SKILL.md +118 -6
package/skills/sprint-status/SKILL.md +60 -6

package/skills/shared/references/PROVIDERS.md ADDED Viewed

@@ -0,0 +1,471 @@
+# Provider API Reference
+This document maps project management operations to provider-specific API
+calls. Skills reference this file when operating in remote mode (GitHub, Jira,
+or Trello).
+## Authentication
+### GitHub
+Requires `gh` CLI authenticated via `gh auth login`.
+No environment variables needed — `gh` manages credentials internally.
+### Jira
+Requires three environment variables:
+| Variable | Description | Example |
+|---|---|---|
+| `JIRA_SITE` | Atlassian site URL (no trailing slash) | `https://yourcompany.atlassian.net` |
+| `JIRA_EMAIL` | Atlassian account email | `user@example.com` |
+| `JIRA_API_TOKEN` | API token from id.atlassian.com | `ATATT3x...` |
+Generate a token at: Settings > Atlassian Account > Security > API Tokens
+All requests use Basic auth:
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$JIRA_SITE/rest/api/3/..."
+```
+### Trello
+Requires two environment variables:
+| Variable | Description | Example |
+|---|---|---|
+| `TRELLO_API_KEY` | API key from trello.com/power-ups/admin | `a1b2c3d4...` |
+| `TRELLO_TOKEN` | Auth token (generated via authorize URL) | `e5f6g7h8...` |
+All requests pass credentials as query parameters:
+```bash
+curl -s "https://api.trello.com/1/...?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN"
+```
+---
+## Auth Verification
+| Operation | GitHub | Jira | Trello |
+|---|---|---|---|
+| Check auth | `gh auth status` | `curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_SITE/rest/api/3/myself"` | `curl -s "https://api.trello.com/1/members/me?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN"` |
+---
+## Epic Operations
+Epics map to different concepts per provider:
+| Concept | GitHub | Jira | Trello |
+|---|---|---|---|
+| Epic container | Milestone | Epic issue type (or Version) | List |
+### Create Epic
+**GitHub:**
+```bash
+gh api repos/<owner/repo>/milestones \
+  -f title="<Epic Name>" \
+  -f description="<description>" \
+  -f state="open"
+```
+**Jira:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -X POST "$JIRA_SITE/rest/api/3/issue" \
+  -d '{
+    "fields": {
+      "project": {"key": "<PROJECT_KEY>"},
+      "summary": "<Epic Name>",
+      "description": {"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"<description>"}]}]},
+      "issuetype": {"name": "Epic"}
+    }
+  }'
+```
+**Trello:**
+```bash
+curl -s -X POST "https://api.trello.com/1/lists?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "name=<Epic Name>&idBoard=<board-id>&pos=bottom"
+```
+### List Open Epics
+**GitHub:**
+```bash
+gh api repos/<owner/repo>/milestones \
+  --jq '.[] | select(.state=="open") | {number, title, open_issues, closed_issues}'
+```
+**Jira:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  "$JIRA_SITE/rest/api/3/search?jql=project=<KEY>+AND+issuetype=Epic+AND+status!=Done&fields=summary,status"
+```
+**Trello:**
+```bash
+curl -s "https://api.trello.com/1/boards/<board-id>/lists?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&filter=open"
+```
+### Close Epic
+**GitHub:**
+```bash
+gh api repos/<owner/repo>/milestones/<number> -X PATCH -f state="closed"
+```
+**Jira:**
+```bash
+# Transition the epic to Done (get transition ID first)
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -X POST "$JIRA_SITE/rest/api/3/issue/<epic-key>/transitions" \
+  -H "Content-Type: application/json" \
+  -d '{"transition":{"id":"<done-transition-id>"}}'
+```
+**Trello:**
+```bash
+curl -s -X PUT "https://api.trello.com/1/lists/<list-id>/closed?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&value=true"
+```
+---
+## Story/Issue Operations
+| Concept | GitHub | Jira | Trello |
+|---|---|---|---|
+| Story | Issue | Issue (Story type) | Card |
+### Create Story
+**GitHub:**
+```bash
+gh issue create --repo <owner/repo> \
+  --title "<title>" \
+  --body "<body>" \
+  --label "type:story,executor:<type>,<priority>,epic:<slug>" \
+  --milestone "<Epic Name>"
+```
+**Jira:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -X POST "$JIRA_SITE/rest/api/3/issue" \
+  -d '{
+    "fields": {
+      "project": {"key": "<PROJECT_KEY>"},
+      "summary": "<title>",
+      "description": {"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"<body>"}]}]},
+      "issuetype": {"name": "Story"},
+      "labels": ["executor:<type>", "<priority>"],
+      "customfield_<epic-link>": "<epic-key>"
+    }
+  }'
+```
+Note: The epic link custom field ID varies per Jira instance. Discover it via:
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" "$JIRA_SITE/rest/api/3/field" | jq '.[] | select(.name=="Epic Link")'
+```
+**Trello:**
+```bash
+curl -s -X POST "https://api.trello.com/1/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "name=<title>&desc=<body>&idList=<list-id>&idLabels=<label-ids>"
+```
+### List Stories
+**GitHub:**
+```bash
+gh issue list --repo <owner/repo> --state open --label "type:story" \
+  --json number,title,labels,milestone
+```
+**Jira:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  "$JIRA_SITE/rest/api/3/search?jql=project=<KEY>+AND+issuetype=Story+AND+status!=Done&fields=summary,status,labels,priority,customfield_<points>"
+```
+**Trello:**
+```bash
+curl -s "https://api.trello.com/1/lists/<list-id>/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&fields=name,desc,labels,idMembers"
+```
+### Update Story Status
+**GitHub:**
+```bash
+# Close
+gh issue close <number> --repo <owner/repo>
+# Reopen
+gh issue reopen <number> --repo <owner/repo>
+```
+**Jira:**
+```bash
+# Get available transitions
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  "$JIRA_SITE/rest/api/3/issue/<issue-key>/transitions"
+# Apply transition
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -X POST "$JIRA_SITE/rest/api/3/issue/<issue-key>/transitions" \
+  -H "Content-Type: application/json" \
+  -d '{"transition":{"id":"<transition-id>"}}'
+```
+**Trello:**
+```bash
+# Move card to a different list (e.g., Done list)
+curl -s -X PUT "https://api.trello.com/1/cards/<card-id>?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "idList=<done-list-id>"
+```
+### Add/Remove Labels
+**GitHub:**
+```bash
+gh issue edit <number> --repo <owner/repo> --add-label "<label>"
+gh issue edit <number> --repo <owner/repo> --remove-label "<label>"
+```
+**Jira:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -X PUT "$JIRA_SITE/rest/api/3/issue/<issue-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"update":{"labels":[{"add":"<label>"}]}}'
+```
+**Trello:**
+```bash
+# Add label
+curl -s -X POST "https://api.trello.com/1/cards/<card-id>/idLabels?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&value=<label-id>"
+# Remove label
+curl -s -X DELETE "https://api.trello.com/1/cards/<card-id>/idLabels/<label-id>?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN"
+```
+### Read Story Details
+**GitHub:**
+```bash
+gh issue view <number> --repo <owner/repo> --json number,title,body,labels,milestone,state
+```
+**Jira:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  "$JIRA_SITE/rest/api/3/issue/<issue-key>?fields=summary,description,status,labels,priority"
+```
+**Trello:**
+```bash
+curl -s "https://api.trello.com/1/cards/<card-id>?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&fields=name,desc,labels,idList,closed"
+```
+---
+## Label Operations
+### Create Label
+**GitHub:**
+```bash
+gh label create "<name>" --color "<hex>" --description "<desc>" --repo <owner/repo>
+```
+**Jira:**
+```bash
+# Jira labels are created implicitly when applied to an issue.
+# No separate create call needed.
+```
+**Trello:**
+```bash
+curl -s -X POST "https://api.trello.com/1/boards/<board-id>/labels?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "name=<name>&color=<color>"
+```
+Note: Trello has a fixed set of label colors: `green`, `yellow`, `orange`,
+`red`, `purple`, `blue`, `sky`, `lime`, `pink`, `black`, `null` (no color).
+---
+## Sprint Operations
+| Concept | GitHub | Jira | Trello |
+|---|---|---|---|
+| Sprint | Iteration field on Project | Sprint (Scrum board) | Convention: use lists named "Sprint N" |
+### Create/Start Sprint
+**GitHub:**
+```bash
+# Create via GraphQL — add an iteration to the Sprint field
+gh api graphql -f query='mutation { ... }'
+```
+**Jira:**
+```bash
+# Get board ID
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  "$JIRA_SITE/rest/agile/1.0/board?projectKeyOrId=<KEY>"
+# Create sprint
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -X POST "$JIRA_SITE/rest/agile/1.0/sprint" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Sprint <N>",
+    "startDate": "<ISO date>",
+    "endDate": "<ISO date>",
+    "originBoardId": <board-id>,
+    "goal": "<sprint goal>"
+  }'
+```
+**Trello:**
+```bash
+# Create a "Sprint N" list at the top of the board
+curl -s -X POST "https://api.trello.com/1/lists?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "name=Sprint <N>&idBoard=<board-id>&pos=top"
+```
+### Assign Story to Sprint
+**GitHub:**
+```bash
+# Update the Sprint iteration field via GraphQL
+gh api graphql -f query='mutation { updateProjectV2ItemFieldValue(...) }'
+```
+**Jira:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -X POST "$JIRA_SITE/rest/agile/1.0/sprint/<sprint-id>/issue" \
+  -H "Content-Type: application/json" \
+  -d '{"issues":["<issue-key>"]}'
+```
+**Trello:**
+```bash
+# Move card to the sprint list
+curl -s -X PUT "https://api.trello.com/1/cards/<card-id>?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "idList=<sprint-list-id>"
+```
+### Complete Sprint
+**GitHub:**
+```bash
+# No explicit close — the iteration just ends by date
+```
+**Jira:**
+```bash
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -X POST "$JIRA_SITE/rest/agile/1.0/sprint/<sprint-id>" \
+  -H "Content-Type: application/json" \
+  -d '{"state":"closed"}'
+```
+**Trello:**
+```bash
+# Archive the sprint list
+curl -s -X PUT "https://api.trello.com/1/lists/<sprint-list-id>/closed?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&value=true"
+```
+---
+## Project/Board Operations
+### Create Project/Board
+**GitHub:**
+```bash
+gh project create --owner <owner> --title "<name>"
+```
+**Jira:**
+```bash
+# Get the current user's account ID
+ACCOUNT_ID=$(curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  "$JIRA_SITE/rest/api/3/myself" | jq -r '.accountId')
+# Create a Scrum software project (preferred template)
+curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
+  -X POST "$JIRA_SITE/rest/api/3/project" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "key": "<PROJECT_KEY>",
+    "name": "<name>",
+    "projectTypeKey": "software",
+    "projectTemplateKey": "com.pyxis.greenhopper.jira:gh-scrum-template",
+    "leadAccountId": "'$ACCOUNT_ID'"
+  }'
+```
+The Scrum template auto-creates a Scrum board with backlog and sprint support.
+Save the project key to `config.json` after creation.
+**Trello:**
+```bash
+# Create board with no default lists (skill creates its own)
+curl -s -X POST "https://api.trello.com/1/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "name=<name>&defaultLists=false"
+```
+Save the board ID from the response to `config.json` after creation.
+---
+## PR / Code Review Operations
+These are git-host-specific. Jira and Trello do not have native PR
+functionality — PRs live in the git host (GitHub, Bitbucket, GitLab).
+When using Jira or Trello as the project tracker with GitHub as the git host,
+PR operations still use `gh`:
+```bash
+gh pr create --repo <owner/repo> --base <base> --head <head> --title "<title>" --body "<body>"
+gh pr merge <number> --repo <owner/repo> --squash
+```
+If not using GitHub for git hosting, replace with direct git merges (same as
+local mode):
+```bash
+git checkout <base> && git merge <head> --no-ff -m "<message>"
+git push origin <base>
+```
+---
+## Provider Limitations
+### Jira
+- Epic link custom field ID varies per instance — must be discovered at runtime
+- Transitions (status changes) require knowing the transition ID — query available transitions first
+- Jira Cloud rate limits: 100 requests/minute for most endpoints
+- Description uses Atlassian Document Format (ADF), not plain markdown
+### Trello
+- No native sprint concept — sprints are modeled as lists
+- No native story points — requires custom fields power-up
+- Limited label colors (10 fixed options)
+- No native issue dependencies — use checklist items or card links
+- Cards don't have a "closed with resolution" concept — archived or moved to Done list
+- Rate limit: 100 requests per 10 seconds per token
+### GitHub
+- Project iteration fields require GraphQL for mutation
+- Rate limit: 5000 requests/hour for authenticated requests
+- Fine-grained PATs require explicit repo and permission scoping

package/skills/sprint-plan/SKILL.md CHANGED Viewed

@@ -9,16 +9,112 @@ Plan and populate the next sprint iteration for an existing GitHub Project.
 ## Before You Start
-1. Read `../project-scaffold/references/CONVENTIONS.md` for all project management standards. Follow these conventions exactly.
-2. **Terminology:** Always refer to milestones as **"epics"** in all user-facing text, summaries, and conversational output. The word "milestone" should only appear in GitHub API commands and code — never in communication with the user.
-3. Confirm the `gh` CLI is authenticated by running `gh auth status`.
+1. Read `../shared/references/CONVENTIONS.md` for all project management standards. Follow these conventions exactly.
+2. Read `../shared/config.json` to determine the scaffolding mode (`scaffolding` key: `"local"`, `"github"`, `"jira"`, or `"trello"`, default: `"local"`). If `"local"`, also read the `paths.backlog` value (default: `.claude-scrum-skill/backlog`).
+3. Read `../shared/references/PROVIDERS.md` for provider-specific API commands when operating in remote mode.
+4. **Terminology:** Always refer to milestones as **"epics"** in all user-facing text, summaries, and conversational output. The word "milestone" should only appear in API commands and code — never in communication with the user.
+5. **If `scaffolding: "github"`:** Confirm the `gh` CLI is authenticated by running `gh auth status`.
+6. **If `scaffolding: "jira"`:** Verify `JIRA_SITE`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` env vars are set.
+7. **If `scaffolding: "trello"`:** Verify `TRELLO_API_KEY` and `TRELLO_TOKEN` env vars are set.
+8. **If `scaffolding: "local"`:** Skip authentication. The backlog is file-based.
 ## Input
-`$ARGUMENTS` should be the repo identifier and optionally the project number.
-If not provided, detect from the current git remote or ask the user.
+**GitHub mode:** `$ARGUMENTS` should be the repo identifier and optionally the project number. If not provided, detect from the current git remote or ask the user.
-## Planning Procedure
+**Jira/Trello mode:** `$ARGUMENTS` is ignored. Project key or board ID is read from config.json. Use the provider-specific API commands from PROVIDERS.md to list stories, create sprints, and assign stories — following the same planning logic as GitHub mode.
+**Local mode:** `$ARGUMENTS` is ignored. Stories are read from the configured backlog path.
+---
+## Local Planning Procedure
+When `scaffolding: "local"`, plan sprints by reading and updating local
+backlog files.
+### Local Step 1: Assess Current State
+Read the backlog directory structure:
+```bash
+# List all epics
+ls <backlog-path>/*/_ epic.md
+# Read PROJECT.md for sprint history
+cat <backlog-path>/PROJECT.md
+```
+For each epic directory, read `_epic.md` (status) and all story files
+(frontmatter). Gather:
+- Stories by status (`backlog`, `ready`, `in-progress`, `done`)
+- Any stories with `rolled-over` in their labels
+- Dependency chains from `blocked_by` fields
+### Local Step 2: Calculate Capacity
+Same as GitHub mode — ask the user or use defaults (20 points/sprint).
+### Local Step 3: Select Stories for Sprint
+Same priority order as GitHub mode (rolled-over → unblocked → P0 → P1 → P2 →
+dependencies-first). Read story points and priorities from frontmatter.
+Present the proposed sprint to the user for confirmation.
+### Persona Assignment
+Same as GitHub mode — check for `persona` field in story frontmatter. If
+missing, apply defaults based on labels:
+| Story labels | Default persona |
+|---|---|
+| `scope:infra`, `scope:ci`, `scope:deploy`, `scope:migration` | `ops` |
+| `needs:design`, `needs:spike` | `research` |
+| All other stories | `impl` (no change needed) |
+Update the story file's frontmatter `persona` field.
+### Local Step 4: Assign Sprint
+Create a sprint file at `<backlog-path>/sprints/sprint-<N>.md`:
+```markdown
+---
+number: <N>
+status: active
+start: <ISO date>
+end: <ISO date>
+velocity_target: <points>
+velocity_actual: null
+---
+# Sprint <N>
+## Stories
+| File | Title | Executor | Persona | Points | Priority | Status |
+|------|-------|----------|---------|--------|----------|--------|
+| core-api/001-user-auth.md | User auth endpoint | claude | impl | 5 | P1-high | ready |
+...
+```
+Update each selected story's frontmatter:
+- Set `sprint: <N>`
+- Set `status: ready` (or `backlog` if dependencies aren't met)
+### Local Step 5: Ensure Branch Exists
+Same as GitHub mode — create release branches from `development` for each
+active epic. Git operations work identically in local mode.
+### Local Step 6: Generate Sprint Kickoff Summary
+Same format as GitHub mode, but reference story file paths instead of issue
+numbers.
+---
+## GitHub Planning Procedure
 ### Step 1: Assess Current State
@@ -97,6 +193,28 @@ For each story in the sprint:
 - Set Status to "Ready" (or "Backlog" if dependencies aren't met yet)
 - Verify labels are correct
+### Persona Assignment
+For each story assigned to the sprint, check for an existing `persona:*`
+label. If none exists, apply a default based on the story's other labels:
+| Story labels | Default persona |
+|---|---|
+| `scope:infra`, `scope:ci`, `scope:deploy`, `scope:migration` | `persona:ops` |
+| `needs:design`, `needs:spike` | `persona:research` |
+| All other stories | No label needed (implicit `impl`) |
+Apply the label:
+```bash
+# Only if the story doesn't already have a persona:* label
+gh issue edit <number> --repo <owner/repo> --add-label "persona:ops"
+```
+This is a default heuristic. Users can override by manually labeling stories
+before planning. The orchestrator reads whatever label is present at
+execution time.
 ### Step 5: Ensure Branch Exists
 ```bash