sdd-init

OverviewHistoryStatsSecurity

npx skills add giuseppe-trisciuoglio/developer-kit --skill sdd-init

Documentation

SKILL.md

npx skills add ...

Documentation

SKILL.md

Initialize Spec-Driven Development context — detects tech stack, conventions, architecture patterns, and bootstraps persistence backends. Triggers on 'sdd-init', 'init sdd', 'setup sdd', 'initialize sdd', 'setup project', 'initialize project context'. Creates/updates docs/specs/architecture.md & ontology.md (Constitution), and populates knowledge-graph.json.

This skill's source file could not be loaded. The install command may not work.

npx skills add giuseppe-trisciuoglio/developer-kit --skill sdd-init

Documentation

SKILL.mdView source

SDD Init Skill

Initialize Spec-Driven Development (SDD) in the current project. Detects tech stack, conventions, architecture patterns, and bootstraps all persistence backends (Constitution + Knowledge Graph).

When to Use

Trigger phrases:

"sdd-init", "init sdd", "setup sdd"
"initialize sdd", "setup project", "initialize project context"
"bootstrap sdd", "start sdd"
"detect project stack", "detect tech stack"

Workflow

1. Detect Project Context
   ├── Scan tech stack (languages, frameworks, tools)
   ├── Identify conventions (folder structure, patterns, configs)
   └── Detect architecture (monolith, microservices, serverless)

2. Bootstrap Constitution
   ├── Check if docs/specs/architecture.md exists
   ├── If missing → ask user to create with constitution skill
   └── If exists → show current state

3. Bootstrap Knowledge Graph
   ├── Check if docs/specs/knowledge-graph.json exists
   ├── Create with initial discoveries (stack, patterns, conventions)
   └── Link to Constitution

4. Return Structured Result
   └── status, executive_summary, artifacts, next_recommended

Phase 1: Detect Project Context

1.1 Scan Tech Stack

Detect the primary language and framework:

# Detect language (priority order)
ls *.go *.rs *.ts *.js *.py *.java *.cs *.rb *.php *.cpp *.c 2>/dev/null | head -1
 
# Detect framework/type
ls package.json pyproject.toml Cargo.toml go.mod pom.xml *.csproj Gemfile composer.json 2>/dev/null
 
# Detect project type
ls -la src/ lib/ app/ cmd/ internal/ pkg/ services/ 2>/dev/null

1.2 Identify Conventions

Scan for existing patterns:

# Folder structure
find . -maxdepth 2 -type d -name "src" -o -name "lib" -o -name "app" -o -name "cmd" | head -10
 
# Config files
ls -la *.yaml *.yml *.toml *.json *.env* Makefile 2>/dev/null
 
# Testing patterns
find . -name "*_test.*" -o -name "test_*.py" -o -name "*_test.go" -o -name "*.spec.ts" 2>/dev/null | head -10
 
# Build system
ls Makefile Dockerfile docker-compose*.yml *.mk 2>/dev/null
 
# CI/CD
ls .github/workflows/ .gitlab-ci.yml .circleci/ 2>/dev/null

1.3 Detect Architecture Style

Analyze project structure for architectural patterns:

# Microservices vs Monolith
ls services/ microservices/ cmd/ api/ internal/ 2>/dev/null
 
# Serverless
ls functions/ lambda/ handlers/ 2>/dev/null
 
# Layered architecture
ls controllers/ services/ repositories/ models/ 2>/dev/null
 
# Hexagonal/Ports & Adapters
ls ports/ adapters/ domain/ infrastructure/ 2>/dev/null

Phase 2: Bootstrap Constitution

2.1 Check Existence

# Check if Constitution files exist
[ -f docs/specs/architecture.md ] && echo "architecture:exists" || echo "architecture:missing"
[ -f docs/specs/ontology.md ] && echo "ontology:exists" || echo "ontology:missing"

2.2 If Missing → Ask User

Use AskUserQuestion to prompt:

The Constitution files (architecture.md, ontology.md) don't exist yet.

