steve/kb
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 18 Wiki Activity

Replace implicit note shorthand with explicit addnote command and split README

Browse Source 
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>
This commit is contained in:
Steve Cliff
2026-03-31 20:48:22 +01:00
parent 9e957f1a9a
commit afbe270181
20 changed files with 688 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/specs/developer-docs/spec.md
+61
View File
@@ -0,0 +1,61 @@
### Requirement: DEVELOPER.md exists at repo root
The repository SHALL have a `DEVELOPER.md` file at the project root containing all developer-facing documentation.
#### Scenario: File exists
- **WHEN** a developer navigates to the repository root
- **THEN** a `DEVELOPER.md` file SHALL be present
### Requirement: DEVELOPER.md contains build-from-source instructions
DEVELOPER.md SHALL contain instructions for building both the engine and client from source.
#### Scenario: Engine build from source
- **WHEN** a developer reads DEVELOPER.md
- **THEN** it SHALL include instructions for starting the engine from source using compose files (both NVIDIA and ROCm)
#### Scenario: Client build from source
- **WHEN** a developer reads DEVELOPER.md
- **THEN** it SHALL include instructions for building the client binary from source using `make build` and `make all`
### Requirement: DEVELOPER.md contains release process
DEVELOPER.md SHALL document the release process for both client and engine, including release scripts, version bumping, and Docker image tagging.
#### Scenario: Client release documentation
- **WHEN** a developer reads DEVELOPER.md
- **THEN** it SHALL include `release-client.sh` usage with flag options (--gitea, --github, --minor, --no-increment, --dry-run)
#### Scenario: Engine release documentation
- **WHEN** a developer reads DEVELOPER.md
- **THEN** it SHALL include `release-engine.sh` usage with flag options and Docker image tag conventions
#### Scenario: Version checking
- **WHEN** a developer reads DEVELOPER.md
- **THEN** it SHALL include how to check client and engine versions
### Requirement: DEVELOPER.md contains developer notes
DEVELOPER.md SHALL include any forward-looking developer notes such as migration plans or technical debt items.
#### Scenario: ROCm migration note
- **WHEN** a developer reads DEVELOPER.md
- **THEN** it SHALL include the ROCm runtime migration note about onnxruntime and MIGraphX
### Requirement: README.md excludes developer-only content
README.md SHALL NOT contain build-from-source instructions, release processes, or developer-only notes.
#### Scenario: No from-source build steps in README
- **WHEN** a user reads README.md
- **THEN** there SHALL be no "From source" subsections under engine or client installation
#### Scenario: No release section in README
- **WHEN** a user reads README.md
- **THEN** there SHALL be no "Building and releasing" section
#### Scenario: No developer notes in README
- **WHEN** a user reads README.md
- **THEN** there SHALL be no "Future: ROCm runtime migration" section
### Requirement: README.md cross-references DEVELOPER.md
README.md SHALL include a link to DEVELOPER.md for users who want to build from source or contribute.
#### Scenario: Developer link in quick start
- **WHEN** a user reads the Quick Start section of README.md
- **THEN** there SHALL be a note pointing to DEVELOPER.md for building from source
openspec/specs/go-client/spec.md
+18 -26
View File
@@ -68,47 +68,39 @@ The client SHALL provide a `kb search <query>` command that sends the query to t
---
### Requirement: Implicit note shorthand
### Requirement: Add note command
The client SHALL treat bare string arguments (with no subcommand) as an implicit note only when **more than one argument** is provided. `kb "my note"` SHALL behave identically to submitting a note via `POST /api/v1/jobs`. All persistent flags (`--format`, `--engine`, `--api-key`) and the root `--tags` flag SHALL work with the shorthand form. A single bare word SHALL be rejected with an error message.
The client SHALL provide a `kb addnote <text>` command that submits a text note to the engine for ingestion. The command SHALL take exactly one positional argument (the note text) and support a `--tags` flag for comma-separated tags. The note SHALL be submitted via `POST /api/v1/jobs` with the `note` field in a multipart request.
#### Scenario: Quick note via bare argument
- **WHEN** the user runs `kb "remember to update DNS"`
#### Scenario: Add a note
- **WHEN** the user runs `kb addnote "remember to update DNS records"`
- **THEN** the client SHALL submit the text as a note via `POST /api/v1/jobs` and print `Queued: note`
#### Scenario: Bare argument with tags
- **WHEN** the user runs `kb "server room is building 3" --tags ops`
#### Scenario: Add a note with tags
- **WHEN** the user runs `kb addnote "server room is building 3" --tags ops`
- **THEN** the client SHALL submit the note with the specified tags
#### Scenario: Bare argument with JSON output
- **WHEN** the user runs `kb "my note" --format json`
#### Scenario: Add a note with JSON output
- **WHEN** the user runs `kb addnote "my note" --format json`
- **THEN** the client SHALL output the raw JSON response from the engine
#### Scenario: Bare argument duplicate detection
- **WHEN** the user runs `kb "my note"` and the engine returns HTTP 409
- **THEN** the client SHALL handle the duplicate response identically to the previous `kb add --note` behaviour
#### Scenario: Duplicate note detection
- **WHEN** the user runs `kb addnote "my note"` and the engine returns HTTP 409
- **THEN** the client SHALL display the duplicate information (document ID or job ID) and exit with code 0
#### Scenario: Multiple unquoted words
- **WHEN** the user runs `kb remember to update dns` (without quotes)
- **THEN** the client SHALL join all arguments into a single note string and submit it
#### Scenario: Missing argument
- **WHEN** the user runs `kb addnote` with no arguments
- **THEN** the client SHALL display an error indicating that the note text argument is required
#### Scenario: Single bare word rejected
- **WHEN** the user runs `kb infow` (a single unrecognized word)
- **THEN** the client SHALL print to stderr: `Unknown command "infow". Run 'kb --help' for available commands.` followed by a hint about note usage, and exit with a non-zero code
#### Scenario: No interference with subcommands
- **WHEN** the user runs `kb search "query"` or any other existing subcommand
- **THEN** the client SHALL route to the subcommand as before — the implicit note shorthand SHALL NOT interfere
#### Scenario: No arguments
- **WHEN** the user runs `kb` with no arguments
- **THEN** the client SHALL display the help text
#### Scenario: Too many arguments
- **WHEN** the user runs `kb addnote remember to update dns` (unquoted, multiple args)
- **THEN** the client SHALL display an error indicating that exactly one argument is required, with a hint to quote the text
---
### Requirement: Add command (file and note ingestion)
The client SHALL provide a `kb addfile` command that uploads files to the engine for async ingestion. The command SHALL validate file extensions before uploading and reject unsupported types. The client SHALL handle duplicate rejection (HTTP 409) and display the existing document information. The command SHALL NOT handle notes — notes are submitted via the implicit note shorthand (`kb "text"`).
The client SHALL provide a `kb addfile` command that uploads files to the engine for async ingestion. The command SHALL validate file extensions before uploading and reject unsupported types. The client SHALL handle duplicate rejection (HTTP 409) and display the existing document information. Notes are handled by the separate `addnote` command — `addfile` is exclusively for file uploads.
#### Scenario: Add a single file
- **WHEN** the user runs `kb addfile report.pdf`