brainclaw 0.19.5 → 0.19.6

package/docs/concepts/coordination.md

@@ -0,0 +1,52 @@
+# Coordination
+
+brainclaw is not only a memory layer.
+It is also a coordination layer.
+
+That distinction matters.
+
+## Why coordination is needed
+
+Multiple humans and coding agents working in the same repo can easily:
+
+- duplicate work
+- miss handoffs
+- overwrite each other
+- diverge on plan status
+- act on stale assumptions
+
+Traditional instruction files do not solve this well because they describe how to behave, but not what is currently happening.
+
+## What brainclaw adds
+
+brainclaw introduces shared operational state for a workspace, including:
+
+- plans
+- task status
+- file claims
+- handoffs
+- runtime notes
+- board views
+
+## The key idea
+
+A workspace should expose not only what the project knows, but also what is currently being done.
+
+That includes:
+
+- what matters
+- what is active
+- who is working where
+- what is blocked
+- what needs review or handoff
+
+## Why this is different from another agent
+
+brainclaw does not try to become the agent that does everything.
+It helps many tools collaborate against the same workspace state.
+
+## Related pages
+
+- [plans-and-claims.md](plans-and-claims.md)
+- [runtime-notes.md](runtime-notes.md)
+- [../integrations/overview.md](../integrations/overview.md)

package/docs/concepts/memory.md

@@ -0,0 +1,87 @@
+# Memory
+
+brainclaw uses the term **memory** in an explicit, workspace-oriented sense.
+
+This is not an opaque cloud memory feature.
+It is shared project state stored locally in a structured, inspectable form.
+
+## What memory includes
+
+Durable memory can include:
+
+- **instructions** — agent workflow instructions written to native formats (CLAUDE.md, .cursor/rules/, etc.)
+- **constraints** — active project constraints that agents must respect
+- **decisions** — logged architectural or process decisions
+- **traps** — documented pitfalls to avoid (with severity and remediation)
+- **handoffs** — structured context transfers between agents or sessions
+- **plans** — shared work items with status, priority, and estimation data
+- **claims** — active file/scope ownership signals for collision avoidance
+- **runtime notes** — short-lived observations from the current session
+- **audit log** — timestamped record of all brainclaw operations in the workspace
+
+These are the pieces of context that should survive across sessions and be readable by both humans and agents.
+
+## Durable vs runtime
+
+A useful mental model is to separate:
+
+### Durable memory
+Shared project knowledge worth keeping.
+
+Examples: constraints, decisions, traps, completed plans, handoffs.
+
+Shared traps now have a lifecycle too: `active`, `resolved`, or `expired`. Active views such as generated context, status, and `project.md` prioritize only active traps so old machine-setup issues stop polluting the current working set, while the canonical memory still keeps resolved traps for audit and search.
+
+These live in `.brainclaw/store.json` and are shared via Git (or by reading the same file).
+
+### Runtime memory
+Operational observations that may be short-lived, host-specific, or private.
+
+Examples: "this API key only works in staging", "the test server is slow today", temporary notes during a session.
+
+Runtime notes are stored separately and can be given a TTL so they expire automatically.
+
+Not everything seen during execution should become canonical memory immediately.
+
+## Why explicit memory matters
+
+Without explicit memory, project context tends to scatter across:
+
+- chat history
+- agent prompts
+- personal notes
+- unstated assumptions
+- hidden tool memory
+
+brainclaw makes this context visible and versionable.
+
+## Readable vs canonical
+
+brainclaw keeps:
+
+- canonical structured JSON as the source of truth (`.brainclaw/store.json`)
+- a generated readable view in each agent's native format (`CLAUDE.md`, `.cursor/rules/brainclaw.md`, etc.)
+
+This balances machine reliability with human readability.
+
+The generated files are **local-only** and should not be committed to Git — each developer regenerates them from their own `.brainclaw/` store. Add them to `.gitignore` (brainclaw does this automatically during `init`).
+
+## Accessing memory
+
+```bash
+brainclaw context               # full context as text
+brainclaw context --json        # full context as JSON (for agents)
+brainclaw agent-board           # live plan + claim board
+brainclaw claim list            # active claims
+brainclaw plan list             # all plans
+brainclaw audit                 # audit log
+```
+
+MCP tools expose the same data to agents that support the Model Context Protocol.
+
+## Related pages
+
+- [coordination.md](coordination.md)
+- [runtime-notes.md](runtime-notes.md)
+- [workspace-bootstrapping.md](workspace-bootstrapping.md)
+- [plans-and-claims.md](plans-and-claims.md)

