kb/openspec/changes/archive/2026-03-31-structured-add-commands/proposal.md at main

steve/kb

Files

T

steve afbe270181 Replace implicit note shorthand with explicit addnote command and split README

Two changes:

1. structured-add-commands: The implicit note shorthand (kb "text") caused
   accidental note creation from mistyped commands. Replaced with explicit
   kb addnote <text> command. Root command reverts to standard Cobra
   behaviour. Updated examples, tests, SKILL.md, and specs.

2. split-readme-developer-docs: Moved build-from-source instructions, release
   process, API reference, and ROCm migration notes from README.md into a
   new DEVELOPER.md. README now links to DEVELOPER.md for dev workflows.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-31 20:48:22 +01:00

2.4 KiB

Raw Permalink Blame History

Why

The implicit note shorthand (kb "some text") makes it too easy to accidentally add notes when mistyping commands. Despite the single-word guard, any multi-word typo (e.g. kb lisst --type pdf) silently creates a note. The root command doing double-duty as both command dispatcher and note ingester undermines user trust. Reverting to explicit, structured add commands eliminates accidental ingestion and gives every content type a clear, discoverable verb.

What Changes

New addnote command: kb addnote <text> takes a single quoted positional argument and submits it as a note. Supports --tags. The submitNote() logic moves from root.go to a new addnote.go command file.
Remove implicit note shorthand: The root command reverts to standard Cobra behaviour — no ArbitraryArgs, no special arg-count logic, no --tags flag on root. Unknown input gets Cobra's default "unknown command" error.
Remove custom usage template: The root command no longer needs the isRootCmd template logic. Standard Cobra usage template for all commands.
Update examples: examples.go updated to show kb addnote instead of bare kb "text".
Update tests: Remove implicit note shorthand tests, add addnote command tests.
addfile unchanged: Stays exactly as-is.
BREAKING: kb "note text" no longer works. Users must use kb addnote "note text".

Capabilities

New Capabilities

(none)

Modified Capabilities

go-client: The "Implicit note shorthand" requirement is removed entirely and replaced by a new "Add note command" requirement. The "Add command (file and note ingestion)" requirement description is updated to reflect addnote / addfile as the two ingestion commands. The root command reverts to standard Cobra behaviour with no custom arg handling or usage template.

Impact

client/cmd/root.go — remove ArbitraryArgs, RunE note logic, --tags flag, custom usage template, isRootCmd template func
client/cmd/add.go — submitNote() function moves to new addnote.go (or stays in add.go alongside addfile — design decision)
client/cmd/addnote.go — new file defining the addnote command
client/cmd/examples.go — update example text
client/cmd/root_test.go — remove implicit note shorthand tests, add standard Cobra behaviour tests
No engine changes — the API contract (POST /api/v1/jobs with note field) is unchanged

2.4 KiB Raw Permalink Blame History

Why