Know Tool

---
name: know-tool
description: 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.
---

# 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:

```bash
# 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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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:

- **[entity-types.md](references/entity-types.md)** - Deep dive on all entity types and their roles
- **[references-guide.md](references/references-guide.md)** - Understanding reference categories and when to use them
- **[meta-sections.md](references/meta-sections.md)** - Meta section structures and schemas
- **[commands-reference.md](references/commands-reference.md)** - Complete command listing with examples
- **[workflows.md](references/workflows.md)** - Common patterns: adding features, connecting actions, validation
- **[troubleshooting.md](references/troubleshooting.md)** - Debugging and fixing graph issues

## Quick Workflow Pattern

When adding a new feature:

```bash
# 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:

```bash
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

- **Adding/modifying entities?** → Read [entity-types.md](references/entity-types.md) and [workflows.md](references/workflows.md)
- **Working with references?** → Read [references-guide.md](references/references-guide.md)
- **Updating meta sections?** → Read [meta-sections.md](references/meta-sections.md)
- **Need command details?** → Read [commands-reference.md](references/commands-reference.md)
- **Debugging issues?** → Read [troubleshooting.md](references/troubleshooting.md)

## 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.