know-tool

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.

⭐2stars🔀1forks📁View on GitHub🕐Updated Dec 3, 2025

When & Why to Use This Skill

The Know Tool is a specialized Claude skill designed for mastering software specification graphs, enabling developers to maintain a rigorous 'source of truth' for complex system architectures. By utilizing a Directed Acyclic Graph (DAG) model, it allows for the explicit management of entities, references, and metadata, ensuring that every software component and its dependencies are clearly defined, validated, and traceable throughout the development lifecycle.

Use Cases

  • Architectural Mapping: Visualizing and managing complex software dependencies to prevent circular references and maintain a clean Directed Acyclic Graph (DAG).
  • Feature Lifecycle Tracking: Managing the progression of features from 'pending' to 'complete' using integrated phase management and status tracking.
  • Gap Analysis & Validation: Identifying missing architectural connections between user requirements and technical implementations to ensure system completeness.
  • Automated Documentation: Generating detailed feature specifications, sitemaps, and dependency reports directly from the project's specification graph.
  • Dependency Enforcement: Using 'know rules' to define and enforce strict unidirectional dependency constraints between different types of system nodes.
nameknow-tool
descriptionMaster 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.

Know Tool - Specification Graph Mastery

What is the Specification Graph?

The specification graph (.ai/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:

  1. Entities - Structural nodes that participate in dependencies (user, feature, component, etc.)
  2. References - Terminal nodes with implementation details (business_logic, data-models, etc.)
  3. Meta - Project metadata (phases, assumptions, decisions, qa_sessions)

Key principle: The graph IS the source of truth. All relationships are explicit.

Phases in meta.phases

The meta.phases section tracks feature lifecycle and scheduling:

Phase Types:

  • I, II, III - Scheduling phases (immediate, next, future)
  • pending - Not yet scheduled
  • done - Completed and archived

Phase Status:

  • incomplete - Feature added but not started
  • in-progress - Active development
  • review-ready - Implementation complete, awaiting review
  • complete - 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

Core Mental Model

Two Chains

WHAT Chain (User Intent):

project → user → objective → action

HOW Chain (Implementation):

project → requirement → interface → feature → action → component → operation

Action connects both chains - what users DO and how the system implements it.

Dependency Rules

Dependencies are strict and unidirectional:

  • Only entities participate in dependencies
  • References are terminal nodes (no dependencies)
  • Graph must remain a DAG (no cycles)

Using know rules Commands

These commands expose the dependency structure for LLMs:

# Understand any type
know rules describe feature
know rules describe business_logic
know rules describe phases

# See dependency rules
know rules before component    # What can depend on component?
know rules after feature        # What can feature depend on?

# Visualize the structure
know rules graph                # See the full dependency map

Always start with know rules commands before manipulating the graph.

Essential Commands

Discovery & Exploration

know list                       # List all entities
know list-type feature          # List specific type
know get feature:real-time-telemetry

# Dependencies
know uses feature:real-time-telemetry          # What does this entity use? (dependencies)
know used-by component:websocket-manager       # What uses this entity? (dependents)
know up feature:x                              # Alias for 'uses' (go up dependency chain)
know down component:y                          # Alias for 'used-by' (go down chain)

# Statistics
know stats                      # Graph statistics (entity counts, dependencies)
know completeness feature:x     # Completeness score for an entity

Modification

know add feature new-feature '{"name":"...", "description":"..."}'
know link feature:analytics action:export-report     # Add dependency
know unlink feature:analytics action:export-report   # Remove dependency

Validation

know validate                   # Must run after changes (includes fix commands in errors)
know health                     # Comprehensive check
know cycles                     # Find circular dependencies

Note: Validation errors now include example fix commands. For example:

✗ Invalid dependency: feature:x → component:y. feature can only depend on: action
  Fix: know unlink feature:x component:y

Analysis

know gap-analysis feature:x     # Find missing dependencies
know gap-missing                # List missing connections in chains
know gap-summary                # Overall implementation status
know ref-orphans                # Find unused references
know ref-usage                  # Reference usage statistics
know ref-suggest                # Suggest connections for orphaned references
know ref-clean                  # Clean up unused references
know build-order                # Topological sort
know trace entity:x             # Trace entity across product-code boundary
know suggest entity:x           # Suggest valid connections for an entity

Specification Generation

know spec entity:x              # Generate spec for single entity
know feature-spec feature:x     # Generate detailed feature specification
know sitemap                    # Generate sitemap of all interfaces

Advanced

know diff graph1.json graph2.json    # Compare two graph files
know init                            # Initialize know workflow in a project
know llm-chains                      # List available LLM workflow chains
know llm-providers                   # List available LLM providers

Reference Files

For detailed information, read these reference files:

Quick Workflow Pattern

When adding a new feature:

# 1. Understand the type
know rules describe feature

# 2. Add the entity
know add feature new-feature '{"name":"...", "description":"..."}'

# 3. Check what it can depend on
know rules after feature

# 4. Connect dependencies
know link feature:new-feature action:trigger-action

# 5. Validate
know validate
know uses feature:new-feature --recursive

Viewing Phases

The know phases command displays features grouped by phase:

know phases    # Show all features organized by phase with task counts

Output includes:

  • Phase metadata (shortname, name, description) from meta.phases_metadata
  • Features within each phase
  • Task completion counts from .ai/know/<feature>/todo.md
  • Status icons (✅ completed, 🔄 in-progress, 📋 planned)
  • Summary totals

Example output:

Phase I (Foundation)
  🔄 feature:auth (3/13) - Authentication system

Phase II (Features)
  📋 feature:api-gateway (0/8) - API routing

Done
  ✅ feature:onboarding (8/8) - User onboarding

Critical Rules for LLMs

  1. Always validate after modifications - Run know validate
  2. Respect entity vs reference distinction - Entities participate in dependencies, references don't
  3. Follow dependency rules - Use know rules to check before adding dependencies
  4. Maintain DAG properties - No cycles allowed, check with know cycles
  5. Use full paths - Always use type:key format (e.g., feature:real-time-telemetry)
  6. Never add dependencies to entity objects - Only in the graph section
  7. Check completeness - Use know gap-analysis to ensure full dependency chains

When to Read Which Reference

Installation Note

If know command is not found, the tool is at /Users/god/projects/know-cli/know/know. See project INSTALL.md for setup.


Remember: The graph is dependency-driven. Use know rules to understand structure before making changes. Always validate after modifications.