fred
efb3c3a10c
ci/woodpecker/pr/ci Pipeline failed
Three guides that existed only as one host's working copy, promoted to framework templates so every estate gets them. A working copy under ~/.mosaic binds one host; only a template here binds all of them. SEAT-IDENTITY.md (new) documents how a seat's git credential is actually resolved after #1311: identity from MOSAIC_GIT_IDENTITY, then mosaic.gitIdentity, then the stdin username; host mapped to a store prefix; then ONE of two stores chosen by whether the seat directory exists, with no precedence and no fallback between them. A seat with a directory and an empty slot fails closed rather than reaching the service store, and that is the point. It also corrects how to find the helper. credential.helper commonly names an absolute path, so `command -v git-credential-mosaic` answers a different question than the one git asks, and the two stop agreeing the moment the PATH copy is removed. Git also tries EVERY configured helper in order, so a fail-closed helper in front silently hands the request to whatever is configured behind it. The guide says to read the whole list. FLEET-COMMS.md (new) documents agent-send.sh: the class table, the addressing preamble, and the exit codes — including that rc=2 means the text reached the pane as an unsubmitted draft, so retrying double-sends it. Confirm with capture-pane instead. It also says to measure the fleet rather than trust roster.yaml, which on a live host was simultaneously naming a socket that did not exist, listing seats that were not running, and omitting seats that were. CODE-REVIEW.md gains an Evidence Discipline section: a green is not a result until you have shown it could go red, measurement and explanation are separate sentences, verify by content on the ref that ships rather than by ancestry of a local sha, and confidence is part of a finding. Plus four shell-measurement rules earned on #1311, each of which produced a wrong conclusion first — `cmd | tail; echo rc=$?` reports tail's status, a missed glob under pipefail exits 2 and kills the run under set -e, nonzero-with-no-output is an environment question before it is a code question, and `git -C` in a non-repo directory answers from the enclosing repo. The estate-specific repository exception that lived in the working copy is not carried here. The template says an estate may document one, scoped to a named repository and never precedent for a second. Both new guides are added to the two routing tables that agents read.
90 lines
6.2 KiB
Markdown
Executable File
90 lines
6.2 KiB
Markdown
Executable File
# Mosaic Agent Dispatcher
|
|
|
|
Thin **load-order dispatcher + guide router**. The non-negotiable law lives in
|
|
`~/.config/mosaic/CONSTITUTION.md` (L0) — this file does NOT restate gates. Framework-owned;
|
|
overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.)
|
|
|
|
## Session Start — Load Order
|
|
|
|
1. Your context already includes `CONSTITUTION.md` + `USER.md` + the TOOLS index + the runtime
|
|
contract (injected by `mosaic` launch) — do not re-read those. **If you were launched bare**
|
|
(a harness started without `mosaic`, so the law is NOT in your context), read
|
|
`~/.config/mosaic/CONSTITUTION.md` now, before your first action. A bare launch also gets
|
|
**base contracts only** — operator overlays (`*.local.md`) are composed by the launcher, so if
|
|
`SOUL.local.md`/`USER.local.md`/`STANDARDS.local.md` exist, relaunch via `mosaic <harness>` (or run
|
|
`mosaic doctor`) to pick them up.
|
|
2. Read `SOUL.md` (agent persona — small, once).
|
|
3. Read project-local `AGENTS.md` / `CLAUDE.md` if present (these may only make behavior stricter).
|
|
4. Read guides ONLY as triggered by the table below — pull role-relevant depth on demand, not up front.
|
|
5. For implementation work, read `guides/E2E-DELIVERY.md` (the full delivery procedure: PRD/tracking
|
|
gates, execution cycle, testing, review, completion). `STANDARDS.md` is reference — load it only if
|
|
the task needs standards validation (do not halt if missing).
|
|
|
|
## Conditional Guide Loading (load only what the task needs)
|
|
|
|
| Task | Guide |
|
|
| -------------------------------------------------- | ---------------------------------- |
|
|
| Project bootstrap | `guides/BOOTSTRAP.md` |
|
|
| PRD creation / requirements | `guides/PRD.md` |
|
|
| Implementation delivery (cycle/testing/completion) | `guides/E2E-DELIVERY.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` |
|
|
| Writing style (docs, comms, any prose) | `guides/WRITING-STYLE.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` |
|
|
| Seat identity, git credentials, token slots | `guides/SEAT-IDENTITY.md` |
|
|
| Reaching another agent (fleet comms) | `guides/FLEET-COMMS.md` |
|
|
|
|
## Subagent Model Selection (Cost — 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).
|
|
|
|
- **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.
|
|
|
|
Start cheapest; escalate only when the task genuinely needs deeper reasoning. Runtime syntax for the
|
|
tier is in the runtime contract.
|
|
|
|
## Superpowers (use your tools — under-use is a violation)
|
|
|
|
Skills, hooks, MCP, and plugins are force multipliers you MUST use when applicable.
|
|
|
|
- **Skills:** before implementation, scan `~/.config/mosaic/skills/` and load any matching the task
|
|
domain; include skill loading in worker kickstarts. Do not load unrelated skills.
|
|
- **Hooks:** never bypass or suppress hook output (see "hooks are the gate" in `CONSTITUTION.md`); fix
|
|
hook failures like failing tests. If a hook is wrong, report it as a framework issue.
|
|
- **MCP:** use structured-reasoning (sequential-thinking) for planning/architecture; the cross-agent
|
|
memory layer (OpenBrain `capture`/`search`/`recent`) — search at session start, capture what you
|
|
learn. Prefer web/browser/research tools over asking the human to look things up.
|
|
- **Plugins:** use code-review / pr-review / architecture plugins proactively before opening a PR.
|
|
- **Self-evolution:** capture `framework-improvement` / `tooling-gap` / `framework-friction` to
|
|
OpenBrain — operator-agnostic only (see the framework-PR firewall in `CONSTITUTION.md`).
|
|
|
|
## Missing core file
|
|
|
|
If `CONSTITUTION.md`, `AGENTS.md`, `SOUL.md`, or the runtime contract is missing, stop and report it.
|
|
This agent-facing strictness is intentional and stricter than the launcher: the launcher injects
|
|
`CONSTITUTION.md` tolerantly (skipping it if absent so pre-upgrade hosts keep working), but once a host
|
|
is re-seeded a genuinely missing core file is a stop-and-report condition — not something to proceed past.
|
|
|
|
## Session Closure
|
|
|
|
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. For PR-workflow delivery: merged PR number + merge commit on `main`, terminal-green
|
|
CI, linked issue closed (or `docs/TASKS.md` equivalent). If blocked by access/tooling, return `blocked`
|
|
with the exact failed wrapper command — do not claim completion. Full checklist: `guides/E2E-DELIVERY.md`.
|