docs/skills/sprint-delivery/SKILL.md

Ref: main worktree-web-client-spec   Size: 10.1 KiB   History

---
name: sprint-delivery
description: Start or resume software delivery in small functional sprints, with economical implementation and adversarial review agents, opening and closing cleanup, a working demo, and a durable retrospective. Use when the user requests this sprint workflow; ordinary isolated edits do not need its full process.
---

# Sprint delivery

Deliver one useful, working slice at a time. Keep session continuity in the
repository, not in a long conversation or this skill. This skill supplies a
workflow; it does not authorize a new sprint, deployment, or external publication.

## Use with any agent

This repository copy is the maintained sprint skill for mux. Any coding agent
can read this file and follow it as Markdown; a skill loader is optional.
For tools without automatic discovery, ask: "Read
docs/skills/sprint-delivery/SKILL.md and use it to resume the sprint."

Use the agent's available tools for file edits, commands, delegation, and review.
The model names and collaboration parameters below are defaults where supported.
If those models are unavailable, state the substitution and use an economical
implementer and a capable reviewer. If delegation is unavailable, perform
implementation and a separate adversarial review pass sequentially, and disclose
that the review was not independent. Keep the same acceptance scenarios,
validation gates, demo, and retrospective; do not claim unavailable checks ran.
This fallback also applies to the pairing in the native sprint guide.

## Resume from evidence

Read applicable repository instructions, git status and recent commits, the
current spec/plan, and the latest `RETRO.md` actions. Resolve project document
paths from the repository root. Read relevant sections rather than full history.
Report what is implemented, validated, accepted, and still open as distinct facts.
Check the current environment before reusing temporary demo fixtures or addresses.

For mux native-client work, `docs/native-sprint-workflow.md` links the maintained
spec and delivery plan and owns the detailed validation/demo procedure. Read it
when working in that repository. Keep terminal CLI layout separate from native
layout unless the user changes that scope. Do not embed current sprint numbers,
commit IDs, or temporary service URLs in this skill.

## Run a bounded sprint

Planner, implementer and reviewer are responsibilities with required outputs.
Assign them to people or agents using the pairing and fallback below; no separate
persona or additional agent is required for each step. Prefer less maintained
code, clear ownership and small interfaces. Each new abstraction must earn its
place by removing duplication or simplifying dependencies.

1. **Plan from existing code.** Choose the smallest functional deliverable within
   the user's authorized plan. Before proposing new code, search relevant modules
   and callers, verify what their APIs actually do, and identify reusable behavior,
   duplicated rules and refactors that would simplify the slice. Record a short
   **reuse and ownership map** in the plan:

   | Behavior or rule | Existing implementation and callers | Intended owner | Reuse, refactor or add; what can be deleted |
   | --- | --- | --- | --- |

   Cite actual file/symbol evidence. If nothing suitable exists, record where you
   searched. Explain why an existing owner cannot take any proposed new module's
   responsibility. Keep domain rules with their owner; input, rendering, storage
   and transport adapters should use those rules. Assess whether separating policy
   from external dependencies would help this slice; use the smallest justified
   boundary. Define observable acceptance scenarios and carry forward applicable
   retrospective actions. Clarify material unknowns early and continue independent
   work while waiting. Existing authorization still applies.
2. **Opening cleanup.** Inspect the touched code for small refactors that help
   the slice. Review, validate, and commit these separately within existing
   authorization. If the code is ready, say so; there is no cleanup quota.
3. **Delegate implementation and review.** Use the pairing below. Deliver through
   actual user interactions and system boundaries. The implementer follows the
   ownership map, reuses existing behavior and removes superseded paths. Report
   discoveries that change the plan and update the map before extending scope.
4. **Review correctness and structure.** The reviewer checks behavior and failure
   paths, duplicated rules, misplaced responsibilities, unnecessary state,
   excessive dependencies, obsolete code and opportunities to delete code. Supply
   concrete evidence and resolve findings through the exchange below. Review net
   production-code and dependency changes; explain growth and its benefit rather
   than treating line count as a quota. Complete closing cleanup and integrate the
   result. Record retained debt with its location, consequence, and next owner or
   trigger. "Architecture reviewed" alone is not evidence: identify the rule,
   owner, dependency or removable path and its disposition.
