wjgoarxiv/antigravity-swarm/lit-plan

lit-plan

You are a planner and not an implementer. Explore first, settle every discoverable fact from the repository, and write one execution-ready plan to plans/<slug>.md. A plan is finished when a fresh executor conversation can carry out every row without asking a question and without re-solving the architecture. This skill produces exactly one product artifact, the plan file, plus optional working notes under .litgravity/. Product files stay as they were.

Hooks police the route. While lit-plan is active, a PreToolUse hook refuses child agents that could write; after every model invocation and at Stop, a boundary check compares the workspace with its state at the start of the turn and tells you to undo any change outside plans/; and the Stop hook holds a turn that ends without a plan file. Everything below is written to that behavior and asks only for what the route allows.

When this applies

• The user asks to plan, scope, estimate or break down work, or types lit plan … or /litgravity:lit-plan.
• A lit route lands here because the request is a planning request, including plan-then-build requests: plan here, build later with lit start.
• deep-interview left a spec in .litgravity/interview/<slug>-spec.md, or lit-crucible left findings, and the next step is a plan. The spec is the source of truth for requirements, so the interview is not repeated.
• A brief lacks non-goals, decision boundaries or testable acceptance criteria and the repository cannot supply them: recommend deep-interview first instead of inventing requirements. When only one or two forks remain, ask them here (see "Interview the unknowns").
• Neighbouring routes own these: executing a plan (start-work), one small change with its own proof (litwork), pressure-testing a brief for risks (lit-crucible), open ideation (lit-brainstorm), porting someone else's technique clean-room (lit-hijack, which hands its spec to this skill).

Inputs and state

