sdd-toolkit 2.0.2 → 3.0.0

package/README.md

@@ -51,7 +51,7 @@ Reads agnostic definitions (YAML) and converts them to specific formats:
 - **Cursor:** Generates rules in `.cursor/commands/*.mdc`.
 - **Windsurf:** Generates workflows in `.windsurf/workflows/*.md`.
 - **Trae:** Generates instructions in `.trae/instructions.md`.
-- **OpenCode:** Generates agents in `.opencode/commands/*.md`.
+- **OpenCode:** Generates skills in `.opencode/skills/`.
 - **Kilo Code:** Generates Markdown prompts (`.kilocode/workflows/*.md`).
 
 ## 👥 The Squad (Agent Roles)
@@ -190,17 +190,17 @@ Once agents are installed, use these commands in your AI coding assistant:
 
 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
+```
+.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)
 ```
@@ -327,7 +327,7 @@ MIT
 - 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.
 
-### `.sdd-toolkit/` folder not created
+### `.sdd-toolkit/` folder not created
 
 **Problem:** The hidden folder structure is not created after installation.
 
@@ -343,9 +343,9 @@ MIT
 
 A: Yes! You can install agents for multiple AI tools in the same project. Each tool has its own folder structure (`.roo/`, `.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: 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?**
 
@@ -371,10 +371,10 @@ A: Simply delete the `.sdd-toolkit/` folder and any tool-specific folders (`.roo
 
 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: 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?**
 
-**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.
+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.

package/definitions/AGENTS.md

@@ -0,0 +1,114 @@
+# AGENTS.md — SDD Toolkit
+
+This document describes the agent and skill structure of SDD Toolkit to guide coding agents.
+
+## Overview
+
+SDD Toolkit is a collaborative agent system for specification-driven development. Agents work as a team, each with specific responsibilities.
+
+## Available Agents
+
+| Command | Agent | Emoji | Responsibility |
+|---------|--------|-------|----------------|
+| `/sdd.project` | Project Architect | 🏛️ | Defines project scope and vision |
+| `/sdd.requirements` | Requirements Engineer | 📝 | Documents requirements and tech stack |
+| `/sdd.feature` | Feature Manager | ✨ | Manages features and milestones |
+| `/sdd.coder` | Coder | 💻 | Implements code following SOLID |
+| `/sdd.frontend` | Frontend Architect | 🎨 | Design and UI/UX (framework-agnostic) |
+| `/sdd.backend` | Backend Architect | ⚙️ | APIs and server-side systems (agnostic) |
+| `/sdd.test` | Test Engineer | 🧪 | Automated testing and TDD |
+| `/sdd.review` | QA Engineer | 🔍 | Reviews and validates code quality |
+| `/sdd.security` | Security Auditor | 🛡️ | Security analysis following OWASP Top 10 |
+| `/sdd.prompt` | Prompt Architect | 🧠 | Creates AI prompts and agents |
+| `/sdd.log` | Release Manager | 📦 | Consolidates logs and manages changelog |
+
+## Workflow
+
+```
+Project Architect → Requirements Engineer → Feature Manager → Coder → Security Auditor → QA Engineer → Release Manager
+       🏛️                    📝                   ✨            💻            🛡️               🔍              📦
+```
+
+## File Structure
+
+```
+definitions/
+├── AGENTS.md                    # This file (main index)
+├── sdd-project.yaml             # Project Architect
+├── sdd-requirements.yaml        # Requirements Engineer
+├── sdd-feature.yaml             # Feature Manager
+├── sdd-coder.yaml               # Coder
+├── sdd-frontend.yaml            # Frontend Architect (Agnostic)
+├── sdd-backend.yaml             # Backend Architect (Agnostic)
+├── sdd-test.yaml                # Test Engineer (TDD)
+├── sdd-review.yaml              # QA Engineer
+├── sdd-security.yaml            # Security Auditor (OWASP)
+├── sdd-prompt.yaml              # Prompt Architect (Meta-Agent)
+├── sdd-log.yaml                 # Release Manager
+└── skills/                      # Reusable skills
+    ├── handover-protocol/
+    │   └── SKILL.md
+    └── detect-manifest/
+        └── SKILL.md
+```
+
+## Available Skills
+
+Skills are reusable instruction modules that agents can load on demand.
+
+| Skill | Description | Used By |
+|-------|-------------|---------|
+| `handover-protocol` | Handover protocol between agents | All |
+| `detect-manifest` | Detects manifests and identifies tech stack | Project, Requirements, Coder |
+
+### How to Use a Skill
+
+1. Read the `skills/[name]/SKILL.md` file before executing
+2. Follow the instructions contained in the skill
+3. Return to main flow after completion
+
+## Generated Artifacts
+
+Agents generate documentation in the `.sdd-toolkit/` folder:
+
+```
+.sdd-toolkit/
+├── project.md              # Conceptual scope (Project Architect)
+├── requirements.md         # Requirements and stack (Requirements Engineer)
+├── context.md              # Feature matrix
+├── features/               # Active features
+│   └── [feature-slug]/
+│       ├── index.md        # Feature overview
+│       ├── state.md        # Progress and context
+│       ├── MT01.md         # Milestone 1 with tasks
+│       ├── MT02.md         # Milestone 2 with tasks
+│       └── ...             # (MTXX = Milestone XX)
+└── logs/                   # Execution history
+    ├── executions/         # Executed task logs
+    ├── reviews/            # Review reports
+    └── archive/            # Archived logs after release
+```
+
+## Build and Test Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run CLI
+npm start
+
+# Check available agents
+node src/index.js
+```
+
+## Code Conventions
+
+- **Language**: English for documentation and responses
+- **Agent format**: YAML with frontmatter
+- **Skill format**: Markdown with YAML frontmatter
+- **Handover**: Always use the handover protocol
+
+## Reference
+
+This format follows the [AGENTS.md](https://agents.md/) convention for compatibility with multiple coding agents.

package/definitions/RULES.md

@@ -0,0 +1,248 @@
+# RULES.md — SDD Toolkit Usage Rules
+
+This document defines usage rules, folder structure, and where to document each type of artifact.
+
+---
+
+## 📁 Target Project Folder Structure
+
+All agents work with the `.sdd-toolkit/` folder in the target project:
+
+```
+.sdd-toolkit/
+├── project.md              # Conceptual project scope
+├── requirements.md         # Functional requirements + Tech stack
+├── context.md              # Feature matrix (global view)
+├── system.md               # System state (deploys, migrations)
+│
+├── features/               # Active features
+│   └── [feature-slug]/
+│       ├── index.md        # Feature overview
+│       ├── state.md        # Progress + context + created files
+│       ├── MT01.md         # Milestone 1 with tasks
+│       ├── MT02.md         # Milestone 2 with tasks
+│       └── ...
+│
+└── logs/                   # Execution history
+    ├── executions/         # Executed task logs
+    │   └── [Task_ID].md    # Ex: MT01-task-1.md
+    ├── reviews/            # Review logs
+    │   └── [Task_ID]-REVIEW.md
+    └── archive/            # Archived logs after release
+        └── [feature-slug]/
+```
+
+---
+
+## 📖 What to Read Before Starting
+
+### Layered Reading Protocol (L1 → L2 → L3)
+
+All agents must follow this protocol to avoid context explosion:
+
+#### L1: Global Context (ALWAYS READ)
+1. `.sdd-toolkit/context.md` — Feature matrix + executive summary
+2. `.sdd-toolkit/requirements.md` — Tech stack + business rules
+
+#### L2: Feature Context (IF WORKING ON A FEATURE)
+3. `.sdd-toolkit/features/[feature-slug]/index.md` — Overview
+4. `.sdd-toolkit/features/[feature-slug]/state.md` — Progress + context
+5. `.sdd-toolkit/features/[feature-slug]/[MILESTONE].md` — Tasks
+
+#### L3: Task Context (ON DEMAND)
+6. `.sdd-toolkit/logs/executions/[Task_ID].md` — Previous execution log
+7. `.sdd-toolkit/logs/reviews/[Task_ID]-REVIEW.md` — Previous review
+
+---
+
+## 📝 Where to Document Each Artifact Type
+
+### Project Scope (Project Architect 🏛️)
+
+| Artifact | Location | Description |
+|----------|----------|-------------|
+| Conceptual scope | `.sdd-toolkit/project.md` | Project constitution |
+
+**Actions after creation:**
+- Update `.sdd-toolkit/context.md` if applicable
+
+---
+
+### Requirements (Requirements Engineer 📝)
+
+| Artifact | Location | Description |
+|----------|----------|-------------|
+| Functional requirements | `.sdd-toolkit/requirements.md` | Stack + FR + NFR + BR |
+
+**Actions after creation:**
+- Update `.sdd-toolkit/context.md` if there are relevant changes
+
+---
+
+### Features (Feature Manager ✨)
+
+| Artifact | Location | Description |
+|----------|----------|-------------|
+| Overview | `.sdd-toolkit/features/[slug]/index.md` | Objective + roadmap |
+| State | `.sdd-toolkit/features/[slug]/state.md` | Progress + context |
+| Milestones | `.sdd-toolkit/features/[slug]/MT01.md` | Milestone tasks |
+
+**`index.md` Structure:**
+```markdown
+# 🚀 Feature: [Name]
+
+## Overview
+- **Objective:** [Value description]
+- **Linked Requirements:** [FR-XXX, FR-YYY]
+
+## Roadmap
+- **MT01:** [Milestone Name]
+- **MT02:** [Milestone Name]
+
+## Dependencies
+- Depends on: [other features]
+- Blocks: [other features]
+```
+
+**`state.md` Structure:**
+```markdown
+# 📊 Feature: [Name] - State & Context
+
+## Progress
+- **MT01:** ⏳ Not Started (0/X tasks)
+- **MT02:** 🔄 In Progress (Y/Z tasks)
+
+## Current Work
+- **Last Completed Task:** [Task_ID]
+- **Current Task:** [Task_ID]
+
+## Technical Context (Created Files)
+[File list]
+
+## Key Decisions
+[YYYY-MM-DD] [DT] Description
+
+## Known Issues
+[YYYY-MM-DD] [ISSUE] Description
+```
+
+**Actions after creation:**
+- ALWAYS update `.sdd-toolkit/context.md` with the new feature
+- Initial status: "Not Started"
+
+---
+
+### Executed Tasks (Coder 💻)
+
+| Artifact | Location | Description |
+|----------|----------|-------------|
+| Execution log | `.sdd-toolkit/logs/executions/[Task_ID].md` | What was done |
+
+**Execution log structure:**
+```markdown
+**Task:** [Task_ID]
+**Status:** Completed
+**Feature:** [feature-slug]
+
+**Changes:**
+- Created `src/components/Button.tsx`
+- Updated `src/utils/helpers.ts`
+
+**Technical Reasoning:**
+- Decision A: Technical justification.
+
+**Self-Check:**
+- [x] Linter Passed
+- [x] Tests Passed (if applicable)
+```
+
+**Actions after each task:**
+1. Create log in `.sdd-toolkit/logs/executions/[Task_ID].md`
+2. Update `.sdd-toolkit/features/[slug]/state.md` (Progress, Current Work, Files)
+3. Update `.sdd-toolkit/context.md` (Feature Matrix)
+4. Mark task as completed in `[MILESTONE].md`
+
+---
+
+### Reviews (QA Engineer 🔍)
+
+| Artifact | Location | Description |
+|----------|----------|-------------|
+| Review report | `.sdd-toolkit/logs/reviews/[Task_ID]-REVIEW.md` | Approval/Rejection |
+
+**Report structure:**
+```markdown
+### 🔬 REVIEW RECORD
+
+**Task_ID:** [Task_ID]
+**Reviewer:** Senior QA Engineer
+**Status:** Approved / Rejected
+
+**Checklist:**
+- [x] Business logic verified
+- [x] Adequate test coverage
+- [x] DoD compliance
+
+**Items for Correction:** (if rejected)
+- [Problem description]
+```
+
+**Actions after review:**
+1. Create report in `.sdd-toolkit/logs/reviews/[Task_ID]-REVIEW.md`
+2. Update `.sdd-toolkit/features/[slug]/state.md`
+3. If approved: indicate next task or milestone
+4. If rejected: list items for correction
+
+---
+
+### Releases (Release Manager 📦)
+
+| Artifact | Location | Description |
+|----------|----------|-------------|
+| Changelog | `changelog.md` (project root) | Version history |
+| Archived logs | `.sdd-toolkit/logs/archive/[feature-slug]/` | Processed logs |
+
+**Changelog structure:**
+```markdown
+## [v1.0.1] - 2024-03-20
+
+### Added
+- New feature X
+
+### Changed
+- Improvements to Y
+
+### Fixed
+- Bug Z
+```
+
+**Actions after release:**
+1. Add version to top of `changelog.md`
+2. Move logs from `executions/` and `reviews/` to `archive/[feature-slug]/`
+3. Update `.sdd-toolkit/context.md` to mark feature as "Completed"
+4. Update `.sdd-toolkit/system.md` if necessary
+
+---
+
+## 🏷️ Standard Naming Conventions
+
+| Element | Format | Example |
+|---------|--------|---------|
+| Feature slug | `kebab-case` | `user-authentication` |
+| Milestone | `MTXX` | `MT01`, `MT02` |
+| Task ID | `MTXX-task Y` | `MT01-task 1` |
+| Functional Requirement | `FR-XXX` | `FR-001` |
+| Business Rule | `BR-XXX` | `BR-001` |
+| Non-Functional Requirement | `NFR-XXX` | `NFR-001` |
+| Temporary features | `fix-[name]` or `refactor-[name]` | `fix-login-bug` |
+
+---
+
+## ⚠️ Critical Rules
+
+1. **Logs are global** — DO NOT create `logs/` folder inside features
+2. **Always update state.md** — After EACH executed task
+3. **Always update context.md** — After feature status changes
+4. **Maximum 5 tasks per milestone** — If exceeded, create new milestone
+5. **Do not delete logs** — Archive in `logs/archive/` after release
+6. **Language** — Respond in the user's language (English by default)