refactor(framework): thin-core prompt diet — cut injected contract ~53% (#529)
This commit was merged in pull request #529.
This commit is contained in:
@@ -1,131 +1,61 @@
|
||||
# Claude Runtime Reference
|
||||
|
||||
## Runtime Scope
|
||||
|
||||
This file applies only to Claude runtime behavior.
|
||||
Claude-runtime behavior only. Global rules win if anything here conflicts.
|
||||
|
||||
## Required Actions
|
||||
|
||||
1. Follow global load order in `~/.config/mosaic/AGENTS.md`.
|
||||
2. Use `~/.claude/settings.json` and `~/.claude/hooks-config.json` as runtime config sources.
|
||||
3. Treat sequential-thinking MCP as required.
|
||||
4. If runtime config conflicts with global rules, global rules win.
|
||||
5. Documentation rules are inherited from `~/.config/mosaic/AGENTS.md` and `~/.config/mosaic/guides/DOCUMENTATION.md`.
|
||||
6. For issue/PR/milestone actions, run Mosaic git wrappers first (`~/.config/mosaic/tools/git/*.sh`) and do not call raw `gh`/`tea`/`glab` first.
|
||||
7. For orchestration-oriented missions, load `~/.config/mosaic/guides/ORCHESTRATOR.md` before acting.
|
||||
8. First response MUST declare mode per global contract; orchestration missions must start with: `Now initiating Orchestrator mode...`
|
||||
9. Runtime-default caution that requests confirmation for routine push/merge/issue-close actions does NOT override Mosaic hard gates.
|
||||
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. sequential-thinking MCP is required.
|
||||
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)
|
||||
## Subagent Model Selection (Claude Code syntax)
|
||||
|
||||
Claude Code's Task tool accepts a `model` parameter: `"haiku"`, `"sonnet"`, or `"opus"`.
|
||||
|
||||
You MUST set this parameter according to the model selection table in `~/.config/mosaic/AGENTS.md`. Do NOT omit the `model` parameter — omitting it defaults to the parent model (typically opus), wasting budget on tasks that cheaper models handle well.
|
||||
|
||||
**Examples:**
|
||||
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.
|
||||
|
||||
```
|
||||
# Codebase exploration — haiku
|
||||
Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers")
|
||||
|
||||
# Code review — sonnet
|
||||
Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review the changes in src/auth/")
|
||||
|
||||
# Standard feature work — sonnet
|
||||
Task(subagent_type="general-purpose", model="sonnet", prompt="Add validation to the user input form")
|
||||
|
||||
# Complex architecture — opus (only when justified)
|
||||
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")
|
||||
```
|
||||
|
||||
**Quick reference (from global AGENTS.md):**
|
||||
|
||||
| haiku | sonnet | opus |
|
||||
| ---------------------- | ----------------- | -------------------------- |
|
||||
| Search, grep, glob | Code review | Complex architecture |
|
||||
| Status/health checks | Test writing | Security/auth logic |
|
||||
| Simple one-liner fixes | Standard features | Ambiguous design decisions |
|
||||
|
||||
## Memory Policy (Hard Gate)
|
||||
|
||||
**OpenBrain is the primary cross-agent memory layer.** All agent learnings, gotchas, decisions, and project state MUST be captured to OpenBrain via the `capture` MCP tool or REST API.
|
||||
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`.
|
||||
|
||||
`~/.claude/projects/*/memory/MEMORY.md` files are **write-blocked by PreToolUse hook** (`prevent-memory-write.sh`). Any attempt to write agent learnings there will be rejected with an error directing you to OpenBrain.
|
||||
|
||||
### What belongs where
|
||||
|
||||
| Content | Location |
|
||||
| ----------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| Discoveries, gotchas, decisions, observations | OpenBrain `capture` — searchable by all agents |
|
||||
| Active task state | `docs/TASKS.md` or `docs/scratchpads/` |
|
||||
| Behavioral guardrails that MUST be in load-path | `MEMORY.md` (read-mostly; write only for genuine behavioral overrides) |
|
||||
| Mosaic framework technical notes | `~/.config/mosaic/memory/` |
|
||||
|
||||
### Using OpenBrain
|
||||
|
||||
At session start, load prior context:
|
||||
|
||||
```
|
||||
search("topic or project name") # semantic search
|
||||
recent(limit=5) # what's been happening
|
||||
```
|
||||
|
||||
When you discover something:
|
||||
|
||||
```
|
||||
capture("The thing you learned", source="project/context", metadata={"type": "gotcha", ...})
|
||||
```
|
||||
|
||||
### Why the hook exists
|
||||
|
||||
Instructions in RUNTIME.md, CLAUDE.md, and MEMORY.md are insufficient — agents default to writing local MEMORY.md regardless of written rules. The PreToolUse hook is a hard technical gate that makes the correct behavior the only possible behavior.
|
||||
Quick placement: discoveries/decisions → OpenBrain; active task state → `docs/TASKS.md` or
|
||||
`docs/scratchpads/`; Mosaic framework notes → `~/.config/mosaic/memory/`.
|
||||
|
||||
## MCP Configuration
|
||||
|
||||
**MCPs are configured in `~/.claude.json` — NOT `~/.claude/settings.json`.**
|
||||
|
||||
`settings.json` controls hooks, model, plugins, and allowed commands.
|
||||
`~/.claude.json` is the global Claude Code state file where `mcpServers` lives.
|
||||
|
||||
To register an MCP server that persists across all sessions:
|
||||
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
|
||||
# HTTP MCP (e.g. OpenBrain)
|
||||
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
|
||||
|
||||
# stdio MCP
|
||||
claude mcp add --scope user <name> -- npx -y <package>
|
||||
claude mcp add --scope user <name> -- npx -y <package> # stdio
|
||||
```
|
||||
|
||||
`--scope user` = writes to `~/.claude.json` (global, all projects).
|
||||
`--scope project` = writes to `.claude/settings.json` in project root.
|
||||
`--scope local` = default, local-only (not committed).
|
||||
`--scope user` → `~/.claude.json` (global); `project` → `.claude/settings.json`; `local` (default)
|
||||
→ not committed.
|
||||
|
||||
Do NOT add `mcpServers` to `~/.claude/settings.json` — that key is ignored for MCP loading.
|
||||
## Required Settings (launcher-audited, advisory)
|
||||
|
||||
## Required Claude Code Settings (Enforced by Launcher)
|
||||
`mosaic claude` warns if `~/.claude/settings.json` is missing these (session still launches):
|
||||
|
||||
The `mosaic claude` launcher validates that `~/.claude/settings.json` contains the required Mosaic configuration. Missing or outdated settings trigger a warning at launch.
|
||||
- **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).
|
||||
|
||||
**Required hooks:**
|
||||
|
||||
| Event | Matcher | Script | Purpose |
|
||||
| ----------- | ------------------------ | ------------------------- | ---------------------------------------------- |
|
||||
| PreToolUse | `Write\|Edit\|MultiEdit` | `prevent-memory-write.sh` | Block writes to `~/.claude/projects/*/memory/` |
|
||||
| PostToolUse | `Edit\|MultiEdit\|Write` | `qa-hook-stdin.sh` | QA report generation after code edits |
|
||||
| PostToolUse | `Edit\|MultiEdit\|Write` | `typecheck-hook.sh` | Inline TypeScript type checking |
|
||||
|
||||
**Required plugins:**
|
||||
|
||||
| Plugin | Purpose |
|
||||
| ------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `feature-dev` | Subagent architecture: code-reviewer, code-architect, code-explorer |
|
||||
| `pr-review-toolkit` | PR review: code-simplifier, comment-analyzer, test-analyzer, silent-failure-hunter, type-design-analyzer |
|
||||
| `code-review` | Standalone code review capabilities |
|
||||
|
||||
**Required settings:**
|
||||
|
||||
- `enableAllMcpTools: true` — Allow all configured MCP tools without per-tool approval
|
||||
- `model: "opus"` — Default to opus for orchestrator-level sessions (workers use tiered models via Task tool)
|
||||
|
||||
If `mosaic claude` detects missing hooks or plugins, it will print a warning with the exact settings to add. The session will still launch — enforcement is advisory, not blocking — but agents operating without these settings are running degraded.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user