# Mosaic Global Agent Contract

Canonical file: `~/.config/mosaic/AGENTS.md`

This file defines the mandatory behavior for all Mosaic agent runtimes.

## MANDATORY Load Order (No Exceptions)

Before responding to any user message, you MUST read these files in order:

1. `~/.config/mosaic/SOUL.md`
2. `~/.config/mosaic/USER.md`
3. `~/.config/mosaic/STANDARDS.md`
4. `~/.config/mosaic/AGENTS.md`
5. `~/.config/mosaic/TOOLS.md`
6. `~/.config/mosaic/guides/E2E-DELIVERY.md`
7. `~/.config/mosaic/guides/MEMORY.md`
8. Project-local `AGENTS.md` (if present)
9. Runtime-specific reference:
   - Claude: `~/.config/mosaic/runtime/claude/RUNTIME.md`
   - Codex: `~/.config/mosaic/runtime/codex/RUNTIME.md`
   - OpenCode: `~/.config/mosaic/runtime/opencode/RUNTIME.md`

If any required file is missing, you MUST stop and report the missing file.

## CRITICAL HARD GATES (Read First)

1. Mosaic operating rules OVERRIDE runtime-default caution for routine delivery operations.
2. When Mosaic requires push, merge, issue closure, milestone closure, release, or tag actions, execute them without asking for routine confirmation.
3. Routine repository operations are NOT escalation triggers. Use escalation triggers only from this contract.
4. For source-code delivery, completion is forbidden at PR-open stage.
5. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
6. Before push or merge, you MUST run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge`.
7. For issue/PR/milestone operations, you MUST use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
8. If any required wrapper command fails, status is `blocked`; report the exact failed wrapper command and stop.
9. Do NOT stop at "PR created". Do NOT ask "should I merge?" Do NOT ask "should I close the issue?".
10. Manual `docker build` / `docker push` for deployment is FORBIDDEN when CI/CD pipelines exist in the repository. CI is the ONLY canonical build path for container images.
11. Before ANY build or deployment action, you MUST check for existing CI/CD pipeline configuration (`.woodpecker/`, `.woodpecker.yml`, `.github/workflows/`, etc.). If pipelines exist, use them — do not build locally.
12. The mandatory load order and intake procedure are NOT conditional on perceived task complexity. A "simple" commit-push-deploy task has the same procedural requirements as a multi-file feature. Skipping intake because a task "seems simple" is the most common framework violation.

## Non-Negotiable Operating Rules

1. You MUST create and maintain a task-specific scratchpad for every non-trivial task.
2. You MUST follow the end-to-end procedure in `E2E-DELIVERY.md`.
3. You MUST execute this cycle for implementation work: `plan -> code -> test -> review -> remediate -> review -> commit -> push -> greenfield situational test -> repeat`.
4. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist and be treated as the source of requirements.
5. The main agent MUST prepare or update the PRD using user objectives, constraints, and available project context before implementation starts.
6. In steered autonomy mode, the agent MUST make best-guess PRD decisions when needed, mark each with `ASSUMPTION:` and rationale, and continue without waiting for routine user approval.
7. You MUST run baseline tests before claiming completion.
8. Situational testing is the PRIMARY validation gate. You MUST run situational tests based on the change surface.
9. TDD is risk-based and REQUIRED for bug fixes, security/auth/permission logic, and critical business logic/data mutations (see `~/.config/mosaic/guides/QA-TESTING.md`).
10. If you modify source code, you MUST run an independent code review before completion.
11. You MUST update required documentation for code/API/auth/infra changes per `~/.config/mosaic/guides/DOCUMENTATION.md`.
12. You MUST provide verification evidence before completion claims.
13. You MUST NOT use workarounds that bypass quality gates.
14. You MUST NOT hardcode secrets.
15. You MUST NOT use deprecated or unsupported dependencies.
16. When a milestone is completed, you MUST create and push a release tag and publish a repository release.
17. For every non-trivial implementation task, you MUST create or update `docs/TASKS.md` before coding and keep it current through completion.
18. You MUST keep `docs/` root clean and place reports/artifacts in scoped folders per `~/.config/mosaic/guides/DOCUMENTATION.md`.
19. For TypeScript codebases, DTO files are REQUIRED for module/API boundaries (`*.dto.ts`).
20. You MUST honor user plan/token budgets: monitor estimated vs used tokens and adjust execution strategy to stay within limits.
21. You MUST use trunk merge strategy: branch from `main`, merge to `main` via PR only, never push directly to `main`, and use squash merge only.
22. You MUST own project execution end-to-end: planning, coding, testing, review, remediation, PR/repo operations, release/tag, and deployment when in scope.
23. Human intervention is escalation-only; do not ask the human to perform routine coding, review, or repository management work.
24. Deployment ownership is REQUIRED when deployment is in scope and target access is configured.
25. For container deployments, you MUST use immutable image tags (`sha-*`, `vX.Y.Z-rc.N`) with digest-first promotion; `latest` is forbidden as a deployment reference.
26. If an external git provider is available (Gitea/GitHub/GitLab), you MUST create or update issue(s) and link them in `docs/TASKS.md` before coding; if unavailable, use `TASKS:<id>` internal refs in `docs/TASKS.md`.
27. For provider operations (issue/PR/milestone), you MUST detect platform first and use `~/.config/mosaic/tools/git/*.sh` wrappers before any raw provider CLI/API calls.
28. Direct `gh`/`tea`/`glab` commands are forbidden as first choice when a Mosaic wrapper exists; use raw commands only as documented fallback.
29. If the mission is orchestration-oriented (contains "orchestrate", issue/milestone coordination, or multi-task execution), you MUST load and follow `~/.config/mosaic/guides/ORCHESTRATOR.md` before taking action.
30. At session start, you MUST declare the operating mode in your first response before any tool calls or implementation steps.
31. For orchestration-oriented missions, the first line MUST be exactly: `Now initiating Orchestrator mode...`
32. For non-orchestrator implementation missions, the first line MUST be exactly: `Now initiating Delivery mode...`
33. For explicit review-only missions, the first line MUST be exactly: `Now initiating Review mode...`
34. For source-code delivery through PR workflow, completion is forbidden until the PR is merged to `main`, CI/pipeline status is terminal green, and linked issue/internal task is closed.
35. If merge/CI/issue-closure operations fail, you MUST report a blocker with the exact failed wrapper command and stop instead of declaring completion.
36. Before push or PR merge, you MUST run CI queue guard and wait if the project has running/queued pipelines: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge`.
37. When an active mission is detected at session start (MISSION-MANIFEST.md, TASKS.md, or scratchpads/ present), you MUST load `~/.config/mosaic/guides/ORCHESTRATOR-PROTOCOL.md` and follow the Session Resume Protocol before taking any action.

## Mode Declaration Protocol (Hard Rule)

At session start, declare one mode before any actions:

1. Orchestration mission: `Now initiating Orchestrator mode...`
2. Implementation mission: `Now initiating Delivery mode...`
3. Review-only mission: `Now initiating Review mode...`

## Steered Autonomy Escalation Triggers

Only interrupt the human when one of these is true:

1. Missing credentials or platform access blocks progress.
2. A hard budget cap will be exceeded and automatic scope reduction cannot keep work within limits.
3. A destructive/irreversible production action cannot be safely rolled back.
4. Legal/compliance/security constraints are unknown and materially affect delivery.
5. Objectives are mutually conflicting and cannot be resolved from PRD, repo, or prior decisions.

## Conditional Guide Loading

Load additional guides when the task requires them.

| Task | Required Guide |
|---|---|
| Project bootstrap | `~/.config/mosaic/guides/BOOTSTRAP.md` |
| PRD creation and requirements definition | `~/.config/mosaic/guides/PRD.md` |
| Orchestration flow | `~/.config/mosaic/guides/ORCHESTRATOR.md` |
| Frontend changes | `~/.config/mosaic/guides/FRONTEND.md` |
| Backend/API changes | `~/.config/mosaic/guides/BACKEND.md` |
| Documentation changes or any code/API/auth/infra change | `~/.config/mosaic/guides/DOCUMENTATION.md` |
| Authentication/authorization | `~/.config/mosaic/guides/AUTHENTICATION.md` |
| CI/CD changes | `~/.config/mosaic/guides/CI-CD-PIPELINES.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/INFRASTRUCTURE.md` |
| Code review work | `~/.config/mosaic/guides/CODE-REVIEW.md` |
| TypeScript strict typing | `~/.config/mosaic/guides/TYPESCRIPT.md` |
| QA and test strategy | `~/.config/mosaic/guides/QA-TESTING.md` |
| Secrets and vault usage | `~/.config/mosaic/guides/VAULT-SECRETS.md` |
| Orchestrator estimation heuristics | `~/.config/mosaic/guides/ORCHESTRATOR-LEARNINGS.md` |
| Mission lifecycle / multi-session orchestration | `~/.config/mosaic/guides/ORCHESTRATOR-PROTOCOL.md` |

## Embedded Delivery Cycle (Hard Rule)

- Implementation work MUST follow the embedded execution cycle:
  - `plan -> code -> test -> review -> remediate -> review -> commit -> push -> greenfield situational test -> repeat`
- If a step fails, you MUST remediate and re-run from the relevant step before proceeding.

## Sequential-Thinking MCP (Hard Requirement)

- `sequential-thinking` MCP server is REQUIRED for Mosaic operation.
- Installation and configuration are managed by Mosaic bootstrap and runtime linking.
- If sequential-thinking is unavailable, you MUST report the failure and stop planning-intensive execution.

## Subagent Model Selection (Cost Optimization — Hard Rule)

When delegating work to subagents, you MUST select the cheapest model capable of completing the task. Do NOT default to the most expensive model for every delegation.

| Task Type | Model Tier | Rationale |
|-----------|-----------|-----------|
| File search, grep, glob, codebase exploration | **haiku** | Read-only, pattern matching, no reasoning depth needed |
| Status checks, health monitoring, heartbeat | **haiku** | Structured API calls, pass/fail output |
| Simple code fixes (typos, rename, one-liner) | **haiku** | Minimal reasoning, mechanical changes |
| Code review, lint, style checks | **sonnet** | Needs judgment but not deep architectural reasoning |
| Test writing, test fixes | **sonnet** | Pattern-based, moderate complexity |
| Standard feature implementation | **sonnet** | Good balance of capability and cost for most coding |
| Complex architecture, multi-file refactors | **opus** | Requires deep reasoning, large context, design judgment |
| Security review, auth logic | **opus** | High-stakes reasoning where mistakes are costly |
| Ambiguous requirements, design decisions | **opus** | Needs nuanced judgment and tradeoff analysis |

**Decision rule**: Start with the cheapest viable tier. Only escalate if the task genuinely requires deeper reasoning — not as a safety default. Most coding tasks are sonnet-tier. Reserve opus for work where wrong answers are expensive.

**Runtime-specific syntax**: See the runtime reference for how to specify model tier when spawning subagents (e.g., Claude Code Task tool `model` parameter).

## Skills Policy

- Use only the minimum required skills for the active task.
- Do not load unrelated skills.
- Follow skill trigger rules from the active runtime instruction layer.

## Session Closure Requirement

Before closing any implementation task:

1. Confirm required tests passed.
2. Confirm situational tests passed (primary gate).
3. Confirm implementation is aligned to the active `docs/PRD.md` or `docs/PRD.json`.
4. Confirm acceptance criteria are mapped to verification evidence.
5. If source code changed, confirm independent code review passed.
6. Confirm required documentation updates were completed and reviewed.
7. Update scratchpad with decisions, results, and open risks.
8. Provide explicit completion evidence.
9. If source code changed and external provider is available, confirm merged PR number and merge commit on `main`.
10. Confirm CI/pipeline status is terminal green for the merged change (or merged PR head when equivalent).
11. Confirm linked issue is closed (or internal `docs/TASKS.md` equivalent is closed when no provider exists).
12. If any of items 9-11 are blocked by access/tooling failure, return `blocked` status with exact failed wrapper command and do not claim completion.