mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

migrate mosaic home to xdg config path

Browse Source
This commit is contained in:
Jason Woltje
2026-02-17 14:12:02 -06:00
parent e16ff8af70
commit c7f363b2d2
60 changed files with 330 additions and 330 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
AUDIT-2026-02-17-framework-consistency.md
View File

@@ -4,7 +4,7 @@ Date: 2026-02-17
Scope:
- `~/src/mosaic-bootstrap`
- `~/src/agent-skills`
- Installed runtime check: `~/.mosaic`
- Installed runtime check: `~/.config/mosaic`
## Findings
@@ -31,7 +31,7 @@ Updated:
- `rails/qa/qa-queue-monitor.sh`
Change:
- Standardized handler paths to `~/.mosaic/rails/qa/...`.
- Standardized handler paths to `~/.config/mosaic/rails/qa/...`.
### MF-002 + MF-003 (conditional loading/context detection)
Updated:
@@ -42,7 +42,7 @@ Updated:
Change:
- Detection now recognizes both legacy and Mosaic patterns:
- `agent-guides` (legacy compatibility)
- `~/.mosaic/guides`
- `~/.config/mosaic/guides`
- `Conditional Loading`
- `Conditional Context`
@@ -58,8 +58,8 @@ Updated:
- `skills/pr-reviewer/SKILL.md`
Change:
- Replaced all `~/.claude/scripts/git/...` with `~/.mosaic/rails/git/...`.
- Replaced `~/.claude/skills/...` with `~/.mosaic/skills/...`.
- Replaced all `~/.claude/scripts/git/...` with `~/.config/mosaic/rails/git/...`.
- Replaced `~/.claude/skills/...` with `~/.config/mosaic/skills/...`.
### MF-006 (worktree skill docs hierarchy)
Updated:
@@ -84,7 +84,7 @@ Updated:
- `skills/systematic-debugging/CREATION-LOG.md`
Change:
- Standardized references to `~/.mosaic/skills`.
- Standardized references to `~/.config/mosaic/skills`.
- Removed stale Claude-only wording.
## Residual Legacy References (Intentional)
@@ -109,7 +109,7 @@ These are required to support existing Claude runtime integration while keeping
Executed checks:
- `rg -n "~/.claude|\\.claude/|agent-guides" ~/src/agent-skills -S`
- Result: no matches after remediation.
- `rg -n "~/.mosaic/rails/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
- `rg -n "~/.config/mosaic/rails/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
- Result: no invalid old-style QA rail paths remain.
- Installed runtime validation:
- `~/.mosaic` contains `rails/git`, `rails/portainer`, `rails/cicd`, `skills`, and `bin` tooling.
- `~/.config/mosaic` contains `rails/git`, `rails/portainer`, `rails/cicd`, `skills`, and `bin` tooling.

82
README.md
View File

@@ -1,6 +1,6 @@
# Mosaic Agent Framework
`~/.mosaic` is the universal userspace standards layer (master) for all agent runtimes.
`~/.config/mosaic` is the universal userspace standards layer (master) for all agent runtimes.
## Install Master Layer
@@ -13,15 +13,15 @@ bash ~/src/mosaic-bootstrap/install.sh
## What It Provides
- Shared standards document: `~/.mosaic/STANDARDS.md`
- Shared operational guides: `~/.mosaic/guides/`
- Shared quality rails/scripts: `~/.mosaic/rails/`
- Shared runtime-neutral presets/profiles: `~/.mosaic/profiles/`
- Runtime adapter docs: `~/.mosaic/adapters/`
- Runtime overlays: `~/.mosaic/runtime/`
- Shared wrapper commands: `~/.mosaic/bin/`
- Canonical skills directory: `~/.mosaic/skills`
- Local cross-runtime skills: `~/.mosaic/skills-local`
- Shared standards document: `~/.config/mosaic/STANDARDS.md`
- Shared operational guides: `~/.config/mosaic/guides/`
- Shared quality rails/scripts: `~/.config/mosaic/rails/`
- Shared runtime-neutral presets/profiles: `~/.config/mosaic/profiles/`
- Runtime adapter docs: `~/.config/mosaic/adapters/`
- Runtime overlays: `~/.config/mosaic/runtime/`
- Shared wrapper commands: `~/.config/mosaic/bin/`
- Canonical skills directory: `~/.config/mosaic/skills`
- Local cross-runtime skills: `~/.config/mosaic/skills-local`
## Universal Skills
@@ -31,7 +31,7 @@ The installer syncs skills from:
into:
- `~/.mosaic/skills`
- `~/.config/mosaic/skills`
Then links each skill into runtime directories:
@@ -39,51 +39,51 @@ Then links each skill into runtime directories:
- `~/.codex/skills`
- `~/.config/opencode/skills`
Local skills under `~/.mosaic/skills-local` are also linked into runtimes.
Local skills under `~/.config/mosaic/skills-local` are also linked into runtimes.
Manual commands:
```bash
~/.mosaic/bin/mosaic-sync-skills
~/.mosaic/bin/mosaic-sync-skills --link-only
~/.config/mosaic/bin/mosaic-sync-skills
~/.config/mosaic/bin/mosaic-sync-skills --link-only
```
## Runtime Compatibility Sync
Installer syncs runtime overlays as regular files (not symlinks):
- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` <- `~/.mosaic/runtime/claude/...`
- `~/.config/opencode/AGENTS.md` <- `~/.mosaic/runtime/opencode/AGENTS.md`
- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` <- `~/.config/mosaic/runtime/claude/...`
- `~/.config/opencode/AGENTS.md` <- `~/.config/mosaic/runtime/opencode/AGENTS.md`
Legacy symlink trees under `~/.claude` for migrated guides/scripts/templates/presets are pruned during sync.
Run manually:
```bash
~/.mosaic/bin/mosaic-link-runtime-assets
~/.mosaic/bin/mosaic-migrate-local-skills --apply
~/.config/mosaic/bin/mosaic-link-runtime-assets
~/.config/mosaic/bin/mosaic-migrate-local-skills --apply
```
Prune migrated legacy backups from runtime folders (dry-run by default):
```bash
~/.mosaic/bin/mosaic-prune-legacy-runtime --runtime claude
~/.mosaic/bin/mosaic-prune-legacy-runtime --runtime claude --apply
~/.config/mosaic/bin/mosaic-prune-legacy-runtime --runtime claude
~/.config/mosaic/bin/mosaic-prune-legacy-runtime --runtime claude --apply
```
Clean empty legacy runtime directories:
```bash
~/.mosaic/bin/mosaic-clean-runtime --runtime claude
~/.mosaic/bin/mosaic-clean-runtime --runtime claude --apply
~/.mosaic/bin/mosaic-clean-runtime --runtime claude --all-empty --apply
~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude
~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude --apply
~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude --all-empty --apply
```
Audit runtime drift:
```bash
~/.mosaic/bin/mosaic-doctor
~/.mosaic/bin/mosaic-doctor --fail-on-warn
~/.config/mosaic/bin/mosaic-doctor
~/.config/mosaic/bin/mosaic-doctor --fail-on-warn
```
Opt-out during install:
@@ -97,9 +97,9 @@ MOSAIC_SKIP_SKILLS_SYNC=1 bash ~/src/mosaic-bootstrap/install.sh
Inside any compatible repository:
```bash
~/.mosaic/bin/mosaic-session-start
~/.mosaic/bin/mosaic-critical
~/.mosaic/bin/mosaic-session-end
~/.config/mosaic/bin/mosaic-session-start
~/.config/mosaic/bin/mosaic-critical
~/.config/mosaic/bin/mosaic-session-end
```
Wrapper commands call local repo scripts under `scripts/agent/`.
@@ -108,18 +108,18 @@ Wrapper commands call local repo scripts under `scripts/agent/`.
Mosaic includes vendored quality-rails templates and scripts at:
- `~/.mosaic/rails/quality/`
- `~/.config/mosaic/rails/quality/`
Apply to a repo:
```bash
~/.mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo
```
Verify enforcement:
```bash
~/.mosaic/bin/mosaic-quality-verify --target /path/to/repo
~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/repo
```
Templates currently supported:
@@ -132,16 +132,16 @@ Templates currently supported:
Mosaic includes a runtime-agnostic orchestrator rail at:
- `~/.mosaic/rails/orchestrator-matrix/`
- `~/.config/mosaic/rails/orchestrator-matrix/`
Run from a bootstrapped repo:
```bash
~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.mosaic/bin/mosaic-orchestrator-run --once
~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
~/.mosaic/bin/mosaic-orchestrator-matrix-publish
~/.mosaic/bin/mosaic-orchestrator-matrix-consume
~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.config/mosaic/bin/mosaic-orchestrator-run --once
~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish
~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume
```
The controller reads/writes repo-local state in `.mosaic/orchestrator/` and emits
@@ -152,13 +152,13 @@ structured events to `.mosaic/orchestrator/events.ndjson` for Matrix bridge cons
Attach any repository/workspace to the master layer:
```bash
~/.mosaic/bin/mosaic-bootstrap-repo /path/to/repo
~/.config/mosaic/bin/mosaic-bootstrap-repo /path/to/repo
```
Attach and apply quality rails in one step:
```bash
~/.mosaic/bin/mosaic-bootstrap-repo --quality-template typescript-node /path/to/repo
~/.config/mosaic/bin/mosaic-bootstrap-repo --quality-template typescript-node /path/to/repo
```
This creates/updates:
@@ -172,11 +172,11 @@ This creates/updates:
Preview upgrades (dry-run):
```bash
~/.mosaic/bin/mosaic-upgrade-slaves
~/.config/mosaic/bin/mosaic-upgrade-slaves
```
Apply upgrades:
```bash
~/.mosaic/bin/mosaic-upgrade-slaves --apply
~/.config/mosaic/bin/mosaic-upgrade-slaves --apply
```