Option 1: Create both (Recommended) - Sets up architectural DNA and domain language Option 2: Create architecture.md only Option 3: Create ontology.md only
Option 4: Skip for now - I'll detect context but skip Constitution

If user chooses option 1-3, delegate to /developer-kit-specs:constitution create with the detected context.

2.3 If Exists → Show Current State

Read and display current Constitution files with detected context as comparison.

Phase 3: Bootstrap Knowledge Graph

3.1 Check Existence

# Check if KG exists
ls docs/specs/knowledge-graph.json 2>/dev/null

3.2 Create/Update KG

Create or update docs/specs/knowledge-graph.json with initial discoveries:

{
  "metadata": {
    "spec_id": "project-init",
    "version": "1.0.0",
    "created": "{{ISO_DATE}}",
    "project": "{{PROJECT_NAME}}",
    "type": "initial-discovery"
  },
  "context": {
    "workingDirectory": "{{PWD}}",
    "projectName": "{{PROJECT_NAME}}"
  },
  "stack": {
    "primaryLanguage": "{{DETECTED_LANGUAGE}}",
    "framework": "{{DETECTED_FRAMEWORK}}",
    "buildSystem": "{{DETECTED_BUILD_SYSTEM}}"
  },
  "conventions": {
    "folderStructure": ["{{FOLDERS}}"],
    "namingPatterns": ["{{PATTERNS}}"],
    "configFiles": ["{{CONFIGS}}"],
    "testingPattern": "{{TESTING_PATTERN}}"
  },
  "architecture": {
    "style": "{{MONOLITH|MICROSERVICE|SERVERLESS|LAYERED|HEXAGONAL}}",
    "layers": ["{{LAYERS}}"],
    "patterns": ["{{ARCHITECTURAL_PATTERNS}}"]
  },
  "references": {
    "constitution": "docs/specs/architecture.md",
    "ontology": "docs/specs/ontology.md"
  },
  "source": "sdd-init"
}

3.3 Validation

After creating KG, validate it exists and has valid JSON:

# Validate KG
cat docs/specs/knowledge-graph.json | python3 -m json.tool > /dev/null && echo "KG:valid" || echo "KG:invalid"

Phase 4: Return Structured Result

Return a JSON object with:

{
  "status": "success|partial|skipped",
  "executive_summary": "Brief description of what was detected and initialized",
  "artifacts": [
    {
      "path": "docs/specs/architecture.md",
      "action": "created|existing|skipped",
      "summary": "What this file contains"
    },
    {
      "path": "docs/specs/ontology.md",
      "action": "created|existing|skipped", 
      "summary": "What this file contains"
    },
    {
      "path": "docs/specs/knowledge-graph.json",
      "action": "created|updated",
      "summary": "What was discovered and stored"
    }
  ],
  "next_recommended": [
    "Review Constitution if just created",
    "Run brainstorm to start first spec",
    "Check knowledge-graph.json for detected patterns"
  ]
}

Output Format

Display result in a structured format:

══════════════════════════════════════════════════
SDD Init — {{PROJECT_NAME}}
══════════════════════════════════════════════════

STATUS: {{status}}

TECH STACK DETECTED:
  Language: {{language}}
  Framework: {{framework}}
  Build: {{build_system}}

ARCHITECTURE:
  Style: {{architecture_style}}
  Patterns: {{patterns}}

ARTIFACTS:
  ✓ Constitution (architecture.md) — {{status}}
  ✓ Constitution (ontology.md) — {{status}}
  ✓ Knowledge Graph — {{status}}

NEXT STEPS:
  {{next_recommended}}

══════════════════════════════════════════════════

Integration with Other Skills

Skill	Integration Point
`constitution`	Created/updated by sdd-init if missing
`knowledge-graph`	Populated by sdd-init with initial discoveries
`brainstorm`	Should read Constitution before starting
`spec-to-tasks`	Should validate against KG and Constitution
`task-implementation`	Should check KG for existing patterns

Constraints and Warnings

Read-only detection — Does NOT modify source code
Non-destructive — Only creates new files, never overwrites existing content
Permission check — Warn if docs/specs/ cannot be created
Backup KG — If updating existing KG, preserve existing data

