settled-reach/.claude/skills/start-sprint/SKILL.md

name, description, user-invocable, allowed-tools

name	description	user-invocable	allowed-tools
start-sprint	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.	true	Bash, Read, Grep, Glob, TeamCreate, Task, TaskCreate, TaskUpdate, TaskList, SendMessage, AskUserQuestion

Start Sprint Skill

Prepare a team branch for sprint work: sync with main, load the sprint briefing, and present actionable next steps.

Workflow

1. Determine the team

The current branch IS the team. Read it with:

git branch --show-current

Valid team branches: server, client, copy, audio, visual, ci.

If on main, follow the Main branch workflow below instead of the team branch workflow (steps 2–8).

---

Main branch workflow (sprint lifecycle management)

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:

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

db/connectors/sprint stop

This marks the active sprint as completed and lists carry-over candidates. Note the sprint number (N) from the output.

A2. Bump the version

The project version scheme is v0.1.{sprint_number}. After closing sprint N, the version is v0.1.N.

Update project.yaml:

• Set the version field to 0.1.N (this is the source of truth).

Update server/Cargo.toml:

• Set version = "0.1.N" in [package].

Update CHANGELOG.md:

• Move all entries under ## [Unreleased] into a new section ## [v0.1.N] — YYYY-MM-DD (using today's date).
• Leave ## [Unreleased] as an empty section above the new version.
• Keep the existing sub-headings (Added, Fixed, Changed, Removed) — only move entries that have content.

A3. Commit the release

Stage and commit project.yaml, server/Cargo.toml, and CHANGELOG.md:

chore(meta): release v0.1.N

A4. Tag the release

git tag v0.1.N

A5. Push

git push && git push --tags

A6. Check for a planned 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/:

   ls docs/sprints/sprint-N/
   

2. Check the ticket count:

   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:

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.

---

Team branch workflow

2. Sync with main

git fetch --all
git merge origin/main --no-edit

If the merge has conflicts, report them and stop — do not force-resolve.

3. Load sprint context

Run the sprint CLI to get the full context dump in one shot:

db/connectors/sprint start-work

This auto-detects the active sprint and current team from the branch. It outputs: sprint metadata, briefing paths, decision refs, actionable tickets, blocked tickets, and done tickets.

If no active sprint is found, report that and stop.

4. Read the sprint briefing

Read the briefing file(s) listed in the start-work output (e.g. docs/sprints/sprint-6/server.md and joint.md). If no matching briefing exists for the team, suggest running /plan-sprint to generate one.

5. Load ticket details

For tickets that need more detail than the start-work summary provides:

db/connectors/ticket show <id>

6. Read key decisions

Read the decision files referenced in the sprint briefing so the agent has full architectural context before starting work.

7. Mark tickets in progress and present the work plan

Mark all actionable (unblocked, non-done) tickets in the sprint as in_progress:

db/connectors/ticket status <id> in_progress

Then output a summary:

• Sprint name and goal
• Branch status (clean merge or conflicts)
• Tickets marked in_progress (list with IDs)
• Blocked tickets (and what blocks them)
• Key decisions loaded
• Suggested first task (lowest ID unblocked ticket)

8. Confirm and spawn the team

Before spawning agents, use AskUserQuestion to confirm the work plan and agent lineup with the user. If declined, stop.

Once confirmed:

8a. Parse agents from the briefing

Extract agent names from the **Agents:** line. Format:

**Agents:** Name (role), Name (role), ...

Map each name to its subagent_type (lowercase):

• "Dudley (simulation)" → dudley
• "Stig (UI)" → stig
• "Tyre (architecture)" → tyre
• "Hoshe (QA)" → hoshe
• "Mellanie (author)" → mellanie
• etc. (see .claude/agents/ for full roster)

8b. Create the team

TeamCreate(team_name: "sprint-{N}-{team}")

This makes you the team lead.

8c. Create tasks from tickets

For each ticket in the briefing, create a task:

TaskCreate(
  subject: "#{id}: {title}",
  description: "Full ticket details from step 5, plus briefing notes
    and integration points for this ticket.",
  activeForm: "Working on #{id}: {short_title}"
)

After creating all tasks, mirror the dependency chain from the briefing using TaskUpdate with addBlockedBy.

8d. Spawn agents

For each agent from the **Agents:** line, spawn a teammate in the background. Spawn all agents in parallel (one message, multiple Task calls):

Task(
  subagent_type: "{name_lowercase}",
  team_name: "sprint-{N}-{team}",
  name: "{name_lowercase}",
  prompt: "You are on the {team} team for Sprint {N}.
    Branch: `{team}`

    1. Read the sprint briefing: docs/sprints/sprint-{N}/{team}.md
    2. Read the decision files referenced in the briefing.
    3. Check TaskList for available work.
    4. Claim an unblocked task (TaskUpdate with owner: your name),
       mark it in_progress, and implement it.
    5. When done, mark the task completed and check TaskList for
       the next available task.

    Use `db/connectors/ticket show <id>` for full ticket specs.",
  description: "Sprint {N} {team}: {name}",
  run_in_background: true
)

8e. Report

Output to the user:

• Team name: sprint-{N}-{team}
• Agents spawned (names and roles)
• Tasks created (count actionable vs blocked)
• How to interact: SendMessage to talk to agents, TaskList to check progress

You are now the team lead. Agents work autonomously — monitor via TaskList, communicate via SendMessage, and handle blockers as they arise.