Jason Woltje
248db8935c
MEMORY.md was conditionally loaded so agents defaulted to their native memory locations (e.g. ~/.claude/projects/*/memory/). This caused durable learnings to be siloed per-runtime instead of shared across agents. - Move MEMORY.md to mandatory load order in AGENTS.md (position 7) - Add Memory Override section to all three runtime configs (Claude, Codex, OpenCode) explicitly forbidding native memory silos for durable data - Add memory/ directory with .gitkeep to bootstrap source - Add mkdir -p for memory/ in install.sh post-sync step Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
150 lines
10 KiB
Markdown
Executable File
150 lines
10 KiB
Markdown
Executable File
# 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/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` |
|
|
|
|
## 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.
|