brainclaw 0.19.14 → 0.20.0

package/docs/architecture/project-refs.md

@@ -0,0 +1,305 @@
+# Project Refs for Multi-Project Navigation
+
+## Goal
+
+In a multi-project workspace, agents should be able to address any known project from anywhere in the workspace without depending on the current working directory.
+
+The core primitive for this is a stable `project_ref`.
+
+Examples:
+
+- `dev/repos/global`
+- `applications/lodestar`
+- `core_services/postgres`
+
+This lets Brainclaw support direct project navigation commands such as:
+
+- `brainclaw projects`
+- `brainclaw project applications/lodestar`
+- `brainclaw context --project applications/lodestar`
+- `brainclaw children dev/repos/global`
+- `brainclaw ancestors applications/lodestar`
+- `brainclaw dependencies applications/lodestar`
+- `brainclaw locate dev/repos/global/applications/lodestar/src/app.ts`
+
+The same addressing model must exist over MCP.
+
+## Why
+
+Current workspace-centric behavior is still too dependent on `cwd` and path heuristics:
+
+- `brainclaw context --for <path>` can help rerank context
+- in folder-mode workspaces it can now resolve a child store for some path-shaped targets
+- but the mental model is still "where am I on disk?"
+
+For agents, this is weaker than "which project am I addressing?"
+
+`project_ref` should become the natural addressing unit for:
+
+- context lookup
+- workspace navigation
+- parent/child traversal
+- dependency traversal
+- future project-scoped MCP tools
+
+## Core Model
+
+Each known project keeps its internal `project_id`.
+
+Each project also gets a stable human-readable `project_ref`:
+
+- derived from the workspace-relative path
+- normalized with forward slashes
+- unique within the workspace
+
+Examples:
+
+- workspace root: `.`
+- child repo: `dev/repos/global`
+- nested project: `dev/repos/global/applications/lodestar`
+
+The registry for a workspace project should expose at least:
+
+- `project_id`
+- `project_ref`
+- `project_name`
+- `relative_path`
+- `absolute_path`
+- `workspace_root`
+- `parent_ref`
+- `aliases`
+- `store_present`
+- `source`
+- `dependencies`
+
+## Naming Rules
+
+Canonical rule:
+
+- `project_ref` is the workspace-relative path to the project root
+
+Short aliases:
+
+- the final path segment may be used as an alias
+- only when unique within the workspace
+- ambiguous aliases must fail with a disambiguation error
+
+Examples:
+
+- `applications/lodestar` may have alias `lodestar`
+- if two projects end with `api`, `brainclaw project api` must fail and suggest full refs
+
+This keeps the model simple:
+
+- canonical ref is always deterministic
+- short names are optional ergonomics, not identity
+
+## Project Resolution
+
+Resolution should work from anywhere in the workspace.
+
+The resolver accepts:
+
+- exact `project_ref`
+- exact `project_id`
+- unique short alias
+- absolute path to a project root
+- absolute or relative path inside a project
+
+The resolver returns:
+
+- the matched project record
+- the resolved project root
+- the matched method: `ref`, `id`, `alias`, or `path`
+
+Resolution priority:
+
+1. exact `project_ref`
+2. exact `project_id`
+3. unique alias
+4. path-to-project containment
+
+If multiple matches remain, Brainclaw must stop and return a clear ambiguity error.
+
+## CLI Surface
+
+The minimal agent-first CLI surface should be:
+
+### `brainclaw projects`
+
+List known projects in the current workspace.
+
+Fields:
+
+- `project_ref`
+- `project_name`
+- `relative_path`
+- `parent_ref`
+- `store_present`
+
+### `brainclaw project <ref>`
+
+Show a compact project card.
+
+Fields:
+
+- `project_id`
+- `project_ref`
+- `aliases`
+- `absolute_path`
+- `parent_ref`
+- `children`
+- `dependencies`
+- store health summary
+
+### `brainclaw context --project <ref>`
+
+Resolve the target project first, then build context from that store.
+
+Notes:
+
+- this is stronger than `context --for`
+- `--for` still helps ranking within the resolved project
+
+Example:
+
+```bash
+brainclaw context --project applications/lodestar --for src/app.ts
+```
+
+### `brainclaw children <ref>`
+
+Return direct child projects.
+
+### `brainclaw ancestors <ref>`
+
+Return the project chain from parent to workspace root.
+
+### `brainclaw dependencies <ref>`
+
+Return declared or detected project dependencies.
+
+### `brainclaw locate <path>`
+
+Resolve any path to the owning project.
+
+This is especially useful for agents:
+
+- start from a changed file
+- ask Brainclaw which project owns it
+- then request context for that project
+
+## MCP Surface
+
+The MCP equivalents should mirror the CLI rather than invent a second addressing model.
+
+Suggested tools:
+
+- `bclaw_list_projects`
+- `bclaw_get_project`
+- `bclaw_get_project_context`
+- `bclaw_list_project_children`
+- `bclaw_list_project_ancestors`
+- `bclaw_list_project_dependencies`
+- `bclaw_locate_project`
+
+All of them should accept `project_ref` as the primary selector.
+
+`bclaw_get_context` may continue to exist, but multi-project agents should prefer `bclaw_get_project_context`.
+
+## Hierarchy Semantics
+
+Hierarchy comes from project roots on disk.
+
+Definitions:
+
+- parent: nearest known project root above the current project
+- child: known project whose nearest known parent is the current project
+- ancestor: repeated parent chain
+
+This is path-derived and deterministic.
+
+## Dependency Semantics
+
+Dependencies are different from hierarchy.
+
+Dependencies should support two sources:
+
+- declared links in Brainclaw metadata
+- detected links from repo/workspace tooling when reliable
+
+Examples:
+
+- monorepo package dependencies
+- service depends on shared database project
+- app depends on auth service
+
+The first iteration should allow declared dependencies first.
+
+Auto-detection can remain additive.
+
+## Storage Direction
+
+This does not require replacing current project ids or store layout.
+
+It requires a workspace project registry that can be rebuilt or refreshed non-destructively.
+
+Likely location:
+
+- workspace-level discovery inventory
+
+Likely persisted fields:
+
+- stable `project_ref`
+- alias set
+- hierarchy links
+- declared dependency links
+
+This should stay clearly separate from canonical memory items such as decisions and constraints.
+
+## Migration Strategy
+
+The migration should be low-risk and incremental.
+
+Phase 1:
+
+- introduce `project_ref` in workspace discovery/registry
+- expose `brainclaw projects`
+- expose `brainclaw locate`
+
+Phase 2:
+
+- add `context --project <ref>`
+- keep current `context --for <path>` behavior
+- when `--project` is present, it wins over cwd heuristics
+
+Phase 3:
+
+- add `children` and `ancestors`
+- add MCP equivalents
+
+Phase 4:
+
+- add declared dependencies
+- optionally add auto-detection
+
+## Non-Goals
+
+This design does not require:
+
+- replacing `project_id`
+- removing cwd-based commands
+- making aliases mandatory
+- making dependency inference perfect in the first release
+
+## Recommendation
+
+The first implementation slice should be:
+
+1. add `project_ref` to workspace project discovery
+2. add a project resolver shared by CLI and MCP
+3. add `brainclaw projects`
+4. add `brainclaw context --project <ref>`
+5. add `brainclaw locate <path>`
+
+That is enough to give agents a stable and simple project-addressing model without a risky refactor.

