brainclaw 1.9.0 → 1.10.0

package/docs/integrations/agents.md

@@ -1,67 +1,67 @@
-# Agent Integration
-
-## The problem brainclaw solves for agents
-
-Coding agents are stateless. Each session starts from zero. They don't know:
-
-- 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
-
-Brainclaw gives every agent access to this shared context through a combination of surfaces adapted to what each agent can handle.
-
-## Multiple points of contact
-
-No single mechanism is enough. Agents don't always obey a single instruction file. They sometimes skip MCP calls. They forget between prompts.
-
-That's why brainclaw uses every available surface:
-
-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
-
-The more surfaces are active, the more reliably the agent uses brainclaw.
-
-## What the instruction file contains
-
-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:
-
-### For agents with MCP and hooks (Claude Code)
-
-Short and focused:
-- Why brainclaw matters for this project
-- The session protocol (hooks handle the rest)
-- Active constraints and instructions
-- Version check reminder
-
-### For agents with MCP but no hooks (Cursor, Codex, Cline, Copilot, Windsurf, Continue, Kilocode, OpenCode, Roo, Mistral Vibe, Gemini CLI, etc.)
-
-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 Tier B/C agents that lack hooks, an opt-in `.live.md` companion (regenerated on session-end and handoff) carries plans, claims, traps, candidates, and handoffs as a parity backstop — write with `brainclaw export --include-live --write`
-
-### For agents without MCP (autonomous agents only)
-
-Full static context via SKILL.md:
-- All of the above
-- Active plans with status and assignees
-- All shared traps
-- Recent architectural decisions
-
-### For autonomous agents (OpenClaw, NanoClaw, NemoClaw, PicoClaw, ZeroClaw)
-
-Skill-based integration via `skills/<agent>/SKILL.md`:
-- Compact brainclaw usage instructions adapted to the agent's workflow
-- Uses `--profile compact` by default (short sessions, constrained resources)
-- Supports task-based and scheduled workflow models
-
-## Setting up agent integration
-
+# Agent Integration
+
+## The problem brainclaw solves for agents
+
+Coding agents are stateless. Each session starts from zero. They don't know:
+
+- 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
+
+Brainclaw gives every agent access to this shared context through a combination of surfaces adapted to what each agent can handle.
+
+## Multiple points of contact
+
+No single mechanism is enough. Agents don't always obey a single instruction file. They sometimes skip MCP calls. They forget between prompts.
+
+That's why brainclaw uses every available surface:
+
+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
+
+The more surfaces are active, the more reliably the agent uses brainclaw.
+
+## What the instruction file contains
+
+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:
+
+### For agents with MCP and hooks (Claude Code)
+
+Short and focused:
+- Why brainclaw matters for this project
+- The session protocol (hooks handle the rest)
+- Active constraints and instructions
+- Version check reminder
+
+### For agents with MCP but no hooks (Cursor, Codex, Cline, Copilot, Windsurf, Continue, Kilocode, OpenCode, Roo, Mistral Vibe, Gemini CLI, etc.)
+
+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 Tier B/C agents that lack hooks, an opt-in `.live.md` companion (regenerated on session-end and handoff) carries plans, claims, traps, candidates, and handoffs as a parity backstop — write with `brainclaw export --include-live --write`
+
+### For agents without MCP (autonomous agents only)
+
+Full static context via SKILL.md:
+- All of the above
+- Active plans with status and assignees
+- All shared traps
+- Recent architectural decisions
+
+### For autonomous agents (OpenClaw, NanoClaw, NemoClaw, PicoClaw, ZeroClaw)
+
+Skill-based integration via `skills/<agent>/SKILL.md`:
+- Compact brainclaw usage instructions adapted to the agent's workflow
+- Uses `--profile compact` by default (short sessions, constrained resources)
+- Supports task-based and scheduled workflow models
+
+## Setting up agent integration
+
 ### Automatic (recommended)
 
 ```bash
@@ -76,101 +76,101 @@ Or ask your coding agent to do it:
 ```
 
 The agent can use `bclaw_setup` to walk through the process interactively.
