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.
npm install -g know-cli
Requires Python >= 3.8.
# 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.
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
Know maintains two graphs in .ai/know/:
Maps who uses your product, what they need, and how it works:
Project -> User -> Objective -> Feature -> Workflow -> Action -> Component -> Operation
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.
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 |
The CLI is organized into two groups:
# 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 # Visualization know viz tree # ASCII tree know viz mermaid # Mermaid diagram know viz dot # Graphviz DOT know viz html # Interactive HTML (pyvis) know viz d3 # D3.js visualization know viz fzf # Fuzzy finder
know feature contract <name> # Display contract info know feature validate-contracts # Validate all contracts know feature validate <name> # Check if re-planning needed know feature done <name> # Complete and archive know feature impact <target> # Show affected features know feature coverage <name> # Test coverage know meta get <section> # Read meta sections know meta set <section> <key> <val> # Write meta sections know horizons list # Show project horizons know op status <feature> # Operation-level progress know req list <feature> # Feature requirements
know -g <path> # Use a specific graph file (default: .ai/know/spec-graph.json) know -r <path> # Override dependency rules file
Rules auto-detect based on graph filename. Spec graph uses dependency-rules.json, code graph uses code-dependency-rules.json.
The graph schema is defined by dependency rules in .ai/know/config/. After know init, you get local copies you can modify:
dependency-rules.json— spec graph entity types, allowed dependencies, reference typescode-dependency-rules.json— code graph rules
Change the rules to reshape the graph model for your domain.
bin/know.js # Node wrapper for npm distribution
know/know # Bash entrypoint (venv + Python)
know/know.py # Click CLI (~7,000 lines)
know/src/ # Python modules (25 modules + visualizers)
graph.py # Graph I/O and algorithms
entities.py # Entity CRUD
dependencies.py # Dependency rules and validation
validation.py # Graph structure validation
generators.py # Spec generation
diff.py # Graph comparison
visualizers/ # tree, mermaid, dot, html, d3, fzf
know/config/ # Default dependency rules
know/templates/ # Slash command templates, feature scaffolds
MIT