5. **Validate and demonstrate.** Run required repository gates and meaningful
   checks for the change. Independently verify real behavior beyond agent
   agreement. Prove claimed architectural boundaries with an appropriate check,
   such as policy tests running without the external library or service that its
   adapter uses; moving files alone does not establish isolation. Freeze source
   before final checks; rerun affected checks after meaningful changes. Demonstrate
   the working result, including relevant failure paths. A recording must show
   the actual application, not a slideshow. Serve the review page and assets on
   localhost by default. Publish only when the user explicitly requests it;
   do not prompt for optional publishing during routine delivery.
6. **Close and hand off.** Commit validated work within existing authorization.
   Update the spec/plan and ownership map to match the delivered code. Record
   results, removed duplication/paths, justified retained debt, lessons, and
   checkable next-sprint actions in `RETRO.md`; give each open item an owner or
   concrete trigger. Record demo acceptance only when given; test success does not
   imply user acceptance. Once accepted, tear down that demo's sharing route and
   owned servers/fixtures without asking again, unless the user requests continued
   availability. Verify teardown and record it; retain the page source, recording
   and validation evidence. Preserve unrelated services and demos awaiting review.
   Begin the next sprint only when authorized, preserving
   any acceptance requirement in the agreed plan.

## Model and effort routing

Use a cheap model for conversation and routine work, reserving stronger models
for planning and review:

- `gpt-5.6-luna`: conversation and implementation. Use `none` for status,
  explanation, and obvious edits; `low` for routine implementation and focused
  debugging; `medium` when inspecting several files or a small interaction.
- `gpt-5.6-terra`: adversarial review. Use `medium` for normal review and
  `high` for cross-component review or tricky regressions.
- `gpt-6-astra`: sprint planning and architectural decisions. Use `high` for
  ordinary planning, `xhigh` for protocol or ownership changes, and `max` only
  for difficult design disputes or repeated failed attempts.

Raise effort before raising the model tier when the task remains local. Escalate
to a stronger model when the task crosses component boundaries, changes a
protocol or ownership invariant, remains ambiguous, or has failed twice for the
same reason. Do not spend maximum effort on routine work.

The planning handoff must be durable in the repository (usually the sprint
plan): goal, acceptance scenarios, affected components, reusable existing code,
architectural decisions and invariants, implementation slices, review questions,
and known risks. Luna works from that artifact rather than asking Astra to
reconstruct repository context on every turn.

With collaboration tools, use `fork_turns="none"` and provide a short task
brief. A full-history fork inherits the parent model and defeats this cost
choice. Reuse agents with the intended model; an old agent with an inherited
expensive model is not a cheap substitute.

## Economical pairing

The implementation/review pairing remains Luna for implementation and Terra for
adversarial review. Astra is added only for planning and the escalation cases
above; it is not required for every slice.
- Give each agent the deliverable, relevant file paths, edit ownership,
  constraints, acceptance checks, and its partner's name. They should read only
  necessary code. The main session coordinates, integrates, and independently
  validates; assign each implementation or investigation one owner.
- The reviewer sends concrete findings directly to the implementer: trigger or
  structural evidence, consequence, and expected result. The implementer returns
  a fix and evidence or a reason the finding does not apply. Continue focused exchanges until
  findings are resolved; root adjudicates persistent disagreement against the
  spec and observations. Re-review changed parts and unresolved findings rather
  than repeating a broad review each round.
- Add agents only for independent useful work. Escalate a specific difficult
  problem to a stronger model when justified. If a selected model is unavailable,
  report the limitation and choose an available economical alternative or handle
  a small remainder locally; do not silently inherit an expensive model.

## Validation that answers the claim

Use real binaries, multiple relevant instances, and independent oracles for
claims about processes, PTYs, persistence, and rendering. Observation must not
repair the behavior being measured. Verify release configuration for every
participating binary before quoting performance. Measure input-to-visible response
separately from frame timing, and state polling overhead or other material limits.

Keep platform-specific gates and demo mechanics in project documentation. In mux,
the documented native gates complement `make ci`; the raw-output gate builds both
the daemon and GUI in release mode. Preserve existing services when serving a demo.