Developer Kit for Claude Code (giuseppe-trisciuoglio/developer-kit)

Developer Kit for Claude Code

https://github.com/giuseppe-trisciuoglio/developer-kit
Admin
Developer Kit for Claude Code is a modular plugin system providing reusable skills, agents, and...

Tokens:2,507,243
Snippets:21,980
Trust Score:7.5
Update:2 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# Developer Kit

Developer Kit is a modular AI plugin marketplace for Claude Code (and compatible CLIs) that teaches AI assistants to perform software development tasks in a repeatable, high-quality way. Instead of ad-hoc AI responses, it delivers domain-specific expertise through 150+ skills, 45+ specialized agents, and 20+ commands organized into self-contained plugins by language and technology — Java/Spring Boot, TypeScript/NestJS/React, Python, PHP/WordPress, AWS/CloudFormation, AI/ML, and DevOps. Version 2.8.2 supports Claude Code, GitHub Copilot CLI, OpenCode CLI, and Codex CLI via a unified Makefile installer.

The system has four capability layers: **Skills** (reusable domain know-how loaded on-demand), **Agents** (specialized sub-agents for code review, refactoring, security, architecture), **Commands** (interactive slash-command workflows with mandatory user-gate checkpoints), and **Rules** (path-scoped `.claude/rules/` files that auto-activate for matching file patterns). The flagship workflow is **Specifications-Driven Development (SDD)**, a structured lifecycle that takes an idea through brainstorming → functional specification → task decomposition → TDD implementation → review → cleanup → spec synchronization, preserving a living Knowledge Graph and decision log throughout.

---

## Installation

### Marketplace install (Claude Code)

```bash
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
```

### Manual install via Makefile

```bash
git clone https://github.com/giuseppe-trisciuoglio/developer-kit.git
cd developer-kit

make install          # auto-detects all installed CLIs
make install-claude   # Claude Code only
make install-copilot  # GitHub Copilot CLI only
make install-opencode # OpenCode CLI only
make install-codex    # Codex CLI only
```

### Copy language rules into your project

```bash
# Copy rules from a specific plugin (activates automatically via globs: frontmatter)
make copy-rules PLUGIN=developer-kit-java
make copy-rules PLUGIN=developer-kit-typescript

# Or manually
mkdir -p .claude/rules
cp plugins/developer-kit-java/rules/*.md .claude/rules/
```

### Validation & security scan

```bash
python .skills-validator-check/validators/cli.py --all
make security-scan          # MCP-Scan on all skills
make security-scan-changed  # MCP-Scan only on changed skills
```

---

## `/specs:brainstorm` — Transform an Idea into a Functional Specification

Guides the developer through a 9-phase collaborative session that produces a technology-agnostic functional specification (WHAT, not HOW) saved under `docs/specs/[id]/`. The command assesses scope early and recommends splitting ideas that would generate more than 15 tasks.

```bash
# Simple feature
/developer-kit-specs:specs.brainstorm Add user authentication with JWT tokens

# Complex real-time feature
/developer-kit-specs:specs.brainstorm Implement real-time notifications using WebSockets

# Full SDD workflow: brainstorm → tasks → implement
/developer-kit-specs:specs.brainstorm Design a microservices architecture for the reporting module
# Output: docs/specs/001-reporting-module/2026-05-10--reporting-module.md

/developer-kit-specs:specs.spec-to-tasks --lang=spring docs/specs/001-reporting-module/
# Output: docs/specs/001-reporting-module/tasks/TASK-001.md ... TASK-NNN.md

/developer-kit-specs:specs.task-implementation --lang=spring --task="docs/specs/001-reporting-module/tasks/TASK-001.md"
```

---

## `/specs:spec-to-tasks` — Convert Specification into Executable Tasks

Reads the functional specification produced by `specs.brainstorm` and decomposes it into atomic, trackable task files with YAML frontmatter (id, title, status, lang, dependencies, complexity). Enforces a hard limit of 15 implementation tasks per spec. Outputs a task list, data model, and API contracts.

