Task boards, decision records, and documentation for VS Code, stored as plain files in your repository.
RepoDoc is a VS Code extension and a command line over the same core. Both read and write the same files with the same rules, so a card moved by an agent from a terminal looks exactly like one dragged on the board.
VS Code ─┐
├─▶ @repodoc/core ─▶ boards/ decisions/ docs/
CLI ─────┘
No install step. From any repository:
bunx github:flying-dice/repodoc board list
bunx github:flying-dice/repodoc card create project-backlog "Add CSV export" --priority high
bunx github:flying-dice/repodoc card move project-backlog add-csv-export doing
bunx github:flying-dice/repodoc card comment project-backlog add-csv-export "Wired the endpoint in src/export/router.ts:22-49"
bunx github:flying-dice/repodoc card gates project-backlog add-csv-export doneEvery command takes --json for machine-readable output and --who <name> to
sign comments and gate evidence. card move refuses a move whose workflow gates
fail, exactly like the board does. See the CLI reference.
A card is a markdown file. A decision is a markdown file. A board is a folder with a JSON config. Project state is versioned with the code it describes, shows up in diffs and pull requests, and travels with every clone. There is no server and no account.
Every content block goes through one renderer: card descriptions, card comments, decision records, and docs. All render full GitHub Flavored Markdown (tables, task lists, strikethrough, autolinks), Mermaid diagrams with no network calls, and PlantUML through a configurable server. In cards and comments, path/to/file.ts:12 references become one-click links that open the file at that line.
Columns with drag and drop, WIP limits, labels, priorities, and search. Cards show a checklist count, comment count, progress, and custom field chips. The board updates when the files change on disk.
Open a card to edit its fields, tick its checklist, read its description as rendered markdown, and follow its comment history. File references in comments, such as src/core/store.ts:123, open that file at that line.
Boards define typed fields in their config: text, number, boolean, date, select, and multiselect. Values are stored in each card's frontmatter and edited in the card view. Fields marked showOnCard appear as chips on the card.
Columns can declare conditions for cards entering or leaving. A script gate requires a recorded green run of a command. A field gate checks a card field against an expression such as = true, >= 3, or contains core. A move that fails a gate is blocked with the reasons listed; choosing to override records the override in the card file.
"enter": [
{ "id": "tests-passing", "script": "npm test", "label": "All tests passing" },
{ "id": "peer-review", "field": "peer-reviewed", "check": "= true", "label": "Peer reviewed" }
]
Numbered markdown records with status and date in frontmatter. The sidebar lists them with status colors, and each record opens in a reading view.
The docs/ tree renders as a handbook. Numeric filename prefixes set the sidebar order. Frontmatter renders as a table under the title. Mermaid fences render as diagrams with no network calls. PlantUML fences render through a configurable server.
RepoDoc reads the repository it lives in. Docs, decisions, cards and features whose file differs from HEAD carry a change badge in the tree, in your theme's own colours; a folder is badged when anything beneath it changed. Open one and the top bar offers HEAD → working tree: the same rendered page, with added and removed blocks marked in place — prose stays prose, diagrams stay diagrams. Card descriptions get the same toggle in the card view.
Outside a git repository, or with repodoc.git.enabled off, every surface renders exactly as it always did.
What this does not do:
- Deletions are not shown. Every RepoDoc tree is built from files it can read, so a deleted file leaves no row to badge. Badges are added, modified and renamed only.
- Frontmatter-only edits badge but do not diff. The reading view shows frontmatter as a table, not prose, so a
status:ordate:change marks the file as modified and the top bar says metadata changed — there is no body difference to render. - Renames are only detected once staged. Moving a card between columns rewrites its file name; until that rename is in the index, git reports it as a delete plus an add.
- Git is read synchronously. Results are cached until something changes, but the first read after a change happens on the extension host. On a very large repository that is a pause, not a hang.
Navigation uses standard tree views: boards expand into columns and cards, and decisions and docs open in one click. Every surface follows your color theme.
- Install RepoDoc and open a repository.
- Click the RepoDoc icon in the activity bar and run Initialize RepoDoc. This creates one file, the starter board config.
- Add cards from the board, or create markdown files under
boards/.
| Path | Contents |
|---|---|
boards/<board-id>/NN-slug.md |
One card per file. Frontmatter holds column, labels, priority, and field values |
boards/<board-id>/.config.json |
Board name, columns, WIP limits, labels, fields, gates |
decisions/NN-slug.md |
Decision records with status: and date: frontmatter |
docs/NN-slug.md |
Documentation tree, ordered by numeric prefix |
repodoc.readingWidthsets the width of reading views and the card view: narrow, wide, or full.repodoc.git.enabledshows change badges and theHEAD → working treediff. On by default; turn it off to render every surface as if the workspace were not a repository.repodoc.plantUmlServersets the PlantUML renderer. The default is the public plantuml.com server. To render privately, rundocker run -d --name plantuml -p 8792:8080 plantuml/plantuml-server:jettyand set the value tohttp://localhost:8792.