22
STANDARDS.md
View File

@@ -3,7 +3,7 @@
This file is the canonical standards contract for agent sessions on this machine.
Master/slave model:
- Master: `~/.mosaic` (this framework)
- Master: `~/.config/mosaic` (this framework)
- Slave: each repo bootstrapped via `mosaic-bootstrap-repo`
## Execution Model
@@ -12,16 +12,16 @@ Master/slave model:
2. Load project-local `AGENTS.md` next.
3. Respect repository-specific tooling and workflows.
4. Use lifecycle scripts when available (`scripts/agent/*.sh`).
5. Use shared rails/guides from `~/.mosaic` as canonical references.
5. Use shared rails/guides from `~/.config/mosaic` as canonical references.
## Non-Negotiables
- Data files are authoritative; generated views are derived artifacts.
- Pull before edits when collaborating in shared repos.
- Run validation checks before claiming completion.
- Apply quality rails from `~/.mosaic/rails/` when relevant (review, QA, git workflow).
- For project-level mechanical enforcement templates, use `~/.mosaic/rails/quality/` via `~/.mosaic/bin/mosaic-quality-apply`.
- For runtime-agnostic delegation/orchestration, use `~/.mosaic/rails/orchestrator-matrix/` with repo-local `.mosaic/orchestrator/` state.
- Apply quality rails from `~/.config/mosaic/rails/` when relevant (review, QA, git workflow).
- For project-level mechanical enforcement templates, use `~/.config/mosaic/rails/quality/` via `~/.config/mosaic/bin/mosaic-quality-apply`.
- For runtime-agnostic delegation/orchestration, use `~/.config/mosaic/rails/orchestrator-matrix/` with repo-local `.mosaic/orchestrator/` state.
- Avoid hardcoded secrets and token leakage in remotes/commits.
- Do not perform destructive git/file actions without explicit instruction.
@@ -44,15 +44,15 @@ If a repo does not expose these scripts, run equivalent local workflow commands
All runtime adapters should inject:
- `~/.mosaic/STANDARDS.md`
- `~/.config/mosaic/STANDARDS.md`
- project `AGENTS.md`
before task execution.
Runtime-compatible guides and rails are hosted at:
- `~/.mosaic/guides/`
- `~/.mosaic/rails/`
- `~/.mosaic/profiles/` (runtime-neutral domain/workflow/stack presets)
- `~/.mosaic/runtime/` (runtime-specific overlays)
- `~/.mosaic/skills-local/` (local private skills shared across runtimes)
- `~/.config/mosaic/guides/`
- `~/.config/mosaic/rails/`
- `~/.config/mosaic/profiles/` (runtime-neutral domain/workflow/stack presets)
- `~/.config/mosaic/runtime/` (runtime-specific overlays)
- `~/.config/mosaic/skills-local/` (local private skills shared across runtimes)

6
adapters/claude.md
View File

@@ -4,14 +4,14 @@ Use this adapter when running Claude CLI sessions.
## Required Context
1. `~/.mosaic/STANDARDS.md`
1. `~/.config/mosaic/STANDARDS.md`
2. `<repo>/AGENTS.md`
## Command Wrapper
Use wrapper commands from `~/.mosaic/bin/` for lifecycle rituals.
Use wrapper commands from `~/.config/mosaic/bin/` for lifecycle rituals.
## Migration Note
Project-local `.claude/commands/*.md` should call `scripts/agent/*.sh` so behavior stays runtime-neutral.
Guides and rails should resolve to `~/.mosaic/guides` and `~/.mosaic/rails` (linked into `~/.claude` for compatibility).
Guides and rails should resolve to `~/.config/mosaic/guides` and `~/.config/mosaic/rails` (linked into `~/.claude` for compatibility).

2
adapters/codex.md
View File

@@ -4,7 +4,7 @@ Use this adapter when running Codex CLI sessions.
## Required Context
1. `~/.mosaic/STANDARDS.md`
1. `~/.config/mosaic/STANDARDS.md`
2. `<repo>/AGENTS.md`
## Runtime Behavior

2
adapters/generic.md
View File

@@ -4,7 +4,7 @@ For runtimes without a first-class adapter yet.
## Required Context
1. Load `~/.mosaic/STANDARDS.md`
1. Load `~/.config/mosaic/STANDARDS.md`
2. Load project `AGENTS.md`
## Minimal Contract

14
bin/mosaic-bootstrap-repo
View File

@@ -27,12 +27,12 @@ if [[ ! -d "$TARGET_DIR" ]]; then
exit 1
fi
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
TEMPLATE_ROOT="$MOSAIC_HOME/templates/repo"
if [[ ! -d "$TEMPLATE_ROOT" ]]; then
echo "[mosaic] Missing templates at $TEMPLATE_ROOT" >&2
echo "[mosaic] Install or refresh framework: ~/.mosaic/install.sh" >&2
echo "[mosaic] Install or refresh framework: ~/.config/mosaic/install.sh" >&2
exit 1
fi
@@ -74,7 +74,7 @@ if [[ ! -f "$TARGET_DIR/AGENTS.md" ]]; then
## Standards Load Order
1. `~/.mosaic/STANDARDS.md`
1. `~/.config/mosaic/STANDARDS.md`
2. `AGENTS.md` (this file)
3. `.mosaic/repo-hooks.sh`
@@ -88,8 +88,8 @@ bash scripts/agent/session-end.sh
## Shared Rails
- Quality and orchestration guides: `~/.mosaic/guides/`
- Shared automation rails: `~/.mosaic/rails/`
- Quality and orchestration guides: `~/.config/mosaic/guides/`
- Shared automation rails: `~/.config/mosaic/rails/`
## Repo-Specific Notes
@@ -103,8 +103,8 @@ fi
echo "[mosaic] Repo bootstrap complete: $TARGET_DIR"
echo "[mosaic] Next: edit $TARGET_DIR/.mosaic/repo-hooks.sh with project workflows"
echo "[mosaic] Optional: apply quality rails via ~/.mosaic/bin/mosaic-quality-apply --template <template> --target $TARGET_DIR"
echo "[mosaic] Optional: run orchestrator rail via ~/.mosaic/bin/mosaic-orchestrator-matrix-cycle"
echo "[mosaic] Optional: apply quality rails via ~/.config/mosaic/bin/mosaic-quality-apply --template <template> --target $TARGET_DIR"
echo "[mosaic] Optional: run orchestrator rail via ~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle"
if [[ -n "$QUALITY_TEMPLATE" ]]; then
if [[ -x "$MOSAIC_HOME/bin/mosaic-quality-apply" ]]; then

2
bin/mosaic-doctor
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
FAIL_ON_WARN=0
VERBOSE=0

