Knowledge Graph Skill

Overview

The Knowledge Graph (KG) is a persistent JSON file that stores discoveries from codebase analysis, eliminating redundant exploration and enabling task validation.

Location

:

docs/specs/[ID-feature]/knowledge-graph.json

Key Benefits:

✅ Avoid re-exploring already-analyzed codebases

✅ Validate task dependencies against actual codebase state

✅ Share discoveries across team members

✅ Accelerate task generation with cached context

When to Use

Use this skill when:

spec-to-tasks needs to cache/reuse codebase analysis

- Store agent discoveries for future reuse

task-implementation needs to validate task dependencies and contracts

- Check if required components exist before implementing

Any command needs to query existing patterns/components/APIs

- Retrieve cached codebase context

Reducing redundant codebase exploration

- Avoid re-analyzing already-explored code

Trigger phrases:

"Load knowledge graph"

"Query knowledge graph"

"Update knowledge graph"

"Validate against knowledge graph"

"Check if component exists"

"Find existing patterns"

Instructions

Available Operations

1. read-knowledge-graph

- Load and parse KG for a specification

Input

Path to spec folder (e.g.,

docs/specs/001-feature/

)

Output

KG object with metadata, patterns, components, APIs

2. query-knowledge-graph

- Query specific sections (components, patterns, APIs)

Input

Spec folder, query type, optional filters

Output

Filtered results matching criteria

3. update-knowledge-graph

- Update KG with new discoveries

Input

Spec folder, updates (partial KG), source description

Output

Merged KG with new findings

4. validate-against-knowledge-graph

- Validate task dependencies against KG

Input

Spec folder, requirements (components, APIs, patterns)

Output

Validation report with errors/warnings

5. validate-contract

- Validate provides/expects between tasks

Input

Spec folder, expects (files + symbols), completed dependencies

Output

Satisfied/unsatisfied expectations report

6. extract-provides

- Extract symbols from implemented files

Input

Array of file paths

Output

Array of provides with file, symbols, type

7. aggregate-knowledge-graphs

- Merge patterns from all specs

Input

Project root path

Output

Global KG with deduplicated patterns

See

references/query-examples.md

for detailed usage examples.

Examples

Input/Output Examples

Read Knowledge Graph:

Input: /knowledge-graph read docs/specs/001-hotel-search/

Output: {

metadata: { spec_id: "001-hotel-search", version: "1.0" },

patterns: { architectural: [...], conventions: [...] },

components:

}

Query Components:

Input: /knowledge-graph query docs/specs/001-hotel-search/ components

Output: [{ id: "comp-svc-001", name: "HotelSearchService", type: "service"}]

Update Knowledge Graph:

Input: /knowledge-graph update docs/specs/001-hotel-search/ {

patterns: { architectural: [{ name: "Repository Pattern"}] }

}

Output: "Added 1 pattern to knowledge graph"

Validate Dependencies:

Input: /knowledge-graph validate docs/specs/001-hotel-search/ {

components: ["comp-repo-001"]

}

Output:

See

references/examples.md

for comprehensive workflow examples.

KG Schema Reference

See

references/schema.md

for complete JSON schema with examples.

Integration Patterns

See

references/integration-patterns.md

for detailed integration with Developer Kit commands.

Error Handling

See

references/error-handling.md

for comprehensive error handling strategies and recovery procedures.

Performance Considerations

See

references/performance.md

for optimization strategies and performance characteristics.

Security

See

references/security.md

for security considerations, threat mitigation, and best practices.

Best Practices

When to Query KG

Before codebase analysis, task generation, dependency validation

When to Update KG

After agent discoveries, component implementation, pattern discovery

KG Freshness

:

< 7 days: Fresh

7-30 days: Stale, warn user

30 days: Very stale, offer regeneration

See

references/performance.md

and

references/security.md

for detailed best practices.

Constraints and Warnings

Critical Constraints

Source-Code Safe Operations

Does NOT modify source code files. Only creates/updates

knowledge-graph.json

files.

Path Validation

Only reads/writes KG files from

docs/specs/[ID]/

paths.

No Automatic Code Generation

Caches analysis results, does NOT generate implementation code.

Limitations

Validation Scope

Checks components exist in KG, but cannot verify if they exist in actual codebase if KG is outdated

Freshness Dependency

KG accuracy depends on how recently it was updated

Single-Spec First

Each KG is primarily specific to a single specification

File Size

KG files can grow large (>1MB) for complex specifications See references/error-handling.md and references/security.md for complete constraints and warnings. Reference Files schema.md - Complete JSON schema query-examples.md - Query patterns integration-patterns.md - Command integration error-handling.md - Error handling guide performance.md - Performance optimization security.md - Security considerations examples.md - Practical examples