Compose Next

Compose Next

Compact end-to-end contract for grill → workspace → spec → implement → verify → review → finalize → finish. One skill load, no internal skill hand-offs.

When writing a checkpoint or compacting context, preserve this recovery instruction in the checkpoint or compacted summary: on resumption, if the Compose Next instructions are absent, reload the compose-next skill before continuing.

Enter this workflow only on an explicit user request. Any clear natural-language instruction to use this workflow counts just like /compose-next; the user does not need to know or name the skill. If the user has not clearly requested the workflow, do the work directly and run none of the phases below; do not infer consent merely because the task is large or resembles a Compose task.

Step 0 — Orient

Inspect the repository, its instructions (AGENTS.md, README, existing spec files), and recent changes before asking anything. Do not ask the user for facts the environment already answers.

Decide the shape of the work:

• Fully constrained mechanical change with no durable design surface → skip Grill and Spec, go to Workspace then Implement.
• Requirements or design ambiguous → Grill first.
• Requirements clear, feature deserves a durable document → Workspace then Spec.

User gates and project overrides:

• If the user explicitly requests without worktree or specifies a worktree or workspace path, use that workspace choice and skip the default worktree gate. Do not ask again for worktree consent.
• If the user explicitly says without spec, "no spec needed", "this is a small fix", or gives an equivalent instruction, skip the durable feature document and its spec gate. Keep verification and review when the task still warrants them.
• An explicit project instruction, AGENTS.md, or user-provided agent/worktree configuration may define a project-specific worktree path, branch convention, spec path, or spec format. Use that configuration instead of the defaults in this skill. Record the override in the feature document or final report when it changes the normal artifact location.

Every path passes through Workspace before Spec or Implement; no branch skips it.

Grill — resolve decisions

Resolve one decision axis at a time. A single decision may bundle multiple dependent fields in one structured question; unrelated decisions require separate turns.

Use the Question tool for every user decision:

• Put known choices in options. Each option gets a concise label and a description explaining the consequence. List the recommendation first and mark its label (Recommended).
• For consequential choices, include 2–3 viable alternatives.
• When choices cannot be enumerated, still call Question with options: [] for free-text.
• Do not ask for permission to continue when no decision remains.

Split requests spanning independent subsystems before refining each part. Do not begin implementation until requirements and scope are settled.

Never-Ask handling

If the Question tool is unavailable or returns [Never-Ask], resolve this one decision yourself and continue:

1. Choose the option marked (Recommended) when repository evidence still supports it and it can run unattended.
2. Otherwise choose the closest minimal-scope option supported by the evidence; prefer text-only, non-interactive work.
3. If the decision includes destructive or irreversible work, choose a non-destructive path that preserves progress; never auto-approve the destructive option.
4. State the option selected and the reason in the response.

Never-Ask applies to the current decision only. At every later decision point, call the Question tool again — Never-Ask does not disable future questions or pause the workflow.

Workspace — worktree ownership

Never begin implementation on main or master without explicit user consent. If the active workspace is already chosen, skip creation below and continue with toolchain setup.

• Compare git rev-parse --git-dir with git rev-parse --git-common-dir. If they differ, use the current linked worktree; do not nest another. A non-empty git rev-parse --show-superproject-working-tree indicates a submodule, not a linked worktree.
• Create a linked worktree at .worktrees/<slug> by default. Base the new branch on the latest mainline (e.g. origin/main). If the current checkout makes the base unclear (detached HEAD, an unrelated feature branch, unknown default branch), ask the user explicitly which base to use before creating the worktree. Run git check-ignore -q "$path"; if it is not ignored, write * to .worktrees/.gitignore. Then run git worktree add "$path" -b "$branch" <base>.
• When targeting the worktree with a command, pass its absolute path as workdir; omitted workdir uses the current session directory.
• Install dependencies per repository instructions. Prefer lockfile-frozen, hardlink-friendly modes (bun ci, uv sync --frozen) over commands that mutate the lockfile. Confirm the toolchain is usable before continuing.

Spec — one document per feature

Maintain one document per feature at docs/compose/spec/<feature-name>.md from the workspace root. Do not add a date to the filename. A user-specified location overrides this path. Edit an existing document in place; never create a separate plan or report. Do not write the feature document before Workspace owns the active workspace.

Template

---
feature: <feature-name>
status: designed | in-progress | delivered
updated: YYYY-MM-DD
branch: <branch-name>
commits: <short-base-sha>..<short-head-sha> # leave empty while in progress; fill at delivery
---

# <Feature Name>

## Report

## [S1] Problem
Describe the user-visible problem.

## [S2] Design
Record the chosen behavior and the contracts needed to implement it.

## [S3] Out of Scope
State explicit boundaries.

## Tasks
- [ ] T1: <work item> — acceptance: <observable result> (covers: S2)
- [ ] T2: <work item> — acceptance: <observable result> (covers: S2; depends: T1)

Design-time rules

• Leave Report empty and set status: designed.
• Keep [Sn] anchors stable when headings change; never renumber existing anchors.
• Record settled decisions and precise contracts, not exploration history or file-level code dumps. Include architecture, interfaces, data flow, error behavior, and testing boundaries when they affect the change.
• Make each task the smallest independently verifiable work item; give it an observable acceptance criterion. Add depends: only for real prerequisites; dependencies must be acyclic.
• Add covers: for every task implementing a design section. Every design requirement must be covered by at least one task; every reference must resolve.
• Remove placeholders such as TBD, "handle edge cases", and references to unspecified similar work.
• Scale detail to the change; do not pad small designs.

Before implementation, fix ambiguous requirements, contradictions, unresolved references, and unverifiable acceptance criteria. If the user is available, request document approval with the Question tool; otherwise continue.

Amendments

Update only affected sections, bump updated:, preserve anchors, and keep only the tasks required by the amendment and their dependents. Do not regenerate the document or create duplicate tasks.

Implement

Use the feature document as the source of requirements, or the conversation for an undocumented mechanical change. When a feature document exists, set its status: in-progress on the first implementation commit. Execute tasks in dependency order. Track multi-step work with the Task tool.

For behavior changes with a cheap reproduction, write a failing test, confirm it fails for the intended reason, implement the smallest fix, and confirm it passes. A bug fix requires a regression test when one can be written. Skip test-first for generated code, configuration-only changes, throwaway prototypes, or explicit user direction.

Test public behavior. Do not duplicate production logic in expected values, add test-only production APIs, or assert only that mocks were called. Prefer real implementations over mocks.

For failures, reproduce before editing and identify the root cause from errors, diffs, recent commits, or boundary instrumentation. After two failed fixes, stop patching and re-derive the cause.