brainclaw 0.28.0 → 1.5.3

package/docs/integrations/agents.md

@@ -37,16 +37,17 @@ Short and focused:
 - Active constraints and instructions
 - Version check reminder
 
-### For agents with MCP but no hooks (Cursor, Codex, OpenCode, etc.)
+### 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 (Copilot, autonomous agents)
+### For agents without MCP (autonomous agents only)
 
-Full static context via instruction file or SKILL.md:
+Full static context via SKILL.md:
 - All of the above
 - Active plans with status and assignees
 - All shared traps
@@ -90,11 +91,11 @@ brainclaw export --detect --write          # auto-detect and write all formats
 When brainclaw memory changes (new constraints, resolved traps, updated plans), regenerate instruction files:
 
 ```bash
-brainclaw export --all              # all 15 agent formats at once
+brainclaw export --all              # all known agent formats at once (17 targets today)
 brainclaw export --detect --write   # only the detected agent
 ```
 
-For agents without MCP (Copilot), this is especially important — the instruction file is their only source of project context.
+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
 
@@ -118,10 +119,10 @@ When a workspace contains multiple brainclaw-initialized child projects, agents
 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_get_context()               # MCP also targets lodestar
-brainclaw switch --clear          # back to workspace root
+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
@@ -149,17 +150,15 @@ brainclaw --cwd apps/lodestar plan list
 ### 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
+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_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
+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
@@ -174,4 +173,4 @@ Always estimate duration in minutes when creating a plan or step. When completin
 
 ## Version awareness
 
-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.
+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/cline.md

@@ -0,0 +1,88 @@
+# Cline Integration
+
+brainclaw integrates with Cline through MCP tools, instruction rules, and lifecycle hooks. Cline is a Tier A agent — full MCP access, hooks, auto-approve support, skills, and CLI spawn capability for parallel lanes.
+
+## 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 auto-discovers skills from `.clinerules/`, `.claude/skills/`, and `.agents/skills/`. brainclaw writes a single `.agents/skills/brainclaw/SKILL.md` that Cline picks up automatically.
+
+## 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 | yes |
+| Auto-approve | yes (`alwaysAllow` per server, `-y` per session) |
+| Skills | yes |
+| 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
+
+- **Hook support varies by platform**: Cline hooks are reliable on macOS/Linux but the Windows path is less exercised. brainclaw generates hooks that gracefully degrade when the runtime doesn't honour them — the templateTier stays A regardless.
+- **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.

package/docs/integrations/codex.md

@@ -1,23 +1,75 @@
-# Codex Integration
-
-brainclaw fits well with Codex-style workflows because Codex can work with project instructions, files, skills, and MCP.
-
-## Auto-setup
-
-`brainclaw init` detects Codex (`~/.codex/` directory) and writes `AGENTS.md` automatically. Or manually:
-
-```bash
-brainclaw export --format agents-md --write
-```
-
-## Recommended approach
-
-- use MCP as the default runtime path for fresh context, plans, claims, and runtime notes
-- keep `AGENTS.md` lightweight and behavioral: it should remind Codex how to use Brainclaw, not duplicate live state
-- use `.brainclaw/project.md` only as a readable fallback (derived view, regenerated best-effort — run `brainclaw rebuild` if stale)
-- encourage plans, claims, and handoffs during multi-step work
-
-## Good role for brainclaw here
-
-Codex stays the coding agent.
-brainclaw provides the live workspace context and coordination layer.
+# Codex Integration
+
+brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex is a Tier A agent — full MCP access, lifecycle hooks, skills support, and headless CLI spawn capability.
+
+## Auto-setup
+
+`brainclaw init` detects Codex (the presence of `~/.codex/`) and writes `AGENTS.md` to the project root. The MCP server is registered machine-wide at `~/.codex/mcp-config.json`. To regenerate manually:
+
+```bash
+brainclaw export --format agents-md --write
+```
+
+## MCP configuration
+
+Codex reads MCP servers from a machine-level config (`~/.codex/mcp-config.json` on most installs). brainclaw is registered as:
+
+```json
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
+    }
+  }
+}
+```
+
+Per-session MCP config can also be passed via `--additional-mcp-config @<file>` when invoking Codex.
+
+## Instruction files
+
+- `AGENTS.md` — shared instruction file (also read by OpenCode)
+- Static content stays behavioural and lightweight; live state (plans, claims, traps) flows through MCP
+
+## Headless invocation
+
+Codex is CLI-spawnable for parallel lanes and dispatched workflows. The canonical invoke template is:
+
+```bash
+codex exec -c approval_policy="never" --sandbox workspace-write "{prompt}"
+```
+
+The `--sandbox workspace-write` setting is required, **not `read-only`** — the read-only sandbox blocks the MCP filesystem writes that brainclaw needs (worktree handoffs, session files, etc.) and forces fallback to GitHub connectors which fail for local-only commits.
+
+### Prompt delivery: stdin_pipe (preferred)
+
+Since pln#475 (1.0.10+), Codex spawned as a child process receives its prompt via **stdin** rather than as an inline argument. The reason is Windows-specific: `codex.cmd` resolves through `cmd.exe`, where embedded backticks, `#`, or multi-line content can be mis-parsed and raise `unexpected argument`. Reading from stdin avoids that.
+
+When you (or the dispatcher) calls Codex with no positional `[PROMPT]`, Codex reads stdin until EOF — that's where brainclaw pipes the brief. `inline_arg` remains a fallback for short prompts on POSIX.
+
+### Brief-ack handshake
+
+Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started` once the wrapping shell touches a brief-ack sentinel at `.brainclaw/coordination/runtime/ack/<assignmentId>.ack`. This proves the spawn actually executed and decouples the handshake from MCP availability inside the worker — important because Codex spawned in `--sandbox workspace-write` may not have brainclaw MCP wired in its session.
+
+## Capability profile
+
+| Field | Value |
+|-------|-------|
+| Tier | A |
+| MCP | yes |
+| Hooks | yes |
+| Auto-approve | manual (per-tool approval) |
+| Skills | yes |
+| CLI spawnable | yes |
+| Max concurrent tasks | 5 |
+| Workflow model | task-based (one-shot exec, not interactive) |
+| MCP config scope | machine |
+| Prompt delivery | `stdin_pipe` (preferred), `inline_arg` (fallback) |
+
+## Caveats
+
+- **Sandbox blocks MCP writes**: when running with strict sandbox, the spawned Codex cannot write to `.brainclaw/` directly. Use the brief-ack file plus filesystem-direct candidate writes (the dispatcher harvests them).
+- **Windows quoting**: long prompts containing backticks or `#` fail when passed as inline args through `cmd.exe`. The default stdin_pipe path avoids this.
+- **Sandbox vs review parity**: review runs use the same `workspace-write` sandbox as execution runs (older templates forced `read-only` on reviews; that path blocked PowerShell exec on Windows).
+- **No always-allow**: each MCP tool call still respects per-call approval policy unless explicitly set with `-c approval_policy="never"`.

