docs:[ENG-2077] add brv swarm query and brv swarm curate to SKILL by cuongdo-byterover · Pull Request #409 · campfirein/byterover-cli

cuongdo-byterover · 2026-04-14T10:47:31Z

Summary

Problem: The SKILL.md template (used by the LLM agent) had no documentation for brv swarm query, brv swarm curate, or brv swarm status. The agent couldn't guide users on swarm memory commands.
Why it matters: Without SKILL documentation, the agent doesn't know these commands exist and can't use them during conversations.
What changed: Added Sections 8 (Swarm Query), 9 (Swarm Curate), and 10 (Swarm Status) to SKILL.md with command syntax, flags, sample outputs (text + JSON + explain mode), and guidance on when to use each command vs alternatives.
What did NOT change: No runtime code changes. No test changes. Only documentation.

Type of change

Scope (select all touched areas)

Linked issues

Closes ENG-2077
Related ENG-2072, ENG-2080

Root cause (bug fixes only, otherwise write `N/A`)

N/A

Test plan

Coverage added:
- Unit test
- Integration test
- Manual verification only
Test file(s): N/A (documentation only)
Key scenario(s) covered:
- Verified all sample commands execute correctly against a configured swarm
- Verified output format matches actual CLI output
- Fixed provider count (5 → 4) in example after review feedback

User-visible changes

LLM agent now knows how to use brv swarm query, brv swarm curate, and brv swarm status
Agent can suggest swarm commands when users ask about searching across knowledge sources

Evidence

Manual verification: all documented commands produce output matching the examples

Checklist

Tests added or updated and passing (npm test)
Lint passes (npm run lint)
Type check passes (npm run typecheck)
Build succeeds (npm run build)
Commits follow Conventional Commits format
Documentation updated (if applicable)
No breaking changes (or clearly documented above)
Branch is up to date with main

Risks and mitigations

None — documentation-only change with no runtime impact.

github-actions · 2026-04-14T10:47:47Z

Claude Code is working…

I'll analyze this and get back to you.

View job run

github-actions · 2026-04-14T10:48:22Z

Claude finished @cuongdo-byterover's task in 1m 23s —— View job

PR Review: docs:[ENG-2077] add brv swarm query and brv swarm curate to SKILL

Tasks

Gather context and read changed files
Review documentation for correctness, completeness, and quality
Post inline comments for specific issues
Post overall summary

Summary

Score: 4 / 5

The documentation is well-structured and consistent with the existing SKILL.md format. The "Use this when / Do NOT use this when" guidance is clear and useful, examples cover the main use cases (plain, --explain, --format json, -n), and the overall signal-to-noise ratio is good for an LLM skill file.

Five issues worth addressing before merge:

Severity	Location	Issue
bug	Line 314 (overview)	`honcho` appears in the `--explain` output block but is missing from the provider list in the overview — the two should match
bug	Line 373	`...` inside the JSON block is syntactically invalid JSON; expand to 2–3 full provider entries
question	Line 389	Content-type routing (entity → GBrain, note → Local Markdown) — is this auto-detected? A `--type` flag is not listed but seems expected
nit	Line 455	`~/.openclaw/wiki/main` — looks like a stale product name; likely should be a `~/.byterover/...` path
suggestion	Line 442	`brv swarm status` is buried inside section 9 (Curate) but is cross-referenced from section 8 (Query) — consider promoting it to its own section (10)

- Remove unsupported honcho provider from --explain example - Expand JSON sample to valid JSON (no ... placeholders) - Add auto-classification note to swarm curate overview - Promote swarm status to its own section 10

github-actions · 2026-04-14T11:07:08Z

Claude finished @cuongdo-byterover's task in 1m 52s —— View job

PR Review: docs:[ENG-2077] add brv swarm query and brv swarm curate to SKILL

Tasks

Gather context and read changed files
Review documentation for correctness, completeness, and quality
Post inline comments for specific issues
Post overall summary

Summary

Score: 4 / 5

Good follow-up on the previous review cycle. The previous round's suggestions have largely been addressed:

Previous Issue	Status
`honcho` in `--explain` block (not a supported provider)	Resolved — honcho is absent from the current file
`...` placeholder in JSON block	Resolved — expanded to real provider entries
Content-type routing auto-detection not explained	Resolved — "ByteRover automatically classifies the content type" is now explicit
`brv swarm status` buried in section 9	Resolved — promoted to its own section 10
`~/.openclaw/wiki/main` stale path	Not resolved — still present at line 466

