brainclaw 1.8.0 → 1.9.1

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
-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 --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.
+
+### 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.

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,88 +1,87 @@
-# 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.
+# 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.
+
+## 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 |
+|-------|-------|
+| 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
+
+- **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,6 +1,6 @@
 # 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.
+brainclaw integrates with OpenAI's Codex CLI through MCP tools and shared instruction files. Codex has MCP access, universal skills support, and headless CLI spawn capability, but no native lifecycle hook surface.
 
 ## Auto-setup
 
@@ -61,7 +61,7 @@ Since pln#476 (1.0.13+), spawned Codex workers are marked `delivered_and_started
 |-------|-------|
 | Tier | A |
 | MCP | yes |
-| Hooks | yes |
+| Hooks | no |
 | Auto-approve | manual (per-tool approval) |
 | Skills | yes |
 | CLI spawnable | yes |