refactor: AGENTS.md is the single source of truth for all runtimes

- Create ~/.config/mosaic/AGENTS.md as the canonical universal agent config
- Runtime adapters (CLAUDE.md, opencode/AGENTS.md, codex/instructions.md) are
  now thin pointers that say "READ ~/.config/mosaic/AGENTS.md"
- mosaic claude: injects AGENTS.md via --append-system-prompt
- mosaic opencode/codex: copies AGENTS.md to runtime config path before launch
- mosaic-link-runtime-assets: pushes thin pointers for direct launch fallback

AGENTS.md is runtime-agnostic. All runtimes get the same standards.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
2026-02-19 13:24:12 -06:00
parent 0b7b823911
commit 3f2ba89db2
8 changed files with 723 additions and 679 deletions

View File

@@ -1,9 +1,12 @@
# mosaic.ps1 — Unified agent launcher and management CLI (Windows)
#
# AGENTS.md is the single source of truth for all agent sessions.
# The launcher injects it into every runtime consistently.
#
# Usage:
# mosaic claude [args...] Launch Claude Code with SOUL.md injected
# mosaic opencode [args...] Launch OpenCode
# mosaic codex [args...] Launch Codex
# mosaic claude [args...] Launch Claude Code with AGENTS.md injected
# mosaic opencode [args...] Launch OpenCode with AGENTS.md injected
# mosaic codex [args...] Launch Codex with AGENTS.md injected
# mosaic init [args...] Generate SOUL.md interactively
# mosaic doctor [args...] Health audit
# mosaic sync [args...] Sync skills
@@ -19,9 +22,9 @@ mosaic $Version - Unified agent launcher
Usage: mosaic <command> [args...]
Agent Launchers:
claude [args...] Launch Claude Code with SOUL.md injected
opencode [args...] Launch OpenCode
codex [args...] Launch Codex
claude [args...] Launch Claude Code with AGENTS.md injected
opencode [args...] Launch OpenCode with AGENTS.md injected
codex [args...] Launch Codex with AGENTS.md injected
Management:
init [args...] Generate SOUL.md (agent identity contract)
@@ -43,6 +46,15 @@ function Assert-MosaicHome {
}
}
function Assert-AgentsMd {
$agentsPath = Join-Path $MosaicHome "AGENTS.md"
if (-not (Test-Path $agentsPath)) {
Write-Host "[mosaic] ERROR: ~/.config/mosaic/AGENTS.md not found." -ForegroundColor Red
Write-Host "[mosaic] Re-run the installer."
exit 1
}
}
function Assert-Soul {
$soulPath = Join-Path $MosaicHome "SOUL.md"
if (-not (Test-Path $soulPath)) {
@@ -60,6 +72,18 @@ function Assert-Runtime {
}
}
function Ensure-RuntimeConfig {
param([string]$Dst)
$src = Join-Path $MosaicHome "AGENTS.md"
$parent = Split-Path $Dst -Parent
if (-not (Test-Path $parent)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null }
$srcHash = (Get-FileHash $src -Algorithm SHA256).Hash
$dstHash = if (Test-Path $Dst) { (Get-FileHash $Dst -Algorithm SHA256).Hash } else { "" }
if ($srcHash -ne $dstHash) {
Copy-Item $src $Dst -Force
}
}
if ($args.Count -eq 0) {
Show-Usage
exit 0
@@ -71,23 +95,31 @@ $remaining = if ($args.Count -gt 1) { $args[1..($args.Count - 1)] } else { @() }
switch ($command) {
"claude" {
Assert-MosaicHome
Assert-AgentsMd
Assert-Soul
Assert-Runtime "claude"
# SOUL.md is loaded via ~/.claude/CLAUDE.md directive (pushed by mosaic-link-runtime-assets)
# Claude supports --append-system-prompt for direct injection
$agentsContent = Get-Content (Join-Path $MosaicHome "AGENTS.md") -Raw
Write-Host "[mosaic] Launching Claude Code..."
& claude @remaining
& claude --append-system-prompt $agentsContent @remaining
}
"opencode" {
Assert-MosaicHome
Assert-AgentsMd
Assert-Soul
Assert-Runtime "opencode"
# OpenCode reads from ~/.config/opencode/AGENTS.md
Ensure-RuntimeConfig (Join-Path $env:USERPROFILE ".config\opencode\AGENTS.md")
Write-Host "[mosaic] Launching OpenCode..."
& opencode @remaining
}
"codex" {
Assert-MosaicHome
Assert-AgentsMd
Assert-Soul
Assert-Runtime "codex"
# Codex reads from ~/.codex/instructions.md
Ensure-RuntimeConfig (Join-Path $env:USERPROFILE ".codex\instructions.md")
Write-Host "[mosaic] Launching Codex..."
& codex @remaining
}