brainclaw 0.19.14 → 0.21.0

package/docs/integrations/agents.md

@@ -1,182 +1,134 @@
-# Agent Integration Principles
-
-## Core reality
-
-No agent should be assumed to obey a single instruction perfectly every time.
-
-That means brainclaw integration should not rely on only one mechanism such as:
-
-- a single instruction file
-- a single skill
-- a single startup command
-
-## Better approach
-
-Use multiple points of contact:
-
-- lightweight system instructions
-- project-specific context retrieval through MCP when available
-- prompt-ready generated context
-- native agent files for local reminders
-- MCP tools for dynamic state
-- board and status views
-- workflow reminders around plans, claims, and handoffs
-
-## Surface hierarchy
-
-The default order is:
-
-1. MCP for live state
-2. native agent files for local workflow guidance
-3. readable files as fallback
-4. CLI for setup, operator tasks, scripting, and fallback workflows
-
-This keeps dynamic state dynamic instead of trying to encode it permanently into static instructions.
-
-## System instructions vs project instructions
-
-Keep these separate.
-
-### System instructions
-How the agent should use brainclaw.
-
-Examples:
-
-- check workspace memory before significant changes
-- prefer MCP over manual CLI calls when MCP is available
-- bootstrap if the workspace is not initialized and the workflow allows it
-- respect file claims
-- update shared plan status when appropriate
-
-### Project instructions
-What is true for the current workspace.
-
-Examples:
-
-- active constraints
-- recent decisions
-- known traps
-- current handoffs
-- relevant plan context
+# Agent Integration
 
-## Setting up agent integration
+## The problem brainclaw solves for agents
 
-### Automatic detection
+Coding agents are stateless. Each session starts from zero. They don't know:
 
-```bash
-brainclaw init
-```
-
-`setup` and `init` write the appropriate local agent config files for the detected integrations. Workspace-local generated files are also added to `.gitignore` automatically so agent-specific config does not pollute Git status.
+- what other agents have been working on
+- what files are being actively edited by someone else
+- what decisions were made last week and why
+- what traps to avoid in a specific part of the codebase
 
-### Manual per-agent setup
+Brainclaw gives every agent access to this shared context through a combination of surfaces adapted to what each agent can handle.
 
-```bash
-brainclaw enable-agent claude-code
-brainclaw enable-agent cursor
-brainclaw enable-agent windsurf
-brainclaw enable-agent opencode
-brainclaw enable-agent antigravity
-```
+## Multiple points of contact
 
-### Export to a specific format
+No single mechanism is enough. Agents don't always obey a single instruction file. They sometimes skip MCP calls. They forget between prompts.
 
-```bash
-brainclaw export --format claude-md --write
-brainclaw export --format cursor-rules --write
-brainclaw export --format agents-md --write   # Codex, OpenCode
-brainclaw export --format gemini-md --write   # Antigravity / Gemini CLI
-brainclaw export --format claude-md --write --shared   # only if you want the main instruction file versioned
-```
-
-`--detect` auto-selects formats based on files found in the workspace:
+That's why brainclaw uses every available surface:
 
-```bash
-brainclaw export --detect --write
-```
-
-By default, `--write` treats generated workspace files as local setup and adds them to `.gitignore`. `--shared` only keeps the main exported instruction file versionable; companion MCP/settings files remain local. OpenCode also gets a workspace MCP config in `opencode.json`. Antigravity/Gemini CLI gets a machine-local MCP config in `.gemini/antigravity/mcp_config.json` when `HOME` is available.
-
-If a repo already contains tracked local agent files from an older setup, `brainclaw session-start` warns at the beginning of work and `brainclaw doctor --fix-agent-ignore` can repair the missing `.gitignore` entries. Tracked files still need to be untracked manually with Git after the ignore rules are in place.
+1. **Instruction files** set the frame — "this project uses brainclaw, here's how"
+2. **Hooks** inject context automatically — the agent sees plans and claims without asking
+3. **MCP tools** provide on-demand access — the agent calls brainclaw when it needs more detail
+4. **Auto-approve** removes friction — no popup confirmation for each tool call
+5. **Skills/commands** give the developer a manual override — force a context refresh when needed
 
-## MCP server workflow
-
-The brainclaw MCP server exposes the dynamic Brainclaw workflow directly. For capable agents, this is the nominal runtime path.
+The more surfaces are active, the more reliably the agent uses brainclaw.
 
