MARS Developer docs

Adoption

Adopt MARS without losing control.

MARS can act like a product engineering team. Start by proving the basics: what it can read, what it can write, how work is checked, who owns the result, and how to stop or remove it.

Summary page: this guide is not an industry checklist or a maturity model. It helps you decide what to inspect before giving MARS more trust. For canonical operating rules, use the documentation map. For control boundaries, start with security and governance.

Questions To Answer First

A good adoption decision starts with plain questions. If the answer is unclear, follow the link before running a mutating command.

What will change?

  • Local runtime state, model cache, and database paths.
  • Target harness files written into a repo.
  • Agent-mediated changes after trust is granted.

Open files and state

Who stays in control?

  • Humans can inspect before writes.
  • Trust levels and role allowlists bound autonomy.
  • Pause, stop, rollback, and eject paths are documented.

Open recovery controls

What counts as proof?

  • Goals, plans, BDD contracts, and tickets explain intent.
  • Checks, traces, validation reports, and commits show work.
  • Release notes and DocSync show what changed and why.

Open evidence flow

Try It Without Surprise Writes

Move from inspection to writes one step at a time. Each step should leave a result you can review.

  1. Check the machine and repo

    Run mars doctor --repo /path/to/repo --json. This is inspection, not a target harness install.

  2. Preview role context

    Run mars run engineer --repo /path/to/repo --dry-run --no-init to see what an agent would receive.

  3. Use a disposable target first

    Choose a throwaway git checkout with tests so you can inspect generated files without risk to an important repo.

  4. Review the init diff

    After mars init, read the new harness files, guardrails, tickets, docs, and release guidance before running agents.

  5. Run one bounded slice

    Use one clear goal, one small ticket, and one acceptance check. Stop if the evidence is not good enough.

Check The Control Boundaries

Before increasing trust, review the surfaces that decide what MARS can see, write, and claim.

QuestionWhat to inspectWhere
Where does data live?Local state, target repo files, logs, traces, model artifacts, and opt-in external routes.What stays local
How are secrets handled?Environment-variable indirection, token lookup order, redaction, and secret scanning.Credentials
What can agents do?Role tool allowlists, guardrail files, trust levels, and mutating command categories.Guardrails
How are changes reviewed?Goals, exec plans, BDD scenarios, tickets, commits, checks, and release notes.Planning and delivery
How do you recover?Pause, stop, rollback, eject, per-repo database cleanup, and incident evidence.Recovery

Understand How Work Moves

MARS is easier to evaluate when you can see the work chain. The public docs summarize it; canonical records own the details.

Intent becomes a plan

  • Goals explain the outcome.
  • Exec plans schedule the current slice.
  • BDD feature contracts define done behavior.

Open canonical records

Agents work inside bounds

  • Roles have domains, modes, tools, and guardrails.
  • Trust starts low and increases only with evidence.
  • Humans can pause, review, and override deliberately.

Open roles and agents

Evidence closes the loop

  • Checks and traces show what ran.
  • Validation reports record repeatable proof.
  • Release notes explain impact, why, and what changed.

Open checks evidence

A Sensible Pilot Path

  1. Define the reason

    Pick one outcome: faster ticket delivery, better docs discipline, release support, local agent evaluation, or evidence capture.

  2. Pick a low-risk target

    Choose a repo with tests, clear owners, and work that matters but can be reverted.

  3. Inspect before writes

    Run doctor and dry-run role context before init or start.

  4. Review generated harness files

    Confirm roles, guardrails, tickets, BDD docs, release files, and ownership model are acceptable.

  5. Run one bounded slice

    Use one goal, one plan, one feature scenario, one ticket, and a small evidence gate.

  6. Decide trust level

    Increase autonomy only after the evidence is good enough for the team that owns the repo.

Proof Checklist

QuestionWhat to inspectWhere
What can MARS write?Target files, local state, databases, logs, traces, eject cleanup.Files and state
How are secrets handled?Env var indirection, token resolution, redaction, secret scanning.Auth and credentials
How is autonomy bounded?Trust levels, role allowlists, hard/advisory guardrails, emergency controls.Governance guide
How do we know work is done?BDD contracts, tickets, checks, validation, release notes.Planning and delivery
How do docs stay aligned?MarsDocSync metadata, audit, product specs, canonical map.Documentation sync

Decide What Happens Next

A rollout decision should name the next trust level, the evidence required to keep it, and the condition that sends you back to inspection.

Continue

Keep going when generated work is reviewable, checks pass, docs stay synced, and owners understand what changed.

Pause

Pause when evidence is weak, a guardrail is unclear, a role needs tighter tools, or the repo owner cannot explain the diff.

Remove

Use the eject dry run first. Apply removal only after checking the planned file and local database cleanup.