spike(framework): define the Freebuff support contract #941

Problem to solve

aidd-context has no representation for Freebuff. It is absent from all five places that enumerate
AI tools, including TOOL_FILES in
update_memory.js. A project that is worked on with
Freebuff therefore cannot keep its AIDD memory current.

On a real project that runs AIDD, with the copy of the hook installed in that project (byte-identical
to upstream/next):

$ node .opencode/hooks/aidd-context/update_memory.js opencode
                                                              # exit 0, memory block updated

$ node .opencode/hooks/aidd-context/update_memory.js freebuff
update_memory: unknown tool freebuff (known: claude, codex, cursor, opencode, copilot)
                                                              # exit 1, refused

$ node .opencode/hooks/aidd-context/update_memory.js kilo
update_memory: unknown tool kilo (known: claude, codex, cursor, opencode, copilot)
                                                              # exit 1, refused

The effect is not cosmetic. Writing a new memory file and syncing:

The guard is doing its job — the tool is simply not in the list.

This is not a Freebuff-shaped gap. Kilo is in the same position today: AiToolId in
cli/src/kernel/tool.ts carries six values including kilo, and 12 files under cli/src/ know
the tool, yet kilo appears zero times in plugins/ and update_memory.js kilo exits 1. Two
tools, one cause: the wiring table and the plugin reference tables are maintained separately from
the tool registry, and nothing checks that they agree.

Proposed solution

Add Freebuff as a detected tool wired to AGENTS.md, alongside codex, cursor and opencode.

• Detection signal: .freebuff/, a project-scoped directory holding project-id. It is created
  when a project is opened in Freebuff, so it is behavioural rather than inferred — I watched it
  appear when I started a session. The vendor writes it from setProjectRoot in
  cli/src/project-files.ts with everyRepository: IS_FREEBUFF, so it is written in every Git
  project, not only in ones without a hosted remote; I confirmed it present in a repo that does
  have a GitHub remote.
• Wiring target: AGENTS.md. Freebuff reads project AGENTS.md and CLAUDE.md. The vendor
  quick-start says "New projects — if you don't already have an AGENTS.md or CLAUDE.md (Codebuff
  will also read these files)" — and that page is the right evidence here, because Freebuff is the
  same CLI built with FREEBUFF_MODE=true, while the knowledge-file resolution lives in
  common/src/constants/knowledge.ts and sdk/src/run-state.ts, neither of which is gated on that
  flag. Picking AGENTS.md also matches how feat(aidd-context): add Kilo-native generation targets #914 settled the same question for Kilo.
• No new surface: AGENTS.md is already the target for three tools, so the existing "tools
  sharing a context file wire it once" rule in tools.md covers this.

Wiring is four table edits (detection.md, tools.md, tool-detect.md, sync-arguments.md) plus
the TOOL_FILES entry. That is necessary and not sufficient — see below.

Content type

• Other

Target tool(s)

• Other — Freebuff, which the dropdowns do not list.

Additional context

• The five tables are the ones that disagree with each other, and the sync-arguments.md default
  is where a fourth writer shows up. Its rule reads "Otherwise derive args from synced context
  files; AGENTS.md defaults to codex". A third tool already targets AGENTS.md, so that
  default is already arbitrary; a fourth makes it arbitrary in a way a reader will hit. Worth
  settling as part of this, not after.

• Wiring is half of it, and the half I cannot deliver is the half that matters. TOOL_FILES is
  the wiring table; it does not maintain anything. Maintenance runs per tool through the CLI
  profiles, and all six existing profiles declare acceptsHooks: true — so a tool is not
  automatically maintained, and a new one needs its profile wired deliberately:

  tool	hook delivery	mechanism
  claude	yes	native plugin, pluginRootToken = CLAUDE_PLUGIN_ROOT
  copilot	yes	native plugin, .github/plugins/
  codex	yes	writes a hook entry to .codex/config.toml
  cursor	yes	hooksContentFormat: "flat", routed to .cursor/hooks.json
  opencode	yes	generated bridge (opencode-hooks-bridge.ts)
  kilo	yes	generated bridge (kilo-hooks-bridge.ts)
  freebuff	no profile	—

  The distinction that matters is mode: "flat" versus native. Claude, Copilot and Cursor take
  hooks.json more or less as-is. OpenCode and Kilo cannot express it natively, so the CLI
  generates a bridge module that parses hooks.json and replays the SessionStart commands.
  Freebuff would need a profile and one of those two shapes decided for it — which is a question
  for whoever validates this, not a guess I should make in a PR. I could not find a session-start
  hook surface in the vendor's published source: there is no hooks.json concept, and
  SessionStart appears nowhere. The one hook concept that does exist is run_file_change_hooks,
  and its SDK path is an explicit no-op ("File change hooks are not supported in the SDK
  environment") — so I cannot claim a bridge is generatable.

• I checked the vendor's source rather than assuming, and its docs disagree with its own code.
  Freebuff resolves one knowledge file per directory, first match wins
  (selectHighestPriorityKnowledgeFile in sdk/src/run-state.ts, walking
  KNOWLEDGE_FILE_NAMES_LOWERCASE over that directory's candidates). That list is
  ['AGENTS.md', 'CLAUDE.md'] (common/src/constants/knowledge.ts); knowledge.md is no longer a
  knowledge file, and isKnowledgeFile additionally accepts *.knowledge.md. Two comments in
  run-state.ts still describe the old knowledge.md-first ordering while the code below them no
  longer implements it, and the vendor's published docs/tips/knowledge-files still tells users
  ~/.knowledge.md is "highest priority" — a file loadUserKnowledgeFiles no longer matches at
  all. So the code is right and the docs are stale here. AGENTS.md is therefore the correct
  target, and a project that also carries a knowledge.md is not a special case. I am reporting
  this only as the reason my choice is grounded; the doc fix is theirs to make.

• I have not checked Discussions, only issues. Searched for freebuff and codebuff across
  open and closed issues: no hit, so I do not believe this is tracked yet.

• Sequencing with feat(aidd-context): add Kilo-native generation targets #914 is a judgement call for the maintainers, not mine.

• I am not asking for a PR to be opened pre-emptively. Per CONTRIBUTING.md an issue is validated
  first — a Certified Member or Maintainer moves it to Todo — and after that anyone may pick it up,
  including me.

Code of Conduct

• I agree to follow this project's Code of Conduct.