The files MARS adds to your repo.

Directory Structure

mars init creates a target-owned harness plus durable planning, delivery, quality, and release artifacts. For the full ownership, local state, and cleanup map, use the Files And State Reference.

.
|-- AGENTS.md
|-- VERSION
|-- CHANGELOG.md
|-- .harness/
|   |-- manifest.yaml
|   |-- metadata.yaml
|   |-- roles/
|   |-- skills/
|   |-- guardrails/
|   +-- knowledge/
+-- docs/
    |-- goals/
    |-- features/
    |-- tickets/
    |-- exec-plans/
    |-- design-docs/
    |-- references/
    +-- QUALITY_SCORE.md

Manifest

.harness/manifest.yaml is the entrypoint for executable agent behavior. It names roles, prompts, canonical domains, modes, model tiers, tool allowlists, guardrails, knowledge routes, and triggers. For exact field validation, routing modes, schedules, generated defaults, and manifest troubleshooting, open the Bundle And Manifest Reference.

name: my-project
description: MARS bundle for my-project

roles:
  engineer:
    prompt: roles/engineer.md
    domain: engineer
    mode: ticket-delivery
    model: coding
    tools:
      - file_read
      - file_write
      - shell_exec
      - grep
      - mars_cli
    guardrails:
      - guardrails/safety.yaml
    knowledge:
      - knowledge/context-glossary.yaml
    triggers:
      - ticket.assigned

Roles

Roles are executable personas with prompts, tools, guardrails, knowledge routes, model tiers, trust levels, scores, and triggers. Generated roles are starter defaults. Target owners should tune them to their product domain and risk tolerance.

Knowledge Routes

Knowledge routes are compact YAML maps that tell MARS which repo docs to include when a role needs specific context. They are the antidote to giant prompts: keep instructions small and route the right durable docs only when relevant.

routes:
  - when: project terminology, domain concepts, architecture vocabulary, naming, or unclear intent
    paths: AGENTS.md, docs/design-docs/context-glossary.md, docs/design-docs/index.md

Guardrails

Guardrails are YAML rules that constrain file writes and tool use. Hard rules block operations; advisory rules become prompt guidance.

rules:
  - id: no-hardcoded-secrets
    name: No hardcoded secrets
    severity: hard
    scope: global
    pattern: '(?i)(password|secret|api_key|token)\s*[:=]\s*["''][^"'']{8,}'
    message: Do not hardcode secrets. Use environment variables or a secrets manager.
    stale_days: -1

Skills

Skills are compact reusable workflows in .harness/skills/<name>/SKILL.md. They guide an agent through recurring judgment-heavy procedures without granting new tool authority. Use skills when a human recovery step repeats, when a process is easy to forget, or when the role prompt would otherwise grow too large.

Operating Model Artifacts

Business Logic Rule

Product rules, state transitions, validations, permissions, scoring/trust behavior, routing rules, release classification, and user-visible outcomes belong in BDD feature contracts before or alongside implementation.

Quality, Scores, Trust, And Release State

Customization Checklist

1. Rename and describe roles for your domain

   Keep role keys stable once automation depends on them.

2. Tune tool allowlists

   Grant mutation only where the role's job requires it.

3. Attach focused guardrails

   Prefer scoped rules over broad global blocks.

4. Add knowledge routes

   Route architecture, API, domain, and style guidance from durable docs.

5. Choose model routing deliberately

   Use local by default, cloud when configured, and overrides for explicit repo or role needs.

6. Keep generated docs alive

   When behavior changes, update the owning docs in the same change.

Upgrade And Eject Behavior

mars update harness --repo ~/my-project

mars eject --repo ~/my-project
mars eject --repo ~/my-project --apply --confirm my-project