feat: [ENG-2697] rewrite ByteRover skill — sub-skill split + Hermes connector#675
Merged
Merged
Conversation
feat: [ENG-2840] Update SKILL.md to force "brv swarm query" to run si…
…nnector Rewrite the ByteRover skill on the Superpowers model: a thin SKILL.md entrypoint with progressive disclosure into focused sub-skill files, plus first-class support for autonomous agents. - Skill: split monolithic SKILL.md into query/curate/review/swarm/vc/ history/troubleshooting.md; SKILL_FILE_NAMES enumerates all managed files and status/uninstall key off the full set - Hermes: add Hermes agent (skill + mcp), connector icon, and YAML MCP config writer; McpConfigFormat now supports 'yaml' (~/.hermes/config.yaml) - Autonomous attachments: write a managed BYTEROVER RULES block into Hermes/OpenClaw system-prompt files via autonomous-agent-attachments and upsert/remove/hasByteroverBlock; idempotent re-install, status reports stale/missing blocks as not-installed - Path resolution: shared agent-path-resolver + skill-path-resolver honor HERMES_HOME / OPENCLAW_STATE_DIR / OPENCLAW_CONFIG_PATH and per-agent globalRoot; OpenClaw skills move to openclaw-state root - Hub: drop hardcoded project scope; daemon infers per-agent default (global for global-only skill agents); writeSkillFiles takes object params with idempotent per-file existence checks - Tests: cover yaml writer, agent-path-resolver, attachment manager, rule-segment-patcher block ops, hub install scope, skill connector Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Claude finished @DatPham-6996's task in 6m 55s —— View job Claude PR Review — SummaryOverall score: 4 / 5 — solid, well-tested feature work with a clean architectural split. A few concrete safety and consistency issues (mostly in connector edges, none blocking for the core skill split). See inline comments for specifics. What this PR does well
Issues (inline)
Nitpicks (inline)
Test coverageTDD ledger looks healthy:
Final checklist
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
|
Claude finished @DatPham-6996's task in 3m 48s —— View job Claude PR Review — re-review after syncOverall score: 4 / 5 — the architectural split and idempotent-block design remain strong; this sync commit was a bulk pull of Since last review (2026-05-18)
Status of prior-review findings against current HEAD
Issues (re-flagged in priority order)
Nitpicks (re-flagged)
Tests & build (unchanged from prior review)
Checklist
|
Add a post-curate self-review sub-skill and substantially strengthen the
curate authoring guide so saved topics are standalone explainers, not
changelogs.
- New src/server/templates/skill/curate-judgement.md: post-write
self-review. After `brv curate` reports done, judge the stored,
rendered topic against curate.md's Quality Bar with a hard cap of one
enhancement pass (references the rubric instead of restating it to
avoid drift).
- Register curate-judgement.md in SKILL_FILE_NAMES
(skill-connector-config.ts) and reference it from SKILL.md (detail
file list + command reference).
- curate.md: document the JSON envelope contract ({html, meta}
replaces bare HTML on --response), add the four-dimension Quality
Bar, decision-flow diagram, rationalizations/red-flags tables, a
richer worked example exercising all dimensions, and a pre-send
self-check; expand Required Preservation and Common Mistakes.
- Add unit coverage asserting curate-judgement.md installs as a lean
self-review guide that points at the Quality Bar, `brv read`, and the
one-pass --overwrite cap.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Claude finished @DatPham-6996's task in 2m 31s —— View job Claude PR Review — synchronize re-reviewOverall score: 4 / 5 — the new Since last review (2026-05-19 03:03 UTC)
Notes on the new
|
| Prior issue | File:line | Status |
|---|---|---|
Hardcoded workdir="~/.hermes/byterover/" ignoring HERMES_HOME |
src/server/templates/skill/curate.md:12, query.md:10 |
Not addressed — still hardcoded in both; double-space typo (at ) still present in both |
YAML config writer silently resets to {} on parse failure |
src/server/infra/connectors/mcp/yaml-mcp-config-writer.ts:88-101 |
Not addressed — still fail-open destructive on invalid YAML |
install() overwrites all SKILL_FILE_NAMES unconditionally |
src/server/infra/connectors/skill/skill-connector.ts:126-132 |
Not addressed — still uses 'overwrite' for every file; writeSkillFiles keeps its safer per-file existence check, but install does not |
BYTEROVER_BLOCK_MARKERS = BRV_RULE_MARKERS identity |
src/server/infra/connectors/shared/constants.ts:22-29 |
Resolved via documentation — docstring now states the invariant (legacy detection compat) |
defaultScopeForAgent uses as Record<...> widening cast |
src/server/infra/transport/handlers/hub-handler.ts:95 |
Not addressed — still violates CLAUDE.md "Avoid as Type assertions" |
agent-path-resolver.ts:resolveUserPath Windows ~\foo gap |
src/server/infra/connectors/shared/agent-path-resolver.ts:29 |
Not addressed — ~/ only; resolveOpenClawUserPath (line 70-77) correctly handles both via /^~[\\/]/u — asymmetric |
mcp-connector-config.ts Hermes configPathResolver ignores injection |
src/server/infra/connectors/mcp/mcp-connector-config.ts:205 |
Not addressed — still () => path.join(resolveHermesHome(), 'config.yaml') with no options |
openclaw.json parsed with yamlLoad |
src/server/infra/connectors/skill/autonomous-agent-attachments.ts:83 |
Not addressed |
SKILL_FILE_NAMES[0] magic indexing in uninstall |
src/server/infra/connectors/skill/skill-connector.ts:255, 274 |
Not addressed — install() uses MAIN_SKILL_FILE_NAME (line 123) but uninstall still uses SKILL_FILE_NAMES[0] |
INVALID_OPENCLAW_ID_CHARS_RE g flag intent |
src/server/infra/connectors/skill/autonomous-agent-attachments.ts:22 |
Not addressed — no clarifying comment |
Re-flagged in priority order (carried forward, unchanged from prior review)
-
yaml-mcp-config-writer.ts:88-101— silent data destruction on invalid YAML.write()still falls through todata = {}on parse failure and overwrites the entire file with just{mcp_servers: {brv: ...}}. Contradicts the connector's own "Non-destructive" header docstring claim. Same destructive path runs for bothbrv hub install --agent Hermesandbrv connectors install. Suggest backup-or-refuse on invalid YAML (IFileService.createBackupis available). Fix this → -
skill-connector.ts:126-132— re-install overwrites user-edited sub-skill files unconditionally. Intended ("re-install refreshes"), but it silently clobbersquery.md/curate.md/curate-judgement.md/ etc. and still returnssuccess: true, alreadyInstalled: truewith no signal. Withcurate-judgement.mdnow in the managed set, this risk surface is wider — a user who tweaks their judgement guide loses it on nextbrv hub install.writeSkillFiles(lines 333-348) already shows the right pattern. Match it ininstall(), gate the refresh behind--force, or add a "Do not edit — regenerated bybrv hub install" header to generated files. Fix this → -
src/server/templates/skill/curate.md:12&query.md:10—workdirhardcoded, doesn't honorHERMES_HOME. Skill install root + Hermes MCP config path both honorHERMES_HOME, but the skill content tells the agent tocd ~/.hermes/byterover/. For a Hermes user withHERMES_HOME=/opt/hermes, the skill is installed at/opt/hermes/skills/byterover/SKILL.mdbut the agent reads "runbrvat~/.hermes/byterover/" — pointing at the non-relocated home. Also still:at(double space) in both files. Either parameterize at install time or reword as(default: ~/.hermes/byterover/, overridable via $HERMES_HOME). Fix this → -
hub-handler.ts:93-98—as Typewidening cast still violates CLAUDE.md. Replace theRecord<string, {projectPath: null | string}>cast with anagent in SKILL_CONNECTOR_CONFIGStype guard. Fix this →
Nitpicks (carried forward)
agent-path-resolver.ts:29— Windows backslash gap.resolveUserPath(used for Hermes) handles~/but not~\;resolveOpenClawUserPath(line 70) handles both. Trivial fix:value.startsWith('~/') || value.startsWith('~\\').skill-connector.ts:255 & 274—uninstallstill usesSKILL_FILE_NAMES[0];MAIN_SKILL_FILE_NAMEis imported but only used at line 123. Easy follow-up to the partial fix already applied.mcp-connector-config.ts:205— HermesconfigPathResolverdoesn't accept options, sogetConfigPath('Hermes')is not injectable in tests (forcesprocess.envmutation inmcp-connector.test.ts:484). Asymmetric with the Skill connector'spathResolverOptions()plumbing.autonomous-agent-attachments.ts:22—gflag onINVALID_OPENCLAW_ID_CHARS_REis load-bearing forreplaceAll; a one-line comment would prevent a future "tidy" regression.autonomous-agent-attachments.ts:83-84— parsingopenclaw.jsonwithyamlLoad: works (YAML ⊃ JSON) but obscures intent.
Tests & build
- New unit coverage in
eafd498for thecurate-judgement.mdinstall path looks healthy (asserts the file installs as a lean self-review guide that points at the Quality Bar,brv read, and the one-pass--overwritecap). - Existing unit suites unchanged and still healthy.
- Gap (same as prior review): no new test covers (a) the YAML-parse-failure path in
yaml-mcp-config-writer.write(), or (b) the re-install-clobbers-edited-sub-skill path inskill-connector.install(). Adding those would have surfaced issues Feat/init #1 and Feat/refactor structure #2 as red tests.
Todos
- Fetch latest branch and diff against
origin/proj/byterover-tool-mode - Re-verify status of prior-review findings against current HEAD
- Read key changed files (yaml-mcp-config-writer, skill-connector, hub-handler, agent-path-resolver, templates, curate-judgement)
- Check whether any new commits since last review address open issues — they don't
- Post final summary with overall score
Contributor
|
Claude finished @DatPham-6996's task in 3m 36s —— View job Claude PR Review — synchronize re-review (4th pass)Overall score: 4 / 5 — the architectural split, idempotent block management, and OpenClaw-faithful path resolution remain strong. This sync pulled Since last review (2026-05-19 10:26 UTC)
No targeted fixes landed for the four open priority issues from the prior reviews. Status of prior-review findings against current HEAD
Re-flagged inline (priority order)
Nitpicks ( Tests & build
Notes on the new
|
Audited each sub-skill (excluding curate / query) against the actual `brv <topic> --help` surface and patched the gaps: - vc.md: added init, clone, config, checkout, merge, fetch, remote; added real examples for reset (was only mentioned as "avoid"). Regrouped Quick Reference by workflow phase (Setup / Inspect / Stage+commit / Branch+checkout / Sync / Merge / Undo). Expanded Safety + Common Mistakes to cover missing-upstream, missing-config, and switching with dirty tree. - swarm.md: added `brv swarm onboard` (interactive setup wizard) + a Setup section explaining when to use it. - review.md: added the toggle subcommands (`brv review`, `--enable`, `--disable`) that the description verb already implied but the body missed entirely. Updated frontmatter to include enable/disable so the matcher fires on those prompts. - history.md: surfaced the filter flags that were buried under `--help` — `--limit`, `--since`, `--before`, `--status`, `--tier`, `--last`, `--format narrative`. Regrouped Quick Reference into Curate / Query / Aggregate sections. - troubleshooting.md: added recovery commands (`brv restart` for crash recovery, `brv logout` + `brv login` reset flow, `brv update` for stale-CLI mismatch) + `brv connectors` to Quick Diagnosis.
Contributor
|
Claude finished @cuongdo-byterover's task in 2m 17s —— View job Claude PR Review — synchronize re-review (5th pass)Overall score: 4 / 5 — the architectural split, idempotent block management, and OpenClaw-faithful path resolution remain strong. The new commit since the prior review ( Since last review (2026-05-20 09:32 UTC)
Status of prior-review priority findings against current HEAD
The inline comments from the 4th-pass review (posted 2026-05-20 09:34 UTC) at Notes on
|
cuongdo-byterover
changed the title
cuongdo-byterover
changed the title
Contributor
|
Claude finished @DatPham-6996's task in 2m 10s —— View job Claude PR Review — synchronize re-review (6th pass)Overall score: 4 / 5 — architecture and idempotent-block design remain solid. The only new commit since the 5th-pass review ( To avoid further noise I am not re-posting those inline comments — please refer to the existing inline threads (most recently re-filed 2026-05-20 09:34 UTC) for fix suggestions / Since last review (2026-05-20 10:25 UTC)
Status of prior-review priority findings against current HEADRe-verified each against current files; nothing has shifted since the 5th-pass review except for the
Tests & build
RecommendationApprove once at least these two top-priority items land — they're the only ones that can lose user content silently:
Items 3 ( Checklist
|
Add a guided 90-second onboarding skill that runs when a user asks
"Show me how ByteRover works" (or any semantic equivalent). The tour
captures the user's persona and the pain that brought them to
ByteRover, persists both locally, and demonstrates how ByteRover
ends the re-explain tax — all without an account, API key, or
provider config.
src/server/templates/skill/onboarding.md (new):
- Msg 1: trust opener (no command names) → one-sentence concept
primer → quick interview (identity + pain in one open question) →
human-reaction beat before curate → visible artifact with pain
bullet + sticky label ("re-explain tax") + behavioral commitment
→ 2-beat concept map with visual separation before pause
- Msg 2: named action ("brv query"), one-line retrieval summary,
conditional bonus-context branch when existing project knowledge
is found, identity-and-pain reflection, future-self demonstration
of the pain ending, loop name + cross-session promise
- Msg 3: where memory lives (one sentence, no commands) →
activation step that detects CLAUDE.md/AGENTS.md/etc. and offers
to curate as starter project context (or prompts for one rule)
→ done signal with two equal-weight paths (curate more vs.
resume work) so users exit without homework
- Spec guards: don't manufacture pains, don't overpromise on
out-of-scope pains, don't turn the artifact into a confirmation,
don't tailor with hollow phrases, don't auto-fire next message
src/server/templates/skill/SKILL.md:
- Add First-Turn Routing block before the Iron Law that hands off
to onboarding.md on tour/intro/walkthrough requests
- Update frontmatter description so the skill router activates the
skill on tour-related phrasings
src/server/infra/connectors/skill/skill-connector-config.ts:
- Add onboarding.md to SKILL_FILE_NAMES so the connector copies it
during install
feat: [ENG-2536] add ByteRover onboarding tour skill
Msg 1 closes with a teaser line ("Also version-controlled, cloud-syncable,
and shareable across agents — more at the end") so users know more controls
exist without diluting the local-only trust climax. Msg 3 Part 1 delivers
on it with three short bullets covering brv vc, brv vc push/pull, and
connector cross-agent sharing.
Without this, the tour leaves users thinking ByteRover is local-only with
no team or sync story — they discover the full surface area accidentally
or not at all.
- Expand kind action notes (link/merge/prune/synthesize) with thresholds, candidate shapes, and accurate `related=` ref convention from curate.md. - Add sample scan + finalize JSON envelopes with all candidate fields. - Describe `path-exists` as a writer response on curate continuation (kickoff returns generate-html only; validation runs on the submitted HTML). - Reframe undo: bit-exact restore of content + original mtime + sidecar signals; `brv dream undo` takes no arguments. - Note that `dream sessions` / `dream cancel` JSON envelopes carry a `note` field disclosing v1 statelessness.
DatPham-6996
requested review from
RyanNg1403,
cuongdo-byterover,
danhdoan and
ngduyanhece
as code owners
DatPham-6996
force-pushed
the
feat/ENG-2697
branch
from
340a28b to
6733e84
Compare
Contributor
|
Claude finished @DatPham-6996's task in 3m 50s —— View job Claude PR Review — synchronize re-review (7th pass)Overall score: 3 / 5 — architecture and idempotent-block design remain solid, and the new Since last review (2026-05-21 02:46 UTC)
New issue introduced by this sync
This looks accidental — Status of prior-review priority findings against current HEADVerified each against current files; none of the four open priority items have moved since the 6th-pass review. To avoid noise, not re-posting the inline comments for these — please see the existing inline threads (most recently re-filed 2026-05-20 09:34 UTC) for
Notes on the new
|
- Add dream.md to managed ByteRover skill files - Add regression coverage for skill template enumeration - Fail YAML MCP writes when existing config is malformed or non-mapping - Preserve existing YAML bytes instead of overwriting with a fresh config
Contributor
|
Claude finished @DatPham-6996's task in 1m 45s —— View job Claude PR Review — synchronize re-review (8th pass)Overall score: 4 / 5 — meaningful forward progress this sync: the new commit ( Since last review (2026-05-27 04:53 UTC)
Both fixes are minimal, surgical, and arrive with the corresponding red-test → green-test transition. Nice TDD discipline on the follow-through. Status of remaining prior-review priority findings against current HEAD
To avoid noise I'm not re-posting the inline comments for the still-unaddressed items — see the existing inline threads (most recently re-filed 2026-05-20 09:34 UTC) for RecommendationThe two most safety-critical items (data loss on hand-edited YAML; dead-linked
#1 is the only one of the three that can affect user content; #2 and #3 are code-quality / consistency items that could land in a follow-up PR if you'd rather keep this diff focused. Tests & build
Checklist
|
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SKILL.mdwith noprogressive disclosure, and autonomous agents (OpenClaw, and now Hermes)
had no reliable way to always load the ByteRover memory contract into their
system prompt. Hub install also hardcoded
scope: 'project', which threw"does not support project scope" for global-only skill agents.
focused sub-skills, predictable folder structure) makes the skill easier
for agents to navigate and keeps the always-on memory rule in front of
autonomous agents without bloating every invocation.
SKILL.mdinto a thin entrypoint plus focused sub-skills(
query/curate/review/swarm/vc/history/troubleshooting.md);SKILL_FILE_NAMESenumerates the full managed set and status/uninstallkey off it.
Hermesagent (skill + mcp), connector icon, and a YAML MCPconfig writer;
McpConfigFormatnow supports'yaml'(
~/.hermes/config.yaml).BYTEROVER RULESblock injection into Hermes/OpenClawsystem-prompt files via
autonomous-agent-attachments.ts+upsert/remove/hasByteroverBlock(idempotent re-install; stale/missingblock reported as not-installed).
agent-path-resolver/skill-path-resolverhonoringHERMES_HOME/OPENCLAW_STATE_DIR/OPENCLAW_CONFIG_PATHandper-agent
globalRoot; OpenClaw skills moved to the openclaw-state root.per-agent default (global for global-only skill agents);
writeSkillFilestakes object params with idempotent per-file existence checks.
context-tree storage, billing, or the transport schema beyond the existing
hub-install scope being optional. Existing home/project-rooted agents
(Claude, Cursor, etc.) keep their current paths and behavior.
Type of change
Scope (select all touched areas)
Linked issues
Root cause (bug fixes only, otherwise write
N/A)Test plan
test/unit/infra/connectors/mcp/yaml-mcp-config-writer.test.tstest/unit/infra/connectors/shared/agent-path-resolver.test.tstest/unit/infra/connectors/connector-manager-attachment.test.tstest/unit/infra/connectors/shared/rule-segment-patcher.test.tstest/unit/infra/connectors/skill/skill-connector.test.tstest/unit/infra/connectors/mcp/mcp-connector.test.tstest/commands/hub-install-scope.test.tstest/unit/infra/hub/hub-handler.test.tstest/unit/infra/hub/hub-install-service.test.tsresolution for Hermes/OpenClaw; autonomous-block upsert/remove/has
(idempotency + stale-block detection); per-agent default scope inference
in hub install; skill connector install/status/uninstall with attachment
block; object-param
writeSkillFilesidempotent file checks.User-visible changes
Hermesagent selectable in hub install and the WebUI connectors panel(with icon).
brv hub installno longer defaults--scopetoproject; the daemoninfers the default per agent (global-only agents like Hermes/OpenClaw
install globally without erroring).
a managed
BYTEROVER RULESblock in their system-prompt files.SKILL.md; re-install refreshes (no longer short-circuits as "alreadyinstalled").
Evidence
Attach at least one:
Checklist
npm test)npm run lint)npm run typecheck)npm run build)mainRisks and mitigations
files could clobber user content.
<!-- BEGIN/END BYTEROVER RULES -->markers; upsert replaces only the bounded block and preserves surrounding
content; removal rejoins cleanly. Covered by rule-segment-patcher tests.
callers that previously relied on the
projectdefault.--scope/data.scopestill wins; default onlyflips to
globalfor agents with no project skill path. Covered byhub-install-scopeandhub-handlertests.HERMES_HOME,OPENCLAW_STATE_DIR,OPENCLAW_CONFIG_PATH) could resolve unexpected locations.unit-tested with injected env/home.