@houseofwolvesllc/claude-scrum-skill 1.5.1 → 1.7.0

package/skills/sprint-plan/SKILL.md

@@ -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

package/skills/sprint-release/SKILL.md

@@ -9,16 +9,128 @@ Close out a sprint: summarize work, handle incomplete stories, open the release
 
 ## Before You Start
 
-1. Read `../project-scaffold/references/CONVENTIONS.md` for project management standards.
-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.
+1. Read `../shared/references/CONVENTIONS.md` for project management standards.
+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.
+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. Sprint data is in local files.
 
 ## 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.
 
-## Release 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 update story status and close sprints — following the same release logic as GitHub mode. PRs are still created via `gh` if the git host is GitHub, otherwise direct git merges (see PROVIDERS.md, PR / Code Review Operations).
+
+**Local mode:** `$ARGUMENTS` is ignored. Sprint data is read from the configured backlog path.
+
+---
+
+## Local Release Procedure
+
+When `scaffolding: "local"`, release sprints by updating local backlog files
+and performing git operations directly (no PRs, no GitHub issues).
+
+### Local Step 1: Sprint Inventory
+
+Find the active sprint and read all its stories:
+
+```bash
+# Find active sprint
+grep -l 'status: active' <backlog-path>/sprints/sprint-*.md
+```
+
+Read each story file referenced in the sprint. Categorize as done,
+in-progress, ready, or blocked based on frontmatter `status`.
+
+Also check git branch state:
+```bash
+git fetch origin
+# Story branches merged into release branch
+git branch -r --merged origin/release/<epic-slug> | grep 'origin/story/'
+# Unmerged story branches
+git branch -r --no-merged origin/release/<epic-slug> | grep 'origin/story/'
+```
+
+### Local Step 2: Handle Incomplete Stories
+
+For stories still open:
+
+1. **In Progress:** Ask the user — merge the story branch now, or roll over?
+2. **Ready (never started):** Update frontmatter: add `rolled-over` to labels,
+   set `sprint: null` (will be picked up by next sprint plan).
+3. **Blocked:** Update frontmatter: set `sprint: null`, keep `blocked` status.
+
+### Local Step 3: Merge Release Branch to Development
+
+In local mode, merge directly instead of opening a PR:
+
+```bash
+# Ensure release branch is up to date
+git checkout release/<epic-slug> && git pull
+
+# Merge to development
+git checkout development && git pull
+git merge release/<epic-slug> --no-ff -m "Release: Sprint <N> — <Epic Name>"
+git push origin development
+```
+
+If merge conflicts exist:
+- Attempt automatic resolution
+- If auto-resolution fails, pause and escalate to the user
+
+### Local Step 4: Clean Up Merged Branches
+
+Same git operations as GitHub mode — delete merged story and release branches.
+
+### Local Step 5: Update Local State
+
+Update the sprint file frontmatter:
+```yaml
+status: completed
+velocity_actual: <points completed>
+```
+
+Update completed story files:
+```yaml
+status: done
+```
+
+If all stories in an epic are done, update `_epic.md`:
+```yaml
+status: closed
+```
+
+### Local Step 6: Generate Release Report
+
+Same format as GitHub mode, but without PR links. Instead report:
+
+```
+## Sprint <N> Release Complete (Local Mode)
+
+**Merge:** release/<epic-slug> → development (direct merge)
+**Commit:** <merge commit SHA>
+
+### Sprint Scorecard
+<same as GitHub mode>
+
+### Epic Progress
+<same as GitHub mode>
+
+### Cleanup
+<same as GitHub mode>
+
+### Next Steps
+1. Review changes on development branch
+2. Run `/sprint-plan` to plan Sprint <N+1>
+3. When ready for production, merge development → main manually
+```
+
+---
+
+## GitHub Release Procedure
 
 ### Step 1: Sprint Inventory
 

package/skills/sprint-status/SKILL.md

@@ -9,16 +9,70 @@ Generate a comprehensive status report for the active sprint.
 
 ## Before You Start
 
-1. Read `../project-scaffold/references/CONVENTIONS.md` for project management standards.
-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.
+1. Read `../shared/references/CONVENTIONS.md` for project management standards.
+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.
+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. Status is read from local files.
 
 ## 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.
 
-## Status Report 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 query story status — following the same reporting logic as GitHub mode.
+
+**Local mode:** `$ARGUMENTS` is ignored. Status is read from the configured backlog path.
+
+---
+
+## Local Status Report Procedure
+
+When `scaffolding: "local"`, generate the status report from local backlog
+files.
+
+### Local Step 1: Gather Data
+
+Find the active sprint:
+
+```bash
+# Find the active sprint file
+grep -l 'status: active' <backlog-path>/sprints/sprint-*.md
+```
+
+Read the active sprint file to get the story list. Then read each referenced
+story file's frontmatter for current status, executor, points, persona,
+and labels.
+
+Also check git state for additional signals:
+```bash
+# Recent commits on release branches
+git log --oneline --since="1 week ago" --all --grep="story/"
+
+# Open local branches (proxy for in-progress work)
+git branch --list 'story/*'
+```
+
+### Local Step 2: Categorize Stories
+
+Same categories as GitHub mode — group stories by their frontmatter
+`status` field: `done`, `in-progress`, `ready`, `blocked`, `needs-context`.
+
+### Local Step 3: Generate Report
+
+Same report format as GitHub mode. Use story file paths instead of issue
+numbers. For "Release Branch Health", check git branch state directly
+instead of via `gh`.
+
+### Local Step 4: Actionable Recommendations
+
+Same as GitHub mode.
+
+---
+
+## GitHub Status Report Procedure
 
 ### Step 1: Gather Data