brainclaw 1.9.0 → 1.10.0

package/docs/integrations/copilot.md

@@ -1,25 +1,25 @@
-# GitHub Copilot Integration
-
-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
-
+# GitHub Copilot Integration
+
+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 (`gh copilot` or `copilot` CLI installed) and writes:
 
 - `.github/copilot-instructions.md` — instruction file Copilot reads automatically on each prompt
 - `.vscode/settings.json` and `.vscode/mcp.json` — project-level MCP registration used by VS Code/Copilot surfaces
 - `.github/copilot/hooks.json` — session lifecycle hooks where supported
 - `.github/skills/brainclaw-context/SKILL.md` and `.agents/skills/brainclaw/SKILL.md` — Copilot and cross-agent skill discovery
-
-Manual regeneration:
-
-```bash
-brainclaw export --format copilot-instructions --write
-brainclaw export --format copilot-instructions --write --include-live
-```
-
-## MCP configuration
-
+
+Manual regeneration:
+
+```bash
+brainclaw export --format copilot-instructions --write
+brainclaw export --format copilot-instructions --write --include-live
+```
+
+## MCP configuration
+
 VS Code/Copilot reads project MCP configuration from `.vscode/settings.json` and `.vscode/mcp.json`:
 
 ```json
@@ -28,55 +28,55 @@ VS Code/Copilot reads project MCP configuration from `.vscode/settings.json` and
     "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
-```
-
-## Capability profile
-
-| 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) |
-
-## Caveats
-
-- **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.
+    }
+  }
+}
+```
+
+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
+```
+
+## Capability profile
+
+| 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) |
+
+## Caveats
+
+- **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/cursor.md

@@ -1,23 +1,23 @@
-# Cursor Integration
-
-brainclaw works well next to Cursor because Cursor can already operate with project rules and can benefit from explicit workspace context.
-
-## Auto-setup
-
-`brainclaw init` detects Cursor (`CURSOR_TRACE_ID`) and writes `.cursor/rules/brainclaw.md` automatically. Or manually:
-
-```bash
-brainclaw export --format cursor-rules --write
-```
-
-## Recommended approach
-
-- use MCP as the default dynamic path for context, board state, plans, and claims
-- let the generated `.cursor/rules/brainclaw.md` tell Cursor when to consult Brainclaw and how to stay inside the workflow
-- use `.brainclaw/project.md` only as readable fallback (derived view, may be stale — run `brainclaw rebuild` to refresh)
-- rely on claims and plans when multiple agents or humans are active in the same repo
-
-## Key point
-
-Cursor rules describe behavior.
-brainclaw provides the living shared state those rules should point to through MCP.
+# Cursor Integration
+
+brainclaw works well next to Cursor because Cursor can already operate with project rules and can benefit from explicit workspace context.
+
+## Auto-setup
+
+`brainclaw init` detects Cursor (`CURSOR_TRACE_ID`) and writes `.cursor/rules/brainclaw.md` automatically. Or manually:
+
+```bash
+brainclaw export --format cursor-rules --write
+```
+
+## Recommended approach
+
+- use MCP as the default dynamic path for context, board state, plans, and claims
+- let the generated `.cursor/rules/brainclaw.md` tell Cursor when to consult Brainclaw and how to stay inside the workflow
+- use `.brainclaw/project.md` only as readable fallback (derived view, may be stale — run `brainclaw rebuild` to refresh)
+- rely on claims and plans when multiple agents or humans are active in the same repo
+
+## Key point
+
+Cursor rules describe behavior.
+brainclaw provides the living shared state those rules should point to through MCP.

package/docs/integrations/kilocode.md

@@ -1,72 +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.
+# 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.