Plan Stream Emit

Plan Stream Emit

For any non-trivial task, emit a structured plan first and let the user see it before you start changing files. A plan is a list of small, ordered, named steps with explicit pass conditions — not prose, not a single "I'll do X" line.

When to use

Activate when any of these is true:

• The user request is multi-step (more than 3 distinct actions).
• The task is ambiguous in any way: which file, which API, which framework, which version.
• The user request is large enough that getting it wrong would cost more than 2 minutes of re-work.
• The user said "plan first" / "before you start" / "let me see your approach".
• The task crosses a trust boundary (production code, public repo, irreversible action).

When NOT to use

• A single one-shot question or one-line edit.
• The user already gave a numbered list of steps ("do 1, 2, 3, 4 in order").
• The task is trivially reversible and the cost of a wrong move is near zero.

Process

1. Stop and think before any tool call. Do not start bash, read, or write until the plan is on the page.

2. Write the plan as a todowrite list, in this exact shape:

   ## Plan — <short task name>
   
   - [ ] **Step 1**: <verb-first sentence, names the file/action>
         Pass: <one-line checkable condition>
   - [ ] **Step 2**: <verb-first sentence, names the file/action>
         Pass: <one-line checkable condition>
   - [ ] **Step 3**: <verb-first sentence, names the file/action>
         Pass: <one-line checkable condition>
   - [ ] **Step 4** (optional, only if needed): <...>
   - [ ] **Step N** (always): Verify — <how you confirm the whole task is done>
   

3. Add an "Open questions" section if any step has un-resolved ambiguity:

   ## Open questions
   
   - <question that, if answered, would change the plan>
   - <another question>
   

4. Surface the plan to the user with a one-sentence preamble: "Here is my plan — I will start with Step 1 once you confirm or correct it." Do not begin executing until the user acks, unless the user has previously said "just go" or "no need to check in for this".

5. Update the plan as you go. When a step is done, mark it complete and emit the next step's status. If reality diverges from the plan, stop and re-plan rather than silently re-routing.

6. Final step is always a Verify — how the agent will confirm the whole task is done (test pass, manual smoke, file existence check, etc.).

Output contract

The user sees, in this order:

• One-sentence preamble acknowledging the plan is coming.
• The ## Plan block.
• (Optional) The ## Open questions block.
• A clear stop point: "I'll start Step 1 once you confirm" (or, if pre-authorised, "Starting Step 1.").

After execution, the user sees the same plan with [x] checks updating live, and a final Verify line that names what was actually checked.

Example

I'll plan the migration before touching files.

## Plan — Migrate auth to OIDC alongside SAML

- [ ] **Step 1**: Read src/auth/idp.rs and src/auth/callback.rs to map the current interface.
      Pass: I can name every public function and its caller in one sentence.
- [ ] **Step 2**: Sketch the OidcProvider trait and one stub impl in a new file
      src/auth/oidc/mod.rs.
      Pass: `cargo check` passes with the new module imported.
- [ ] **Step 3**: Wire the new provider into the login/callback dispatch in src/auth/mod.rs,
      gated on a config flag `auth.oidc_enabled`.
      Pass: existing SAML tests still pass; `auth.oidc_enabled = false` is the default.
- [ ] **Step 4**: Add one happy-path test for OIDC login with a mock IdP.
      Pass: `cargo test auth::oidc` is green.
- [ ] **Step 5**: Document the new config flag in docs/auth.md.
      Pass: docs/auth.md lists `oidc_enabled`, `oidc_issuer`, `oidc_client_id`.
- [ ] **Verify**: Run the full test suite + a manual smoke against the dev OIDC sandbox.

## Open questions

- Do you have a preferred OIDC library (openidconnect crate vs oauth2 + manual JWKS)?
- Should the OIDC path share the session store with SAML, or own its own?

Common pitfalls

• Do not emit a plan and then ignore it. Every tool call should map to a step. If reality diverges, stop and re-plan, do not silently re-route.
• Do not write prose plans. "I'll look at the code and then maybe refactor" is not a plan. Every step names an action and a pass condition.
• Do not skip the Verify step. The user must be able to trust the agent to confirm the whole task is done, not just the last file edit.
• Do not over-plan trivial work. A 3-line bug fix is one step. Save the structure for work that needs it.
• Do not surface a plan and immediately barrel into Step 1. The user must have a chance to redirect cheaply, before you have committed to a path.
• Do not re-plan without telling the user. "I am going to re-plan because Step 2 hit a wall" is a one-line update; the user expects it.

Verification checklist

• Did the plan come before any tool call?
• Is every step a verb-first sentence with a pass condition?
• Did you include a final Verify step?
• Did you list Open questions instead of guessing on ambiguity?
• Did the user have a chance to confirm or redirect?
• Did you update the plan as steps completed, rather than drifting silently?
• At the end, did the Verify step actually run and pass?