2
bin/mosaic-link-runtime-assets
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
backup_stamp="$(date +%Y%m%d%H%M%S)"
copy_file_managed() {

4
bin/mosaic-migrate-local-skills
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
APPLY=0
usage() {
@@ -9,7 +9,7 @@ usage() {
Usage: $(basename "$0") [--apply]
Migrate runtime-local skill directories (e.g. ~/.claude/skills/jarvis) to Mosaic-managed
skills by replacing local directories with symlinks to ~/.mosaic/skills-local.
skills by replacing local directories with symlinks to ~/.config/mosaic/skills-local.
Default mode is dry-run.
USAGE

2
bin/mosaic-orchestrator-matrix-consume
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
BRIDGE="$MOSAIC_HOME/rails/orchestrator-matrix/transport/matrix_transport.py"
if [[ ! -f "$BRIDGE" ]]; then

2
bin/mosaic-orchestrator-matrix-cycle
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
consume="$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-consume"
run="$MOSAIC_HOME/bin/mosaic-orchestrator-run"

2
bin/mosaic-orchestrator-matrix-publish
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
BRIDGE="$MOSAIC_HOME/rails/orchestrator-matrix/transport/matrix_transport.py"
if [[ ! -f "$BRIDGE" ]]; then

2
bin/mosaic-orchestrator-run
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
CTRL="$MOSAIC_HOME/rails/orchestrator-matrix/controller/mosaic_orchestrator.py"
if [[ ! -f "$CTRL" ]]; then

4
bin/mosaic-prune-legacy-runtime
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
RUNTIME="claude"
APPLY=0
@@ -10,7 +10,7 @@ usage() {
Usage: $(basename "$0") [options]
Remove legacy runtime files that were preserved as *.mosaic-bak-* after Mosaic linking.
Only removes backups when the active file is a symlink to ~/.mosaic.
Only removes backups when the active file is a symlink to ~/.config/mosaic.
Options:
--runtime <name> Runtime to prune (default: claude)

2
bin/mosaic-quality-apply
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
TARGET_DIR="$(pwd)"
TEMPLATE=""

2
bin/mosaic-quality-verify
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
TARGET_DIR="$(pwd)"
usage() {

10
bin/mosaic-sync-skills
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
SKILLS_REPO_URL="${MOSAIC_SKILLS_REPO_URL:-https://git.mosaicstack.dev/mosaic/agent-skills.git}"
SKILLS_REPO_DIR="${MOSAIC_SKILLS_REPO_DIR:-$MOSAIC_HOME/sources/agent-skills}"
MOSAIC_SKILLS_DIR="$MOSAIC_HOME/skills"
@@ -14,17 +14,17 @@ usage() {
cat <<USAGE
Usage: $(basename "$0") [options]
Sync canonical skills into ~/.mosaic/skills and link all Mosaic skills into runtime skill directories.
Sync canonical skills into ~/.config/mosaic/skills and link all Mosaic skills into runtime skill directories.
Options:
--link-only Skip git clone/pull and only relink from ~/.mosaic/{skills,skills-local}
--link-only Skip git clone/pull and only relink from ~/.config/mosaic/{skills,skills-local}
--no-link Sync canonical skills but do not update runtime links
-h, --help Show help
Env:
MOSAIC_HOME Default: ~/.mosaic
MOSAIC_HOME Default: ~/.config/mosaic
MOSAIC_SKILLS_REPO_URL Default: https://git.mosaicstack.dev/mosaic/agent-skills.git
MOSAIC_SKILLS_REPO_DIR Default: ~/.mosaic/sources/agent-skills
MOSAIC_SKILLS_REPO_DIR Default: ~/.config/mosaic/sources/agent-skills
USAGE
}

4
bin/mosaic-upgrade-slaves
View File

@@ -1,7 +1,7 @@
#!/usr/bin/env bash
set -euo pipefail
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
BOOTSTRAP_CMD="$MOSAIC_HOME/bin/mosaic-bootstrap-repo"
roots=("$HOME/src")
@@ -45,7 +45,7 @@ done
if [[ ! -x "$BOOTSTRAP_CMD" ]]; then
echo "[mosaic-upgrade] Missing bootstrap command: $BOOTSTRAP_CMD" >&2
echo "[mosaic-upgrade] Install/refresh framework first: ~/.mosaic/install.sh" >&2
echo "[mosaic-upgrade] Install/refresh framework first: ~/.config/mosaic/install.sh" >&2
exit 1
fi

2
guides/authentication.md
View File

@@ -1,7 +1,7 @@
# Authentication & Authorization Guide
## Before Starting
1. Check assigned issue: `~/.mosaic/rails/git/issue-list.sh -a @me`
1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
2. Review existing auth implementation in codebase
3. Review Vault secrets structure: `docs/vault-secrets-structure.md`

6
guides/backend.md
View File

@@ -1,7 +1,7 @@
# Backend Development Guide
## Before Starting
1. Check assigned issue: `~/.mosaic/rails/git/issue-list.sh -a @me`
1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Review API contracts and database schema
@@ -47,7 +47,7 @@
- Use project's established auth pattern
- Validate tokens on every request
- Check permissions before operations
- See `~/.mosaic/guides/authentication.md` for details
- See `~/.config/mosaic/guides/authentication.md` for details
## Testing Requirements (TDD)
1. Write tests BEFORE implementation
@@ -73,7 +73,7 @@ class TestResourceEndpoint:
## Code Style
- Follow Google Style Guide for your language
- **TypeScript: Follow `~/.mosaic/guides/typescript.md` — MANDATORY**
- **TypeScript: Follow `~/.config/mosaic/guides/typescript.md` — MANDATORY**
- Use linter/formatter from project configuration
- Keep functions focused and small
- Document complex business logic

42
guides/bootstrap.md
View File

@@ -15,7 +15,7 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
```bash
# Automated bootstrap (recommended)
~/.mosaic/rails/bootstrap/init-project.sh \
~/.config/mosaic/rails/bootstrap/init-project.sh \
--name "my-project" \
--type "nestjs-nextjs" \
--repo "https://git.mosaicstack.dev/owner/repo"
@@ -24,8 +24,8 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="What this project does"
export TASK_PREFIX="MP"
envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
envsubst < ~/.mosaic/templates/agent/AGENTS.md.template > AGENTS.md
envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
```
---
@@ -86,12 +86,12 @@ export TASK_PREFIX="MP"
# Use tech-stack-specific template if available
TYPE=$(detect_project_type)
TEMPLATE_DIR="$HOME/.mosaic/templates/agent/projects/$TYPE"
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
if [[ -d "$TEMPLATE_DIR" ]]; then
envsubst < "$TEMPLATE_DIR/CLAUDE.md.template" > CLAUDE.md
else
envsubst < "$HOME/.mosaic/templates/agent/CLAUDE.md.template" > CLAUDE.md
envsubst < "$HOME/.config/mosaic/templates/agent/CLAUDE.md.template" > CLAUDE.md
fi
```
@@ -116,7 +116,7 @@ export LINT_COMMAND="ruff check ."
export TYPECHECK_COMMAND="mypy ."
export QUALITY_GATES="ruff check . && mypy . && pytest tests/"
envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
```
### Required Sections
@@ -141,12 +141,12 @@ The `AGENTS.md` file contains agent-specific patterns, gotchas, and orchestrator
```bash
TYPE=$(detect_project_type)
TEMPLATE_DIR="$HOME/.mosaic/templates/agent/projects/$TYPE"
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
if [[ -d "$TEMPLATE_DIR" ]]; then
envsubst < "$TEMPLATE_DIR/AGENTS.md.template" > AGENTS.md
else
envsubst < "$HOME/.mosaic/templates/agent/AGENTS.md.template" > AGENTS.md
envsubst < "$HOME/.config/mosaic/templates/agent/AGENTS.md.template" > AGENTS.md
fi
```
@@ -175,10 +175,10 @@ mkdir -p docs/reports
```bash
# Use the init script
~/.mosaic/rails/bootstrap/init-repo-labels.sh
~/.config/mosaic/rails/bootstrap/init-repo-labels.sh
# Or manually create standard labels
~/.mosaic/rails/git/issue-create.sh # (labels are created on first use)
~/.config/mosaic/rails/git/issue-create.sh # (labels are created on first use)
```
### Standard Labels
@@ -198,7 +198,7 @@ mkdir -p docs/reports
Create the first milestone for MVP:
```bash
~/.mosaic/rails/git/milestone-create.sh -t "0.1.0" -d "MVP - Minimum Viable Product"
~/.config/mosaic/rails/git/milestone-create.sh -t "0.1.0" -d "MVP - Minimum Viable Product"
```
---
@@ -210,8 +210,8 @@ Create the first milestone for MVP:
```bash
# Copy Codex review pipeline
mkdir -p .woodpecker/schemas
cp ~/.mosaic/rails/codex/woodpecker/codex-review.yml .woodpecker/
cp ~/.mosaic/rails/codex/schemas/*.json .woodpecker/schemas/
cp ~/.config/mosaic/rails/codex/woodpecker/codex-review.yml .woodpecker/
cp ~/.config/mosaic/rails/codex/schemas/*.json .woodpecker/schemas/
# Add codex_api_key secret to Woodpecker CI dashboard
```
@@ -243,7 +243,7 @@ grep -c "Code Review" CLAUDE.md
eval "$(grep -A1 'Quality Gates' CLAUDE.md | tail -1)"
# Test Codex review (if configured)
~/.mosaic/rails/codex/codex-code-review.sh --help
~/.config/mosaic/rails/codex/codex-code-review.sh --help
```
---
@@ -254,15 +254,15 @@ eval "$(grep -A1 'Quality Gates' CLAUDE.md | tail -1)"
| Template | Path | Purpose |
|----------|------|---------|
| `CLAUDE.md.template` | `~/.mosaic/templates/agent/` | Generic project CLAUDE.md |
| `AGENTS.md.template` | `~/.mosaic/templates/agent/` | Generic agent context |
| `CLAUDE.md.template` | `~/.config/mosaic/templates/agent/` | Generic project CLAUDE.md |
| `AGENTS.md.template` | `~/.config/mosaic/templates/agent/` | Generic agent context |
### Tech-Stack Templates
| Stack | Path | Includes |
|-------|------|----------|
| NestJS + Next.js | `~/.mosaic/templates/agent/projects/nestjs-nextjs/` | CLAUDE.md, AGENTS.md |
| Django | `~/.mosaic/templates/agent/projects/django/` | CLAUDE.md, AGENTS.md |
| NestJS + Next.js | `~/.config/mosaic/templates/agent/projects/nestjs-nextjs/` | CLAUDE.md, AGENTS.md |
| Django | `~/.config/mosaic/templates/agent/projects/django/` | CLAUDE.md, AGENTS.md |
### Orchestrator Templates
@@ -305,7 +305,7 @@ eval "$(grep -A1 'Quality Gates' CLAUDE.md | tail -1)"
Full project bootstrap with interactive and flag-based modes:
```bash
~/.mosaic/rails/bootstrap/init-project.sh \
~/.config/mosaic/rails/bootstrap/init-project.sh \
--name "My Project" \
--type "nestjs-nextjs" \
--repo "https://git.mosaicstack.dev/owner/repo" \
@@ -318,7 +318,7 @@ Full project bootstrap with interactive and flag-based modes:
Initialize standard labels and MVP milestone:
```bash
~/.mosaic/rails/bootstrap/init-repo-labels.sh
~/.config/mosaic/rails/bootstrap/init-repo-labels.sh
```
---
@@ -335,4 +335,4 @@ After bootstrapping, verify:
- [ ] Quality gates run successfully
- [ ] `.env.example` exists (if project uses env vars)
- [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)
- [ ] Codex review scripts accessible (`~/.mosaic/rails/codex/`)
- [ ] Codex review scripts accessible (`~/.config/mosaic/rails/codex/`)

2
guides/code-review.md
View File

@@ -64,7 +64,7 @@
### Getting Context
```bash
# List the issue being addressed
~/.mosaic/rails/git/issue-list.sh -i {issue-number}
~/.config/mosaic/rails/git/issue-list.sh -i {issue-number}
# View the changes
git diff main...HEAD

4
guides/frontend.md
View File

@@ -1,7 +1,7 @@
# Frontend Development Guide
## Before Starting
1. Check assigned issue in git repo: `~/.mosaic/rails/git/issue-list.sh -a @me`
1. Check assigned issue in git repo: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Review existing components and patterns in the codebase
@@ -49,7 +49,7 @@ describe('ComponentName', () => {
## Code Style
- Follow Google JavaScript/TypeScript Style Guide
- **TypeScript: Follow `~/.mosaic/guides/typescript.md` — MANDATORY**
- **TypeScript: Follow `~/.config/mosaic/guides/typescript.md` — MANDATORY**
- Use ESLint/Prettier configuration from project
- Prefer functional components over class components (React)
- TypeScript strict mode is REQUIRED, not optional

2
guides/infrastructure.md
View File

@@ -1,7 +1,7 @@
# Infrastructure & DevOps Guide
## Before Starting
1. Check assigned issue: `~/.mosaic/rails/git/issue-list.sh -a @me`
1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Review existing infrastructure configuration

20
guides/orchestrator.md
View File

@@ -50,8 +50,8 @@ Choose one delegation mode at session start:
Matrix rail mode commands:
```bash
~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
```
In Matrix rail mode, keep `docs/tasks.md` as canonical project tracking and use
@@ -186,7 +186,7 @@ Use these heuristics based on task type:
Create ONE issue per phase using git scripts:
```bash
~/.mosaic/rails/git/issue-create.sh \
~/.config/mosaic/rails/git/issue-create.sh \
-t "Phase 1: Critical Security Fixes" \
-b "$(cat <<'EOF'
## Findings
@@ -309,10 +309,10 @@ Run review when the worker's result includes code changes (commits). Skip for ta
cd {project_path}
# Code quality review
~/.mosaic/rails/codex/codex-code-review.sh -b {base_branch} -o /tmp/review-{task_id}.json
~/.config/mosaic/rails/codex/codex-code-review.sh -b {base_branch} -o /tmp/review-{task_id}.json
# Security review
~/.mosaic/rails/codex/codex-security-review.sh -b {base_branch} -o /tmp/security-{task_id}.json
~/.config/mosaic/rails/codex/codex-security-review.sh -b {base_branch} -o /tmp/security-{task_id}.json
```
### Step 2: Parse Review Results
@@ -373,7 +373,7 @@ Review the code changes on branch {branch} against {base_branch}.
- Security (OWASP Top 10, secrets, injection)
- Testing (coverage, quality)
- Code quality (complexity, duplication)
3. Reference: ~/.mosaic/guides/code-review.md
3. Reference: ~/.config/mosaic/guides/code-review.md
Report findings as JSON:
```json
@@ -448,8 +448,8 @@ Construct this from the task row and pass to worker via Task tool:
## Git Scripts
For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
- `~/.mosaic/rails/git/issue-view.sh -i {N}`
- `~/.mosaic/rails/git/pr-create.sh -t "Title" -b "Desc" -B develop`
- `~/.config/mosaic/rails/git/issue-view.sh -i {N}`
- `~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Desc" -B develop`
Standard git commands (pull, commit, push, checkout) are fine.
@@ -706,7 +706,7 @@ Next: MS-SEC-004
### Cross-Project Learnings
Universal heuristics are maintained in `~/.mosaic/guides/orchestrator-learnings.md`.
Universal heuristics are maintained in `~/.config/mosaic/guides/orchestrator-learnings.md`.
After completing a milestone, review variance patterns and propose updates to the universal guide.
---
@@ -858,7 +858,7 @@ Remediate findings from the codebase review.
- Task prefix: {PREFIX} (e.g., MS, UC)
## Protocol
Read ~/.mosaic/guides/orchestrator.md for full instructions.
Read ~/.config/mosaic/guides/orchestrator.md for full instructions.
## Start
Bootstrap from the review report, then execute until complete.

2
guides/qa-testing.md
View File

@@ -1,7 +1,7 @@
# QA & Testing Guide
## Before Starting
1. Check assigned issue: `~/.mosaic/rails/git/issue-list.sh -a @me`
1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Review existing test structure and patterns

4
install.sh
View File

@@ -2,7 +2,7 @@
set -euo pipefail
SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
TARGET_DIR="${MOSAIC_HOME:-$HOME/.mosaic}"
TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
mkdir -p "$TARGET_DIR"
@@ -39,7 +39,7 @@ fi
echo "[mosaic-install] Running health audit"
if ! "$TARGET_DIR/bin/mosaic-doctor"; then
echo "[mosaic-install] WARNING: doctor reported issues (run ~/.mosaic/bin/mosaic-doctor --fail-on-warn)" >&2
echo "[mosaic-install] WARNING: doctor reported issues (run ~/.config/mosaic/bin/mosaic-doctor --fail-on-warn)" >&2
fi
echo "[mosaic-install] Add to PATH: export PATH=\"$TARGET_DIR/bin:$PATH\""

6
profiles/README.md
View File

@@ -10,12 +10,12 @@ Profiles are runtime-neutral context packs that can be consumed by any agent run
## Runtime Split
- Runtime-neutral content belongs here under `~/.mosaic/profiles`.
- Runtime-specific settings belong under `~/.mosaic/runtime/<runtime>/...`.
- Runtime-neutral content belongs here under `~/.config/mosaic/profiles`.
- Runtime-specific settings belong under `~/.config/mosaic/runtime/<runtime>/...`.
Current runtime overlay example:
- `~/.mosaic/runtime/claude/settings-overlays/jarvis-ralph.json`
- `~/.config/mosaic/runtime/claude/settings-overlays/jarvis-ralph.json`
## Claude Compatibility

6
rails/bootstrap/agent-lint.sh
View File

@@ -105,7 +105,7 @@ check_agents_md() {
# Check conditional loading/context (references guides or conditional section)
check_conditional_loading() {
local claude_md="$1/CLAUDE.md"
[[ -f "$claude_md" ]] && grep -qi "agent-guides\|~/.mosaic/guides\|conditional.*loading\|conditional.*documentation\|conditional.*context" "$claude_md" 2>/dev/null
[[ -f "$claude_md" ]] && grep -qi "agent-guides\|~/.config/mosaic/guides\|conditional.*loading\|conditional.*documentation\|conditional.*context" "$claude_md" 2>/dev/null
}
# Check quality gates
@@ -214,9 +214,9 @@ JSONEOF
if $FIX_HINT && ! $JSON_OUTPUT; then
if [[ "$has_claude" == "MISS" || "$has_agents" == "MISS" ]]; then
echo " ${DIM}Fix: ~/.mosaic/rails/bootstrap/init-project.sh --name \"$name\" --type auto${NC}"
echo " ${DIM}Fix: ~/.config/mosaic/rails/bootstrap/init-project.sh --name \"$name\" --type auto${NC}"
elif [[ "$has_guides" == "MISS" ]]; then
echo " ${DIM}Fix: ~/.mosaic/rails/bootstrap/agent-upgrade.sh $dir --section conditional-loading${NC}"
echo " ${DIM}Fix: ~/.config/mosaic/rails/bootstrap/agent-upgrade.sh $dir --section conditional-loading${NC}"
fi
fi

6
rails/bootstrap/agent-upgrade.sh
View File

@@ -18,8 +18,8 @@ set -euo pipefail
# Defaults
SRC_DIR="$HOME/src"
FRAGMENTS_DIR="$HOME/.mosaic/templates/agent/fragments"
TEMPLATES_DIR="$HOME/.mosaic/templates/agent"
FRAGMENTS_DIR="$HOME/.config/mosaic/templates/agent/fragments"
TEMPLATES_DIR="$HOME/.config/mosaic/templates/agent"
DRY_RUN=false
ALL_PROJECTS=false
TARGET_PATH=""
@@ -135,7 +135,7 @@ inject_fragment() {
# Determine detection pattern for this fragment
local detect_pattern
case "$fragment_name" in
conditional-loading) detect_pattern="agent-guides\|~/.mosaic/guides\|Conditional.*Loading\|Conditional.*Documentation\|Conditional.*Context" ;;
conditional-loading) detect_pattern="agent-guides\|~/.config/mosaic/guides\|Conditional.*Loading\|Conditional.*Documentation\|Conditional.*Context" ;;
commit-format) detect_pattern="<type>.*#issue\|Types:.*feat.*fix" ;;
secrets) detect_pattern="NEVER hardcode secrets\|\.env.example.*committed" ;;
multi-agent) detect_pattern="Multi-Agent Coordination\|pull --rebase.*before" ;;

8
rails/bootstrap/init-project.sh
View File

@@ -8,8 +8,8 @@
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
TEMPLATE_DIR="$HOME/.mosaic/templates/agent"
GIT_SCRIPT_DIR="$HOME/.mosaic/rails/git"
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent"
GIT_SCRIPT_DIR="$HOME/.config/mosaic/rails/git"
# Defaults
PROJECT_NAME=""
@@ -373,7 +373,7 @@ echo "Created docs/scratchpads/, docs/reports/, docs/templates/"
# Set up CI/CD pipeline
if [[ "$SKIP_CI" != true ]]; then
CODEX_DIR="$HOME/.mosaic/rails/codex"
CODEX_DIR="$HOME/.config/mosaic/rails/codex"
if [[ -d "$CODEX_DIR/woodpecker" ]]; then
mkdir -p .woodpecker/schemas
cp "$CODEX_DIR/woodpecker/codex-review.yml" .woodpecker/
@@ -386,7 +386,7 @@ fi
# Generate Docker build/push/link pipeline steps
if [[ "$CICD_DOCKER" == true ]]; then
CICD_SCRIPT="$HOME/.mosaic/rails/cicd/generate-docker-steps.sh"
CICD_SCRIPT="$HOME/.config/mosaic/rails/cicd/generate-docker-steps.sh"
if [[ -x "$CICD_SCRIPT" ]]; then
# Parse org and repo from git remote
CICD_REGISTRY=""

2
rails/bootstrap/init-repo-labels.sh
View File

@@ -7,7 +7,7 @@
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
GIT_SCRIPT_DIR="$HOME/.mosaic/rails/git"
GIT_SCRIPT_DIR="$HOME/.config/mosaic/rails/git"
source "$GIT_SCRIPT_DIR/detect-platform.sh"
SKIP_MILESTONE=false

30
rails/codex/README.md
View File

@@ -50,45 +50,45 @@ Security vulnerability review focusing on:
```bash
# Code review
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
# Security review
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```
### Review a Pull Request
```bash
# Review and post findings as a PR comment
~/.mosaic/rails/codex/codex-code-review.sh -n 42
~/.config/mosaic/rails/codex/codex-code-review.sh -n 42
# Security review and post to PR
~/.mosaic/rails/codex/codex-security-review.sh -n 42
~/.config/mosaic/rails/codex/codex-security-review.sh -n 42
```
### Review Against Base Branch
```bash
# Code review changes vs main
~/.mosaic/rails/codex/codex-code-review.sh -b main
~/.config/mosaic/rails/codex/codex-code-review.sh -b main
# Security review changes vs develop
~/.mosaic/rails/codex/codex-security-review.sh -b develop
~/.config/mosaic/rails/codex/codex-security-review.sh -b develop
```
### Review a Specific Commit
```bash
~/.mosaic/rails/codex/codex-code-review.sh -c abc123f
~/.mosaic/rails/codex/codex-security-review.sh -c abc123f
~/.config/mosaic/rails/codex/codex-code-review.sh -c abc123f
~/.config/mosaic/rails/codex/codex-security-review.sh -c abc123f
```
### Save Results to File
```bash
# Save JSON output
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted -o review-results.json
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted -o security-results.json
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted -o review-results.json
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted -o security-results.json
```
## Options
@@ -113,12 +113,12 @@ Automated PR reviews in CI pipelines.
1. **Copy the pipeline template to your repo:**
```bash
cp ~/.mosaic/rails/codex/woodpecker/codex-review.yml your-repo/.woodpecker/
cp ~/.config/mosaic/rails/codex/woodpecker/codex-review.yml your-repo/.woodpecker/
```
2. **Copy the schemas directory:**
```bash
cp -r ~/.mosaic/rails/codex/schemas your-repo/.woodpecker/
cp -r ~/.config/mosaic/rails/codex/schemas your-repo/.woodpecker/
```
3. **Add Codex API key to Woodpecker:**
@@ -203,7 +203,7 @@ Automated PR reviews in CI pipelines.
## Platform Support
Works with both **GitHub** and **Gitea** via the shared `~/.mosaic/rails/git/` infrastructure:
Works with both **GitHub** and **Gitea** via the shared `~/.config/mosaic/rails/git/` infrastructure:
- Auto-detects platform from git remote
- Posts PR comments using `gh` (GitHub) or `tea` (Gitea)
- Unified interface across both platforms
@@ -260,6 +260,6 @@ For best results, use `gpt-5.2-codex` or newer for strongest review accuracy.
## See Also
- `~/.mosaic/guides/code-review.md` — Manual code review checklist
- `~/.mosaic/rails/git/` — Git helper scripts (issue/PR management)
- `~/.config/mosaic/guides/code-review.md` — Manual code review checklist
- `~/.config/mosaic/rails/git/` — Git helper scripts (issue/PR management)
- OpenAI Codex CLI docs: https://developers.openai.com/codex/cli/

10
rails/orchestrator-matrix/README.md
View File

@@ -35,26 +35,26 @@ The controller expects this layout in each bootstrapped repo:
From a bootstrapped repo:
```bash
~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.mosaic/bin/mosaic-orchestrator-run --once
~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
~/.config/mosaic/bin/mosaic-orchestrator-run --once
```
Continuous loop:
```bash
~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
```
Publish new orchestrator events to Matrix:
```bash
~/.mosaic/bin/mosaic-orchestrator-matrix-publish
~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish
```
Consume Matrix task messages into `tasks.json`:
```bash
~/.mosaic/bin/mosaic-orchestrator-matrix-consume
~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume
```
## Matrix Note

2
rails/qa/qa-hook-handler.sh
View File

@@ -1,6 +1,6 @@
#!/bin/bash
# Universal QA hook handler with robust error handling
# Location: ~/.mosaic/rails/qa/qa-hook-handler.sh
# Location: ~/.config/mosaic/rails/qa/qa-hook-handler.sh
# Don't exit on unset variables initially to handle missing params gracefully
set -eo pipefail

6
rails/qa/qa-hook-stdin.sh
View File

@@ -1,6 +1,6 @@
#!/bin/bash
# QA Hook handler that reads from stdin
# Location: ~/.mosaic/rails/qa/qa-hook-stdin.sh
# Location: ~/.config/mosaic/rails/qa/qa-hook-stdin.sh
set -eo pipefail
@@ -51,9 +51,9 @@ if ! [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx|mjs|cjs)$ ]]; then
fi
# Call the main QA handler with extracted parameters
if [ -f ~/.mosaic/rails/qa/qa-hook-handler.sh ]; then
if [ -f ~/.config/mosaic/rails/qa/qa-hook-handler.sh ]; then
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Calling QA handler for $FILE_PATH" >> "$LOG_FILE"
~/.mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH" 2>&1 | tee -a "$LOG_FILE"
~/.config/mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH" 2>&1 | tee -a "$LOG_FILE"
else
echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] QA handler script not found" >> "$LOG_FILE"
fi

