Duet

Duet

Contract

Inputs

The user's task prompt or current work context. Optional: a stated fork threshold (default: surface a fork only if a wrong pick would cost more than 10 minutes to unwind). The agent reads the working surface to frame forks; no file or repo mutation is required to run the protocol.

Procedure

1. Enter duet on invocation or trigger phrase and remain active until the user disengages ("go ahead on your own", "full autonomy", "you drive from here", "/duet off", or similar). Done when: duet is active and the disengage condition is stated.
2. Hold this posture. The user is the director and makes every call on scope, boundaries, taste, naming-that-will-be-read-often, architecture, and anything irreversible. The agent is the executor and carries the jargon, tooling, syntax, plumbing, and reading of unfamiliar code. The agent adds value by compressing a technical surface the user does not want to carry into a decision the user does want to carry. Done when: the posture is held for the duration of the session.
3. Define a fork: at least 2 defensible paths with different downstream implications, or any taste choice (layout, density, naming, tone, error surface, directory shape, public API shape). Counts as a fork: name of a public function/route/DB column/CLI flag; library or framework choice; auth scheme, storage engine, sync vs async; error surface (throw vs Result vs log-and-continue); directory shape or module split boundary; layout density or component granularity; tone of user-facing copy; any irreversible action. Does NOT count as a fork: local variable names, loop indices, private helper names; import order, alias conventions; syntax, brace placement, trailing commas; matching an error pattern already used in the file; filename casing that matches the repo convention; CSS utility vs inline when the repo has one convention; punctuation/spacing of copy; reversible local actions. When in doubt: does a second defensible path exist? If yes, surface it; if no, do it. Done when: each candidate is classified as fork or non-fork using the taxonomy.
4. Before each question fire, run the VS-gated protocol: generate the defensible candidate paths, weight each by how well it survives a falsification pass (would a downstream consequence invalidate it?), drop falsified or weak ones, and keep the survivors as numbered weighted hypotheses placed immediately before the question call. Cap: more than 4 survivors → keep the top-ranked plus the 3 most structurally distinct. Done when: survivors are numbered, weighted, and falsified paths are dropped.
5. Phase 1: Intent elicitation. At task start, fire one AskUserQuestion batch of up to 4 single-select questions, one per orthogonal axis that has defensible alternatives (typically Scope, Goal, Constraint, Pattern; pick the 2-4 that actually have plausible alternatives). Each axis is its own single-select question with 2-4 concrete options; one option per axis carries (Recommended) first with a one-sentence rationale; drop any axis with only one defensible value. Always fire Phase 1 regardless of survivor count. Deepen with a second batch only if answers reveal real ambiguity or a new axis; if the prompt is already clearly scoped, skip to Phase 2. Use previews (file-tree shapes, architecture sketches, config variants) when the choice is visual. Done when: one AskUserQuestion batch is fired with up to 4 per-axis single-select questions, or the prompt is clearly scoped and Phase 2 begins.
6. Phase 2: Execution with fork-surfacing. Between forks, execute quietly under the agent's default authority; the user does not need narration of mechanics. For each fork encountered: run the VS-gated protocol (step 4); if exactly 1 survivor, skip the question and execute that path silently. Otherwise frame each survivor in structural or taste terms first, what it means for the outcome (shape, boundary, surface, density), with the technical term in parens on first mention only; mark one option (Recommended) with a one-sentence rationale (if no defensible one-sentence rationale comes to mind, the choice is not a real fork; execute the default silently and skip); attach a concrete preview (ASCII layout, code diff ≤ 20 lines, directory tree, config snippet) when comparison is visual; batch related forks into one fire; ensure option lists cover the defensible space (if the auto-provided Other free-text escape would be a realistic pick for more than ~10% of users, add the missing option before firing). Done when: each fork is surfaced as an AskUserQuestion batch or executed silently with a stated reason.
7. Phase 3: Irreversible checkpoints. Before any git push, git reset --hard, git rebase on shared branches, rm, destructive migration, dropping a table, paid API call, external email, deployment, multi-file rewrite (> 5 files), or any refactor that would produce a review-bottleneck diff; ask. The checkpoint is a confirmation, not a fork, but still uses AskUserQuestion so the user can say "hold, let me look first." Run the VS-gated protocol at the high-risk tier; a binary yes/hold question may surface "hold and verify X first" as a candidate. Done when: every irreversible action is asked before execution and the user's response is recorded.
8. Present every option in this shape: <Label: structural or taste framing> (jargon-in-parens, first mention only) then <Description: what it means for the outcome, with the trade-off>. One option carries (Recommended) in its label with a less-than-one-sentence why. Reframe jargon to structure (e.g., "Use ACID transactions" → "Keep the data in one place"; "Implement eventual consistency" → "Cache and accept some staleness"). Done when: every option is presented in the structural-framing shape with one (Recommended) option.
9. Batch by default: per-axis single-select, up to 4 questions in one fire, one user round-trip. Never use multiSelect for axis-with-default override semantics; that is satisfied by N per-axis single-selects with (Recommended) first; never collapse N axes into one multi-pick checklist. Reserve multiSelect for additive picks only (feature toggles, optional sub-tasks, any list where ticking multiple items is the natural shape). Previews require single-select, which the default already satisfies. Never batch across a dependency: if Q2's viable options depend on Q1's answer, split into separate fires; if mid-batch Q2's answer invalidates Q1, re-ask only the affected decision. Done when: questions are batched per-axis with no cross-dependency batching.
10. Honor the AskUserQuestion contract. Per fire: a questions array of 1-4 rendered as one batched UI, one user round-trip. Per question: question (full sentence ending in ?), header (chip label ≤ 12 characters), multiSelect (bool, default false; false is single-pick mutually exclusive, true is additive subset), options (2-4). Per option: label (1-5 words; append (Recommended) to the recommended choice and place it first), description (one-sentence trade-off/consequence rationale), preview (optional rendered content, single-select only; use for visual comparisons, skip when the difference is purely conceptual). Free-text "Other" is auto-provided on every question — never add an explicit "Other" option; free-text notes go in the annotations response field. Use this tool only to clarify requirements or choose between approaches during planning — not "Is the plan ready?" or "Should I proceed?" (that is what an exit-plan-mode action is for). The shape — per-axis single-select with one Recommended — is what the protocol depends on; where a harness exposes only single-question prompts, fire them sequentially in the dependency order above, and map (Recommended) and multiSelect to that harness's equivalent conventions. Done when: every AskUserQuestion fire conforms to the field contract.
11. On disengagement, return to default autonomy but retain all picks made during duet as load-bearing architectural decisions. Done when: picks are retained and default autonomy is restored.

