{
  "markdown": "# Comments\n\nGoogle-Docs-style review for markdown, locally. Inline comment threads and edit suggestions live in sidecar JSON files next to your docs — a TUI or browser workspace for the human, a CLI + MCP server for agents, and a machine-readable review gate between them.\n\n[![asciicast](https://asciinema.org/a/z6fSaof32MYS36NOtZ5Oj84Lf.svg)](https://asciinema.org/a/z6fSaof32MYS36NOtZ5Oj84Lf)\n\n## Overview\n\n`comments` is built for human↔agent doc collaboration (spec-driven development). Instead of having an LLM rewrite entire documents, the agent creates a typed knowledge artifact, drafts under a template that keeps it short and reviewable, and annotates uncertain reasoning inline. The human walks those threads in the TUI or browser and signs off; the agent listens for that verdict and addresses feedback until the gate opens.\n\n## Features\n\n- **Inline comments & threads**: anchored to lines or markdown sections, with nested replies and content-based re-anchoring when the doc changes\n- **Edit suggestions**: multi-line proposals with preview and accept/reject; queued decisions apply atomically at review verdict\n- **Review gate**: `comments gate` exits 0 (approved) or 10 (changes requested); `signoff` records the human pass agents block on\n- **Doc templates as guardrails**: required sections, word caps, forced alternatives, human-owned zones, `[NEEDS CLARIFICATION:]` marker caps — built-ins: `design-doc`, `mini`, `research`, `plan`, `adr`, `rfc`, `as-built`\n- **OKF document bundles by default**: the first `comments new` initializes a standard `docs/artifacts` bundle, then creates frontmatter-rich concepts in template-guided folders; `comments context` exposes explicit relations, backlinks, sources, and review state without a whole-tree search\n- **RPI flow**: research docs with file:line evidence → plans citing the research → reviewed in the TUI where `f` peeks any citation and Enter opens `$EDITOR` there\n- **Plan-led implementation**: optional in-document phase status lists keep Summary/Evidence/Next visible across multi-day work; `context --for implementation` reports alignment without turning Comments into the runtime\n- **Autonomous research convergence**: draft-blind coverage scout + evidence verifier add missing `Qn` questions until clean; `comments analyze plan.md --against research.md` proves the handoff before review\n- **Watch**: `comments watch --until signoff` streams NDJSON review events so agents can wait on humans\n- **Browser review**: `comments serve` opens a rendered document and line-accurate source view beside live threads, suggestions, and verdict controls\n- **MCP server**: 23 tools over stdio for agent integration; batch operations; `@filename` text input\n- **Surface parity**: every MCP tool has a CLI equivalent backed by the same code — see `docs/ARCHITECTURE.md` decision 8\n\n## Why OKF and Comments fit together\n\n[Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) makes a knowledge base portable: Markdown concepts carry YAML frontmatter, folders and `index.md` files provide navigation, and optional trust fields describe provenance and lifecycle. Comments adds the collaborative layer that the format deliberately does not prescribe.\n\n| Layer | Owns | Benefit |\n|---|---|---|\n| OKF-compatible frontmatter and folders | type, title, status, provenance, relations, placement | agents can discover and traverse artifacts without guessing filenames or searching the whole repository |\n| Markdown | research, design, plan, decision, or as-built content | the durable artifact remains readable in any Markdown tool |\n| `.comments.json` sidecar | anchored threads, suggestions, verdicts, review history | agents and humans can debate and approve the artifact without polluting its content or metadata |\n\nThe first `comments new` initializes a default bundle at `docs/artifacts`; no setup command is required. Comments-specific producer configuration lives in `.comments/bundle.yaml`, while `comments.template` and `related` extend otherwise portable OKF frontmatter. Existing Markdown remains supported and is never migrated automatically. See [the OKF bundle guide](docs/OKF.md) for the exact boundary and format.\n\n## Install\n\n```bash\n# the binary (required) — prebuilt, no Go toolchain needed:\n# grab the archive for your platform from the latest release\n#   https://github.com/rcliao/comments/releases/latest\ncurl -sL https://github.com/rcliao/comments/releases/latest/download/comments_darwin_arm64.tar.gz | tar xz comments && mv comments ~/.local/bin/\n\n# or, with Go installed:\ngo install github.com/rcliao/comments/cmd/comments@latest\n\n# the Claude Code plugin: review-comments skill + MCP server, one install\n/plugin marketplace add rcliao/comments\n/plugin install comments@comments\n```\n\n## The core loop\n\n```bash\ncomments new cache-policy --template design-doc\ncomments context docs/artifacts/designs/cache-policy.md --for drafting --include-threads\ncomments add docs/artifacts/designs/cache-policy.md --section \"Proposed Design\" \\\n  --author agent --text \"[Q] The repository does not yet establish the proposed TTL.\" --blocking\ncomments validate docs/artifacts/designs/cache-policy.md\ncomments watch docs/artifacts/designs/cache-policy.md --until signoff\n```\n\nThe human reviews the same artifact while the agent listens:\n\n```bash\ncomments view docs/artifacts/designs/cache-policy.md   # q -> a/c/r records a verdict\ncomments serve docs/artifacts/designs/cache-policy.md  # browser alternative\n```\n\nAfter the signoff event, the agent reads `comments inbox docs/artifacts/designs/cache-policy.md` first, fixes or replies to each thread, and checks `comments gate` (exit 0 = approved, 10 = changes requested). `comments signoff` is the non-interactive verdict writer for CI or scripts; a TUI/browser verdict already records the signoff.\n\nFor Research → Plan, use the same slug and preserve lineage:\n\n```bash\ncomments new cache-policy --template research-deep\ncomments new cache-policy --template plan --from docs/artifacts/research/cache-policy.md\ncomments analyze docs/artifacts/plans/cache-policy.md \\\n  --against docs/artifacts/research/cache-policy.md --json\n```\n\n## TUI keys\n\n`j/k` move · `r` dive into thread at cursor · `Tab` cycle stacked threads · `n/N` next/prev NEW since your last signoff · `f` peek citation (Enter → `$EDITOR` at file:line) · `t` table of contents · `a`/`x` queue accept/reject on suggestions · `q` verdict (approve / request changes, `n` for a review note) · `?` full keybinding help\n\n## What the templates produce\n\nEvery template ships with a self-describing, OKF-compatible worked example under [`docs/examples/`](docs/examples/) — real subjects from this repo, written to every constraint and validating clean. These are static examples; `comments new` places live artifacts in the configured bundle.\n\n| Template | Example | Shows off |\n|---|---|---|\n| `design-doc` | [design-doc.md](docs/examples/design-doc.md) | one-pager: data flow story, full DBML model, contract interfaces |\n| `as-built` | [as-built.md](docs/examples/as-built.md) | the gate/signoff loop as it runs today, with peekable evidence |\n| `research` | [research.md](docs/examples/research.md) | documentarian findings with file:line per claim |\n| `plan` | [plan.md](docs/examples/plan.md) | phases with automated/manual success criteria |\n| `adr` | [adr.md](docs/examples/adr.md) | one decision, honest consequences |\n| `rfc` | [rfc.md](docs/examples/rfc.md) | thread citations, guide + reference level |\n| `mini` | [mini.md](docs/examples/mini.md) | a whole change in 400 words |\n\nReview any of them in the tool itself: `comments view docs/examples/design-doc.md` — peek the citations with `f`.\n\n## Storage\n\nThe knowledge bundle and the review record are intentionally separate:\n\n- `.comments/bundle.yaml` maps templates to typed folders and generates navigational indexes;\n- `docs/artifacts/**/*.md` contains portable OKF-compatible concepts;\n- `doc.md.comments.json` contains collaboration state beside each reviewed concept.\n\nSidecars keep Markdown clean, version collaboration independently, and use a SHA-256 document hash to drive the re-anchoring cascade (exact → text → fuzzy → section → orphan).\n\n## Documentation\n\n- [docs/README.md](docs/README.md) — documentation status, active proposals, and retained design records\n- [CLAUDE.md](CLAUDE.md) — command reference, architecture, agent workflow\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — system design and data model\n- [USAGE.md](USAGE.md) — current CLI and TUI workflow guide\n- [docs/OKF.md](docs/OKF.md) — OKF v0.2 boundary, default folder map, frontmatter, context modes, and RPI example\n- [skills/review-comments/SKILL.md](skills/review-comments/SKILL.md) — the agent skill (bundled by the plugin)\n\n## License\n\nMIT\n",
  "bytes": 8816,
  "sha": "f2e954a53c8600e0b13dd90b81881ae62f7719f7ef49c4e97431ed9b4ed8c7d9",
  "repo_slug": "rcliao/comments",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_rcliao_comments_docs_artifacts_index_md_a6175cfb/readme"
}