First day with the DOCOD Runtime

Install it. Read the state. Start from the right place.

This page is the operating manual. The argument, the architecture and the guarantees live on the runtime page.

Action names belong to the live reference of the runtime and can evolve between versions. This page teaches the stable responsibilities; the technical documentation carries the exact vocabulary of each version.

Read the argument

Two options, the same runtime

Install it and read the state.

Option 1 · harness-neutral install

git clone https://github.com/docod-ai/getdocod
./getdocod/install.sh /path/to/project

Then:

node .docod/docod.mjs status

The runtime can already read the project and derive its state without depending on a specific adapter.

Option 2 · Claude Code

/plugin marketplace add docod-ai/getdocod
/plugin install docod@docod
/docod:setup-docod

Then:

/docod:start

The start command does not assume every project begins from scratch. It reads the current state and points at the next available entry.

Requirement: Node 18 or newer. YAML ships vendored.

Two doors. The same method.

The entry depends on what is already decided.

When the investment still needs justifying

Business case → PRD → FRD → Design → Review → Tasks → Build → QA → Review

When product intent is already clear enough

PRD → FRD → Design → Review → Tasks → Build → QA → Review

Specialised designs appear when needed: data, APIs, security, infrastructure, observability.

ADRs, RFCs, trade-offs, impact analysis and counsel cut across the cycle. They appear when a decision needs them, not because the project reached the ADR phase.

The runtime executes responsibilities, not personas

Four words you will meet constantly.

Agent: An agent owns one responsibility and delivers one artifact. Not a personality with a clever prompt: a role with a contract.
Action: An action is a verb that agent can execute. Specific names can evolve between versions; the responsibility behind them is what stays stable.
Skill: A skill is reusable craft that several agents may need. It is not a document and not a phase: it is craft.
Adapter: An adapter translates the method into the capabilities of a harness. In one harness that may mean slash commands and subagents; another can materialise the same discipline differently.

The method stays. The adapter changes.

Every responsibility has an owner

From approved design to executable work.

When the project reaches implementation, the runtime moves through specialised responsibilities.

rules-factory: Derives project-specific rules from decisions, design, configuration and existing code.
task-extraction: Turns approved design into build-order tasks, each traceable to what it must deliver.
task-executor: Builds and collects evidence inside the defined scope.
qa-executor: Verifies behaviour against the requirement, not against the narrative of whoever wrote the code.
code-review: Examines the diff against the task, the design and the standards.
design-review: Performs the same kind of confrontation one phase earlier, on the design.

None of them is given authority to declare the whole process correct.

What each one does, and what it refuses to do

The commands, and the limit of each one.

Invoke an agent directly

/docod:run <agent> <action>

When you already know which responsibility has to be exercised, call its owner. The first argument is the agent; the second is the verb it knows how to execute.

A grounded example:

/docod:run prd create_prd

Calls the agent that owns the PRD to create the document. The action name belongs to the live reference of the runtime and can evolve; the responsibility behind it does not.

One task. One mandate.

/docod:loop <task>

Build → Verify → QA → Fix → Re-QA → Code review

Coordinates a single task through build and confirmation. It can fix bugs found inside that mandate and, by default, continues through code review.

The loop hands control back when:

there is a question for the user
the root cause lives in an already approved upstream artifact
the same task has failed repeatedly
a dependency blocks continuation
something needs approval
the situation deserves immediate human judgment

And there are things it deliberately never does:

it does not approve, does not deploy, does not release, does not run a whole batch of tasks, and does not turn persistence into evidence.

Resume and close a front

A project with several fronts needs two things derived state alone does not give: going back to one of them, and closing the one that died.

/docod:continue <ws>

Resumes ONE front: its state and the next step. It answers where you stopped and what the next move is.

/docod:ws list | done | abandon --reason <reason>

The lifecycle of a front: list the ones that exist, register, close and abandon.

The reason is mandatory when abandoning, and that is not bureaucracy: a front that disappears with no recorded reason comes back as a question six months later.

Approval belongs to a version.

/docod:approve <file> --by <who>

When you approve, the runtime seals that decision against the artifact body: who approved, when, and the hash of the content.

Edit → different hash → invalid approval.