-### Starting the MCP server
+## What the instruction file contains
 
-```bash
-brainclaw mcp
-```
+The instruction file (CLAUDE.md, .cursor/rules/, AGENTS.md, etc.) is the agent's first contact with brainclaw. Its content depends on the agent's capabilities:
 
-Most agents pick this up via their MCP config file (`.mcp.json`, `~/.cursor/mcp.json`, etc.). brainclaw writes these during `init`.
-
-### Available MCP tools
-
-| Tool | Description |
-|------|-------------|
-| `bclaw_get_context` | Full workspace context (constraints, decisions, traps, plans, handoffs) |
-| `bclaw_get_agent_board` | Live plan + claim board |
-| `bclaw_session_start` | Start an agent session (registers identity) |
-| `bclaw_session_end` | End session, optionally auto-release claims |
-| `bclaw_claim` | Claim a file scope |
-| `bclaw_release_claim` | Release a claim |
-| `bclaw_create_candidate` | Create a plan item |
-| `bclaw_accept` / `bclaw_reject` | Accept or reject a plan candidate |
-| `bclaw_write_note` | Write a runtime note |
-| `bclaw_search` | Search memory entries |
-| `bclaw_read_handoff` | Read a handoff document |
-| `bclaw_bootstrap` | Initialize the workspace if not already done |
-| `bclaw_get_execution_context` | Get execution context (identity, claims, active plans) |
-
-## Session lifecycle
-
-### Starting a session
-
-```bash
-brainclaw session-start --agent my-agent --model claude-opus-4-5
-```
+### For agents with MCP and hooks (Claude Code)
 
-This registers the agent's identity and optionally records the model being used. Other agents can see active sessions in `list-claims` and `board`.
+Short and focused:
+- Why brainclaw matters for this project
+- The session protocol (hooks handle the rest)
+- Active constraints and instructions
+- Version check reminder
 
-### During the session
-
-For MCP-capable agents, prefer the MCP equivalents of these actions. The CLI examples below are the operator and fallback form of the same lifecycle.
+### For agents with MCP but no hooks (Cursor, Codex, OpenCode, etc.)
 