```bash
# Java/Spring Boot tasks
/developer-kit-specs:specs.spec-to-tasks --lang=spring docs/specs/001-feature/

# TypeScript/NestJS tasks
/developer-kit-specs:specs.spec-to-tasks --lang=nestjs docs/specs/002-feature/

# Python tasks
/developer-kit-specs:specs.spec-to-tasks --lang=python docs/specs/003-feature/

# Expected output structure:
# docs/specs/001-feature/
# ├── 2026-05-10--feature-name.md         (spec)
# ├── 2026-05-10--feature-name--tasks.md  (task list)
# ├── data-model.md
# ├── contracts/
# └── tasks/
#     ├── TASK-001.md
#     ├── TASK-002.md
#     └── TASK-NNN.md
```

---

## `/specs:task-implementation` — Implement a Single Spec Task

Focused single-task implementation workflow. Reads the task file, explores the codebase for relevant patterns, designs the solution, implements it following project conventions, and runs a code review. Auto-detects the task from the current git branch if `--task` is omitted.

```bash
# Implement a specific task
/developer-kit-specs:specs.task-implementation --lang=java --task="docs/specs/001-feature/tasks/TASK-003.md"

# TypeScript NestJS task
/developer-kit-specs:specs.task-implementation --lang=nestjs --task="docs/specs/002-feature/tasks/TASK-001.md"

# Auto-detect task from current branch
/developer-kit-specs:specs.task-implementation --lang=spring
```

---

## `/specs:task-tdd` — Test-Driven Development for a Task

Generates failing tests (RED phase) before any implementation code is written. Mandatory first step in the SDD per-task loop; the subsequent `task-implementation` makes the tests pass (GREEN phase).

```bash
# RED phase — write failing tests first
/developer-kit-specs:specs.task-tdd --lang=java --task="docs/specs/001-feature/tasks/TASK-003.md"

# Then GREEN phase — implement to make tests pass
/developer-kit-specs:specs.task-implementation --lang=java --task="docs/specs/001-feature/tasks/TASK-003.md"

# Then review
/developer-kit-specs:specs.task-review --task="docs/specs/001-feature/tasks/TASK-003.md"
```

---

## `/specs:task-review` — Verify a Task Against Spec and Code Quality

Validates the implemented task against its acceptance criteria, checks specification compliance, performs language-specific code review, and generates a structured review report. Must pass before proceeding to cleanup.

```bash
# Review after implementation
/developer-kit-specs:specs.task-review --task="docs/specs/001-feature/tasks/TASK-003.md"

# Output: review report with PASS / FAIL verdict and line-level findings
# Mandatory gate — must fix all findings before cleanup
```

---

## `/specs:spec-sync-with-code` — Sync Specification with Implementation Reality

After completing one or more tasks, detects drift between the functional specification and the actual code, then updates the spec to reflect decisions made during coding. Closes the SDD triangle (Spec ↔ Tests ↔ Code).

```bash
/developer-kit-specs:specs.spec-sync-with-code docs/specs/001-feature/

# After a specific task
/developer-kit-specs:specs.spec-sync-with-code docs/specs/001-feature/ --after-task=TASK-003
```

---

## Ralph Loop (`ralph_loop.py`) — Automated Multi-Task Orchestration

A Python state-machine orchestrator that drives the full SDD per-task cycle (implementation → review → fix → cleanup → sync → done) one step at a time, persisting state in `fix_plan.json` to avoid context-window overflow. Supports task-range filtering and 7 AI CLI agents.

```bash
# 1. Initialize — scan tasks and create fix_plan.json
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-001 \
  --to-task=TASK-010 \
  --agent=claude

# 2. Run one step — script prints the exact CLI command to execute
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/
# → Execute:  /developer-kit-specs:specs.task-implementation --task=TASK-001
# → Run loop again after execution

# 3. Advance state after manual command execution
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=next \
  --spec=docs/specs/001-feature/

# 4. Check progress
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/

# 5. Scheduled with Claude Code /loop every 5 minutes
/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/

# Task file format (YAML frontmatter)
# docs/specs/001-feature/tasks/TASK-001.md
# ---
# id: TASK-001
# title: Implement JWT authentication
# status: pending
# lang: java
# dependencies: []
# complexity: medium
# agent: claude
# ---
```

---

## `/devkit.feature-development` — Guided Feature Implementation

A 7-phase workflow: pre-flight git/lint check → codebase exploration → clarifying questions (mandatory gate) → architecture design (mandatory gate) → implementation → quality review → summary. Dispatches language-specific sub-agents based on `--lang`.