No service needs to consume an event to remember this. The next derivation finds the inconsistency.

Revalidating deliberate change

When changes are intentional and several artifacts need revalidating, the runtime has a revalidation path. It requires identity, reason and scope when necessary, and shows the plan before applying it.

And when the origin of a relationship is ambiguous it stops and says it cannot resolve. The runtime does not pick an interpretation just to keep going.

Verify

node .docod/docod.mjs verify <file>

Is the state claimed by this artifact still supported by what exists now?

It can fail when it finds, among other things:

invalid frontmatter
status outside the contract
approval that no longer matches the content
stale input hash
unregistered artifact
incomplete document

And it warns about situations that deserve attention without necessarily blocking: hash fields that hold no valid hash, hashes stranded in prose, fragile anchors, ADRs used but not declared, incomplete coverage in the task index, and inconsistent attribution.

The goal is not to produce a green check. It is to make green mean something.

Status does not lie.

/docod:status

It reads derived state and shows:

workstreams
declared state against effective state
warnings
open external questions
possible actions
blocked actions, and why each one is blocked

It does not maintain that state. It calculates it.

Report is another view of the same truth.

/docod:report

Produces a static, self-contained, offline HTML file. No server, no CDN, no tracking. It organises artifacts, declared and effective status, invalid approvals, stale relationships, tasks in each state, possible and blocked actions, workstreams and the project flow.

The report is not another dashboard that must be kept in sync. It is a projection of the same state derived from the files.

Ask the project, not the chat memory.

/docod:lead

The tech lead is the runtime's resident counsel. It reads what the project actually contains: decisions, documents, code, workstreams, task state, QA results, stale inputs and open questions. Then it returns alternatives, costs, relevant evidence, a recommendation and impact.

When the counsel changes the direction of the project, it leaves an append-only entry in the counsel record.

But the decision remains human. The tech lead does not approve, does not invoke other agents on its own, and does not edit artifacts owned by someone else.

You can diagnose before adopting.

/docod:diagnose

A legacy system does not need to be fully converted before the runtime can help. Diagnostic mode performs a pre-read with no adoption commitment: it observes the repository and reconstructs only the artifacts that apply.

Every claim gets provenance:

evidence: directly observed, with a source reference
inferred: deduced from what was found
user-supplied: information provided by someone outside the code

The diagnostic also records divergences between a claim and observed reality, relevant risks the documentation does not mention, and questions the repository cannot answer that need an external owner.

And none of it becomes approval: it creates no pins, no gates, freezes no baseline and requires no adoption.

Pre-read, not pre-approved.

Govern what you are about to change

The goal is not to document years of system history before touching the next feature.

The recommended path is smaller.

Extract the rules the code already follows.
Reverse the design of the area you are about to change.
Reverse the data model or API contract when the change requires it.
Have a human review and approve that baseline.
Define the feature or workstream being changed.
Extract the tasks.
Build and confirm.

The adoption boundary follows the real change you need to make now, not the ambition to reconstruct the entire past.

Upstream changes have downstream consequences

When a decision changes, old work does not disappear.

The runtime mechanically detects staleness.

Understanding what should change belongs to impact analysis: it identifies the affected consumers and delegates each correction to the owner of that artifact.

When a dependency is explicitly waivable, the path is not to ignore it. It is to record the waiver and its reason.

A waiver is a recorded decision. Not silence.

No benchmark, no case study, no believing a slide

The most important demo takes four steps.

Approve an artifact.
Edit the approved content.
Run verify.
Watch the approval become invalid and downstream work block again.

That is the difference between documentation that says governance exists and a runtime that can show when it stopped existing.

The table you will come back to

First day with DOCOD.

I want to	Use
Start	/docod:start
See the state	/docod:status
Run work	/docod:run <agent> <action>
Run one task end to end	/docod:loop <task>
Approve	/docod:approve <file> --by <who>
Verify an artifact	node .docod/docod.mjs verify <file>
Generate a report	/docod:report
Diagnose a legacy repo	/docod:diagnose
Ask the tech lead	/docod:lead

Action names belong to the live reference of the runtime and can evolve. This page teaches the stable responsibilities.

Get the runtime Read the argument