-
-### Per-agent manual setup
-
-```bash
+
+### 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 the current agent format
-```
-
-### Regenerating after changes
-
-When brainclaw memory changes (new constraints, resolved traps, updated plans), regenerate instruction files:
-
-```bash
-brainclaw export --all              # all known agent formats at once (17 targets today)
-brainclaw export --detect --write   # only the detected agent
-```
-
-For agents without MCP (autonomous agents), this is especially important — the instruction file or SKILL.md 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 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.
-
-## Multi-project workspaces
-
-When a workspace contains multiple brainclaw-initialized child projects, agents need to target the correct project store. There are three mechanisms (from most to least ergonomic):
-
-### 1. `brainclaw switch` (persistent)
-
-An operator or agent sets the active project once, and all subsequent commands resolve against it:
-
-```bash
-brainclaw switch apps/lodestar         # set active project
-brainclaw plan list                    # targets lodestar
-bclaw_context(kind="memory")           # MCP also targets lodestar
-brainclaw switch --clear               # back to workspace root
-```
-
-### 2. `BRAINCLAW_PROJECT` environment variable
-
-Set in the shell or agent configuration. Useful for CI/CD or when the agent can control its environment:
-
-```bash
-export BRAINCLAW_PROJECT=lodestar
-```
-
-### 3. `--cwd` flag (one-off override)
-
-For a single command without changing the active project:
-
-```bash
-brainclaw --cwd apps/lodestar plan list
-```
-
-**Priority**: `--cwd` > `BRAINCLAW_PROJECT` > active project > shell cwd.
-
-**Discovery**: use `brainclaw switch --list` to see all available projects in the workspace.
-
-## Session lifecycle
-
-### Starting work
-
-```
-bclaw_work(intent="execute", scope="src/auth/")          → start session, load context, claim scope in one call
-bclaw_context(kind="execution")                          → check local tooling and brainclaw updates
-```
-
-### During work
-
-```
-bclaw_write_note("Found a race condition in AuthService")            → record observations
-bclaw_create(entity="plan", data={ text: "Fix race condition", estimated_effort: 30 })  → track work
-```
-
-### Finishing work
-
-```
-bclaw_session_end(auto_release: true) → release claims, update plans
-```
-
-### Plans and estimation
-
-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.
-
-## Version awareness
-
-Agents should call `bclaw_context(kind="execution")` at session start (or `bclaw_work` which loads it implicitly). 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.
+```
+
+### Regenerating after changes
+
+When brainclaw memory changes (new constraints, resolved traps, updated plans), regenerate instruction files:
+
+```bash
+brainclaw export --all              # all known agent formats at once (17 targets today)
+brainclaw export --detect --write   # only the detected agent
+```
+
+For agents without MCP (autonomous agents), this is especially important — the instruction file or SKILL.md 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 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.
+
+## Multi-project workspaces
+
+When a workspace contains multiple brainclaw-initialized child projects, agents need to target the correct project store. There are three mechanisms (from most to least ergonomic):
+
+### 1. `brainclaw switch` (persistent)
+
+An operator or agent sets the active project once, and all subsequent commands resolve against it:
+
+```bash
+brainclaw switch apps/lodestar         # set active project
+brainclaw plan list                    # targets lodestar
+bclaw_context(kind="memory")           # MCP also targets lodestar
+brainclaw switch --clear               # back to workspace root
+```
+
+### 2. `BRAINCLAW_PROJECT` environment variable
+
+Set in the shell or agent configuration. Useful for CI/CD or when the agent can control its environment:
+
+```bash
+export BRAINCLAW_PROJECT=lodestar
+```
+
+### 3. `--cwd` flag (one-off override)
+
+For a single command without changing the active project:
+
+```bash
+brainclaw --cwd apps/lodestar plan list
+```
+
+**Priority**: `--cwd` > `BRAINCLAW_PROJECT` > active project > shell cwd.
+
+**Discovery**: use `brainclaw switch --list` to see all available projects in the workspace.
+
+## Session lifecycle
+
+### Starting work
+
+```
+bclaw_work(intent="execute", scope="src/auth/")          → start session, load context, claim scope in one call
+bclaw_context(kind="execution")                          → check local tooling and brainclaw updates
+```
+
+### During work
+
+```
+bclaw_write_note("Found a race condition in AuthService")            → record observations
+bclaw_create(entity="plan", data={ text: "Fix race condition", estimated_effort: 30 })  → track work
+```
+
+### Finishing work
+
+```
+bclaw_session_end(auto_release: true) → release claims, update plans
+```
+
+### Plans and estimation
+
+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.
+
+## Version awareness
+
+Agents should call `bclaw_context(kind="execution")` at session start (or `bclaw_work` which loads it implicitly). 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/claude-code.md

@@ -1,23 +1,23 @@
-# Claude Code Integration
-
-brainclaw is a good fit for Claude Code because Claude Code can work with files, instructions, MCP, and hook-like workflow mechanisms.
-
-## Auto-setup
-
-`brainclaw init` detects Claude Code (`CLAUDE_CODE_VERSION`) and writes `CLAUDE.md` automatically. Or manually:
-
-```bash
-brainclaw export --format claude-md --write
-```
-
-## Recommended approach
-
-- use MCP as the default runtime path for dynamic retrieval and writes
-- keep `CLAUDE.md` lightweight and behavioral: it should tell Claude Code when to call Brainclaw, not carry all mutable workspace state
-- use `.brainclaw/project.md` as a readable fallback (it is a derived view, regenerated best-effort — run `brainclaw rebuild` if stale)
-- use hooks or workflow checks when a stronger reminder is needed
-
-## Key idea
-
-Claude Code should not carry all workspace state in static instructions.
-brainclaw provides the living workspace layer through MCP plus local workflow guidance.
+# Claude Code Integration
+
+brainclaw is a good fit for Claude Code because Claude Code can work with files, instructions, MCP, and hook-like workflow mechanisms.
+
+## Auto-setup
+
+`brainclaw init` detects Claude Code (`CLAUDE_CODE_VERSION`) and writes `CLAUDE.md` automatically. Or manually:
+
+```bash
+brainclaw export --format claude-md --write
+```
+
+## Recommended approach
+
+- use MCP as the default runtime path for dynamic retrieval and writes
+- keep `CLAUDE.md` lightweight and behavioral: it should tell Claude Code when to call Brainclaw, not carry all mutable workspace state
+- use `.brainclaw/project.md` as a readable fallback (it is a derived view, regenerated best-effort — run `brainclaw rebuild` if stale)
+- use hooks or workflow checks when a stronger reminder is needed
+
+## Key idea
+
+Claude Code should not carry all workspace state in static instructions.
+brainclaw provides the living workspace layer through MCP plus local workflow guidance.

package/docs/integrations/cline.md

@@ -1,87 +1,87 @@
-# Cline Integration
-
+# Cline Integration
+
 brainclaw integrates with Cline through MCP tools, instruction rules, auto-approval, and CLI spawn capability for parallel lanes. Cline does not currently expose a Brainclaw-managed lifecycle hook surface.
-
-## Auto-setup
-
-`brainclaw init` detects Cline (the VS Code extension and/or the `cline` CLI) and writes:
-
-- `.clinerules/brainclaw.md` — Cline-specific instruction rules (auto-discovered by Cline)
-- `.cline/mcp.json` — project-level MCP config registering brainclaw
-
-Manual regeneration:
-
-```bash
-brainclaw export --format cline --write
-brainclaw export --format cline --write --include-live
-```
-
-## MCP configuration
-
-Cline reads MCP servers from `.cline/mcp.json` at the project root:
-
-```json
-{
-  "mcpServers": {
-    "brainclaw": {
-      "command": "npx",
-      "args": ["-y", "brainclaw@latest", "mcp"]
-    }
-  }
-}
-```
-
-Cline supports per-server `alwaysAllow` for auto-approving specific tools:
-
-```json
-{
-  "mcpServers": {
-    "brainclaw": {
-      "command": "npx",
-      "args": ["-y", "brainclaw@latest", "mcp"],
-      "alwaysAllow": ["bclaw_context", "bclaw_work", "bclaw_find", "bclaw_get"]
-    }
-  }
-}
-```
-
-## Instruction files
-
-- `.clinerules/brainclaw.md` — Cline-specific rules (auto-discovered, project-scoped)
-- `.clinerules/live.md` — optional local live companion with current plans, claims, traps, candidates, and handoffs. Write it with `brainclaw export --format cline --write --include-live`; it remains gitignored.
-- Static content stays behavioural and lightweight. By default, live state flows through MCP; the live companion is an optional parity/backstop file.
-
+
+## Auto-setup
+
+`brainclaw init` detects Cline (the VS Code extension and/or the `cline` CLI) and writes:
+
+- `.clinerules/brainclaw.md` — Cline-specific instruction rules (auto-discovered by Cline)
+- `.cline/mcp.json` — project-level MCP config registering brainclaw
+
+Manual regeneration:
+
+```bash
+brainclaw export --format cline --write
+brainclaw export --format cline --write --include-live
+```
+
+## MCP configuration
+
+Cline reads MCP servers from `.cline/mcp.json` at the project root:
+
+```json
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
+    }
+  }
+}
+```
+
+Cline supports per-server `alwaysAllow` for auto-approving specific tools:
+
+```json
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"],
+      "alwaysAllow": ["bclaw_context", "bclaw_work", "bclaw_find", "bclaw_get"]
+    }
+  }
+}
+```
+
+## Instruction files
+
+- `.clinerules/brainclaw.md` — Cline-specific rules (auto-discovered, project-scoped)
+- `.clinerules/live.md` — optional local live companion with current plans, claims, traps, candidates, and handoffs. Write it with `brainclaw export --format cline --write --include-live`; it remains gitignored.
+- Static content stays behavioural and lightweight. By default, live state flows through MCP; the live companion is an optional parity/backstop file.
+
 ## SKILL.md discovery
 
 Cline may discover skills from agent-specific directories depending on the installed extension/version. Brainclaw's current Cline writer configures MCP and `.clinerules/brainclaw.md`; it does not write a Cline-specific SKILL.md.
-
-## Headless invocation
-
-Cline is CLI-spawnable for parallel lanes and dispatched workflows. The canonical invoke template is:
-
-```bash
-cline -y "{prompt}"
-```
-
-The `-y` flag (YOLO mode) disables interactive approval prompts so the spawned worker runs autonomously.
-
-## Capability profile
-
-| Field | Value |
-|-------|-------|
+
+## Headless invocation
+
+Cline is CLI-spawnable for parallel lanes and dispatched workflows. The canonical invoke template is:
+
+```bash
+cline -y "{prompt}"
+```
+
+The `-y` flag (YOLO mode) disables interactive approval prompts so the spawned worker runs autonomously.
+
+## Capability profile
+
+| Field | Value |
+|-------|-------|
 | Tier | A |
 | MCP | yes |
 | Hooks | no |
 | Auto-approve | yes (`alwaysAllow` per server, `-y` per session) |
 | Skills | no Brainclaw-specific writer |
-| CLI spawnable | yes |
-| Max concurrent tasks | 3 |
-| Workflow model | interactive |
-| MCP config scope | project |
-| Prompt delivery | `inline_arg` (preferred, max 8000 chars), `inbox_structured` (fallback) |
-
-## Caveats
-
+| CLI spawnable | yes |
+| Max concurrent tasks | 3 |
+| Workflow model | interactive |
+| MCP config scope | project |
+| Prompt delivery | `inline_arg` (preferred, max 8000 chars), `inbox_structured` (fallback) |
+
+## Caveats
+
 - **Cline / Roo / Kilocode family**: Cline shares its config-pattern lineage with Roo Code and Kilocode. The directory names differ (`.clinerules/` vs `.roo/rules/` vs `.kilo/rules/`) but the auto-discovery model is the same.
-- **Project-scoped MCP**: unlike machine-scoped agents (Cursor, Windsurf), Cline's MCP config lives in the repo. Each repo gets its own brainclaw registration.
-- **Long prompts**: inline arg supports up to 8000 chars before falling back to inbox-structured delivery. Briefs longer than that should arrive via inbox.
+- **Project-scoped MCP**: unlike machine-scoped agents (Cursor, Windsurf), Cline's MCP config lives in the repo. Each repo gets its own brainclaw registration.
+- **Long prompts**: inline arg supports up to 8000 chars before falling back to inbox-structured delivery. Briefs longer than that should arrive via inbox.

package/docs/integrations/continue.md

@@ -1,60 +1,60 @@
-# Continue Integration
-
-brainclaw integrates with Continue through MCP tools and project-scoped rules, giving Continue access to shared memory, plans, claims, and coordination state.
-
-## Auto-setup
-
-`brainclaw init` detects Continue and writes `.continue/rules/brainclaw.md` automatically. Or manually:
-
+# Continue Integration
+
+brainclaw integrates with Continue through MCP tools and project-scoped rules, giving Continue access to shared memory, plans, claims, and coordination state.
+
+## Auto-setup
+
+`brainclaw init` detects Continue and writes `.continue/rules/brainclaw.md` automatically. Or manually:
+
 ```bash
 brainclaw export --format continue --write
 ```
-
-## MCP configuration
-
-Continue reads MCP server definitions from `.continue/config.json`. Add brainclaw:
-
-```json
-{
-  "mcpServers": [
-    {
-      "name": "brainclaw",
-      "command": "npx",
-      "args": ["-y", "brainclaw@latest", "mcp"]
-    }
-  ]
-}
-```
-
-Per-server YAML configs are also supported in `.continue/mcpServers/*.yaml`.
-
-## Permissions
-
-Continue uses a separate permissions file at `~/.continue/permissions.yaml`. Tool-level control uses `--allow`, `--ask`, and `--exclude` flags on the CLI.
-
+
+## MCP configuration
+
+Continue reads MCP server definitions from `.continue/config.json`. Add brainclaw:
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "brainclaw",
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
+    }
+  ]
+}
+```
+
+Per-server YAML configs are also supported in `.continue/mcpServers/*.yaml`.
+
+## Permissions
+
+Continue uses a separate permissions file at `~/.continue/permissions.yaml`. Tool-level control uses `--allow`, `--ask`, and `--exclude` flags on the CLI.
+
 `brainclaw setup-machine` writes `~/.continue/permissions.yaml` when Continue is selected. Configure it manually only if you need stricter local policy than Brainclaw's generated defaults.
-
-## SKILL.md discovery
-
-Continue discovers skills from `config.yaml` slashCommands. It does not auto-discover `.agents/skills/` — use explicit config if you need brainclaw skills.
-
-## Headless invocation
-
-```bash
-cn --auto /path/to/project
-```
-
-Set `CONTINUE_API_KEY` for API-backed headless runs.
-
-## Invoke template
-
-```bash
-cn /path/to/project
-```
-
-## Caveats
-
-- **No hooks**: Continue delegates hook-like behavior to VS Code extensions. No native pre-prompt injection.
+
+## SKILL.md discovery
+
+Continue discovers skills from `config.yaml` slashCommands. It does not auto-discover `.agents/skills/` — use explicit config if you need brainclaw skills.
+
+## Headless invocation
+
+```bash
+cn --auto /path/to/project
+```
+
+Set `CONTINUE_API_KEY` for API-backed headless runs.
+
+## Invoke template
+
+```bash
+cn /path/to/project
+```
+
+## Caveats
+
+- **No hooks**: Continue delegates hook-like behavior to VS Code extensions. No native pre-prompt injection.
 - **Permissions are machine-local**: Brainclaw can write `~/.continue/permissions.yaml`, but it is not committed with the project.
-- **No native subagents**: Continue does not expose subagent orchestration.
-- **Windows**: Works via VS Code extension; CLI (`cn`) requires Node.js on PATH.
+- **No native subagents**: Continue does not expose subagent orchestration.
+- **Windows**: Works via VS Code extension; CLI (`cn`) requires Node.js on PATH.