knowledge-graph

Original：🇺🇸 English

Translated

Manages persistent Knowledge Graph for specifications. Caches agent discoveries and codebase analysis to remember findings across sessions. Validates task dependencies, stores patterns, components, and APIs to avoid redundant exploration. Use when: you need to cache analysis results, remember findings, reuse previous discoveries, look up what we found, spec-to-tasks needs to persist codebase analysis, task-implementation needs to validate contracts, or any command needs to query existing patterns/components/APIs.

13installs

Sourcegiuseppe-trisciuoglio/developer-kit

Added on2026-03-31

NPX Install

npx skill4agent add giuseppe-trisciuoglio/developer-kit knowledge-graph

SKILL.md Content

View Translation Comparison →

Knowledge Graph Skill

Overview

Persistent JSON storage that caches agent discoveries and codebase analysis. Remember findings across sessions, validate task dependencies, query patterns/components/APIs, skip redundant exploration.

Location:

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

When to Use

Cache results - Before launching expensive codebase analysis, check if findings are already stored
Remember findings - After agent exploration, persist discoveries for future use
Reuse discoveries - Query existing context to maintain consistency across tasks
Validate dependencies - Check if required components/APIs exist before implementing
Look up previous work - Find what patterns, components, or APIs were already discovered

Instructions

read-knowledge-graph

Read existing Knowledge Graph or initialize empty structure:

Read file_path="docs/specs/001/knowledge-graph.json"

Returns full KG content. If file missing, returns empty structure and creates on first update.

query-knowledge-graph

Query specific sections:

components

patterns

apis

integration-points

all

Read file_path="docs/specs/001/knowledge-graph.json"

Filter results by section and process in-memory.

update-knowledge-graph

# 1. Read existing
Read file_path="docs/specs/001/knowledge-graph.json"

# 2. Deep-merge updates (arrays append by ID, objects preserve existing)
# 3. Update timestamp
Write file_path="docs/specs/001/knowledge-graph.json" content="<merged JSON>"

Deep-merge rules:

Arrays: append new items, deduplicate by
```
id
```
field
Objects: preserve existing keys, add/update new keys
Always update
```
metadata.updated_at
```
to current ISO timestamp

Complete JSON example for update:

json

{
  "metadata": {
    "spec_id": "001-hotel-search",
    "created_at": "2026-03-14T10:30:00Z",
    "updated_at": "2026-03-23T10:00:00Z",
    "version": "1.0.0"
  },
  "patterns": {
    "architectural": [
      {
        "id": "pat-001",
        "name": "Repository Pattern",
        "convention": "Extend JpaRepository<Entity, ID>",
        "files": ["src/main/java/**/repository/*Repository.java"]
      }
    ]
  },
  "components": {
    "services": [
      {
        "id": "comp-svc-001",
        "name": "HotelService",
        "location": "src/main/java/com/example/hotel/service/HotelService.java",
        "type": "service",
        "methods": [{"name": "searchHotels", "returns": "List<HotelDTO>"}]
      }
    ]
  }
}

validate-against-knowledge-graph

# 1. Read KG
Read file_path="docs/specs/001/knowledge-graph.json"

# 2. Check KG contains required IDs
# 3. Verify actual files exist
Grep pattern="src/**/HotelRepository.java"

Report satisfied dependencies and missing components.

validate-contract

# 1. Read KG and task expectations
Read file_path="docs/specs/001/knowledge-graph.json"
Glob pattern="src/**/ExpectedFile.java"
Grep pattern="class ExpectedClass|interface ExpectedInterface"

# 2. Match expectations against KG.provides
# 3. Report satisfied/unsatisfied contracts

extract-provides

# 1. Find implementation files
Glob pattern="src/**/*.java"

# 2. Extract symbols
Grep pattern="^(public|protected)? (class|interface|enum) " output_mode="content"

# 3. Classify by directory: /entity/ → entity, /service/ → service, /repository/ → repository
# 4. Update KG.provides with {task_id, file, symbols, type, implemented_at}

aggregate-knowledge-graphs

# 1. Find all KG files
Glob pattern="docs/specs/*/knowledge-graph.json"

# 2. Read each, extract patterns.architectural and patterns.conventions
# 3. Write merged .global-knowledge-graph.json
Write file_path="docs/specs/.global-knowledge-graph.json" content="<aggregated>"

Schema Structure