package/docs/concepts/plans-and-claims.md

@@ -0,0 +1,139 @@
+# Plans and Claims
+
+Plans and claims are where brainclaw starts to feel less like a note system and more like a coordination layer.
+
+## Plans
+
+Plans provide a shared view of intended work.
+
+They help teams and agents answer questions like:
+
+- what are we trying to ship?
+- what is in progress?
+- what is blocked?
+- what is done?
+- who is responsible right now?
+
+### Plan statuses
+
+| Status | Meaning |
+|--------|---------|
+| `todo` | Not started yet |
+| `in_progress` | Actively being worked on |
+| `done` | Completed |
+| `blocked` | Waiting on something external |
+| `dropped` | Dropped |
+
+### Creating plans
+
+```bash
+brainclaw plan create "implement login flow"
+brainclaw plan create "refactor auth module" --priority high --estimate 120
+```
+
+The `--estimate` flag accepts a **positive integer in minutes**. Example: `--estimate 30` means 30 minutes, `--estimate 120` means 2 hours.
+
+### Updating plans
+
+```bash
+brainclaw plan update <id> --status in_progress
+brainclaw plan update <id> --status done --actual-effort 45min
+```
+
+When marking a plan `in_progress` for the first time, `started_at` is automatically recorded.
+When marking a plan `done`, `completed_at` is automatically recorded.
+
+### Plan steps
+
+Plans can have sub-steps for multi-phase work:
+
+```bash
+brainclaw add-step <plan-id> "write unit tests"
+brainclaw add-step <plan-id> "update docs"
+brainclaw complete-step <plan-id> <step-index>
+```
+
+Steps show up in `brainclaw context` and `brainclaw board` so other agents and humans can see granular progress.
+
+### Estimation and calibration
+
+When both `estimated_effort` and `actual_effort` are present on completed plans, brainclaw can compute an accuracy report:
+
+```bash
+brainclaw estimation-report
+brainclaw estimation-report --agent my-agent
+```
+
+This shows a ratio chart (actual / estimate) and a calibration hint:
+
+```
+task with estimate      est:30min  actual:45min  [ratio:1.5x]
+[0.0x    ░░░░░░░░░░│████████████████████░░░░░░░░░░░░░░░░░  2.0x+]
+                                                        OVER +50%
+```
+
+A ratio below 1.0 means the task finished faster than expected (early). Above 1.0 means it took longer (over).
+
+## Claims
+
+Claims make current ownership explicit.
+
+A claim can represent:
+
+- a file
+- a folder
+- a feature area
+- a work scope linked to a plan item
+
+Claims help reduce collisions when multiple humans or agents work in parallel.
+
+### Creating claims
+
+```bash
+brainclaw claim create "refactoring auth module" --scope src/auth/
+brainclaw claim create "updating docs" --scope docs/ --ttl 4h
+brainclaw claim create "fixing login bug" --scope src/auth/ --plan <plan-id>
+```
+
+The `--ttl` flag sets a time-to-live for the claim. After expiry, the claim is no longer considered active by other agents. Valid formats: `30min`, `2h`, `1d`.
+
+### Listing and releasing claims
+
+```bash
+brainclaw claim list
+brainclaw claim release <id>
+```
+
+`claim list` shows who holds each claim and whether it is still active. If a claim has a `session_id`, the last 8 characters are shown so you can correlate with the agent session that created it.
+
+## Why claims matter
+
+Without claims, multiple agents can easily touch the same area at once and generate conflicting changes.
+Claims are not necessarily hard file locks.
+They are a shared coordination signal.
+
+## Recommended workflow
+
+1. create a plan item
+2. claim the target scope
+3. work on the implementation
+4. update the plan status
+5. release the claim when done or blocked
+6. create a handoff if another actor should continue
+
+## Session hygiene
+
+Before finishing a session, always:
+
+- release active claims: `brainclaw claim release <id>`
+- update plan items: `brainclaw plan update <id> --status done`
+- or use `brainclaw session-end --auto-release` to clean up automatically
+
+`session-end --auto-release` releases all claims held by the current agent and marks any `in_progress` plans as needing attention.
+
+## Plans + claims together
+
+Plans describe what should happen.
+Claims describe who is currently working where.
+
+That combination is much more useful than either one alone.

