andreiverdes/bluedoc

An agent skill for engineering docs, plans, code reviews, UI designs, slide decks, website reviews, app icons and app store listings. The agent writes one JSON file, plus small HTML fragments for screens and SVG layers for icons; a local server renders it as a page. You tick checklists, pick options, comment on any element and approve or send back; your answers and change requests go to the agent, and each revision can be compared with the last. Works with Claude Code, Codex, pi and omp.
> **Beta.** bluedoc is in beta: the doc format and commands may still change between betas. It is tested on macOS; Linux and Windows are untested. Issues and feedback are welcome on GitHub.
Doc types
| Type | What it's for | Page | |
|---|---|---|---|
| docs | Architecture pages, walkthroughs, runbooks, setup guides, change proposals | docs | |
| plan | A plan you approve or send back before the agent writes code | plan | |
| review | Review findings pinned to their lines from git, one decision per finding | review | |
| design | UI screens on a board and app icons | design | |
| website | A site's pages, live from its dev server: comment on sections, pick versions in place, each comment names the source to edit | website | |
| presentation | Slide decks with speaker notes, played in Present | presentation | |
| storelisting | An app's Google Play and App Store listing: screenshots per device, store text per locale, store checks, fastlane export | storelisting | |
| other | Status pages, incident reports, inventories, meeting notes, comparisons | other | |
What you get
- **A home page.** http://127.0.0.1:8740/ lists every doc the server knows. It opens on a pixel-art banner of a bay with a ringed planet, a night version for the dark theme and a day version for the light one, with the title and search field over it. Under the search field, chips filter by doc type and status, with a count on each; a sidebar lists projects with their folder trees. Each doc is a card whose hero shows its type's own element (a review's +/− lines, a plan's step timeline, a doc's drawing), in a grid (2–6 columns), a list or a board.
- **Blueprint canvas.** Open a system to see its parts; each level plays its own animated flow (request, event, data). Nests 3 levels deep. Edges are routed at right angles around the nodes, with labels that don't overlap.
- **Checklists as task trackers.** Each item is a two-line row (the action, then why it matters) that opens to show details, commands, checks, tables or a sub-checklist. Ticks persist on the local server; **Copy progress** exports Markdown for a PR or issue.
- **Decisions.** When the agent needs you to choose, an item shows its options as pills with the agent's recommendation starred. Pick one, or press **Accept recommended** to take every starred option at once.
- **Need more details.** Every decision item has a **Need more details** toggle after its pills. It leaves the pick alone, turns the item's dot amber and asks what is missing; the agent answers in the next revision with a fuller description and options. A plan, design, presentation or website can't be approved while an item asks for more details. Turning the toggle off withdraws a sent request.
- **Comments and Revisions tabs.** The right panel of every doc has two tabs. Comments lists your notes as Pending (saved), Open (sent) or Resolved, with a General comment field for the whole doc. Revisions switches to any earlier revision or compares two: new, changed and removed parts are marked in place with a word-level diff, next to the author's note on what changed.
- **Comments on anything.** A tray of keys at the bottom (View, Point, Select, Draw) pins a comment on an element, a selected passage or a drawn mark. **Request changes** sends the pending comments to the agent as edits to make; **Send answers** sends your picks, ticks and item comments.
- **The agent resolves what it addressed.** Each comment in a reply carries an id. The agent lists the ids it addressed in the new revision (build.py patch … --resolves ); on load, those comments move to Resolved with "Resolved by the agent in rev X".