Plangate

PlanGate — terminal-native plan-review loop

Batch the decisions into a reviewable plan file instead of forcing the user through one-by-one chat. The user reviews in vim; their :w is the signal; you resolve and revise; no code until it's agreed. Full background & prior art: see the repo README.

Review markers (the contract). Everything the user reviews is markdown blockquotes:

• > Q: — a question / decision / anything needing the user's input. Whenever you write a > Q: line, put an empty > A: line directly under it so the user jumps in and types the answer with no marker typing (their vim has ]a to jump to the next empty > A: and start typing).
• > A: — the answer. The user fills the empty slot; you fill it when replying to a > Q: the user raised.
• An open item = an empty > A: slot (^\s*> A:\s*$), plus any > Q: the user added with no > A: under it. The loop is done when every > Q: has a non-empty > A: beneath it.
• Blockquotes keep the plan valid markdown (renders fine in Obsidian/GitHub) and — with the bundled vim reading setup (see README) — highlight > Q: vs > A:, with ]q/[q to page between open questions.

Helper scripts live beside this file:

• open-plan.sh <file> — open/focus the plan in a right-side vim pane (its own pane; never hijacks the user's working vim).
• wait-save.sh <file> [max_s] — block until the user saves; run it in the BACKGROUND so their :w re-invokes you.
• nudge-reload.sh — after you edit the plan, refresh the user's vim (:checktime + autoread) to show your > A: answers.
• prune-plans.sh <plans-dir> [days] — delete plan files untouched for N days (default 7). Run it once per plan, at step 2.

When to fire

• 2+ open decisions/tradeoffs, or multiple implementation steps → propose the loop.
• One simple/single-answer question → just answer, no plan.
• If the user says "just answer" / "skip the plan" → drop the loop for that task.

Loop

1. Scope it. Feature comes from the /plangate <description> argument if given, else infer it from the conversation and confirm your one-line summary before writing.

2. Pick the path, then prune. In a git repo → .plans/<slug>.md at the repo root; otherwise ~/.plans/<slug>.md. <slug> is a short kebab-case name. First time you create a plan in a git repo, add .plans/ to its .gitignore (and mention it). Then run prune-plans.sh <plans-dir> before writing the new plan — it deletes plans untouched for 7 days (finished or abandoned; an in-review plan's mtime is bumped by every :w, so it survives). Mention anything it pruned. Override with PLAN_RETENTION_DAYS.

3. Write the plan — a design doc and a decision surface, with decisions up front. The reader asked for this plan minutes ago and reviews it fresh — they already know the goal, so don't re-explain the ask or pad with background. Spend words on what they can't already know: the decisions, the open questions, and non-obvious design findings.

   • Order: Goal (≤3 lines) → Decisions → Open questions → Approach → Steps → Risks / unknowns. Keep a terse Goal on top for orientation, then hit the decisions immediately — don't bury them under a long exposition. Approach / Steps / Risks still carry the full design below.
   • Context budget: restating what the user asked for = cut. A background fact earns its place only if it's non-obvious and bears on a decision — put it inside that decision block, not a standalone exposition section. Findings that shape the whole design can live in Approach.
   • Open the file with a short header telling the user how to review (markers below).
   • Pose every real choice as a decision block (the checkbox / "input" pattern):

     ### Decision: <title>
     - [ ] Option A — one-line tradeoff
     - [ ] Option B — one-line tradeoff
     > Q: pick one (check the box) or comment. Recommend A because…
     > A:
     

     Options are one-line tradeoffs, not paragraphs; always give a recommendation and leave the empty > A: line so the user jumps straight to typing.
   • Genuinely leave decisions open — don't pre-resolve to avoid review.

4. Open it: run open-plan.sh <path>.

5. Wait for review: launch wait-save.sh <path> in the BACKGROUND. The user's :w will fire it and re-invoke you. (Typing "reviewed" is a manual fallback.)

6. Resolve (each round). On the save signal, re-read the file and find open items — grep -nE '^\s*> A:\s*$' (empty answer slots) plus any > Q: the user added with no > A: below:

   • The user's > A: text answers your questions; their > Q: lines are new comments/instructions (> Q: DELETE … = cut that scope, > Q: REPLACE: … = proposed change). Apply ticked [x] decisions.
   • Revise the plan inline. Fill every > A: you owe (answering a user > Q:), and for anything still needing the user, add a fresh > Q: + empty > A: pair. Leave the user's answered > Q:/> A: exchanges in place as the record.
   • Run nudge-reload.sh so their vim shows your changes.
   • Post a short chat summary of what changed — inline edits are invisible in chat.
   • Re-launch wait-save.sh in the background for the next round. Repeat until no empty > A: slots remain, every > Q: has an answer, and no decisions are unticked.

7. Gate. Do NOT write code or make implementation edits until BOTH: no open items (every > Q: has a non-empty > A:, no empty slots) AND the user explicitly approves (e.g. "approved", "go build it", "lgtm"). If the user wants to bypass planning for a quick change, honor "just answer".

8. Build. Once gated through, implement against the agreed plan.

Notes

• The > Q: / > A: markers and decision blocks are the whole contract — keep them consistent, and always pair a > Q: with an empty > A: beneath it.
• The save-signal means the user has no unsaved changes at resolve time, so nudge-reload.sh refreshes safely; :checktime won't clobber if they've started editing again.
• If wait-save.sh reports TIMEOUT, the review is just still open — re-launch it or check in.
• Portability: the scripts are best in tmux + vim/nvim on macOS or Linux. Outside tmux, open-plan.sh prints the path for you to open manually and nudge-reload.sh is a silent no-op; wait-save.sh uses entr when installed (event-driven) and otherwise falls back to mtime polling — either way it works in any editor that writes to disk.