```bash
# General purpose
/developer-kit:devkit.feature-development Add user authentication

# Java/Spring Boot
/developer-kit:devkit.feature-development --lang=spring Add REST API for user management

# NestJS
/developer-kit:devkit.feature-development --lang=nestjs Implement authentication module with JWT

# React frontend
/developer-kit:devkit.feature-development --lang=react Create dashboard with charts and user filters

# Python FastAPI
/developer-kit:devkit.feature-development --lang=python Implement REST API with FastAPI and SQLAlchemy

# AWS infrastructure
/developer-kit:devkit.feature-development --lang=aws Create ECS Fargate infrastructure with auto scaling
```

---

## `/devkit.refactor` — Systematic Code Refactoring

9-phase refactoring workflow with two mandatory user gates: compatibility requirements (backward compatible / breaking changes / internal only) and strategy approval. Runs parallel sub-agents for structure analysis, usage analysis, and test coverage before writing a single line.

```bash
# Single file — extract utility methods
/developer-kit:devkit.refactor --scope=file Extract utility methods from UserService

# Java module — repository pattern
/developer-kit:devkit.refactor --lang=spring --scope=module Refactor repository layer to use specification pattern

# TypeScript — async/await migration
/developer-kit:devkit.refactor --lang=typescript Convert callbacks to async/await in data layer

# React — shared hooks extraction
/developer-kit:devkit.refactor --lang=react Extract shared hooks from dashboard components

# AWS — monolithic CloudFormation to nested stacks
/developer-kit:devkit.refactor --lang=aws Refactor monolithic CloudFormation template into nested stacks

# Python — repository pattern
/developer-kit:devkit.refactor --lang=python Refactor data access layer to use repository pattern
```

---

## `/devkit.fix-debugging` — Root Cause Analysis and Bug Fix

Systematic debugging workflow: trace root cause, design a minimal surgical fix, implement it, and verify. Dispatches language-specific sub-agents matching the `--lang` parameter.

```bash
# Paste an error message directly
/developer-kit:devkit.fix-debugging NullPointerException in UserService.findById line 42

# With language context
/developer-kit:devkit.fix-debugging --lang=spring Fix transaction rollback not working in OrderService

# TypeScript type error
/developer-kit:devkit.fix-debugging --lang=typescript Type 'undefined' is not assignable to type 'User' in AuthGuard

# React rendering bug
/developer-kit:devkit.fix-debugging --lang=react Dashboard re-renders infinitely when filter changes

# Python async bug
/developer-kit:devkit.fix-debugging --lang=python RuntimeError: Event loop is closed in async task handler
```

---

## `/devkit.github.create-pr` — Create a GitHub Pull Request

Validates git state, creates a branch if needed, commits staged changes, then generates a comprehensive PR description using `gh` CLI. Supports multilingual PR bodies.

```bash
# Auto-generate title from commits
/developer-kit:devkit.github.create-pr

# With explicit title and target branch
/developer-kit:devkit.github.create-pr "Add JWT authentication" main

# Italian PR description
/developer-kit:devkit.github.create-pr "Aggiungi autenticazione JWT" main it

# Supported languages: en, it, es, fr, de
```

---

## `constitution` Skill — Project Architectural DNA

Creates and manages two shared documents: `docs/specs/architecture.md` (approved tech stack, AI guardrails, security constraints, CWE mappings) and `docs/specs/ontology.md` (domain glossary / Ubiquitous Language). Run before the first brainstorm session on a new project.

```bash
# New project setup — create both files interactively
/developer-kit-specs:constitution create

# Validate a spec against architecture rules and ontology
/developer-kit-specs:constitution check --target=docs/specs/001/2026-05-10--user-auth.md

# Update security constraints section only
/developer-kit-specs:constitution update --file=architecture --section=security

# Review current constitution
/developer-kit-specs:constitution show
```

---

## `learn` Skill — Autonomous Project Pattern Discovery

Two-agent orchestrator + analyst that scans the codebase, discovers coding conventions, architectural patterns, and team rules, then writes them as `.claude/rules/` files with correct `globs:` frontmatter so they auto-activate for matching files.

