# Plangate > Use for any non-trivial task with 2+ open decisions/tradeoffs OR multiple implementation steps — instead of deliberating one question at a time in chat, write a structured plan to a file and let the user review it inline in vim with `> Q:` / `> A:` blockquote markers, then revise until agreed before touching any code. Triggers on feature planning, design/architecture decisions, refactors, or multi-step work. Auto-propose it when a task hits the 2+-decisions bar; the user can opt out by saying "just answer". Do NOT use for a single simple question. - Skill: `parthganatra/plangate` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add parthganatra/plangate` - Raw SKILL.md: https://api.skillmd.com/api/skills/parthganatra/plangate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: ParthGanatra (https://skillmd.com/u/parthganatra) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/parthganatra/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 ` — open/focus the plan in a right-side vim pane (its own pane; never hijacks the user's working vim). - `wait-save.sh [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 [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 ` 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/.md` at the repo root; otherwise `~/.plans/.md`. `` 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 ` 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: - [ ] 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.