MARS Bundle And Manifest Reference

Directory Layout

mars init creates .harness/ and the surrounding repo-owned operating docs. The bundle itself is the executable agent configuration; release files and operating docs live beside it because they belong to the target project, not only to the agent runtime.

.harness/
|-- manifest.yaml
|-- metadata.yaml
|-- roles/
|   |-- engineer.md
|   |-- qa.md
|   `-- orchestrator.md
|-- guardrails/
|   `-- safety.yaml
|-- knowledge/
|   `-- context-glossary.yaml
|-- skills/
|   `-- self-improvement/
|       `-- SKILL.md
|-- integrations.example.yaml
|-- integrations.yaml
|-- model-overrides.yaml
|-- .env.example
`-- .env.local

Path	Purpose	Commit?
`manifest.yaml`	Required role and orchestration entrypoint.	Yes.
`metadata.yaml`	Generated harness version and drift metadata.	Yes.
`roles/*.md`	Role prompt manuals.	Yes, user-owned after init.
`guardrails/*.yaml`	Role-attached policy rules.	Yes.
`knowledge/*.yaml`	Context routing from situations to repo docs.	Yes.
`skills/*/SKILL.md`	Reusable procedures for recurring work.	Yes.
`integrations.example.yaml`	Documented opt-in integration template.	Yes.
`integrations.yaml`	Real target integration config when opted in.	Only when it contains no secrets.
`model-overrides.yaml`	Repo, tier, or role model routing overrides.	Yes when policy should travel with the repo.
`.env.example`	Credential variable names without values.	Yes.
`.env.local`	Local secret values.	Never.

Manifest Contract

.harness/manifest.yaml is required. MARS refuses to load a bundle with no name, no roles, missing role prompts, invalid trust levels, invalid schedules, or role chains that point at undefined roles.

name: my-project
description: Starter autonomous AI pipeline for my-project
orchestration_mode: dispatch

roles:
  engineer:
    prompt: roles/engineer.md
    domain: engineer
    mode: ticket-delivery
    model: coding
    trust_level: contributor
    max_turns: 100
    schedule: "0 0,6,12,18 * * 1-5"
    knowledge: [knowledge/context-glossary.yaml]
    guardrails: [guardrails/safety.yaml]
    tools: [file_read, file_write, shell_exec, mars_cli, grep, docsync_audit, git_status, git_diff, git_commit]
    triggers:
      - ticket.assigned

Top-level field	Required?	User behavior
`name`	Yes	Stable bundle identifier used in logs, jobs, and generated context.
`description`	No	Human-readable description of the target harness.
`orchestration_mode`	No	Use `dispatch` for new targets. Empty and `legacy` are accepted for compatibility.
`roles`	Yes	Map of executable role keys. At least one role is required.

Role Fields

Role keys are the names users pass to mars run <role>. Keep keys stable once jobs, scores, trust, and telemetry refer to them.

Role field	Required?	Accepted values or behavior
`prompt`	Yes	Path relative to `.harness/`. File must exist and be non-empty.
`domain`	No	Canonical domain such as `planner`, `engineer`, `reviewer`, `maintainer`, `end-to-end-tester`, or `orchestrator`.
`mode`	No	Lower-kebab-case reason for the role, such as `ticket-delivery` or `quality-review`.
`model`	No	Model tier or hint. Prefer `fast`, `reasoning`, or `coding` so routing can adapt.
`trust_level`	No	`observer`, `contributor`, or `autonomous`. Invalid values fail bundle load.
`tools`	No	Tool allowlist. Empty means the role cannot use tools.
`guardrails`	No	Files under `.harness/` loaded for that role.
`knowledge`	No	Knowledge route files under `.harness/knowledge/` or other harness-relative paths.
`triggers`	No	Event expressions or shorthand trigger names such as `ticket.assigned`.
`then`	No	Legacy chain targets. Every named role must exist.
`idle_then`	No	Legacy chain targets used when a role has no useful next action. Every named role must exist.
`schedule`	No	`hourly`, `daily`, `weekly`, `monthly`, or a standard 5-field cron expression.
`max_turns`	No	Maximum LLM round trips for that role. Use to bound recurring jobs.
`context_size`	No	Token window override. Use sparingly; model routing usually owns context size.

Routing Modes

New generated manifests use orchestration_mode: dispatch. Dispatch mode routes terminal dispositions through the Orchestrator instead of exposing legacy then chains as the next hop.

Dispatch mode

Use for new targets. Roles finish with evidence and disposition; Orchestrator selects the next appropriate role.

Legacy mode

Accepted for older manifests. then and idle_then chains are shown directly as handoffs.

Manual runs

mars run engineer --repo /path/to/repo executes one named role regardless of schedule.

Schedules

Use named presets for simple cadence or 5-field cron for exact recurring runs. Second-resolution cron is not accepted.

Role Prompts

Prompt files are Markdown manuals for roles. MARS reads the file named by the role's prompt field and rejects empty or missing prompt files.

Prompt shape

# Engineer

## Role Contract
Describe the role's purpose, ownership, and stop conditions.

## Workflow
List the steps the role follows during a job.

## Evidence
Name what the role must verify before claiming completion.

User rule

Keep prompts focused. Route long product context through knowledge files and durable docs instead of pasting everything into a role prompt.

Upgrade behavior

mars upgrade preserves existing role prompts and fills only missing starter prompts.

Tool Allowlists

Tools are capabilities a role may use. The manifest does not grant unlimited power by default; each role names the tools it needs. Trust level and built-in policy still constrain tool behavior.

