stack/docs/design/framework-constitution/BRIEF.md

Mission Brief — Mosaic Framework Constitution & Public Sanitization (Alpha)

The problem

@mosaicstack/mosaic ships a public, open-source agent framework under packages/mosaic/framework/. Today it conflates three different things in the same files:

1. Universal framework law — hard gates, delivery contract, escalation rules, integrity guardrails. Should be identical for every user and every harness. (currently spread across defaults/AGENTS.md, guides/*)
2. Agent persona — the agent's name, tone, identity. (currently defaults/SOUL.md, hardcoded to "Jarvis")
3. The human operator's profile & preferences — name, accommodations, projects, comms style. (currently leaks into defaults/SOUL.md as "PDA", into defaults/USER.md, runtime overlays like jarvis-loop.json)

Because of this conflation, the public package is contaminated with one operator's personal preferences (29 files reference jarvis/jason/woltje/PDA), and there is no clean separation between what the framework owns (and updates) and what a user owns (and customizes). A downstream user who edits files gets clobbered on upgrade; the maintainer's personal identity ships to everyone.

The goal

Re-architect the framework so that:

• It is a clean, generic, open-source framework any team can adopt.
• There is a clear, enforced separation between a Mosaic Constitution (universal, framework-owned, non-negotiable) and per-user/per-deployment customization (identity, profile, preferences, project specifics).
• Users can customize and still receive framework updates without losing their changes or drifting (the deployed-vs-source drift problem is real today).
• The contract is robust and consistent across harnesses (Claude, Codex, Pi, OpenCode) which inject context differently.
• Ships as a solid alpha release.

Current document architecture (ground truth — read the real files)

Repo working copy: /home/jwoltje/src/_ms_stack Framework root: packages/mosaic/framework/

• defaults/ — AGENTS.md (thin-core contract), SOUL.md (persona), STANDARDS.md, TOOLS.md, USER.md. These deploy to ~/.config/mosaic/. Contaminated with personal data.
• templates/ — SOUL.md.template, USER.md.template, TOOLS.md.template, agent/AGENTS.md.template, project templates with {{PLACEHOLDER}} tokens. A template/personalization layer already exists but is under-used.
• guides/ — on-demand deep guides (E2E-DELIVERY, ORCHESTRATOR, QA-TESTING, PRD, CODE-REVIEW, etc.). Mostly framework-universal.
• runtime/{claude,codex,pi,opencode,mcp}/ — per-harness RUNTIME.md + settings.
• adapters/{claude,codex,pi,generic}.md — per-harness adapter notes.
• profiles/ — domain / tech-stack / workflow presets (JSON).
• install.sh / mosaic-init — deploy/personalization entrypoints.

Design questions to resolve (debate these)

• DQ1 — Layering. Should Mosaic introduce an explicit Constitution layer distinct from SOUL (persona) and USER (operator profile)? Define the canonical layers, what content belongs in each, and the precedence/override order.
• DQ2 — Sanitization. How to remove personal data from public defaults/ while keeping a great out-of-box experience: generic-defaults vs empty-defaults+examples vs template-then-init. What ships vs what's generated.
• DQ3 — Customization & upgrade safety. How a user customizes and still pulls framework updates without losing changes or drifting. Layering/override, version pinning, migration, the deployed-vs-source reconciliation.
• DQ4 — Cross-harness robustness. How to make the Constitution enforce consistently across Claude/Codex/Pi/OpenCode given different injection and tool models. Single source of truth + adapter strategy.
• DQ5 — Minimalism vs completeness. The contract is large and partly duplicated. How to keep it robust but not bloated, contradictory, or model-degrading — thin always-resident core vs on-demand depth.

Constraints / non-negotiables

• Output must be harness-agnostic in the core; harness specifics isolated to adapters/runtime.
• No personal data, no secrets, no PII in any public/shipped file.
• Must be backward-compatible enough to land as an alpha without breaking existing deployments catastrophically (migration path required).
• Keep the existing Mosaic hard gates intact (PR-review-before-merge, green CI, no forced merges, completion-defined-at-end) — this re-architecture is about where rules live and how they're customized, not weakening them.

Definition of done (alpha)

A merged, CI-green PR that: establishes the Constitution/customization layering; sanitizes the public package; provides an upgrade-safe customization mechanism; documents the model; and tags an alpha release. A PRD precedes implementation.