2
rails/qa/qa-hook-wrapper.sh
View File

@@ -13,7 +13,7 @@ echo "[$(date '+%Y-%m-%d %H:%M:%S')] Hook wrapper called: tool=$TOOL_NAME file=$
# Call the actual QA handler if we have a file
if [ -n "$FILE_PATH" ]; then
~/.mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH"
~/.config/mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH"
else
echo "[$(date '+%Y-%m-%d %H:%M:%S')] No file path available for QA check" >> logs/qa-automation.log 2>/dev/null || true
fi

2
rails/qa/qa-queue-monitor.sh
View File

@@ -1,6 +1,6 @@
#!/bin/bash
# Monitor QA queues with graceful handling of missing directories
# Location: ~/.mosaic/rails/qa/qa-queue-monitor.sh
# Location: ~/.config/mosaic/rails/qa/qa-queue-monitor.sh
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

2
rails/qa/remediation-hook-handler.sh
View File

@@ -1,6 +1,6 @@
#!/bin/bash
# Universal remediation hook handler with error recovery
# Location: ~/.mosaic/rails/qa/remediation-hook-handler.sh
# Location: ~/.config/mosaic/rails/qa/remediation-hook-handler.sh
set -euo pipefail

6
rails/quality/README.md
View File

@@ -19,7 +19,7 @@ Based on real-world validation of 50 issues in a production codebase:
### New Project
```bash
# Apply template from Mosaic
~/.mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/project
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/project
# Install dependencies
cd /path/to/project
@@ -29,13 +29,13 @@ npm install
npx husky install
# Verify enforcement is working
~/.mosaic/bin/mosaic-quality-verify --target /path/to/project
~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/project
```
### Existing Project
```bash
# Same as above - works for new or existing projects
~/.mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/existing-project
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/existing-project
```
## 🛡️ What You Get

