kb/openspec/changes/kb-search/specs/skill-interface/spec.md

ADDED Requirements

Requirement: JSON output format for search

The system SHALL output search results as JSON when --format json is used (this is the default). The JSON schema SHALL include: query, results array, total_matches, and returned count. Each result SHALL include: chunk_id, score, score_breakdown (with fts and vector sub-scores), text, and source object.

Scenario: JSON search output

• WHEN user runs kb search "install git" --format json
• THEN the output is valid JSON matching this structure:

  {
    "query": "install git",
    "results": [
      {
        "chunk_id": 1423,
        "score": 0.031,
        "score_breakdown": {"fts": 0.016, "vector": 0.015},
        "text": "To install the latest version...",
        "source": {
          "document_id": 42,
          "title": "Git Admin Guide",
          "path": "/home/user/docs/git-admin.pdf",
          "type": "pdf",
          "page": 12,
          "chunk_index": 3,
          "total_chunks": 28,
          "tags": ["git", "admin"]
        }
      }
    ],
    "total_matches": 47,
    "returned": 10
  }
  

Scenario: Score breakdown in FTS-only mode

• WHEN user runs kb search "test" --fts-only --format json
• THEN score_breakdown contains {"fts": <score>, "vector": null}

Scenario: Score breakdown in vector-only mode

• WHEN user runs kb search "test" --vec-only --format json
• THEN score_breakdown contains {"fts": null, "vector": <score>}

Requirement: Human-readable output format

The system SHALL support human-readable output via --format human. This format SHALL show: query, match count, and for each result: rank, score, title, page/section (if applicable), type, tags, and a text preview.

Scenario: Human-readable search output

• WHEN user runs kb search "install git" --format human
• THEN output is formatted for terminal reading:

  Search: "install git" (47 matches, showing top 10)
  
   1. [0.031] Git Admin Guide (p.12)               [pdf] [git, admin]
      To install the latest version of git from source...
  
   2. [0.025] setup-notes.md §Installation          [markdown] [git]
      First, add the PPA repository for the latest git...
  

Requirement: JSON output for list and tags commands

The system SHALL support --format json for kb list, kb tags, kb info, and kb status commands. JSON output SHALL be valid and parseable by the skill wrapper.

Scenario: List documents as JSON

• WHEN user runs kb list --format json
• THEN output is a JSON array of document objects with id, title, type, tags, chunk_count, created_at

Scenario: Tags as JSON

• WHEN user runs kb tags --format json
• THEN output is a JSON array: [{"name": "git", "count": 15}, ...]

Scenario: Status as JSON

• WHEN user runs kb status --format json
• THEN output is a JSON object with documents (counts by type), total_chunks, db_size_bytes, model_name, embedding_dim, schema_version

Requirement: JSON schema stability

The JSON output schema SHALL be treated as a public contract. Fields MAY be added to JSON objects in future versions. Fields SHALL NOT be removed or renamed. The skill wrapper MUST be able to rely on the presence and type of all documented fields.

Scenario: Forward compatibility

• WHEN a future version adds a language field to search results
• THEN all existing fields remain present and unchanged, the new field is additive only

Requirement: Exit codes

The system SHALL use consistent exit codes: 0 for success, 1 for user errors (bad arguments, missing files), 2 for system errors (database corruption, model failure). JSON error output SHALL include an error field with a human-readable message.

Scenario: Successful operation

• WHEN any command completes successfully
• THEN exit code is 0

Scenario: User error with JSON output

• WHEN user runs kb search with no query argument
• THEN exit code is 1 and stderr contains a clear error message

Scenario: System error

• WHEN the SQLite database is corrupted
• THEN exit code is 2 and stderr contains the error details

Requirement: Skill definition file

The project SHALL include a SKILL.md file that defines how an LLM tool (e.g. Claude Code) should invoke and interpret kb commands. The skill file SHALL document: when to use the tool, available commands, output format, how to cite sources, and how to handle low-confidence results.

Scenario: Skill file exists

• WHEN the project is built
• THEN a SKILL.md file exists at the project root describing the skill interface for LLM consumption