MARS Developer docs

No stale documentation

Keep code, behavior, operating doctrine, and user docs in lockstep.

MARS treats documentation as part of the product. Source files declare which durable docs own their behavior, roles are expected to read and update those docs, and mars docsync audit makes missing documentation metadata mechanically visible.

Used by agents: DocSync keeps public docs and harness docs connected. For the public IA contract, read documentation-site.md and F-015; for the full map, use documentation map.

The Repo Is The System Record

MARS agents can discuss work in chat, but completed work is not true until the owning repo artifact says so. Durable state lives in committed files: goals, active plans, feature contracts, tickets, design docs, validation reports, release notes, scores, and source.

ArtifactUser meaningWhen it changes
docs/goals/What the system is trying to achieve.When priority, observations, or supersession changes.
docs/exec-plans/The active delivery strategy and scenario order.When the plan, assumptions, blockers, or current failing scenario changes.
docs/features/BDD feature contracts and business logic.Before or alongside implementation of user-visible behavior.
docs/tickets/Work item lifecycle and completion evidence.As tickets move from backlog to in-progress, review, done, or blocked.
docs/design-docs/Architecture, operating doctrine, and decision rationale.When a rule, workflow, subsystem, or architectural choice changes.
docs/QUALITY_SCORE.mdRepo-visible quality and role-health evidence.After score export, quality review, telemetry triage, or improvement work.
CHANGELOG.mdVersioned user impact and patch notes.After each non-release semantic change in MARS and initialized target repos.

MarsDocSync Metadata

A source file's top-of-file MarsDocSync block lists the minimum docs a user or agent must inspect when that file changes. The block is a review contract, not decoration.

Go, CSS, and JavaScript

/*
MarsDocSync:
docs:
- docs/design-docs/code-documentation-map.md
- docs/design-docs/documentation-sync-architecture.md
- docs/features/F-001-delivery-operating-model.md
*/

HTML

<!doctype html>
<!--
MarsDocSync:
docs:
- README.md
- docs/index.html
- docs/product-specs/product-surface.md
-->

Keep <!doctype html> first, then place the metadata comment immediately after it.

YAML and workflows

# MarsDocSync:
# docs:
# - docs/design-docs/cli-tool-skill-sync.md
# - docs/features/F-004-target-harness-lifecycle.md

What Belongs In The List

  • Feature contracts that define the user-visible behavior.
  • Design docs that explain architecture or operating doctrine.
  • Product specs or README surfaces users rely on.
  • Generated target guidance when source changes alter deployed harness behavior.
  • Release, tool, or CLI sync docs when a command or tool surface changes.

BDD Feature Contracts

Business logic belongs in docs/features/. A feature contract explains step-by-step product behavior, scenarios, rules, validations, permissions, routing, scoring, trust behavior, release classification, and user-visible outcomes.

Before implementation

Write or update the scenario and business rules that define done.

During implementation

Build the next walking-skeleton slice that makes one real scenario pass.

During review

Check code, docs, tests, and evidence against the exact scenario.

At release

Separate shipped user behavior from enabler work in the changelog.

User rule: if a behavior matters to a user, role, or reviewer, do not leave it only in chat, ticket notes, or source comments. Put it in the owning feature contract or design doc.

Context Routes

Documentation sync and context efficiency work together. MARS keeps prompts small by injecting compact route hints and letting roles retrieve deeper docs when they need them. 

routes:
  - when: role routing, domains, modes, schedules, chains, trigger routing, handoff, feedback, persona manuals, or manifest role behavior
    paths: .harness/manifest.yaml, docs/roles/ROLES.md, docs/roles/personas, docs/design-docs/harness-operating-model.md, docs/design-docs/context-glossary.md
  - when: implementation, architecture, tests, local commands, CLI commands, command flags, source documentation metadata, no-stale-documentation checks, or CLI tool/skill sync
    paths: AGENTS.md, README.md, docs/design-docs/context-glossary.md, docs/design-docs/code-documentation-map.md, docs/design-docs/documentation-sync-architecture.md, docs/design-docs/cli-tool-skill-sync.md, docs/features/README.md

