DocOps

Typed project-state substrate for LLM-first development

Install · Quickstart · How it works · CLI reference · Developing

---

DocOps is in active development. The core CLI commands (init, validate, index, state, audit, new, schema, refresh, get, list, graph, next, search, upgrade) are shipped and stable. Additional commands (serve, html, amend, review, status) are on the roadmap — see docs/STATE.md for what's live and what's coming.

Why DocOps?

Coding agents (Claude Code, Cursor, Aider, Codex, Copilot CLI, Windsurf) land in a repo and immediately ask: what are we building, what was decided, and what's next? When that context lives in Slack threads, Jira tickets, or tribal knowledge, agents — and humans — guess.

DocOps puts three document types in docs/, typed with YAML frontmatter, linked with explicit edges, and validated by a CLI:

Type	Folder	Holds	Example
Context	docs/context/	Stakeholder inputs — PRDs, memos, research, interview notes	Product brief, user research
Decision	docs/decisions/	Architecture and process decisions (ADR format)	"Use SQLite for local state"
Task	docs/tasks/	Units of work that cite ≥1 decision or context	"Wire up SQLite per ADR-0012"

The key invariant: every task must cite at least one decision or context document. docops validate enforces this. This is the alignment contract — it prevents drift between "what we're building" and "what we said we'd build."

No other tool in the space enforces this.

How it works

docs/
  context/CTX-001-vision.md      ← stakeholder intent
  decisions/ADR-0001-pick-db.md   ← how we chose
  tasks/TP-003-wire-sqlite.md    ← what to build (cites ADR-0001)
  .index.json                    ← computed graph (don't edit)
  STATE.md                       ← generated snapshot (don't edit)
docops.yaml                      ← project config (context types, gap thresholds)

1. docops init scaffolds the folder structure, schemas, agent skills, and AGENTS.md into any git repo.
2. docops new creates documents with auto-allocated IDs and validated frontmatter.
3. docops validate checks schema and graph invariants (citations resolve, no dangling refs, task alignment rule).
4. docops index builds the enriched graph; docops state generates a human-readable snapshot.
5. docops audit finds structural gaps: accepted decisions with no tasks, stalled tasks, stale reviews.
6. Agents read STATE.md → pick a task → read its cited ADRs → code → update status → docops refresh.

The CLI is the query and mutation API. Every read command supports --json for scripting. See ADR-0018 for the design rationale.

Install

macOS / Linux (Homebrew)

brew install logicwind/tap/docops

Windows (Scoop)

scoop bucket add logicwind https://github.com/logicwind/scoop-bucket
scoop install docops

Direct download

Grab the archive for your platform from GitHub Releases, extract, and put docops on your PATH.

Docker and npm

Docker image (GHCR) and npm convenience shims (@docops/cli) are planned for a future release. See ADR-0012 for the distribution rationale.

Quickstart

From the root of any git repo:

docops init                                        # scaffold everything
docops new ctx "Product vision" --type brief        # first context document
docops new adr "Pick a database"                    # first decision
docops new task "Wire up SQLite" --requires ADR-0001 # task citing the decision
docops validate                                     # check everything is sound
docops refresh                                      # validate + index + state in one pass
docops audit                                        # find structural gaps

docops init flags: --dry-run (preview), --force (re-sync drifted files), --no-skills (skip agent skill scaffolding).

Upgrading

brew upgrade docops              # or scoop update docops
docops upgrade                   # sync skills, schemas, AGENTS.md
docops upgrade --dry-run         # preview first

docops upgrade only touches DocOps-owned scaffolding. To also rewrite docops.yaml or reinstall the pre-commit hook, use --config or --hook. Run docops update-check to see if a new version is available.

CLI reference

Command	What it does
docops init	Scaffold DocOps into a repo (idempotent)
docops upgrade	Refresh DocOps-owned files in an existing project
docops validate	Schema + graph invariants; exits non-zero on errors
docops index	Build docs/.index.json (enriched graph)
docops state	Regenerate docs/STATE.md (counts, active work, gaps)
docops audit	Structural gap punch list
docops refresh	validate + index + state in one pass
docops schema	(Re)write JSON Schemas from docops.yaml
docops new	Scaffold a new CTX, ADR, or Task document
docops get <ID>	Look up one document by ID
docops list	List docs with filters (--kind, --status, --tag)
docops graph <ID>	Typed edge graph from a starting doc
docops next	Recommend the next task to work on
docops search <query>	Substring/regex search over title, tags, body
docops html	Emit a browsable HTML viewer to docs/.html/
docops serve	Localhost web viewer on :8484 — sidebar, graph, live

All commands support --json for structured output. Run docops <command> --help for details.

HTML viewer

docops serve --open spins up a localhost web UI for the current repo: sidebar by kind (CTX / ADR / TP), frontmatter + rendered markdown on the right, and an interactive graph tab. Hover a node to focus its neighborhood, single-click to pin, double-click to open the doc. Works on any modern browser; no install, no framework — the SPA pulls Tailwind / marked / cytoscape from jsDelivr on first load.

Editor integration

docops init (and docops schema) write JSON Schemas to docs/.docops/schema/. Install redhat.vscode-yaml and add to your .vscode/settings.json:

"yaml.schemas": {
  "./docs/.docops/schema/context.schema.json":  "docs/context/*.md",
  "./docs/.docops/schema/decision.schema.json": "docs/decisions/*.md",
  "./docs/.docops/schema/task.schema.json":     "docs/tasks/*.md"
}

What DocOps is not

DocOps is a substrate, not a framework. It provides typed state — not workflow, not orchestration, not personas, and not code generation. See ADR-0014 for the full scope boundaries.

• Not a phase orchestrator (that's GSD's domain).
• Not a role/persona system (that's GStack's domain).
• Not a code generator or execution harness.
• Not a hosted dashboard or issue tracker.

Documentation

• docs/STATE.md — current project state (auto-generated)
• docs/context/ — stakeholder inputs and research
• docs/decisions/ — architecture decisions (ADRs)
• docs/tasks/ — work items with citation requirements
• AGENTS.md — orientation for coding agents working on DocOps itself
• CHANGELOG.md — release history

Contributing

Issues, feature requests, and pull requests are welcome on GitHub. This repo dog-foods DocOps: all changes go through the same validate → index → state cycle.

See AGENTS.md for the orientation guide if you're an agent, and the Makefile targets for the local development workflow:

make tidy     # go mod tidy
make build    # builds bin/docops
make test     # go test -race ./...
make lint     # go vet ./...

Developing on DocOps itself

This repository is the DocOps source, and it dog-foods its own convention. The root AGENTS.md separates the "meta" layer (this repo's own project management) from the "product" layer (what docops init emits into user repos). See ADR-0016.

Release

From a clean main:

make release VERSION=0.4.1

This bumps the VERSION file, commits, creates an annotated tag, and pushes. The tag triggers .github/workflows/release.yml, which runs goreleaser to build the matrix, attach artifacts to the GitHub Release, and update the Homebrew/Scoop stubs.

Dry-run: make release VERSION=0.4.1 DRY_RUN=1. Local snapshot (no tag, no push): make release-snapshot.

License

MIT © Logicwind Technologies Pvt Ltd — see LICENSE.

DocOps is built and maintained by Logicwind.