campfirein/byterover-cli/skill

ByteRover Knowledge Management

Use the brv CLI to manage your project's long-term memory. Knowledge is stored in .brv/context-tree/ as human-readable Markdown.

Install: npm install -g byterover-cli. No authentication needed. No LLM provider needed. brv query, brv search, brv read, brv curate, and brv vc (local version control) all run locally. Your own LLM drives any synthesis or HTML authoring step. Login is only required for remote sync (brv vc push / brv vc pull).

First-Turn Routing

Check this before anything else on every user turn.

If the user message reads as a request for an introduction, tour, or overview of ByteRover — for example:

• "Show me how ByteRover works" (canonical phrase from the install docs)
• "Walk me through ByteRover" / "Give me a ByteRover tour"
• "How does ByteRover work?"
• "Intro me to ByteRover" / "Show me ByteRover"
• Any semantic equivalent ("can you walk me through this", "explain ByteRover to me", etc.)

→ Stop reading this file. Open `onboarding.md` and follow it. Do NOT run brv query, brv search, or brv curate before the tour — the tour itself runs those commands as part of the demonstration.

For every other request, continue below to the Iron Law.

The Iron Law

QUERY BEFORE THINKING. CURATE AFTER IMPLEMENTING.

brv query first — retrieve relevant context from the context tree before forming an answer or starting a change. brv curate after — save new patterns, decisions, or learned facts before claiming done. Violating the letter of the rule is violating the spirit of the rule. No exceptions without your human partner's permission.

Curate Dispatch — Read This Before Calling brv curate

brv curate is a multi-step session (kickoff → author → continuation → validate, ~10-60s per topic) that BLOCKS the user's conversation when run inline. Your default for any substantive curate is to dispatch it to the saved `brv-curate` sub-agent — the operational protocol (HTML contract, session state machine, envelope path, --response-file form, path-exists merging, retry cap, return shape) lives in the saved agent's definition, so your dispatch ONLY hands over the facts.

Claude Code — tool-call dispatch:

Agent({
  subagent_type: "brv-curate",
  description: "brv curate (background)",
  prompt: `Curate the following 1-5 facts:\n1. <summary>\n   Body: <context>\n...`,
  run_in_background: true,
})

Codex — conversational dispatch (Codex has no subagent_type tool param; it spawns named agents on explicit instruction):

Spawn the brv-curate agent with the following 1-5 facts. Return the aggregate { completed, pending_review, failed, file_paths }.

1. <summary> — Body: <context>

2. <summary> — Body: <context> ...

Decision in one line:

Do NOT run a substantive curate inline. Do NOT fan out N parallel sub-agents on the same project — the daemon's overlap lock will reject every sub-agent after the first. Do NOT inline the curate protocol into the dispatch prompt — the saved agent definition has it.

The saved agent definition MUST be deployed at the right path for each surface:

Full dispatch shape, permission pre-authorization, the chunked-orchestrator pattern, and both saved-agent definitions all live in curate.md. Open it before your first curate dispatch in any session.

When To Use This Skill

Invoke brv when:

• The user wants you to recall something from this project
• Your context does not contain information you need
• Before performing any action, to check for relevant rules, criteria, or preferences
• You need to recall your capabilities or prior actions
• The user wants you to remember something
• The user intentionally curates memory or knowledge
• There are meaningful memories from user interactions worth persisting
• There are important facts about what was done, what is known, or what decisions and actions have been taken

When NOT To Use This Skill

Do NOT invoke brv when:

• The information is already present in your current context
• The query is about general knowledge, not stored memory
• The information is already stored unchanged
• The information is transient (only relevant to the current task) or general knowledge

Decision Flowchart

digraph brv_flow {
    start [label="User message arrives", shape=doublecircle];
    need_context [label="Need project context\nfor the next step?", shape=diamond];
    skip [label="Skip brv.\nRespond from context.", shape=ellipse];
    know_path [label="Already know the\nexact topic path?", shape=diamond];
    paths_only [label="Need ranked paths /\nexcerpts only?", shape=diamond];
    swarm_cfg [label="2+ memory providers\nconfigured?\n(brv swarm status)", shape=diamond];
    query [label="brv query <text>\n--format json", shape=box, style=filled, fillcolor="#ccffcc"];
    search [label="brv search <text>", shape=box, style=filled, fillcolor="#ccffcc"];
    read [label="brv read <path>", shape=box, style=filled, fillcolor="#ccffcc"];
    swarm_q [label="brv swarm query <text>", shape=box, style=filled, fillcolor="#ccffcc"];
    work [label="Do the work", shape=box];
    learned [label="Made a change,\ndecision, or discovery\nworth persisting?", shape=diamond];
    bootstrap [label="6+ substantive curates\nin this turn?\n(bootstrap / repo scan)", shape=diamond];
    substantive [label="Substantive?\n(decision / arch fact /\nbug+fix / convention)", shape=diamond];
    bg_batch [label="Multiple brv-curate sub-agent\ndispatches, 2-5 facts per chunk,\nfired SEQUENTIALLY.\n\nSee curate.md § Bootstrap", shape=box, style=filled, fillcolor="#ffcccc"];
    bg_curate [label="Dispatch the brv-curate\nsub-agent (Claude: Agent(...);\nCodex: 'Spawn brv-curate').\n\nDefault for substantive curates\n(handles up to 5 in one sub-agent).\nSee curate.md § Background Execution", shape=box, style=filled, fillcolor="#ffcccc"];
    curate [label="brv curate <intent>\n(inline — session protocol)", shape=box, style=filled, fillcolor="#ffcccc"];
    done [label="Done", shape=ellipse];
 
    start -> need_context;
    need_context -> skip [label="no"];
    need_context -> know_path [label="yes"];
    know_path -> read [label="yes"];
    know_path -> paths_only [label="no"];
    paths_only -> search [label="yes"];
    paths_only -> swarm_cfg [label="no"];
    swarm_cfg -> swarm_q [label="yes"];
    swarm_cfg -> query [label="no"];
    query -> work;
    search -> work;
    read -> work;
    swarm_q -> work;
    work -> learned;
    learned -> done [label="no"];
    learned -> bootstrap [label="yes"];
    bootstrap -> bg_batch [label="yes"];
    bootstrap -> substantive [label="no"];
    substantive -> bg_curate [label="yes (default)"];
    substantive -> curate [label="trivial /\nturn-dependent /\nuser said wait"];
    bg_batch -> done;
    bg_curate -> done;
    curate -> done;
}

Detailed Guides

• onboarding.md - 90-second introduction tour; follow when the user asks for an overview, intro, or tour of ByteRover (canonical phrase: "Show me how ByteRover works")
• query.md - retrieval protocol for brv query, brv swarm query, brv search, and brv read
• curate.md - saving durable project knowledge, including the HTML <bv-topic> contract
• review.md - handling pending human review after curate
• swarm.md - swarm query and external-provider storage
• vc.md - local context-tree version control
• dream.md - context-tree cleanup via brv dream's three-phase scan / curate / finalize workflow
• history.md - query and curate history inspection
• troubleshooting.md - brv error handling, data-handling, and file-input limits

Quick Reference

Common Rationalizations

These are excuses agents reach for. Each one is wrong. If you catch yourself thinking the left column, the right column is reality:

Red Flags — STOP and Restart

If you catch yourself in any of these states, STOP and reset: