giuseppe-trisciuoglio/developer-kit

Comprehensive developer toolkit providing reusable skills for Java/Spring Boot, TypeScript/NestJS/React/Next.js, Python, PHP, AWS CloudFormation, AI/RAG, DevOps, and more.

Quality

90%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Risky

Do not use without reviewing

This version of the tile failed moderation

Moderation pipeline encountered an internal error

Examples - Knowledge Graph

Name: giuseppe-trisciuoglio/developer-kit
Rating: 90.85333333333334 (1 reviews)
Author: giuseppe-trisciuoglio

Practical examples of Knowledge Graph operations and workflows.

Example 1: Cache Agent Discoveries

Scenario: spec-to-tasks Phase 3.5 - Agent discovers Repository Pattern

Agent output:

Found Repository Pattern with JpaRepository convention
All repositories extend JpaRepository<Entity, ID>
Located in: src/main/java/com/example/repository/

Update KG:

/knowledge-graph update docs/specs/001-hotel-search/ {
  patterns: {
    architectural: [
      {
        id: "pat-001",
        name: "Repository Pattern",
        category: "data-access",
        convention: "All repositories extend JpaRepository<Entity, ID>",
        location: "src/main/java/com/example/repository/",
        discovered_at: "2026-03-14T10:30:00Z"
      }
    ]
  }
} "general-software-architect agent"

Result:

docs/specs/001-hotel-search/knowledge-graph.json updated with pattern discovery
Metadata updated with new analysis source
Pattern can be queried in future operations

Example 2: Validate Task Dependencies

Scenario: task-implementation Task Mode - Task requires HotelRepository

Task: "Use HotelRepository to search hotels"

Validate:

/knowledge-graph validate docs/specs/001-hotel-search/ {
  components: ["comp-repo-001"]
}

Result:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "found": [
    {
      "id": "comp-repo-001",
      "name": "HotelRepository",
      "type": "repository",
      "location": "src/main/java/com/hotels/search/repository/HotelRepository.java"
    }
  ]
}

Outcome: Task validated, proceed with implementation

Example 3: Query for Context

Scenario: spec-to-tasks Phase 4 - Generate tasks for new feature

Need: Generate tasks for "Add booking feature" using existing patterns

Query KG:

/knowledge-graph query docs/specs/001-hotel-search/ patterns

Result:

[
  {
    "name": "Repository Pattern",
    "convention": "Extend JpaRepository with Entity and ID types"
  },
  {
    "name": "Service Layer",
    "convention": "@Service classes with business logic"
  },
  {
    "name": "DTO Pattern",
    "convention": "Data Transfer Objects for API layer"
  }
]

Usage: Generate tasks following discovered patterns

Example 4: Contract Validation Failure

Scenario: Task expects SearchId value object, but no dependency provides it

Task Expects:

{
  "expects": [
    {
      "file": "src/main/java/com/hotels/search/domain/valueobject/SearchId.java",
      "symbols": ["SearchId"]
    }
  ]
}

Completed Dependencies:

[
  {
    "task_id": "TASK-001",
    "provides": [
      {
        "file": "src/main/java/com/hotels/search/domain/entity/Search.java",
        "symbols": ["Search", "SearchStatus", "SearchCriteria"]
      }
    ]
  }
]

Validate Contract:

/knowledge-graph validate-contract docs/specs/001-hotel-search/ expects completed_dependencies

Result:

{
  "satisfied": [
    {
      "expectation": "Search entity with symbols [Search, SearchStatus]",
      "provided_by": "TASK-001"
    }
  ],
  "unsatisfied": [
    {
      "expectation": "SearchId value object",
      "provided_by": "None",
      "reason": "No completed dependency provides SearchId"
    }
  ],
  "valid": false
}

Action: Implement SearchId in current task or reorder dependencies

Example 5: Extract Provides from Implementation

Scenario: Task completed, extract what was implemented

Files implemented:

[
  "src/main/java/com/hotels/search/domain/entity/Search.java",
  "src/main/java/com/hotels/search/domain/valueobject/SearchId.java"
]

Extract:

/knowledge-graph extract-provides files

Result:

{
  "provides": [
    {
      "file": "src/main/java/com/hotels/search/domain/entity/Search.java",
      "symbols": ["Search", "SearchStatus"],
      "type": "entity"
    },
    {
      "file": "src/main/java/com/hotels/search/domain/valueobject/SearchId.java",
      "symbols": ["SearchId"],
      "type": "value-object"
    }
  ]
}

