Canonical grammar — six verbs across every entity

brainclaw exposes a uniform CRUD surface across 17 entities : plan, step, claim, session, handoff, decision, constraint, trap, candidate, runtime_note, sequence, inbox_message, instruction, assignment, agent_run, action, cross_project_link.

Six verbs. Every entity. No per-entity tool invention.

# Read paths
bclaw_find    entity=plan filter={status: "in_progress"}
bclaw_get     entity=handoff id=hnd_abc123
bclaw_context kind=memory path="src/auth/"

# Write paths
bclaw_create     entity=decision data={text: "...", author: "..."}
bclaw_update     entity=plan id=pln_xyz patch={priority: "high"}
bclaw_remove     entity=trap id=trp_xyz
bclaw_transition entity=plan id=pln_xyz to=done

Worked example — capture and act on a decision

A typical end-to-end flow over the lifetime of a small refactor:

# 1. Plan the work
bclaw_create entity=plan data={
  text: "Replace REST auth with JWT verify middleware",
  author: "claude-code",
  priority: "high",
  related_paths: ["src/auth/"]
}
# → { id: "pln_abc", short_label: "pln#42" }

# 2. Decompose into steps
bclaw_add_step planId=pln_abc text="Pull request shape — sketch endpoint signature"
bclaw_add_step planId=pln_abc text="Wire the middleware in src/server/auth.ts"
bclaw_add_step planId=pln_abc text="Migrate tests to use signed tokens"

# 3. Claim the scope before editing
bclaw_work intent=execute scope="src/auth/" task="JWT middleware"
# → claim clm_abc, worktree at ~/.brainclaw/worktrees/<hash>/feat_src-auth/

# 4. While editing — capture a decision and a trap
bclaw_create entity=decision data={
  text: "JWT secret reads from env at boot, not on every request",
  author: "claude-code",
  outcome: "approved",
  plan_id: "pln_abc"
}
bclaw_create entity=trap data={
  text: "Token rotation forces a server restart — rolling deploy required",
  severity: "medium",
  related_paths: ["src/auth/middleware.ts"]
}

# 5. Mark the step done as you go
bclaw_complete_step planId=pln_abc stepId=stp_xyz

# 6. Hand off when paused mid-flight — handoffs are not a bclaw_create entity;
#    use the CLI (or the dedicated MCP tool) so the contract block is set right.
brainclaw handoff "Middleware wired, 2/3 tests pass. Token-rotation test failing on local clock skew." \
  --plan pln_abc \
  --pre-condition "npm install fresh" \
  --post-condition "All src/auth/*.test.ts pass"

# 7. Release the claim and transition the plan when done
bclaw_release_claim id=clm_abc planStatus=done
# or, separately:
bclaw_transition entity=plan id=pln_abc to=done

Why this matters

• Once-and-done learning — agents that know the grammar work on every entity without per-entity docs. New entity? Same six verbs.
• Schema-typed updates — EntityRegistry.updatable declares the patchable fields per entity. Patches against non-listed fields are rejected at the dispatch boundary, so bclaw_update entity=plan id=… patch={cursed_field: 1} returns a clear validation error rather than silently dropping the field (the reason bclaw_update is not an Object.assign on the raw record).
• Lifecycle-typed transitions — EntityRegistry.transitions declares valid status transitions. Invalid ones throw at runtime: trying to move a plan from dropped back to in_progress returns InvalidTransitionError instead of corrupting the lifecycle.
• Default read filtering — bclaw_find excludes provenance.kind="legacy" records and auto_reflect records below 0.6 confidence by default. Override via filter={includeLegacy: true, minAutoReflectConfidence: 0.3} when you need the long tail.

Beyond the six verbs

Two facade entry points cover the daily loop without verb-by-verb thinking — see bclaw_work and bclaw_context for the full pattern.

For multi-agent orchestration, the coordination facade adds three intents on top:

• bclaw_coordinate intent=assign — dispatches a brief to a target agent (claim + assignment + inbox message)
• bclaw_coordinate intent=review — opens a review loop with multi-turn delegation
• bclaw_coordinate intent=ideate — opens an ideation loop with critique gates

See coordination loops for the loop driver semantics.

Cross-project routing

Every canonical-grammar call, bclaw_context, and bclaw_coordinate accept an optional project: <name> argument that routes the operation to a linked project (cross_project_links from brainclaw link list OR a workspace store-chain child):

bclaw_get entity=trap id=trp_xyz project=brainclaw-site
bclaw_update entity=plan id=pln_abc patch={priority: "high"} project=brainclaw-cloud

Identity stays sourced from the caller; writes + audit land in the target project. Unknown project names throw — no silent fallback. The CLI exposes the same as --project <name>. Read the MCP integration feature for the full surface list.