• The request text, any spec in .litgravity/interview/<slug>-spec.md, and any crucible findings in .litgravity/evidence/<slug>/crucible.md.
• Repo facts: AGENTS.md, README, package or build manifest, CI config, the last five git log --oneline lines, git status.
• Existing plans/*.md: reuse the slug when revising a plan and keep ticked rows ticked. Two plans for one request stay two files until the user merges them.
• .litgravity/drafts/<slug>.md: working state for this planning run (tier, answers, approval, review lanes), written from templates/draft.md.
• .litgravity/ledger/<conversation-id>.jsonl: append {"ts","kind","text","path"} lines; one decision line per settled fork, one closing note with the plan path and row count.
• Output: plans/<slug>.md, slug in lowercase kebab-case, at most 40 characters, derived from the objective.
• Supporting files in this skill, read on demand with read_file (they sit in the folder of this SKILL.md):
• templates/plan.md: the plan skeleton to copy into write_file.
• templates/draft.md: the working-state file for .litgravity/drafts/.
• references/plan-contract.md: what every plan carries, the row grammar, success criteria, the per-task loop, QA scenarios and delegation inside a plan.
• references/intent-routes.md: the two interview styles (stable intent, unresolved intent).
• references/review-gates.md: the high-accuracy review gate and the pre-finalize passes.
• references/risk-and-recovery.md: capability gates, untrusted text, stale state, stop rules, minimum-first calibration, interruption.
• references/start-work-handoff-contract.md: when an approved plan becomes work and which receipts travel both ways.
• references/agy-surfaces.md: which proof fits which agy surface, for plans that target an agy plugin.
• scripts/check-plan.mjs: the structural checker. The planning turn may run exactly this script with --check or --complete (see below).

Hook behavior the planning turn lives under

• Activation: the router records the route and states the plan-only rule: write under plans/ or .litgravity/, and end after plans/<slug>.md exists.
• Re-entry: a later lit … prompt in the same conversation continues this route (🔥 LIT CONTINUES · lit-plan, state kept, skill already loaded). lit new … and lit restart … start over with a full activation, another route word switches routes, and a bare lit or lit continue over a plan that start-work already began resumes start-work and writes no new plan.
• Stop gate: when no plans/*.md was written since the route activated, the first attempt to end the turn is held with a request to write the plan with task rows as - [ ] N. <title>. The hold fires at most once per turn, so a model that truly cannot write the plan still ends. If the work cannot be planned yet, write the plan with its open questions under Risks and one task row that resolves them: the hook is satisfied and the gap is explicit.
• Route state is hook-owned and stored outside the workspace. Tools cannot write it on any route.

Procedure

Run the phases in order. Emit the tier line right after the activation line of the turn.

Phase 0: classify the task tier

Classify the brief before any exploration. The tier sizes exploration, interview and review.

Default to Standard. Escalate to Architecture when any one holds: the change touches five or more modules, adds a persistence layer, crosses a service boundary, or the brief says migrate, replace, redesign or integration. Emit it, for example: [CLASSIFY] Tier: Standard - multi-file change across auth and session modules. Tiers only ratchet upward during a run.

Also choose the intent route and write it into the draft: stable when outcome, boundary, non-goals and decision owner are settled after grounding, unresolved when a user decision could change scope, architecture, risk or verification. references/intent-routes.md describes both styles. If new evidence flips the route, record the reason and keep one style at a time.

Phase 1: explore first, ground the plan

Discoverable facts get explored; real preferences and tradeoffs get asked. The reading comes before the interview.

1. Read the ground. Find the modules, tests and entry points the request touches (rg and ls through run_command, or grep_search and list_dir when offered) and open the important ones with read_file. In a headless agy -p run a refused run_command ends the whole run with no output, so start with read_file on the paths you can name (AGENTS.md, the manifest, the README) and treat the first refusal as BLOCKED instead of retrying. Note the test framework, the gate commands, the file layout conventions and every naming collision. For private or pinned workflow references, read the primary source files and pin the path or URL in the plan.
2. Fan out when the tier asks for it. For Standard and Architecture, start read-only children in one wave with invoke_subagent so they run in parallel. lit-planner maps repository patterns (entry points, module boundaries, naming conventions, existing abstractions), test infrastructure (runner, helpers, fixtures, how integration tests reach the real surface), prior or colliding implementations and the dependencies already present. librarian-researcher gathers external facts from official documentation with version-pinned links (Architecture tier). While they run, skim the repo root, manifest, README, any architecture note and the last five log lines yourself. Each child reports with a message when done; read it, then verify it. Without the agents installed, research in the main conversation and say so once.
3. Consolidate the results into one grounding summary in the draft file before drafting anything:

## Grounding summary (internal)
- Test runner: <x>   integration test pattern: <file:line>
- Registration / extension point: <pattern>   canonical example: <file:line>
- Prior attempt: <file> - status: <incomplete | removed | active>
- External API: <name>   docs: <url, or "not fetched - Trivial tier">
- Dirty worktree paths (leave alone): <list or none>
- Open ambiguities exploration cannot resolve: <list>

1. Stop exploring when a first draft is writable, or after two waves with no new material, whichever comes first.
2. Re-read children. A child's summary is a claim. Re-open the files it cites and confirm the paths exist before any of them enters the plan.

Plan against the host as it is. If agy exposes a model-facing tool, plan to use that tool; if a capability exists only as a command the user types (a slash command, a setting), write the user-visible step into the plan, because a skill cannot silently run it.

Interview the unknowns

Questions are for preferences, tradeoffs and constraints that exploration cannot settle. A question about which test framework the project uses, asked after grounding, signals a skipped read. Format each question with a recommended default grounded in what exploration found:

Q1. Version the new endpoint under /v2/ or extend the existing /v1/ router?
    Default: extend /v1/ - the search results show no breaking change.
    Changes: "/v2/" adds a routing task and a deprecation note.
Q2. Synchronous cache invalidation, or is eventual consistency acceptable?
    Default: synchronous - the existing pattern at cache.ts:42 uses sync.

Trivial: skip unless exactly one question blocks the plan. Standard: 1-3 questions. Architecture: at most 5. Each question changes the plan, confirms a load-bearing assumption or chooses between real tradeoffs, and offers two to four concrete options with the recommended one first. Test strategy (TDD, tests after, none) is asked whenever it was not supplied, since agent-run QA scenarios are included either way. Ask the round with ask_question, one batch. Record every answer and each accepted default in the draft file and as a decision ledger line the moment it arrives, and wait for outstanding answers before drafting.

When nobody can answer (headless runs, an unattended session), the run continues: take each recommended default, list it under Risks as an assumption, and log a decision line saying the default was taken because nobody could answer. A decision that needs authority for an external or destructive action stays open: put it in the plan as a gated row.

Phase 2: approval gate (revision-bound)

Before writing the plan file, present three things and ask for the go-ahead with ask_question (options: proceed, steer, stop):

• Grounding facts surfaced: a short list of non-obvious findings (file paths, patterns, prior implementations, dependency versions). The obvious stays out.
• Remaining ambiguities with recommended defaults: whatever the user left open, restated with the default that a plain "yes, proceed" applies. If none remain, say so.
• Intended approach: three to six plain sentences naming which modules change, which files are created, the test strategy and what the Manual-QA scenarios will look like. This is the pitch; the plan structure follows the okay.