know-cli

know

Structured context for AI-driven software development. Spec graphs, not spec files.

Know turns product decisions into dependency graphs that LLMs can traverse — linking what you're building and why to how it gets implemented. Instead of brittle markdown specs that rot over time, you get a queryable graph where information lives in one place and relationships are first-class.

Install

npm install -g know-cli

Requires Node.js >= 14 and Python >= 3.8.

Quick Start

# Initialize in your project
know init .

# Start building your spec graph
/know:plan          # Product discovery conversation
/know:add           # Add features interactively
/know:build <feat>  # Build with structured context
/know:review <feat> # Acceptance testing walkthrough
/know:done <feat>   # Archive completed work

know init installs slash commands and a skill into your project for use with Claude Code.

Why Graphs Over Spec Files

Spec files are fine for humans. For AI, they're token overhead — brittle snapshots that bloat, duplicate information, and rot. Spec graphs solve this:

• Single source of truth — information lives in one place, not scattered across files
• Queryable relationships — traverse from user intent to implementation in a single query
• Generated on demand — specs are produced from the graph when needed, always current
• Deterministic completion — feature delivery is a graph state, not a checklist

Dual Graph System

Know maintains two graphs in .ai/know/:

Spec Graph (spec-graph.json) — Product Intent

Maps who uses your product, what they need, and how it works:

Project -> User -> Objective -> Feature -> Workflow -> Action -> Component -> Operation

Code Graph (code-graph.json) — Codebase Architecture

Maps your actual code structure and dependencies:

module -> [module, package, external-dep]
package -> [package, module, external-dep]
class   -> [class, interface, module]
function -> [function, module, class]

Graphs cross-link via implementation (spec->code) and graph-link (code->spec) references.

LLM Workflow

The primary interface is through slash commands in Claude Code:

Command	Purpose
/know:plan	Phased product discovery conversation
/know:add	Add features with interactive QA
/know:prepare	Bootstrap an existing codebase
/know:prebuild	Validate specs align with graph
/know:build <feat>	7-phase structured build workflow
/know:review <feat>	End-user acceptance testing
/know:done <feat>	Archive completed features
/know:bug	Track issues against features
/know:change <feat>	Structured change requests
/know:connect	Cross-link sparse graphs
/know:validate	Graph integrity checks
/know:list	Show features by status
/know:schema	Design custom graph schemas
/know:fill-out	Expand graph to full coverage

CLI Reference

The CLI is organized into two groups:

Graph — Structure and Data

# Add entities and references
know add <type> <key> [<key2>...] '{"name":"...","description":"..."}'

# Dependencies
know link <from> <to> [<to2> <to3>...]
know unlink <from> <to> [<to2>...]

# Query
know list [--type <type>]
know get <entity_id>
know search <query>
know find <query>              # Semantic search
know related <entity_id>

# Graph traversal
know graph uses <entity_id>    # What does this depend on?
know graph used-by <entity_id> # What depends on this?
know graph build-order         # Topological sort
know graph diff a.json b.json  # Compare graphs

# Node operations
know nodes update <id> '{"name":"New Name"}'
know nodes rename <id> <new_key>
know nodes merge <from> <into>
know nodes clone <id> <new_key>
know nodes delete <id> [-y]
know nodes deprecate <id> --reason "..."

# Validation
know check validate            # Full graph validation
know check syntax              # Fast structural check
know check structure           # Schema and orphan check
know check semantics           # Dependency rules and cycles
know check health              # Comprehensive health report
know check stats               # Graph statistics

# Generation
know gen spec <entity_id>      # Generate entity specification
know gen feature-spec <feat>   # Feature specification
know gen sitemap               # Interface sitemap
know gen codemap <src_dir>     # Code structure map
know gen trace <entity_id>     # Cross product-code boundary
know gen trace-matrix          # Requirement traceability matrix
know gen rules graph           # Visualize dependency topology