spike(framework): define the Freebuff support contract

未关闭
#941 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
42/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
活跃
技术栈
typescript

调研方向

Start with cli/src/kernel/tool.ts and the five reference tables: detection.md, tools.md, tool-detect.md, sync-arguments.md, plus plugins/aidd-context/hooks/update_memory.js. Then inspect the existing OpenCode and Kilo profiles and bridges, and verify whether Freebuff has a usable session-start hook surface. Done means Freebuff detection, AGENTS.md wiring, profile delivery, and maintenance behavior are consistently represented and validated.

由索引模型根据 Issue 内容生成。

描述

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:

synced for exit block lists the new file
opencode 0 yes
freebuff 1 no
kilo 1 no

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 #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 #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
主要语言
TypeScript
星标
481
派生
45
平均合并
1 天 13 小时
30 天内合并 PR
91

环境准备

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

ai-driven-dev/framework 的其他 Issue

查看 ai-driven-dev/framework 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。