Master the know CLI tool for managing specification graphs. Use when working with spec-graph.json, understanding graph structure, querying entities/references/meta, managing dependencies, or learning graph architecture. Teaches dependency rules, entity types, and graph operations.
From knownpx claudepluginhub eighteyes/know-cli --plugin knowThis skill uses the workspace's default tool permissions.
references/creating.mdreferences/generating.mdreferences/qa-steps.mdreferences/validating.mdProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Calculates TAM/SAM/SOM using top-down, bottom-up, and value theory methodologies for market sizing, revenue estimation, and startup validation.
The specification graph (.ai/know/spec-graph.json) is a directed acyclic graph (DAG) representing software systems as interconnected nodes with explicit dependencies. Everything is a node, relationships are explicit, nothing is implied.
Three node types:
Key principle: The graph IS the source of truth. All relationships are explicit.
The meta.phases section tracks feature lifecycle and scheduling:
Phase Types:
I, II, III - Scheduling phases (immediate, next, future)pending - Not yet scheduleddone - Completed and archivedPhase Status:
incomplete - Feature added but not startedin-progress - Active developmentreview-ready - Implementation complete, awaiting reviewcomplete - Finished (in done phase)Phase Lifecycle:
/know:add → pending phase, status: incomplete
/know:build → status: in-progress → review-ready
/know:done → done phase, status: complete
Project → User → Objective → Feature → Action → Component → Operation
Flows from who uses it, through what they want, to how the system delivers it. requirement and interface are reference types, not entities.
Dependencies are strict and unidirectional:
Know CLI uses a flat structure with auto-detection:
| Command | Purpose |
|---|---|
know get <type:key> | Get entity or reference (auto-detects) |
know list [--type TYPE] | List entities or references (auto-detects) |
know search <pattern> | Search all text content (supports regex) |
know add <type> <key> [key2 ...] | Add one or more entities/references (auto-detects) |
know link <from> <to> [to2 ...] | Add one or more dependencies |
know unlink <from> <to> [to2 ...] | Remove one or more dependencies |
know nodes | Node operations: deprecate, merge, rename, delete, cut, clone, update |
know meta | Get, set, and delete meta sections (project, phases, decisions) |
know graph | Traverse, uses, used-by, connect, clean, suggest, diff, migrate, coverage, cross connect, cross coverage |
know graph coverage | Show % of spec entities reachable from root users |
know graph cross connect [feature] | Auto-connect spec features/components to code via token matching |
know graph cross coverage | Show spec↔code link coverage (% with code-link refs) |
know check | Validate, health, stats, gaps, orphans, cycles, completeness |
know gen | Specs, feature-specs, docs, traces, rules, codemap, code-graph, sitemap |
know feature | Lifecycle: status, connect, review, done, impact, validate, contracts, coverage |
know req | Requirements: add, list, status, block, complete |
know op | Op-level progress: start, done, next, reset, status |
know phases | Phase management: list, add, move, status, remove |
know init | Initialize know workflow (installs graph protection hooks) |
These commands expose the dependency structure for LLMs:
# Understand any type
know gen rules describe feature
know gen rules describe business_logic
know gen rules describe phases
# See dependency rules
know gen rules before component # What can depend on component?
know gen rules after feature # What can feature depend on?
# Visualize the structure
know gen rules graph # See the full dependency map
Always start with know gen rules commands before manipulating the graph.
know list # List all entities
know list --type feature # List entities of type (auto-detects entity vs reference)
know list --type business_logic # List references of type (auto-detects)
know get feature:real-time-telemetry # Get entity (auto-detects)
know get business_logic:login # Get reference (auto-detects)
# Search
know search "authentication" # Plain text search (case-insensitive)
know search "auth.*login" --regex # Regex search
know search "API" --section references # Search only references
know search "user" --field description # Search specific field
know search "Feature.*" -rc # Regex, case-sensitive
# Dependencies
know graph uses feature:real-time-telemetry # What does this entity use? (dependencies)
know graph used-by component:websocket-manager # What uses this entity? (dependents)
know graph up feature:x # Alias for 'uses' (go up dependency chain)
know graph down component:y # Alias for 'used-by' (go down chain)
# Cross-Graph Navigation (spec ↔ code)
know graph traverse feature:auth --direction impl # Show code implementations
know graph traverse module:auth --direction spec # Show spec feature
know graph traverse feature:profile # Auto-detects direction
# Statistics
know graph check stats # Graph statistics (entity counts, dependencies)
know graph check completeness feature:x # Completeness score for an entity
know add feature new-feature '{"name":"...", "description":"..."}' # Add single entity
know add feature feat-a feat-b feat-c -f data.json # Add multiple (shared data from file)
know add documentation new-doc '{"title":"...", "url":"..."}' # Add reference (auto-detects)
know meta set project key '{"value":"..."}' # Set meta value
know meta get project # Get meta section
know meta delete phases I # Delete meta key (prompts)
know meta delete requirements auth-login -y # Delete meta key (skip prompt)
know link feature:auth action:login # Add single dependency
know link feature:auth action:login action:logout component:session # Add multiple at once
know unlink feature:auth action:login action:logout # Remove multiple at once
know graph check validate # Must run after changes (includes fix commands in errors)
know graph check health # Comprehensive check
know graph check cycles # Find circular dependencies
know req)know req list feature:auth # List requirements with status
know req add feature:auth req-name '{"description":"..."}' # Add requirement
know req status feature:auth req-name in-progress # Update status
know req block feature:auth req-name --by "reason" # Mark blocked
know req complete feature:auth req-name # Mark complete
Status values: pending, in-progress, blocked, complete, verified
know op)know op status feature:auth # Show op status for a feature
know op next feature:auth # Print the next op number
know op start feature:auth # Mark current op as in-progress
know op done feature:auth # Mark current op as complete with commits
know op reset feature:auth # Reset an op to pending
know feature)know graph cross connect feature:auth # Create bidirectional spec ↔ code linkage
know feature connect auth module:x module:y # Link feature to multiple code entities at once
know feature review feature:auth # Review for completion: validate graph, check coverage
know feature done feature:auth # Complete: tag commits, update phase, archive
know feature impact entity:x # Show features depending on an entity or file
know feature validate feature:auth # Check if codebase changes warrant revisiting
know feature contract feature:auth # Display contract info
know feature validate-contracts # Validate for drift between contracts
know feature coverage feature # Aggregate coverage from feature level
know feature coverage feature --detail # Per-component breakdown
know nodes)# Deprecation
know nodes deprecate entity:id --reason "..." [--replacement entity:new]
know nodes undeprecate entity:id
know nodes deprecated # List all deprecated entities
know nodes deprecated --overdue # Only entities past removal date
# Modification
know nodes update entity:id '{"name":"New Name"}' # Update properties
know nodes rename entity:id new-key # Rename entity key (shows confirmation)
know nodes rename entity:id new-key -y # Skip confirmation
know nodes clone entity:id new-key # Clone with all dependencies
know nodes clone entity:id new-key --no-upstream # Clone without incoming deps
# Removal (works with entities AND references)
know nodes delete feature:old # Remove entity, clean up dependencies
know nodes delete feature:old action:bar # Remove multiple at once
know nodes delete data-model:old-schema # Remove reference, clean up dependencies
know nodes delete component:temp -y # Skip confirmation
know nodes cut entity:id # Remove node only, leave deps orphaned
know nodes cut reference:id -y # Skip confirmation
# Merging
know nodes merge from:entity into:entity # Merge entities, transfer deps (shows confirmation)
know nodes merge from:entity into:entity -y # Skip confirmation
know nodes merge from:entity into:entity --keep # Keep source after merge
# Graph Operations
know link feature:x action:y action:z # Add one or more dependencies
know unlink feature:x action:y action:z # Remove one or more (shows confirmation)
know unlink feature:x action:y -y # Skip confirmation
Important: All destructive operations (delete, cut, rename, merge, unlink) now show detailed confirmation prompts by default. Use -y or --yes to skip confirmation in scripts.
Note: Validation errors include fix commands. For example:
✗ Invalid dependency: feature:x → component:y. feature can only depend on: action
Fix: know unlink feature:x component:y
know graph check gap-analysis feature:x # Find missing dependencies
know graph check gap-missing # List missing connections in chains
know graph check gap-summary # Overall implementation status
know graph check orphans # Find unused references
know graph check usage # Reference usage statistics
know graph suggest # Suggest connections for orphaned references
know graph clean # Clean up unused references (dry run)
know graph clean --remove --execute # Actually remove unused references
know graph build-order # Topological sort
know graph connect entity:x # Suggest valid connections for an entity
know gen)know gen spec entity:x # Generate spec for a single entity
know gen feature-spec feature:x # Generate detailed feature specification
know gen docs feature:x # Generate .md files from graph for a feature
know gen trace entity:x # Trace entity across product-code boundary
know gen trace-matrix # Show requirement traceability matrix
know gen trace-matrix -t component # Trace specific entity type
know gen sitemap # Generate sitemap of all interfaces
know gen codemap # Generate code structure map
know gen code-graph # Generate code-graph from codemap
know graph migrate)know graph migrate # Check graph structure against current rules
know graph migrate --format json # Structured output for LLM consumption
know graph migrate-rules /path/to/new-rules.json # Analyze impact of rules change
know graph migrate-rules /path/to/new-rules.json --format json --verbose
know graph diff graph1.json graph2.json # Compare two graph files
know init # Initialize know workflow in a project
know init sets up the complete know workflow:
know init # Run in project root
know init --project-dir /path/to/project
What it installs:
.claude/commands/know/.claude/skills/know-tool/.claude/agents/.ai/know/.ai/know/project.md.claude/hooks/protect-graph-files.shGraph Protection Hook:
The hook automatically blocks direct Read/Edit/Write access to *-graph.json files, enforcing use of the know CLI:
❌ Direct Edit access to graph files is not allowed
Graph file: .ai/know/spec-graph.json
⚠️ Use the know CLI instead:
• Read: know get <entity-id>
• List: know list
• Edit: know add <type> <key> <data>
• Link: know link <from> <to>
• Validate: know graph check validate
Why this matters: Direct file editing can corrupt the graph structure. The hook ensures all modifications go through validated CLI commands.
Configuration: The hook is installed in .claude/settings.json:
{
"hooks": {
"PreToolUse": [{
"matcher": "Read|Edit|Write",
"hooks": [{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-graph-files.sh"
}]
}]
}
}
For detailed information, read these reference files:
When adding a new feature:
# 1. Understand the type
know gen rules describe feature
# 2. Add the entity
know add feature new-feature '{"name":"...", "description":"..."}'
# 3. Check what it can depend on
know gen rules after feature
# 4. Connect dependencies
know link feature:new-feature action:trigger-action
# 5. Validate
know graph check validate
know graph uses feature:new-feature --recursive
Phase = Roman numerals (I, II, III) - WHEN to do this feature (planning waves) Status = in-progress, complete, planned - current state of the work
Phase is the plan, status is the territory. A feature can be phase: III (planned for wave 3) but status: in-progress (started early).
know phases # Alias for phases list
know phases list # Show all features organized by phase
know phases add <phase> <entity> # Add feature to phase (e.g., know phases add I feature:auth)
know phases move <entity> <phase> # Move feature to different phase
know phases status <entity> <status> # Update status (planned, in-progress, complete)
know phases remove <entity> # Remove entity from all phases
Output includes:
meta.phases_metadatameta.requirements)Example output:
Phase I (Foundation)
🔄 feature:auth (3/5) - Authentication system
Phase II (Features)
📋 feature:api-gateway (0/4) - API routing
Phase III (Polish)
📋 feature:dark-mode (--) - No requirements yet
Note: "--" indicates no requirements exist yet for that feature.
Virtual flags computed from graph state (not stored, derived):
know feature status feature:auth # Show all three status flags
know phases list # Shows status icons inline
📋 Planned - Feature exists in meta.phases (any phase)
/know:add or /know:plan adding to phases✅ Implemented - Code-graph links exist for this feature
/know:build creating bidirectional spec↔code linkscode-link references pointing to this featuregraph-link, implementation, product-component are deprecated. Use code-link instead.✅ Reviewed - Git commit with [feature:id] merged to main
git log --grep "\[feature:auth\]" mainfeat: implement auth [feature:auth] in commit message/know:add → meta.phases[pending][feature:x] → 📋 planned
/know:build → creates code-links → ✅ implemented
git merge → [feature:x] in commit msg → ✅ reviewed
/know:done → removes from phases, archives → done
$ know feature status feature:auth
Feature Status: feature:auth
✅ Planned: Yes
Phase: I
Status: in-progress
✅ Implemented: Yes
Modules: module:auth-handler, module:session-store
✅ Reviewed: Yes
Commit: abc123f
Date: 2026-02-13
✓ Feature is fully complete!
Important: Always include [feature:name] in merge commit messages to enable automatic reviewed status detection.
Requirements replace todo.md for progress tracking:
meta.requirementsknow req commands (add, list, status, block, complete)know req list feature:x or know meta get requirementsknow gen rules describe references # List all reference types with descriptions
know gen rules describe <type> # Deep dive on any type (entity or reference)
know gen rules after <entity-type> # What can this entity depend on?
know gen rules before <entity-type> # What can depend on this entity?
Run these before adding references. The rules file is the canonical source for what types exist and what they mean.
code-linkcode-link is the current reference type for linking spec and code graphs:
| Graph | Schema |
|---|---|
| spec-graph | { modules, classes, packages, status } |
| code-graph | { feature, component, status } |
Usage: Cross-graph link between spec entities (feature/component) and code entities (module/class).
Deprecated: graph-link, implementation, and product-component are deprecated cross-graph reference types. Use code-link instead.
The permission reference type links users to features for access control:
"references": {
"permission": {
"admin-full-access": "*",
"editor": ["feature:user-management", "feature:content-editor"],
"viewer": ["feature:dashboard", "feature:reports"],
"trusted-user": ["*", "!feature:admin-panel", "!feature:billing"]
}
}
Users depend on permissions to define what they can access:
"graph": {
"user:admin": {"depends_on": ["permission:admin-full-access"]},
"user:trusted": {"depends_on": ["permission:trusted-user"]}
}
Permission values:
"*" - All features["feature:x", "feature:y"] - Specific features only["*", "!feature:x"] - All features except those negated with !When a reference has a rendering in an external tool (Figma, Pencil, Storybook), store the external ID on the reference. This creates spec-to-design traceability.
figma_id — Figma node or frame IDpen_file — Pencil .pen file pathstorybook_id — Storybook story identifierexternal_url — Generic link to external artifactApplies to any reference type with an external rendering, not just interfaces.
know graph uses + know graph used-by + know graph check orphansknow CLI commands (enforced by hooks)know graph check validateknow gen rules to check before adding dependenciesknow graph check cyclestype:key format (e.g., feature:real-time-telemetry)graph sectionknow graph check gap-analysis to ensure full dependency chainsknow search <pattern> is faster than reading the entire graph-y flag to skip confirmation in automated scriptsknow unlink, know add, know link, or any other write command in parallel (e.g., with & in bash) causes race conditions where the last writer overwrites earlier changes. Always chain write commands with && or run them in a single sequential script.If know command is not found, run python3 know/know.py from the project root. See project INSTALL.md for setup.
Remember: The graph is dependency-driven. Use know gen rules to understand structure before making changes. Always validate after modifications.