```bash
# Trigger via natural language
"learn from this project"
"extract project rules"
"discover patterns"
"generate project rules"

# After running, rules are created at:
# .claude/rules/naming-conventions.md
# .claude/rules/project-structure.md
# .claude/rules/language-best-practices.md
# .claude/rules/error-handling.md

# Example generated rule file
# ---
# globs: ["**/*.java"]
# ---
# Always use constructor injection. Never use @Autowired field injection.
# Follow naming convention: DTOs end with Dto, services end with Service.
```

---

## Path-Scoped Rules — Auto-Activation by File Pattern

Rules in `.claude/rules/` activate automatically when Claude opens a matching file. Each rule file has a `globs:` YAML frontmatter header. Developer Kit ships pre-built rule sets for Java, TypeScript, Python, and PHP.

```yaml
# .claude/rules/java-naming-conventions.md
---
globs: ["**/*.java"]
---
# Java Naming Conventions

- Class names: PascalCase (e.g., UserService, OrderRepository)
- Methods: camelCase (e.g., findById, createUser)
- Constants: UPPER_SNAKE_CASE
- Always use constructor injection. Never use @Autowired on fields.
- DTOs must end with `Dto` suffix. Entities must not expose setters.
```

```yaml
# .claude/rules/typescript-conventions.md
---
globs: ["**/*.ts", "**/*.tsx"]
---
# TypeScript Conventions

- Use strict mode. No implicit any.
- Prefer interface over type for object shapes.
- Use Zod for runtime validation at API boundaries.
- NestJS: use constructor injection, never property injection.
```

```bash
# Install plugin rules into your project
make copy-rules PLUGIN=developer-kit-typescript
# Copies 17 TypeScript rules covering NestJS, React, Drizzle ORM, Tailwind, i18n
```

---

## Plugin Manifest Format (`plugin.json`)

Each plugin declares its components in a `.claude-plugin/plugin.json` manifest. This drives marketplace discovery, installation, and validation.

```json
{
  "name": "developer-kit",
  "version": "2.8.2",
  "description": "Core agents and commands required by all Developer Kit plugins",
  "author": {
    "name": "Giuseppe Trisciuoglio",
    "email": "giuseppe.trisciuoglio@gmail.com"
  },
  "agents": [
    "./agents/general-code-explorer.md",
    "./agents/general-code-reviewer.md",
    "./agents/general-refactor-expert.md",
    "./agents/general-software-architect.md",
    "./agents/general-debugger.md",
    "./agents/document-generator-expert.md"
  ],
  "commands": [
    "./commands/devkit.refactor.md",
    "./commands/devkit.feature-development.md",
    "./commands/devkit.fix-debugging.md",
    "./commands/documentation/devkit.generate-document.md",
    "./commands/devkit.github.create-pr.md",
    "./commands/devkit.github.review-pr.md"
  ],
  "skills": [
    "./skills/adr-drafting",
    "./skills/memory-md-management",
    "./skills/docs-updater",
    "./skills/drawio-logical-diagrams",
    "./skills/github-issue-workflow",
    "./skills/learn",
    "./skills/bug-fix-brief"
  ]
}
```

---

## Marketplace Registry (`marketplace.json`)

The root marketplace file lists every plugin with its source path and version. Used by the Makefile installer and Claude Code plugin system.

```json
{
  "name": "developer-kit",
  "version": "2.8.2",
  "plugins": [
    { "name": "developer-kit",       "source": "./plugins/developer-kit-core",       "version": "2.8.0" },
    { "name": "developer-kit-specs", "source": "./plugins/developer-kit-specs",      "version": "2.8.0" },
    { "name": "developer-kit-java",  "source": "./plugins/developer-kit-java",       "version": "2.8.0" },
    { "name": "developer-kit-typescript", "source": "./plugins/developer-kit-typescript", "version": "2.8.0" },
    { "name": "developer-kit-python","source": "./plugins/developer-kit-python",     "version": "2.8.0" },
    { "name": "developer-kit-php",   "source": "./plugins/developer-kit-php",        "version": "2.8.0" },
    { "name": "developer-kit-aws",   "source": "./plugins/developer-kit-aws",        "version": "2.8.0" },
    { "name": "developer-kit-ai",    "source": "./plugins/developer-kit-ai",         "version": "2.8.0" },
    { "name": "developer-kit-devops","source": "./plugins/developer-kit-devops",     "version": "2.8.0" },
    { "name": "developer-kit-tools", "source": "./plugins/developer-kit-tools",      "version": "2.8.0" },
    { "name": "github-spec-kit",     "source": "./plugins/github-spec-kit",          "version": "2.8.0" }
  ]
}
```