package/docs/concepts/runtime-notes.md

@@ -0,0 +1,38 @@
+# Runtime Notes
+
+Runtime notes capture operational observations made during work.
+
+They help bridge the gap between live execution and durable project memory.
+
+## Examples
+
+- a local environment quirk
+- a host-specific issue
+- a temporary blocker
+- a short-lived implementation observation
+- a note worth later reflection
+
+## Visibility modes
+
+Depending on configuration and use, runtime notes may be:
+
+- shared
+- machine-local
+- private
+
+This lets teams keep transient or host-specific context available without polluting canonical project memory too early.
+
+## Reflection workflow
+
+A runtime note does not have to become durable memory immediately.
+A useful pattern is:
+
+1. capture the observation quickly
+2. keep it visible in runtime state
+3. reflect it into a candidate if it seems reusable
+4. accept or reject it later through review
+
+## Why this matters
+
+This creates a safer bridge from ephemeral facts to durable memory.
+Not every operational observation deserves instant promotion.

package/docs/concepts/workspace-bootstrapping.md

@@ -0,0 +1,40 @@
+# Workspace Bootstrapping
+
+brainclaw is workspace-aware.
+Shared memory is not assumed to exist everywhere by default.
+
+## Why bootstrap exists
+
+A workspace may be:
+
+- already initialized
+- known to the agent integration layer but not initialized locally
+- entirely new
+
+Bootstrap is the process that turns a workspace into a brainclaw-aware workspace.
+
+## What bootstrap does
+
+Bootstrap is more than creating a folder.
+It establishes the first shared memory foundation for the workspace:
+
+- inspects the repository structure
+- detects the AI coding agent environment
+- seeds stable workspace identity (`project_id`, `agent_id`)
+- creates the initial storage structure
+- writes to the detected agent's native instruction file (Cursor, Claude Code, Windsurf, etc.)
+- creates `AGENTS.md` and `.github/copilot-instructions.md`
+
+## Good integration pattern
+
+1. check whether the workspace is initialized
+2. if yes, retrieve fresh memory
+3. if not, bootstrap when allowed
+4. then use shared memory normally
+
+## Why this matters for agents
+
+If shared memory is absent, that should not always be interpreted as "there is no relevant context".
+It may simply mean the workspace has not been onboarded yet.
+
+This lets a single machine support multiple very different workspaces without forcing one static instruction layer to fit all of them equally well.

package/docs/context-format-changelog.md

@@ -0,0 +1,35 @@
+# Context Format Changelog
+
+## 1.3
+
+- Added `available_capabilities` field to structured context containing registered project capabilities with metadata (id, name, category)
+- Added `available_tools` field to structured context containing registered project tools with metadata (id, name, type)
+- Enhanced text output to include "Available Capabilities" and "Available Tools" sections when metadata is present
+- Added discovery hints pointing users to `bclaw_get_capabilities`, `bclaw_list_tools`, and `bclaw_search_tools` MCP tools
+- Kept the contract additive and backward-compatible with `1.2`
+
+## 1.2
+
+- Added `context_diff` to expose compact memory deltas since a session started.
+- Clarified the public contract for contradiction-aware session context refreshes.
+- Kept the contract additive and backward-compatible with `1.1`.
+
+## 1.1
+
+- Added explicit `context_schema` rendering in markdown and template outputs.
+- Added `agent_tooling.agents_rules`.
+- Added skill metadata flags: `scripts_present`, `references_present`, `assets_present`.
+- Added MCP inventory metadata: `availability`, `source`.
+- Kept the contract additive and backward-compatible with `1.0`.
+
+## 1.0
+
+- Baseline contract introduced with:
+  - `digest`
+  - `memory_density`
+  - `bootstrap_available`
+  - `derived_signals`
+  - `execution_context`
+  - `agent_tooling`
+  - `scoped_activity`
+  - `selected`

package/docs/context-format.md

