MARS Roles And Agents Guide

Mental Model

A role is the executable unit you run with mars run or schedule through start and serve. A domain is the stable vocabulary for what kind of work the role does. A mode is the specific reason the role is running right now.

Role key

The manifest key, such as engineer, qa, or release-manager. It is the name you pass to mars run and the name recorded in jobs, traces, scores, and trust.

Domain

One of the six canonical operating groups: planner, engineer, reviewer, maintainer, end-to-end-tester, or orchestrator.

Mode

Lower-kebab-case purpose inside a domain, such as ticket-delivery, quality-review, release-management, or dispatch-routing.

Authority

Tools, trust, guardrails, and workflow gates decide what a role may actually do. A domain label never grants authority by itself.

User rule: change the manifest when you want executable behavior to change; change docs/roles/ROLES.md when you want the human and agent inventory to stay truthful.

Canonical Domains

Domain	Responsibility	Boundary
`planner`	Goals, strategy, scenario order, architecture direction, and ticket shape.	Does not implement product code or claim delivery complete.
`engineer`	Bounded source, test, documentation, and deterministic repair changes.	Must respect ticket, BDD, guardrail, test, DocSync, release, and git gates.
`reviewer`	Behavior, evidence, security posture, tool exposure, and completion truth.	Does not hide defects by redefining acceptance criteria.
`maintainer`	Dependencies, release state, documentation hygiene, scores, and routine upkeep.	Does not change product direction without planner input.
`end-to-end-tester`	Real build, run, user, dogfood, and agent-path validation evidence.	Does not turn failed validation into success by changing the claim.
`orchestrator`	Queue health, dispatch routing, stuck-work recovery, and ticket hygiene.	Does not hide blocked work or start random backlog over active truth.

Default Roles

Generated target harnesses start with explicit roles. They are starter defaults, not untouchable built-ins. Users can edit prompts, schedules, tools, model tiers, guardrails, and knowledge routes to fit the target repo.

Role	Domain / mode	User-facing job
`ceo`	`planner` / `strategy`	Owns vision, active goals, scope choices, and strategy tradeoffs.
`head-of-strategy`	`planner` / `strategy-advisory`	Advises on strategy memos, executive narrative, tradeoffs, and goal conflict.
`coo`	`planner` / `execution-planning`	Owns active plans, BDD feature contracts, scenario schedules, and current failing scenarios.
`cto-weekly`	`planner` / `technical-planning`	Turns scenario intent into architecture-aware implementation tickets.
`engineer`	`engineer` / `ticket-delivery`	Completes one bounded ticket with tests, docs, evidence, and commits.
`qa`	`reviewer` / `quality-review`	Checks implementation evidence against tickets, BDD contracts, and regression risk.
`security`	`reviewer` / `security-review`	Reviews security posture, secrets, sensitive tool use, and remediation quality.
`dependency-manager`	`maintainer` / `dependency-maintenance`	Keeps package and dependency work small, tested, and reversible.
`release-manager`	`maintainer` / `release-management`	Maintains versions, changelog, tags, release assets, and release blockers.
`dogfood`	`end-to-end-tester` / `dogfood-validation`	Runs real setup, build, execution, and user-path validation.
`pipeline-fixer`	`engineer` / `pipeline-repair`	Repairs failed build, test, or workflow paths through bounded changes.
`orchestrator`	`orchestrator` / `dispatch-routing`	Chooses the next valid role after terminal dispositions and stops unclear loops.
`janitor`	`orchestrator` / `ticket-hygiene`	Finds stale, blocked, misleading, or idle ticket state and routes cleanup.

Source-Only Foundation Role

The MARS source repo also has foundation-maintainer, a source-only manual role for maintaining the software factory. It is not generated into target harnesses and is rejected for ordinary target repos.

Routing And Dispatch

New generated target manifests use orchestration_mode: dispatch. In dispatch mode, a role completes by recording a disposition. The runtime sends that structured packet to orchestrator, which picks one valid next manifest role or stops with a reason.

Normal product delivery spine

ceo
coo
cto-weekly
engineer
qa
security
dependency-manager
release-manager

The Orchestrator sits between terminal jobs and uses dispositions, role manuals, active plans, tickets, and loop guards before scheduling follow-up.

Support and recovery roles

head-of-strategy
dogfood
pipeline-fixer
janitor

These roles advise, validate, repair, or clean state. They do not replace the delivery owners for strategy, planning, implementation, review, and release.

Legacy compatibility

orchestration_mode: legacy
roles:
  engineer:
    then: [qa]
    idle_then: [janitor]

Legacy chains remain supported for repos that deliberately keep them, but dispatch mode is the generated default.

Disposition Handoff Fields

Roles can provide handoff and feedback objects when they call job_disposition_record. Those fields tell Orchestrator who should act next, what evidence exists, which blocker remains, and what correction is being requested.

Authority: Tools, Trust, Models, And Guardrails

A role's prompt explains how it should think. The manifest and runtime policy decide what it can actually do.

Control	Where users configure or inspect it	Effect
Tool allowlist	`.harness/manifest.yaml`, `mars tools list`	Determines which deterministic capabilities the role can call.
Trust level	`.harness/manifest.yaml`, `mars trust`, `mars trust set`	Controls observer, contributor, or autonomous authority.
Model tier	`.harness/manifest.yaml`, `.harness/model-overrides.yaml`	Routes the role to fast, reasoning, coding, local, cloud, or explicit provider choices.
Guardrails	`.harness/guardrails/*.yaml`, role `guardrails` lists	Blocks or advises on risky writes and tool behavior.
Knowledge routes	`.harness/knowledge/*.yaml`	Points the role at durable docs only when a task needs them.
Scores	`mars scores`, `docs/QUALITY_SCORE.md`	Tracks outcome quality and informs future trust and intervention work.