package/docs/cli.md

@@ -918,7 +918,7 @@ Generate compact, prompt-ready context for agents.
 
 | Option | Description |
 |---|---|
-| `--for <path>` | Scope context to a file or path |
+| `--for <path>` | Scope context to a file or path; in folder-mode workspaces, child project paths resolve the matching nested store automatically |
 | `--project <name>` | Filter by project |
 | `--agent <name>` | Filter by agent |
 | `--host <name>` | Filter by host |
@@ -938,6 +938,7 @@ Generate compact, prompt-ready context for agents.
 
 ```bash
 brainclaw context --for src/auth/routes.ts --digest
+brainclaw context --for applications/lodestar/src/app.ts --json
 brainclaw context --json --max-chars 1200
 brainclaw context --explain
 brainclaw context --since-session --max-items 20

package/docs/integrations/agents.md

@@ -1,182 +1,134 @@
-# 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 through MCP when available
-- prompt-ready generated context
-- native agent files for local reminders
-- MCP tools for dynamic state
-- board and status views
-- workflow reminders around plans, claims, and handoffs
-
-## Surface hierarchy
-
-The default order is:
-
-1. MCP for live state
-2. native agent files for local workflow guidance
-3. readable files as fallback
-4. CLI for setup, operator tasks, scripting, and fallback workflows
-
-This keeps dynamic state dynamic instead of trying to encode it permanently into static instructions.
-
-## System instructions vs project instructions
-
-Keep these separate.
-
-### System instructions
-How the agent should use brainclaw.
-
-Examples:
-
-- check workspace memory before significant changes
-- prefer MCP over manual CLI calls when MCP is available
-- 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
+# Agent Integration
 
-## Setting up agent integration
+## The problem brainclaw solves for agents
 
-### Automatic detection
+Coding agents are stateless. Each session starts from zero. They don't know:
 
-```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.
+- 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
 
