Jason Woltje
2a91f6c202
Agents consistently ignore written instructions about memory routing and default to writing local MEMORY.md files regardless of rules in RUNTIME.md, CLAUDE.md, or MEMORY.md itself. Instructions alone are insufficient — a technical gate is required. Changes: - Add tools/qa/prevent-memory-write.sh — PreToolUse hook that blocks Write/Edit/MultiEdit to ~/.claude/projects/*/memory/*.md (exit 2) - Register hook in runtime/claude/settings.json PreToolUse array - Update runtime/claude/RUNTIME.md: replace soft "Memory Override" note with hard-gate policy, what-goes-where table, and rationale - Rewrite guides/MEMORY.md: OpenBrain as primary layer, blocked silos table, project continuity files, how-the-hook-works section The correct behavior is now the only possible behavior for Claude Code. All agent learnings route to OpenBrain where every harness can read them. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# Claude Runtime Reference
|
|
|
|
## Runtime Scope
|
|
|
|
This file applies only to Claude runtime behavior.
|
|
|
|
## 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.
|
|
|
|
## 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:**
|
|
|
|
```
|
|
# 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="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.
|
|
|
|
`~/.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.
|
|
|
|
## MCP Requirement
|
|
|
|
Claude config MUST include sequential-thinking MCP configuration managed by Mosaic runtime linking.
|