From bea46d7689905a270a4e92b730c4a34e3a502a53 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Mon, 2 Feb 2026 13:48:13 -0500 Subject: [PATCH] feat(projman): add sprint lifecycle state machine via milestone metadata - New skill: sprint-lifecycle.md defines states, transitions, and check protocol - All sprint commands now check and set lifecycle state - States tracked in milestone description metadata (Sprint/Planning, Sprint/Executing, Sprint/Reviewing) - Out-of-order calls produce warnings with guidance - --force override available for all lifecycle checks - Added Sprint/* labels to label taxonomy documentation Co-Authored-By: Claude Opus 4.5 --- .doc-guardian-queue | 8 ++ plugins/projman/agents/code-reviewer.md | 1 + plugins/projman/agents/orchestrator.md | 1 + plugins/projman/agents/planner.md | 1 + plugins/projman/commands/review.md | 2 + plugins/projman/commands/sprint-close.md | 2 + plugins/projman/commands/sprint-plan.md | 2 + plugins/projman/commands/sprint-start.md | 3 +- plugins/projman/commands/sprint-status.md | 2 + .../skills/label-taxonomy/labels-reference.md | 12 ++ plugins/projman/skills/sprint-lifecycle.md | 104 ++++++++++++++++++ 11 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 plugins/projman/skills/sprint-lifecycle.md diff --git a/.doc-guardian-queue b/.doc-guardian-queue index aa22cfb..9c60170 100644 --- a/.doc-guardian-queue +++ b/.doc-guardian-queue @@ -7,3 +7,11 @@ 2026-02-02T13:39:15 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/setup.md | docs/COMMANDS-CHEATSHEET.md README.md 2026-02-02T13:39:32 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/rfc-workflow.md | README.md 2026-02-02T13:43:14 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/rfc-templates.md | README.md +2026-02-02T13:44:55 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/sprint-lifecycle.md | README.md +2026-02-02T13:45:04 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/label-taxonomy/labels-reference.md | README.md +2026-02-02T13:45:14 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-plan.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:45:48 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/review.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:46:07 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-close.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:46:21 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-status.md | docs/COMMANDS-CHEATSHEET.md README.md +2026-02-02T13:46:38 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/planner.md | README.md CLAUDE.md +2026-02-02T13:46:57 | agents | /home/lmiranda/claude-plugins-work/plugins/projman/agents/code-reviewer.md | README.md CLAUDE.md diff --git a/plugins/projman/agents/code-reviewer.md b/plugins/projman/agents/code-reviewer.md index d5fc1f0..fb51198 100644 --- a/plugins/projman/agents/code-reviewer.md +++ b/plugins/projman/agents/code-reviewer.md @@ -11,6 +11,7 @@ You are the **Code Reviewer Agent** - a thorough, practical reviewer who ensures - skills/review-checklist.md - skills/test-standards.md +- skills/sprint-lifecycle.md ## Your Personality diff --git a/plugins/projman/agents/orchestrator.md b/plugins/projman/agents/orchestrator.md index dfd647e..df21732 100644 --- a/plugins/projman/agents/orchestrator.md +++ b/plugins/projman/agents/orchestrator.md @@ -19,6 +19,7 @@ You are the **Orchestrator Agent** - a concise, action-oriented coordinator who - skills/runaway-detection.md - skills/wiki-conventions.md - skills/domain-consultation.md +- skills/sprint-lifecycle.md ## Your Personality diff --git a/plugins/projman/agents/planner.md b/plugins/projman/agents/planner.md index 7224a6c..185a0e8 100644 --- a/plugins/projman/agents/planner.md +++ b/plugins/projman/agents/planner.md @@ -21,6 +21,7 @@ You are the **Planner Agent** - a methodical architect who thoroughly analyzes r - skills/planning-workflow.md - skills/label-taxonomy/labels-reference.md - skills/domain-consultation.md +- skills/sprint-lifecycle.md ## Your Personality diff --git a/plugins/projman/commands/review.md b/plugins/projman/commands/review.md index 11102b8..fac445c 100644 --- a/plugins/projman/commands/review.md +++ b/plugins/projman/commands/review.md @@ -8,6 +8,7 @@ agent: code-reviewer ## Skills Required - skills/review-checklist.md +- skills/sprint-lifecycle.md ## Purpose @@ -19,6 +20,7 @@ Run `/review` before `/sprint-close` to catch issues. ## Workflow +0. **Check Lifecycle State** - Execute `skills/sprint-lifecycle.md` check protocol. Expect `Sprint/Executing`. Set `Sprint/Reviewing` after review begins. Warn if in wrong state (allow with `--force`). 1. **Determine Scope** - Sprint files or recent commits (`git diff --name-only HEAD~5`) 2. **Read Files** - Use Read tool for each file in scope 3. **Scan for Patterns** - Check each category from review checklist diff --git a/plugins/projman/commands/sprint-close.md b/plugins/projman/commands/sprint-close.md index dbb25c7..b8d4f30 100644 --- a/plugins/projman/commands/sprint-close.md +++ b/plugins/projman/commands/sprint-close.md @@ -13,6 +13,7 @@ agent: orchestrator - skills/rfc-workflow.md - skills/progress-tracking.md - skills/git-workflow.md +- skills/sprint-lifecycle.md ## Purpose @@ -26,6 +27,7 @@ Run `/sprint-close` when sprint work is complete. Execute the sprint close workflow: +0. **Check Lifecycle State** - Execute `skills/sprint-lifecycle.md` check protocol. Expect `Sprint/Reviewing`. Clear all Sprint/* labels (return to idle) at the END of close workflow, after all other steps. Warn if in wrong state (allow with `--force`). 1. **Review Sprint Completion** - Verify issues closed or moved to backlog 2. **Capture Lessons Learned** - Interview user about challenges and insights 3. **Tag for Discoverability** - Apply technology, component, and pattern tags diff --git a/plugins/projman/commands/sprint-plan.md b/plugins/projman/commands/sprint-plan.md index 9bda12d..31e1ffd 100644 --- a/plugins/projman/commands/sprint-plan.md +++ b/plugins/projman/commands/sprint-plan.md @@ -18,6 +18,7 @@ agent: planner - skills/sprint-approval.md - skills/planning-workflow.md - skills/label-taxonomy/labels-reference.md +- skills/sprint-lifecycle.md ## Purpose @@ -35,6 +36,7 @@ Provide sprint goals as natural language input, or prepare input via: Execute the planning workflow as defined in `skills/planning-workflow.md`. **Key steps:** +0. **Check Lifecycle State** - Execute `skills/sprint-lifecycle.md` check protocol. Expect idle state. Set `Sprint/Planning` after planning completes. Warn and stop if sprint is in another active state (unless `--force`). 1. Run pre-planning validations (branch, repo org, labels) 2. Detect input source (file, wiki, or conversation) 3. Search relevant lessons learned diff --git a/plugins/projman/commands/sprint-start.md b/plugins/projman/commands/sprint-start.md index a7cddc0..6af22ac 100644 --- a/plugins/projman/commands/sprint-start.md +++ b/plugins/projman/commands/sprint-start.md @@ -15,6 +15,7 @@ agent: orchestrator - skills/git-workflow.md - skills/progress-tracking.md - skills/runaway-detection.md +- skills/sprint-lifecycle.md ## Purpose @@ -31,7 +32,7 @@ Run `/sprint-start` when ready to begin executing a planned sprint. Execute the sprint start workflow: -1. **Verify Sprint Approval** (required) - Check milestone for approval record. STOP if missing unless `--force` flag provided. +1. **Verify Sprint Approval & Lifecycle State** (required) - Check milestone for approval record. STOP if missing unless `--force` flag provided. Also verify lifecycle state is `Sprint/Planning` per `skills/sprint-lifecycle.md`. Set `Sprint/Executing` after verification passes. 2. **Detect Checkpoints** - Check for resume points from interrupted sessions 3. **Fetch Sprint Issues** - Get open issues from milestone 4. **Analyze Dependencies** - Use `get_execution_order` for parallel batches diff --git a/plugins/projman/commands/sprint-status.md b/plugins/projman/commands/sprint-status.md index c409eb9..e55525e 100644 --- a/plugins/projman/commands/sprint-status.md +++ b/plugins/projman/commands/sprint-status.md @@ -9,6 +9,7 @@ description: Check current sprint progress, identify blockers, optionally genera - skills/mcp-tools-reference.md - skills/progress-tracking.md - skills/dependency-management.md +- skills/sprint-lifecycle.md ## Purpose @@ -23,6 +24,7 @@ Check current sprint progress, identify blockers, and show execution status. Opt ## Workflow +0. **Display Lifecycle State** - Read current Sprint/* state from milestone description per `skills/sprint-lifecycle.md` and display in output header. 1. **Fetch Sprint Issues** - Get all issues for current milestone 2. **Calculate Progress** - Count completed vs total issues 3. **Identify Active Tasks** - Find issues with `Status/In-Progress` diff --git a/plugins/projman/skills/label-taxonomy/labels-reference.md b/plugins/projman/skills/label-taxonomy/labels-reference.md index 0c73786..2dbdb4e 100644 --- a/plugins/projman/skills/label-taxonomy/labels-reference.md +++ b/plugins/projman/skills/label-taxonomy/labels-reference.md @@ -90,6 +90,18 @@ Repository-level labels are specific to each project. - `Tech/Vue` (#42b883) - Vue.js frontend framework - `Tech/FastAPI` (#009688) - FastAPI backend framework +### Sprint Lifecycle (Milestone Metadata) + +These are tracked as milestone description metadata, not as Gitea issue labels. They are documented here for completeness. + +| Label | Description | +|-------|-------------| +| `Sprint/Planning` | Sprint planning in progress | +| `Sprint/Executing` | Sprint execution in progress | +| `Sprint/Reviewing` | Code review in progress | + +**Note:** Lifecycle state is stored in milestone description as `**Sprint State:** Sprint/Executing`. See `skills/sprint-lifecycle.md` for state machine rules. + ### Domain (2 labels) Cross-plugin integration labels for domain-specific validation gates. diff --git a/plugins/projman/skills/sprint-lifecycle.md b/plugins/projman/skills/sprint-lifecycle.md new file mode 100644 index 0000000..f36f082 --- /dev/null +++ b/plugins/projman/skills/sprint-lifecycle.md @@ -0,0 +1,104 @@ +--- +name: sprint-lifecycle +description: Sprint lifecycle state machine using milestone labels +--- + +# Sprint Lifecycle + +## Purpose + +Defines the valid sprint lifecycle states and transitions, enforced via labels on the sprint milestone. Each projman command checks the current state before executing and updates it on completion. + +## When to Use + +- **All sprint commands**: Check state on entry, update on exit +- **Sprint status**: Display current lifecycle state + +--- + +## State Machine + +``` +idle -> Sprint/Planning -> Sprint/Executing -> Sprint/Reviewing -> idle + (sprint-plan) (sprint-start) (review) (sprint-close) +``` + +## State Labels + +| Label | Set By | Meaning | +|-------|--------|---------| +| *(no Sprint/* label)* | `/sprint-close` or initial state | Idle - no active sprint phase | +| `Sprint/Planning` | `/sprint-plan` | Planning in progress | +| `Sprint/Executing` | `/sprint-start` | Execution in progress | +| `Sprint/Reviewing` | `/review` | Code review in progress | + +**Rule:** Only ONE `Sprint/*` label may exist on a milestone at a time. Setting a new one removes the previous one. + +--- + +## State Transition Rules + +| Command | Expected State | Sets State | On Wrong State | +|---------|---------------|------------|----------------| +| `/sprint-plan` | idle (no Sprint/* label) | `Sprint/Planning` | Warn: "Sprint is in [state]. Run `/sprint-close` first or use `--force` to re-plan." Allow with `--force`. | +| `/sprint-start` | `Sprint/Planning` | `Sprint/Executing` | Warn: "Expected Sprint/Planning state but found [state]. Run `/sprint-plan` first or use `--force`." Allow with `--force`. | +| `/review` | `Sprint/Executing` | `Sprint/Reviewing` | Warn: "Expected Sprint/Executing state but found [state]." Allow with `--force`. | +| `/sprint-close` | `Sprint/Reviewing` | Remove all Sprint/* labels (idle) | Warn: "Expected Sprint/Reviewing state but found [state]. Run `/review` first or use `--force`." Allow with `--force`. | +| `/sprint-status` | Any | No change (read-only) | Display current state in output. | + +--- + +## Checking State (Protocol) + +At command entry, before any other work: + +1. Fetch the active milestone using `get_milestone` +2. Check milestone description for `**Sprint State:**` line +3. Compare against expected state for this command +4. If mismatch: display warning with guidance, STOP unless `--force` provided +5. If match: proceed and update state after command completes its primary work + +**Implementation:** Use milestone description metadata. Add/update a line: +``` +**Sprint State:** Sprint/Executing +``` + +This avoids needing actual Gitea labels on milestones (which may not be supported). Parse this line to check state, update it to set state. + +--- + +## Setting State + +After command completes successfully: + +1. Fetch current milestone description +2. If `**Sprint State:**` line exists, replace it +3. If not, append it to the end of the description +4. Update milestone via `update_milestone` + +**Format:** `**Sprint State:** ` where state is one of: +- `Sprint/Planning` +- `Sprint/Executing` +- `Sprint/Reviewing` +- (empty/removed for idle) + +--- + +## Displaying State + +In `/sprint-status` output, include: + +``` +Sprint Phase: Executing (since 2026-02-01) +``` + +Parse the milestone description for the `**Sprint State:**` line and display it prominently. + +--- + +## Edge Cases + +- **No active milestone**: State is implicitly `idle` +- **Multiple milestones**: Use the open/active milestone. If multiple open, use the most recent. +- **Milestone has no state line**: Treat as `idle` +- **`--force` used**: Log to milestone: "Warning: Lifecycle state override: [command] forced from [actual] state on [date]"