Skip to main content
Claude Code provides full sub-agent support via its Task tool. Each SDD phase runs in a fresh context window, making it ideal for complex feature development.

​
Prerequisites

  • Claude Code installed and configured
  • Git installed for cloning the repository
  • Access to ~/.claude/ directory

​
Installation Steps

1

Clone the repository

git clone https://github.com/gentleman-programming/agent-teams-lite.git
cd agent-teams-lite
2

Run the installer

./scripts/install.sh
# Choose option 1: Claude Code
This copies skills to ~/.claude/skills/sdd-*/You should see output like:
Installing skills for Claude Code...
  ✓ _shared (3 convention files)
  ✓ sdd-init
  ✓ sdd-explore
  ✓ sdd-propose
  ✓ sdd-spec
  ✓ sdd-design
  ✓ sdd-tasks
  ✓ sdd-apply
  ✓ sdd-verify
  ✓ sdd-archive

  9 skills installed → ~/.claude/skills
3

Add orchestrator to CLAUDE.md

The installer will prompt you to add orchestrator instructions to ~/.claude/CLAUDE.md.Open your existing CLAUDE.md file:
code ~/.claude/CLAUDE.md
Append the contents from examples/claude-code/CLAUDE.md to your existing file. This preserves your current assistant identity while adding SDD capabilities.
The orchestrator section teaches Claude Code to:
  • Detect SDD triggers (/sdd-new, feature descriptions, etc.)
  • Launch sub-agents via the Task tool
  • Pass skill file paths to sub-agents
  • Track state between phases
  • Follow artifact storage policies (engram/openspec/none)
Key sections added:
  • Artifact Store Policy (engram/openspec/none)
  • SDD Commands table
  • Command → Skill Mapping
  • Orchestrator Rules
  • Engram Artifact Convention
4

Verify installation

Open Claude Code in any project directory:
claude-code .
Type:
/sdd-init
Expected response:
Launching sdd-init sub-agent to bootstrap project context...
✓ Detected stack: [your project's stack]
✓ SDD initialized
If Claude Code doesn’t recognize the command, verify:
  1. Skills are in ~/.claude/skills/sdd-*/
  2. Orchestrator instructions are in ~/.claude/CLAUDE.md
  3. You’ve restarted Claude Code after making changes

​
Configuration Locations

Skills Directory

~/.claude/skills/sdd-*/Contains 9 skill folders + _shared/ conventions

Orchestrator Config

~/.claude/CLAUDE.mdYour main assistant configuration file

​
How It Works

Claude Code’s Task tool enables true sub-agent delegation: Each sub-agent:
  1. Gets launched via Task(subagent_type: 'general', prompt: 'Read skill at ~/.claude/skills/sdd-explore/SKILL.md...')
  2. Starts with fresh context (no history from orchestrator)
  3. Reads its skill instructions
  4. Executes the phase work
  5. Returns structured results to orchestrator

​
Example Usage

​
Initialize SDD

You: /sdd-init

Claude: Launching sdd-init sub-agent...
        ✓ Detected stack: React + TypeScript + Tailwind
        ✓ Project: my-app
        ✓ Artifact store: engram (Engram detected)
        
        SDD initialized. Ready to start building.

​
Start a New Feature

You: /sdd-new add-dark-mode

Claude: Launching explorer sub-agent to analyze codebase...
        ✓ Current theme: hardcoded light mode in globals.css
        ✓ No theme context detected
        
        Launching proposal sub-agent...
        ✓ Proposal created: sdd/add-dark-mode/proposal
        
        Summary:
        - Intent: Add dark mode toggle with system preference detection
        - Scope: Theme context, toggle component, CSS variables
        - Rollback: Remove ThemeProvider, revert CSS
        
        Ready to continue with specs and design? (or review proposal first)

​
Fast-Forward Planning

You: /sdd-ff add-dark-mode

Claude: Running all planning phases...
        
        Launching spec sub-agent...
        ✓ specs/ui/spec.md — 3 requirements, 7 scenarios
        
        Launching design sub-agent...
        ✓ design.md — CSS variables approach, React Context, localStorage
        
        Launching tasks sub-agent...
        ✓ tasks.md — 3 phases, 8 tasks
        
        All planning complete. Run /sdd-apply to implement.

​
Artifact Storage

Claude Code supports all three storage modes:

​
Verification Checklist

1

Check skills are installed

ls ~/.claude/skills/sdd-*/
Should show 9 directories:
sdd-apply/  sdd-design/    sdd-init/     sdd-spec/
sdd-archive/  sdd-explore/  sdd-propose/  sdd-tasks/  sdd-verify/
2

Check shared conventions

ls ~/.claude/skills/_shared/
Should show:
engram-convention.md
openspec-convention.md
persistence-contract.md
3

Verify CLAUDE.md contains SDD section

grep -i "sdd orchestrator" ~/.claude/CLAUDE.md
Should return matches if orchestrator instructions are present.
4

Test SDD command

claude-code .
# In Claude Code prompt:
# /sdd-init
Should recognize the command and launch sdd-init sub-agent.

​
Troubleshooting

Problem: Claude Code doesn’t recognize /sdd-initSolutions:
  1. Verify skills are in ~/.claude/skills/sdd-*/
  2. Check orchestrator instructions are appended to ~/.claude/CLAUDE.md
  3. Restart Claude Code to reload configuration
  4. Try alternative phrasing: “Initialize SDD” or “Start spec-driven development”
Problem: Orchestrator doesn’t use Task toolSolutions:
  1. Ensure orchestrator instructions mention Task tool explicitly
  2. Verify skill file paths are correct: ~/.claude/skills/sdd-{name}/SKILL.md
  3. Check Claude Code version supports Task tool (update if needed)
Problem: Results shown but not savedSolutions:
  1. Check artifact_store mode: engram requires Engram MCP server
  2. Verify Engram is running: check MCP server status
  3. Explicitly request openspec mode if you want file-based artifacts
  4. In none mode, persistence is intentionally disabled

​
Next Steps

Quick Start

Learn how to use SDD commands

Commands Reference

Complete command documentation

Engram Setup

Install recommended persistence backend

Workflow Guide

Understand the SDD workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us