boost init --opencode writes BOOST.md to a path opencode never reads

[guysoft]

Bug: boost init --opencode writes BOOST.md to a path opencode never reads

Summary

After running boost init --opencode, the file ~/.config/opencode/BOOST.md
exists on disk, but opencode agents have zero awareness of boost in a
fresh session. When asked to use boost (e.g. "use boost to give me a report
on my CI speed"), the agent replies that it has no tool called boost and
refuses to even probe which boost.

Environment

• opencode (current version, fresh session)
• boost installed via boost init --opencode
• macOS 15, zsh
• ~/.config/opencode/BOOST.md exists, populated with the standard content
  (# boost-skill-version: 5 / # boost-agent: opencode header plus the
  ## /boost - local analytics skill body)
• ~/.config/opencode/plugins/boost.ts exists and is registered in
  ~/.config/opencode/opencode.json
• boost --help works correctly from the shell that opencode was
  started from (so boost is on PATH and the binary works)

Steps to reproduce

1. boost init --opencode
2. Confirm ~/.config/opencode/BOOST.md exists.
3. Start a fresh opencode session.
4. Ask the agent: "use boost to give me a report on my CI speed".

Expected

The agent recognizes boost as an available CLI, follows the instructions
in BOOST.md (which point at boost skill --help), and proceeds with
the analytics workflow.

Actual

The agent responds along these lines:

"No, I don't have a boost tool or CLI available in my environment.
None of these is called boost, and nothing in the system prompt /
CLAUDE.md / available skills mentions a boost verb set."

Restarting opencode does not help. The agent does not auto-probe
(which boost, command -v boost, reading its bash scrollback) — it
treats boost as a missing entry in its tool manifest and stops.

The bundled plugin at ~/.config/opencode/plugins/boost.ts does
transparently rewrite commands the agent already chose to run
(e.g. pytest → boost pytest), and that part works. But this silent
rewrite does not surface boost as a discoverable CLI, so the agent
never invokes any boost-native verb (boost report, boost query,
boost skill, etc.) on its own.

Why the file sits unread

opencode's discoverable-instructions surfaces (the places it scans for
agent-visible context at session start) are:

• ~/.config/opencode/AGENTS.md — always-on global instructions
• ~/.config/opencode/skills/<name>/SKILL.md — discoverable skills the
  model picks up at session start based on YAML frontmatter triggers

boost init --opencode writes BOOST.md at the opencode config root,
which is neither of those. Nothing references it from a location
opencode actually loads, so it never reaches agent context.

The plugin handles transparent command rewriting independently, which
may have masked the fact that the user-facing /boost analytics skill
was never reachable from opencode agents.

Impact

• The /boost analytics skill is effectively unreachable on opencode.
• Any boost native subcommand that an agent has to invoke deliberately
  (i.e. not a command the silent-rewrite plugin transforms) is
  undiscoverable.
• Users have to know to run boost skill --help themselves and paste
  the output into the agent's context manually.

Workaround (verified working on my machine)

Convert ~/.config/opencode/BOOST.md into a valid opencode skill by
prepending YAML frontmatter:

---
name: boost
description: <one-line description with trigger keywords like
  "boost, /boost, CI speed, agent speed, flaky tests, build performance,
  use boost, boost report, background command, parallel build,
  long-running command">
---

Then symlink it into the skills directory so opencode finds it:

mkdir -p ~/.config/opencode/skills/boost
ln -s ../../BOOST.md ~/.config/opencode/skills/boost/SKILL.md

After an opencode restart, the agent finds boost in its skill index
and responds correctly to "use boost to give me a report on my CI
speed".

Suggested fix for the install flow

Two changes to boost init --opencode:

1. Write BOOST.md with proper opencode-skill YAML frontmatter
   (--- … name / description … ---) so it qualifies as a skill
   file.
2. Either symlink it into ~/.config/opencode/skills/boost/SKILL.md
   or write the skill body there directly.

Optional polish:

3. Make the BOOST.md write idempotent / merge-friendly — today it
   unconditionally truncates and rewrites, so a user who customises
   their local copy loses the edits on the next boost init /
   boost update cycle.

Related: /boost slash command

opencode does not have a per-config commands/ slash-command directory
the way some other agents do, so if a user is instructed to try
/boost to invoke the analytics skill, that command simply does not
fire on opencode. The fix above addresses this too: a properly-
registered skill with /boost in its trigger description means typing
/boost in opencode loads the skill body and works.

Happy to send a PR if you point me at the preferred approach.