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: { controllers: [...], services: [...]} }

Query Components:

Input: /knowledge-graph query docs/specs/001-hotel-search/ components {"category": "services"} 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: { valid: true, errors: [], warnings: [] }

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