---

## Skill File Format (`SKILL.md`)

Skills are Markdown files with a YAML frontmatter header. The `name`, `description`, and `allowed-tools` fields are required. The body contains the full instructional prompt for the AI.

```markdown
---
name: spring-boot-crud-patterns
description: Generates complete Spring Boot CRUD modules with REST API, service layer,
  repository, DTOs, validation, and unit tests. Use when building a new entity endpoint.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
---

# Spring Boot CRUD Patterns

## When to Use
Use this skill to generate a complete CRUD module for a new entity.

## Instructions
1. Identify entity name and fields from user request
2. Generate: Entity, Repository, Service, Controller, DTOs, MapStruct mapper
3. Add Bean Validation annotations (@NotNull, @Size, etc.)
4. Generate JUnit 5 + Mockito unit tests for service and controller layers
5. Follow RESTful conventions: GET /entities, POST /entities, PUT /entities/{id}, DELETE /entities/{id}

## Example Output Structure
src/main/java/com/example/
├── entity/User.java
├── repository/UserRepository.java
├── service/UserService.java
├── controller/UserController.java
└── dto/UserDto.java, CreateUserRequest.java, UpdateUserRequest.java
```

---

## Available Plugin Summary

| Plugin | Key Skills & Agents |
|--------|---------------------|
| `developer-kit-core` | general-code-explorer, general-code-reviewer, general-software-architect, general-debugger, adr-drafting, learn, drawio-logical-diagrams |
| `developer-kit-specs` | constitution, knowledge-graph, ralph-loop, task-quality-kpi, create-pr-from-spec |
| `developer-kit-java` | spring-boot-crud-patterns, spring-boot-security-jwt, spring-data-jpa, langchain4j-*, aws-sdk-java-v2-*, graalvm-native-image, wiremock, 20+ JUnit skills |
| `developer-kit-typescript` | nestjs-*, nextjs-*, react-*, drizzle-orm-patterns, zod-validation-utilities, nx-monorepo, turborepo-monorepo, better-auth |
| `developer-kit-python` | python-code-review-expert, python-refactor-expert, python-security-expert, python-software-architect-expert |
| `developer-kit-php` | php-code-review-expert, wordpress-development-expert, clean-architecture, wordpress-sage-theme |
| `developer-kit-aws` | aws-cloudformation-* (14 services), aws-cli-beast, aws-cost-optimization, aws-sam-bootstrap, aws-drawio-architecture-diagrams |
| `developer-kit-ai` | prompt-engineering, rag, chunking-strategy |
| `developer-kit-devops` | general-docker-expert, github-actions-pipeline-expert |
| `developer-kit-tools` | gemini, codex, copilot-cli, notebooklm, sonarqube-mcp, qwen-coder |

---

Developer Kit's primary use cases span three scenarios: (1) **greenfield projects** where teams run `constitution create` to define their stack and guardrails, then use the full SDD loop (`brainstorm` → `spec-to-tasks` → `task-tdd` → `task-implementation` → `task-review` → `spec-sync-with-code`) to produce well-tested, specification-backed features; (2) **ongoing maintenance** where individual commands like `/devkit.fix-debugging`, `/devkit.refactor`, and `/devkit.github.create-pr` accelerate isolated tasks without requiring a full SDD setup; and (3) **knowledge transfer** where the `learn` skill auto-generates project-specific `.claude/rules/` files so new contributors immediately benefit from codified conventions.

Integration patterns fall into two modes. **Interactive mode** relies on Claude Code slash commands that pause at mandatory `[GATE]` checkpoints for user approval — ideal for design decisions and compatibility choices during feature development and refactoring. **Automated mode** uses the `ralph_loop.py` Python orchestrator (schedulable via Claude Code's `/loop` command) to drive the complete per-task SDD cycle unattended, managing state in `fix_plan.json` and supporting multi-agent delegation to Claude, Codex, Gemini, GitHub Copilot CLI, and others. Both modes share the same skill library and agent roster, making it straightforward to start interactively and switch to automation once the specification and task list are finalized.