Error Handling

Error	Recovery
Cannot create docs/specs/	Ask user to create directory manually
KG JSON invalid	Show error, keep raw file, suggest validation
Constitution delegate fails	Fall back to inline creation with template

npx skills add giuseppe-trisciuoglio/developer-kit --skill sdd-init

Documentation

SKILL.md

This skill's source file could not be loaded. The install command may not work.

npx skills add giuseppe-trisciuoglio/developer-kit --skill sdd-init

Documentation

SKILL.mdView source

SDD Init Skill

Initialize Spec-Driven Development (SDD) in the current project. Detects tech stack, conventions, architecture patterns, and bootstraps all persistence backends (Constitution + Knowledge Graph).

When to Use

Trigger phrases:

"sdd-init", "init sdd", "setup sdd"
"initialize sdd", "setup project", "initialize project context"
"bootstrap sdd", "start sdd"
"detect project stack", "detect tech stack"

Workflow

1. Detect Project Context
   ├── Scan tech stack (languages, frameworks, tools)
   ├── Identify conventions (folder structure, patterns, configs)
   └── Detect architecture (monolith, microservices, serverless)

2. Bootstrap Constitution
   ├── Check if docs/specs/architecture.md exists
   ├── If missing → ask user to create with constitution skill
   └── If exists → show current state

3. Bootstrap Knowledge Graph
   ├── Check if docs/specs/knowledge-graph.json exists
   ├── Create with initial discoveries (stack, patterns, conventions)
   └── Link to Constitution

4. Return Structured Result
   └── status, executive_summary, artifacts, next_recommended

Phase 1: Detect Project Context

1.1 Scan Tech Stack

Detect the primary language and framework:

# Detect language (priority order)
ls *.go *.rs *.ts *.js *.py *.java *.cs *.rb *.php *.cpp *.c 2>/dev/null | head -1
 
# Detect framework/type
ls package.json pyproject.toml Cargo.toml go.mod pom.xml *.csproj Gemfile composer.json 2>/dev/null
 
# Detect project type
ls -la src/ lib/ app/ cmd/ internal/ pkg/ services/ 2>/dev/null

1.2 Identify Conventions

Scan for existing patterns:

# Folder structure
find . -maxdepth 2 -type d -name "src" -o -name "lib" -o -name "app" -o -name "cmd" | head -10
 
# Config files
ls -la *.yaml *.yml *.toml *.json *.env* Makefile 2>/dev/null
 
# Testing patterns
find . -name "*_test.*" -o -name "test_*.py" -o -name "*_test.go" -o -name "*.spec.ts" 2>/dev/null | head -10
 
# Build system
ls Makefile Dockerfile docker-compose*.yml *.mk 2>/dev/null
 
# CI/CD
ls .github/workflows/ .gitlab-ci.yml .circleci/ 2>/dev/null

1.3 Detect Architecture Style

Analyze project structure for architectural patterns:

# Microservices vs Monolith
ls services/ microservices/ cmd/ api/ internal/ 2>/dev/null
 
# Serverless
ls functions/ lambda/ handlers/ 2>/dev/null
 
# Layered architecture
ls controllers/ services/ repositories/ models/ 2>/dev/null
 
# Hexagonal/Ports & Adapters
ls ports/ adapters/ domain/ infrastructure/ 2>/dev/null

Phase 2: Bootstrap Constitution

2.1 Check Existence

# Check if Constitution files exist
[ -f docs/specs/architecture.md ] && echo "architecture:exists" || echo "architecture:missing"
[ -f docs/specs/ontology.md ] && echo "ontology:exists" || echo "ontology:missing"

2.2 If Missing → Ask User

Use AskUserQuestion to prompt:

The Constitution files (architecture.md, ontology.md) don't exist yet.

Option 1: Create both (Recommended) - Sets up architectural DNA and domain language Option 2: Create architecture.md only Option 3: Create ontology.md only
Option 4: Skip for now - I'll detect context but skip Constitution

If user chooses option 1-3, delegate to /developer-kit-specs:constitution create with the detected context.

