know-tool

name	know-tool
description	Use when performing graph operations with the know CLI — adding or linking entities, validating, searching, or generating specs from the spec-graph/code-graph. Captures architecture and product decisions as graph entities instead of prose.

know-tool

know is a product knowledge-graph CLI. Capture architecture, product, and design decisions as graph entities — not prose. The spec-graph is the source of truth for product intent.

Discover the surface

• know -h — all commands. know <command> -h — usage for one command.
• know check ref-types — reference types with descriptions.
• know gen rules describe entities — entity types.
• know gen rules graph — the dependency topology (what may depend on what).

Entities

• Spec graph: project, user, objective, feature, workflow, action, component, operation
• Code graph: module, package, layer, namespace, interface, class, function
• Common reference types: data-model, endpoint, api-contract, business-logic, acceptance-criterion, validation-rule, source-file, external-dep, code-link

Core operations

know add <type> <key> '{"name":"...","description":"..."}'   # one or more entities
know link <from> <to> [<to2> ...]                            # one or more dependencies
know graph uses <entity>        # what it depends on   (alias: graph up)
know graph used-by <entity>     # what depends on it    (alias: graph down)
know search "<term>" --all-graphs    # cross-graph lexical search
know check validate             # validate after every change
know check stats                # graph statistics

Rules

• Run know check validate after graph changes.
• Graph files (*-graph.json) are write-protected — use know CLI commands for all modifications, never edit the JSON directly.
• Relationships live ONLY in the graph section as dependencies. Never add relationship attributes (refs, parent, uses, screen) onto an entity — express them as links.
• Prefer one batched call with multiple targets over several sequential calls.

Slash commands (Claude Code)

When adding features use /know:add; run /know:list to see existing features first. /know:plan, /know:build, /know:prepare, /know:connect, /know:review drive the larger workflows.