Skip to content

Contributing

Repository layout

.
├── Cargo.toml            # virtual workspace manifest: 9 crates, resolver 2
├── kovarc.toml           # engine config (workdir, data_dir, api.addr, research, models)
├── mkdocs.yml            # MkDocs site config (docs_dir: docs/human)
├── crates/
│   ├── kova-primitives/  # deterministic core types (no I/O)
│   ├── kova-core/        # engine, state store, guard, config, CLI (binary `kova`)
│   ├── kova-router/      # LlmBackend: chat / chat_tools / raw completion
│   ├── kova-mcp/         # MCP JSON-RPC 2.0 dispatch + in-process tool registry
│   ├── kova-sandbox/     # check execution: host process group / youki OCI
│   ├── kova-actor/       # WorkOrder / VramBudget (actor pool pending)
│   ├── kova-api/         # Axum REST surface + GUI serving
│   ├── kova-gui/         # rust-embed GUI assets (assets/gui/)
│   └── kova-docs-lint/   # docs linter: frontmatter, links, write limits
├── docs/
│   ├── human/            # this MkDocs site
│   └── agent/            # machine-readable contracts (tier1 / tier2 / code_flows / templates)
├── plans/                # execution plans + sub-plans (checkmark ledgers)
└── research/plans/       # fenced plan-artifact output of the research phase

Dependency direction is strict: kova-primitives depends on nothing in the workspace; kova-core sits on top of primitives, router, mcp, sandbox; kova-api on core + gui. Keep it that way — the primitives crates exist precisely so the deterministic core stays I/O-free and unit- testable.

Build & test

cargo check --workspace --all-targets --message-format=short
cargo test --workspace                      # 115 tests, all must pass
cargo clippy --workspace --all-targets

Run the engine:

cargo run -p kova-core -- --config kovarc.toml

There is no --gui / --port / --headless — the server address is api.addr in the config file (see Getting Started).

Documentation conventions

Human docs (docs/human/):

  • Built with MkDocs + the Material theme; mkdocs build --strict must pass (CI). docs_dir is docs/human, so docs/agent/ is deliberately outside the site.
  • Every claim about code names a real file (and line, for plan docs). No invented APIs — if a component is planned but absent, say so explicitly ("planned in sub-plan 03a", "not yet wired") rather than writing it as fact.

Agent docs (docs/agent/):

  • YAML frontmatter is required and schema-checked (see Agent Docs Concept).
  • Tier 1 = module contracts (module, structs, reads, writes); Tier 2 = side-effect surfaces (target_file, procs, drivers, env); code flows = standardized execution chains.
  • Scaffold from docs/agent/templates/; every structs entry and target_file must resolve to the real tree.
  • Tier 1 docs must cross-link their Tier 2 docs (checked in CI).

Plan docs (plans/):

  • Execution plans and sub-plans use checkmark ledgers: [x] implemented & verified, [~] partial / divergent, [ ] not started, with a status header (complete / PARTIAL / not started) and file:line evidence per checkbox.
  • Update the ledger when you change the code it tracks; the ledger is the source of truth for what exists versus what is planned.

What the research agent may write

The research phase has exactly one fenced write surface: plan artifacts in research/plans/, kebab-case names, .md suffix (kova-primitives::plan::validate_plan_name). Everything else — pipeline state, the event ring, crate sources — is written only by the engine and only through its gated transitions. The Tier 1 writes declarations in docs/agent/ are the declared boundary that the write-limits validation checks against.