2.3 If Exists → Show Current State

Read and display current Constitution files with detected context as comparison.

Phase 3: Bootstrap Knowledge Graph

3.1 Check Existence

# Check if KG exists
ls docs/specs/knowledge-graph.json 2>/dev/null

3.2 Create/Update KG

Create or update docs/specs/knowledge-graph.json with initial discoveries:

{
  "metadata": {
    "spec_id": "project-init",
    "version": "1.0.0",
    "created": "{{ISO_DATE}}",
    "project": "{{PROJECT_NAME}}",
    "type": "initial-discovery"
  },
  "context": {
    "workingDirectory": "{{PWD}}",
    "projectName": "{{PROJECT_NAME}}"
  },
  "stack": {
    "primaryLanguage": "{{DETECTED_LANGUAGE}}",
    "framework": "{{DETECTED_FRAMEWORK}}",
    "buildSystem": "{{DETECTED_BUILD_SYSTEM}}"
  },
  "conventions": {
    "folderStructure": ["{{FOLDERS}}"],
    "namingPatterns": ["{{PATTERNS}}"],
    "configFiles": ["{{CONFIGS}}"],
    "testingPattern": "{{TESTING_PATTERN}}"
  },
  "architecture": {
    "style": "{{MONOLITH|MICROSERVICE|SERVERLESS|LAYERED|HEXAGONAL}}",
    "layers": ["{{LAYERS}}"],
    "patterns": ["{{ARCHITECTURAL_PATTERNS}}"]
  },
  "references": {
    "constitution": "docs/specs/architecture.md",
    "ontology": "docs/specs/ontology.md"
  },
  "source": "sdd-init"
}

3.3 Validation

After creating KG, validate it exists and has valid JSON:

# Validate KG
cat docs/specs/knowledge-graph.json | python3 -m json.tool > /dev/null && echo "KG:valid" || echo "KG:invalid"

Phase 4: Return Structured Result

Return a JSON object with:

{
  "status": "success|partial|skipped",
  "executive_summary": "Brief description of what was detected and initialized",
  "artifacts": [
    {
      "path": "docs/specs/architecture.md",
      "action": "created|existing|skipped",
      "summary": "What this file contains"
    },
    {
      "path": "docs/specs/ontology.md",
      "action": "created|existing|skipped", 
      "summary": "What this file contains"
    },
    {
      "path": "docs/specs/knowledge-graph.json",
      "action": "created|updated",
      "summary": "What was discovered and stored"
    }
  ],
  "next_recommended": [
    "Review Constitution if just created",
    "Run brainstorm to start first spec",
    "Check knowledge-graph.json for detected patterns"
  ]
}

Output Format

Display result in a structured format:

══════════════════════════════════════════════════
SDD Init — {{PROJECT_NAME}}
══════════════════════════════════════════════════

STATUS: {{status}}

TECH STACK DETECTED:
  Language: {{language}}
  Framework: {{framework}}
  Build: {{build_system}}

ARCHITECTURE:
  Style: {{architecture_style}}
  Patterns: {{patterns}}

ARTIFACTS:
  ✓ Constitution (architecture.md) — {{status}}
  ✓ Constitution (ontology.md) — {{status}}
  ✓ Knowledge Graph — {{status}}

NEXT STEPS:
  {{next_recommended}}

══════════════════════════════════════════════════

Integration with Other Skills

Skill	Integration Point
`constitution`	Created/updated by sdd-init if missing
`knowledge-graph`	Populated by sdd-init with initial discoveries
`brainstorm`	Should read Constitution before starting
`spec-to-tasks`	Should validate against KG and Constitution
`task-implementation`	Should check KG for existing patterns

Constraints and Warnings

Read-only detection — Does NOT modify source code
Non-destructive — Only creates new files, never overwrites existing content
Permission check — Warn if docs/specs/ cannot be created
Backup KG — If updating existing KG, preserve existing data

Error Handling

Error	Recovery
Cannot create docs/specs/	Ask user to create directory manually
KG JSON invalid	Show error, keep raw file, suggest validation
Constitution delegate fails	Fall back to inline creation with template