Read a plan from top to bottom
One page holds it all: the goal, the proposed design, before and after, the mockup, the steps, the files and the risks.
Doc type
Plans
A plan you approve before any code is written.
The agent writes its plan as a page: the goal, the proposed design on a canvas, the steps and the files each one touches, then the open questions with its recommendation starred. Approve it, or send it back with your notes.
"type": "plan"
Watch the status chip follow the review. The chip at the top reads Awaiting approval, then Changes requested once you send notes, then Approved once you approve the agent’s next revision.
What it’s for
Every plan has the same eight parts.
The agent starts from a skeleton and fills each part from the code it read, so plans read the same from one task to the next.
- Goal
What ships, for whom, in how many steps, and how many questions need a pick.
- Context
The current state and why it has to change, with file and line anchors.
- Approach
The proposal on a canvas, new parts marked proposed; before/after panes and mockups.
- Steps
One reviewable change each, in order, with its effort and the files it touches.
- Files
Every path the plan adds, edits, deletes or moves, and why.
- Open questions
One per choice you make, the agent’s recommendation starred.
- Risks
Likelihood, impact and mitigation, in a table.
- Verification
The checks that show the plan worked, with their commands.
Features
What you can do on the page.
Tell proposed parts from live ones
On the Approach canvas, parts the plan adds are drawn amber and dashed, apart from what runs today. A flow runs through them to show how they fit.
Compare before and after, then open the mockup
A compare block puts what changes side by side, here the API response. A mockup opens full size in a lightbox.
Follow a step to the files it touches
Each step lists its files. Click one and the files table flashes its row; the row’s step link jumps back.
Read what the agent changed after a request
When the agent’s next revision lands, Show what changed marks it against the one you saw: its notes on the changes, the question it reworked, the step it rewrote.
Works on every doc
Comments, revisions and approval, the same on every type.
Pick an option from decision pills
Each open question shows its options as pills, the agent’s recommendation starred. Pick one and the question counts as decided.
Accept every recommendation at once
Accept recommended picks every starred option in one go. Change the ones you disagree with afterwards.
Ask for more details
Need more details marks a question and asks the agent what is missing before you pick.
Send change requests to the agent
Request changes previews your notes as Markdown, then sends them in one go.
Approve the current revision
Approve lists your picks and records the approval against this revision. The agent waits for it.
Keep an approval across progress
A revision that only marks steps done keeps the approval. Any other edit asks for approval again.
How the agent uses it
The agent writes JSON. The server draws the page.
The agent fills in the steps and the files, then turns each choice it can’t make alone into an open question with a recommend. It waits for your answer before it writes code.
python3 <skill>/scripts/build.py new plan docs/plans/saved-carts.bluedoc.json --title "Saved carts"python3 <skill>/scripts/build.py docs/plans/saved-carts.bluedoc.jsonpython3 <skill>/scripts/serve.py open docs/plans/saved-carts.bluedoc.jsonpython3 <skill>/scripts/serve.py wait docs/plans/saved-carts.bluedoc.json --kind any{ "id": "repo", "title": "Write `SavedCartRepo` with the 20-cart limit", "effort": "M", "status": "todo", "md": "Saving a 21st cart throws `SavedCartLimit`.", "files": [ "services/orders-api/src/carts/savedCartRepo.ts", "services/orders-api/src/carts/savedCartRepo.test.ts" ], "refs": ["arch/api/repo"]}{ "id": "retention", "text": "How long does a saved cart stay after its last use?", "sub": "Recommend 180 days: covers half-yearly reorders.", "recommend": "d180", "choices": [ { "id": "d90", "label": "90 days" }, { "id": "d180", "label": "180 days" }, { "id": "forever", "label": "Until deleted" } ]}serve.py wait returns when you approve or request changes. Marking steps done after an approval keeps it; any other edit asks for approval again.
Install
Pick your agent.
Each one installs the same skill from the GitHub repository.
claude plugin marketplace add andreiverdes/bluedocclaude plugin install bluedoc@bluedocInside a session the same commands are /plugin marketplace add andreiverdes/bluedoc and /plugin install bluedoc@bluedoc. Start a new session to load the skill.
codex plugin marketplace add andreiverdes/bluedoccodex plugin add bluedoc@bluedocRestart Codex. The skill is listed as bluedoc:bluedoc; mention it with $bluedoc or let Codex pick it from your request.
pi install git:github.com/andreiverdes/bluedocRestart pi. Run it as /skill:bluedoc or let pi pick it from your request.
omp plugin marketplace add andreiverdes/bluedocomp plugin install bluedoc@bluedocRun /reload-plugins in an open session, or start a new one.
npx skills add andreiverdes/bluedocFor any other agent that reads skills. Or clone the repository and link skills/bluedoc into your agent’s skills folder.
Needs: Python 3.9 or later on PATH · git, for code reviews · gh, only to import GitHub review threads.
Other doc types
Six more kinds of page.
Docs
Architecture pages, walkthroughs, runbooks, setup guides and change proposals.
Reviews
Review findings pinned to their lines from git, one decision per finding.
Designs
UI screens on a pan-and-zoom board, and app icons.
Presentations
Slide decks with speaker notes, played in Present.
Websites
A site’s pages on a board, live from its dev server.
Other
Status pages, incident reports, inventories, meeting notes and comparisons.
