From 9ccd13fae7852f4e3c9896faa1202be41003892f Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Sat, 21 Feb 2026 11:36:16 -0600 Subject: [PATCH] feat: add USER.md and TOOLS.md to bootstrap framework MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduce user profile (USER.md) and machine tool reference (TOOLS.md) as first-class framework files. Both ship as generic defaults and are personalized via mosaic init. - Add USER.md/TOOLS.md defaults and parameterized templates - Update AGENTS.md load order (6 → 8 steps) - Update SOUL.md: default name "Assistant", add trash/mental-notes guardrails - Update install.sh: preserve USER.md/TOOLS.md on reinstall - Update mosaic-init: interactive USER.md + TOOLS.md generation - Update mosaic-doctor: existence checks for new files - Update mosaic launcher: inject USER.md/TOOLS.md into runtime prompt - Update README: architecture diagram, generic-repo policy note Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 12 +- README.md | 15 ++- SOUL.md | 9 +- TOOLS.md | 60 +++++++++ USER.md | 37 ++++++ bin/mosaic | 11 ++ bin/mosaic-doctor | 2 + bin/mosaic-init | 240 ++++++++++++++++++++++++++++++++++-- install.sh | 10 +- templates/SOUL.md.template | 2 + templates/TOOLS.md.template | 56 +++++++++ templates/USER.md.template | 30 +++++ 12 files changed, 454 insertions(+), 30 deletions(-) create mode 100644 TOOLS.md create mode 100644 USER.md create mode 100644 templates/TOOLS.md.template create mode 100644 templates/USER.md.template diff --git a/AGENTS.md b/AGENTS.md index 7e69fc9..b2ffd28 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,11 +9,13 @@ This file defines the mandatory behavior for all Mosaic agent runtimes. Before responding to any user message, you MUST read these files in order: 1. `~/.config/mosaic/SOUL.md` -2. `~/.config/mosaic/STANDARDS.md` -3. `~/.config/mosaic/AGENTS.md` -4. `~/.config/mosaic/guides/E2E-DELIVERY.md` -5. Project-local `AGENTS.md` (if present) -6. Runtime-specific reference: +2. `~/.config/mosaic/USER.md` +3. `~/.config/mosaic/STANDARDS.md` +4. `~/.config/mosaic/AGENTS.md` +5. `~/.config/mosaic/TOOLS.md` +6. `~/.config/mosaic/guides/E2E-DELIVERY.md` +7. Project-local `AGENTS.md` (if present) +8. Runtime-specific reference: - Claude: `~/.config/mosaic/runtime/claude/RUNTIME.md` - Codex: `~/.config/mosaic/runtime/codex/RUNTIME.md` - OpenCode: `~/.config/mosaic/runtime/opencode/RUNTIME.md` diff --git a/README.md b/README.md index c7636d0..e8372c5 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ Universal agent standards layer for Claude Code, Codex, and OpenCode. One config, every runtime, same standards. +> **This repository is a generic framework baseline.** No personal data, credentials, user-specific preferences, or machine-specific paths should be committed. All personalization happens at install time via `mosaic init` or by editing files in `~/.config/mosaic/` after installation. + ## Quick Install ### Mac / Linux @@ -42,7 +44,10 @@ After install, open a new terminal (or `source ~/.bashrc`) and run: mosaic init ``` -This generates `~/.config/mosaic/SOUL.md` — your agent identity contract. It's loaded into every session regardless of runtime. +This generates three files loaded into every agent session: +- `SOUL.md` — agent identity contract (name, style, guardrails) +- `USER.md` — your user profile (name, timezone, accessibility, preferences) +- `TOOLS.md` — machine-level tool reference (git providers, credentials, CLI patterns) ## Launching Agent Sessions @@ -65,7 +70,9 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim ``` ~/.config/mosaic/ ├── AGENTS.md ← THE source of truth (all standards, all runtimes) -├── SOUL.md ← User identity (generated by mosaic init) +├── SOUL.md ← Agent identity (generated by mosaic init) +├── USER.md ← User profile and accessibility (generated by mosaic init) +├── TOOLS.md ← Machine-level tool reference (generated by mosaic init) ├── STANDARDS.md ← Machine-wide standards ├── guides/E2E-DELIVERY.md ← Mandatory E2E software delivery procedure ├── guides/PRD.md ← Mandatory PRD requirements gate before coding @@ -121,7 +128,7 @@ mosaic upgrade project ... # Project file cleanup mode (see below) Upgrade the installed framework in place: ```bash -# Default (safe): keep local SOUL.md + memory +# Default (safe): keep local SOUL.md, USER.md, TOOLS.md + memory mosaic upgrade # Check current/target release info without changing files @@ -245,7 +252,7 @@ cd ~/src/mosaic-bootstrap && git pull && bash install.sh ``` If an existing install is detected, the installer prompts for: -- `keep` (recommended): preserve local `SOUL.md` and `memory/` +- `keep` (recommended): preserve local `SOUL.md`, `USER.md`, `TOOLS.md`, and `memory/` - `overwrite`: replace everything in `~/.config/mosaic` Or use the one-liner again — it always pulls the latest: diff --git a/SOUL.md b/SOUL.md index e8baddb..b57834e 100644 --- a/SOUL.md +++ b/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 **Assistant** 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 Assistant, 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 — see `~/.config/mosaic/USER.md` for user-specific accommodations. ## Communication Style @@ -42,7 +42,8 @@ If asked "who are you?", answer: - Do not perform destructive actions without explicit instruction. - Do not silently change intent, scope, or definitions. - Do not create fake policy by writing canned responses for every prompt. - +- Prefer `trash` over `rm` when available — recoverable beats gone forever. +- Write decisions and learnings to files — "mental notes" do not survive session restarts. ## Why This Exists diff --git a/TOOLS.md b/TOOLS.md new file mode 100644 index 0000000..b1359bc --- /dev/null +++ b/TOOLS.md @@ -0,0 +1,60 @@ +# Machine-Level Tool Reference + +Centralized reference for tools, credentials, and CLI patterns available across all projects. +Project-specific tooling belongs in the project's `AGENTS.md`, not here. + +## Mosaic Git Wrappers (Use First) + +Mosaic wrappers at `~/.config/mosaic/rails/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands. + +```bash +# Issues +~/.config/mosaic/rails/git/issue-create.sh +~/.config/mosaic/rails/git/issue-close.sh + +# PRs +~/.config/mosaic/rails/git/pr-create.sh +~/.config/mosaic/rails/git/pr-merge.sh + +# Milestones +~/.config/mosaic/rails/git/milestone-create.sh + +# CI queue guard (required before push/merge) +~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge +``` + +## Code Review (Codex) + +```bash +# Code quality review +~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted + +# Security review +~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted +``` + +## Git Providers + +| Instance | URL | CLI | Purpose | +|----------|-----|-----|---------| +| (add your git providers here) | | | | + +## Credentials + +**Location:** (configure your credential file path) + +**Never expose actual values. Never commit credential files.** + +## CLI Gotchas + +(Add platform-specific CLI gotchas as you discover them. Examples: TTY requirements, default list limits, API fallback patterns.) + +## Custom Tools + +(Add any machine-specific tools, scripts, or workflows here.) + +## Safety Defaults + +- Prefer `trash` over `rm` when available — recoverable beats gone forever +- Never run destructive commands without explicit instruction +- Write it down — "mental notes" don't survive session restarts; files do diff --git a/USER.md b/USER.md new file mode 100644 index 0000000..c7e4c08 --- /dev/null +++ b/USER.md @@ -0,0 +1,37 @@ +# User Profile + +This file defines user-specific context for all agent sessions. +It is loaded globally and applies regardless of runtime or project. + +> **This file has not been personalized yet.** +> Run `mosaic init` to set up your user profile, or edit this file directly. + +## Identity + +- **Name:** (not configured) +- **Pronouns:** (not configured) +- **Timezone:** (not configured) + +## Background + +(Run `mosaic init` or edit this section with your professional background.) + +## Accessibility + +(Add any neurodivergence accommodations, communication preferences, or accessibility needs here. Agents will adapt their behavior based on this section.) + +## Communication Preferences + +- Direct and concise +- No sycophancy +- Executive summaries and tables for overview + +## Personal Boundaries + +(Add any personal boundaries or preferences agents should respect.) + +## Current Projects + +| Project | Stack | Registry | +|---------|-------|----------| +| (none configured) | | | diff --git a/bin/mosaic b/bin/mosaic index 7e331ab..2d44c66 100755 --- a/bin/mosaic +++ b/bin/mosaic @@ -148,6 +148,17 @@ For required push/merge/issue-close/release actions, execute without routine con EOF cat "$MOSAIC_HOME/AGENTS.md" + + if [[ -f "$MOSAIC_HOME/USER.md" ]]; then + printf '\n\n# User Profile\n\n' + cat "$MOSAIC_HOME/USER.md" + fi + + if [[ -f "$MOSAIC_HOME/TOOLS.md" ]]; then + printf '\n\n# Machine Tools\n\n' + cat "$MOSAIC_HOME/TOOLS.md" + fi + printf '\n\n# Runtime-Specific Contract\n\n' cat "$runtime_file" } diff --git a/bin/mosaic-doctor b/bin/mosaic-doctor index aabb80a..2b6f940 100755 --- a/bin/mosaic-doctor +++ b/bin/mosaic-doctor @@ -146,6 +146,8 @@ echo "[mosaic-doctor] Mosaic home: $MOSAIC_HOME" # Canonical Mosaic checks expect_file "$MOSAIC_HOME/STANDARDS.md" +expect_file "$MOSAIC_HOME/USER.md" +expect_file "$MOSAIC_HOME/TOOLS.md" expect_dir "$MOSAIC_HOME/guides" expect_dir "$MOSAIC_HOME/rails" expect_dir "$MOSAIC_HOME/rails/quality" diff --git a/bin/mosaic-init b/bin/mosaic-init index 2763abe..f61a20f 100755 --- a/bin/mosaic-init +++ b/bin/mosaic-init @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -euo pipefail -# mosaic-init — Interactive SOUL.md generator +# mosaic-init — Interactive agent identity, user profile, and tool config generator # # Usage: # mosaic-init # Interactive mode @@ -10,8 +10,12 @@ set -euo pipefail # --accessibility "ADHD-friendly chunking" --guardrails "Never auto-commit" MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}" -TEMPLATE="$MOSAIC_HOME/templates/SOUL.md.template" -OUTPUT="$MOSAIC_HOME/SOUL.md" +SOUL_TEMPLATE="$MOSAIC_HOME/templates/SOUL.md.template" +USER_TEMPLATE="$MOSAIC_HOME/templates/USER.md.template" +TOOLS_TEMPLATE="$MOSAIC_HOME/templates/TOOLS.md.template" +SOUL_OUTPUT="$MOSAIC_HOME/SOUL.md" +USER_OUTPUT="$MOSAIC_HOME/USER.md" +TOOLS_OUTPUT="$MOSAIC_HOME/TOOLS.md" # Defaults AGENT_NAME="" @@ -20,11 +24,28 @@ STYLE="" ACCESSIBILITY="" CUSTOM_GUARDRAILS="" +# USER.md defaults +USER_NAME="" +PRONOUNS="" +TIMEZONE="" +BACKGROUND="" +COMMUNICATION_PREFS="" +PERSONAL_BOUNDARIES="" +PROJECTS_TABLE="" + +# TOOLS.md defaults +GIT_PROVIDERS_TABLE="" +CREDENTIALS_LOCATION="" +CUSTOM_TOOLS_SECTION="" + usage() { cat < Communication style: direct, friendly, or formal --accessibility Accessibility preferences (e.g., "ADHD-friendly chunking") --guardrails Custom guardrails (appended to defaults) + --user-name Your name for USER.md + --pronouns Your pronouns (e.g., "He/Him") + --timezone Your timezone (e.g., "America/Chicago") --non-interactive Fail if any required value is missing (no prompts) + --soul-only Only generate SOUL.md -h, --help Show help USAGE } NON_INTERACTIVE=0 +SOUL_ONLY=0 while [[ $# -gt 0 ]]; do case "$1" in @@ -48,7 +74,11 @@ while [[ $# -gt 0 ]]; do --style) STYLE="$2"; shift 2 ;; --accessibility) ACCESSIBILITY="$2"; shift 2 ;; --guardrails) CUSTOM_GUARDRAILS="$2"; shift 2 ;; + --user-name) USER_NAME="$2"; shift 2 ;; + --pronouns) PRONOUNS="$2"; shift 2 ;; + --timezone) TIMEZONE="$2"; shift 2 ;; --non-interactive) NON_INTERACTIVE=1; shift ;; + --soul-only) SOUL_ONLY=1; shift ;; -h|--help) usage; exit 0 ;; *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;; esac @@ -85,7 +115,32 @@ prompt_if_empty() { eval "$var_name=\"$value\"" } -echo "[mosaic-init] Generating SOUL.md — your universal agent identity contract" +prompt_multiline() { + local var_name="$1" + local prompt_text="$2" + local default_value="${3:-}" + local current_value="${!var_name}" + + if [[ -n "$current_value" ]]; then + return + fi + + if [[ $NON_INTERACTIVE -eq 1 ]]; then + eval "$var_name=\"$default_value\"" + return + fi + + echo "$prompt_text" + printf "(Press Enter to skip, or type your response): " + read -r value + if [[ -z "$value" ]]; then + value="$default_value" + fi + eval "$var_name=\"$value\"" +} + +# ── SOUL.md Generation ──────────────────────────────────────── +echo "[mosaic-init] Generating SOUL.md — agent identity contract" echo "" prompt_if_empty AGENT_NAME "What name should agents use" "Assistant" @@ -124,25 +179,28 @@ case "$STYLE" in 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." +4. Visible state over hidden assumptions. +5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations." ;; friendly) BEHAVIORAL_PRINCIPLES="1. Be helpful and approachable while staying efficient. 2. Provide context and explain reasoning when helpful. 3. Truthfulness over confidence: state uncertainty explicitly. -4. Visible state over hidden assumptions." +4. Visible state over hidden assumptions. +5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations." ;; formal) BEHAVIORAL_PRINCIPLES="1. Maintain professional, structured communication. 2. Provide thorough analysis with explicit tradeoffs. 3. Truthfulness over confidence: state uncertainty explicitly. -4. Document decisions and rationale clearly." +4. Document decisions and rationale clearly. +5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations." ;; esac if [[ "$ACCESSIBILITY" != "none" && -n "$ACCESSIBILITY" ]]; then BEHAVIORAL_PRINCIPLES="$BEHAVIORAL_PRINCIPLES -5. $ACCESSIBILITY." +6. $ACCESSIBILITY." fi # Build communication style section @@ -175,8 +233,8 @@ if [[ -n "$CUSTOM_GUARDRAILS" ]]; then fi # Verify template exists -if [[ ! -f "$TEMPLATE" ]]; then - echo "[mosaic-init] ERROR: Template not found: $TEMPLATE" >&2 +if [[ ! -f "$SOUL_TEMPLATE" ]]; then + echo "[mosaic-init] ERROR: Template not found: $SOUL_TEMPLATE" >&2 echo "[mosaic-init] Run the Mosaic installer first." >&2 exit 1 fi @@ -194,17 +252,173 @@ awk -v name="$AGENT_NAME" \ gsub(/\{\{COMMUNICATION_STYLE\}\}/, comms) gsub(/\{\{CUSTOM_GUARDRAILS\}\}/, guardrails) print - }' "$TEMPLATE" > "$OUTPUT" + }' "$SOUL_TEMPLATE" > "$SOUL_OUTPUT" echo "" -echo "[mosaic-init] Generated: $OUTPUT" +echo "[mosaic-init] Generated: $SOUL_OUTPUT" echo "[mosaic-init] Agent name: $AGENT_NAME" echo "[mosaic-init] Style: $STYLE" +if [[ $SOUL_ONLY -eq 1 ]]; then + # Push to runtime adapters and exit + if [[ -x "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" ]]; then + echo "[mosaic-init] Updating runtime adapters..." + "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" + fi + echo "[mosaic-init] Done. Launch with: mosaic claude" + exit 0 +fi + +# ── USER.md Generation ──────────────────────────────────────── +echo "" +echo "[mosaic-init] Generating USER.md — user profile" +echo "" + +prompt_if_empty USER_NAME "Your name" "" +prompt_if_empty PRONOUNS "Your pronouns" "They/Them" +prompt_if_empty TIMEZONE "Your timezone" "UTC" + +prompt_multiline BACKGROUND "Your professional background (brief summary)" "(not configured)" + +# Build accessibility section +ACCESSIBILITY_SECTION="" +if [[ "$ACCESSIBILITY" != "none" && -n "$ACCESSIBILITY" ]]; then + ACCESSIBILITY_SECTION="$ACCESSIBILITY" +else + if [[ $NON_INTERACTIVE -eq 0 ]]; then + echo "" + prompt_multiline ACCESSIBILITY_SECTION \ + "Accessibility or neurodivergence accommodations (or press Enter to skip)" \ + "(No specific accommodations configured. Edit this section to add any.)" + else + ACCESSIBILITY_SECTION="(No specific accommodations configured. Edit this section to add any.)" + fi +fi + +# Build communication preferences +if [[ -z "$COMMUNICATION_PREFS" ]]; then + case "$STYLE" in + direct) + COMMUNICATION_PREFS="- Direct and concise +- No sycophancy +- Executive summaries and tables for overview" + ;; + friendly) + COMMUNICATION_PREFS="- Warm and conversational +- Explain reasoning when helpful +- Balance thoroughness with brevity" + ;; + formal) + COMMUNICATION_PREFS="- Professional and structured +- Thorough explanations with supporting detail +- Formal tone with explicit recommendations" + ;; + esac +fi + +prompt_multiline PERSONAL_BOUNDARIES \ + "Personal boundaries or preferences agents should respect" \ + "(Edit this section to add any personal boundaries.)" + +if [[ -z "$PROJECTS_TABLE" ]]; then + PROJECTS_TABLE="| Project | Stack | Registry | +|---------|-------|----------| +| (none configured) | | |" +fi + +if [[ ! -f "$USER_TEMPLATE" ]]; then + echo "[mosaic-init] WARN: USER.md template not found: $USER_TEMPLATE" >&2 + echo "[mosaic-init] Skipping USER.md generation." >&2 +else + awk -v user_name="$USER_NAME" \ + -v pronouns="$PRONOUNS" \ + -v timezone="$TIMEZONE" \ + -v background="$BACKGROUND" \ + -v accessibility="$ACCESSIBILITY_SECTION" \ + -v comms="$COMMUNICATION_PREFS" \ + -v boundaries="$PERSONAL_BOUNDARIES" \ + -v projects="$PROJECTS_TABLE" \ + '{ + gsub(/\{\{USER_NAME\}\}/, user_name) + gsub(/\{\{PRONOUNS\}\}/, pronouns) + gsub(/\{\{TIMEZONE\}\}/, timezone) + gsub(/\{\{BACKGROUND\}\}/, background) + gsub(/\{\{ACCESSIBILITY_SECTION\}\}/, accessibility) + gsub(/\{\{COMMUNICATION_PREFS\}\}/, comms) + gsub(/\{\{PERSONAL_BOUNDARIES\}\}/, boundaries) + gsub(/\{\{PROJECTS_TABLE\}\}/, projects) + print + }' "$USER_TEMPLATE" > "$USER_OUTPUT" + + echo "[mosaic-init] Generated: $USER_OUTPUT" +fi + +# ── TOOLS.md Generation ─────────────────────────────────────── +echo "" +echo "[mosaic-init] Generating TOOLS.md — machine-level tool reference" +echo "" + +if [[ -z "$GIT_PROVIDERS_TABLE" ]]; then + if [[ $NON_INTERACTIVE -eq 0 ]]; then + echo "Git providers (add rows for your Gitea/GitHub/GitLab instances):" + printf "Primary git provider URL (or press Enter to skip): " + read -r git_url + if [[ -n "$git_url" ]]; then + printf "Provider name: " + read -r git_name + printf "CLI tool (tea/gh/glab): " + read -r git_cli + printf "Purpose: " + read -r git_purpose + GIT_PROVIDERS_TABLE="| Instance | URL | CLI | Purpose | +|----------|-----|-----|---------| +| $git_name | $git_url | \`$git_cli\` | $git_purpose |" + else + GIT_PROVIDERS_TABLE="| Instance | URL | CLI | Purpose | +|----------|-----|-----|---------| +| (add your git providers here) | | | |" + fi + else + GIT_PROVIDERS_TABLE="| Instance | URL | CLI | Purpose | +|----------|-----|-----|---------| +| (add your git providers here) | | | |" + fi +fi + +prompt_if_empty CREDENTIALS_LOCATION "Credential file path (or 'none')" "none" + +if [[ -z "$CUSTOM_TOOLS_SECTION" ]]; then + CUSTOM_TOOLS_SECTION="## Custom Tools + +(Add any machine-specific tools, scripts, or workflows here.)" +fi + +if [[ ! -f "$TOOLS_TEMPLATE" ]]; then + echo "[mosaic-init] WARN: TOOLS.md template not found: $TOOLS_TEMPLATE" >&2 + echo "[mosaic-init] Skipping TOOLS.md generation." >&2 +else + awk -v providers="$GIT_PROVIDERS_TABLE" \ + -v creds="$CREDENTIALS_LOCATION" \ + -v custom="$CUSTOM_TOOLS_SECTION" \ + '{ + gsub(/\{\{GIT_PROVIDERS_TABLE\}\}/, providers) + gsub(/\{\{CREDENTIALS_LOCATION\}\}/, creds) + gsub(/\{\{CUSTOM_TOOLS_SECTION\}\}/, custom) + print + }' "$TOOLS_TEMPLATE" > "$TOOLS_OUTPUT" + + echo "[mosaic-init] Generated: $TOOLS_OUTPUT" +fi + +# ── Finalize ────────────────────────────────────────────────── + # Push to runtime adapters if [[ -x "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" ]]; then + echo "" echo "[mosaic-init] Updating runtime adapters..." "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" fi +echo "" echo "[mosaic-init] Done. Launch with: mosaic claude" +echo "[mosaic-init] Edit USER.md and TOOLS.md directly for further customization." diff --git a/install.sh b/install.sh index 44340f9..2ad0cb5 100755 --- a/install.sh +++ b/install.sh @@ -4,7 +4,7 @@ set -euo pipefail SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}" INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}" # prompt|keep|overwrite -PRESERVE_PATHS=("SOUL.md" "memory") +PRESERVE_PATHS=("SOUL.md" "USER.md" "TOOLS.md" "memory") # Colors (disabled if not a terminal) if [[ -t 1 ]]; then @@ -46,7 +46,7 @@ select_install_mode() { echo "" echo "Existing Mosaic install detected at: $TARGET_DIR" echo "Choose reinstall mode:" - echo " 1) keep Keep local files (SOUL.md, memory/) while updating framework" + echo " 1) keep Keep local files (SOUL.md, USER.md, TOOLS.md, memory/) while updating framework" echo " 2) overwrite Replace everything in $TARGET_DIR" echo " 3) cancel Abort install" printf "Selection [1/2/3] (default: 1): " @@ -131,7 +131,7 @@ mkdir -p "$TARGET_DIR" select_install_mode if [[ "$INSTALL_MODE" == "keep" ]]; then - ok "Install mode: keep local SOUL.md/memory while updating framework" + ok "Install mode: keep local SOUL.md/USER.md/TOOLS.md/memory while updating framework" else ok "Install mode: overwrite existing files" fi @@ -226,7 +226,9 @@ if [[ "$PATH_CHANGED" == "true" ]]; then fi if [[ ! -f "$TARGET_DIR/SOUL.md" ]]; then - NEXT_STEPS+=("Run ${CYAN}mosaic init${RESET} to set up your agent identity (SOUL.md).") + NEXT_STEPS+=("Run ${CYAN}mosaic init${RESET} to set up your agent identity (SOUL.md), user profile (USER.md), and tool config (TOOLS.md).") +elif grep -q "not configured" "$TARGET_DIR/USER.md" 2>/dev/null; then + NEXT_STEPS+=("Run ${CYAN}mosaic init${RESET} to personalize your user profile (USER.md) and tool config (TOOLS.md).") fi if [[ ${#NEXT_STEPS[@]} -gt 0 ]]; then diff --git a/templates/SOUL.md.template b/templates/SOUL.md.template index 720b0b3..6a60141 100644 --- a/templates/SOUL.md.template +++ b/templates/SOUL.md.template @@ -35,6 +35,8 @@ If asked "who are you?", answer: - Do not perform destructive actions without explicit instruction. - Do not silently change intent, scope, or definitions. - Do not create fake policy by writing canned responses for every prompt. +- Prefer `trash` over `rm` when available — recoverable beats gone forever. +- Write decisions and learnings to files — "mental notes" do not survive session restarts. {{CUSTOM_GUARDRAILS}} ## Why This Exists diff --git a/templates/TOOLS.md.template b/templates/TOOLS.md.template new file mode 100644 index 0000000..2f44d83 --- /dev/null +++ b/templates/TOOLS.md.template @@ -0,0 +1,56 @@ +# Machine-Level Tool Reference + +Centralized reference for tools, credentials, and CLI patterns available across all projects. +Project-specific tooling belongs in the project's `AGENTS.md`, not here. + +## Mosaic Git Wrappers (Use First) + +Mosaic wrappers at `~/.config/mosaic/rails/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands. + +```bash +# Issues +~/.config/mosaic/rails/git/issue-create.sh +~/.config/mosaic/rails/git/issue-close.sh + +# PRs +~/.config/mosaic/rails/git/pr-create.sh +~/.config/mosaic/rails/git/pr-merge.sh + +# Milestones +~/.config/mosaic/rails/git/milestone-create.sh + +# CI queue guard (required before push/merge) +~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge +``` + +## Code Review (Codex) + +```bash +# Code quality review +~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted + +# Security review +~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted +``` + +## Git Providers + +{{GIT_PROVIDERS_TABLE}} + +## Credentials + +**Location:** {{CREDENTIALS_LOCATION}} + +**Never expose actual values. Never commit credential files.** + +## CLI Gotchas + +(Add platform-specific CLI gotchas as you discover them.) + +{{CUSTOM_TOOLS_SECTION}} + +## Safety Defaults + +- Prefer `trash` over `rm` when available — recoverable beats gone forever +- Never run destructive commands without explicit instruction +- Write it down — "mental notes" don't survive session restarts; files do diff --git a/templates/USER.md.template b/templates/USER.md.template new file mode 100644 index 0000000..cbf66fc --- /dev/null +++ b/templates/USER.md.template @@ -0,0 +1,30 @@ +# User Profile + +This file defines user-specific context for all agent sessions. +It is loaded globally and applies regardless of runtime or project. + +## Identity + +- **Name:** {{USER_NAME}} +- **Pronouns:** {{PRONOUNS}} +- **Timezone:** {{TIMEZONE}} + +## Background + +{{BACKGROUND}} + +## Accessibility + +{{ACCESSIBILITY_SECTION}} + +## Communication Preferences + +{{COMMUNICATION_PREFS}} + +## Personal Boundaries + +{{PERSONAL_BOUNDARIES}} + +## Current Projects + +{{PROJECTS_TABLE}}