package/docs/integrations/continue.md

@@ -0,0 +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:
+
+```bash
+brainclaw export --format continue-rules --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.
+
+brainclaw does not yet emit `permissions.yaml` automatically — configure manually if running headless.
+
+## 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.
+- **No auto-approve writer**: brainclaw does not emit `permissions.yaml` yet — tool approval must be configured manually.
+- **No native subagents**: Continue does not expose subagent orchestration.
+- **Windows**: Works via VS Code extension; CLI (`cn`) requires Node.js on PATH.

package/docs/integrations/copilot.md

@@ -1,22 +1,80 @@
 # GitHub Copilot Integration
 
-brainclaw complements Copilot by making shared project context explicit and local.
+brainclaw integrates with GitHub Copilot through MCP tools, instruction files, and lifecycle hooks. Copilot is a Tier A agent — full MCP access, hooks, skills support, and headless CLI spawn capability since CLI 1.0.35.
 
 ## Auto-setup
 
-`brainclaw init` detects Copilot and writes `.github/copilot-instructions.md` automatically. Or manually:
+`brainclaw init` detects Copilot (`gh copilot` or `copilot` CLI installed) and writes:
+
+- `.github/copilot-instructions.md` — instruction file Copilot reads automatically on each prompt
+- MCP registration at `~/.copilot/mcp-config.json` (machine-level fallback) and/or project-level `.github/copilot/mcp-config.json`
+
+Manual regeneration:
 
 ```bash
 brainclaw export --format copilot-instructions --write