2
rails/quality/scripts/install.sh
View File

@@ -71,5 +71,5 @@ echo ""
echo "Next steps:"
echo "1. Install dependencies: npm install"
echo "2. Initialize husky: npx husky install"
echo "3. Run verification: ~/.mosaic/bin/mosaic-quality-verify --target $TARGET_DIR"
echo "3. Run verification: ~/.config/mosaic/bin/mosaic-quality-verify --target $TARGET_DIR"
echo ""

118
runtime/claude/CLAUDE.md
View File

@@ -1,10 +1,10 @@
# Mosaic Universal Standards (Machine-Wide)
Before applying any runtime-specific guidance in this file, load and apply:
- `~/.mosaic/STANDARDS.md`
- `~/.config/mosaic/STANDARDS.md`
- project-local `AGENTS.md`
`~/.mosaic` is the canonical cross-agent standards layer. This `CLAUDE.md` is an adapter layer for Claude-specific capabilities only.
`~/.config/mosaic` is the canonical cross-agent standards layer. This `CLAUDE.md` is an adapter layer for Claude-specific capabilities only.
---
@@ -17,11 +17,11 @@ Before applying any runtime-specific guidance in this file, load and apply:
## Skills System
**Skills are available in `~/.mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.
**Skills are available in `~/.config/mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.
**Load a skill by reading its SKILL.md:**
```
Read ~/.mosaic/skills/<skill-name>/SKILL.md
Read ~/.config/mosaic/skills/<skill-name>/SKILL.md
```
### Skill Dispatch Table — Load the right skills for your task
@@ -66,7 +66,7 @@ Read ~/.mosaic/skills/<skill-name>/SKILL.md
When spawning workers via `claude -p`, include skill loading in the kickstart:
```bash
claude -p "Read ~/.mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
```
For Ralph prd.json stories, add a `skills` field:
@@ -118,7 +118,7 @@ claude -p "Implement US-001 from prd.json following Ralph pattern"
2. Convert to Ralph: `Load the ralph skill and convert tasks/prd-[name].md to prd.json`
3. Run Ralph: `./scripts/ralph/ralph.sh`
**For full Ralph guide:** `~/.mosaic/guides/ralph-autonomous.md`
**For full Ralph guide:** `~/.config/mosaic/guides/ralph-autonomous.md`
## AGENTS.md Pattern
@@ -148,40 +148,40 @@ When starting work on a **new project** that lacks `CLAUDE.md` or `AGENTS.md`, b
```bash
# Automated (recommended)
~/.mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto
~/.config/mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto
# Or manually with templates
export PROJECT_NAME="Project Name" PROJECT_DESCRIPTION="What it does" TASK_PREFIX="PN"
envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
envsubst < ~/.mosaic/templates/agent/AGENTS.md.template > AGENTS.md
envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
```
**Available project types:** `nestjs-nextjs`, `django`, `typescript`, `python-fastapi`, `python-library`, `generic` (auto-detected from project files).
**Templates:** `~/.mosaic/templates/agent/` (generic) and `~/.mosaic/templates/agent/projects/<type>/` (tech-stack specific).
**Templates:** `~/.config/mosaic/templates/agent/` (generic) and `~/.config/mosaic/templates/agent/projects/<type>/` (tech-stack specific).
**Fragments:** `~/.mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
**Fragments:** `~/.config/mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
**Full guide:** `~/.mosaic/guides/bootstrap.md`
**Full guide:** `~/.config/mosaic/guides/bootstrap.md`
### Agent Configuration Health
```bash
# Audit all projects for missing CLAUDE.md, AGENTS.md, agent-guide references
~/.mosaic/rails/bootstrap/agent-lint.sh
~/.config/mosaic/rails/bootstrap/agent-lint.sh
# Audit with fix suggestions
~/.mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint
~/.config/mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint
# Non-destructively upgrade existing projects (inject missing sections)
~/.mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run # Preview
~/.mosaic/rails/bootstrap/agent-upgrade.sh --all # Apply
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run # Preview
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all # Apply
# Upgrade a single project
~/.mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
```
**Spec:** `~/.mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.
**Spec:** `~/.config/mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.
## Issue Tracking (Git-Based)
@@ -210,7 +210,7 @@ Use consistent labels across projects:
- Post-release: `X.0.0` for breaking changes
### Git Scripts (PREFERRED for Gitea/GitHub operations)
Cross-platform helpers at `~/.mosaic/rails/git/` (work with both Gitea and GitHub):
Cross-platform helpers at `~/.config/mosaic/rails/git/` (work with both Gitea and GitHub):
**Why use these scripts?**
- ✅ Auto-detect platform (Gitea vs GitHub)
@@ -220,37 +220,37 @@ Cross-platform helpers at `~/.mosaic/rails/git/` (work with both Gitea and GitHu
**Issues:**
```bash
~/.mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
~/.mosaic/rails/git/issue-list.sh -s open -l "bug"
~/.mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration" # Works with milestone names!
~/.mosaic/rails/git/issue-view.sh -i 42 # View issue details
~/.mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
~/.mosaic/rails/git/issue-assign.sh -i 42 -a "username"
~/.mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
~/.mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
~/.mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
~/.config/mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
~/.config/mosaic/rails/git/issue-list.sh -s open -l "bug"
~/.config/mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration" # Works with milestone names!
~/.config/mosaic/rails/git/issue-view.sh -i 42 # View issue details
~/.config/mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
~/.config/mosaic/rails/git/issue-assign.sh -i 42 -a "username"
~/.config/mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
~/.config/mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
~/.config/mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
```
**Pull Requests:**
```bash
~/.mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
~/.mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
~/.mosaic/rails/git/pr-list.sh -s open
~/.mosaic/rails/git/pr-view.sh -n 42 # View PR details
~/.mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
~/.mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
~/.mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
~/.mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
~/.mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch] # Get PR diff
~/.mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json] # Get PR metadata as JSON
~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
~/.config/mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
~/.config/mosaic/rails/git/pr-list.sh -s open
~/.config/mosaic/rails/git/pr-view.sh -n 42 # View PR details
~/.config/mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
~/.config/mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
~/.config/mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
~/.config/mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
~/.config/mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch] # Get PR diff
~/.config/mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json] # Get PR metadata as JSON
```
**Milestones:**
```bash
~/.mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
~/.mosaic/rails/git/milestone-create.sh --list
~/.mosaic/rails/git/milestone-list.sh [-s open|closed|all]
~/.mosaic/rails/git/milestone-close.sh -t "0.2.0"
~/.config/mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
~/.config/mosaic/rails/git/milestone-create.sh --list
~/.config/mosaic/rails/git/milestone-list.sh [-s open|closed|all]
~/.config/mosaic/rails/git/milestone-close.sh -t "0.2.0"
```
**NOTE:** These scripts handle the Gitea `--milestones` (plural) syntax automatically. Always prefer these over raw `tea` or `gh` commands.
@@ -303,7 +303,7 @@ woodpecker secret rm <owner/repo> -n KEY # Delete secret
**Setup command:** `woodpecker setup --server https://ci.mosaicstack.dev --token "YOUR_TOKEN"`
### Portainer Scripts
CLI tools for managing Portainer stacks at `~/.mosaic/rails/portainer/`.
CLI tools for managing Portainer stacks at `~/.config/mosaic/rails/portainer/`.
**Setup:**
```bash
@@ -345,9 +345,9 @@ endpoint-list.sh -f json # JSON format
**Common Workflow (CI/CD redeploy):**
```bash
~/.mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
~/.mosaic/rails/portainer/stack-status.sh -n myapp && \
~/.mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
~/.config/mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
~/.config/mosaic/rails/portainer/stack-status.sh -n myapp && \
~/.config/mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
```
### Git Worktrees
@@ -398,7 +398,7 @@ git worktree remove ../my-app_worktrees/42-fix-login
- Never disable lint rules (`eslint-disable`, `noqa`, `nolint`)
- Never leave warnings — warnings are errors you haven't fixed yet
- If you touched a file, you own its lint violations (Campsite Rule)
- If unsure what linter the project uses, read the `lint` skill: `~/.mosaic/skills/lint/SKILL.md`
- If unsure what linter the project uses, read the `lint` skill: `~/.config/mosaic/skills/lint/SKILL.md`
### Code Style
Follow [Google Style Guides](https://github.com/google/styleguide) for all languages.
@@ -443,30 +443,30 @@ When working on issue #N, create `docs/scratchpads/N-short-name.md`:
| Task Type | Guide |
|-----------|-------|
| Bootstrapping a new project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous task completion | `~/.mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
| Frontend development | `~/.mosaic/guides/frontend.md` |
| Backend/API development | `~/.mosaic/guides/backend.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
| CI/CD pipelines & Docker builds | `~/.mosaic/guides/ci-cd-pipelines.md` |
| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
| Bootstrapping a new project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous task completion | `~/.config/mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
| CI/CD pipelines & Docker builds | `~/.config/mosaic/guides/ci-cd-pipelines.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
| Secrets management | See section below |
**Project-specific skills:**
| Project | Skill |
|---------|-------|
| jetrich/jarvis | `~/.mosaic/skills/jarvis/SKILL.md` |
| jetrich/jarvis | `~/.config/mosaic/skills/jarvis/SKILL.md` |
## Secrets Management
**NEVER hardcode secrets in the codebase.** Choose the appropriate method based on your environment.
### If Using Vault
See `~/.mosaic/guides/vault-secrets.md` for the canonical structure and rules.
See `~/.config/mosaic/guides/vault-secrets.md` for the canonical structure and rules.
Quick reference:
```

2
runtime/claude/settings.json
View File

@@ -7,7 +7,7 @@
"hooks": [
{
"type": "command",
"command": "~/.mosaic/rails/qa/qa-hook-stdin.sh",
"command": "~/.config/mosaic/rails/qa/qa-hook-stdin.sh",
"timeout": 60
}
]

8
runtime/opencode/AGENTS.md
View File

@@ -1,7 +1,7 @@
# Mosaic Runtime Adapter — OpenCode
Load and apply in this order:
1. `~/.mosaic/STANDARDS.md`
1. `~/.config/mosaic/STANDARDS.md`
2. repo-local `AGENTS.md` (and `SOUL.md` when present)
This file is an OpenCode adapter layer. It does not replace project guidance.
@@ -10,19 +10,19 @@ This file is an OpenCode adapter layer. It does not replace project guidance.
- OpenCode sessions may not expose a native subagent/background task primitive in all deployments.
- When native subagent delegation is unavailable, use Mosaic's deterministic orchestrator rail:
- `~/.mosaic/bin/mosaic-orchestrator-matrix-cycle`
- `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle`
- Keep repo task tracking in `docs/tasks.md` as the canonical human-readable state.
- Keep machine transport/controller state in `.mosaic/orchestrator/`.
## Fallback Delegation Mode (No Native Subagents)
1. Bootstrap repo if needed:
- `~/.mosaic/bin/mosaic-bootstrap-repo /path/to/repo`
- `~/.config/mosaic/bin/mosaic-bootstrap-repo /path/to/repo`
2. Configure `.mosaic/orchestrator/config.json`:
- set `"enabled": true`
- set `"worker.command_template"` to your OpenCode worker command
3. Queue work items in `.mosaic/orchestrator/tasks.json` (or via Matrix command ingestion).
4. Run deterministic ticks:
- `~/.mosaic/bin/mosaic-orchestrator-matrix-cycle`
- `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle`
This preserves rails enforcement (`quality_gates`) even without runtime-native subagent features.

4
skills-local/mosaic-standards/SKILL.md
View File

@@ -7,7 +7,7 @@ description: Load machine-wide Mosaic standards and enforce the repository lifec
## Load Order
1. `~/.mosaic/STANDARDS.md`
1. `~/.config/mosaic/STANDARDS.md`
2. Repository `AGENTS.md`
3. Repo-local `.mosaic/repo-hooks.sh` when present
@@ -25,7 +25,7 @@ If wrappers are available, you may use:
## Enforcement Rules
- Treat `~/.mosaic` as canonical for shared guides, rails, profiles, and skills.
- Treat `~/.config/mosaic` as canonical for shared guides, rails, profiles, and skills.
- Do not edit generated project views directly when the repo defines canonical data sources.
- Pull/rebase before edits in shared repositories.
- Run project verification commands before claiming completion.

6
skills-local/setup-cicd/SKILL.md
View File

@@ -7,7 +7,7 @@ description: "Configure CI/CD Docker build, push, and package linking for a proj
Configure Docker build, registry push, and package linking for a Woodpecker CI pipeline using Kaniko and Gitea's container registry.
**Before starting:** Read `~/.mosaic/guides/ci-cd-pipelines.md` for deep background on the patterns used here.
**Before starting:** Read `~/.config/mosaic/guides/ci-cd-pipelines.md` for deep background on the patterns used here.
**Reference implementation:** `~/src/mosaic-stack/.woodpecker.yml`
@@ -140,7 +140,7 @@ Ask these questions with lettered options (user can respond "1A, 2B, 3C"):
If the project's `.woodpecker.yml` doesn't already have a `kaniko_setup` anchor in its `variables:` section, add it:
```bash
~/.mosaic/rails/cicd/generate-docker-steps.sh --kaniko-setup-only --registry REGISTRY_HOST
~/.config/mosaic/rails/cicd/generate-docker-steps.sh --kaniko-setup-only --registry REGISTRY_HOST
```
This outputs:
@@ -158,7 +158,7 @@ Add this to the existing `variables:` block at the top of `.woodpecker.yml`.
Use the generator script with the user's answers:
```bash
~/.mosaic/rails/cicd/generate-docker-steps.sh \
~/.config/mosaic/rails/cicd/generate-docker-steps.sh \
--registry REGISTRY \
--org ORG \
--repo REPO \

4
templates/agent/AGENTS.md.template
View File

@@ -51,8 +51,8 @@ When completing an orchestrated task:
### Post-Coding Review
After implementing changes, the orchestrator will run:
1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
3. If blockers/critical findings: remediation task created
4. If clean: task marked done

22
templates/agent/CLAUDE.md.template
View File

@@ -24,14 +24,14 @@ git push
| Task Type | Guide |
|-----------|-------|
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| Frontend development | `~/.mosaic/guides/frontend.md` |
| Backend/API development | `~/.mosaic/guides/backend.md` |
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
## Technology Stack
@@ -123,16 +123,16 @@ After completing code changes, run independent reviews:
```bash
# Code quality review (Codex)
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
# Security review (Codex)
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```
**Fallback:** If Codex is unavailable, use Claude's built-in review skills.
### Review Checklist
See `~/.mosaic/guides/code-review.md` for the full review checklist.
See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
## Secrets Management

6
templates/agent/SPEC.md
View File

@@ -6,7 +6,7 @@
### Tier 1 (Required — blocks audit pass)
1. **Conditional Documentation Loading** — Table linking to `~/.mosaic/guides/`
1. **Conditional Documentation Loading** — Table linking to `~/.config/mosaic/guides/`
2. **Quality Gates** — Bash commands that must pass before commit (build, test, lint, typecheck)
3. **Build/Test/Lint commands** — How to build, test, and lint the project
@@ -56,13 +56,13 @@ The `agent-lint.sh` tool checks for these markers:
|-------|---------------|
| CLAUDE.md exists | File present at project root |
| AGENTS.md exists | File present at project root |
| Conditional context/loading | CLAUDE.md contains `~/.mosaic/guides` or `Conditional` + `Loading/Context` |
| Conditional context/loading | CLAUDE.md contains `~/.config/mosaic/guides` or `Conditional` + `Loading/Context` |
| Quality gates | CLAUDE.md contains `Quality Gates` or quality commands (test, lint, typecheck) |
| Monorepo sub-agents | Each app/package dir with own manifest has AGENTS.md |
## Fragment Sources
Shared sections are maintained in `~/.mosaic/templates/agent/fragments/`:
Shared sections are maintained in `~/.config/mosaic/templates/agent/fragments/`:
| Fragment | Injects Section |
|----------|----------------|

6
templates/agent/fragments/code-review.md
View File

@@ -4,11 +4,11 @@ After completing code changes, run independent reviews:
```bash
# Code quality review (Codex)
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
# Security review (Codex)
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```
**Fallback:** If Codex is unavailable, use Claude's built-in review skills.
See `~/.mosaic/guides/code-review.md` for the full review checklist.
See `~/.config/mosaic/guides/code-review.md` for the full review checklist.

22
templates/agent/fragments/conditional-loading.md
View File

@@ -4,14 +4,14 @@
| Task Type | Guide |
|-----------|-------|
| Bootstrapping a new project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
| Frontend development | `~/.mosaic/guides/frontend.md` |
| Backend/API development | `~/.mosaic/guides/backend.md` |
| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
| Secrets management (Vault) | `~/.mosaic/guides/vault-secrets.md` |
| Bootstrapping a new project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
| Secrets management (Vault) | `~/.config/mosaic/guides/vault-secrets.md` |

4
templates/agent/projects/django/AGENTS.md.template
View File

@@ -52,8 +52,8 @@ Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
### Post-Coding Review
After implementing changes, the orchestrator will run:
1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
3. If blockers/critical findings: remediation task created
4. If clean: task marked done

14
templates/agent/projects/django/CLAUDE.md.template
View File

@@ -6,11 +6,11 @@
| When working on... | Load this guide |
|---|---|
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
| Backend/API development | `~/.mosaic/guides/backend.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
## Technology Stack
@@ -135,10 +135,10 @@ After completing code changes, run independent reviews:
```bash
# Code quality review (Codex)
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
# Security review (Codex)
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```
## Issue Tracking

4
templates/agent/projects/nestjs-nextjs/AGENTS.md.template
View File

@@ -56,8 +56,8 @@ Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
### Post-Coding Review
After implementing changes, the orchestrator will run:
1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
3. If blockers/critical findings: remediation task created
4. If clean: task marked done

20
templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
View File

@@ -6,14 +6,14 @@
| When working on... | Load this guide |
|---|---|
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
| Frontend development | `~/.mosaic/guides/frontend.md` |
| Backend/API development | `~/.mosaic/guides/backend.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
## Technology Stack
@@ -166,10 +166,10 @@ After completing code changes, run independent reviews:
```bash
# Code quality review (Codex)
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
# Security review (Codex)
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```
## Issue Tracking

24
templates/agent/projects/python-fastapi/CLAUDE.md.template
View File

@@ -9,15 +9,15 @@
| Task Type | Guide |
|-----------|-------|
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
| Backend/API development | `~/.mosaic/guides/backend.md` |
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
| Secrets management (Vault) | `~/.mosaic/guides/vault-secrets.md` |
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
| Secrets management (Vault) | `~/.config/mosaic/guides/vault-secrets.md` |
## Technology Stack
@@ -112,11 +112,11 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
After completing code changes, run independent reviews:
```bash
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```
See `~/.mosaic/guides/code-review.md` for the full review checklist.
See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
## Secrets Management

18
templates/agent/projects/python-library/CLAUDE.md.template
View File

@@ -9,12 +9,12 @@
| Task Type | Guide |
|-----------|-------|
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
| Backend/API development | `~/.mosaic/guides/backend.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
## Technology Stack
@@ -102,11 +102,11 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
After completing code changes, run independent reviews:
```bash
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```
See `~/.mosaic/guides/code-review.md` for the full review checklist.
See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
## Secrets Management

2
templates/agent/projects/typescript/AGENTS.md.template
View File

@@ -6,7 +6,7 @@
## Codebase Patterns
- TypeScript strict mode enabled — no `any`, no implicit types
- See `~/.mosaic/guides/typescript.md` for mandatory TypeScript rules
- See `~/.config/mosaic/guides/typescript.md` for mandatory TypeScript rules
<!-- Add project-specific patterns as you discover them -->
## Common Gotchas

20
templates/agent/projects/typescript/CLAUDE.md.template
View File

@@ -9,13 +9,13 @@
| Task Type | Guide |
|-----------|-------|
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
| Frontend development | `~/.mosaic/guides/frontend.md` |
| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
## Technology Stack
@@ -93,14 +93,14 @@ After completing code changes, run independent reviews:
```bash
# Code quality review (Codex)
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
# Security review (Codex)
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
```
**Fallback:** If Codex is unavailable, use Claude's built-in review skills.
See `~/.mosaic/guides/code-review.md` for the full review checklist.
See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
## Secrets Management