diff --git a/.woodpecker/ci.yml b/.woodpecker/ci.yml index 07484b7..5a5f63a 100644 --- a/.woodpecker/ci.yml +++ b/.woodpecker/ci.yml @@ -18,6 +18,14 @@ steps: - apk add --no-cache python3 make g++ - pnpm install --frozen-lockfile + # Blocking gate: public framework package must contain no operator-specific + # personal data or private $HOME defaults. Runs early (no node_modules needed). + sanitization: + image: *node_image + commands: + - apk add --no-cache bash + - bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh + typecheck: image: *node_image commands: diff --git a/packages/mosaic/framework/defaults/AUDIT-2026-02-17-framework-consistency.md b/docs/audits/AUDIT-2026-02-17-framework-consistency.md similarity index 100% rename from packages/mosaic/framework/defaults/AUDIT-2026-02-17-framework-consistency.md rename to docs/audits/AUDIT-2026-02-17-framework-consistency.md diff --git a/packages/mosaic/framework/defaults/AGENTS.md b/packages/mosaic/framework/defaults/AGENTS.md index 457efd8..214c9c9 100755 --- a/packages/mosaic/framework/defaults/AGENTS.md +++ b/packages/mosaic/framework/defaults/AGENTS.md @@ -34,7 +34,7 @@ At session start, additionally: 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 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. -13. **Merge authority (coordinated work):** when a coordinator/orchestrator session is active for the work, the post-review MERGE GO-AHEAD is the coordinator's to give — once code has passed the required review gates, request the coordinator's go-ahead and merge on their confirmation; do NOT wait on the human owner personally. Solo (uncoordinated) delivery keeps the default: merge without routine confirmation per gates 2 and 9. A "No self-merge" note on a PR means no UNREVIEWED self-merge — it does not suspend coordinator-authorized merges. (Policy: Jason, 2026-06-11.) +13. **Merge authority (coordinated work):** when a coordinator/orchestrator session is active for the work, the post-review MERGE GO-AHEAD is the coordinator's to give — once code has passed the required review gates, request the coordinator's go-ahead and merge on their confirmation; do NOT wait on the human owner personally. Solo (uncoordinated) delivery keeps the default: merge without routine confirmation per gates 2 and 9. A "No self-merge" note on a PR means no UNREVIEWED self-merge — it does not suspend coordinator-authorized merges. ## Non-Negotiable Operating Rules (condensed — full detail in `guides/E2E-DELIVERY.md`) diff --git a/packages/mosaic/framework/defaults/README.md b/packages/mosaic/framework/defaults/README.md index 097d5b6..629c0bf 100644 --- a/packages/mosaic/framework/defaults/README.md +++ b/packages/mosaic/framework/defaults/README.md @@ -69,7 +69,7 @@ It also detects installed runtimes (Claude, Codex, OpenCode, Pi), configures seq For CI or scripted installs: ```bash -mosaic init --non-interactive --name Jarvis --style direct --user-name Jason --timezone America/Chicago +mosaic init --non-interactive --name "Mosaic Agent" --style direct --user-name "Your Name" --timezone "UTC" ``` All flags: `--name`, `--role`, `--style`, `--user-name`, `--pronouns`, `--timezone`, `--mosaic-home`, `--source-dir`. diff --git a/packages/mosaic/framework/defaults/SOUL.md b/packages/mosaic/framework/defaults/SOUL.md index 65db90a..a8cbf2f 100644 --- a/packages/mosaic/framework/defaults/SOUL.md +++ b/packages/mosaic/framework/defaults/SOUL.md @@ -5,14 +5,14 @@ It is loaded globally and applies to all sessions regardless of runtime or proje ## Identity -You are **Jarvis** in this session. +You are the **Mosaic agent** in this session. - Runtime (Claude, Codex, OpenCode, etc.) is implementation detail. - Role identity: execution partner and visibility engine If asked "who are you?", answer: -`I am Jarvis, running on .` +`I am the Mosaic agent, running on .` ## Behavioral Principles @@ -20,7 +20,7 @@ If asked "who are you?", answer: 2. Practical execution over abstract planning. 3. Truthfulness over confidence: state uncertainty explicitly. 4. Visible state over hidden assumptions. -5. PDA-friendly language, communication style, and iconography. Avoid overwhelming info and communication style.. +5. Accessibility-aware: honor the operator's communication and formatting preferences declared in `USER.md`. ## Communication Style diff --git a/packages/mosaic/framework/defaults/TOOLS.md b/packages/mosaic/framework/defaults/TOOLS.md index 6ef3808..0cca3db 100644 --- a/packages/mosaic/framework/defaults/TOOLS.md +++ b/packages/mosaic/framework/defaults/TOOLS.md @@ -66,12 +66,6 @@ starts, commits, PRs, test results, or file edits. At session start, `search` + prior context. MCP (`mcp__openbrain__capture/search/recent/stats`) preferred when connected; else REST/`tools/openbrain_client.py`. Full protocol: `guides/MEMORY.md`. -**MANDATORY jarvis-brain rule:** when working in `~/src/jarvis-brain`, NEVER capture project data, -meeting notes, status, timelines, or task completions to OpenBrain — the flat files -(`data/projects/*.json`, `data/tasks/*.json`) are the SSOT (use `tools/brain.py` + direct JSON -edits). OpenBrain there is for agent meta-observations ONLY (tooling gotchas, framework learnings, -cross-project patterns). Violating this creates duplicate, divergent data. - ## Git Providers | Host | Instance | CI | diff --git a/packages/mosaic/framework/examples/overlays/e2e-loop.json b/packages/mosaic/framework/examples/overlays/e2e-loop.json new file mode 100644 index 0000000..b4288d0 --- /dev/null +++ b/packages/mosaic/framework/examples/overlays/e2e-loop.json @@ -0,0 +1,29 @@ +{ + "_comment": "EXAMPLE Claude runtime overlay managed by Mosaic. Copy/adapt and merge into ~/.claude/settings.json as needed. Replace the placeholder project paths and skills with your own. Never auto-loaded.", + "model": "opus", + "additionalAllowedCommands": [ + "alembic", + "alembic upgrade", + "alembic downgrade", + "uvicorn", + "ruff", + "ruff check", + "ruff format", + "black", + "isort" + ], + "projectConfigs": { + "app": { + "path": "~/src/your-app", + "model": "opus", + "skills": ["prd"], + "guides": ["E2E-DELIVERY", "QA-TESTING"] + }, + "review": { + "path": "~/src/your-app", + "model": "opus", + "skills": ["code-review"], + "guides": ["CODE-REVIEW"] + } + } +} diff --git a/packages/mosaic/framework/examples/personas/execution-partner.md b/packages/mosaic/framework/examples/personas/execution-partner.md new file mode 100644 index 0000000..bd22bc3 --- /dev/null +++ b/packages/mosaic/framework/examples/personas/execution-partner.md @@ -0,0 +1,46 @@ +# Example persona — "Execution Partner" + +A worked example of an agent persona (the `SOUL.md` layer). Copy it to +`~/.config/mosaic/SOUL.md` and adapt, or generate one with `mosaic init`. This is +an **example only** — it is never auto-loaded. Keep operator-specific +accommodations (accessibility needs, comms preferences) in your own `USER.md`, +not here. + +--- + +## Identity + +You are the **Execution Partner** in this session. + +- Runtime (Claude, Codex, OpenCode, etc.) is an implementation detail. +- Role identity: execution partner and visibility engine. + +If asked "who are you?", answer: `I am the Execution Partner, running on .` + +## Behavioral Principles + +1. Clarity over performance theater. +2. Practical execution over abstract planning. +3. Truthfulness over confidence: state uncertainty explicitly. +4. Visible state over hidden assumptions. +5. Accessibility-aware: honor the operator's communication and formatting + preferences declared in `USER.md`. + +## Communication Style + +- Be direct, concise, and concrete. +- Avoid fluff, hype, and anthropomorphic roleplay. +- Do not simulate certainty when facts are missing. +- Prefer actionable next steps and explicit tradeoffs. + +## Operating Stance + +- Proactively surface what is hot, stale, blocked, or risky. +- Preserve canonical data integrity. +- Respect generated-vs-source boundaries. +- Treat multi-agent collisions as a first-class risk; sync before/after edits. + +## Why this exists + +Agents should be governed by durable principles, not brittle scripted outputs. +The model should reason within constraints, not mimic a fixed response table. diff --git a/packages/mosaic/framework/guides/BOOTSTRAP.md b/packages/mosaic/framework/guides/BOOTSTRAP.md index b750eb4..d6b5c45 100755 --- a/packages/mosaic/framework/guides/BOOTSTRAP.md +++ b/packages/mosaic/framework/guides/BOOTSTRAP.md @@ -396,12 +396,12 @@ fi ### Orchestrator Templates -| Template | Path | Purpose | -| -------------------------------------- | ------------------------------------------------- | ----------------------- | -| `tasks.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Task tracking | -| `orchestrator-learnings.json.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Variance tracking | -| `phase-issue-body.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Git provider issue body | -| `scratchpad.md.template` | `~/src/jarvis-brain/docs/templates/` | Per-task working doc | +| Template | Path | Purpose | +| -------------------------------------- | ------------------------------------------ | ----------------------- | +| `tasks.md.template` | `~/.config/mosaic/templates/orchestrator/` | Task tracking | +| `orchestrator-learnings.json.template` | `~/.config/mosaic/templates/orchestrator/` | Variance tracking | +| `phase-issue-body.md.template` | `~/.config/mosaic/templates/orchestrator/` | Git provider issue body | +| `scratchpad.md.template` | `~/.config/mosaic/templates/` | Per-task working doc | ### Variables Reference diff --git a/packages/mosaic/framework/guides/ORCHESTRATOR-LEARNINGS.md b/packages/mosaic/framework/guides/ORCHESTRATOR-LEARNINGS.md index fb8938a..bb2000a 100644 --- a/packages/mosaic/framework/guides/ORCHESTRATOR-LEARNINGS.md +++ b/packages/mosaic/framework/guides/ORCHESTRATOR-LEARNINGS.md @@ -124,4 +124,4 @@ Where: ## Where to Find Project-Specific Data - **Project learnings:** `/docs/tasks/orchestrator-learnings.json` -- **Cross-project metrics:** `jarvis-brain/data/orchestrator-metrics.json` +- **Cross-project metrics:** `~/.config/mosaic/orchestrator/metrics.json` diff --git a/packages/mosaic/framework/guides/ORCHESTRATOR-PROTOCOL.md b/packages/mosaic/framework/guides/ORCHESTRATOR-PROTOCOL.md index 3566ef8..c29b964 100644 --- a/packages/mosaic/framework/guides/ORCHESTRATOR-PROTOCOL.md +++ b/packages/mosaic/framework/guides/ORCHESTRATOR-PROTOCOL.md @@ -1,7 +1,7 @@ # Orchestrator Protocol — Mission Lifecycle Guide > **Operational guide for agent sessions.** Distilled from the full specification at -> `jarvis-brain/docs/protocols/ORCHESTRATOR-PROTOCOL.md` (1,066 lines). +> the canonical orchestrator protocol maintained with the framework. > > Load this guide when: active mission detected, multi-milestone orchestration, mission continuation. > Load `ORCHESTRATOR.md` for per-session execution protocol (planning, coding, review, commit cycle). @@ -194,7 +194,7 @@ This is the confirmed, most common failure. Every session will eventually trigge ## 8. r0 Manual Coordinator Process -In r0, the Coordinator is Jason + shell scripts. No daemon. No automation. +In r0, the Coordinator is a human operator + shell scripts. No daemon. No automation. ### Commands diff --git a/packages/mosaic/framework/guides/ORCHESTRATOR.md b/packages/mosaic/framework/guides/ORCHESTRATOR.md index 582f60e..81c8e5b 100644 --- a/packages/mosaic/framework/guides/ORCHESTRATOR.md +++ b/packages/mosaic/framework/guides/ORCHESTRATOR.md @@ -96,7 +96,7 @@ In Matrix rail mode, keep `docs/TASKS.md` as canonical project tracking and use ## Bootstrap Templates -Use templates from `jarvis-brain/docs/templates/` to scaffold tracking files: +Use templates from `~/.config/mosaic/templates/` to scaffold tracking files: ```bash # Set environment variables @@ -108,7 +108,7 @@ export PHASE_ISSUE="#1" export PHASE_BRANCH="fix/security" # Copy templates -TEMPLATES=~/src/jarvis-brain/docs/templates +TEMPLATES=~/.config/mosaic/templates # Create PRD if missing (before coding begins) [[ -f docs/PRD.md || -f docs/PRD.json ]] || cp ~/.config/mosaic/templates/docs/PRD.md.template docs/PRD.md @@ -149,7 +149,7 @@ Branch and merge strategy (HARD RULE): | `reports/review-report-scaffold.sh` | Creates report directory | | `scratchpad.md.template` | Per-task working document | -See `jarvis-brain/docs/templates/README.md` for full documentation. +See `~/.config/mosaic/templates/README.md` for full documentation. --- diff --git a/packages/mosaic/framework/guides/TOOLS-REFERENCE.md b/packages/mosaic/framework/guides/TOOLS-REFERENCE.md index 72c0bcd..74ce461 100644 --- a/packages/mosaic/framework/guides/TOOLS-REFERENCE.md +++ b/packages/mosaic/framework/guides/TOOLS-REFERENCE.md @@ -146,8 +146,6 @@ load_credentials Self-hosted semantic brain backed by pgvector. Primary shared memory layer for all agents across all sessions and harnesses. Stores and retrieves decisions, context, and observations via semantic search. -**MANDATORY jarvis-brain rule:** When working in `~/src/jarvis-brain`, NEVER capture project data, meeting notes, status updates, timeline decisions, or task completions to OpenBrain. The flat files (`data/projects/*.json`, `data/tasks/*.json`) are the SSOT — use `tools/brain.py` and direct JSON edits. OpenBrain is for agent meta-observations ONLY (tooling gotchas, framework learnings, cross-project patterns). Violating this creates duplicate, divergent data. - **Credentials:** `load_credentials openbrain` → exports `OPENBRAIN_URL`, `OPENBRAIN_TOKEN` Configure in your credentials.json: @@ -179,7 +177,7 @@ curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/ curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/stats" ``` -**Python client** (if jarvis-brain is available on PYTHONPATH): +**Python client** (if the OpenBrain client is on your PYTHONPATH): ```bash python tools/openbrain_client.py search "topic" @@ -223,7 +221,7 @@ Headless `.excalidraw` → SVG export via `@excalidraw/excalidraw`. Available as **Diagram generation** (`list_diagrams`, `generate_diagram`, `generate_and_export`) requires `EXCALIDRAW_GEN_PATH` env var pointing to `excalidraw_gen.py`. Set in environment or shell profile: ```bash -export EXCALIDRAW_GEN_PATH="$HOME/src/jarvis-brain/tools/excalidraw_export/excalidraw_gen.py" +export EXCALIDRAW_GEN_PATH="$HOME/.config/mosaic/tools/excalidraw/excalidraw_gen.py" ``` **Manual registration:** diff --git a/packages/mosaic/framework/profiles/README.md b/packages/mosaic/framework/profiles/README.md index 632e0c9..24f60a3 100644 --- a/packages/mosaic/framework/profiles/README.md +++ b/packages/mosaic/framework/profiles/README.md @@ -15,7 +15,7 @@ Profiles are runtime-neutral context packs that can be consumed by any agent run Current runtime overlay example: -- `~/.config/mosaic/runtime/claude/settings-overlays/jarvis-loop.json` +- `examples/overlays/e2e-loop.json` ## Claude Compatibility diff --git a/packages/mosaic/framework/runtime/claude/settings-overlays/jarvis-loop.json b/packages/mosaic/framework/runtime/claude/settings-overlays/jarvis-loop.json deleted file mode 100644 index 2ba69ed..0000000 --- a/packages/mosaic/framework/runtime/claude/settings-overlays/jarvis-loop.json +++ /dev/null @@ -1,53 +0,0 @@ -{ - "_comment": "Claude runtime overlay managed by Mosaic. Merge into ~/.claude/settings.json as needed.", - "model": "opus", - "additionalAllowedCommands": [ - "alembic", - "alembic upgrade", - "alembic downgrade", - "alembic revision", - "alembic history", - "uvicorn", - "fastapi", - "ruff", - "ruff check", - "ruff format", - "black", - "isort", - "httpx" - ], - "projectConfigs": { - "jarvis": { - "path": "~/src/jarvis", - "model": "opus", - "skills": ["jarvis", "prd"], - "guides": [ - "E2E-DELIVERY", - "PRD", - "BACKEND", - "FRONTEND", - "AUTHENTICATION", - "QA-TESTING", - "CODE-REVIEW" - ], - "env": { - "PYTHONPATH": "packages/plugins" - } - } - }, - "presets": { - "jarvis-loop": { - "description": "Embedded E2E delivery cycle for Jarvis", - "model": "opus", - "skills": ["jarvis", "prd"], - "systemPrompt": "You are an autonomous coding agent. For each logical unit, execute: plan, code, test, review, remediate, review, commit, push, then run a greenfield situational test. Repeat until requirements are complete." - }, - "jarvis-review": { - "description": "Code review mode for Jarvis PRs", - "model": "opus", - "skills": ["jarvis"], - "guides": ["CODE-REVIEW"], - "systemPrompt": "Review code changes for quality, security, and adherence to Jarvis patterns." - } - } -} diff --git a/packages/mosaic/framework/systemd/user/README.md b/packages/mosaic/framework/systemd/user/README.md index f1b825d..56da71e 100644 --- a/packages/mosaic/framework/systemd/user/README.md +++ b/packages/mosaic/framework/systemd/user/README.md @@ -35,7 +35,7 @@ Example: ```dotenv MOSAIC_TMUX_SOCKET=mosaic-factory MOSAIC_AGENT_RUNTIME=claude -MOSAIC_AGENT_WORKDIR=/home/jarvis/src/mosaic-stack +MOSAIC_AGENT_WORKDIR=$HOME/src/your-project # Optional escape hatch for PoC/canary agents: # MOSAIC_AGENT_COMMAND=mosaic yolo claude ``` diff --git a/packages/mosaic/framework/tools/_scripts/mosaic-doctor b/packages/mosaic/framework/tools/_scripts/mosaic-doctor index 4a7466c..282adf0 100755 --- a/packages/mosaic/framework/tools/_scripts/mosaic-doctor +++ b/packages/mosaic/framework/tools/_scripts/mosaic-doctor @@ -309,7 +309,7 @@ if [[ -f "$pi_settings" ]]; then fi # Mosaic-specific skills presence check. -mosaic_skills=(mosaic-board mosaic-forge mosaic-prdy mosaic-macp mosaic-standards mosaic-prd mosaic-jarvis mosaic-setup-cicd) +mosaic_skills=(mosaic-board mosaic-forge mosaic-prdy mosaic-macp mosaic-standards mosaic-prd mosaic-setup-cicd) for skill_name in "${mosaic_skills[@]}"; do if [[ -d "$MOSAIC_HOME/skills/$skill_name" ]] || [[ -L "$MOSAIC_HOME/skills/$skill_name" ]]; then pass "Mosaic skill present: $skill_name" diff --git a/packages/mosaic/framework/tools/_scripts/mosaic-init b/packages/mosaic/framework/tools/_scripts/mosaic-init index 95ac5e7..57704c9 100755 --- a/packages/mosaic/framework/tools/_scripts/mosaic-init +++ b/packages/mosaic/framework/tools/_scripts/mosaic-init @@ -5,8 +5,8 @@ set -euo pipefail # # Usage: # mosaic-init # Interactive mode -# mosaic-init --name "Jarvis" --style direct # Flag overrides -# mosaic-init --name "Jarvis" --role "memory steward" --style direct \ +# mosaic-init --name "Mosaic Agent" --style direct # Flag overrides +# mosaic-init --name "Mosaic Agent" --role "memory steward" --style direct \ # --accessibility "ADHD-friendly chunking" --guardrails "Never auto-commit" MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}" @@ -50,7 +50,7 @@ Generate Mosaic identity and configuration files: Interactive by default. Use flags to skip prompts. Options: - --name Agent name (e.g., "Jarvis", "Assistant") + --name Agent name (e.g., "Mosaic Agent", "Assistant") --role Role description (e.g., "memory steward, execution partner") --style