sdd-toolkit (Universal Spec CLI)

!npm version
!License: MIT
!Downloads

CLI tool to automatically set up the development environment and install AI agents (Auditor, Coder, etc.) for various modern AI tools.

Overview

sdd-toolkit is an "AI Agent Package Manager". It defines a standard squad of AI Developers and installs them directly into the context of your favorite AI Coding Assistant (such as Gemini, Cline, Kilo Code, OpenCode).

The main idea is to stop creating prompts from scratch and install a proven, structured workflow.

📑 Table of Contents

- Overview
- Key Features
- The Squad
- Installation and Usage
- How it Works
- Development Workflow
- AI Tool Commands
- Generated Files Structure
- Usage Examples
- Troubleshooting
- FAQ
- Project Structure
- License

🚀 Key Features

$3

- Hybrid Flow: Supports both "Waterfall" planning (for new projects) and "Agile" execution (for hotfixes/features).
- Smart Context: Agents automatically scan your package.json, go.mod, or requirements.txt to understand your stack. No more explaining "I use React" every time.
- Unified Memory: All context is stored in a hidden .sdd-toolkit/ folder, keeping your root directory clean.

$3

The toolkit supports English, Portuguese (Brazil), and Spanish. Agents automatically adapt their responses to your preferred language.

$3

Reads agnostic definitions (YAML) and converts them to specific formats:

