From c2a3a251b4ee4ba7b67bc603e31d6cfec0b709ab Mon Sep 17 00:00:00 2001
From: Jeroen Schweitzer <jpmschweitzer@gmail.com>
Date: Wed, 18 Feb 2026 12:15:56 +0100
Subject: [PATCH] feat(skills): start-sprint main workflow as state machine
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On main, the skill now assesses sprint state and does the next right
thing: close active sprint (Case A), activate planned sprint (Case B),
or suggest /plan-sprint (Case C). Cases chain automatically — closing
flows into activation if a planned sprint is waiting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .claude/skills/start-sprint/SKILL.md | 84 +++++++++++++++++++++-------
 1 file changed, 64 insertions(+), 20 deletions(-)

diff --git a/.claude/skills/start-sprint/SKILL.md b/.claude/skills/start-sprint/SKILL.md
index e0be94911..cf8a92d00 100644
--- a/.claude/skills/start-sprint/SKILL.md
+++ b/.claude/skills/start-sprint/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: start-sprint
 description: >
-  Start sprint work on a team branch, or close a sprint from main. Use when
-  the user says "start sprint", "start working on the server/client/copy",
-  "begin sprint", or invokes /start-sprint. On a team branch: merges main,
-  finds the active sprint, reads the briefing, presents the work plan. On
-  main: closes the active sprint, bumps the version (v0.1.N), updates the
-  changelog, tags, and pushes.
+  Manage the sprint lifecycle from main, or start sprint work on a team
+  branch. Use when the user says "start sprint", "start working on the
+  server/client/copy", "begin sprint", or invokes /start-sprint. On main:
+  assesses sprint state and does the next right thing (close, activate, or
+  guide). On a team branch: merges main, loads the briefing, presents the
+  work plan.
 user-invocable: true
 allowed-tools: Bash, Read, Grep, Glob, TeamCreate, Task, TaskCreate, TaskUpdate, TaskList, SendMessage, AskUserQuestion
 ---
@@ -32,12 +32,22 @@ the team branch workflow (steps 2–8).
 
 ---
 
-## Main branch workflow (sprint close + version bump)
+## Main branch workflow (sprint lifecycle management)
 
-When `/start-sprint` is run on `main`, it means the user wants to close
-the current sprint, cut a version, and prepare for the next one.
+When `/start-sprint` is run on `main`, assess the current sprint state
+and do the next right thing. Query the database to determine the state:
 
-### M1. Close the active sprint
+```bash
+db/connectors/sqlite-query "SELECT id, name, status FROM sprints ORDER BY id DESC LIMIT 3"
+```
+
+Then follow the **first matching case**:
+
+### Case A: An active sprint exists
+
+The active sprint needs to be closed before moving on.
+
+#### A1. Close the active sprint
 
 ```bash
 db/connectors/sprint stop
@@ -46,7 +56,7 @@ db/connectors/sprint stop
 This marks the active sprint as completed and lists carry-over candidates.
 Note the sprint number (N) from the output.
 
-### M2. Bump the version
+#### A2. Bump the version
 
 The project version scheme is `v0.1.{sprint_number}`. After closing
 sprint N, the version is `v0.1.N`.
@@ -64,32 +74,66 @@ Update `CHANGELOG.md`:
 - Keep the existing sub-headings (Added, Fixed, Changed, Removed) —
   only move entries that have content.
 
-### M3. Commit the release
+#### A3. Commit the release
 
 Stage and commit `project.yaml`, `server/Cargo.toml`, and `CHANGELOG.md`:
 ```
 chore(meta): release v0.1.N
 ```
 
-### M4. Tag the release
+#### A4. Tag the release
 
 ```bash
 git tag v0.1.N
 ```
 
-### M5. Push
+#### A5. Push
 
 ```bash
 git push && git push --tags
 ```
 
-### M6. Report
+#### A6. Check for a planned sprint
 
-Output a summary:
-- Sprint closed (name, done/total tickets, carry-over count)
-- Version tagged (`v0.1.N`)
-- Carry-over candidates (if any)
-- Suggest running `/plan-sprint` next to prepare the next sprint
+After closing, re-query the database. If a sprint in `planning` status
+exists, continue to **Case B**. Otherwise, report the close and suggest
+running `/plan-sprint`.
+
+---
+
+### Case B: No active sprint, but a planned sprint exists
+
+A sprint is ready to activate. Verify it looks complete:
+
+1. Check that briefing files exist at `docs/sprints/sprint-N/`:
+   ```bash
+   ls docs/sprints/sprint-N/
+   ```
+2. Check the ticket count:
+   ```bash
+   db/connectors/sprint status --sprint N
+   ```
+
+If briefings are missing or the sprint has 0 tickets, report the gap
+and suggest running `/plan-sprint` to complete planning.
+
+If everything looks ready, activate the sprint:
+
+```bash
+db/connectors/sprint start
+```
+
+Then report:
+- Sprint activated (name, ticket count per team)
+- Remind the user to switch to a team branch and run `/start-sprint`
+  there (or `cd` into the relevant worktree)
+
+---
+
+### Case C: No active sprint and no planned sprint
+
+Nothing is ready. Report the state and suggest running `/plan-sprint`
+to plan the next sprint.
 
 ---