Intent-Planner

Inspiration

Codex can write code incredibly fast. But while working on larger projects, I kept running into a frustrating problem: every individual change looked reasonable, yet the product as a whole was slowly moving away from what I originally wanted.

The problem was not coding ability. It was that the reasoning behind the project—the goal, the tradeoffs, and the decisions that must remain true—was getting lost between prompts, specifications, implementation tasks, and separate sessions.

That experience inspired me to build intent-planner.

What it does

intent-planner is an open-source planning layer for AI coding agents. Before Codex starts implementing, it helps the human and the agent agree on what they are trying to achieve, what must not be compromised, and how to divide the work into small, testable units.

The workflow begins with a vague request. intent-planner asks the questions that could materially change the result, then organizes the answers into:

• a shared goal;
• project-wide decision criteria;
• small “packets” with clear scope, expected behavior, validation, and rollback boundaries.

A selected packet can then be exported into cc-sdd, OpenSpec, or GitHub Spec Kit and carried into specification and implementation.

Implementation is not the end of the process. Code often reveals assumptions that were invisible during planning. intent-planner records those findings as proposed updates and reflects them into the original planning documents only after human approval. This keeps the project’s intent current without allowing the agent to rewrite history on its own.

How we built it

I built intent-planner as a Node.js CLI distributed through npm. It installs agent-specific skills and a Git-friendly Markdown workspace for Codex, Claude Code, or Gemini CLI.

The planning records live inside the repository, so teams can inspect, review, version, and remove them without depending on a hosted service. The main artifacts describe the project’s goals, its non- negotiable decisions, its implementation packets, and what was learned after implementation.

I used Codex and GPT-5.6 to build and refine the project itself. Codex helped trace changes across the CLI, skill instructions, templates, documentation, and tests. At the same time, I used intent-planner to define the goals and boundaries for those changes.

Building the tool with the kind of agent it is designed to guide became one of the project’s most useful tests.

Challenges we ran into

The hardest challenge was deciding how much context Codex should receive.

Giving it every project decision on every task created noise and made unrelated rules compete for attention. Giving it too little context allowed important constraints to disappear. I addressed this by loading only the current packet and the decisions relevant to it, while keeping project-wide rules available when they genuinely apply.

Another challenge was balancing autonomy with human control. Asking for approval at every step makes the workflow exhausting, but allowing unresolved decisions to pass silently creates expensive mistakes.

intent-planner stops only when a decision could change the outcome, scope, external contract, or a hard-to-reverse choice. In those cases, it presents a recommendation, explains why, and states what new evidence would change that recommendation.

I also had to keep behavior consistent across multiple agents, languages, and export formats. A small wording change can accidentally weaken one version of a safety rule. The project therefore uses automated parity checks and tests that deliberately remove or reverse important rules to confirm that the test suite catches the regression.

Accomplishments that we're proud of

I am proud that intent-planner is not just a prototype or a collection of prompt files. It is a working npm package that can be installed with one command and used with multiple coding agents.

It supports the full loop from early intent discovery to specification handoff and post-implementation learning. It can export work into three different specification-driven development tools without taking ownership of those tools or locking the user into a hosted platform.

I am especially proud that intent-planner is used to develop itself. Its own goals, decisions, implementation packets, and lessons are managed through the same workflow it gives to other projects. That self-hosting process has exposed problems that would have been easy to miss in a demonstration- only project.

What we learned

The biggest lesson was that more context does not automatically produce better alignment. An agent needs the smallest set of decisions that genuinely constrains the work in front of it, together with a reliable path back to why those decisions exist.

I also learned that planning cannot be a one-way handoff. Intent must travel into implementation, and implementation must be able to return evidence and new knowledge.

Finally, technical completion and user value are different. Passing tests can prove that an implementation works as specified, but it does not prove that the product created the intended outcome. intent-planner keeps implementation evidence and post-release results separate so neither is overstated.

What's next for intent-planner

The next step is to validate the workflow across more real-world projects, especially large existing codebases where the original design intent is incomplete or no longer documented.

I also want to make the first-run experience simpler, improve the quality of handoffs into downstream specification tools, and learn which decisions are genuinely useful during implementation versus which ones only add noise.

The long-term goal is not to add more process. It is to find the smallest amount of shared intent that lets humans and coding agents move quickly without losing the reason the project exists.

Built With

• codex
• git
• gpt-5.6
• javascript
• markdown
• node.js
• npm
• test