knowledge-graph.json
├── metadata (spec_id, created_at, updated_at, version, analysis_sources)
├── codebase_context (project_structure, technology_stack)
├── patterns (architectural[], conventions[])
├── components (controllers[], services[], repositories[], entities[], dtos[])
├── provides[] ({ task_id, file, symbols[], type, implemented_at })
├── apis (internal[], external[])
└── integration_points[]

Complete schema with field definitions: See

references/schema.md

Error Handling

Scenario	Handling
File not found	Return empty KG; creates on first update
Invalid JSON	Raise error; offer to recreate from analysis
Merge conflicts	Deep-merge preserves existing, adds new with timestamps
Write failure	Log error; continue without caching (non-blocking)

Update workflow:

Read:

Read

→

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

Validate update JSON structure
Deep-merge updates into KG object
Write:
```
Write
```
→ same path
Verify write succeeded

Best Practices

Before expensive operations:

Query KG first to check for cached analysis
If fresh (< 7 days), skip redundant exploration
Offer user choice: use cached or re-explore

After discoveries:

Update KG immediately after agent analysis completes
Include source agent/timestamp in metadata
Batch similar updates, avoid per-operation writes

Freshness guidelines:

< 7 days: Fresh, safe to use
7-30 days: Consider regenerating
30 days: Stale, re-analysis recommended

Examples

Cache Agent Discoveries (Complete Workflow)

# Step 1: Check existing KG
Read file_path="docs/specs/001/knowledge-graph.json"

# Step 2: Analyze codebase (agent task)
Glob pattern="src/main/java/**/*.java"
Grep pattern="public (class|interface) " output_mode="content"

# Step 3: Build update with discoveries
Write file_path="docs/specs/001/knowledge-graph.json" content="{
  \"metadata\": {
    \"spec_id\": \"001-hotel-search\",
    \"created_at\": \"2026-03-14T10:30:00Z\",
    \"updated_at\": \"2026-03-23T10:00:00Z\",
    \"version\": \"1.0.0\",
    \"analysis_sources\": [{\"agent\": \"general-code-explorer\", \"timestamp\": \"2026-03-23T10:00:00Z\"}]
  },
  \"patterns\": {
    \"architectural\": [{
      \"id\": \"pat-001\",
      \"name\": \"Repository Pattern\",
      \"convention\": \"Extend JpaRepository<Entity, ID>\"
    }]
  },
  \"components\": {
    \"services\": [{
      \"id\": \"comp-svc-001\",
      \"name\": \"HotelService\",
      \"location\": \"src/main/java/com/example/hotel/service/HotelService.java\",
      \"type\": \"service\"
    }],
    \"repositories\": [{
      \"id\": \"comp-repo-001\",
      \"name\": \"HotelRepository\",
      \"location\": \"src/main/java/com/example/hotel/repository/HotelRepository.java\",
      \"type\": \"repository\"
    }]
  }
}"

Validate Task Dependencies

# Read KG and task requirements
Read file_path="docs/specs/001/knowledge-graph.json"

# Verify components exist in codebase
Grep pattern="src/main/java/com/example/hotel/repository/HotelRepository.java"
Grep pattern="src/main/java/com/example/hotel/service/HotelService.java"

# Report validation result
# If all found: "All dependencies satisfied, proceed with implementation"
# If missing: "Warning: HotelService not found. Create it first?"

Query for Context Before Task Generation

# Load KG to get cached context
Read file_path="docs/specs/001/knowledge-graph.json"

# Present summary to user:
# "Found cached analysis (2 days old):
#  - Patterns: Repository Pattern, Service Layer
#  - Components: HotelService, HotelController
#  - Conventions: naming with *Controller/*Service/*Repository
#  Use cached context for task generation?"

More examples: See

references/query-examples.md

Constraints and Warnings

Critical Constraints:

Read-only on source code; only creates/updates
```
knowledge-graph.json
```
Only reads/writes KG files from
```
docs/specs/[ID]/
```
paths
Does NOT generate implementation code automatically

Limitations:

Validation checks KG only; cannot verify actual codebase if KG outdated
KG accuracy depends on freshness; re-explore if > 7 days old
Cross-spec learning only via
```
aggregate
```
operation

Warnings:

KG > 30 days old may not reflect current codebase state
Validator may report false negatives if KG predates implementation
Merge strategy preserves existing values; explicit overwrite required to replace