bootstrap/AGENTS.md

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/STANDARDS.md
3. ~/.config/mosaic/AGENTS.md
4. ~/.config/mosaic/guides/E2E-DELIVERY.md
5. Project-local AGENTS.md (if present)
6. 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/rails/git/ci-queue-wait.sh --purpose push|merge.
7. For issue/PR/milestone operations, you MUST use Mosaic wrappers first (~/.config/mosaic/rails/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?".

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/rails/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/rails/git/ci-queue-wait.sh --purpose push|merge.

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
Shared memory patterns	~/.config/mosaic/guides/MEMORY.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.

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.