Safe default: start custom roles at observer or contributor with narrow tools, then expand authority only after repeated successful evidence.

Role Registry

docs/roles/ROLES.md is the checked inventory that users and agents can review without parsing the whole harness. It should mirror the executable manifest and record custom target roles explicitly.

Registry column	Why it matters
`Origin`	Distinguishes generated defaults, custom target roles, and source-only foundation roles.
`Domain` and `Mode`	Show the role's operating memory and purpose.
`Trigger sources` and `Schedule`	Explain how work enters the queue.
`Tools`	Make tool exposure reviewable before the role runs.
`Trust level`	Shows autonomy level and mutation authority.
`Guardrails`	Names the policy envelope around the role.
`Model routing`	Explains whether the role favors fast, reasoning, or coding behavior.
`Scoring signals`	Defines the outcome signals used to judge role health.
`Escalation behavior`	Tells users how blocked or risky work should be surfaced.

mars doctor --repo /path/to/repo

doctor reports role-registry drift so users can repair stale rows, missing manifest roles, invalid domains, or outdated routing metadata.

Customize Roles Safely

Role customization is expected. The key is to keep runtime truth, documentation, and safety policy aligned in the same change. For exact manifest fields, trust values, schedules, and routing modes, open the Bundle And Manifest Reference.

Add a role

mkdir -p .harness/roles
edit .harness/roles/docs-writer.md
edit .harness/manifest.yaml
edit docs/roles/ROLES.md
mars doctor --repo .

Add the manifest entry, choose domain and mode, grant narrow tools, set trust, and add a registry row with Origin set to custom.

Tune a role

edit .harness/roles/engineer.md
edit .harness/manifest.yaml
mars run engineer --repo . --dry-run
mars doctor --repo .

Use dry run to inspect assembled context before allowing the role to call a model or mutate files.

Reduce blast radius

mars trust set engineer . observer --reason "Investigating unsafe behavior"
mars guardrails secret-scan --repo .
mars run engineer --repo . --dry-run --no-init

Trust can be lowered while you investigate prompt, tool, guardrail, or ticket problems.

Manifest Example

roles:
  docs-writer:
    prompt: roles/docs-writer.md
    domain: maintainer
    mode: documentation-maintenance
    model: reasoning
    trust_level: contributor
    max_turns: 30
    knowledge:
      - knowledge/context-glossary.yaml
    tools:
      - file_read
      - file_write
      - grep
      - docsync_audit
      - git_status
      - git_diff
      - git_commit

Operate Roles

User task	Command	Expected use
Preview a role prompt	`mars run engineer --repo /path/to/repo --dry-run`	Inspect assembled context without model calls.
Inspect a repo without scaffolding	`mars run engineer --repo /path/to/repo --dry-run --no-init`	Check missing-harness behavior safely.
Run one mutating role	`mars run qa --repo /path/to/repo --execution-profile host --acknowledge-host-execution`	Targeted manual execution with current-user host authority.
Run the scoped lifecycle	`mars start --repo /path/to/repo --execution-profile host --acknowledge-host-execution`	Initialize, register, reconcile, seed, and dispatch work for one repo.
Run multi-repo service	`mars serve --addr 127.0.0.1:9091 --execution-profile host --acknowledge-host-execution`	Persistent mutating scheduler, dashboard, worker pool, webhooks, and surveys.
Check role health	`mars scores --repo /path/to/repo`	View outcome scores per role.
Change autonomy	`mars trust set engineer /path/to/repo contributor --reason "Ticket-bound edits approved"`	Record an explicit trust decision.

These agent entry points default to observer, which independently caps progressive role trust and blocks every mutating tool. Host acknowledgement does not upgrade trust; isolated is unavailable.

Troubleshooting

Symptom	Likely cause	Fix
Role is unavailable	The key is missing from `.harness/manifest.yaml`.	Run `mars doctor --repo .` and add or correct the manifest role.
Role has no tools	Strict tool allowlists require explicit tool configuration.	Add the smallest necessary `tools` list to the role.
Reviewer changed product code unexpectedly	Prompt, trust, and tools allow mutation.	Lower trust, remove write tools, and narrow guardrails for that role.
Orchestrator loops	Disposition, handoff, or feedback data is ambiguous.	Inspect recent traces and ask the prior role for a precise `next_need`, blocker, and evidence list.
Custom role is missing from docs	Registry drift after manifest edit.	Add a `custom` row to `docs/roles/ROLES.md` and rerun `mars doctor`.
Role context is huge or noisy	Prompt contains long doctrine instead of route hints.	Move durable content to docs and route it through `.harness/knowledge/*.yaml`.

Understand the people in the machine before you let them work.

Mental Model

Role key

Domain

Mode

Authority

Canonical Domains

Default Roles

Source-Only Foundation Role

Routing And Dispatch

Normal product delivery spine

Support and recovery roles

Legacy compatibility

Disposition Handoff Fields

Authority: Tools, Trust, Models, And Guardrails

Role Registry

Customize Roles Safely

Add a role

Tune a role

Reduce blast radius

Manifest Example

Operate Roles

Troubleshooting