The Paqad planning stage and plan.json

What the planning stage is

Planning is the first mandatory stage of every code change. Before any code is written, the AI works out how it will approach the request, checks what already exists in your codebase, and records the result as a structured plan. paqad then turns that plan into an official record, plan.json, stored in the change's evidence bundle under .paqad/ledger/feature-evidence/<change>/.

The point is simple: an AI that has not looked at what exists tends to rebuild it. Planning makes "did you check?" a question the record has to answer.

What the AI does (judgement)

Reads the documents listed under planning.read in feature-development.yaml. By default that is docs/modules/** and docs/instructions/**.
Looks for code it can reuse, using the "existing surface" summary paqad puts in its context and, if needed, paqad-ai index query <name> to search the code index. For each piece of work it decides whether to reuse, extend or build new, and writes down why whenever it builds new.
On the graduated and full lanes, runs the diff-minimizer skill over its steps and drops any that are over-building, and runs existing-doc-checker before proposing a new document. When the change touches more than one module, it runs cross-module-impact-scanner.
Checks, at the start of planning, whether your written rules and their enforcement scripts have drifted apart (the rule-script-reconciler skill).
Writes the plan as a JSON template: a summary, ordered steps, the modules touched, the risks and how each is handled, and a reuse section. The format is on The plan file format.

What the scripts do (machine checks)

The AI starts the stage with paqad-ai stage start planning (or an equivalent marker line) and then runs paqad-ai plan compile <template.json>. The compile step is deterministic and makes no AI call. It:

refuses a template with no reuse section, or one whose reuse.consulted list is empty;
checks every reused symbol the plan names against the project's code index, and suggests the nearest real name when one does not exist;
checks framework reuse claims (a symbol from a library such as React or Laravel) against the packages you actually have installed: a claim must name the package and version, and a symbol that is missing or deprecated at that version is refused;
when a framework is detected, refuses a new construct that does not record whether the framework already offers an equivalent;
refuses a step that says it will add a new helper, util or component when no new construct is declared;
validates the result against a strict schema, adds identity fields and a content hash, writes plan.json into the bundle, and deletes the template so only the official record remains.

Where a check cannot be performed, for example because the code index has not been built yet, the compile prints a warning instead of blocking.

The AI then ends the stage against that file with paqad-ai stage end planning --artifact <plan.json>. paqad hashes the file into the stage record, so a bare "start" and "end" with no real file counts as inconclusive, not done.

Where you decide

Planning can open a decision pause, which stops the work until you answer:

Reuse or create. With decision_arm_mode set to strict, plan compile compares each declared new construct with existing code. A close match (0.85 similarity by default) opens a create-vs-reuse decision with the evidence filled in. Under the default warn, the match is reported but no pause is opened. If you already answered an identical question, the earlier answer is reused.
Cross-module impact. When the impact scan finds a change that would break or silently shift another module's public surface, the AI raises it to you as a decision pause.
Stale rule scripts. When the drift check finds rules and scripts out of step, the AI raises it to you before planning continues.
Screenshots. With visual evidence switched on, a frontend change on a machine that cannot capture screenshots opens one pause with three choices: set it up, attach your own screenshots, or record a waiver.

The gate on code edits

On Claude Code and Codex CLI, paqad blocks every code edit until planning has a recorded start, a recorded end and a hashed plan file. On the graduated and full lanes, the frozen spec is required too (see From plan to frozen spec). The gate follows the stages_mode setting, which is strict by default; the team's tracked value is a floor that a local setting can raise but not lower. On IDE tools without hooks, the AI is instructed to run the same commands, but nothing blocks the edit.

What changed from older versions

Earlier paqad documentation described a YAML "planning manifest" with a requirement graph, execution slices and a verification matrix, generated in one model call. In 1.91.1 the live flow does not produce that file. The plan is plan.json, and acceptance criteria and invariants live in the frozen spec, specification.json.

Planning a change