kb/openspec/changes/archive/2026-03-31-split-readme-developer-docs/specs/developer-docs/spec.md at d078af9ad39e4664e46ff38d48cebf207e79a5dd

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.9 KiB

Raw Blame History

ADDED Requirements

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

2.9 KiB Raw Blame History