Users should add routes when agents repeatedly miss the same durable context. Prefer pointing at existing docs over copying long instructions into role prompts.

User Workflow

1. Identify the behavior owner

Find the feature contract, design doc, product spec, README, or generated target guidance that explains the behavior you are changing.

rg -n "release notes|model override|ticket delivery" docs README.md AGENTS.md

2. Read the file metadata

Open the changed source file's MarsDocSync docs and decide whether each is still accurate after the change.

sed -n '1,40p' internal/models/overrides.go

3. Update docs alongside behavior

Change durable docs in the same patch as code or record explicitly why no doc text changed.

edit docs/features/F-003-local-inference-lifecycle.md
edit docs/design-docs/local-inference.md

4. Run audit evidence

Use the CLI or mirrored tool before review, release, or successful job disposition.

mars docsync audit --repo .
mars tools run docsync_audit --repo . --args-json '{}'

Audit Evidence

mars docsync audit is local and deterministic. It walks audited source roots, parses metadata, checks referenced docs exist, and applies foundation prefix rules when running inside the MARS source repo.

FindingWhat it meansUser fix
Missing metadataAn audited source file has no top-of-file MarsDocSync block.Add metadata that points to the owning docs.
Missing docsA listed path does not exist or is not a durable documentation artifact.Correct the path or create the owning doc.
Missing required docsA foundation source file omitted baseline docs from the code-documentation map.Add the required baseline path and read it before completing the change.
Parse errorThe metadata block shape is invalid for that file type.Use the documented block comment, HTML comment, or YAML comment format.

Validation Commands

mars docsync audit --repo .
go test ./internal/docsconsistency ./internal/docsync
git diff --check

For docs-only static-site work, this audit plus static link and syntax checks is usually enough. Runtime, generated-target, release, orchestration, inference, scoring, or safety changes need the broader validation gates documented elsewhere.

Generated And Deployed Docs

Target repos inherit the no-stale-documentation model. Generated harnesses receive AGENTS.md, a context glossary, feature-contract scaffolding, release docs, ticket lifecycle docs, a role registry, and knowledge routes. After init, those files belong to the target repo.

SurfaceGenerated purposeUser ownership
AGENTS.mdFirst-read map and working discipline.Target-owned after init.
docs/design-docs/context-glossary.mdProject vocabulary and routing hints.Target-owned; expand as terminology grows.
.harness/knowledge/context-glossary.yamlCompact context routes into durable docs.Target-owned; tune for project concepts.
docs/features/README.mdBDD contract rules and feature index.Target-owned behavior truth.
docs/roles/ROLES.mdRole inventory matching the manifest.Target-owned registry; custom roles use Origin: custom.
docs/design-docs/release-versioning.mdVersion, changelog, and release note contract.Target-owned release doctrine.

Troubleshooting

SymptomLikely causeRecovery
Audit passes but prose is staleAudit proves metadata shape and paths, not semantic completeness.Read the listed docs and update the owning behavior description manually.
Agent keeps missing project terminologyContext route is absent or too vague.Add a route in .harness/knowledge/context-glossary.yaml to the right glossary or design doc.
Docs changed without codePure documentation correction or user-facing site improvement.Still run link, syntax, and DocSync checks for changed static assets.
Code changed without docsNo-stale-docs gap.Open the file metadata, update listed docs, or record why they remain current.
New command documented in one place onlyCLI tool/skill sync rule was missed.Update CLI reference, mirrored mars_cli guidance, generated target docs, and affected skills.
Generated target guidance divergesFoundation doctrine changed without mirroring or source-only classification.Classify the rule, update generator defaults and tests, or record why it is source-only.