In this article
Last updated September 18, 2026
4 min read
Many AI-generated plans are expanded task lists.
They name files, suggest an order, promise tests, and end with a confident estimate.
That can help one agent begin. It does not necessarily help a team understand or govern the change.
A team-ready plan has a different job. It exposes the decisions that will become expensive after implementation.
Start with ownership, not files
“Change OrderController.php” tells the agent where a current implementation happens.
It does not explain which module owns the behaviour, which interface is public, which service is authoritative, or
which adjacent code should remain untouched.
Start the plan with:
- product capability;
- owning module;
- affected boundaries;
- public contracts;
- data ownership;
- named decision owners.
Files can follow. Ownership gives the file list meaning.
Show what already exists
AI can produce a clean new abstraction faster than it can understand why the repository already has three similar
ones.
Require a reuse declaration:
- What existing component, service, pattern, or rule was inspected?
- Which candidate is closest?
- Does it own the same business responsibility?
- Will reuse clarify or tangle the boundary?
- If the plan creates something new, why is that the safer choice?
This converts search into a reviewable decision.
Expose rule drift
Written rules gain authority when agents load them automatically. That authority becomes dangerous when the rule is
stale.
If current code and repository guidance disagree, the plan should not silently choose one.
Record:
- the conflicting rule and implementation;
- the affected boundary;
- possible explanations;
- the human or team that owns the standard;
- whether code, documentation, or both must change.
The plan may pause here. That pause is cheaper than making every future agent consistently follow an obsolete rule.
Define the scope fence
Agents notice adjacent work. The plan should say what happens when they do.
Include:
- expected modules and artifacts;
- requested behaviours;
- expected tests and documents;
- explicit exclusions;
- a rule for discoveries outside scope;
- a maximum diff or surface that triggers re-planning.
Useful adjacent work can be recorded as a follow-up without being quietly absorbed.
Connect work to proof
“Add tests” is not an evidence plan.
For each planned behaviour, name:
- acceptance criterion;
- proof method;
- expected deterministic check;
- specialist review if required;
- human decision if required.
This lets the test writer and reviewer work from a target rather than from the implementation summary.
Route by consequence
Line count is a weak risk measure.
A three-line authorisation change can be more consequential than a three-file interface cleanup.
The plan should classify:
- reversibility;
- security and privacy impact;
- money or entitlement impact;
- public contract change;
- migration or data risk;
- breadth across modules;
- operational and rollback risk.
Use the result to select a fast, graduated, or full path. Sensitivity should set the minimum lane.
Include documentation and state
Documentation is part of the change when people and future agents use it to understand the repository.
Name:
- affected feature documentation;
- architecture or stack documents;
- API examples;
- decision records;
- migration notes;
- state needed to pause and resume.
The final documentation list may change after implementation, but it should not appear for the first time at the end.
End with open decisions, not false certainty
A strong plan can say:
- these facts are known;
- these assumptions are bounded;
- these questions require a human;
- this evidence will decide;
- this condition triggers re-planning.
That is more useful than an estimate built on unspoken choices.
How paqad-ai structures planning
paqad-ai’s feature-development workflow is designed to connect routing, module attribution, rule drift, reuse search,
scope, specification, proof, documentation, and human decisions in structured artifacts.
The point is not to generate a longer plan.
It is to create a plan that the specification, implementer, reviewer, checker, document maintainer, and human owner can
all use without reinventing the task.
A plan is ready when it reduces guessing for the team, not when it gives the agent enough words to start typing.
Install paqad-ai: https://github.com/Eliyce/paqad-ai/
Source notes
- OpenAI, Harness engineering, first-party account of repository-local
plans, progressive disclosure, and enforced architecture. - Planning mechanism: first-party details from the current Eliyce/paqad-ai repository.