-```bash
-brainclaw context --json        # load fresh project state
-brainclaw claim list            # check for conflicts
-brainclaw claim create "desc" --scope src/feature/
-brainclaw plan create "implement X" --estimate 60
-brainclaw plan update <id> --status in_progress
-```
+More directive:
+- Same core sections as above, with stronger language ("REQUIRED", "MUST")
+- The top 5 most critical traps (the agent won't see them otherwise)
+- Explicit step-by-step protocol with all MCP calls listed
+
+### For agents without MCP (Copilot)
+
+Full static context:
+- All of the above
+- Active plans with status and assignees
+- All shared traps
+- Recent architectural decisions
+
+## Setting up agent integration
 
-### Ending the session
+### Automatic (recommended)
 
 ```bash
-brainclaw session-end --auto-release
+brainclaw setup     # machine-level: detects agents, creates global configs
+brainclaw init      # project-level: creates .brainclaw/, writes agent files
 ```
 
-This releases all active claims held by the current agent and updates plan statuses.
+Or ask your coding agent to do it:
 
-## Generated files are local-only
+```
+"Install and initialize brainclaw in this project"
+```
 
-Agent config files generated by brainclaw — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/brainclaw.md`, `.windsurfrules`, `.github/copilot-instructions.md` — are **not committed to Git**.
+The agent can use `bclaw_setup` to walk through the process interactively.
 
-Each developer regenerates them locally from their own `.brainclaw/` store:
+### Per-agent manual setup
+
+```bash
+brainclaw enable-agent claude-code
+brainclaw enable-agent cursor
+brainclaw export --format claude-md --write
+brainclaw export --detect --write          # auto-detect and write all formats
+```
+
+### Regenerating after changes
+
+When brainclaw memory changes (new constraints, resolved traps, updated plans), regenerate instruction files:
 
 ```bash
 brainclaw export --detect --write
 ```
 
+For agents without MCP (Copilot), this is especially important — the instruction file is their only source of project context.
+
+## Generated files are local
+
+Agent config files generated by brainclaw are **not committed to Git**. Each developer regenerates them locally from the shared `.brainclaw/` store.
+
 This ensures:
-- no private project notes leak into the shared repo
-- each developer's local agent sees the right instructions for their setup
-- instructions stay in sync with the current brainclaw store, not a stale committed version
+- No machine-specific traps leak into the shared repo
+- Each developer's agent sees instructions tailored to their setup
+- Instructions stay in sync with current memory, not a stale committed version
+
+brainclaw adds all generated files to `.gitignore` automatically during init.
+
+Exception: use `--shared` if you intentionally want the main instruction file (e.g., CLAUDE.md) versioned for the whole team.
+
+## Session lifecycle
+
+### Starting work
+
+```
+bclaw_session_start → identify yourself, see the board
+bclaw_get_context(target: "src/auth/") → load relevant memory
+bclaw_get_execution_context → check for brainclaw updates
+```
+
+### During work
+
+```
+bclaw_claim(scope: "src/auth/") → signal what you're editing
+bclaw_write_note("Found a race condition in AuthService") → record observations
+bclaw_create_plan("Fix race condition", estimate: 30) → track work
+```
+
+### Finishing work
+
+```
+bclaw_session_end(auto_release: true) → release claims, update plans
+```
+
+### Plans and estimation
 
-brainclaw adds all generated files to `.gitignore` automatically during `init`.
+Always estimate duration in minutes when creating a plan or step. When completing, report actual effort. This builds a calibration history that helps improve future estimates — agents are typically poor at estimation, and this feedback loop helps.
 
-## Goal
+## Version awareness
 
-The goal is not perfect enforcement.
-The goal is to make brainclaw the natural path for fresh workspace context and coordination.
+Agents should call `bclaw_get_execution_context` at session start. If a newer brainclaw version is available, it tells the agent, who can then inform the developer and suggest updating. Updates may include new features, new MCP tools, and improved coordination.

package/docs/integrations/openclaw.md

@@ -0,0 +1,98 @@
+# OpenClaw Integration
+
+## Why brainclaw for OpenClaw users
+
+OpenClaw's built-in memory (`MEMORY.md` + daily logs) is great for personal notes and preferences, but it doesn't distinguish between different types of project knowledge. After many conversations, constraints get buried, decisions lose their reasoning, and the agent drifts from its original instructions.
+
+brainclaw adds a structured memory layer on top:
+
+| Problem | OpenClaw alone | With brainclaw |
+|---|---|---|
+| "Don't deploy on Friday" gets forgotten | Buried in MEMORY.md after 50 conversations | Stored as a constraint, always visible |
+| Agent repeats a known mistake | No trap system | Traps scored by relevance to current scope |
+| Two agents work on same file | No coordination | Claims prevent collisions |
+| Decision reasoning is lost | Mixed with daily notes | Preserved as typed decisions, searchable |
+
+## How it works
+
+brainclaw integrates as an OpenClaw **skill**. The skill instructs the agent to:
+
+1. Load brainclaw project context before any coding work
+2. Record constraints, traps, and decisions in brainclaw (not MEMORY.md)
+3. Keep MEMORY.md for personal preferences and daily observations
+4. Coordinate with other agents through plans and claims
+
+## Installation
+
+### Prerequisites
+
+```bash
+npm install -g brainclaw
+```
+
+### Install the skill
+
+```bash
+brainclaw enable-agent openclaw
+```
+
+This copies the brainclaw skill to `~/.openclaw/workspace/skills/brainclaw/`.
+
+Or manually:
+
+```bash
+mkdir -p ~/.openclaw/workspace/skills/brainclaw
+cp "$(npm root -g)/brainclaw/skills/openclaw/SKILL.md" ~/.openclaw/workspace/skills/brainclaw/
+```
+
+### Initialize a project
+
+```bash
+cd /path/to/your/project
+brainclaw init
+```
+
+### Restart OpenClaw
+
+```
+/new
+```
+
+or restart the Gateway. The brainclaw skill will be loaded automatically.
+
+## What the agent sees
+
+After installation, your OpenClaw agent will:
+
+- Run `brainclaw context` before project work to load constraints, traps, and plans
+- Record rules you give it as brainclaw constraints (not just MEMORY.md entries)
+- Record problems it discovers as traps (with severity)
+- Log architectural decisions with their reasoning
+- Clean up with `brainclaw session-end` when finished
+
+## Memory split
+
+The brainclaw skill establishes a clear split:
+
+- **MEMORY.md** — your preferences, habits, personal context (OpenClaw manages this)
+- **brainclaw** — project constraints, traps, decisions, plans (shared with all agents)
+
+This means if you switch from OpenClaw to Claude Code or Codex for coding, the project memory follows — it's in `.brainclaw/`, not in `~/.openclaw/`.
+
+## Multi-agent coordination
+
+If you use both OpenClaw and a coding agent (Claude Code, Cursor, etc.) on the same project, brainclaw coordinates between them:
+
+- OpenClaw records a constraint → Claude Code sees it at next session
+- Claude Code claims a file scope → OpenClaw knows not to edit there
+- Either agent creates a plan → both see it in their context
+
+## Profile
+
+When loading context for OpenClaw, use the `openclaw` profile for optimized scoring:
+
+```bash
+brainclaw context --profile openclaw
+```
+
+This boosts constraints, handoffs, and runtime notes — the items most relevant to an agent that might not be editing code directly but needs to understand the project state.

package/docs/integrations/overview.md

@@ -1,74 +1,102 @@
 # Integration Overview
 
-Brainclaw is designed to work with existing coding agents, not replace them.
+Brainclaw works alongside your existing coding agents. It does not replace them — it gives them a shared memory and coordination layer they can all read from and write to.
 
-The key integration rule is simple:
+## How agents connect to brainclaw
 
-1. use MCP for dynamic shared state when the agent supports it
-2. use native agent files for local behavioral guidance
-3. use the CLI for setup, operator workflows, scripting, and fallback access
+Brainclaw reaches each agent through multiple surfaces. Not every agent supports every surface, and that's fine — brainclaw adapts what it writes based on what the agent can handle.
 
-## Current Limitation
+| Surface | What it does | When it activates |
+|---|---|---|
+| **MCP tools** | The agent calls brainclaw directly to read context, create plans, claim files, and coordinate. This is the richest integration. | During every prompt, when the agent decides to call a tool |
+| **Instruction file** | A markdown file in the agent's native format that explains how to use brainclaw and lists active project constraints. | Read once at session start |
+| **Hooks** | Brainclaw injects fresh context into the agent's prompt automatically, without the agent asking. | Every prompt (where supported) |
+| **Auto-approve** | MCP tool calls are pre-approved so the agent doesn't have to ask the developer for permission each time. | Every MCP call (where supported) |
+| **Skills / Commands** | A shortcut the developer can trigger manually to refresh brainclaw context. | On demand |
 
-For now, Brainclaw should be used for sequential multi-agent collaboration, not true parallel editing in the same checkout.
+## What goes where: core vs run
 
-One agent can hand work to another, and the next agent can recover good project context through shared memory, plans, claims, and handoffs. But without dedicated Git worktrees per agent/session, running several coding agents concurrently on the same project checkout is still risky and can create conflicts or unstable local state.
+Instruction files contain **core** content — things that don't change between prompts:
 
-## Integration Surfaces
+- Why brainclaw matters for this project
+- The session protocol (what to call and when)
+- Active constraints
+- Project instructions
 
-brainclaw can integrate through several surfaces, but they do not have the same role.
+Everything else is **run** content — it changes constantly and belongs in the dynamic context delivered through MCP or hooks:
 
-| Surface | Role |
-|---|---|
-| **MCP tools** | primary dynamic access path for context, plans, claims, board views, and runtime writes |
-| **Native agent files** | local guidance in the agent's own surface: `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/brainclaw.md`, `.windsurfrules`, etc. |
-| **Readable files** | fallback readable state such as `.brainclaw/project.md` |
-| **CLI commands** | setup, scripting, release, inspection, and fallback workflows |
-| **System/project instructions** | static reminders about how Brainclaw should be used in this workspace |
+- Active plans and their status
+- Who is working where (claims)
+- Known traps (scored by relevance to the current file)
+- Handoffs between agents
+- Runtime notes
 
-## Recommended Pattern
+This separation keeps instruction files clean and focused. The agent gets the stable rules from the file and the live state from MCP.
 
-A good default pattern is:
+## Three levels of integration
 
-1. give the agent lightweight static instructions about how to use Brainclaw
-2. let it retrieve fresh workspace state through MCP before significant edits
-3. rely on plans, claims, and handoffs during execution
-4. keep native files and readable project state available as fallback context
-5. use hooks or repeated reminders where the host surface supports them
+Brainclaw adapts its instruction file content based on what each agent can do:
 
-## Native Files Are Support, Not The Live Source Of Truth
+### Full integration (MCP + hooks)
 
-Generated files such as `CLAUDE.md` or `.cursor/rules/brainclaw.md` are useful because they keep Brainclaw visible inside the agent surface already in use.
+The agent gets dynamic context injected at every prompt. The instruction file can be lightweight — just the protocol and constraints. Everything else comes through hooks and MCP calls.
 
-They are not meant to replace:
+**Today:** Claude Code
 
-- fresh context retrieval
-- live board state
-- current claims
-- recent runtime notes
-- current handoffs
+### Standard integration (MCP, no hooks)
 
-For those, use MCP when available.
+The agent can call brainclaw tools but doesn't get automatic context injection. The instruction file is more directive — it tells the agent it MUST call specific tools before working, and includes the most critical traps statically.
 
-## Getting The Native File Written Automatically
+**Today:** Cursor, Windsurf, Cline, Roo, Continue, OpenCode, Codex, Antigravity/Gemini CLI
 
-Run `brainclaw init` and Brainclaw will detect the current agent surface and write the appropriate local file automatically.
+### Limited integration (no MCP)
 
-That includes OpenCode (`AGENTS.md` + `opencode.json`) and Antigravity/Gemini CLI (`GEMINI.md` + machine-local MCP config) when those environments are present.
+The agent cannot call brainclaw tools at all. The instruction file becomes the only source of project context, so it includes everything: constraints, traps, active plans, recent decisions.
 
-Or at any time:
+**Today:** GitHub Copilot (uses skills as a partial workaround)
 
-```bash
-brainclaw export --detect --write
-```
+## Agent integration matrix
 
-By default, generated workspace files are treated as local setup and added to `.gitignore`. `--shared` should only be used when you intentionally want the main exported instruction file to be versioned.
+| Agent | MCP | Instruction file | Hooks | Auto-approve | Skills |
+|---|---|---|---|---|---|
+| **Claude Code** | ✔ project + global | CLAUDE.md | ✔ pre-prompt + stop | ✔ permissions | ✔ /brainclaw |
+| **Cursor** | ✔ global | .cursor/rules/ + MDC | ◐ alwaysApply MDC | — | — |
+| **Windsurf** | ✔ global | .windsurfrules | ◐ session trigger | — | — |
+| **Cline** | ✔ project | .clinerules/ | — | ✔ autoApprove | — |
+| **Roo** | ✔ project | .roo/rules/ | — | ✔ alwaysAllow | — |
+| **Continue** | ✔ both | .continue/rules/ | — | — | — |
+| **OpenCode** | ✔ project | AGENTS.md | — | — | — |
+| **Codex** | ✔ global | AGENTS.md | — | — | — |
+| **Gemini CLI** | ✔ global | GEMINI.md | — | — | — |
+| **Copilot** | — | .github/copilot-instructions.md | — | — | ✔ brainclaw-context |
+| **OpenClaw** | — | — | — | — | ✔ brainclaw skill |
 
-## Choose Your Next Page
+**Legend:** ✔ = fully supported, ◐ = partial (static trigger, not dynamic injection), — = not available
 
-- [mcp.md](mcp.md) — the nominal path for capable agents
-- [agents.md](agents.md) — integration principles that apply to every agent
+## Why maximum integration by default
+
+Without active pressure, agents ignore brainclaw. This is a consistent finding from real usage: if brainclaw only declares an MCP server and doesn't push the agent to use it, the agent never calls it.
+
+That's why brainclaw activates **all available surfaces** by default during setup:
+
+- The MCP server and instruction file are always configured (non-negotiable)
+- Auto-approve and hooks are enabled where supported (opt-out possible)
+- The instruction file includes a "why this matters" section so the agent understands why it should care
+
+The developer can dial back individual surfaces if needed, but the default is full integration because that's what works.
+
+## Sequential collaboration, not parallel editing
+
+For now, brainclaw works best when one agent works at a time in a given checkout. The next agent can pick up where the previous one stopped, using shared plans, claims, handoffs, and memory.
+
+Running multiple agents in parallel on the same checkout will create conflicts. Git worktree isolation per agent is planned but not yet available.
+
+## Next reads
+
+- [mcp.md](mcp.md) — the dynamic runtime path for capable agents
+- [agents.md](agents.md) — integration principles and setup details
 - [claude-code.md](claude-code.md)
-- [codex.md](codex.md)
 - [cursor.md](cursor.md)
+- [codex.md](codex.md)
 - [copilot.md](copilot.md)
+- [openclaw.md](openclaw.md)