Files

T

jpmschweitzer 5b68c4ce80 Merge remote-tracking branch 'origin/sprint-37/ci'

2026-04-22 08:47:27 +02:00

21 KiB

Raw Blame History

name, description, user-invocable, allowed-tools

name	description	user-invocable	allowed-tools
sprint-start	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 /sprint-start. 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

Sprint branches follow the pattern sprint-{N}/{team} (e.g. sprint-31/server). Valid team names: server, client, copy, audio, visual, ci, planning.

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 /sprint-start is run on main, assess the current sprint state and do the next right thing. Query the database to determine the state:

tooling/db/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

First, check whether the sprint's work is actually done:

tooling/db/sprint status

This shows ticket counts by status (done, in_progress, backlog).

Also check for open PRs that may contain completed work waiting for review or merge:

tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple

Report the full picture to the user:

Ticket progress (done / in_progress / backlog counts)
Open PRs (if any — these represent work that's done but not merged)

If tickets remain unfinished (in_progress or backlog) or open PRs exist, do NOT close the sprint. Instead, report the current progress and ask the user what they want to do:

Continue working — switch to a team branch and run /sprint-start there to resume work
Review & merge PRs first — (only if open PRs exist) merge pending work before deciding whether to close
Close anyway — proceed with the close workflow below (carries over unfinished tickets)

Use AskUserQuestion to confirm. Do not proceed to A1 unless the user explicitly chooses to close.

A1. Close the active sprint

tooling/db/sprint stop

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

A1b. Sprint retrospective and review

Before bumping the version, run a brief retro. Present the following to the user:

What shipped — list completed tickets with one-line summaries
What didn't ship — carry-overs and why (blocked, cut, deprioritized)
What we learned — open questions raised during the sprint (new Q-NNN items), review findings that surfaced design gaps, and any assumptions that turned out to be wrong
Process notes — what worked well, what was friction (e.g. dependency chains that blocked teams, specs that were over/under-specified, review cycles that caught real issues vs busywork)
Process improvements — this is the most important section. Do NOT skip it. Look for:
- Dependency chains that blocked teams — could the sprint have been structured differently to avoid the bottleneck?
- Specs that were over-specified (wasted planning) or under-specified (wasted iteration) — what's the right level of detail for this project's current stage?
- Review cycles — did they catch real issues or create busywork?
- Agent coordination — were agents stuck, duplicating work, or idle?
- Dig into the deeper why. Don't stop at "the dependency chain blocked the copy team." Ask: why was there a dependency chain? Was the sprint structured wrong, or was the work inherently sequential? Could Phase 0 have been done pre-sprint? Should we change how we plan sprints going forward?
- If something went rough, understand the root cause — not just what happened, but why the process allowed it to happen.
- If a concrete process change follows naturally, propose it. But do NOT force improvements. If nothing was broken, say so and move on. Unnecessary process changes are worse than no changes.

Keep each section concise — a few bullet points, not a document. The retro is a conversation checkpoint, not a report. Use AskUserQuestion to let the user add their own observations and push back before proceeding.

If the user raises items that should be tracked, create Q-NNN entries or backlog tickets on the spot. If process changes are agreed, update the relevant skill files or CLAUDE.md immediately — don't defer them.

A1c. Clean up sprint worktrees (MANDATORY — do not skip)

Always run the teardown script. It's idempotent and prints "No worktrees found" gracefully if there's nothing to clean:

.claude/skills/sprint-start/scripts/sprint-teardown.sh {N}

Do not try to pre-check whether worktrees exist by running ls locally. Sprint worktrees live at $(dirname <repo-root>)/.sprint/sprint-{N}/ — a sibling of the repo root, not a child. Running ls .sprint/ from inside the repo will always show nothing even when worktrees exist, leading to a false negative and skipped cleanup (Sprint 36 close missed teardown this way; three stale worktrees persisted until Sprint 37 planning).

The script knows the correct path via its own SCRIPT_DIR — trust it.

Verify cleanup after it runs:

git worktree list

Only main should remain. Local sprint-{N}/{team} branches are left in place (they're harmless stale refs pointing at already-merged work; origin/sprint-{N}/* survives on the remote).

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 /sprint-plan.

Case B: No active sprint, but a planned sprint exists

A sprint is ready to activate. Verify it looks complete:

Check that briefing files exist at docs/sprints/sprint-N/:
```
ls docs/sprints/sprint-N/
```
Check the ticket count:
```
tooling/db/sprint status --sprint N
```

If briefings are missing or the sprint has 0 tickets, report the gap and suggest running /sprint-plan to complete planning.

If everything looks ready, activate the sprint:

tooling/db/sprint start

Then open team terminal tabs automatically:

.claude/skills/sprint-start/scripts/start-sprint.sh

This creates ephemeral worktrees under .sprint/sprint-{N}/{team}/ for each team with open tickets, and opens Ptyxis windows with tmux + Claude auto-starting in each tab. The user will have one tab per active team.

Report:

Sprint activated (name, ticket count per team)
Worktrees created and tabs opened
Each team tab runs /sprint-start to load briefing and spawn agents

Case C: No active sprint and no planned sprint

Nothing is ready. Report the state and suggest running /sprint-plan to plan the next sprint.

Team branch workflow

2. Sync with main

Sprint branches are created fresh from main by start-sprint, so they should already be up to date. If main has moved since branch creation:

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:

tooling/db/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 /sprint-plan to generate one.

5. Load ticket details

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

tooling/db/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:

tooling/db/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):

Model pin (MANDATORY for team members): every team-mode spawn — i.e. any Task with a team_name argument — must pass model: "sonnet". Sprint 37 observed Opus 4.7 teammates ignoring scope rules, leaving tasks half-done, and failing to report back via SendMessage. Sonnet 4.6 follows literal rules block discipline better. The team lead (this session, running /sprint-start) stays on whatever model the user has selected — typically Opus.

Inline (non-team) Agent spawns are exempt. One-shot reviewers (/pr-review), research subagents, and other Task calls without a team_name keep their default model. The pin applies to the long-running team-coordination path specifically, not every Agent call.

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

    RULES (NON-NEGOTIABLE):

    0. TEAM SCOPE: Your team is `{team}` on branch `sprint-{N}/{team}`.
       Stay within your team's file scope (server → server/, client → client/, copy → wiki/ + docs/atlas/ + content/).
       You may read (but not modify): docs/, decisions/, wiki/, .claude/
       Do NOT modify files belonging to other teams.

    1. GIT: Do NOT run any git commands (commit, push, pull, merge,
       checkout, branch, stash, tag, etc.). All git operations are
       handled by the team lead. No exceptions.

    2. DB SCRIPTS: When calling ticket/sprint/sqlite scripts, use
       the exact command with no wrappers or chaining. Examples:
         tooling/db/ticket show 528
         tooling/db/ticket list --sprint {N}
       Do NOT prepend python3, do NOT chain with && or ;, do NOT
       add cleanup commands. Just the bare command.

    3. READ BEFORE WRITE: Before modifying ANY file, Read it first.
       Before creating a new file, Glob for similar files to learn
       the existing patterns (naming, structure, imports). Follow
       the conventions you find — do not invent new ones.

    4. VERIFY AFTER WRITE: After implementing a change, grep for
       all references to functions/properties/classes you modified
       or removed. If you renamed, moved, or deleted something,
       update EVERY call site. Missing a call site breaks tests
       and blocks the team.

    5. NO PARTIAL WORK: Do not mark a task completed unless ALL
       parts of the ticket are implemented. If the ticket says
       'deliver A, B, and C', all three must exist and work. If
       you cannot complete part of a task, message the team lead
       explaining what is blocked and what remains — do NOT mark
       it completed.

    6. MESSAGE WHEN BLOCKED: If you hit a problem you cannot solve
       in 3 attempts, stop and message the team lead immediately.
       Do not silently skip work or leave stubs. Do not move to
       the next task while the current one is incomplete.

    7. BACKWARD COMPATIBILITY: When extracting, moving, or
       refactoring code, ensure all existing consumers still work.
       Add proxy methods/properties if needed. Grep for the old
       name to find every call site.

    WORKFLOW:

    1. Read the sprint briefing: docs/sprints/sprint-{N}/{team}.md
    2. Read the decision files referenced in the briefing.
       If your work touches systems.db sources (markers.json, TOML files,
       or generator code), read .claude/rules/asset-pipeline.md before
       modifying anything.
    3. Check TaskList for available work.
    4. Claim an unblocked task (TaskUpdate with owner: your name),
       mark it in_progress, and implement it.
    5. Before marking done, verify:
       - All deliverables from the ticket exist (not just some)
       - No broken references (grep for changed names/signatures)
       - New files follow existing naming and directory conventions
       - Modified files still parse (no syntax errors)
    6. Mark the task completed and check TaskList for the next
       available task.
    7. If no tasks remain, message the team lead. Do NOT shut down
       on your own.

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

8d-planning. Planning team variant — proposers vs executors

When the team is planning, agents work in discussion mode, not implementation mode. The briefing typically defines discussion rounds (propose → review → execute). Most agents are proposers — they analyze and recommend. Only designated agents execute (write to files, modify DB).

Classify agents from the briefing:

Executor agents: SI (project manager), Qatux (documenter). These agents wait for consensus before writing anything.
Proposer agents: Everyone else (Gestalt, Tyre, Paula, Ozzie, etc.). These agents analyze, propose, and discuss — they do NOT write decision files, modify the DB, or create/delete tickets.

Add this block to proposer agent prompts (replaces rules 3–5 and the WORKFLOW section from the standard template):

    PLANNING TEAM RULES (replace standard rules 3-7 and WORKFLOW):

    3. PROPOSE ONLY: You are a discussion participant. Your job is
       to ANALYZE tickets, PROPOSE team assignments, and RECOMMEND
       splits. You do NOT:
       - Write or modify decision files (decisions/*.md)
       - Run DB update/insert/delete commands
       - Create, delete, or modify tickets
       - Mark tasks as completed
       Those actions belong to executor agents (SI, Qatux) after
       the team lead confirms consensus.

    4. OUTPUT FORMAT: Your first message to the team lead should
       be your full analysis. Structure it as:
       - Your position on open questions (with rationale)
       - Proposed team assignments (table format)
       - Split candidates (if any)
       - Sprint readiness assessment
       Do NOT claim or work tasks. The team lead coordinates.

    5. WAIT FOR CONSENSUS: Do not treat your own proposal as
       decided. Other agents may disagree. The team lead calls
       consensus and directs executors to implement it.

Add this block to executor agent prompts (appended after the standard rules):

    PLANNING TEAM RULES (additional):

    8. WAIT FOR CONSENSUS: Do NOT execute DB changes, write
       decision files, or create tickets until the team lead
       explicitly tells you to. Your first message should confirm
       you are ready and describe your execution plan. Then wait.

    9. EXECUTE EXACTLY WHAT IS DIRECTED: When the team lead sends
       you a list of changes, execute them precisely. Do not add
       extra changes, reinterpret the instructions, or fill gaps
       with your own judgment. If something is ambiguous, ask
       before executing.

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.

When all tasks complete: Do NOT shut down agents. The team stays alive through PR review AND merge. Follow step 9 (post-work lifecycle).

9. Post-work lifecycle

When all tasks are complete (TaskList shows all completed):

9a. Commit and push

Run /git-commit to commit all changes, then /pr-push to create or update the PR. Do NOT shut down agents — the team stays alive through review and merge.

9b. Wait for review

Do NOT run /pr-review from the team window — PR reviews run from the main branch (a separate window/session). The team window stays on its sprint branch.

After pushing and creating the PR, report the PR number to the user and stop. Wait for review feedback to arrive (the user or the main session will relay it, or it will appear as Gitea PR comments).

9c. Handle review outcome

When review feedback arrives (from the user, main session, or PR comments):

If CHANGES_REQUESTED:

Parse the review comment table (from the Gitea PR comment or the review output). Extract each issue with:
- File path and approximate line
- Description

Create a task per issue:

TaskCreate(
  subject: "Review: {short description}",
  description: "{full issue description from review table, including
    file path and reviewer name}",
  activeForm: "Fixing review comment: {short description}"
)

Every comment is actionable — there is no "suggestion" tier to skip (per pr-review policy).

Dispatch to idle agents: send each a message via SendMessage telling them to check TaskList for new review-fix tasks. Agents claim and work tasks as usual.
After all review-fix tasks are complete, re-run /git-commit then /pr-push to update the PR. Then re-run /pr-review.
Repeat this loop until review returns APPROVED.

If APPROVED (but not yet merged):

Do NOT shut down. Approval alone is not terminal — reviewers can leave follow-up comments, the PR can be re-reviewed, or merge conflicts can surface. Keep the team alive and idle until the PR is merged into main.

Report to the user: "Sprint {N} {team} PR #{X} approved. Awaiting merge. Team remains alive."
Agents stay idle. Do not reassign them to unrelated work.
Periodically check merge state (or wait for the user to confirm the merge). The main session handles the merge itself.
If new review comments arrive between approval and merge, treat it as CHANGES_REQUESTED and re-enter the fix loop.
Once the PR is merged, proceed to 9d.

9d. Handle merge completion

When the PR is confirmed merged into main (user confirmation, Gitea state change, or the main session reports the merge):

Send shutdown_request to all sprint agents.
Wait for all shutdown_response confirmations.
Call TeamDelete to clean up.
Report: "Sprint {N} {team} complete. PR #{X} merged into main. Team shut down."

21 KiB Raw Blame History Unescape Escape