spike(framework): define the Freebuff support contract

Abierto
#941 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
42/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
typescript

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
TypeScript
Estrellas
481
Forks
45
Merge medio
1 d 13 h
PR fusionados (30 d)
91

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de ai-driven-dev/framework

Todos los issues de ai-driven-dev/framework

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.