+brainclaw export --format copilot-instructions --write --include-live
+```
+
+## MCP configuration
+
+Copilot reads MCP servers from `~/.copilot/mcp-config.json`:
+
+```json
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
+    }
+  }
+}
+```
+
+For per-session overrides (typical when spawning Copilot from a dispatcher), pass `--additional-mcp-config @<path-to-config.json>` on the CLI invocation. This was validated end-to-end during pln#440.
+
+## Instruction files
+
+- `.github/copilot-instructions.md` — Copilot reads this automatically. Keep it lightweight and behavioural.
+- `.github/copilot-instructions.live.md` — optional local live companion with current plans, claims, traps, candidates, and handoffs. Write it with `brainclaw export --format copilot-instructions --write --include-live`; it stays gitignored even when the main instruction file is shared/versioned.
+- By default, live state flows through MCP. The live companion is parity/backstop context for native-file workflows.
+
+## Headless invocation
+
+Since Copilot CLI 1.0.35 (validated 2026-04-24), Copilot is CLI-spawnable in headless mode. The canonical invoke template is:
+
+```bash
+copilot -p "{prompt}" --allow-all --no-ask-user
+```
+
+- `--allow-all` (or equivalent `--yolo`) disables interactive approval prompts (combines `--allow-all-tools --allow-all-paths --allow-all-urls`).
+- `--no-ask-user` runs autonomously without pausing for clarifying questions.
+- `-p` (or `--prompt`) takes the prompt as the next positional argument. Output is silent unless `-s` is also passed.
+
+For machine-readable output (JSONL events per line):
+
+```bash
+copilot -p "{prompt}" --allow-all --no-ask-user --output-format json
 ```
 
-## Recommended approach
+## Capability profile
 
-- use MCP whenever the Copilot surface supports it for fresh context and coordination views
-- keep `.github/copilot-instructions.md` lightweight and behavioral
-- use `.brainclaw/project.md` as readable fallback (derived view, regenerated best-effort — may need `brainclaw rebuild` if stale)
-- use plans, claims, and handoffs to reduce ambiguity across sessions
+| Field | Value |
+|-------|-------|
+| Tier | A |
+| MCP | yes |
+| Hooks | yes |
+| Auto-approve | manual (per-call) |
+| Skills | yes |
+| CLI spawnable | yes (1.0.35+) |
+| Max concurrent tasks | 1 |
+| Workflow model | interactive |
+| MCP config scope | project (project-level config + machine-level fallback) |
+| Prompt delivery | `inline_arg` (preferred), `inbox_structured` (fallback) |
 
-## Why this matters
+## Caveats
 
-Copilot benefits from explicit project memory and shared coordination state instead of relying only on implicit memory features.
+- **CLI version**: headless spawn requires Copilot CLI 1.0.35 or later. Earlier versions failed silently when invoked headless and were treated as inbox-only by brainclaw.
+- **Quota awareness**: Copilot enforces a per-window credit budget visible in session metadata. The dispatcher uses `max_concurrent_tasks=1` to avoid exhausting it on parallel work.
+- **Update cadence**: keep `copilot` updated (`copilot update`) — flags and behaviour have moved between releases (`--yolo` was added, `--additional-mcp-config` flag was renamed once).
+- **Windows path resolution**: on Windows, `where copilot` may resolve to multiple paths (`.exe`, `.cmd`, npm shim). The brainclaw dispatcher resolves via `where` and prefers the `.exe` form when present.

package/docs/integrations/kilocode.md

@@ -0,0 +1,72 @@
+# Kilo Code Integration
+
+brainclaw integrates with Kilo Code through MCP tools and instruction files, providing shared memory, plans, and coordination. Kilo Code is a fork of the Cline/Roo family with its own config paths.
+
+## Auto-setup
+
+`brainclaw init` detects Kilo Code and writes `.kilo/rules/brainclaw.md` automatically (per the writer in `src/core/agent-files.ts`). The MCP config at `.kilo/mcp.json` is also generated when applicable.
+
+## MCP configuration
+
+Kilo Code reads MCP servers from `~/.config/kilo/kilo.jsonc` (global) or `kilo.jsonc` (project-scoped):
+
+```jsonc
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"]
+    }
+  }
+}
+```
+
+Note: Kilo uses JSONC (JSON with comments), not plain JSON.
+
+## Permissions
+
+Kilo Code supports per-tool permission control and per-server `alwaysAllow`:
+
+```jsonc
+{
+  "mcpServers": {
+    "brainclaw": {
+      "command": "npx",
+      "args": ["-y", "brainclaw@latest", "mcp"],
+      "alwaysAllow": ["bclaw_context", "bclaw_work", "bclaw_find", "bclaw_get"]
+    }
+  }
+}
+```
+
+Individual tools can also use `permission: { tool: "allow" | "ask" | "deny" }` syntax.
+
+## Instruction files
+
+- `AGENTS.md` — standard instruction file (shared with Codex, OpenCode)
+- `.kilo/rules/brainclaw.md` — Kilo-specific brainclaw rules (auto-written)
+
+## SKILL.md discovery
+
+Kilo Code auto-discovers skills from `.kilocode/skills/`, `.claude/skills/`, and `.agents/skills/`. A single `.agents/skills/brainclaw/SKILL.md` is picked up automatically.
+
+## Headless invocation
+
+```bash
+kilo --auto --json /path/to/project
+```
+
+The `--auto` flag enables YOLO mode (no approval prompts). `--json` provides structured output.
+
+## Invoke template
+
+```bash
+kilo /path/to/project
+```
+
+## Caveats
+
+- **Cline/Roo family fork**: Config patterns are similar to Cline and Roo but paths differ (`.kilo/` vs `.cline/` vs `.roo/`).
+- **JSONC format**: Config files use JSONC (comments allowed), not plain JSON. Parsers must handle this.
+- **No hooks**: Hook support is tracked in issue #5827 but not yet public.
+- **Windows/Linux**: Works via VS Code extension on all platforms.