mirror of
https://github.com/giuseppe-trisciuoglio/developer-kit.git
synced 2026-09-14 18:22:07 +08:00
docs(specs): updated docs and minor fix on skill
This commit is contained in:
Giuseppe Trisciuoglio
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "Modular marketplace for developer kit plugins",
|
||||
"owner": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -39,3 +39,23 @@ jobs:
|
||||
run: |
|
||||
echo "🔍 Running MCP-Scan security check on all skills..."
|
||||
python .skills-validator-check/validators/mcp_scan_checker.py --all -v
|
||||
|
||||
- name: Run Trust Hub Security Check (PR only)
|
||||
if: github.event_name == 'pull_request'
|
||||
env:
|
||||
GITHUB_REPOSITORY: ${{ github.repository }}
|
||||
GITHUB_HEAD_REF: ${{ github.head_ref }}
|
||||
GITHUB_BASE_REF: ${{ github.base_ref }}
|
||||
run: |
|
||||
echo "🔐 Running Trust Hub security check on changed skills..."
|
||||
python .skills-validator-check/validators/security_checker.py
|
||||
|
||||
- name: Run Trust Hub Security Check (push to main/develop)
|
||||
if: github.event_name == 'push'
|
||||
env:
|
||||
GITHUB_REPOSITORY: ${{ github.repository }}
|
||||
GITHUB_HEAD_REF: ${{ github.ref_name }}
|
||||
GITHUB_BASE_REF: ${{ github.event.before }}
|
||||
run: |
|
||||
echo "🔐 Running Trust Hub security check..."
|
||||
python .skills-validator-check/validators/security_checker.py
|
||||
|
||||
@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
- **New Plugin: developer-kit-specs** — Specifications-Driven Development (SDD) workflow:
|
||||
- 10 commands for the complete SDD lifecycle: `brainstorm`, `quick-spec`, `spec-to-tasks`, `task-manage`, `task-implementation`, `task-tdd`, `task-review`, `spec-sync-with-code`, `spec-sync-context`, `spec-quality-check`
|
||||
- 2 agents: `evaluator-agent` (KPI-driven quality evaluation), `session-tracking-agent` (audit trail)
|
||||
- 4 skills: `knowledge-graph`, `ralph-loop`, `specs-code-cleanup`, `task-quality-kpi`
|
||||
- TDD integration with RED/GREEN phases and language-specific test templates (8 languages)
|
||||
- Ralph Loop automation for multi-agent task execution (claude, codex, copilot, gemini, glm4, kimi, minimax)
|
||||
- KPI evaluation framework with weighted scoring (Spec Compliance 30%, Code Quality 25%, Test Coverage 25%, Contract Fulfillment 20%)
|
||||
- Drift Guard for real-time spec-to-implementation monitoring
|
||||
- Automatic hooks: task auto-status, KPI analysis, drift tracking, session audit trail
|
||||
- Language support: Java/Spring, TypeScript/NestJS/React, Python, PHP, and general
|
||||
|
||||
## [2.7.2] - 2026-03-24
|
||||
|
||||
### Changed
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-ai",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "AI/ML capabilities including prompt engineering, RAG, and chunking strategies",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-aws",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "AWS infrastructure and CloudFormation expertise",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "Core agents and commands required by all Developer Kit plugins",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-devops",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "DevOps and containerization expertise",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-java",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "Comprehensive Java development toolkit with Spring Boot, testing, LangChain4J, and AWS integration",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-php",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "PHP and WordPress development capabilities",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-project-management",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "Project management and workflow commands",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-python",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "Python development capabilities",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-specs",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "Specifications-driven development workflow for transforming ideas into functional specifications and executable tasks",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
@@ -26,7 +26,8 @@
|
||||
"./commands/specs.spec-sync-with-code.md",
|
||||
"./commands/specs.spec-sync-context.md",
|
||||
"./commands/specs.quick-spec.md",
|
||||
"./commands/specs.spec-quality-check.md"
|
||||
"./commands/specs.spec-quality-check.md",
|
||||
"./commands/specs.task-tdd.md"
|
||||
],
|
||||
"agents": [
|
||||
"./agents/evaluator-agent.md",
|
||||
@@ -35,6 +36,7 @@
|
||||
"skills": [
|
||||
"./skills/knowledge-graph",
|
||||
"./skills/ralph-loop",
|
||||
"./skills/specs-code-cleanup"
|
||||
"./skills/specs-code-cleanup",
|
||||
"./skills/task-quality-kpi"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -7,6 +7,8 @@ model: sonnet
|
||||
|
||||
# Evaluator Agent
|
||||
|
||||
## Role
|
||||
|
||||
You are an **objective quality evaluator** for software development tasks. Your role is to provide quantitative, evidence-based assessments using pre-calculated KPI data.
|
||||
|
||||
## Core Principle
|
||||
|
||||
@@ -0,0 +1,579 @@
|
||||
# Commands Reference
|
||||
|
||||
Complete reference for all SDD commands with arguments, options, and real-world examples.
|
||||
|
||||
---
|
||||
|
||||
## `/specs:brainstorm`
|
||||
|
||||
Transform ideas into full functional specifications through guided brainstorming.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:brainstorm [idea-description]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `idea-description` | Yes | Natural language description of the feature to build |
|
||||
|
||||
### When to Use
|
||||
|
||||
- New features with complex requirements
|
||||
- Features affecting 5+ files
|
||||
- Requirements that need clarification
|
||||
- Features requiring architectural decisions
|
||||
- Any feature where the "right approach" isn't immediately clear
|
||||
|
||||
### Process (9 Phases)
|
||||
|
||||
| Phase | Name | Description |
|
||||
|-------|------|-------------|
|
||||
| 1 | Context Discovery | Explore project structure, dependencies, existing patterns |
|
||||
| 1.5 | Complexity Assessment | Estimate task count; split if >15 tasks |
|
||||
| 2 | Idea Refinement | Ask up to 3 clarifying questions |
|
||||
| 3 | Functional Approach | Present 2-3 approaches (WHAT, not HOW) |
|
||||
| 4 | Codebase Exploration | Examine integration points |
|
||||
| 5 | Spec Presentation | Validate sections incrementally |
|
||||
| 6 | Spec Generation | Create full specification document |
|
||||
| 7 | Quality Review | Verify completeness |
|
||||
| 8 | Next Steps | Recommend follow-up commands |
|
||||
| 9 | Summary | List outputs and file locations |
|
||||
|
||||
### Output
|
||||
|
||||
```
|
||||
docs/specs/[ID-feature]/
|
||||
├── YYYY-MM-DD--feature-name.md # Main specification
|
||||
├── user-request.md # Original request
|
||||
├── brainstorming-notes.md # Session context
|
||||
└── decision-log.md # Decision audit trail
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# New feature with complex requirements
|
||||
/specs:brainstorm Add a multi-tenant SaaS billing system with subscription management,
|
||||
usage metering, invoice generation, Stripe integration, and prorated upgrades
|
||||
|
||||
# API design
|
||||
/specs:brainstorm Design a RESTful API for an e-commerce platform with product catalog,
|
||||
shopping cart, checkout flow, and order management
|
||||
|
||||
# Infrastructure feature
|
||||
/specs:brainstorm Add real-time WebSocket notifications for order status changes
|
||||
with delivery guarantees and connection management
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:quick-spec`
|
||||
|
||||
Create a lightweight specification for well-understood changes.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:quick-spec [description]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `description` | Yes | Clear description of the change |
|
||||
|
||||
### When to Use
|
||||
|
||||
- Bug fixes with known solutions
|
||||
- Small features affecting 1-3 files
|
||||
- Changes with clear acceptance criteria (≤4)
|
||||
- Well-understood technical context
|
||||
|
||||
### Process (4 Phases)
|
||||
|
||||
| Phase | Name | Description |
|
||||
|-------|------|-------------|
|
||||
| 1 | Quick Context | Check git log, identify affected files |
|
||||
| 2 | Problem + Solution Checkpoint | Define and validate approach |
|
||||
| 3 | Generate Minimal Spec | Create lightweight specification |
|
||||
| 4 | Next Step Recommendation | Suggest implementation path |
|
||||
|
||||
### Output
|
||||
|
||||
```
|
||||
docs/specs/[ID-feature]/
|
||||
├── YYYY-MM-DD--feature-name.md # Minimal specification
|
||||
└── decision-log.md # Decision record
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Bug fix
|
||||
/specs:quick-spec Fix the NullPointerException in UserService.updateProfile()
|
||||
when the email field is null
|
||||
|
||||
# Small feature
|
||||
/specs:quick-spec Add pagination to the /api/v1/orders endpoint with
|
||||
configurable page size and sorting
|
||||
|
||||
# Performance improvement
|
||||
/specs:quick-spec Optimize the dashboard query that loads in 8+ seconds
|
||||
by adding database indexes and caching the aggregation results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:spec-to-tasks`
|
||||
|
||||
Convert a functional specification into executable task files.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:spec-to-tasks [--lang=language] [spec-folder]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--lang` | Recommended | Target language: `java`, `spring`, `typescript`, `nestjs`, `react`, `python`, `php`, `general` |
|
||||
| `spec-folder` | Yes | Path to the specification directory |
|
||||
|
||||
### Process (7 Phases)
|
||||
|
||||
| Phase | Name | Description |
|
||||
|-------|------|-------------|
|
||||
| 1 | Specification Analysis | Read and understand the spec |
|
||||
| 1.5 | Architecture & Ontology | Ensure technical foundation exists |
|
||||
| 2 | Requirement Extraction | Organize requirements, assign REQ-IDs |
|
||||
| 2.5 | Knowledge Graph | Load or create cached codebase analysis |
|
||||
| 3 | Codebase Analysis | Language-specific exploration |
|
||||
| 3.5 | Update Knowledge Graph | Persist discoveries |
|
||||
| 4 | Task Decomposition | Break into atomic tasks |
|
||||
| 5 | Task Generation | Create task files and index |
|
||||
| 5.5 | Traceability Matrix | Map requirements to tasks |
|
||||
| 6 | Review and Confirmation | Present for validation |
|
||||
| 7 | Summary | List outputs |
|
||||
|
||||
### Task Limit
|
||||
|
||||
Maximum 15 implementation tasks per specification. If exceeded, the command rejects and recommends splitting.
|
||||
|
||||
### Output
|
||||
|
||||
```
|
||||
docs/specs/[ID-feature]/
|
||||
├── YYYY-MM-DD--feature-name--tasks.md # Task index
|
||||
├── knowledge-graph.json # Codebase analysis cache
|
||||
├── traceability-matrix.md # Requirements mapping
|
||||
└── tasks/
|
||||
├── TASK-001.md
|
||||
├── TASK-002.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Spring Boot project
|
||||
/specs:spec-to-tasks --lang=spring docs/specs/001-user-auth/
|
||||
|
||||
# NestJS project
|
||||
/specs:spec-to-tasks --lang=nestjs docs/specs/002-notification-system/
|
||||
|
||||
# Python project
|
||||
/specs:spec-to-tasks --lang=python docs/specs/003-data-pipeline/
|
||||
|
||||
# General / multi-language
|
||||
/specs:spec-to-tasks --lang=general docs/specs/004-api-design/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:task-manage`
|
||||
|
||||
Manage tasks after generation — add, split, update, list.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:task-manage --action=action [options]
|
||||
```
|
||||
|
||||
### Actions
|
||||
|
||||
| Action | Description | Required Options |
|
||||
|--------|-------------|-----------------|
|
||||
| `list` | Display all tasks with status and complexity | `--spec` |
|
||||
| `add` | Create a new task | `--spec` |
|
||||
| `split` | Split a complex task into subtasks | `--task` |
|
||||
| `mark-optional` | Mark task as not required | `--task` |
|
||||
| `mark-required` | Mark optional task as required | `--task` |
|
||||
| `update` | Modify task details | `--task` |
|
||||
| `regenerate-index` | Recreate task index from files | `--spec` |
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--spec="path"` | Specification directory |
|
||||
| `--task="path"` | Path to specific task file |
|
||||
|
||||
### Task Complexity Scoring
|
||||
|
||||
```
|
||||
COMPLEXITY = (Files × 10) + (Acceptance Criteria × 5) +
|
||||
(Independent Components × 25) + (Design Decisions × 10) +
|
||||
(Integration Points × 15) + (External Dependencies × 20)
|
||||
```
|
||||
|
||||
Tasks with complexity ≥50 are candidates for splitting.
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# List all tasks
|
||||
/specs:task-manage --action=list --spec="docs/specs/001-user-auth/"
|
||||
|
||||
# Split a complex task
|
||||
/specs:task-manage --action=split --task="docs/specs/001-user-auth/tasks/TASK-003.md"
|
||||
# Result: TASK-003 → TASK-003A + TASK-003B
|
||||
|
||||
# Add a new task
|
||||
/specs:task-manage --action=add --spec="docs/specs/001-user-auth/"
|
||||
# Claude will ask for task details interactively
|
||||
|
||||
# Mark a task as optional (won't block completion)
|
||||
/specs:task-manage --action=mark-optional --task="docs/specs/001-user-auth/tasks/TASK-008.md"
|
||||
|
||||
# Regenerate task index after manual changes
|
||||
/specs:task-manage --action=regenerate-index --spec="docs/specs/001-user-auth/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:task-implementation`
|
||||
|
||||
Implement a specific task from a task list.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:task-implementation [--lang=language] --task="task-file"
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--lang` | Recommended | Target language/framework |
|
||||
| `--task` | **Yes** | Path to task file |
|
||||
|
||||
### Process (12 Steps)
|
||||
|
||||
| Step | Name | Gate |
|
||||
|------|------|------|
|
||||
| T-1 | Task identification | Valid task file |
|
||||
| T-2 | Git state check | Clean working tree |
|
||||
| T-3 | Dependency check | All deps completed |
|
||||
| T-3.5 | Knowledge Graph validation | Components exist |
|
||||
| T-3.6 | Contract validation | Provides/expects compatible |
|
||||
| T-3.7 | Review feedback check | For Ralph Loop iterations |
|
||||
| T-4 | Implementation | — |
|
||||
| T-5 | Verification | Tests pass |
|
||||
| T-6 | Task completion | Status updated |
|
||||
| T-6.5 | Knowledge Graph update | Context persisted |
|
||||
| T-6.6 | Spec deviation check | Drift reported |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Spring Boot task
|
||||
/specs:task-implementation --lang=spring \
|
||||
--task="docs/specs/001-user-auth/tasks/TASK-001.md"
|
||||
|
||||
# NestJS task
|
||||
/specs:task-implementation --lang=nestjs \
|
||||
--task="docs/specs/002-notification/tasks/TASK-003.md"
|
||||
|
||||
# React task
|
||||
/specs:task-implementation --lang=react \
|
||||
--task="docs/specs/003-dashboard/tasks/TASK-002.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:task-tdd`
|
||||
|
||||
Generate failing tests (TDD RED phase) before implementation.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:task-tdd [--lang=language] --task="task-file"
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--lang` | Recommended | Target language/framework |
|
||||
| `--task` | **Yes** | Path to task file |
|
||||
|
||||
### Supported Test Frameworks
|
||||
|
||||
| Language | Framework | Template |
|
||||
|----------|-----------|----------|
|
||||
| Spring | JUnit 5 + Mockito | `spring-test-template.java` |
|
||||
| Java | JUnit 5 | `java-test-template.java` |
|
||||
| NestJS | Jest | `nestjs-test-template.spec.ts` |
|
||||
| TypeScript | Jest / Mocha | `typescript-test-template.spec.ts` |
|
||||
| React | Jest + React Testing Library | `react-test-template.test.tsx` |
|
||||
| Node.js | Jest | `nodejs-test-template.test.ts` |
|
||||
| Python | pytest | `python-test-template.py` |
|
||||
| PHP | PHPUnit | `php-test-template.php` |
|
||||
|
||||
### TDD Workflow
|
||||
|
||||
```
|
||||
RED phase: /specs:task-tdd → Generate failing tests
|
||||
GREEN phase: /specs:task-implementation → Make tests pass
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Spring Boot — RED phase
|
||||
/specs:task-tdd --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-002.md"
|
||||
# Creates: src/test/java/.../JwtTokenServiceTest.java (all tests fail)
|
||||
|
||||
# Then GREEN phase
|
||||
/specs:task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-002.md"
|
||||
# Creates: src/main/java/.../JwtTokenService.java (all tests pass)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:task-review`
|
||||
|
||||
Verify that an implemented task meets specifications and passes code review.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:task-review [--lang=language] [--task="task-file"]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--lang` | Recommended | Target language/framework |
|
||||
| `--task` | Yes | Path to task file |
|
||||
|
||||
### Review Dimensions
|
||||
|
||||
| Dimension | What It Checks |
|
||||
|-----------|---------------|
|
||||
| Implementation | Code matches task description |
|
||||
| Acceptance Criteria | All criteria checkboxes ✅ |
|
||||
| Spec Compliance | Alignment with functional specification |
|
||||
| Code Quality | Language-specific patterns, security, conventions |
|
||||
|
||||
### Review Outcomes
|
||||
|
||||
| Status | Condition |
|
||||
|--------|-----------|
|
||||
| **PASSED** | All criteria ✅, all DoD ✅, no critical issues |
|
||||
| **FAILED** | Any criterion ❌, or critical code issues |
|
||||
|
||||
### Output
|
||||
|
||||
`TASK-XXX--review.md` — Detailed review report with findings per dimension.
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Spring Boot review
|
||||
/specs:task-review --lang=spring docs/specs/001-user-auth/tasks/TASK-001.md
|
||||
|
||||
# NestJS review
|
||||
/specs:task-review --lang=nestjs docs/specs/002-notification/tasks/TASK-003.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/developer-kit-specs:specs-code-cleanup`
|
||||
|
||||
Professional code cleanup after task review approval.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/developer-kit-specs:specs-code-cleanup --lang=language --task="task-file"
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--lang` | Yes | Target language/framework |
|
||||
| `--task` | Yes | Path to task file (must be in `reviewed` status) |
|
||||
|
||||
### Cleanup Process (8 Phases)
|
||||
|
||||
1. **Task verification** — Confirm reviewed status
|
||||
2. **Identify files** — From review report and task provides
|
||||
3. **Remove debug artifacts** — `console.log`, `System.out.println`, temporary comments
|
||||
4. **Optimize imports** — Language-specific import cleanup
|
||||
5. **Code readability** — Run formatters
|
||||
6. **Documentation check** — Headers, API docs
|
||||
7. **Final verification** — Run tests, verify no logic changes
|
||||
8. **Task completion** — Update status to `completed`
|
||||
|
||||
### Language-Specific Formatters
|
||||
|
||||
| Language | Formatter Command |
|
||||
|----------|-------------------|
|
||||
| Spring | `./mvnw spotless:apply` |
|
||||
| TypeScript | `npm run lint:fix && npm run format` |
|
||||
| Python | `black .` |
|
||||
| PHP | `php-cs-fixer fix` |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
/developer-kit-specs:specs-code-cleanup --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md"
|
||||
/developer-kit-specs:specs-code-cleanup --lang=nestjs --task="docs/specs/002-notification/tasks/TASK-003.md"
|
||||
/developer-kit-specs:specs-code-cleanup --lang=python --task="docs/specs/003-pipeline/tasks/TASK-002.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:spec-sync-with-code`
|
||||
|
||||
Synchronize functional specification with actual implementation state.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:spec-sync-with-code [--spec="spec-folder"] [--after-task="TASK-XXX"]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--spec` | Yes | Specification directory |
|
||||
| `--after-task` | No | Sync after specific task completion |
|
||||
|
||||
### Deviation Types
|
||||
|
||||
| Type | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| **Scope Expansion** | Features added beyond spec | Added refresh token support |
|
||||
| **Requirement Refinement** | Clarifications or corrections | Changed password length to 12 |
|
||||
| **Scope Reduction** | Features dropped or deferred | Deferred 2FA to next spec |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Full sync
|
||||
/specs:spec-sync-with-code docs/specs/001-user-auth/
|
||||
|
||||
# Sync after specific task
|
||||
/specs:spec-sync-with-code --spec="docs/specs/001-user-auth/" --after-task="TASK-003"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:spec-sync-context`
|
||||
|
||||
Synchronize Knowledge Graph, tasks, and codebase state.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:spec-sync-context [--spec="spec-folder"] [--update-kg-only] [--task="task-file"] [--dry-run]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--spec` | Yes | Specification directory |
|
||||
| `--update-kg-only` | No | Only update Knowledge Graph, skip task enrichment |
|
||||
| `--task` | No | Sync context for specific task |
|
||||
| `--dry-run` | No | Preview changes without writing |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Full context sync
|
||||
/specs:spec-sync-context --spec="docs/specs/001-user-auth/"
|
||||
|
||||
# Preview only
|
||||
/specs:spec-sync-context --spec="docs/specs/001-user-auth/" --dry-run
|
||||
|
||||
# Update Knowledge Graph only
|
||||
/specs:spec-sync-context --spec="docs/specs/001-user-auth/" --update-kg-only
|
||||
|
||||
# Sync after specific task
|
||||
/specs:spec-sync-context --spec="docs/specs/001-user-auth/" --task="TASK-003"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `/specs:spec-quality-check`
|
||||
|
||||
Interactive specification quality assessment.
|
||||
|
||||
### Syntax
|
||||
|
||||
```
|
||||
/specs:spec-quality-check [--spec="spec-folder"]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
| Argument | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `--spec` | Yes | Specification directory |
|
||||
|
||||
### Quality Scan Taxonomy
|
||||
|
||||
The scan covers 12 areas:
|
||||
|
||||
1. Completeness and Clarity
|
||||
2. Domain and Data Model
|
||||
3. Interaction and UX Flow
|
||||
4. Non-Functional Quality (performance, scalability, reliability)
|
||||
5. Security and Compliance
|
||||
6. Integrations and Dependencies
|
||||
7. Edge Cases and Error Handling
|
||||
8. Constraints and Trade-offs
|
||||
9. Terminology and Consistency
|
||||
10. Completion Criteria
|
||||
11. Placeholders and TODOs
|
||||
12. Architecture/Ontology Alignment
|
||||
|
||||
### Process
|
||||
|
||||
Claude asks up to 5 focused questions, one at a time. Your answers are integrated directly into the specification.
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Check specification quality
|
||||
/specs:spec-quality-check --spec="docs/specs/001-user-auth/"
|
||||
|
||||
# Can be run multiple times (idempotent)
|
||||
/specs:spec-quality-check --spec="docs/specs/001-user-auth/"
|
||||
```
|
||||
@@ -0,0 +1,192 @@
|
||||
# Getting Started — Specification-Driven Development
|
||||
|
||||
This guide walks you through the core concepts of SDD and gets you productive in minutes.
|
||||
|
||||
## What is SDD?
|
||||
|
||||
Specification-Driven Development (SDD) is a workflow where you define **WHAT** you want to build before writing any code. The specification becomes a contract between your idea and the implementation, enforced through automated quality gates.
|
||||
|
||||
```
|
||||
Idea → Specification → Tasks → Implementation → Review → Cleanup → Done
|
||||
(brainstorm) (spec-to-tasks) (task-review) (code-cleanup)
|
||||
```
|
||||
|
||||
**Why SDD?**
|
||||
- **Eliminates ambiguity**: Every feature is defined functionally before coding starts
|
||||
- **Traceability**: Every line of code traces back to a requirement
|
||||
- **Quality gates**: Automated review ensures nothing is missed
|
||||
- **Living docs**: Specifications evolve alongside the codebase
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Claude Code** installed and configured
|
||||
- **Python 3.11+** (for hook scripts and Ralph Loop automation)
|
||||
- **developer-kit-core** plugin installed (provides general-purpose agents)
|
||||
- A **git repository** with at least one commit
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Install the plugin from marketplace
|
||||
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
|
||||
|
||||
# Or install from local directory
|
||||
/plugin install /path/to/developer-kit/plugins/developer-kit-specs
|
||||
```
|
||||
|
||||
Verify installation:
|
||||
|
||||
```
|
||||
/help
|
||||
# You should see /specs:brainstorm, /specs:spec-to-tasks, etc.
|
||||
```
|
||||
|
||||
## Your First Specification
|
||||
|
||||
Let's build a real feature: **user authentication with JWT tokens** for a Spring Boot application.
|
||||
|
||||
### Step 1: Brainstorm the Idea
|
||||
|
||||
```
|
||||
/specs:brainstorm Add user authentication with JWT tokens for a Spring Boot REST API
|
||||
```
|
||||
|
||||
Claude will guide you through a 9-phase process:
|
||||
|
||||
1. **Context Discovery** — Analyzes your project structure, existing code patterns, dependencies
|
||||
2. **Complexity Assessment** — Checks if the idea should be split into multiple specifications
|
||||
3. **Idea Refinement** — Asks up to 3 clarifying questions (e.g., "Should refresh tokens be supported?")
|
||||
4. **Functional Approach Exploration** — Presents 2-3 approaches, focusing on WHAT not HOW
|
||||
5. **Contextual Codebase Exploration** — Examines existing security config, user entities, etc.
|
||||
6. **Specification Presentation** — Shows the functional specification section by section
|
||||
7. **Specification Generation** — Creates the full spec document
|
||||
8. **Quality Review** — Verifies completeness and consistency
|
||||
9. **Summary** — Lists outputs and recommended next steps
|
||||
|
||||
**Output files created:**
|
||||
```
|
||||
docs/specs/001-user-auth/
|
||||
├── 2026-04-10--user-auth.md # Main functional specification
|
||||
├── user-request.md # Your original request
|
||||
├── brainstorming-notes.md # Session context and decisions
|
||||
└── decision-log.md # Decision audit trail
|
||||
```
|
||||
|
||||
The specification is technology-agnostic. It describes behaviors, not implementation details.
|
||||
|
||||
### Step 2: Convert to Tasks
|
||||
|
||||
```
|
||||
/specs:spec-to-tasks --lang=spring docs/specs/001-user-auth/
|
||||
```
|
||||
|
||||
Claude analyzes your specification and generates executable tasks:
|
||||
|
||||
1. **Reads the specification** and extracts functional requirements
|
||||
2. **Explores your codebase** to understand existing patterns (Spring Security, User entities, etc.)
|
||||
3. **Breaks requirements into tasks** — atomic, testable units with clear acceptance criteria
|
||||
4. **Generates a traceability matrix** mapping requirements to tasks
|
||||
|
||||
**Output files created:**
|
||||
```
|
||||
docs/specs/001-user-auth/
|
||||
├── 2026-04-10--user-auth--tasks.md # Task index
|
||||
├── knowledge-graph.json # Cached codebase analysis
|
||||
├── traceability-matrix.md # Requirements → Tasks mapping
|
||||
└── tasks/
|
||||
├── TASK-001.md # Create User entity and repository
|
||||
├── TASK-002.md # Implement JWT token service
|
||||
├── TASK-003.md # Create authentication endpoints
|
||||
├── TASK-004.md # Add Spring Security configuration
|
||||
├── TASK-005.md # Write e2e tests for auth flow
|
||||
└── TASK-006.md # Code cleanup and finalization
|
||||
```
|
||||
|
||||
Each task file contains:
|
||||
- **Frontmatter**: ID, title, status, dependencies, provides/expects contracts
|
||||
- **Description**: What to implement
|
||||
- **Acceptance Criteria**: Checkboxes for verification
|
||||
- **Definition of Done**: Quality checklist
|
||||
|
||||
### Step 3: Implement a Task
|
||||
|
||||
```
|
||||
/specs:task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md"
|
||||
```
|
||||
|
||||
Claude follows a structured 12-step process:
|
||||
|
||||
1. **Validates prerequisites** — Checks git state, task dependencies, contracts
|
||||
2. **Implements the code** — Writes production code following your project conventions
|
||||
3. **Runs verification** — Executes tests, validates acceptance criteria
|
||||
4. **Updates task status** — Automatically marks `in_progress` → `implemented`
|
||||
|
||||
**Hooks fire automatically:**
|
||||
- `task-auto-status.py` updates the task frontmatter based on checkbox changes
|
||||
- `task-kpi-analyzer.py` calculates quality KPIs and saves them to `TASK-001--kpi.json`
|
||||
|
||||
### Step 4: Review the Implementation
|
||||
|
||||
```
|
||||
/specs:task-review --lang=spring docs/specs/001-user-auth/tasks/TASK-001.md
|
||||
```
|
||||
|
||||
The review validates 4 dimensions:
|
||||
|
||||
| Dimension | What It Checks |
|
||||
|-----------|---------------|
|
||||
| **Implementation** | Does the code match the task description? |
|
||||
| **Acceptance Criteria** | Are all criteria met? |
|
||||
| **Spec Compliance** | Does it align with the original specification? |
|
||||
| **Code Quality** | Language-specific best practices, patterns, security |
|
||||
|
||||
**Output:** `TASK-001--review.md` with pass/fail status and detailed findings.
|
||||
|
||||
### Step 5: Clean Up and Complete
|
||||
|
||||
If the review passes:
|
||||
|
||||
```
|
||||
/developer-kit-specs:specs-code-cleanup --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-001.md"
|
||||
```
|
||||
|
||||
This final step:
|
||||
- Removes debug logs (`System.out.println`, temporary comments)
|
||||
- Optimizes imports
|
||||
- Runs language-specific formatters (`./mvnw spotless:apply`)
|
||||
- Verifies tests still pass
|
||||
- Marks the task as `completed`
|
||||
|
||||
### Step 6: Sync Specification with Implementation
|
||||
|
||||
After implementing several tasks, sync the spec with reality:
|
||||
|
||||
```
|
||||
/specs:spec-sync-with-code docs/specs/001-user-auth/
|
||||
```
|
||||
|
||||
This detects deviations (scope expansions, refinements, reductions) and updates the specification to match what was actually built.
|
||||
|
||||
## What's Next?
|
||||
|
||||
- **[SDD Workflow](./sdd-workflow.md)** — Complete workflow documentation with all phases
|
||||
- **[Commands Reference](./commands-reference.md)** — Detailed command documentation with examples
|
||||
- **[Ralph Loop Guide](./ralph-loop-guide.md)** — Automate task execution across multiple agents (manual and fully automated via `agents_loop.py`)
|
||||
- **[TDD Workflow](./tdd-workflow.md)** — Test-Driven Development integration
|
||||
- **[KPI Evaluation](./kpi-evaluation.md)** — Understanding quality metrics and scoring
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/specs:brainstorm "idea"` | Create a full specification |
|
||||
| `/specs:quick-spec "fix"` | Create a minimal spec for small changes |
|
||||
| `/specs:spec-to-tasks --lang=spring spec/` | Generate executable tasks |
|
||||
| `/specs:task-implementation --lang=spring --task=TASK.md` | Implement a task |
|
||||
| `/specs:task-tdd --lang=spring --task=TASK.md` | Generate failing tests first (RED) |
|
||||
| `/specs:task-review --lang=spring TASK.md` | Review implementation |
|
||||
| `/developer-kit-specs:specs-code-cleanup --lang=spring --task=TASK.md` | Final cleanup |
|
||||
| `/specs:spec-sync-with-code spec/` | Sync spec with implementation |
|
||||
| `/specs:spec-sync-context spec/` | Sync Knowledge Graph and context |
|
||||
| `/specs:task-manage --action=list` | List and manage tasks |
|
||||
| `agents_loop.py --spec=spec/ --agent=auto` | Fully automated multi-agent orchestration |
|
||||
@@ -0,0 +1,297 @@
|
||||
# KPI Evaluation — Quality Metrics System
|
||||
|
||||
The KPI Evaluation system provides objective, quantitative quality metrics for task implementations. It removes evaluator bias by using pre-calculated data instead of subjective assessments.
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Step 1: HOOK (automatic) │
|
||||
│ Trigger: PostToolUse on TASK-*.md files │
|
||||
│ Script: hooks/task-kpi-analyzer.py │
|
||||
│ Output: tasks/TASK-XXX--kpi.json │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Step 2: EVALUATOR AGENT │
|
||||
│ Input: tasks/TASK-XXX--kpi.json │
|
||||
│ Action: Data-driven pass/fail decision │
|
||||
│ Output: tasks/TASK-XXX--evaluation.md │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**You don't run KPI analysis manually.** The hook fires automatically every time a task file is saved. The Evaluator Agent reads the results during task review.
|
||||
|
||||
## KPI Categories
|
||||
|
||||
### 1. Spec Compliance (30% weight)
|
||||
|
||||
Measures how well the implementation matches the specification.
|
||||
|
||||
| Metric | Calculation | Max Score |
|
||||
|--------|------------|-----------|
|
||||
| **Acceptance Criteria Met** | `(checked / total) × 10` | 10 |
|
||||
| **Requirements Coverage** | Count of REQ-IDs covered by implementation | 10 |
|
||||
| **No Scope Creep** | `(implemented_files / expected_files) × 10` | 10 |
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Task: Implement JWT token service
|
||||
Acceptance Criteria: 4 defined, 4 checked → score: 10.0
|
||||
Requirements: REQ-05, REQ-06 covered → score: 10.0
|
||||
Scope: 3 files expected, 3 implemented → score: 10.0
|
||||
Weighted: 10.0 × 0.30 = 3.0
|
||||
```
|
||||
|
||||
### 2. Code Quality (25% weight)
|
||||
|
||||
Measures implementation quality against language-specific standards.
|
||||
|
||||
| Metric | Calculation | Max Score |
|
||||
|--------|------------|-----------|
|
||||
| **Static Analysis** | Tool results (ESLint, Checkstyle, etc.) | 10 |
|
||||
| **Complexity** | Function length analysis | 10 |
|
||||
| **Patterns Alignment** | Knowledge Graph pattern matching | 10 |
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Static Analysis: 0 errors, 2 warnings → score: 9.0
|
||||
Complexity: All functions <20 lines → score: 10.0
|
||||
Patterns: Follows project conventions → score: 9.5
|
||||
Weighted: 9.5 × 0.25 = 2.375
|
||||
```
|
||||
|
||||
### 3. Test Coverage (25% weight)
|
||||
|
||||
Measures testing completeness.
|
||||
|
||||
| Metric | Calculation | Max Score |
|
||||
|--------|------------|-----------|
|
||||
| **Unit Tests** | `min(10, test_files × 5)` | 10 |
|
||||
| **Test/Code Ratio** | `(test_count / code_count) × 10` | 10 |
|
||||
| **Coverage Percentage** | Coverage report / 10 | 10 |
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Unit Tests: 2 test files for 1 source file → score: 10.0
|
||||
Ratio: 120 test LOC / 95 code LOC = 1.26 → score: 10.0
|
||||
Coverage: 87% → score: 8.7
|
||||
Weighted: 9.57 × 0.25 = 2.39
|
||||
```
|
||||
|
||||
### 4. Contract Fulfillment (20% weight)
|
||||
|
||||
Measures whether task contracts (provides/expects) are satisfied.
|
||||
|
||||
| Metric | Calculation | Max Score |
|
||||
|--------|------------|-----------|
|
||||
| **Provides Verified** | Symbols from `provides` found in code | 10 |
|
||||
| **Expects Satisfied** | Dependencies from `expects` exist | 10 |
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Provides: [JwtTokenService, TokenPair] — both found → score: 10.0
|
||||
Expects: [UserDetails, SecretKey] — both exist → score: 10.0
|
||||
Weighted: 10.0 × 0.20 = 2.0
|
||||
```
|
||||
|
||||
## Overall Score Calculation
|
||||
|
||||
```
|
||||
Overall = (Spec Compliance × 0.30) +
|
||||
(Code Quality × 0.25) +
|
||||
(Test Coverage × 0.25) +
|
||||
(Contract Fulfillment × 0.20)
|
||||
```
|
||||
|
||||
### Example Calculation
|
||||
|
||||
| Category | Raw Score | Weight | Weighted |
|
||||
|----------|-----------|--------|----------|
|
||||
| Spec Compliance | 10.0 | 30% | 3.00 |
|
||||
| Code Quality | 9.5 | 25% | 2.38 |
|
||||
| Test Coverage | 9.57 | 25% | 2.39 |
|
||||
| Contract Fulfillment | 10.0 | 20% | 2.00 |
|
||||
| **Overall** | | | **9.77/10** |
|
||||
|
||||
## Thresholds
|
||||
|
||||
### Decision Protocol
|
||||
|
||||
| Decision | Condition |
|
||||
|----------|-----------|
|
||||
| **APPROVE** | `score ≥ threshold` AND `critical_issues == 0` |
|
||||
| **CONDITIONAL APPROVE** | `score ≥ threshold - 0.5` AND `critical_issues == 0` |
|
||||
| **REQUEST FIXES** | `score < threshold` OR `critical_issues > 0` |
|
||||
|
||||
### Default Threshold
|
||||
|
||||
**7.5/10** — configurable per project type.
|
||||
|
||||
### Recommended Thresholds
|
||||
|
||||
| Project Type | Threshold | Rationale |
|
||||
|--------------|-----------|-----------|
|
||||
| Production MVP | 8.0 | High quality required for production |
|
||||
| Internal Tool | 7.0 | Good enough for internal use |
|
||||
| Prototype | 6.0 | Functional over perfect |
|
||||
| Critical System | 8.5 | No compromises (payments, security, medical) |
|
||||
|
||||
## Quality Levels
|
||||
|
||||
| Score Range | Level | Action |
|
||||
|-------------|-------|--------|
|
||||
| 9.0 - 10.0 | Exceptional | Approve, document best practices |
|
||||
| 8.0 - 8.9 | Good | Approve with minor notes |
|
||||
| 7.0 - 7.9 | Acceptable | Approve (if meets threshold) |
|
||||
| 6.0 - 6.9 | Below Standard | Request specific improvements |
|
||||
| < 6.0 | Poor | Significant rework required |
|
||||
|
||||
## KPI File Format
|
||||
|
||||
Auto-generated at `tasks/TASK-XXX--kpi.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "TASK-002",
|
||||
"spec_id": "001-user-auth",
|
||||
"evaluated_at": "2026-04-10T14:30:00Z",
|
||||
"overall_score": 8.2,
|
||||
"passed_threshold": true,
|
||||
"threshold": 7.5,
|
||||
"kpi_scores": [
|
||||
{
|
||||
"category": "spec_compliance",
|
||||
"weight": 0.30,
|
||||
"score": 9.0,
|
||||
"weighted_score": 2.70,
|
||||
"metrics": {
|
||||
"acceptance_criteria_met": 10.0,
|
||||
"requirements_coverage": 8.0,
|
||||
"no_scope_creep": 9.0
|
||||
}
|
||||
},
|
||||
{
|
||||
"category": "code_quality",
|
||||
"weight": 0.25,
|
||||
"score": 8.0,
|
||||
"weighted_score": 2.00,
|
||||
"metrics": {
|
||||
"static_analysis": 8.5,
|
||||
"complexity": 8.0,
|
||||
"patterns_alignment": 7.5
|
||||
}
|
||||
},
|
||||
{
|
||||
"category": "test_coverage",
|
||||
"weight": 0.25,
|
||||
"score": 7.5,
|
||||
"weighted_score": 1.875,
|
||||
"metrics": {
|
||||
"unit_tests": 8.0,
|
||||
"test_code_ratio": 7.0,
|
||||
"coverage_percentage": 7.5
|
||||
}
|
||||
},
|
||||
{
|
||||
"category": "contract_fulfillment",
|
||||
"weight": 0.20,
|
||||
"score": 8.1,
|
||||
"weighted_score": 1.62,
|
||||
"metrics": {
|
||||
"provides_verified": 10.0,
|
||||
"expects_satisfied": 6.2
|
||||
}
|
||||
}
|
||||
],
|
||||
"critical_issues": [],
|
||||
"recommendations": [
|
||||
"Add more integration tests for expects contracts",
|
||||
"Consider reducing function complexity in JwtTokenService.validateToken()"
|
||||
],
|
||||
"summary": "Score: 8.2/10 - PASSED"
|
||||
}
|
||||
```
|
||||
|
||||
## Evaluator Agent
|
||||
|
||||
The Evaluator Agent (`evaluator-agent`) is a specialized subagent that reads KPI files and makes data-driven decisions.
|
||||
|
||||
### Core Principle
|
||||
|
||||
**"Don't trust your gut — trust the data."**
|
||||
|
||||
The Evaluator Agent counters LLM leniency bias by grounding decisions in quantitative metrics.
|
||||
|
||||
### Evaluation Workflow
|
||||
|
||||
1. **Read KPI file** (mandatory first step)
|
||||
2. **Read task and specification** for qualitative validation
|
||||
3. **Compare KPI evidence** with actual implementation
|
||||
4. **Generate evaluation report** at `TASK-XXX--evaluation.md`
|
||||
5. **Make decision** based on scores and critical issues
|
||||
|
||||
### When the Evaluator Can Override KPI Scores
|
||||
|
||||
The Evaluator can only lower scores (never raise) with documented justification:
|
||||
- Critical security vulnerability discovered during code review
|
||||
- Completely wrong implementation that passes metrics by coincidence
|
||||
- Missing error handling that metrics couldn't detect
|
||||
|
||||
### Evaluation Report
|
||||
|
||||
Output at `tasks/TASK-XXX--evaluation.md`:
|
||||
|
||||
```markdown
|
||||
# Task Evaluation: TASK-002
|
||||
|
||||
## Decision: APPROVED
|
||||
|
||||
## Scores
|
||||
| Category | Score | Weight | Weighted |
|
||||
|----------|-------|--------|----------|
|
||||
| Spec Compliance | 9.0 | 30% | 2.70 |
|
||||
| Code Quality | 8.0 | 25% | 2.00 |
|
||||
| Test Coverage | 7.5 | 25% | 1.88 |
|
||||
| Contract Fulfillment | 8.1 | 20% | 1.62 |
|
||||
| **Overall** | | | **8.2/10** |
|
||||
|
||||
## Critical Issues
|
||||
None
|
||||
|
||||
## Recommendations
|
||||
1. Add integration tests for expects contracts (score: 6.2/10)
|
||||
2. Reduce complexity in JwtTokenService.validateToken()
|
||||
|
||||
## Evidence
|
||||
- KPI data source: TASK-002--kpi.json (evaluated 2026-04-10T14:30:00Z)
|
||||
- Code review: passed with minor notes
|
||||
- Spec compliance: 4/4 acceptance criteria verified
|
||||
```
|
||||
|
||||
## Integration with Ralph Loop
|
||||
|
||||
The Ralph Loop uses KPI evaluation to decide whether to retry failed tasks:
|
||||
|
||||
```
|
||||
implementation → review → (read KPI score)
|
||||
├─ score ≥ threshold → cleanup → sync
|
||||
└─ score < threshold → fix → implementation (retry)
|
||||
└─ max 3 retries
|
||||
```
|
||||
|
||||
## Reading KPI Files Manually
|
||||
|
||||
```bash
|
||||
# View KPI scores for a task
|
||||
cat docs/specs/001-user-auth/tasks/TASK-002--kpi.json | python3 -m json.tool
|
||||
|
||||
# Quick summary
|
||||
cat docs/specs/001-user-auth/tasks/TASK-002--kpi.json | python3 -c "
|
||||
import json, sys
|
||||
data = json.load(sys.stdin)
|
||||
print(f\"Score: {data['overall_score']}/10\")
|
||||
print(f\"Status: {'PASSED' if data['passed_threshold'] else 'FAILED'}\")
|
||||
print(f\"Threshold: {data['threshold']}\")
|
||||
for kpi in data['kpi_scores']:
|
||||
print(f\" {kpi['category']}: {kpi['score']}/10 (weight: {kpi['weight']})\")
|
||||
"
|
||||
```
|
||||
@@ -0,0 +1,494 @@
|
||||
# Ralph Loop — Multi-Agent Automation Guide
|
||||
|
||||
The Ralph Loop automates the SDD implementation cycle across multiple tasks using different AI agents. It applies Geoffrey Huntley's "Ralph Wiggum as a Software Engineer" technique: one step per invocation, state persisted to disk.
|
||||
|
||||
## Why Ralph Loop?
|
||||
|
||||
**The problem:** Implementing a 10-task specification in a single Claude Code session causes context window explosion. After 3-4 tasks, the agent loses track of earlier decisions and implementation details.
|
||||
|
||||
**The solution:** The Ralph Loop executes exactly one step per invocation and persists all state to `fix_plan.json`. Each invocation starts fresh with only the context it needs.
|
||||
|
||||
```
|
||||
Traditional approach (single session):
|
||||
Session 1: TASK-001 → TASK-002 → TASK-003 → [context limit reached]
|
||||
|
||||
Ralph Loop approach:
|
||||
Invocation 1: choose_task → TASK-001
|
||||
Invocation 2: implement TASK-001
|
||||
Invocation 3: review TASK-001
|
||||
Invocation 4: cleanup TASK-001
|
||||
Invocation 5: choose_task → TASK-002
|
||||
... (unlimited, state in fix_plan.json)
|
||||
```
|
||||
|
||||
## State Machine
|
||||
|
||||
```
|
||||
init → choose_task → implementation → review → fix → cleanup → sync → update_done → choose_task
|
||||
↑ │
|
||||
└────────── (if review failed, max 3 retries) ┘
|
||||
```
|
||||
|
||||
| State | Action | Next State |
|
||||
|-------|--------|------------|
|
||||
| `init` | Load spec, validate prerequisites | `choose_task` |
|
||||
| `choose_task` | Pick next pending task | `implementation` |
|
||||
| `implementation` | Execute task with assigned agent | `review` |
|
||||
| `review` | Run task-review | `cleanup` (pass) or `fix` (fail) |
|
||||
| `fix` | Apply review feedback | `implementation` (retry ≤3) |
|
||||
| `cleanup` | Run code-cleanup | `sync` |
|
||||
| `sync` | Update Knowledge Graph and context | `update_done` |
|
||||
| `update_done` | Mark task completed, commit | `choose_task` |
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Initialize
|
||||
|
||||
```bash
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/001-user-auth/
|
||||
```
|
||||
|
||||
This creates `docs/specs/001-user-auth/_ralph_loop/fix_plan.json` with initial state.
|
||||
|
||||
**Options:**
|
||||
|
||||
```bash
|
||||
# Process only a specific range of tasks
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--from-task=TASK-003 \
|
||||
--to-task=TASK-007
|
||||
|
||||
# Specify default agent
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=codex
|
||||
|
||||
# Skip git commits (for testing)
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--no-commit
|
||||
```
|
||||
|
||||
### Run the Loop
|
||||
|
||||
```bash
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=loop \
|
||||
--spec=docs/specs/001-user-auth/
|
||||
```
|
||||
|
||||
Each invocation:
|
||||
1. Reads `fix_plan.json` to determine current state
|
||||
2. Executes exactly one step
|
||||
3. Updates `fix_plan.json` with new state
|
||||
4. Prints a command for the user to execute next
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
[ralph-loop] State: choose_task
|
||||
[ralph-loop] Selected: TASK-003 (Implement JWT token service)
|
||||
[ralph-loop] Agent: claude
|
||||
[ralph-loop] Next: Execute the following command, then run loop again:
|
||||
|
||||
claude --print "/specs:task-implementation --lang=spring --task=docs/specs/001-user-auth/tasks/TASK-003.md"
|
||||
```
|
||||
|
||||
After executing the shown command, run the loop again:
|
||||
```bash
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=loop \
|
||||
--spec=docs/specs/001-user-auth/
|
||||
```
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=status \
|
||||
--spec=docs/specs/001-user-auth/
|
||||
```
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
[ralph-loop] Status for docs/specs/001-user-auth/
|
||||
[ralph-loop] Current state: review
|
||||
[ralph-loop] Current task: TASK-003
|
||||
[ralph-loop] Retries: 0/3
|
||||
[ralph-loop] Progress: 3/8 tasks completed
|
||||
[ralph-loop] Completed: TASK-001 ✓, TASK-002 ✓, TASK-003 (in review)
|
||||
[ralph-loop] Remaining: TASK-004, TASK-005, TASK-006, TASK-007, TASK-008
|
||||
```
|
||||
|
||||
## Multi-Agent Support
|
||||
|
||||
The Ralph Loop can dispatch different tasks to different AI agents. This is useful when:
|
||||
- Some tasks need deep reasoning (use Claude)
|
||||
- Some tasks are boilerplate (use Codex or Copilot)
|
||||
- You want to compare agent outputs
|
||||
|
||||
### Per-Task Agent Assignment
|
||||
|
||||
Set the `agent` field in task frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: TASK-003
|
||||
title: Implement JWT token service
|
||||
agent: claude # Use Claude for complex security logic
|
||||
---
|
||||
|
||||
---
|
||||
id: TASK-004
|
||||
title: Create REST DTOs
|
||||
agent: codex # Use Codex for straightforward DTO generation
|
||||
---
|
||||
|
||||
---
|
||||
id: TASK-005
|
||||
title: Write unit tests
|
||||
agent: copilot # Use Copilot for test generation
|
||||
---
|
||||
```
|
||||
|
||||
### Supported Agents
|
||||
|
||||
| Agent | CLI | Best For |
|
||||
|-------|-----|----------|
|
||||
| `claude` | Claude Code | Complex logic, security, architecture |
|
||||
| `codex` | Codex CLI | Code generation, boilerplate, straightforward tasks |
|
||||
| `copilot` | GitHub Copilot CLI | Test generation, code completion |
|
||||
| `gemini` | Gemini CLI | Large-context analysis, documentation |
|
||||
| `glm4` | GLM-4 CLI | General-purpose coding |
|
||||
| `kimi` | Kimi CLI | Long-context reasoning |
|
||||
| `minimax` | MiniMax CLI | General-purpose coding |
|
||||
|
||||
### Default Agent
|
||||
|
||||
If no agent is specified in task frontmatter, the default is used:
|
||||
|
||||
```bash
|
||||
# Set default agent at initialization
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=codex
|
||||
```
|
||||
|
||||
## Real-World Scenario: Spring Boot Auth System
|
||||
|
||||
Here's a complete walkthrough for a 6-task specification:
|
||||
|
||||
```bash
|
||||
# 1. Initialize with task range
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--from-task=TASK-001 \
|
||||
--to-task=TASK-006
|
||||
|
||||
# Output:
|
||||
# [ralph-loop] Initialized fix_plan.json
|
||||
# [ralph-loop] Tasks: TASK-001 through TASK-006
|
||||
# [ralph-loop] Default agent: claude
|
||||
|
||||
# 2. Run loop (iteration 1: choose_task)
|
||||
python3 .../ralph_loop.py --action=loop --spec=docs/specs/001-user-auth/
|
||||
# → Selects TASK-001 (Create User entity)
|
||||
# → Shows command: /specs:task-implementation --lang=spring --task=...TASK-001.md
|
||||
|
||||
# 3. Execute the shown command (manually or via script)
|
||||
# ... implement TASK-001 ...
|
||||
|
||||
# 4. Run loop (iteration 2: review)
|
||||
python3 .../ralph_loop.py --action=loop --spec=docs/specs/001-user-auth/
|
||||
# → Reviews TASK-001
|
||||
# → If PASSED: proceeds to cleanup
|
||||
# → Shows command: /developer-kit-specs:specs-code-cleanup --lang=spring --task=...TASK-001.md
|
||||
|
||||
# 5. Execute cleanup
|
||||
# ... cleanup TASK-001 ...
|
||||
|
||||
# 6. Run loop (iteration 3: sync + choose next)
|
||||
python3 .../ralph_loop.py --action=loop --spec=docs/specs/001-user-auth/
|
||||
# → Syncs Knowledge Graph
|
||||
# → Marks TASK-001 completed
|
||||
# → Commits changes
|
||||
# → Selects TASK-002
|
||||
|
||||
# ... continue for remaining tasks ...
|
||||
```
|
||||
|
||||
## Review Failure Handling
|
||||
|
||||
When a task review fails, the Ralph Loop enters the `fix` state:
|
||||
|
||||
```
|
||||
implementation → review (FAILED) → fix → implementation (retry) → review → ...
|
||||
```
|
||||
|
||||
- **Max retries:** 3 per task
|
||||
- **On retry:** The loop provides review feedback to the next implementation attempt
|
||||
- **After 3 failures:** The loop pauses and asks for manual intervention
|
||||
|
||||
## State File Reference
|
||||
|
||||
The `fix_plan.json` file stores all loop state:
|
||||
|
||||
```json
|
||||
{
|
||||
"spec_path": "docs/specs/001-user-auth/",
|
||||
"state": "choose_task",
|
||||
"current_task": null,
|
||||
"task_range": {
|
||||
"from": "TASK-001",
|
||||
"to": "TASK-006"
|
||||
},
|
||||
"completed_tasks": ["TASK-001", "TASK-002"],
|
||||
"failed_tasks": [],
|
||||
"retries": {
|
||||
"TASK-003": 2
|
||||
},
|
||||
"default_agent": "claude",
|
||||
"no_commit": false,
|
||||
"started_at": "2026-04-10T10:00:00Z",
|
||||
"last_updated": "2026-04-10T11:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Important:** Do not edit `fix_plan.json` manually. The Python script manages all state transitions.
|
||||
|
||||
## Fully Automated Orchestration with `agents_loop.py`
|
||||
|
||||
The manual Ralph Loop requires you to run `ralph_loop.py` and execute each command yourself. The `agents_loop.py` script in `scripts/` **fully automates** this cycle: it calls `ralph_loop.py` to get the next command, executes it with the chosen AI agent, advances the state, and repeats until all tasks are done.
|
||||
|
||||
```
|
||||
Manual Ralph Loop:
|
||||
You: ralph_loop.py --action=loop → see command
|
||||
You: execute command manually
|
||||
You: ralph_loop.py --action=next
|
||||
...repeat...
|
||||
|
||||
Automated agents_loop.py:
|
||||
Script: ralph_loop.py → get command → execute with agent → advance state → repeat
|
||||
You: sit back and monitor
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Fully automated with a single agent
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=claude
|
||||
|
||||
# Auto-select the best agent per workflow phase
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=auto
|
||||
|
||||
# Use a specific reviewer agent
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=claude \
|
||||
--reviewer=glm4
|
||||
```
|
||||
|
||||
### Supported Agents
|
||||
|
||||
| Agent | CLI | Best For |
|
||||
|-------|-----|----------|
|
||||
| `claude` | Claude Code | Complex logic, security, architecture |
|
||||
| `codex` | Codex CLI | Code generation, boilerplate |
|
||||
| `gemini` | Gemini CLI | Large-context analysis |
|
||||
| `kimi` | Kimi CLI | Long-context reasoning |
|
||||
| `glm4` | GLM-4 CLI | General-purpose coding |
|
||||
| `minimax` | MiniMax CLI | General-purpose coding |
|
||||
| `openrouter` | OpenRouter CLI | Access to multiple models |
|
||||
| `copilot` | GitHub Copilot CLI | Test generation, code review |
|
||||
| `qwen` | Qwen Code | Coding tasks with Qwen models |
|
||||
| `auto` | Dynamic selection | Best agent per workflow phase |
|
||||
|
||||
### Key Parameters
|
||||
|
||||
| Parameter | Default | Description |
|
||||
|-----------|---------|-------------|
|
||||
| `--spec` | required | Path to specification folder |
|
||||
| `--agent` | `codex` | AI agent to use (or `auto`) |
|
||||
| `--delay` | `10` | Seconds between iterations |
|
||||
| `--max-iterations` | `20` | Safety limit on iterations |
|
||||
| `--fast` | `false` | Skip cleanup and sync steps |
|
||||
| `--verbose` | `false` | Enable debug output with real-time streaming |
|
||||
| `--model` | agent default | Model override (e.g. `sonnet`, `opus`, `gpt-5.4`) |
|
||||
| `--kpi-check` | `true` | Enable KPI quality gates after review |
|
||||
| `--kpi-threshold` | `7.5` | Quality score threshold (0-10) |
|
||||
| `--max-quality-iterations` | `5` | Max fix cycles based on KPI score |
|
||||
| `--reviewer` | none | Dedicated agent for review steps |
|
||||
| `--agent-timeout` | `1200` | Timeout per agent execution (seconds) |
|
||||
| `--dry-run` | `false` | Print commands without executing |
|
||||
|
||||
### Auto Mode (`--agent=auto`)
|
||||
|
||||
When using `--agent=auto`, the script selects the best agent for each workflow phase:
|
||||
|
||||
| Phase | Agent | Rationale |
|
||||
|-------|-------|-----------|
|
||||
| `review` | `codex` | Code review specialist |
|
||||
| `sync` | `gemini` | Powerful context analysis |
|
||||
| `implementation` | Rotates: `claude` → `kimi` → `glm4` | Diversity of approach |
|
||||
| `fix` | Rotates: `glm4` → `minimax` → `openrouter` | Alternative perspectives |
|
||||
| `cleanup` | Rotates: `claude` → `kimi` → `codex` | General cleanup |
|
||||
| Other steps | `glm4` | Default fallback |
|
||||
|
||||
### Fast Mode (`--fast`)
|
||||
|
||||
Skip cleanup and sync steps for rapid iteration cycles:
|
||||
|
||||
```bash
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=claude \
|
||||
--fast
|
||||
```
|
||||
|
||||
- **Normal flow**: `review → cleanup → sync → update_done`
|
||||
- **Fast flow**: `review → update_done`
|
||||
|
||||
Use fast mode when you want rapid implementation-review cycles and will sync later.
|
||||
|
||||
### KPI Quality Gates (`--kpi-check`)
|
||||
|
||||
When enabled (default), the script checks quality KPIs after each review step:
|
||||
|
||||
1. Reads `TASK-XXX--kpi.json` (auto-generated by hooks)
|
||||
2. Compares `overall_score` against threshold (default: 7.5)
|
||||
3. If **passed**: proceeds normally
|
||||
4. If **failed**: forces state to `fix` for another iteration
|
||||
5. After max quality iterations (default: 5): marks task as failed
|
||||
|
||||
This enables data-driven iteration — the script keeps fixing until quality meets the threshold.
|
||||
|
||||
```bash
|
||||
# Custom quality threshold
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=claude \
|
||||
--kpi-threshold=8.0 \
|
||||
--max-quality-iterations=3
|
||||
```
|
||||
|
||||
### Reviewer Override (`--reviewer`)
|
||||
|
||||
Use a different agent specifically for review steps, regardless of the main agent:
|
||||
|
||||
```bash
|
||||
# Implementation with Claude, review with GLM-4
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=claude \
|
||||
--reviewer=glm4
|
||||
```
|
||||
|
||||
This also works with `--agent=auto`, overriding the auto-selection for review phases only.
|
||||
|
||||
### Real-World Example
|
||||
|
||||
```bash
|
||||
# 1. Initialize the Ralph Loop first
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--from-task=TASK-001 \
|
||||
--to-task=TASK-006
|
||||
|
||||
# 2. Run fully automated with auto mode and KPI checks
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=auto \
|
||||
--kpi-check \
|
||||
--verbose
|
||||
|
||||
# The script will:
|
||||
# - Auto-select agents per phase
|
||||
# - Execute implementation, review, cleanup, sync
|
||||
# - Check quality KPIs after each review
|
||||
# - Fix issues if KPIs below threshold
|
||||
# - Create git checkpoints after each iteration
|
||||
# - Stop when all tasks are complete or failed
|
||||
```
|
||||
|
||||
### Monitoring and Debugging
|
||||
|
||||
```bash
|
||||
# Enable verbose output for real-time agent streaming
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=claude \
|
||||
--verbose
|
||||
|
||||
# Dry run to see what would be executed
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-user-auth/ \
|
||||
--agent=claude \
|
||||
--dry-run
|
||||
|
||||
# Logs are saved automatically to .agents_loop_logs/
|
||||
```
|
||||
|
||||
Log files are written to `.agents_loop_logs/<spec-name>/` with timestamps, agent output, and execution metrics.
|
||||
|
||||
### Graceful Shutdown
|
||||
|
||||
Press `Ctrl+C` to stop the loop. The script:
|
||||
1. Finishes the current agent execution
|
||||
2. Prints a summary
|
||||
3. Preserves `fix_plan.json` state
|
||||
4. You can resume later by running the same command
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start with clean git state** — Uncommitted changes can cause conflicts
|
||||
2. **One step per invocation** — Never combine implementation + review + sync (manual mode)
|
||||
3. **Check status between runs** — Use `--action=status` to verify state (manual mode)
|
||||
4. **Assign agents wisely** — Use Claude for complex logic, Codex for boilerplate
|
||||
5. **Monitor retries** — If a task fails 3 times, investigate manually
|
||||
6. **Commit between tasks** — Each task completion triggers a git commit
|
||||
7. **Use task ranges** — Start with a small range to validate the workflow
|
||||
8. **Use `agents_loop.py` for automation** — Fully automates the manual loop cycle
|
||||
9. **Use `--verbose` for debugging** — See real-time agent output and execution metrics
|
||||
10. **Leverage KPI quality gates** — Let the script iterate on quality automatically
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "fix_plan.json not found"
|
||||
|
||||
Run `--action=start` to initialize:
|
||||
|
||||
```bash
|
||||
python3 .../ralph_loop.py --action=start --spec=docs/specs/001-user-auth/
|
||||
```
|
||||
|
||||
### "State is wrong"
|
||||
|
||||
Resume or reset the loop:
|
||||
|
||||
```bash
|
||||
# Resume from current state
|
||||
python3 .../ralph_loop.py --action=resume --spec=docs/specs/001-user-auth/
|
||||
|
||||
# Or reset and start over
|
||||
rm -rf docs/specs/001-user-auth/_ralph_loop/
|
||||
python3 .../ralph_loop.py --action=start --spec=docs/specs/001-user-auth/
|
||||
```
|
||||
|
||||
### "Max retries exceeded"
|
||||
|
||||
The task has failed review 3 times. Options:
|
||||
1. Implement the task manually
|
||||
2. Split the task into smaller subtasks: `/specs:task-manage --action=split --task=...`
|
||||
3. Review the task yourself and fix the issues
|
||||
@@ -0,0 +1,572 @@
|
||||
# Specification-Driven Development — Complete Workflow
|
||||
|
||||
This document covers the full SDD lifecycle from idea to production-ready code.
|
||||
|
||||
## The SDD Triangle
|
||||
|
||||
SDD enforces a three-way alignment between specification, tests, and implementation:
|
||||
|
||||
```
|
||||
Specification
|
||||
/ \
|
||||
/ \
|
||||
Tests ←───────── Code
|
||||
```
|
||||
|
||||
Every change should update all three vertices. The sync commands keep them aligned.
|
||||
|
||||
## Lifecycle Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Phase 1: SPECIFICATION │
|
||||
│ brainstorm → spec-quality-check → spec-to-tasks │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ Phase 2: IMPLEMENTATION (per task, repeat for each) │
|
||||
│ task-tdd (RED) → task-implementation (GREEN) → task-review │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ Phase 3: FINALIZATION │
|
||||
│ code-cleanup → spec-sync-with-code → spec-sync-context │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ AUTOMATION (optional) │
|
||||
│ ralph-loop: automates Phase 2-3 across all tasks │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Specification
|
||||
|
||||
### 1.1 Choose Your Entry Point
|
||||
|
||||
| Scenario | Command | Output |
|
||||
|----------|---------|--------|
|
||||
| New complex feature | `/specs:brainstorm "idea"` | Full 9-phase specification |
|
||||
| Bug fix or small change | `/specs:quick-spec "fix"` | Minimal 4-phase specification |
|
||||
|
||||
**When to use `brainstorm` vs `quick-spec`:**
|
||||
|
||||
- **brainstorm**: 5+ files involved, unclear requirements, multiple stakeholders, needs architectural decisions
|
||||
- **quick-spec**: 1-3 files, clear solution, well-understood context, ≤4 acceptance criteria
|
||||
|
||||
#### Example: Complex Feature (brainstorm)
|
||||
|
||||
```
|
||||
/specs:brainstorm Add a hotel search engine with multi-provider aggregation,
|
||||
real-time availability, price comparison, and guest review scoring
|
||||
```
|
||||
|
||||
Claude goes through these phases:
|
||||
|
||||
**Phase 1 — Context Discovery:**
|
||||
Claude reads your project structure, identifies existing patterns, and checks for related code:
|
||||
```
|
||||
Exploring project structure...
|
||||
Found: Spring Boot 3.2, Spring WebFlux, MongoDB, Redis
|
||||
Existing: /src/main/java/com/example/search/ (search infrastructure)
|
||||
Missing: No hotel-specific models or services detected
|
||||
```
|
||||
|
||||
**Phase 1.5 — Complexity Assessment:**
|
||||
Claude estimates task count. If >15 tasks, recommends splitting:
|
||||
```
|
||||
Estimated tasks: 22 — exceeds 15-task limit.
|
||||
Recommendation: Split into 3 specifications:
|
||||
001-hotel-search-data-model (6 tasks)
|
||||
002-hotel-search-aggregation (8 tasks)
|
||||
003-hotel-search-api (5 tasks)
|
||||
```
|
||||
|
||||
**Phase 2 — Idea Refinement:**
|
||||
Claude asks targeted questions (max 3):
|
||||
```
|
||||
Question 1 of 3:
|
||||
"Should the search support real-time availability via provider APIs,
|
||||
or is cached/periodic data sufficient?"
|
||||
a) Real-time via provider APIs (recommended for accuracy)
|
||||
b) Cached with periodic refresh (better performance)
|
||||
c) Hybrid: real-time for availability, cached for pricing
|
||||
```
|
||||
|
||||
**Phase 3 — Functional Approach Exploration:**
|
||||
Claude presents 2-3 approaches without prescribing technology:
|
||||
```
|
||||
Approach A: Direct Provider Integration
|
||||
- Each hotel provider has a dedicated adapter
|
||||
- Sequential queries to each provider
|
||||
- Simple error handling (fail-fast)
|
||||
|
||||
Approach B: Aggregation Pipeline (recommended)
|
||||
- Unified provider interface
|
||||
- Parallel queries with reactive composition
|
||||
- Graceful degradation (partial results allowed)
|
||||
```
|
||||
|
||||
**Phase 5 — Specification Generation:**
|
||||
Output specification is technology-agnostic — describes WHAT, not HOW:
|
||||
|
||||
```markdown
|
||||
## Hotel Search Engine — Functional Specification
|
||||
|
||||
### Search Request
|
||||
The system shall accept search requests containing:
|
||||
- Destination (city, coordinates, or landmark)
|
||||
- Check-in and check-out dates
|
||||
- Number of guests and rooms
|
||||
- Optional filters: price range, star rating, amenities
|
||||
|
||||
### Search Response
|
||||
The system shall return results containing:
|
||||
- Hotel name, images, star rating
|
||||
- Available room types with pricing
|
||||
- Guest review score (1-10) with review count
|
||||
- Provider source and booking URL
|
||||
```
|
||||
|
||||
#### Example: Simple Fix (quick-spec)
|
||||
|
||||
```
|
||||
/specs:quick-spec Fix the N+1 query issue when loading user orders with items
|
||||
```
|
||||
|
||||
Claude skips idea refinement and approach exploration, going straight to:
|
||||
```
|
||||
Phase 1 — Quick Context:
|
||||
Found: UserRepository, OrderService, OrderRepository
|
||||
Issue: OrderService.findAll() triggers lazy loading per order
|
||||
|
||||
Phase 2 — Problem + Solution Checkpoint:
|
||||
Problem: N+1 query on Order.findAll() → lazy loads items for each order
|
||||
Solution: Use JOIN FETCH in repository query
|
||||
|
||||
Phase 3 — Generate Minimal Spec:
|
||||
docs/specs/004-fix-n1-orders/2026-04-10--fix-n1-orders.md
|
||||
Acceptance criteria: 3 (within limit of 4)
|
||||
```
|
||||
|
||||
### 1.2 Quality Check the Specification
|
||||
|
||||
After generating a specification, validate it:
|
||||
|
||||
```
|
||||
/specs:spec-quality-check docs/specs/001-hotel-search/
|
||||
```
|
||||
|
||||
Claude asks up to 5 targeted questions, one at a time:
|
||||
|
||||
```
|
||||
Question 1 of 5:
|
||||
"The specification mentions 'real-time availability' but doesn't specify
|
||||
a timeout. What should happen if a provider takes >5 seconds to respond?"
|
||||
|
||||
Your answer: "Return cached data if available, otherwise skip that provider"
|
||||
→ Integrated into specification under "Error Handling" section
|
||||
```
|
||||
|
||||
Quality scan covers 12 taxonomy areas:
|
||||
- Completeness and Clarity
|
||||
- Domain and Data Model
|
||||
- Interaction and UX Flow
|
||||
- Non-Functional Requirements (performance, scalability, security)
|
||||
- Edge Cases and Error Handling
|
||||
- Architecture Alignment (if architecture.md exists)
|
||||
|
||||
### 1.3 Generate Tasks
|
||||
|
||||
```
|
||||
/specs:spec-to-tasks --lang=spring docs/specs/001-hotel-search/
|
||||
```
|
||||
|
||||
This is the bridge from functional specification to executable code:
|
||||
|
||||
**What happens:**
|
||||
1. Reads the specification and extracts requirements (assigned REQ-IDs)
|
||||
2. Loads or creates a Knowledge Graph (`knowledge-graph.json`)
|
||||
3. Explores your codebase with language-specific patterns
|
||||
4. Updates the Knowledge Graph with discoveries
|
||||
5. Decomposes requirements into atomic tasks
|
||||
6. Generates a traceability matrix
|
||||
7. Enforces task limit (≤15 implementation tasks)
|
||||
|
||||
**Task file structure:**
|
||||
```markdown
|
||||
---
|
||||
id: TASK-003
|
||||
title: Implement hotel availability aggregation
|
||||
spec: docs/specs/001-hotel-search
|
||||
lang: spring
|
||||
status: pending
|
||||
complexity: 65
|
||||
dependencies: [TASK-001, TASK-002]
|
||||
provides: [HotelAggregationService, AggregatedResult]
|
||||
expects: [HotelProviderClient, ProviderResponse]
|
||||
started_date:
|
||||
implemented_date:
|
||||
reviewed_date:
|
||||
completed_date:
|
||||
---
|
||||
|
||||
## Description
|
||||
Implement the service that queries multiple hotel providers in parallel
|
||||
and aggregates results into a unified response.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Query all configured providers in parallel
|
||||
- [ ] Return results within 3 seconds total
|
||||
- [ ] Gracefully handle provider timeouts
|
||||
- [ ] Deduplicate results by hotel ID
|
||||
- [ ] Sort by price (ascending) as default
|
||||
|
||||
## Definition of Done
|
||||
- [ ] All acceptance criteria checked
|
||||
- [ ] Unit tests written and passing
|
||||
- [ ] Integration test with mock providers
|
||||
- [ ] Code follows project conventions
|
||||
- [ ] No TODOs or placeholder code
|
||||
```
|
||||
|
||||
**Traceability matrix example:**
|
||||
```markdown
|
||||
| REQ-ID | Requirement | TASK-001 | TASK-002 | TASK-003 |
|
||||
|--------|------------|----------|----------|----------|
|
||||
| REQ-01 | Search by destination | ✅ | | |
|
||||
| REQ-02 | Multi-provider query | | ✅ | ✅ |
|
||||
| REQ-03 | Price sorting | | | ✅ |
|
||||
```
|
||||
|
||||
### 1.4 Manage Tasks
|
||||
|
||||
View, split, or reorganize tasks before implementation:
|
||||
|
||||
```
|
||||
# List all tasks with status and complexity
|
||||
/specs:task-manage --action=list --spec="docs/specs/001-hotel-search/"
|
||||
|
||||
# Split a complex task (complexity ≥ 50)
|
||||
/specs:task-manage --action=split --task="docs/specs/001-hotel-search/tasks/TASK-003.md"
|
||||
|
||||
# Add a new task
|
||||
/specs:task-manage --action=add --spec="docs/specs/001-hotel-search/"
|
||||
|
||||
# Mark a task as optional
|
||||
/specs:task-manage --action=mark-optional --task="docs/specs/001-hotel-search/tasks/TASK-006.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Implementation
|
||||
|
||||
For each task, follow one of two approaches:
|
||||
|
||||
### Approach A: Direct Implementation
|
||||
|
||||
```
|
||||
/specs:task-implementation --lang=spring --task="docs/specs/001-hotel-search/tasks/TASK-001.md"
|
||||
```
|
||||
|
||||
### Approach B: TDD (Test-Driven Development)
|
||||
|
||||
```
|
||||
# RED phase — generate failing tests
|
||||
/specs:task-tdd --lang=spring --task="docs/specs/001-hotel-search/tasks/TASK-001.md"
|
||||
|
||||
# GREEN phase — implement to make tests pass
|
||||
/specs:task-implementation --lang=spring --task="docs/specs/001-hotel-search/tasks/TASK-001.md"
|
||||
```
|
||||
|
||||
### Implementation Process (12 Steps)
|
||||
|
||||
When you run `task-implementation`, Claude follows this structured process:
|
||||
|
||||
| Step | Action | Gate |
|
||||
|------|--------|------|
|
||||
| T-1 | Parse task file, extract parameters | Valid task file required |
|
||||
| T-2 | Check git state (clean working tree) | No uncommitted changes |
|
||||
| T-3 | Validate dependencies (all completed) | All deps in `completed` status |
|
||||
| T-3.5 | Validate against Knowledge Graph | Required components exist |
|
||||
| T-3.6 | Contract validation (provides/expects) | Contracts compatible |
|
||||
| T-4 | **Implement the code** | — |
|
||||
| T-5 | Run tests, verify acceptance criteria | All tests pass |
|
||||
| T-6 | Update task status, write summary | — |
|
||||
| T-6.5 | Update Knowledge Graph | — |
|
||||
| T-6.6 | Check for spec deviations | Report any drift |
|
||||
|
||||
**Automatic hooks fire during implementation:**
|
||||
- `task-auto-status.py` — Updates status when you edit the task file
|
||||
- `task-kpi-analyzer.py` — Calculates quality KPIs
|
||||
- `drift-monitor.py` — Watches for unplanned file changes
|
||||
|
||||
### Task Status Lifecycle
|
||||
|
||||
```
|
||||
pending → in_progress → implemented → reviewed → completed
|
||||
↓
|
||||
blocked (can return to in_progress)
|
||||
```
|
||||
|
||||
Status transitions happen automatically based on your actions:
|
||||
|
||||
| Your Action | Status Change |
|
||||
|-------------|---------------|
|
||||
| Start editing a task file | `pending` → `in_progress` |
|
||||
| Check acceptance criteria boxes | Progress tracked |
|
||||
| Check all DoD boxes | `implemented` → ready for review |
|
||||
| Review passes | `reviewed` |
|
||||
| Cleanup completes | `completed` |
|
||||
|
||||
### Language-Specific Agents
|
||||
|
||||
Implementation uses language-specific review agents:
|
||||
|
||||
| `--lang` Value | Framework | Review Agent |
|
||||
|----------------|-----------|--------------|
|
||||
| `spring` | Spring Boot | `developer-kit-java:spring-boot-code-review-expert` |
|
||||
| `java` | Java SE | `developer-kit-java:java-software-architect-review` |
|
||||
| `nestjs` | NestJS | `developer-kit-typescript:nestjs-code-review-expert` |
|
||||
| `typescript` | Node.js | `developer-kit:general-code-reviewer` |
|
||||
| `react` | React | `developer-kit:general-code-reviewer` |
|
||||
| `python` | Django/FastAPI | `developer-kit-python:python-code-review-expert` |
|
||||
| `php` | Laravel/Symfony | `developer-kit-php:php-code-review-expert` |
|
||||
| `general` | Any | `developer-kit:general-code-reviewer` |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Finalization
|
||||
|
||||
### 3.1 Review
|
||||
|
||||
```
|
||||
/specs:task-review --lang=spring docs/specs/001-hotel-search/tasks/TASK-001.md
|
||||
```
|
||||
|
||||
The review checks 4 dimensions:
|
||||
|
||||
1. **Implementation Verification** — Does the code match the task description?
|
||||
2. **Acceptance Criteria** — Are all checkboxes ✅?
|
||||
3. **Specification Compliance** — Does it align with the functional spec?
|
||||
4. **Code Quality** — Language-specific review (patterns, security, conventions)
|
||||
|
||||
**Review outcomes:**
|
||||
|
||||
| Status | Condition |
|
||||
|--------|-----------|
|
||||
| **PASSED** | All criteria ✅, all DoD ✅, no critical code issues |
|
||||
| **FAILED** | Any criterion ❌ or ⚠️, or critical code issues found |
|
||||
|
||||
Output: `TASK-001--review.md` with detailed findings.
|
||||
|
||||
**If FAILED:** Fix the issues and re-run task-implementation. The Ralph Loop automates this cycle.
|
||||
|
||||
### 3.2 Code Cleanup
|
||||
|
||||
```
|
||||
/developer-kit-specs:specs-code-cleanup --lang=spring --task="docs/specs/001-hotel-search/tasks/TASK-001.md"
|
||||
```
|
||||
|
||||
8-phase cleanup process:
|
||||
|
||||
1. Verify task is in `reviewed` status
|
||||
2. Identify files from review report and task provides
|
||||
3. Remove debug artifacts (`console.log`, `System.out.println`, temporary comments)
|
||||
4. Optimize imports
|
||||
5. Run formatters (`spotless:apply`, `prettier`, `black`)
|
||||
6. Verify documentation headers
|
||||
7. Run final tests
|
||||
8. Mark task as `completed`
|
||||
|
||||
### 3.3 Sync Specification
|
||||
|
||||
After completing tasks, sync the specification with the implementation:
|
||||
|
||||
```
|
||||
/specs:spec-sync-with-code docs/specs/001-hotel-search/
|
||||
```
|
||||
|
||||
This detects three types of deviations:
|
||||
|
||||
| Deviation Type | Example |
|
||||
|---------------|---------|
|
||||
| **Scope Expansion** | Added refresh token support not in original spec |
|
||||
| **Requirement Refinement** | Changed password policy from 8 to 12 characters |
|
||||
| **Scope Reduction** | Deferred 2FA to a future specification |
|
||||
|
||||
The sync command:
|
||||
- Compares acceptance criteria vs actual implementation
|
||||
- Proposes spec updates with revision markers
|
||||
- Creates new tasks for unexpected scope expansions
|
||||
- Updates the revision history section
|
||||
|
||||
### 3.4 Sync Context
|
||||
|
||||
```
|
||||
/specs:spec-sync-context docs/specs/001-hotel-search/
|
||||
```
|
||||
|
||||
This keeps technical context aligned:
|
||||
|
||||
1. **Gap Analysis** — Identifies discrepancies between Knowledge Graph, tasks, and codebase
|
||||
2. **Knowledge Graph Update** — Extracts new components, APIs, patterns from implemented code
|
||||
3. **Task Enrichment** — Updates task files with improved technical context
|
||||
4. **Drift Detection** — Checks if spec document reflects actual implementation
|
||||
|
||||
**Options:**
|
||||
```bash
|
||||
# Preview changes without writing
|
||||
/specs:spec-sync-context --spec="docs/specs/001-hotel-search/" --dry-run
|
||||
|
||||
# Update only the Knowledge Graph
|
||||
/specs:spec-sync-context --spec="docs/specs/001-hotel-search/" --update-kg-only
|
||||
|
||||
# Sync after a specific task
|
||||
/specs:spec-sync-context --spec="docs/specs/001-hotel-search/" --task="TASK-003"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automation: Ralph Loop
|
||||
|
||||
For multi-task implementations, the Ralph Loop automates the entire cycle:
|
||||
|
||||
```
|
||||
# Initialize the loop
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/001-hotel-search/
|
||||
|
||||
# Run one step (execute the shown command, then run again)
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=loop \
|
||||
--spec=docs/specs/001-hotel-search/
|
||||
```
|
||||
|
||||
Each `loop` invocation executes exactly one step from the state machine:
|
||||
|
||||
```
|
||||
choose_task → implementation → review → fix (if needed) → cleanup → sync → update_done → choose_task
|
||||
```
|
||||
|
||||
The Ralph Loop supports **multi-agent execution** — different AI agents can implement different tasks:
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: TASK-003
|
||||
title: Implement aggregation service
|
||||
agent: codex # Use Codex CLI for this task
|
||||
---
|
||||
```
|
||||
|
||||
Supported agents: `claude`, `codex`, `copilot`, `gemini`, `glm4`, `kimi`, `minimax`
|
||||
|
||||
### Fully Automated Orchestration
|
||||
|
||||
For hands-off execution, use `agents_loop.py` to automate the entire loop — no manual step execution needed:
|
||||
|
||||
```bash
|
||||
# Fully automated with auto agent selection and KPI quality gates
|
||||
python3 scripts/agents_loop.py \
|
||||
--spec=docs/specs/001-hotel-search/ \
|
||||
--agent=auto \
|
||||
--kpi-check
|
||||
```
|
||||
|
||||
This script calls `ralph_loop.py` internally, executes each command with the chosen agent, advances the state, and repeats until all tasks are complete. It supports `--fast` mode, `--reviewer` override, and automatic KPI-based quality iteration.
|
||||
|
||||
See the [Ralph Loop Guide](./ralph-loop-guide.md) for complete documentation of both manual and automated modes.
|
||||
|
||||
---
|
||||
|
||||
## File Structure Reference
|
||||
|
||||
A complete specification directory:
|
||||
|
||||
```
|
||||
docs/specs/001-hotel-search/
|
||||
├── 2026-04-10--hotel-search.md # Main functional specification
|
||||
├── 2026-04-10--hotel-search--tasks.md # Task index
|
||||
├── user-request.md # Original user input
|
||||
├── brainstorming-notes.md # Brainstorming session context
|
||||
├── decision-log.md # Decision audit trail
|
||||
├── traceability-matrix.md # Requirements → Tasks mapping
|
||||
├── knowledge-graph.json # Cached codebase analysis
|
||||
├── tasks/
|
||||
│ ├── TASK-001.md # Create data models
|
||||
│ ├── TASK-001--kpi.json # Auto-generated quality KPIs
|
||||
│ ├── TASK-001--review.md # Review report
|
||||
│ ├── TASK-002.md # Implement provider clients
|
||||
│ ├── TASK-002--kpi.json
|
||||
│ ├── TASK-003.md # Implement aggregation
|
||||
│ ├── TASK-004.md # REST API endpoints
|
||||
│ ├── TASK-005.md # E2E tests
|
||||
│ └── TASK-006.md # Cleanup and finalization
|
||||
├── _ralph_loop/
|
||||
│ └── fix_plan.json # Ralph Loop state (auto-managed)
|
||||
└── _drift/
|
||||
└── tdd-handoff-TASK-001.md # TDD handoff artifacts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real-World Example: Full Feature
|
||||
|
||||
Here's a concrete example implementing a **notification system** for a NestJS application:
|
||||
|
||||
```
|
||||
# 1. Brainstorm
|
||||
/specs:brainstorm Add a notification system with email, SMS, and push channels
|
||||
with template management and delivery tracking
|
||||
|
||||
# 2. Quality check
|
||||
/specs:spec-quality-check docs/specs/002-notification-system/
|
||||
|
||||
# 3. Generate tasks
|
||||
/specs:spec-to-tasks --lang=nestjs docs/specs/002-notification-system/
|
||||
→ Generates 8 tasks
|
||||
|
||||
# 4. List tasks
|
||||
/specs:task-manage --action=list --spec="docs/specs/002-notification-system/"
|
||||
TASK-001 [pending] Create notification entity and repository complexity: 35
|
||||
TASK-002 [pending] Implement template engine complexity: 50
|
||||
TASK-003 [pending] Build email channel adapter complexity: 40
|
||||
TASK-004 [pending] Build SMS channel adapter complexity: 40
|
||||
TASK-005 [pending] Build push notification adapter complexity: 45
|
||||
TASK-006 [pending] Create notification orchestration service complexity: 60
|
||||
TASK-007 [pending] Add REST API endpoints complexity: 35
|
||||
TASK-008 [pending] E2E tests and cleanup complexity: 30
|
||||
|
||||
# 5. Split complex task
|
||||
/specs:task-manage --action=split --task="docs/specs/002-notification-system/tasks/TASK-006.md"
|
||||
→ Split into TASK-006A (orchestrator) and TASK-006B (delivery tracking)
|
||||
|
||||
# 6. Implement each task
|
||||
/specs:task-implementation --lang=nestjs --task="docs/specs/002-notification-system/tasks/TASK-001.md"
|
||||
/specs:task-review --lang=nestjs docs/specs/002-notification-system/tasks/TASK-001.md
|
||||
/developer-kit-specs:specs-code-cleanup --lang=nestjs --task="docs/specs/002-notification-system/tasks/TASK-001.md"
|
||||
|
||||
# Repeat for TASK-002 through TASK-006B...
|
||||
|
||||
# 7. Final sync
|
||||
/specs:spec-sync-with-code docs/specs/002-notification-system/
|
||||
/specs:spec-sync-context docs/specs/002-notification-system/
|
||||
|
||||
# 8. Or automate everything with Ralph Loop
|
||||
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
|
||||
--action=start \
|
||||
--spec=docs/specs/002-notification-system/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hooks: Automatic Quality Gates
|
||||
|
||||
The plugin installs hooks that run automatically during your workflow:
|
||||
|
||||
| Hook | Trigger | What It Does |
|
||||
|------|---------|-------------|
|
||||
| `task-auto-status.py` | Edit any `TASK-*.md` file | Updates status based on checkbox changes |
|
||||
| `task-kpi-analyzer.py` | Edit any `TASK-*.md` file | Calculates quality KPIs to `TASK-XXX--kpi.json` |
|
||||
| `drift-init.py` | User submits a prompt | Initializes drift tracking for current spec |
|
||||
| `drift-monitor.py` | Write or Edit any file | Monitors for changes outside task scope |
|
||||
| `drift-report.py` | Task marked completed | Generates fidelity report |
|
||||
| Session Tracking | Claude finishes a response | Creates audit trail in `tracking_log.md` |
|
||||
|
||||
These hooks require no configuration — they activate automatically when the plugin is installed.
|
||||
@@ -0,0 +1,308 @@
|
||||
# TDD Workflow — Test-Driven Development with SDD
|
||||
|
||||
This guide covers the TDD integration within the Specification-Driven Development workflow.
|
||||
|
||||
## Overview
|
||||
|
||||
TDD in SDD follows the classic RED/GREEN cycle, integrated into the task implementation workflow:
|
||||
|
||||
```
|
||||
brainstorm → spec-to-tasks → task-tdd (RED) → task-implementation (GREEN) → task-review → code-cleanup
|
||||
```
|
||||
|
||||
The key difference from traditional TDD: tests are generated from the specification's acceptance criteria, ensuring tests validate the documented requirements.
|
||||
|
||||
## RED Phase
|
||||
|
||||
Generate failing tests before writing any production code.
|
||||
|
||||
### Command
|
||||
|
||||
```bash
|
||||
/specs:task-tdd --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-002.md"
|
||||
```
|
||||
|
||||
### What Happens
|
||||
|
||||
1. **Task Parsing** (`specs-task-tdd-parser.py` hook)
|
||||
- Reads the task file
|
||||
- Extracts acceptance criteria and contracts (provides/expects)
|
||||
- Identifies the target class/module to test
|
||||
|
||||
2. **Test Skeleton Generation** (`specs-task-tdd-generator.py` hook)
|
||||
- Creates a test file using the language-specific template
|
||||
- Generates test methods for each acceptance criterion
|
||||
- Each test asserts the expected behavior from the spec
|
||||
|
||||
3. **RED Phase Verification** (`specs-task-tdd-red-phase.py` hook)
|
||||
- Runs the generated tests
|
||||
- Confirms all tests FAIL (expected — no implementation yet)
|
||||
- Saves verification results
|
||||
|
||||
4. **Task File Update** (`specs-task-tdd-updater.py` hook)
|
||||
- Adds test file references to the task
|
||||
- Records RED phase completion status
|
||||
|
||||
5. **Implementation Handoff** (`specs-task-tdd-handoff.py` hook)
|
||||
- Creates a handoff artifact in `_drift/tdd-handoff-TASK-XXX.md`
|
||||
- Lists the test file, failing tests, and implementation hints
|
||||
|
||||
### Example Output
|
||||
|
||||
For a Spring Boot JWT token service task:
|
||||
|
||||
```java
|
||||
// Generated: src/test/java/com/example/auth/JwtTokenServiceTest.java
|
||||
|
||||
class JwtTokenServiceTest {
|
||||
|
||||
private JwtTokenService jwtTokenService;
|
||||
|
||||
@BeforeEach
|
||||
void setUp() {
|
||||
jwtTokenService = new JwtTokenService(secretKey, expirationMs);
|
||||
}
|
||||
|
||||
// AC-01: Generate valid JWT token from user credentials
|
||||
@Test
|
||||
void shouldGenerateValidJwtToken() {
|
||||
// Given
|
||||
UserDetails user = User.builder()
|
||||
.username("testuser")
|
||||
.password("encoded-password")
|
||||
.roles("USER")
|
||||
.build();
|
||||
|
||||
// When
|
||||
String token = jwtTokenService.generateToken(user);
|
||||
|
||||
// Then
|
||||
assertThat(token).isNotNull();
|
||||
assertThat(jwtTokenService.extractUsername(token)).isEqualTo("testuser");
|
||||
}
|
||||
|
||||
// AC-02: Validate token and return user details
|
||||
@Test
|
||||
void shouldValidateTokenAndReturnUsername() {
|
||||
// ... failing test
|
||||
}
|
||||
|
||||
// AC-03: Reject expired tokens
|
||||
@Test
|
||||
void shouldRejectExpiredTokens() {
|
||||
// ... failing test
|
||||
}
|
||||
|
||||
// AC-04: Support token refresh within grace period
|
||||
@Test
|
||||
void shouldSupportTokenRefreshWithinGracePeriod() {
|
||||
// ... failing test
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
All tests fail because `JwtTokenService` doesn't exist yet.
|
||||
|
||||
### Supported Languages and Templates
|
||||
|
||||
| Language | Framework | Test File Pattern | Template |
|
||||
|----------|-----------|-------------------|----------|
|
||||
| Spring | JUnit 5 + Mockito | `*Test.java` | `spring-test-template.java` |
|
||||
| Java | JUnit 5 | `*Test.java` | `java-test-template.java` |
|
||||
| NestJS | Jest | `*.spec.ts` | `nestjs-test-template.spec.ts` |
|
||||
| TypeScript | Jest / Mocha | `*.spec.ts` | `typescript-test-template.spec.ts` |
|
||||
| React | Jest + RTL | `*.test.tsx` | `react-test-template.test.tsx` |
|
||||
| Node.js | Jest | `*.test.ts` | `nodejs-test-template.test.ts` |
|
||||
| Python | pytest | `test_*.py` | `python-test-template.py` |
|
||||
| PHP | PHPUnit | `*Test.php` | `php-test-template.php` |
|
||||
|
||||
Templates are located at: `hooks/test-templates/`
|
||||
|
||||
## GREEN Phase
|
||||
|
||||
Implement production code to make the failing tests pass.
|
||||
|
||||
### Command
|
||||
|
||||
```bash
|
||||
/specs:task-implementation --lang=spring --task="docs/specs/001-user-auth/tasks/TASK-002.md"
|
||||
```
|
||||
|
||||
### What Happens
|
||||
|
||||
The implementation command detects the TDD handoff artifact and:
|
||||
1. Reads the test file and handoff notes
|
||||
2. Implements the minimal code to make tests pass
|
||||
3. Runs all tests to verify GREEN status
|
||||
4. Continues with the standard implementation verification
|
||||
|
||||
### Example
|
||||
|
||||
After implementing `JwtTokenService`:
|
||||
|
||||
```bash
|
||||
# Tests now pass
|
||||
./mvnw test -Dtest=JwtTokenServiceTest
|
||||
|
||||
# Results:
|
||||
# Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
|
||||
# GREEN ✓
|
||||
```
|
||||
|
||||
## Complete TDD Example: NestJS Notification Service
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Already have specification and tasks generated
|
||||
/specs:spec-to-tasks --lang=nestjs docs/specs/002-notification-system/
|
||||
```
|
||||
|
||||
### Task: Implement Template Engine (TASK-002)
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: TASK-002
|
||||
title: Implement notification template engine
|
||||
lang: nestjs
|
||||
status: pending
|
||||
provides: [TemplateEngineService, RenderedTemplate]
|
||||
expects: [TemplateRepository]
|
||||
---
|
||||
```
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] Parse template with variable placeholders `{{variable}}`
|
||||
- [ ] Render template with provided context data
|
||||
- [ ] Support conditional blocks `{{#if condition}}...{{/if}}`
|
||||
- [ ] Cache compiled templates for performance
|
||||
|
||||
### RED Phase
|
||||
|
||||
```bash
|
||||
/specs:task-tdd --lang=nestjs --task="docs/specs/002-notification/tasks/TASK-002.md"
|
||||
```
|
||||
|
||||
Generates:
|
||||
|
||||
```typescript
|
||||
// src/template-engine/template-engine.service.spec.ts
|
||||
|
||||
describe('TemplateEngineService', () => {
|
||||
let service: TemplateEngineService;
|
||||
|
||||
beforeEach(() => {
|
||||
service = new TemplateEngineService();
|
||||
});
|
||||
|
||||
// AC-01: Parse template with variable placeholders
|
||||
it('should parse template with variable placeholders', () => {
|
||||
const template = 'Hello {{name}}, welcome to {{platform}}!';
|
||||
const context = { name: 'Alice', platform: 'Developer Kit' };
|
||||
|
||||
const result = service.render(template, context);
|
||||
|
||||
expect(result).toBe('Hello Alice, welcome to Developer Kit!');
|
||||
});
|
||||
|
||||
// AC-02: Handle missing variables gracefully
|
||||
it('should handle missing variables gracefully', () => {
|
||||
const template = 'Hello {{name}}!';
|
||||
const context = {};
|
||||
|
||||
const result = service.render(template, context);
|
||||
|
||||
expect(result).toBe('Hello !');
|
||||
});
|
||||
|
||||
// AC-03: Support conditional blocks
|
||||
it('should support conditional blocks', () => {
|
||||
const template = 'Order {{#if premium}}priority{{/if}} shipping';
|
||||
const context = { premium: true };
|
||||
|
||||
const result = service.render(template, context);
|
||||
|
||||
expect(result).toBe('Order priority shipping');
|
||||
});
|
||||
|
||||
// AC-04: Cache compiled templates
|
||||
it('should cache compiled templates', () => {
|
||||
const template = 'Hello {{name}}!';
|
||||
|
||||
// First render compiles
|
||||
service.render(template, { name: 'Alice' });
|
||||
// Second render uses cache
|
||||
const result = service.render(template, { name: 'Bob' });
|
||||
|
||||
expect(result).toBe('Hello Bob!');
|
||||
expect(service.getCacheSize()).toBe(1);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
Tests fail: `TemplateEngineService` doesn't exist.
|
||||
|
||||
### GREEN Phase
|
||||
|
||||
```bash
|
||||
/specs:task-implementation --lang=nestjs --task="docs/specs/002-notification/tasks/TASK-002.md"
|
||||
```
|
||||
|
||||
Claude implements:
|
||||
|
||||
```typescript
|
||||
// src/template-engine/template-engine.service.ts
|
||||
|
||||
@Injectable()
|
||||
export class TemplateEngineService {
|
||||
private compiledTemplates = new Map<string, CompiledTemplate>();
|
||||
|
||||
render(template: string, context: Record<string, any>): string {
|
||||
const compiled = this.getOrCompile(template);
|
||||
return compiled(context);
|
||||
}
|
||||
|
||||
getCacheSize(): number {
|
||||
return this.compiledTemplates.size;
|
||||
}
|
||||
|
||||
private getOrCompile(template: string): CompiledTemplate {
|
||||
if (!this.compiledTemplates.has(template)) {
|
||||
this.compiledTemplates.set(template, this.compile(template));
|
||||
}
|
||||
return this.compiledTemplates.get(template)!;
|
||||
}
|
||||
|
||||
private compile(template: string): CompiledTemplate {
|
||||
// Compile variable placeholders and conditionals
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Tests pass. Proceed to review.
|
||||
|
||||
### Review
|
||||
|
||||
```bash
|
||||
/specs:task-review --lang=nestjs docs/specs/002-notification/tasks/TASK-002.md
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
|
||||
```bash
|
||||
/developer-kit-specs:specs-code-cleanup --lang=nestjs --task="docs/specs/002-notification/tasks/TASK-002.md"
|
||||
```
|
||||
|
||||
## When to Use TDD vs Direct Implementation
|
||||
|
||||
| Scenario | Approach |
|
||||
|----------|----------|
|
||||
| Complex business logic | TDD (RED first) |
|
||||
| Security-sensitive code | TDD (RED first) |
|
||||
| Algorithm implementation | TDD (RED first) |
|
||||
| Simple CRUD endpoints | Direct implementation |
|
||||
| Boilerplate code | Direct implementation |
|
||||
| UI components | Direct implementation |
|
||||
|
||||
TDD adds ~30% overhead per task but catches design issues early. Use it for tasks with complexity ≥50.
|
||||
@@ -78,7 +78,15 @@ docs/specs/[ID]/tasks/TASK-XXX--kpi.json
|
||||
| Test Coverage | 25% | Verification and confidence |
|
||||
| Contract Fulfillment | 20% | Integration with other tasks |
|
||||
|
||||
## Usage
|
||||
## When to Use
|
||||
|
||||
- Reading KPI data for task quality evaluation
|
||||
- Understanding quality metrics and scoring breakdown
|
||||
- Deciding whether to iterate or approve based on quantitative data
|
||||
- Integrating KPI checks into automated loops (`agents_loop.py`)
|
||||
- Generating evidence-based evaluation reports
|
||||
|
||||
## Instructions
|
||||
|
||||
### 1. Reading KPI Data (Primary Use)
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-tools",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "External tools integration skills for CLI utilities, APIs, and third-party services",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "developer-kit-typescript",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "TypeScript/JavaScript full-stack development with NestJS, React, and React Native",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "github-spec-kit",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"description": "GitHub specification integration and verification",
|
||||
"author": {
|
||||
"name": "Giuseppe Trisciuoglio",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "giuseppe-trisciuoglio/developer-kit",
|
||||
"version": "2.8.1",
|
||||
"version": "2.8.0",
|
||||
"private": false,
|
||||
"summary": "Comprehensive developer toolkit providing reusable skills for Java/Spring Boot, TypeScript/NestJS/React/Next.js, Python, PHP, AWS CloudFormation, AI/RAG, DevOps, and more.",
|
||||
"skills": {
|
||||
|
||||
@@ -1,59 +0,0 @@
|
||||
# Session Tracking Log
|
||||
|
||||
This file tracks development sessions, recording what was changed and why.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-09 — Session 73bf42df
|
||||
**Branch:** feature/improved-specs-flow
|
||||
**Orario:** 22:42
|
||||
|
||||
### Task eseguiti
|
||||
- Fix performance issue in TASK-003: session-tracker.py read_last_n_lines() function
|
||||
|
||||
### File modificati
|
||||
- `plugins/developer-kit-specs/scripts/session-tracker.py` (modificato)
|
||||
- `docs/specs/005-session-tracking-hook/tasks/TASK-003--review.md` (modificato)
|
||||
|
||||
### Rationale
|
||||
La funzione `read_last_n_lines()` in session-tracker.py utilizzava `deque(f, maxlen=n)` che, pur restituendo solo le ultime n righe, leggeva comunque l'intero contenuto del file prima di troncare. Questo violava il requisito esplicito di leggere **solo** le ultime 100 righe del transcript senza mai iterare il file completo. È stato implementato un seek-based tail reader che legge all'indietro dal fondo del file in blocchi di 8KB, accedendo solo alla porzione necessaria del file. Tutti i 33 test passano e il review file è stato aggiornato da FAILED a PASSED, completando TASK-003.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-09 — Session 89cddc6c
|
||||
**Branch:** feature/improved-specs-flow
|
||||
**Orario:** 22:27
|
||||
|
||||
### Task eseguiti
|
||||
- Fix TASK-003: session-tracker.py (3 major issues from previous review)
|
||||
- Implementare 33 test automatizzati per session-tracker.py
|
||||
|
||||
### File modificati
|
||||
- `plugins/developer-kit-specs/scripts/session-tracker.py` (modificato)
|
||||
- `plugins/developer-kit-specs/scripts/tests/test_session_tracker.py` (creato)
|
||||
|
||||
### Rationale
|
||||
Correzione di tre problemi critici identificati nella review precedente di session-tracker.py:
|
||||
1. **Efficienza lettura file**: Sostituito `f.readlines()` con `collections.deque(f, maxlen=n)` per leggere solo le ultime 100 righe senza caricare l'intero file in memoria (migliora performance con transcript di grandi dimensioni).
|
||||
2. **Estrazione path eliminati**: Aggiunto regex `_DELETE_PATH_PATTERN` per estrarre i path dei file dai comandi Bash `rm`, `rmdir`, `git rm` e includerli nella lista `modified_files` (era un requisito non implementato).
|
||||
3. **Copertura test**: Creato suite di 33 test automatizzati (`test_session_tracker.py`) che coprono: lettura efficiente (4 test), estrazione user messages (5 test), operazioni tool (8 test), redazione segreti (5 test), session ID (3 test), end-to-end (5 test), CLI (3 test). Tutti i 152 test totali del plugin passano (119 esistenti + 33 nuovi), soddisfacendo tutti gli acceptance criteria e DoD di TASK-003.
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-09 — Sessione 9e0da99e
|
||||
|
||||
## 2026-04-09 — Sessione 9e0da99e
|
||||
**Branch:** feature/improved-specs-flow
|
||||
**Orario:** 22:17
|
||||
|
||||
### Task eseguiti
|
||||
- Implementare TASK-003: Create session-tracker.py support script
|
||||
|
||||
### File modificati
|
||||
- `plugins/developer-kit-specs/scripts/session-tracker.py` (creato)
|
||||
|
||||
### Rationale
|
||||
Creato script Python standalone che estrae dati strutturati dal transcript JSONL di Claude Code. Lo script legge le ultime 100 righe del transcript, estrae gli ultimi 10 messaggi utente, conta le operazioni degli strumenti (Write, Edit, Delete) e traccia i file modificati. Tutte le credenziali, API key e token vengono redatti con [REDACTED]. Lo script gestisce gracilmente errori (file mancante, vuoto, malformato) ed esce sempre con 0. Implementato per supportare il session-tracking-agent nel hook Stop per generare entry in tracking_log.md.
|
||||
|
||||
### Commit
|
||||
- Nessun commit effettuato in questa sessione
|
||||
Reference in New Issue
Block a user