Usage: Persist to KG for future contract validation

Example 6: Aggregate Multiple KGs

Scenario: Create project-wide knowledge graph from all specs

Aggregate:

/knowledge-graph aggregate /path/to/project/root

Process:

Scan all docs/specs/*/knowledge-graph.json files
Extract patterns.architectural and patterns.conventions
Deduplicate by pattern name
Write to docs/specs/.global-knowledge-graph.json

Result:

{
  "metadata": {
    "aggregated_at": "2026-03-14T15:00:00Z",
    "project_root": "/path/to/project",
    "contributing_specs": ["001-hotel-search", "002-booking", "003-payment"],
    "total_patterns": 15
  },
  "patterns": {
    "architectural": [
      {
        "name": "Repository Pattern",
        "sources": ["001-hotel-search", "002-booking"],
        "frequency": 2,
        "first_seen": "2026-03-01T10:00:00Z",
        "convention": "Extend JpaRepository<Entity, ID>"
      },
      {
        "name": "Service Layer",
        "sources": ["001-hotel-search", "002-booking", "003-payment"],
        "frequency": 3,
        "first_seen": "2026-03-01T10:00:00Z",
        "convention": "@Service classes with @Transactional methods"
      }
    ],
    "conventions": [
      {
        "name": "Naming Convention",
        "sources": ["001-hotel-search"],
        "frequency": 1,
        "examples": ["Repository suffix for repositories", "Service suffix for services"]
      }
    ]
  }
}

Example 7: Query Specific Component Types

Scenario: Find all services in the codebase

Query:

/knowledge-graph query docs/specs/001-hotel-search/ components {"category": "services"}

Result:

[
  {
    "id": "comp-svc-001",
    "name": "HotelSearchService",
    "type": "service",
    "location": "src/main/java/com/hotels/search/service/HotelSearchService.java",
    "annotations": ["@Service"],
    "methods": ["searchHotels", "getHotelById"]
  },
  {
    "id": "comp-svc-002",
    "name": "BookingService",
    "type": "service",
    "location": "src/main/java/com/hotels/booking/service/BookingService.java",
    "annotations": ["@Service"],
    "methods": ["createBooking", "cancelBooking"]
  }
]

Example 8: Validate API Existence

Scenario: Task needs to call internal API /api/v1/hotels

Validate:

/knowledge-graph query docs/specs/001-hotel-search/ apis {
  "type": "internal",
  "path": "/api/v1/hotels"
}

Result:

[
  {
    "id": "api-int-001",
    "path": "/api/v1/hotels",
    "method": "GET",
    "type": "internal",
    "controller": "HotelController",
    "description": "Search hotels by criteria"
  }
]

Outcome: API exists, task can proceed

Example 9: Full Workflow Integration

Scenario: Complete spec-to-tasks workflow with KG

Phase 1: Exploration

Agent: Explore codebase for "hotel search aggregation"
Discovers:
- Repository Pattern
- Service Layer Pattern
- DTO Pattern

Phase 2: Update KG (after exploration)

/knowledge-graph update docs/specs/001-hotel-search/ {
  patterns: {
    architectural: [
      { "name": "Repository Pattern", "convention": "..." },
      { "name": "Service Layer", "convention": "..." },
      { "name": "DTO Pattern", "convention": "..." }
    ]
  }
} "general-software-architect agent"

Phase 3: Generate Tasks

Query KG for patterns → Generate tasks following patterns

Phase 4: Validate Task Dependencies

/knowledge-graph validate docs/specs/001-hotel-search/ {
  components: ["comp-repo-001", "comp-svc-001"]
}

Phase 5: Implement Task

Implement feature following discovered patterns

Phase 6: Extract Provides

/knowledge-graph extract-provides [
  "src/main/java/.../HotelAggregateService.java",
  "src/main/java/.../HotelAggregateRepository.java"
]

Phase 7: Update KG with New Components

/knowledge-graph update docs/specs/001-hotel-search/ {
  components: {
    services: [...],
    repositories: [...]
  },
  provides: [...]
} "task-implementation agent"

Example 10: Stale Knowledge Detection

Scenario: KG is 45 days old, may be stale

Check:

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

Result:

{
  "metadata": {
    "updated_at": "2026-02-01T10:00:00Z"
  }
}

Calculate age: 45 days old (> 30 day threshold)

Warning:

⚠️  Warning: Knowledge graph is stale (45 days old)
Codebase may have changed since last analysis.
Recommend regenerating from codebase.

Would you like to:
1. Proceed with stale knowledge (may have outdated info)
2. Regenerate knowledge graph from codebase (recommended)

Example 11: Merge Conflict Resolution

Scenario: Two agents update KG concurrently

Agent A updates:

{
  "patterns": {
    "architectural": [
      { "name": "Repository Pattern", "convention": "JpaRepository" }
    ]
  }
}

Agent B updates:

{
  "patterns": {
    "architectural": [
      { "name": "Service Layer", "convention": "@Service" }
    ]
  }
}

Merge result (deep merge):

{
  "patterns": {
    "architectural": [
      { "name": "Repository Pattern", "convention": "JpaRepository" },
      { "name": "Service Layer", "convention": "@Service" }
    ]
  },
  "metadata": {
    "updated_at": "2026-03-14T15:30:00Z",
    "analysis_sources": [
      { "agent": "Agent A", "timestamp": "2026-03-14T15:00:00Z" },
      { "agent": "Agent B", "timestamp": "2026-03-14T15:30:00Z" }
    ]
  }
}

Message: "Merged 2 new findings into existing knowledge graph"

Example 12: Incremental Learning

Scenario: KG grows as project evolves

Day 1 (Initial):

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

Day 7 (After feature additions):

{
  "patterns": {
    "architectural": [
      { "name": "Repository Pattern" },
      { "name": "Service Layer" },
      { "name": "DTO Pattern" }
    ]
  }
}

Day 30 (After new features):

{
  "patterns": {
    "architectural": [
      { "name": "Repository Pattern" },
      { "name": "Service Layer" },
      { "name": "DTO Pattern" },
      { "name": "Factory Pattern" },
      { "name": "Strategy Pattern" }
    ]
  }
}

Benefit: KG becomes more comprehensive over time, improving task generation and validation.

Example 13: Cross-Spec Learning

Scenario: Learn patterns across multiple specifications

Spec 001 (Hotel Search):

Uses Repository Pattern
Uses Service Layer

Spec 002 (Booking):

Uses Repository Pattern
Uses Service Layer
Uses Unit of Work Pattern

Aggregated:

{
  "patterns": {
    "architectural": [
      {
        "name": "Repository Pattern",
        "sources": ["001-hotel-search", "002-booking"],
        "frequency": 2
      },
      {
        "name": "Service Layer",
        "sources": ["001-hotel-search", "002-booking"],
        "frequency": 2
      },
      {
        "name": "Unit of Work Pattern",
        "sources": ["002-booking"],
        "frequency": 1
      }
    ]
  }
}

Usage: When generating tasks for Spec 003, recommend following most common patterns (Repository, Service Layer).

Example 14: Error Recovery

Scenario: KG file corrupted

Read attempt:

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

Error:

❌ Error: Knowledge graph corrupted at docs/specs/001-hotel-search/knowledge-graph.json
Invalid JSON: Expecting ',' delimiter: line 42 column 5 (char 1023)

Recovery options:

🔧 Recovery options:

1. Recreate from codebase analysis
   - Re-run codebase exploration
   - Generate new KG from scratch
   - Estimated time: 2-5 minutes

2. Restore from backup (if available)
   - Check git history for previous version
   - Restore last known good version

3. Manual repair
   - Edit JSON file to fix syntax
   - Advanced users only

Which option would you like?

Example 15: Performance Optimization

Scenario: KG file is 1.5 MB (too large)

Detection:

⚠️  Warning: Knowledge graph is large (1.5 MB)
Recommend splitting by feature area for better performance.

Current structure:
docs/specs/001-hotel-search/knowledge-graph.json (1.5 MB)

Suggested split:
docs/specs/001-hotel-search/kg-auth.json (300 KB)
docs/specs/001-hotel-search/kg-database.json (400 KB)
docs/specs/001-hotel-search/kg-api.json (500 KB)
docs/specs/001-hotel-search/kg-services.json (300 KB)

Would you like to split the knowledge graph?

Summary

Common operations:

Cache discoveries: Update KG with agent findings
Validate dependencies: Check if components exist
Query patterns: Retrieve conventions for task generation
Validate contracts: Check if dependencies provide what's needed
Extract provides: Analyze implementation to capture what was built
Aggregate KGs: Create project-wide pattern summary
Detect staleness: Check if KG needs refresh

Key workflows:

spec-to-tasks: Explore → Update KG → Query KG for patterns
task-implementation: Validate dependencies → Implement → Extract provides → Update KG
spec-quality: Sync provides from completed tasks

Error handling: