Skip to content

Doc type · "type": "plan"

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.

claude plugin marketplace add andreiverdes/bluedocclaude plugin install bluedoc@bluedoc

Inside a session the same commands are /plugin marketplace add andreiverdes/bluedoc and /plugin install bluedoc@bluedoc. Start a new session to load the skill.

Approve a plan from plan mode. Claude Code in plan mode writes the plan; bluedoc’s gate opens it as a page and the agent waits in the background. Your picks and notes reach it the moment you approve.
Send a plan back instead of saying no. Request changes with a note. The agent patches rev 2 and resolves your note, the page marks the change word by word, and you approve that.

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.

  • 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.

  • 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.

  • 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.

  • Approve once your questions are answered

    While a question asks for more details, Approve plan waits, and says why. Send the question; when the agent’s next revision answers it, approve.

  • Spot a check the code has moved past

    Proof the agent records for a step or a check is pinned to the commit it ran on. When a later commit touches the code it covers, the check reads Needs recheck and stops counting as done.

Works on every doc

Comments, revisions and approval, the same on every type.

See every shared feature
  • Pick from option rows, one or several

    Each option is a row with a radio or checkbox, the label, ★ Recommended and one line that opens to the full explanation. A question can take several answers; Need more details is the last row.

  • 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.json
python3 <skill>/scripts/serve.py open docs/plans/saved-carts.bluedoc.json
python3 <skill>/scripts/serve.py wait docs/plans/saved-carts.bluedoc.json --kind any
acme-saved-carts-plan.bluedoc.json · a step
{  "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"]}
acme-saved-carts-plan.bluedoc.json · an open question
{  "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.

Answer your agent
on a page.

Pick your agent. Each one installs the same skill from the GitHub repository.

claude plugin marketplace add andreiverdes/bluedocclaude plugin install bluedoc@bluedoc

Inside a session the same commands are /plugin marketplace add andreiverdes/bluedoc and /plugin install bluedoc@bluedoc. Start a new session to load the skill.

  • Python 3.9 or later on PATH
  • git, for code reviews
  • gh, only to import GitHub review threads