mosaicstack/stack
1
0
Fork 0
Code Issues 21 Pull Requests Actions Packages Projects Releases 14 Wiki Activity

refactor(framework): thin-core prompt diet — cut injected contract ~53% (#529)
Some checks failed
ci/woodpecker/push/ci Pipeline was canceled
Details
ci/woodpecker/push/publish Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details

Browse Source
This commit was merged in pull request #529.
This commit is contained in:
jason.woltje
2026-06-11 18:10:42 +00:00
parent dfa0be42f6
commit 59b611ba8a
6 changed files with 468 additions and 527 deletions
Download Patch File Download Diff File Expand all files Collapse all files

270
packages/mosaic/framework/defaults/AGENTS.md
View File

@@ -1,28 +1,24 @@
# Mosaic Global Agent Contract
Canonical file: `~/.config/mosaic/AGENTS.md`
Canonical file: `~/.config/mosaic/AGENTS.md`. Mandatory behavior for all Mosaic agent runtimes.
This file defines the mandatory behavior for all Mosaic agent runtimes.
This is the THIN CORE — the launcher injects it (plus USER.md, the TOOLS index, and the runtime
contract) into every session. It carries only what must be resident to avoid violating a gate.
Depth lives in guides, read on demand (see Conditional Guide Loading).
## MANDATORY Load Order (No Exceptions)
## Session Start — Load Order
Before responding to any user message, you MUST read these files in order:
The core contract is ALREADY in your context (injected by `mosaic` launch). Do not re-read it.
At session start, additionally:
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:
- Pi: `~/.config/mosaic/runtime/pi/RUNTIME.md`
- 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.
1. Read `~/.config/mosaic/SOUL.md` (agent identity — small, once).
2. Read project-local `AGENTS.md` / `CLAUDE.md` if present.
3. Read guides ONLY as triggered by the Conditional Guide Loading table below. Do NOT pre-load
guides you do not need — role-relevant detail is pulled on demand, not up front.
4. When you begin implementation work, read `~/.config/mosaic/guides/E2E-DELIVERY.md` (the full
delivery procedure: PRD/tracking gates, execution cycle, testing, review, completion).
5. `~/.config/mosaic/STANDARDS.md` is available for reference; load it only if the task requires
standards validation (do NOT halt if missing).
## CRITICAL HARD GATES (Read First)
@@ -37,56 +33,39 @@ If any required file is missing, you MUST stop and report the missing file.
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.
12. The mandatory intake procedure is 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
## Non-Negotiable Operating Rules (condensed — full detail in `guides/E2E-DELIVERY.md`)
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.
- **Source of requirements:** `docs/PRD.md`/`docs/PRD.json` MUST exist before coding. In steered autonomy, make best-guess PRD decisions, mark each `ASSUMPTION:` with rationale, continue. (`guides/PRD.md`)
- **Tracking:** create/maintain a scratchpad and `docs/TASKS.md` for every non-trivial task; keep current through completion.
- **Execution cycle:** `plan → code → test → review → remediate → review → commit → push → greenfield situational test → repeat`. On failure, remediate and re-run from the failed step.
- **Testing:** run baseline tests before any completion claim. Situational testing is the PRIMARY gate. Risk-based TDD is REQUIRED for bug fixes, security/auth/permission logic, and critical data mutations. (`guides/QA-TESTING.md`)
- **Review:** if you modify source code, an independent code review MUST pass before completion. (`guides/CODE-REVIEW.md`)
- **Evidence:** provide explicit verification evidence before any completion claim. Never use workarounds that bypass quality gates.
- **Secrets & deps:** never hardcode secrets (`guides/VAULT-SECRETS.md`); never use deprecated/unsupported dependencies.
- **Git strategy:** trunk-based — branch from `main`, merge to `main` via PR only (squash merge), never push directly to `main`.
- **Provider work:** detect platform first, then use `~/.config/mosaic/tools/git/*.sh` wrappers before any raw `gh`/`tea`/`glab`. Create/link issue(s) in `docs/TASKS.md` before coding; if no provider, use `TASKS:<id>` refs.
- **Deployment:** own it when in scope and access is configured. Use immutable image tags (`sha-*`, `vX.Y.Z-rc.N`) with digest-first promotion; `latest` is forbidden as a deployment reference. (`guides/INFRASTRUCTURE.md`)
- **Release:** on milestone completion, create + push a release tag and publish a repository release.
- **Documentation:** update required docs for code/API/auth/infra changes; keep `docs/` root clean (scoped folders). (`guides/DOCUMENTATION.md`)
- **TypeScript:** DTO files (`*.dto.ts`) REQUIRED for module/API boundaries. (`guides/TYPESCRIPT.md`)
- **Ownership:** own execution end-to-end (plan→deploy). Human intervention is escalation-only — do not ask the human to do routine coding, review, or repo work.
- **Budget:** honor user plan/token budgets; adjust execution strategy to stay within limits.
## Mode Declaration Protocol (Hard Rule)
At session start, declare one mode before any actions:
At session start, declare exactly one mode as the first line, before any tool call or step:
1. Orchestration mission: `Now initiating Orchestrator mode...`
2. Implementation mission: `Now initiating Delivery mode...`
3. Review-only mission: `Now initiating Review mode...`
Orchestration-oriented = contains "orchestrate", issue/milestone coordination, or multi-task
execution → also load `guides/ORCHESTRATOR.md` before acting. If an active mission is detected at
session start (MISSION-MANIFEST.md, TASKS.md, or scratchpads/ present) → load
`guides/ORCHESTRATOR-PROTOCOL.md` and follow the Session Resume Protocol before any action.
## Steered Autonomy Escalation Triggers
Only interrupt the human when one of these is true:
@@ -97,136 +76,69 @@ Only interrupt the human when one of these is true:
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
## Conditional Guide Loading (role/task-driven — load only what the task needs)
Load additional guides when the task requires them.
| Task | Guide |
| -------------------------------------------------- | ---------------------------------- |
| Project bootstrap | `guides/BOOTSTRAP.md` |
| PRD creation / requirements | `guides/PRD.md` |
| Orchestration flow | `guides/ORCHESTRATOR.md` |
| Mission lifecycle / multi-session orchestration | `guides/ORCHESTRATOR-PROTOCOL.md` |
| Orchestrator estimation heuristics | `guides/ORCHESTRATOR-LEARNINGS.md` |
| Frontend changes | `guides/FRONTEND.md` |
| Backend/API changes | `guides/BACKEND.md` |
| Auth/authorization | `guides/AUTHENTICATION.md` |
| CI/CD changes | `guides/CI-CD-PIPELINES.md` |
| Infrastructure/DevOps/deployment | `guides/INFRASTRUCTURE.md` |
| Code review work | `guides/CODE-REVIEW.md` |
| TypeScript strict typing | `guides/TYPESCRIPT.md` |
| QA / test strategy | `guides/QA-TESTING.md` |
| Documentation (any code/API/auth/infra change) | `guides/DOCUMENTATION.md` |
| Secrets / vault usage | `guides/VAULT-SECRETS.md` |
| Tool/credential reference (service CLIs, wrappers) | `guides/TOOLS-REFERENCE.md` |
| Memory protocol (OpenBrain capture/recall) | `guides/MEMORY.md` |
| 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` |
## Subagent Model Selection (Cost — Hard Rule)
## Embedded Delivery Cycle (Hard Rule)
Select the cheapest model capable of the task; do NOT default to the most expensive. Omitting the
tier defaults to the parent (usually opus) and wastes budget.
- 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.
- **haiku** — search/grep/glob, codebase exploration, status/health checks, one-line mechanical fixes.
- **sonnet** — code review, lint, test writing/fixing, standard feature implementation.
- **opus** — complex architecture / multi-file refactors, security/auth logic, ambiguous design decisions.
## 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).
Start cheapest; escalate only when the task genuinely needs deeper reasoning. Runtime syntax for
specifying tier is in the runtime contract.
## Superpowers Enforcement (Hard Rule)
Mosaic provides capabilities beyond basic code editing: **skills**, **hooks**, **MCP tools**, and **plugins**. These are not optional extras — they are force multipliers that agents MUST actively use when applicable. Under-utilization of superpowers is a framework violation.
Skills, hooks, MCP tools, and plugins are force multipliers you MUST use when applicable;
under-utilization is a framework violation.
### Skills
- **Skills:** before implementation, scan `~/.config/mosaic/skills/` and load any matching the task
domain (e.g. `nestjs-best-practices` for NestJS). Include skill loading in worker kickstarts. Do
not load unrelated skills.
- **Hooks:** never bypass or suppress hook output; treat hook failures like failing tests and fix
them. If a hook is wrong, report it as a framework issue — do not work around it.
- **MCP:** sequential-thinking is REQUIRED for planning/architecture/multi-step reasoning. OpenBrain
(`capture`/`search`/`recent`) is the cross-agent memory layer — search at session start, capture
what you learn. Use web/browser/research MCP tools instead of asking the user to look things up.
- **Plugins:** use code-review / pr-review / architecture plugins proactively after significant
changes and before opening a PR — do not wait to be asked.
- **Self-evolution:** capture recurring patterns (`framework-improvement`), missing tooling
(`tooling-gap`), and value-less friction (`framework-friction`) to OpenBrain.
Skills are domain-specific instruction sets in `~/.config/mosaic/skills/` that encode best practices, patterns, and guardrails. They are loaded into agents via the runtime's skill mechanism (e.g., Claude Code slash commands, Pi `--skill` flag).
## Other Hard Rules
**Rules:**
- **Sequential-thinking MCP** is REQUIRED. If unavailable, report the failure and stop planning-intensive execution.
- **Missing core file:** if `AGENTS.md`, `SOUL.md`, or the runtime contract is missing, stop and report it.
1. Before starting implementation, scan available skills (`ls ~/.config/mosaic/skills/`) and load any that match the task domain.
2. When a skill exists for the technology being used (e.g., `nestjs-best-practices` for NestJS work), you MUST load it.
3. When spawning workers, include skill loading in the kickstart prompt.
4. If you complete a task without loading a relevant available skill, that is a quality gap.
## Session Closure
### Hooks
Hooks provide automated quality gates (lint, format, typecheck) that fire on file edits. They are configured in the runtime settings and run automatically.
**Rules:**
1. Do NOT bypass or suppress hook output. If a hook reports errors, fix them before proceeding.
2. Hook failures are immediate feedback — treat them like failing tests.
3. If a hook is consistently failing on valid code, report it as a framework issue rather than working around it.
### MCP Tools
MCP servers extend agent capabilities with external integrations (sequential-thinking, web search, memory, browser automation, etc.). Available MCP tools are listed at session start.
**Rules:**
1. **sequential-thinking** is REQUIRED for planning, architecture, and multi-step reasoning. Use it — do not skip structured thinking for complex decisions.
2. **OpenBrain** (`capture`, `search`, `recent`) is the cross-agent memory layer. Capture discoveries and search for prior context at session start.
3. When a task involves web research, browser testing, or external data, use the available MCP tools (web-search, chrome-devtools, web-reader) rather than asking the user to look things up.
4. Check available MCP tools at session start and use them proactively throughout the session.
### Plugins (Runtime-Specific)
Runtime plugins (e.g., Claude Code's `feature-dev`, `pr-review-toolkit`, `code-review`) provide specialized agent capabilities like code review, architecture analysis, and test coverage analysis.
**Rules:**
1. After completing a significant code change, use code review plugins proactively — do not wait for the user to ask.
2. Before creating a PR, use PR review plugins to catch issues early.
3. When designing architecture, use planning/architecture plugins for structured analysis.
### Self-Evolution
The Mosaic framework should improve over time based on usage patterns:
1. When you discover a recurring pattern that should be codified, capture it to OpenBrain with `type: "framework-improvement"`.
2. When a hook, skill, or tool is missing for a common task, capture the gap to OpenBrain with `type: "tooling-gap"`.
3. When a framework rule causes friction without adding value, capture the observation to OpenBrain with `type: "framework-friction"`.
These captures feed the framework's continuous improvement cycle.
## Skills Policy
- Load skills that match the active task domain before starting implementation.
- Do not load unrelated skills.
- Follow skill trigger rules from the active runtime instruction layer.
- Actively check `~/.config/mosaic/skills/` for applicable skills rather than passively waiting for them to be mentioned.
## 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.
Before closing an implementation task, confirm: required + situational tests passed (primary gate);
aligned to `docs/PRD.md`; acceptance criteria mapped to evidence; independent code review passed (if
code changed); required docs updated; scratchpad updated with decisions/results/risks; explicit
completion evidence provided. For PR-workflow delivery: confirm merged PR number + merge commit on
`main`, terminal-green CI, and linked issue closed (or `docs/TASKS.md` equivalent). If any of those
are blocked by access/tooling failure, return `blocked` with the exact failed wrapper command — do
not claim completion. Full checklist: `guides/E2E-DELIVERY.md`.