7d972a65

docs: share sprint delivery workflow with repository agents

a73x 2026-09-06 05:15

Commit message

docs: share sprint delivery workflow with repository agents

AGENTS.md

@@ @@ -0,0 +1,10 @@ @@
+# Agent instructions
+Read [CLAUDE.md](CLAUDE.md) for the repository's toolchain, architecture,
+invariants, and working rules; those instructions apply to every coding agent.
+When the user requests sprint delivery, read and follow the repository's
+[sprint-delivery skill](docs/skills/sprint-delivery/SKILL.md). It is ordinary
+Markdown and can be followed without a skill loader or a personal installation.
+Use this repository copy for mux work. Ordinary isolated edits do not require
+the sprint workflow.

docs/native-sprint-workflow.md

Old		New
@@ -1,5 +1,9 @@
1	# Native client sprint workflow	1	# Native client sprint workflow
2		2
		3	The repository's [sprint-delivery skill](skills/sprint-delivery/SKILL.md) supplies
		4	the shared workflow and instructions for agents with different tool capabilities.
		5	Any agent can read it directly; no personal skill installation is required.
		6
3	Use this formula for each native client sprint. The tiling	7	Use this formula for each native client sprint. The tiling
4	[spec](superpowers/specs/2026-09-05-native-tiling-design.md) defines behavior;	8	[spec](superpowers/specs/2026-09-05-native-tiling-design.md) defines behavior;
5	the [delivery plan](superpowers/plans/2026-09-05-native-tiling.md) breaks it into	9	the [delivery plan](superpowers/plans/2026-09-05-native-tiling.md) breaks it into

docs/skills/sprint-delivery/SKILL.md

@@ @@ -0,0 +1,100 @@ @@
+---
+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
+. **Scope and acceptance.** Choose the smallest functional deliverable within
+   the user's authorized plan. Define observable acceptance scenarios and carry
+   forward applicable retrospective actions. Clarify material unknowns early;
+   continue independent work while waiting. Existing authorization still applies.
+. **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.
+. **Delegate implementation and review.** Use the pairing below. Deliver through
+   actual user interactions and system boundaries, then integrate the result.
+. **Closing cleanup.** Explicitly review duplication, obsolete paths, temporary
+   scaffolding, and unnecessary state. Refactor what the slice exposed. Record
+   retained debt with its location, consequence, and next owner or trigger.
+. **Validate and demonstrate.** Run required repository gates and meaningful
+   checks for the change. Independently verify real behavior beyond agent
+   agreement. 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.
+. **Close and hand off.** Commit validated work within existing authorization.
+   Update the spec/plan status and `RETRO.md`: results, lessons, retained debt,
+   and checkable next-sprint actions. Record demo acceptance only when given;
+   test success does not imply user acceptance. Begin the next sprint only when
+   authorized, preserving any acceptance requirement in the agreed plan.
+## Economical pairing
+- Explicit model defaults: `gpt-5.6-luna` for implementation and
+  `gpt-5.6-terra` for adversarial review. 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.
+- 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,
+  consequence, and expected behavior. 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 sharing a
+demo, and use only the sharing scope the user authorized.