.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

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
 

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
 

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
 

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

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

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

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

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`

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.

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:** <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]"