Tool family	Examples	User guidance
Read/search	`file_read`, `grep`, `code_search`, `code_snippet`	Safe starting point for observer or reviewer roles.
Mutation	`file_write`, `dependency_sync`, `git_commit`, `git_push`	Grant only to roles allowed to change the target repo.
MARS operations	`mars_cli`, `docsync_audit`, `workspace_hygiene`	Useful for roles that must verify harness and repo state.
Meta tooling	`tool_create`, `persona_create`, `record_decision`	Use when the role may evolve harness capability or durable doctrine.
Release	`release_orchestrate`, `github_release_status`, `git_release_guard`	Reserve for release-manager or foundation-maintainer style roles.

Run mars tools list --json for the current installed tool registry, and open the Tools And MCP Guide for trust and external-client behavior.

Guardrails

Role guardrails entries load YAML files from the harness. Hard rules block matching writes; advisory rules appear in role context. Use the dedicated reference for exact matching semantics.

roles:
  engineer:
    guardrails:
      - guardrails/safety.yaml

rules:
  - id: no-hardcoded-secrets
    name: No hardcoded secrets
    severity: hard
    scope: global
    pattern: '(?i)(password|secret|api_key|token)'

Open the Guardrails Reference

Knowledge Routes

Knowledge routes map situations to durable docs. They are loaded from files named in the role's knowledge list.

routes:
  - when: release planning, semantic versioning, changelog, patch notes, or tags
    paths: VERSION, CHANGELOG.md, docs/design-docs/release-versioning.md
  - when: project terminology, domain concepts, architecture vocabulary, naming, or unclear intent
    paths: AGENTS.md, docs/design-docs/context-glossary.md

Good route files point outward: keep the route compact and point to repo docs. Do not turn knowledge YAML into a second giant prompt.

Skills

Skills live under .harness/skills/<name>/SKILL.md. They teach recurring procedures, but they do not grant tool authority. Tool access still comes from the manifest and runtime trust policy.

Use a skill for

Recurring procedures such as release publication, private release auth, validation replay, dependency checks, or persona design.

Use a guardrail for

Rules that must block or warn regardless of role memory.

Use a tool for

Repeated deterministic actions that need structured inputs, outputs, validation, and policy.

Use a doc for

Durable product, architecture, or operating context a role should read when relevant.

Generated Defaults And Upgrade Behavior

Generated roles are starter defaults, not a permanent claim about the best team for every project. After init, target owners can edit prompts, add roles, remove roles, change schedules, restrict tools, attach guardrails, and adjust knowledge routes.

Command	Bundle behavior	Preservation rule
`mars init --repo /path/to/repo`	Creates the initial bundle and operating docs.	Use in a git checkout and review generated files before committing.
`mars register`, `scan`	Auto-initialize a missing target harness.	Review generated target files before continuing.
`mars start`, `run`	Observer is the default and rejects a missing target before writes; acknowledged host may initialize.	Use `run --dry-run --no-init` for the explicit missing-harness preview, or pass `--execution-profile host --acknowledge-host-execution` only when current-user host mutation is intended.
`mars upgrade --repo /path/to/repo`	Fills missing defaults after a MARS upgrade.	Preserves existing manifest, prompts, knowledge routes, guardrails, docs, tickets, and plans.
`mars eject --repo /path/to/repo`	Previews removal of the deployed harness and associated per-repo DB.	Requires explicit apply and confirm flags for deletion.

Recipes

Preview role context after manifest edits

mars run engineer --repo /path/to/target-repo --dry-run

Validate machine and bundle health

mars doctor --repo /path/to/target-repo --json
mars tools list --json

Inspect generated changes before committing

git -C /path/to/target-repo status --short
git -C /path/to/target-repo diff -- .harness AGENTS.md docs

Adopt newer starter prompt wording deliberately

tmp=$(mktemp -d)
git init "$tmp"
mars init --repo "$tmp"
diff -u "$tmp/.harness/roles/engineer.md" /path/to/target-repo/.harness/roles/engineer.md

Troubleshooting

Symptom	Likely cause	Next action
`missing .harness/ directory`	The target was not initialized.	Run `mars init --repo /path/to/repo`.
`manifest ... is missing required field 'name'`	Top-level `name` is absent or empty.	Add a stable bundle name.
`defines no roles`	The `roles` map is empty.	Add at least one role with a prompt.
`invalid orchestration_mode`	Unsupported mode string.	Use `dispatch`, `legacy`, or omit the field.
`invalid trust_level`	Role trust is not one of the supported values.	Use `observer`, `contributor`, or `autonomous`.
`has no prompt path`	Role lacks required `prompt`.	Point to a role Markdown file relative to `.harness/`.
`prompt file ... not found`	The prompt path is wrong or file is missing.	Create the file or fix the path.
`prompt file ... is empty`	The role has no instructions.	Add a role contract, workflow, constraints, and evidence expectations.
`chains to ... but ... is not defined`	`then` or `idle_then` names a missing role.	Add the role or remove the chain target.
`invalid schedule`	Schedule is neither a preset nor a 5-field cron expression.	Use `hourly`, `daily`, `weekly`, `monthly`, or a 5-field cron.
`guardrail file ... not found`	Role references a missing guardrail file.	Create the file or remove the reference.
`knowledge file ... not found`	Role references a missing knowledge route file.	Create the route file or remove the reference.

Understand the files that make a target repo executable by MARS.

Directory Layout

Manifest Contract

Role Fields

Routing Modes

Dispatch mode

Legacy mode

Manual runs

Schedules

Role Prompts

Prompt shape

User rule

Upgrade behavior

Tool Allowlists

Guardrails

Knowledge Routes

Skills

Use a skill for

Use a guardrail for

Use a tool for

Use a doc for

Generated Defaults And Upgrade Behavior

Recipes

Preview role context after manifest edits

Validate machine and bundle health

Inspect generated changes before committing

Adopt newer starter prompt wording deliberately

Troubleshooting