- Gemini CLI: Generates .toml configuration files.
- Cline: Generates custom modes (_custom_modes.json) and context rules in .cline/.
- GitHub Copilot: Generates instructions in .github/prompts.md and agents in .github/prompts/*.md.
- Cursor: Generates rules in .cursor/commands/*.mdc.
- Windsurf: Generates workflows in .windsurf/workflows/*.md.
- Trae: Generates instructions in .trae/instructions.md.
- OpenCode: Generates skills in .opencode/skills/.
- Kilo Code: Generates Markdown prompts (.kilocode/workflows/*.md).

👥 The Squad (Agent Roles)

The system installs a team of specialized agents:

$3

- @Project Architect: Defines the scope and principles.
- @Requirements Engineer: Defines the tech stack (Auto-detected).

$3

- @Feature Manager: Manages features, milestones, and tasks.
- @Coder: The senior developer. Implements code following SOLID principles.

$3

- @QA Engineer: Reviews code against the spec.
- @Release Manager: Consolidates logs and manages the changelog.
- @SDD Helper: Provides access to all agents and help.

Installation and Usage

$3

Run the tool directly via npx without prior installation:

``bash
npx sdd-toolkit
`

$3

Check your current project status:

`bash
sdd-toolkit view
`

$3

Update installed agents without reconfiguration:

`bash
sdd-toolkit upgrade
`

$3

$3

Check your current project status:

`bash
sdd-toolkit view
`

$3

Update installed agents without reconfiguration:

`bash
sdd-toolkit upgrade
`

$3

Or install globally:

`bash
npm install -g sdd-toolkit
sdd-toolkit
`

How it Works

1. Initialization: The wizard detects your tools and sets up the hidden .sdd-toolkit/ context folder.
2. Agent Building: Reads the agent definitions (YAML) and compiles them into your AI tool's native format.
3. Execution: Interact with agents using simplified commands (e.g., /project, /coder, /feature).

Development Workflow

The sdd-toolkit provides a structured workflow with specialized agents:

$3

- Command: /project
- Creates .sdd-toolkit/project.md with project scope and principles.

$3

- Command: /requirements
- Analyzes your stack and creates .sdd-toolkit/requirements.md.

$3

- Command: /feature
- Creates .sdd-toolkit/features/[name].md with milestones and tasks.

$3

- Command: /coder [task-id]
- Implements tasks from feature plan and logs work.

$3

- Command: /review [task-id]
- QA Engineer reviews implementation against requirements.

$3

- Command: /log or /dev:release
- Consolidates logs into changelog and archives completed work.

AI Tool Commands

Once agents are installed, use these commands in your AI coding assistant:

$3

- /sdd - Display available agents and help
- /sdd.project - Activate Project Architect
- /sdd.requirements - Activate Requirements Engineer
- /sdd.feature - Activate Feature Manager
- /sdd.coder - Activate Coder
- /sdd.review - Activate QA Engineer
- /sdd.log - Activate Release Manager

$3

- /dev:review [Task_ID] - Trigger code review for a specific task
- /dev:release - Consolidate logs and create changelog

Generated Files Structure

After running sdd-toolkit, the following structure is created in your project:

`
.sdd-toolkit/
├── project.md # Project scope and principles
├── requirements.md # Technical requirements and stack
├── milestones.md # Development roadmap
├── task.md # Task execution backlog
├── features/ # Individual feature specifications
│ └── [feature-name].md
├── logs/
│ ├── executions/ # Task execution logs
│ ├── reviews/ # Code review reports
│ └── archive/ # Archived completed work
└── agents/ # Custom agent definitions (optional overrides)
`

Project Structure

- definitions/: YAML agent definitions
- templates/: Documentation templates
- src/: CLI source code

Usage Examples

$3

1. Define project:

`
/sdd.project
`

Creates .sdd-toolkit/project.md with scope and principles.

2. Define technical requirements:

`
/sdd.requirements
`

Analyzes your package.json/go.mod and creates .sdd-toolkit/requirements.md.

3. Plan a new feature:

`
/sdd.feature
`

Specify your feature (e.g., "Add user authentication"). Creates .sdd-toolkit/features/auth.md.

4. Implement tasks:

`
/sdd.coder MT01-task-1
`

Coder implements task following SOLID principles and logs work.

5. Review implementation:

`
/sdd.review MT01-task-1
`

QA Engineer validates implementation against requirements.

6. Release changes:
`
/sdd.log
`
Consolidates logs into changelog and archives completed work.

$3

1. Use Coder directly:

`
/sdd.coder fix-login-bug
`

Coder analyzes, fixes, and documents change.

2. Review fix:
`
/sdd.review fix-login-bug
`
Validates that fix meets requirements.

License

MIT

---

Troubleshooting

$3

Problem: After running sdd-toolkit, agents don't appear in your AI coding assistant.

Solutions:

- Cline: Check if you've configured Custom Modes in your settings. See the warning message after installation.
- Cursor: Restart the IDE after installation.
- OpenCode: Refresh the command palette.
- Gemini CLI: Verify .gemini/commands/dev/ folder exists with .toml files.

$3

Problem: Getting "Permission denied" or EACCES error when running npx sdd-toolkit.

Solutions:

- Option 1: Run with elevated permissions (not recommended):
`bash
sudo npx sdd-toolkit
`
- Option 2: Fix npm permissions:
`bash
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
`
- Option 3: Install globally with sudo:
`bash
sudo npm install -g sdd-toolkit
`

$3

Problem: Agents are not responding in your preferred language.

Solution:

- Re-run sdd-toolkit and ensure you select the correct language during setup (English, Portuguese, or Spanish).
- Or manually edit the LANGUAGE_RULES in your agent files.

$3

Problem: The hidden folder structure is not created after installation.

Solutions:

- Check that you're running the command from your project's root directory (where package.json is located).
- Verify write permissions in the directory.
- Check for error messages during installation.

❓ Frequently Asked Questions

Q: Can I use multiple AI assistants simultaneously?

A: Yes! You can install agents for multiple AI tools in the same project. Each tool has its own folder structure (.cline/, .cursor/, etc.) and they can coexist without conflicts.

Q: How do I update agents after initial setup?

A: Run sdd-toolkit upgrade. This will update all installed agents without requiring you to reconfigure global rules.

Q: Can I customize agent definitions?

A: Yes! Create custom YAML files in .sdd-toolkit/agents/ folder. The toolkit will use your custom versions instead of the default ones. You can copy and modify the default definitions from the definitions/ folder in the toolkit.

Q: What happens if I run sdd-toolkit multiple times?

A: The tool is idempotent - running it again will only update or regenerate missing files without duplicating existing configurations. Your existing project docs in .sdd-toolkit/ will be preserved.

Q: Can I use this with projects that already have existing code?

A: Yes! The "Requirements Engineer" agent can analyze your existing package.json, go.mod, or requirements.txt to auto-detect your stack. The "Project Architect" can also formalize existing projects in "hybrid" mode.

Q: Do I need to commit .sdd-toolkit/ to my repository?

A: Yes, it's recommended. The .sdd-toolkit/ folder contains your project documentation, specifications, and agent configurations. Committing them ensures consistency across your team and preserves context for future sessions.

Q: How do I remove sdd-toolkit from my project?

A: Simply delete the .sdd-toolkit/ folder and any tool-specific folders (.cline/, .cursor/, etc.). These are all generated files and won't affect your source code.

Q: Are my code changes tracked by sdd-toolkit?

A: No, sdd-toolkit only manages documentation and AI agent configurations. It does not track code changes, read your source files, or interfere with version control.

Q: How do I define my tech stack and conventions?

A: Use the Requirements Engineer agent (/sdd.requirements) to define your tech stack. The agent will interview you with detailed questions about frontend, backend, database, and infrastructure. Stack-specific conventions can also be added via "Global Rules" during setup or by manually editing .sdd-toolkit/requirements.md.

Q: Is this suitable for enterprise projects?

A: Yes, sdd-toolkit is designed to scale. The .sdd-toolkit/ folder can be committed to your repository, ensuring all team members use the same agent configurations and follow the same development principles defined in requirements.md and project.md`. Stack-specific conventions are automatically applied via selected profile during agent installation.