Using ComposeSDK Planning Documents: Guiding an AI Coding Assistant with a Written Planning Document
Summary: Jeremy Friedel discusses using planning documents to guide AI coding assistants for ComposeSDK applications. Unlike the prompt-by-prompt method in 'From Zero to ComposeSDK,' this approach involves drafting a comprehensive plan that guides a longer implementation session. The planning document includes details like application purpose, data models, page structures, filters, layout, and a milestone checklist. This method is beneficial when the project is well-defined in advance, reducing the need for on-the-fly decision-making. The article emphasizes the importance of reviewing the plan before implementation and keeping credentials secure, while allowing certain commands to go uninterrupted during development.
Using ComposeSDK Planning Documents: Guiding an AI Coding Assistant with a Written Planning Document
From Zero to ComposeSDK describes building a ComposeSDK application one prompt at a time, and that approach scales well. Adding one page, one widget, one filter at a time, each described on its own and confirmed before moving to the next, works for a small dashboard and for a larger one, provided each addition is independent and the person directing the assistant is already thinking through the pieces one at a time.
This article describes a different way of working with an AI coding assistant. It is not strictly better than the approach in that article, simply different. Rather than prompting through a ComposeSDK build step by step, the assistant drafts a written plan first. That plan gets revised over a few rounds while nothing has been built yet, and only then does the assistant implement most or all of it in one longer working session. It is a more involved process than the one in From Zero to ComposeSDK, worth using when enough of a project is already decided in advance that writing it down once is less effort than describing it prompt by prompt, not a step every ComposeSDK build needs.
Any modern LLM based coding assistant can drive this workflow the same way it drives the one described in From Zero to ComposeSDK. It needs the same two capabilities, editing files in the project folder and running terminal commands. This article mostly describes Claude Code as an example, but nothing about a written planning document is specific to it, and the same steps apply with another agentic editor, a standalone CLI assistant, or a desktop app with terminal access.
This article does not cover installing the editor, the assistant, Node, or ComposeSDK itself, and it assumes the setup from From Zero to ComposeSDK is already in place, a scaffolded React project with the ComposeSDK packages installed and a .env file holding the Sisense instance URL and API token. It builds on that setup rather than repeating it.
A planning document does not remove the need to review the assistant's work. It moves most of that review earlier, into the document, before the assistant starts writing code against it, rather than after each small step. A plan reviewed carefully before implementation catches a wrong field name or a missing page as a one line edit. The same mistake caught after a long stretch of implementation can require changes in many different places, and costs considerably more time to fix.
What goes Into the Planning Document
A planning document for a ComposeSDK build works best as a plain markdown file kept in the project, for example plan.md in the project root, rather than something that only exists in the chat history. As a file on disk, it can be opened and edited directly, referenced again in a later session, and it survives a long session's context being condensed in a way that conversation history alone does not.
The document does not need a fixed template, but it generally works better when it covers a few things beyond a page and widget list.
What the application is for, who uses it, and what habit or decision it supports.
Which ComposeSDK flavor the project uses, React, Angular, or Vue, since that decides the package names and component syntax everything else in the plan assumes.
The data model involved, referencing the
.tsfile already generated by the ComposeSDK CLI, or naming the data source if it still needs generating, along with why the fields involved matter to that audience, not just their names.Each page or view and its widgets, specific enough to build from, naming the chart type, the dimensions and measures, and any filters.
Interactivity between widgets or pages, such as a filter or a click on one page affecting another.
Layout and visual style, to whatever level of detail is already decided, colors, branding, density.
Where the Sisense URL and token is and how the assistant checks its own connection without viewing or saving the authentication token, covered in its own section below.
A milestone checklist, ordered the way the build should proceed, written as markdown checkboxes so the assistant can mark each one complete as it finishes.
Anything explicitly out of scope, so the assistant does not add it unasked while working through a long stretch unsupervised.
The checklist carries the most weight during implementation. A long LLM working session eventually has its earlier history summarized, and a agent's summarization keeps only a handful of the most recently read files in full alongside the summary. A checklist file the assistant is instructed to re-open at the start of each milestone stays accurate regardless of how much of the conversation itself has been condensed, because the current state of the build lives in the file rather than in memory of the conversation.
Drafting the plan
The first cycle is a conversation, not a single prompt. Describing the project and asking for a draft is enough to start. The prompts throughout this article are rough examples of the general tone and type of instruction, not meant to be copied directly. The right wording depends on the specific ComposeSDK application being built.
Draft a planning document for a new React ComposeSDK application in this folder, save it as plan.md. It's for the regional sales team, replacing three spreadsheets they currently cross-reference by hand before the weekly pipeline review, built on the Sample ECommerce data model, which mirrors what's in those spreadsheets. Use ComposeSDK's ExecuteQuery function to look at the actual values in a column if that would help, not just the field names in the schema file. The token for authentication is in .env. Cover the purpose, why the data matters to this audience, each page and its filters, any interactivity between pages, a rough visual style, and a milestone checklist. List anything you're unsure of as open questions in its own section rather than guessing.
That last instruction matters. An assistant asked to draft a plan will otherwise fill a gap with a guess that sounds reasonable rather than flagging it, and a guess buried in a paragraph of prose is easy to miss on a first read. A dedicated "Open questions" section in the draft is easy to scan and resolve before moving on.
Revising the plan across cycles
The draft is rarely final on the first pass. Revising it happens either by editing the markdown file directly, or by describing the change and letting the assistant update the file.
In plan.md, change the regional breakdown page to a map visualization instead of a bar chart, and add a country filter UI that applies across all pages. Update the milestone checklist to match.
Either editing style works, and most planning sessions mix both, a person adjusting a sentence directly while asking the assistant to work out the consequences elsewhere in the document, such as keeping the checklist in sync with a changed page list. As many cycles as needed happen before implementation starts. Nothing has been built yet, so a revision at this stage costs a paragraph, not a refactor.
Keeping the connection working while the build runs
The plan should note where the Sisense URL and token live, .env, and that the assistant's own read access to it is denied, the setup already covered in From Zero to ComposeSDK. That protection does not need re-explaining here, the plan only needs to point at it.
What is worth adding for a longer, less supervised run is two different checks, since they answer different questions.
Rotating the token or changing the URL is the only thing that actually requires re-testing whether the assistant can still reach Sisense at all. Reusing the same ComposeSDK CLI command already used to generate the data model file, pointed at a throwaway output path, is a reasonable way to confirm that without the assistant ever seeing the token value, since the script reads .env at run time on its own rather than through a tool call the assistant's file permissions would block.
// scripts/check-credentials.mjs
// Confirms Sisense credentials still authenticate, without printing
// the token. Run with: node --env-file=.env scripts/check-credentials.mjs
import { execFileSync } from 'node:child_process';
const url = process.env.VITE_SISENSE_URL;
const token = process.env.VITE_SISENSE_TOKEN;
try {
execFileSync(
'npx',
[
'@sisense/sdk-cli', 'get-data-model',
'--url', url,
'--token', token,
'--dataSource', 'Sample ECommerce',
'--output', 'scratch/credential-check.ts',
],
{ stdio: 'ignore' },
);
console.log('Sisense credentials OK');
} catch {
console.log('Sisense credential check FAILED');
}This is worth running once after setup, and again only if the plan notes that .env has changed. Running it after an ordinary milestone, like adding a widget, confirms nothing new, since nothing about the credentials changed either. This is for the assistant to run on its own, a person does not need to run it by hand.
What the assistant will almost certainly check on its own, once there is a widget to look at, is whether it renders the way the plan describes, and that is a visual check, not a credential check. If the session has a browser automation tool connected, a Playwright MCP server is a common example, the assistant can open the running dev server itself, take a screenshot, and confirm the new chart or page looks right. Asked to verify a milestone and given a way to see the running app, most assistants will reach for exactly this on their own, without needing the mechanism spelled out. Without a connected browser tool, this check still means a person glancing at the running app in a browser, the same as the smoke test described in From Zero to ComposeSDK. If the assistant asks partway through to install a browser automation tool, whether as a yes or no prompt or a plain request, it is usually worth approving. Iterative development goes far better when the assistant can see what its own code produces instead of just describing it.
The plan's connection section can state this plainly, without prescribing how.
Choosing a permission mode for the implementation run
Claude Code, used here as the concrete example, cycles through a few permission modes with Shift+Tab, and the mode in use during implementation determines how often the assistant stops to ask before acting.
Manual (the default) asks before every file edit and most shell commands. It suits the planning cycles above, where little is being written yet, but is not practical for a long implementation run, since it interrupts constantly.
Accept Edits auto-approves file edits and common filesystem commands, while still asking before other shell commands, such as installing a package or running a build, unless those have already been allow-listed. It is a reasonable default for working through a reviewed plan. Code changes stop interrupting, while a command run for the first time still gets a look.
Auto goes further, approving tool calls generally with a background safety check evaluating each action against what was asked, rather than a person reviewing each one. It suits a long stretch of implementation against a plan that has already been reviewed carefully, since there are fewer opportunities to catch a problem as it happens.
Bypass Permissions (
--dangerously-skip-permissionsat startup) skips prompts almost entirely. It is documented as intended for use inside a container or VM the assistant cannot otherwise damage, not on a developer's own machine. Since the setup this article builds on keeps a live Sisense token in.envon that same machine, this mode is out of scope here.
Other LLM's have very similar permission modes.
Whichever mode is active, deny rules are checked before any mode grants approval, so the .env protection from From Zero to ComposeSDK stays in effect through Accept Edits and Auto mode as well. Commands already known to be safe and expected by the plan, running the dev server, running tests, regenerating the data model, can be allow-listed directly in .claude/settings.json (or equivalent for your LLM) so they stop prompting even once, while everything else continues to ask.
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(npm test *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}A Stop hook, configured the same way in settings.json, is a further option worth knowing about. It runs a chosen shell command each time the assistant finishes responding, which can be pointed at the credential check script so it runs automatically after any milestone that touches .env, rather than depending on the assistant remembering the instruction in the plan. The Claude Code hooks documentation is linked below. Other LLM code assistants have similar features.
Handing off the finished plan
Once the plan reads correctly end to end, implementation itself is one request.
Work through plan.md from top to bottom. After finishing each item on the milestone checklist, check it off in the file, confirm the change renders correctly in the browser, and report the result before starting the next item. Re-read plan.md at the start of each milestone rather than relying on memory of earlier parts of this conversation. Stop and ask only when a decision is not covered by the plan.
The instruction to re-read the file matters on a long session. It is what keeps the assistant's sense of what is done and what remains accurate even after earlier parts of the conversation have been condensed.
Resuming and checking status
Because the plan and its checklist live on disk, a new session, or the same session after a break, can pick up where the last one left off.
Read plan.md and tell me which milestones are checked off, what remains, and whether any of the finished ones still need a browser check before I can consider them done.
This works whether the pause was intentional or the result of the assistant stopping to ask about something the plan did not cover.
Example planning document
The following is a shortened example of what a finished plan looks like before implementation begins, for a small internal ComposeSDK app.
# Regional Sales Pulse
*Sisense ComposeSDK Planning Document*
## Purpose
Built as a React ComposeSDK application for the regional sales managers who
currently pull this picture together from three spreadsheets before
the weekly pipeline review. The app should answer, at a glance,
whether a region or category is trending up or down. It exists
specifically for that meeting, and is meant to make it faster and
more informative.
## Data model and what it contains
Sample ECommerce (src/models/sample-ecommerce.ts). Revenue and Units
are the two figures managers actually watch weekly. Category and
Country are the two dimensions they currently cross-reference by hand
for trends. Condition (New/Used) does not matter here and should not
appear on any page unless someone asks for it later.
## Pages, filters, and interactivity
1. Overview. Revenue and Units by month, column chart. This is the
page a manager opens first, so it should load with the current
calendar year already selected.
2. Regional Breakdown. Revenue by Country, map visualization.
3. Product Performance. Revenue by Category, ranked bar chart,
highest to lowest.
Two filters sit at the top of the app and apply across all three
pages, a date range defaulting to the last two weeks, and a country
selector. Both should be visible without opening a menu.
## Visual style
Matches the internal tools intranet look, navy header, white
background, no dark mode needed for this audience. Cards with some
padding around each chart rather than charts running edge to edge.
Nothing more elaborate than that is expected here.
## Connection and verification
URL and token in .env, read access denied per project settings.
Re-run scripts/check-credentials.mjs only if these values change.
After each milestone, confirm the change actually renders correctly
in the browser.
## Milestones
- [x] Scaffold three page routes with placeholder headers and the
shared filters wired to nothing yet
- [ ] Overview page with Revenue and Units by month
- [ ] Regional Breakdown page with Revenue by Country as a map
- [ ] Product Performance page with Category ranked by Revenue
- [ ] Shared date range and country filters applied across all
three pages
- [ ] Navigation between the three pages
- [ ] Visual pass matching the style notes above
## Testing
Add unit and integration tests where they make sense, and skip them
where they don't. Use headless browser screenshots for visual checks,
the same way each milestone gets confirmed in the browser. Confirm at
least once, early on, that a real query actually returns data, since
the credential check script only proves the token authenticates, not
that a query returns rows.
## Out of scope
No user accounts or role management beyond what Sisense already
provides. No PDF export or scheduled email in this version. Condition
does not appear anywhere unless a later request asks for it.
## Open questions
- Should the country filter support selecting more than one country
at once? Left single select for now, since that already matches
what the spreadsheets show today.
Prompt library
Drafting and revising.
Draft a planning document for [project description] as a [React/Angular/Vue] ComposeSDK application, saved as plan.md. Cover the purpose, why the data matters, which ComposeSDK flavor it uses, each page and its filters, any interactivity, a rough visual style, and a milestone checklist, with open questions listed separately.
Use ExecuteQuery to check the actual values in [columns] before finalizing that page in the plan, not just the field names in the schema file.
In plan.md, change [specific details] and update the milestone checklist to match.
Review plan.md and flag anything ambiguous enough that you would have to guess during implementation.
Connection and verification.
Add scripts/check-credentials.mjs as described in plan.md, and note that it only needs to run again if the .env values change.
After this milestone, confirm it renders correctly in the browser before checking it off.
Settings for a longer run.
Add an allow rule to .claude/settings.json (or equivalent for the LLM Code Assistant you or using) for [command], so it stops prompting for that one going forward.
Add a Stop hook in settings.json that runs scripts/check-credentials.mjs automatically whenever .env changes.
Handoff and resumption.
Work through plan.md from top to bottom, checking off each milestone as it's finished, confirming each one in the browser, and re-reading plan.md at the start of the next. Stop only for decisions the plan does not cover.
Read plan.md and report which milestones are done, what remains, and which finished ones still need a browser check.
Useful links
A written planning document is worthwhile when a application design and purpose is already decided in enough detail to write down once. A application still being thought out piece by piece is usually still faster to build the direct way, one prompt, one page, one widget at a time.