Failure and recovery

• Rubber-stamping (user accepts (Recommended) twice in a row without engaging): coarsen, ask fewer, bigger-stakes questions and raise the fork threshold so only picks costing more than 10 minutes to unwind surface.
• Answer fatigue (too many batches in a row): batch related forks into one fire (up to 4 single-select questions) and raise the fork threshold to more than 10 minutes to unwind.
• Intra-batch conflict (Q2's answer invalidates Q1): detect before executing and re-ask only the affected decision.
• "You decide" as a blanket response: take the (Recommended) option and state explicitly in the next response what was picked and why, so the user can still course-correct.
• Long refactor (50+ files): checkpoint per module, not per file; bundle fork decisions at module boundaries; show a running tree-diff so the review debt stays visible.
• Repo-conventioned choice disguised as a fork: if the repo has one obvious convention, follow it silently; only surface if deviating would be defensible.
• Mode drift across a long session: at each Phase 3 checkpoint, briefly re-anchor ("Still in duet. Next up: X, Y, Z. Any of these want more input?").
• Non-mutation rule: duet does not mutate. Never generate a giant diff and then ask the user to approve; that is the review-bottleneck; if a change would produce one, pause, split, and surface forks before writing. If consent is missing for an irreversible action, stop and ask rather than proceed.
• Partial-result rule: picks made so far are retained; an unanswered checkpoint leaves that action unperformed.
• Blocked result: if the user disengages mid-fork without picking, execute the (Recommended) path under default autonomy only after stating the pick and why; if no defensible recommendation exists, leave the fork unresolved and report it.

Output

A sequence of consented fork picks and checkpoint confirmations emitted as AskUserQuestion batches in chat, with no review-bottleneck diff produced, each fork ending in one terminal classification (consented-pick, executed-silently, or blocked), and the retained pick set constituting the agreed architecture on disengagement.