@@ -0,0 +1,48 @@
+# Context Format
+
+`brainclaw context` and `bclaw_get_context` expose a versioned public contract for agent consumers.
+
+Current version: `1.2`
+
+## Stable top-level fields
+
+- `context_schema`
+- `digest`
+- `memory_density`
+- `bootstrap_available`
+- `derived_signals`
+- `execution_context`
+- `agent_tooling`
+- `scoped_activity`
+- `context_diff`
+- `selected`
+
+## Compatibility policy
+
+- Additive changes bump the minor version.
+- Breaking changes bump the major version.
+- Fields listed above are treated as public and stable for agent consumers.
+- Future enrichments should prefer optional fields over reshaping existing ones.
+
+## `1.2` additions over `1.1`
+
+- `context_diff` is available for session-aware deltas through `brainclaw context --since-session` and `bclaw_get_context`.
+- `context_schema: 1.2` is emitted across JSON, markdown, template, and MCP structured content.
+
+## `1.1` additions over `1.0`
+
+- `context_schema` is now explicitly surfaced in markdown and template renders.
+- `agent_tooling` includes `agents_rules`.
+- `agent_tooling.skills[]` includes bounded capability markers:
+  - `scripts_present`
+  - `references_present`
+  - `assets_present`
+- `agent_tooling.mcp_servers[]` includes:
+  - `availability`
+  - `source`
+
+## Semantics
+
+- `execution_context` and `agent_tooling` are opportunistic and may be omitted when not useful.
+- `derived_signals` are non-canonical bootstrap hints, not accepted project memory.
+- `agent_tooling` inventories local capabilities and constraints; it does not imply project decisions.

package/docs/integrations/agents.md

@@ -0,0 +1,169 @@
+# 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
+- prompt-ready generated context
+- MCP tools when available
+- board and status views
+- workflow reminders around plans, claims, and handoffs
+
+## System instructions vs project instructions
+
+Keep these separate.
+
+### System instructions
+How the agent should use brainclaw.
+
+Examples:
+
+- check workspace memory before significant changes
+- 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
+
+## Setting up agent integration
+
+### Automatic detection
+
+```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.
+
+### Manual per-agent setup
+
+```bash
+brainclaw enable-agent claude-code
+brainclaw enable-agent cursor
+brainclaw enable-agent windsurf
+brainclaw enable-agent opencode
+brainclaw enable-agent antigravity
+```
+
+### Export to a specific format
+
+```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:
+
+```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.
+
+## MCP server workflow
+
+The brainclaw MCP server exposes all memory operations as tools that agents can call directly.
+
+### Starting the MCP server
+
+```bash
+brainclaw mcp
+```
+
+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
+```
+
+This registers the agent's identity and optionally records the model being used. Other agents can see active sessions in `list-claims` and `board`.
+
+### During the session
+
+At each significant step:
+
+```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
+```
+
+### Ending the session
+
+```bash
+brainclaw session-end --auto-release
+```
+
+This releases all active claims held by the current agent and updates plan statuses.
+
+## Generated files are local-only
+
+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**.
+
+Each developer regenerates them locally from their own `.brainclaw/` store:
+
+```bash
+brainclaw export --detect --write
+```
+
+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
+
+brainclaw adds all generated files to `.gitignore` automatically during `init`.
+
+## Goal
+
+The goal is not perfect enforcement.
+The goal is to make brainclaw the natural path for fresh workspace context and coordination.

package/docs/integrations/claude-code.md

@@ -0,0 +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
+
+- add lightweight usage instructions for brainclaw in `CLAUDE.md`
+- use `.brainclaw/project.md` as a readable baseline
+- prefer MCP for dynamic retrieval when available
+- 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.

package/docs/integrations/codex.md

@@ -0,0 +1,23 @@
+# 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
+
+- keep a lightweight instruction telling Codex to consult brainclaw
+- let Codex read `.brainclaw/project.md` when simple file context is enough
+- use MCP for fresher scoped context when available
+- encourage use of plans, claims, and handoffs during multi-step work
+
+## Good role for brainclaw here
+
+Codex stays the coding agent.
+brainclaw provides the shared workspace context and coordination layer.

package/docs/integrations/copilot.md

@@ -0,0 +1,21 @@
+# GitHub Copilot Integration
+
+brainclaw complements Copilot by making shared project context explicit and local.
+
+## Auto-setup
+
+`brainclaw init` detects Copilot and writes `.github/copilot-instructions.md` automatically. Or manually:
+
+```bash
+brainclaw export --format copilot-instructions --write
+```
+
+## Recommended approach
+
+- point Copilot to `.brainclaw/project.md` or use fresh context retrieval
+- use plans, claims, and handoffs to reduce ambiguity across sessions
+- use MCP where supported for dynamic collaboration views
+
+## Why this matters
+
+Copilot benefits from explicit project memory and shared coordination state instead of relying only on implicit memory features.