Jason Woltje
319e21ddc0
Splits the 155-line thin-core AGENTS.md into: - defaults/CONSTITUTION.md (L0): gates + integrity + escalation + block-vs-done + mode + two-axis precedence + hooks-are-the-gate + framework-PR firewall + structured-reasoning capability + tier-aware self-load. Capability-verb authored. - defaults/AGENTS.md gutted to an ~80-line load-order dispatcher + guide table (kills the false "already in context, do not re-read" line). - constitution/LAYER-MODEL.md: source-only governance spec (layers + precedence). Non-regression wiring (fresh-install functional; upgrade-safety is P4): - launch.ts injects CONSTITUTION.md before AGENTS.md (tolerant of un-reseeded installs) - install.sh + file-adapter.ts seed CONSTITUTION.md (+ test fixture updated) Runtime adapters: capability-verb the sequential-thinking binding; claude/codex/ opencode restate the REQUIRED hard-stop, pi binds to native thinking (gate=false) — restores the force the adversarial review flagged as weakened. Gate hardening (dual-engine review): identity denylist now covers examples/ (closes the Codex open-source gap), self-test-first, *.json in scope, ci.yml typecheck depends on sanitization (fail-fast), L0 line-count ceiling (<=120). Adversarial gate-preservation review: every original rule traced to L0, the dispatcher, or a routed guide — nothing lost. Refs #542, closes #574 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
62 lines
3.0 KiB
Markdown
62 lines
3.0 KiB
Markdown
# Claude Runtime Reference
|
|
|
|
Claude-runtime behavior only. Global rules win if anything here conflicts.
|
|
|
|
## Required Actions
|
|
|
|
1. Follow the Session Start load order in `~/.config/mosaic/AGENTS.md`.
|
|
2. Runtime config lives in `~/.claude/settings.json` (hooks, model, plugins, permissions) and
|
|
`~/.claude/hooks-config.json`.
|
|
3. Structured reasoning (Constitution) binds to the sequential-thinking MCP on this harness; it is REQUIRED — if unavailable, report the failure and stop planning-intensive execution.
|
|
4. First response MUST declare mode per the global contract.
|
|
5. Git wrappers first for issue/PR/milestone ops; runtime-default confirmation prompts do NOT
|
|
override Mosaic hard gates (push/merge/issue-close without routine confirmation).
|
|
|
|
## Subagent Model Selection (Claude Code syntax)
|
|
|
|
The Task tool takes `model`: `"haiku"` | `"sonnet"` | `"opus"`. You MUST set it per the tier rule
|
|
in AGENTS.md — omitting it defaults to the parent (usually opus) and wastes budget.
|
|
|
|
```
|
|
Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers")
|
|
Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review src/auth/ changes")
|
|
Task(subagent_type="Plan", model="opus", prompt="Design the multi-tenant isolation strategy")
|
|
```
|
|
|
|
## Memory Policy (Hard Gate)
|
|
|
|
OpenBrain is the primary cross-agent memory layer — capture learnings/gotchas/decisions there
|
|
(`capture` MCP tool or REST). `~/.claude/projects/*/memory/MEMORY.md` is **write-blocked** by the
|
|
`prevent-memory-write.sh` PreToolUse hook (the rule alone proved insufficient — the hook is the
|
|
hard gate). At session start, `search(topic)` + `recent()` to load prior context. Full protocol:
|
|
`~/.config/mosaic/guides/MEMORY.md`.
|
|
|
|
Quick placement: discoveries/decisions → OpenBrain; active task state → `docs/TASKS.md` or
|
|
`docs/scratchpads/`; Mosaic framework notes → `~/.config/mosaic/memory/`.
|
|
|
|
## MCP Configuration
|
|
|
|
MCP servers are configured in `~/.claude.json` (key `mcpServers`) — NOT `~/.claude/settings.json`,
|
|
where that key is ignored. `settings.json` controls hooks/model/plugins/permissions.
|
|
|
|
```bash
|
|
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
|
|
claude mcp add --scope user <name> -- npx -y <package> # stdio
|
|
```
|
|
|
|
`--scope user` → `~/.claude.json` (global); `project` → `.claude/settings.json`; `local` (default)
|
|
→ not committed.
|
|
|
|
## Required Settings (launcher-audited, advisory)
|
|
|
|
`mosaic claude` warns if `~/.claude/settings.json` is missing these (session still launches):
|
|
|
|
- **Hooks** — PreToolUse `prevent-memory-write.sh` (Write|Edit|MultiEdit); PostToolUse
|
|
`qa-hook-stdin.sh` + `typecheck-hook.sh` (Edit|MultiEdit|Write).
|
|
- **Plugins** — `feature-dev`, `pr-review-toolkit`, `code-review`.
|
|
- **Settings** — `enableAllMcpTools: true`; `model: "opus"` (orchestrator default; workers use
|
|
tiered models via the Task `model` param).
|
|
|
|
Note: PostToolUse hook plain stdout on exit 0 goes to the debug log, not model context — only
|
|
`hookSpecificOutput.additionalContext` (or exit-2 stderr) enters context.
|