# Bundle Reference

A bundle is the `.harness/` directory in your repository. It contains everything MARS needs to operate on your codebase.

The primary user-facing site reference is
[bundle-reference.html](bundle-reference.html). This Markdown file remains a
compact repo-readable companion.

`mars init` also creates repo-level release files (`VERSION` and
`CHANGELOG.md`) plus `docs/design-docs/release-versioning.md`. Those files live
outside `.harness/` because semantic versioning and patch notes belong to the
target project, not just the harness bundle.

## Directory Structure

```
.harness/
|-- manifest.yaml       # Required: role definitions and metadata
|-- metadata.yaml       # Generated harness version and drift metadata
|-- roles/              # Role prompt files (Markdown)
|   |-- engineer.md
|   `-- pipeline-fixer.md
|-- guardrails/         # Guardrail rule files (YAML)
|   `-- safety.yaml
|-- knowledge/          # Lightweight context route files
|   |-- context-glossary.yaml
|   `-- api-conventions.yaml
`-- skills/             # Reusable workflow instructions
```

## manifest.yaml

The manifest is the entry point. It declares the bundle name and all roles.
The roles generated by `mars init` are starter agents, not a fixed or
perfect operating team. End users can edit prompts, add roles, remove roles,
change schedules, change chains, restrict tools, add guardrails, or point roles
at different knowledge routes.

```yaml
name: my-project
description: MARS bundle for my-project
orchestration_mode: dispatch

roles:
  pipeline-fixer:
    prompt: roles/pipeline-fixer.md
    domain: engineer
    mode: pipeline-repair
    model: ""
    trust_level: contributor
    max_turns: 40
    tools:
      - file_read
      - file_write
      - shell_exec
      - grep
    guardrails:
      - guardrails/safety.yaml
    knowledge:
      - knowledge/context-glossary.yaml
    triggers:
      - workflow_run.conclusion == "failure"
```

### Top-level fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Bundle identifier. Used in job IDs and logs. |
| `description` | No | Human-readable description. |
| `orchestration_mode` | No | Empty, `legacy`, or `dispatch`. New generated manifests use `dispatch`. |
| `roles` | Yes | Map of role name to role config. At least one required. |

### Role configuration

| Field | Required | Description |
|-------|----------|-------------|
| `prompt` | Yes | Path to the role's markdown prompt file, relative to `.harness/`. |
| `domain` | No | Canonical operating domain: `planner`, `engineer`, `reviewer`, `maintainer`, `end-to-end-tester`, or `orchestrator`. Existing manifests without this field remain valid. |
| `mode` | No | Lower-kebab-case purpose inside the domain, such as `ticket-delivery`, `quality-review`, or `pipeline-repair`. |
| `model` | No | Model hint (e.g. `gemma-4-27b`). Empty string uses the default. |
| `trust_level` | No | `observer`, `contributor`, or `autonomous`. Invalid values fail bundle load. |
| `tools` | No | List of tools the role is allowed to use. |
| `guardrails` | No | List of guardrail files to load for this role. |
| `knowledge` | No | List of knowledge files to inject into the context. |
| `triggers` | No | Events that activate this role. |
| `then` | No | Legacy chain targets. Every named role must exist. |
| `idle_then` | No | Legacy idle chain targets. Every named role must exist. |
| `schedule` | No | `hourly`, `daily`, `weekly`, `monthly`, or a 5-field cron expression. |
| `max_turns` | No | Maximum LLM round trips for this role. |
| `context_size` | No | Optional token-window override. Use sparingly. |

### Available tools

These built-in tools are available to both the foundation harness and deployed
harness manifests when a role allowlist includes them.

| Tool | Description |
|------|-------------|
| `file_read` | Read file contents |
| `file_write` | Write or create files |
| `shell_exec` | Execute shell commands |
| `mars_cli` | Read exhaustive CLI reference or execute `mars` commands with structured argv; mirrored for foundation and deployed harnesses |
| `grep` | Search file contents with regex |
| `ticket_create` | Create or update deduped ticket files |
| `record_decision` | Persist durable learning and decision notes |
| `tool_create` | Scaffold a new built-in Go tool under `internal/tools/`; implementation and registration still require follow-up edits and tests |
| `persona_create` | Scaffold a repo-local persona manual, role prompt, registry row, and optional manifest role |
| `git_status` | Inspect repository status |
| `git_diff` | Inspect diffs |
| `git_commit` | Stage files and create a commit |
| `git_push` | Push commits |

### Trigger syntax

Triggers use the format `<event>.<field> == "<value>"` or shorthand names:

```yaml
triggers:
  - workflow_run.conclusion == "failure"   # CI failure
  - schedule.weekly                        # Weekly cron
  - schedule.daily                         # Daily cron
  - workflow_dispatch                      # Manual trigger
  - ticket.assigned                        # Ticket assigned
  - ticket.blocked                         # Blocked ticket needs repair
  - alert.fired                            # Alert triggered
```

GitHub compatibility triggers may be configured explicitly, but strict trunk is
the default delivery model: roles commit directly to `main` and push after each
completed step.

## Role Prompts

Role prompts are markdown files containing the system instructions for the agent. They should include:

1. **Identity** - who the agent is and what it does
2. **Workflow** - step-by-step instructions
3. **Constraints** - what the agent must not do
4. **Output format** - expected response structure

The shipped prompts are examples and defaults. They are intentionally
user-owned once copied into a target repo, because the best agent shape depends
on the project's domain, risk tolerance, commands, and team habits.

`mars upgrade` preserves existing role prompts. It only fills in missing
starter prompts, so a harness update cannot silently erase local agent tuning.
To adopt newer default prompt wording, initialize a temporary repo with the new
binary and copy the specific changes you want.

See `examples/roles/` for complete starter examples.

## Guardrails

Guardrail files define safety rules enforced during execution. See [guardrails-guide.md](guardrails-guide.md) for the full format.

```yaml
rules:
  - id: no-secrets
    name: No hardcoded secrets
    severity: hard
    scope: global
    pattern: '(?i)(password|secret|api_key)\s*[:=]\s*["\x27][^"\x27]{8,}'
    message: Do not hardcode secrets in source files
```

## Knowledge Routes

Knowledge files are small YAML route maps injected into the role's context during assembly. Use them for:

- Architecture overviews the agent needs to respect
- API conventions and naming standards
- Domain-specific terminology

Keep knowledge files concise. They should usually point to files such as `AGENTS.md`, `docs/design-docs/context-glossary.md`, or a relevant design doc instead of embedding the full content. The context assembly engine (MH-004) manages token budgets automatically.

```yaml
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
```

## Example: Minimal Bundle

```yaml
name: my-app
description: Minimal harness bundle
roles:
  pipeline-fixer:
    prompt: roles/pipeline-fixer.md
    tools:
      - file_read
      - file_write
      - shell_exec
      - grep
    triggers:
      - workflow_run.conclusion == "failure"
```

With a single file at `.harness/roles/pipeline-fixer.md` containing the role prompt.