Three remaining issues to address before merge:

Severity	Location	Issue
bug	Line 466	`~/.openclaw/wiki/main` — stale product name, leftover from previous review
bug	Lines 372–376	`meta.providers` omits `memory-wiki`, but `results` includes a `memory-wiki` entry — the two are internally inconsistent
nit	Line 350	Basic example says "5 queried", `--explain` example says "4 of 4 available" — no context switch between examples; readers will be confused

github-actions · 2026-04-14T11:10:32Z

Claude finished @cuongdo-byterover's task in 1m 7s —— View job

PR Review: docs:[ENG-2077] add brv swarm query and brv swarm curate to SKILL

Tasks

Gather context and read changed files
Review documentation for correctness, completeness, and quality
Post inline comments for specific issues
Post overall summary

Summary

Score: 4.5 / 5

Good progress from the previous cycles. The major structural and content issues have been resolved — honcho removed, JSON expanded with real entries, content-type auto-detection documented, and brv swarm status promoted to its own section. The file is nearly ready to merge.

Two remaining issues:

Severity	Location	Issue
bug	Line 375	Missing comma after `gbrain` entry in the JSON block — the object is syntactically invalid
nit	Line 350	`--explain` example shows "4 of 4 available" while the basic example shows "5 queried" — provider counts don't align between back-to-back examples

Note on ~/.openclaw/wiki/main (line 467): author confirmed this is intentional — no action needed.

The missing comma at line 375 is the only blocker; the provider count mismatch is cosmetic but worth fixing for reader clarity.

github-actions · 2026-04-14T11:15:15Z

Claude finished @cuongdo-byterover's task in 1m 31s —— View job

PR Review: docs:[ENG-2077] add brv swarm query and brv swarm curate to SKILL

Tasks

Gather context and read changed files
Review documentation for correctness, completeness, and quality
Post inline comments for specific issues
Post overall summary

Summary

Score: 4.8 / 5

Good progress from the previous cycle. The one hard blocker is now resolved:

Previous Issue	Status
Missing comma after `gbrain` entry (invalid JSON)	✅ Resolved
`~/.openclaw/wiki/main` stale path	✅ Intentional — author confirmed, no action needed
`meta.providers` omitting `memory-wiki`	✅ Resolved — `memory-wiki` entry added
Provider count mismatch: "5 queried" vs "4 of 4 available"	⚠️ Still present (nit)

One remaining issue:

Severity	Location	Issue
nit	Line 350	Basic query shows "5 queried"; `--explain` block shows "4 of 4 available" — back-to-back examples with different counts and no context switch will confuse readers. Fix this →

The file is well-structured and consistent with the existing SKILL.md format. The "Use this when / Do NOT use this when" guidance is clear, the JSON examples are now syntactically valid, content-type auto-detection is documented, and brv swarm status has its own section. This is cosmetic-only at this point and can be merged as-is at the author's discretion.

github-actions · 2026-04-14T11:24:40Z

Claude finished @cuongdo-byterover's task in 1m 6s —— View job

PR Review: docs:[ENG-2077] add brv swarm query and brv swarm curate to SKILL

Tasks

Gather context and read changed files
Review documentation for correctness, completeness, and quality
Post inline comments for specific issues
Post overall summary

Summary

Score: 5 / 5

All previously identified issues have been resolved in this cycle.

Previous Issue	Status
Missing comma after `gbrain` entry (invalid JSON)	✅ Resolved
`meta.providers` omitting `memory-wiki`	✅ Resolved
`brv swarm status` buried in section 9	✅ Resolved — promoted to section 10
Content-type auto-detection undocumented	✅ Resolved
`honcho` in `--explain` block	✅ Resolved
Provider count mismatch: "5 queried" vs "4 of 4 available"	✅ Resolved — both now show 4
`~/.openclaw/wiki/main` path	✅ Intentional — author confirmed

The file is well-structured, all examples are internally consistent, JSON is syntactically valid, and the "Use this when / Do NOT use this when" guidance is clear. This is ready to merge.

bao-byterover

LGTM

docs:[ENG-2077] add brv swarm query and brv swarm curate to SKILL

31e0a1a

cuongdo-byterover requested review from bao-byterover and leehpham as code owners April 14, 2026 10:47