-### Manual per-agent setup
+Brainclaw gives every agent access to this shared context through a combination of surfaces adapted to what each agent can handle.
 
-```bash
-brainclaw enable-agent claude-code
-brainclaw enable-agent cursor
-brainclaw enable-agent windsurf
-brainclaw enable-agent opencode
-brainclaw enable-agent antigravity
-```
+## Multiple points of contact
 
-### Export to a specific format
+No single mechanism is enough. Agents don't always obey a single instruction file. They sometimes skip MCP calls. They forget between prompts.
 
-```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:
+That's why brainclaw uses every available surface:
 
-```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.
+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
 
-## MCP server workflow
-
-The brainclaw MCP server exposes the dynamic Brainclaw workflow directly. For capable agents, this is the nominal runtime path.
+The more surfaces are active, the more reliably the agent uses brainclaw.
 
-### Starting the MCP server
+## What the instruction file contains
 
-```bash
-brainclaw mcp
-```
+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:
 
-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
-```
+### For agents with MCP and hooks (Claude Code)
 
-This registers the agent's identity and optionally records the model being used. Other agents can see active sessions in `list-claims` and `board`.
+Short and focused:
+- Why brainclaw matters for this project
+- The session protocol (hooks handle the rest)
+- Active constraints and instructions
+- Version check reminder
 
-### During the session
-
-For MCP-capable agents, prefer the MCP equivalents of these actions. The CLI examples below are the operator and fallback form of the same lifecycle.
+### For agents with MCP but no hooks (Cursor, Codex, OpenCode, etc.)
 
-```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
-```
+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 agents without MCP (Copilot)
+
+Full static context:
+- All of the above
+- Active plans with status and assignees
+- All shared traps
+- Recent architectural decisions
+
+## Setting up agent integration
 
-### Ending the session
+### Automatic (recommended)
 
 ```bash
-brainclaw session-end --auto-release
+brainclaw setup     # machine-level: detects agents, creates global configs
+brainclaw init      # project-level: creates .brainclaw/, writes agent files
 ```
 
-This releases all active claims held by the current agent and updates plan statuses.
+Or ask your coding agent to do it:
 
-## Generated files are local-only
+```
+"Install and initialize brainclaw in this project"
+```
 
-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**.
+The agent can use `bclaw_setup` to walk through the process interactively.
 
-Each developer regenerates them locally from their own `.brainclaw/` store:
+### 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 --detect --write
 ```
 
+For agents without MCP (Copilot), this is especially important — the instruction file 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 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
+- 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.
+
+## Session lifecycle
+
+### 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
+```
+
+### 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
+```
+
+### Finishing work
+
+```
+bclaw_session_end(auto_release: true) → release claims, update plans
+```
+
+### Plans and estimation
 
-brainclaw adds all generated files to `.gitignore` automatically during `init`.
+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.
 
-## Goal
+## Version awareness
 
-The goal is not perfect enforcement.
-The goal is to make brainclaw the natural path for fresh workspace context and coordination.
+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.