Work is not grounded in durable intent
Plans, tickets, decisions, and review notes often live in disconnected tools or chat memory.
Cost: the next agent repeats discovery or ships the wrong slice.Adoption explainer
Use local agents without losing control.
MARS keeps code, evidence, docs, and safety rules in your repo. You can review what happened, see why it happened, and stop or improve the loop before giving agents more trust.
Keep code local
Reduce review guesswork
Prevent stale docs
Trace every action
Turn failures into fixes
The engineering problem
Agents need an operating system.
A ticket and a codebase are not enough. Useful autonomy needs priorities, boundaries, safety rules, evidence standards, release discipline, and feedback that survives the chat.
Documentation drifts from behavior
Agents can change code faster than the surrounding docs, contracts, and release notes stay true.
Cost: reviewers lose the source of truth for what the system is supposed to do.Automation lacks a safety envelope
Without hard guardrails, trust levels, and blast-radius checks, autonomy becomes a governance risk.
Cost: teams cannot safely move beyond demos and read-only experiments.Telemetry is passive
Failures, human follow-up, reverts, no-ops, and slow loops are collected but rarely routed into improvement.
Cost: the same class of failure burns time again next week.Value lens
Value is trustable delivery.
MARS reduces the hidden cost of agentic engineering: unclear intent, unsafe mutation, unverifiable completion, stale docs, and repeated human rescue.
Know whether autonomous work is actually moving product outcomes.
Goals, BDD feature contracts, active plans, tickets, and evidence connect agent work to shipped scenarios instead of activity reports.
- Measure: scenario pass rate, ticket cycle time, false-done count.
- Ask in pilot: did the agent finish a valuable slice or just produce scaffolding?
Reduce review ambiguity and handoff waste.
Every run leaves durable state: what was attempted, which docs constrained it, what tests passed, what failed, and who owns the next action.
- Measure: reviewer rework requests, missing evidence, repeated discovery.
- Ask in pilot: could another engineer resume without reading the chat?
Keep autonomy inside operator-controlled boundaries.
Local inference, explicit tool allowlists, trust levels, guardrails, secret scanning, and blast-radius checks make mutation governable.
- Measure: policy blocks, secret-scan findings, unapproved network dependency.
- Ask in pilot: did safety block bad behavior before code landed?
Avoid opaque vendor spend and hidden learning loops.
The default path uses local open models and repo-local telemetry. Optional integrations stay explicit, and quality signals are visible as artifacts.
- Measure: local run cost, intervention trend, repeated failure categories.
- Ask in pilot: did each failure produce a reusable improvement target?
Lead timeBrief to evidence-backed ticket completion
ContainmentBlocked unsafe operations before mutation
TruthCompletion claims backed by tests, traces, docs, release notes
LearningRepeat failures routed to prompts, skills, guardrails, tools, or model config
The solution
Runtime plus operating model.
The binary runs the automation. The harness tells agents how to use it. Target repos receive the same discipline in a compact, project-owned form.
Data controlOpen-weight models run locally by default; optional external integrations are explicit.
Completion truthDone means BDD scenario evidence, docs checked, release state updated, and traceable handoff.
Governed mutationRoles, trust, tool allowlists, guardrails, and blast-radius limits constrain what agents can change.
Reusable learningTelemetry becomes improvement work instead of another tribal-memory note.
System map
Four surfaces, clear ownership.
The most important adoption concept is the separation between the software factory, the runtime binary, the generated target harness, and the product being built.
Selected surface
Foundation harness
The MARS source repository owns the operating doctrine, generated target defaults, release discipline, product specifications, role registry, and foundation validation evidence.
- Owns source operating model and generated target doctrine.
- Classifies findings as foundation-owned, deployed-owned, mixed, or evidence-only.
- Does not become the target of its own agents during active target runs.
Operating model
Intent becomes evidence.
MARS turns a goal into behavior, tickets, validation, release state, and feedback that remain visible in the repo.
1
Goals
Define outcomes and tradeoffs.
2
BDD contracts
Define behavior and done.
3
Active plan
Ranks failing scenarios.
4
Tickets
Scope one walking-skeleton slice.
5
Roles execute
Engineer, QA, Dogfood, Release.
6
Evidence
Tests, traces, commits, releases.
7
Telemetry
Scores and failures improve the system.
BDD defines done
Feature contracts document business logic, workflow branches, state transitions, validations, permissions, scoring behavior, routing rules, and user-visible outcomes.
Walking skeleton defines the slice
Agents implement the thinnest real end-to-end path that proves the next failing scenario, rather than widening scope or shipping scaffold-only work.
Evidence closes the loop
Completion claims require repo-visible proof: tests, dogfood evidence, quality scores, traces, release notes, and clear ownership of any remaining blocker.
Concept library
A stack, not a feature.
Use the cards below as the first-pass mental model. Each concept starts with the executive meaning, then expands into the engineering behavior that makes it real.
The glossary prevents teams from blurring the lines between MARS source work, runtime defects, generated target doctrine, and product backlog work.
Key terms include foundation harness, runtime substrate, deployed harness, target project, mirrored doctrine, universal tool surface, skills, and failure ownership classification.
Source files declare which docs constrain them. Before a code change is complete, agents read those docs, update or verify them, then run the audit.
DocSync connects code, BDD contracts, design decisions, product specs, role guidance, generated target defaults, and release evidence through top-of-file metadata.
The harness records terminal outcomes, guardrail blocks, no-ops, timeouts, human follow-up, trace pace, dogfood findings, scores, and stale work.
Triage routes patterns to prompt, skill, process, guardrail, context, inference, manifest, tool policy, or foundation telemetry before creating tickets.
Planner, Engineer, Reviewer, Maintainer, End-to-End Tester, and Orchestrator domains group memory and responsibility while executable manifest roles remain explicit.
CEO owns goals, COO owns plans and BDD contracts, CTO owns technical tickets, Engineer implements, QA reviews, Dogfood validates, Release Manager versions, and Janitor keeps state truthful.
Tools mutate or inspect state through allowlists and trust policy. Skills teach compact workflows but do not grant authority.
The same universal tool surface is exposed through role runs,
mars tools run, and MCP so external AI clients can
use governed operations without shell folklore.
Observer, contributor, and autonomous trust levels determine what a role may do. Guardrails block unsafe writes, destructive commands, secret leaks, and misleading completion.
Policy is enforced at tool execution, not only in prompts. Workspace hygiene, dependency sync, ticket lifecycle, validation, and DocSync gates keep mutations bounded and auditable.
The harness manages llama.cpp as a subprocess, stores model weights outside the repo, detects hardware, and routes roles by model tier.
OpenAI-compatible endpoints and Ollama overrides can be evaluated explicitly, but default model promotion requires harness-specific benchmark evidence and pinned artifacts.
Non-release semantic commits are followed by generated version and changelog updates. Source releases build and verify local assets before optional GitHub mirroring.
Target repos inherit release-note discipline, while MARS source has extra binary
publication rules for mars assets.
Drill-down workbench
Translate the core terms.
Each drill-down translates a MARS concept into the problem it solves, the mechanism behind it, and the evidence a pilot should produce.
Selected drill-down
BDD operating model
Agent work is valuable only when it proves an intended product behavior. MARS turns goals into BDD contracts, plans, tickets, validation evidence, and release notes.
Problem it solves
Agents can complete tasks that look busy but do not ship the user-visible capability leadership asked for.
Adoption value
Delivery leaders can ask whether a scenario passed, not whether an agent produced a large diff.
How it works
Goals define outcomes, BDD contracts define behavior, the active plan ranks failing scenarios, and tickets implement the next walking-skeleton slice.
Proof in a pilot
Pick one product slice and require the final claim to cite a BDD scenario, validation command, ticket state, and release-note entry.
Watch for:
False-done tickets, scenario evidence gaps, and enabler work described as shipped product value.
Self-reflective telemetry
Telemetry feeds improvement.
Scores are not vanity metrics. They are control signals that tell the harness where to inspect: prompt quality, guardrail calibration, missing skills, tool policy, model configuration, stale ticket flow, or generated target guidance.
- Raw telemetry remains local by default in per-repo SQLite.
- Foundation telemetry is opt-in and aggregate-only; its minimized payload does not make transport anonymous.
- Target-owned failures become target work; foundation-owned failures stay foundation evidence.
- Quality scores export to
docs/QUALITY_SCORE.mdso agents can see current readiness.
Trace
Score
Improvement target
What a target repo receives
What the target receives.
mars init creates a repo-owned operating surface so agents, humans, and external
AI clients all know how to plan, execute, review, validate, release, and improve the product.
AGENTS.mdfirst-read map
.harness/manifest.yamlroles, tools, triggers, models
.harness/roles/role prompts
.harness/guardrails/policy inputs
.harness/skills/reusable workflows
.harness/knowledge/context routing
docs/goals/active and superseded goals
docs/features/BDD contracts
docs/exec-plans/one active plan
docs/tickets/backlog to done lifecycle
docs/QUALITY_SCORE.mdrepo-visible grade
VERSION + CHANGELOG.mdrelease state
Important ownership rule
Existing target files remain user-owned. mars upgrade
fills missing defaults without overwriting deliberate local
policy. Source-only MARS release mechanics stay in the foundation
harness.
Adoption proposal
Pilot first. Autonomy later.
The adoption path should prove value, safety, and fit against one representative repository before wider rollout. The goal is to make the software factory more explicit while preserving local governance. For reader-specific steps, use the MARS adoption guide; for control evidence, use security and governance.
Orientation and safety review
Map operating constraints to MARS tenets, trust levels, guardrails, source control policy, and telemetry boundaries.
Read-only target assessment
Run doctor, dry-run role context, scan output, generated harness review, and DocSync fit without mutating product code.
Contributor pilot
Select one non-critical repo and one bounded feature or repair path. Require human-triggered runs, review, and visible evidence.
Operationalize learning
Evaluate scores, guardrail blocks, human follow-up, release notes, and team feedback before expanding roles or autonomy.
Pilot passes when
One bounded product slice moves from brief to evidence-backed completion with no unreviewed repo mutation.
Expand when
Reviewers can trust the evidence trail, safety blocks are mostly correct, and repeated failures become specific improvement targets.
Pause when
The agent repeatedly claims false done, bypasses policy, needs constant human rescue, or creates target backlog noise from foundation-owned defects.
Glossary
Search concepts.
These definitions are compressed for briefing use. The canonical wording remains in the MARS docs.
Source material
Source docs.
This app is a repo-hosted static artifact. The paths below name the MARS repository documents used as source material; the app does not need them to render.
README.md
ARCHITECTURE.md
docs/product-specs/vision.md
docs/product-specs/product-surface.md
docs/design-docs/harness-glossary.md
docs/design-docs/index.md
docs/design-docs/implementation-language.md
docs/design-docs/pipeline-engine.md
docs/design-docs/dashboard.md
docs/design-docs/code-documentation-map.md
docs/design-docs/cli-tool-skill-sync.md
docs/design-docs/dogfood-and-decisions.md
docs/design-docs/scoring-system.md
docs/design-docs/validation-matrix-gating.md
docs/design-docs/foundation-deployed-harness-architecture.md
docs/design-docs/delivery-operating-model.md
docs/design-docs/documentation-sync-architecture.md
docs/design-docs/self-reflective-telemetry.md
docs/design-docs/tools-glossary.md
docs/design-docs/guardrails.md
docs/design-docs/local-inference.md
docs/design-docs/release-versioning.md
docs/roles/ROLES.md