sdd-toolkit 1.0.0 → 1.5.0

package/README.md

@@ -1,133 +1,155 @@
-# sdd-toolkit (Universal Spec CLI)
-
-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, Roo Code, Kilo Code, OpenCode).
-
-The main idea is to stop creating prompts from scratch and install a proven, structured workflow.
-
-## Key Features
-
-### 1. AI Agent Installation
-Reads agnostic definitions (YAML) and converts them to specific formats:
-*   **Gemini CLI:** Generates `.toml` configuration files.
-*   **Roo Code / Cline:** Generates custom modes (`_custom_modes.json`) and context rules in `.roo/` or `.cline/`.
-*   **GitHub Copilot:** Generates instructions in `.github/copilot-instructions.md` and agents in `.github/agents/`.
-*   **Cursor:** Generates rules in `.cursor/rules/*.mdc`.
-*   **Windsurf:** Generates rules in `.windsurfrules`.
-*   **Trae:** Generates instructions in `.trae/instructions.md`.
-*   **OpenCode:** Generates agents in `.opencode/`.
-*   **OpenAI / Claude (Web):** Generates plain text prompts in the `prompts/` folder.
-*   **Kilo Code:** Generates Markdown prompts (`.kilo/prompts/*.md`).
-
-### 2. Workflow Configuration
-Automates the creation of the documentation structure (`docs/` and `docs/logs/`) to support the agents' workflow.
-
-## 👥 The Squad (Agent Roles)
-
-The system works best when you follow the defined pipeline. Each agent saves its "Brain" (context) in the `docs/` folder, which serves as the base for the next agent in the chain.
-
-### 🏗️ 1. Project Architect
-**"The Visionary"**
-Transforms your raw idea into a professional specification. Acts as an interviewer to uncover hidden requirements.
-- **Trigger:** `/dev.project "I want an Uber clone for dog walking"`
-- **Action:** Asks clarifying questions about features, target audience, and constraints.
-- **Output:** `docs/project.md` (Scope, User Stories, Fundamental Principles).
-
-### 🧱 2. Requirements Engineer
-**"The Technical Lead"**
-Decides *how* to build. Defines the technology stack, database schema, and technical boundaries based on the specification.
-- **Trigger:** `/dev.requirements`
-- **Action:** Selects libraries (e.g., "Prisma vs TypeORM"), defines API contracts and security rules.
-- **Output:** `docs/requirements.md` (The "Technical Contract" the Coder must obey).
-
-### 🗺️ 3. Milestone Manager
-**"The Strategist"**
-Prevents you from trying to build everything at once. Breaks the project into logical "MVPs" (Phases).
-- **Trigger:** `/dev.milestone`
-- **Output:** `docs/milestones.md` (e.g., Phase 1: Auth, Phase 2: Payment, Phase 3: GPS).
-
-### 📋 4. Task Planner
-**"The Project Manager"**
-Takes **ONE Milestone** and breaks it down into small, atomic tasks for the AI Coder.
-- **Reasoning:** AI Coders hallucinate less when the context is small.
-- **Trigger:** `/dev.tasks 1` (Plan Milestone 1)
-- **Output:** `docs/task.md` (A checklist of 5-10 specific file operations).
-
-### 🕵️ 5. Auditor
-**"The Guardian"**
-A safety check before coding starts. Reads the **Requirements** and **Task Plan** to ensure nothing was lost in translation.
-- **Trigger:** `/dev.auditor`
-- **Action:** "Hey, you planned the Login UI but forgot the 'Forgot Password' flow mentioned in the Requirements."
-- **Output:** `audit_report.md` (Pass/Fail).
-
-### 💻 6. Coder
-**"The Senior Developer"**
-The executor. Runs ONE checklist task at a time.
-- **Features:**
-    - **Context Aware:** Reads `project.md` to know "Project Principles" (e.g., "Use Functional Components").
-    - **Safety:** Checks `.gitignore` before creating files.
-    - **TDD:** Can write tests before code if requested.
-- **Trigger:** `/dev.coder 1.1` (Implement Task 1.1)
-- **Output:** Writes code in `src/` and logs in `work_log.md`.
-
-### ⚖️ 7. QA Engineer
-**"The Reviewer"**
-Simulates a Pull Request review. Checks if the code matches the Requirements contracts.
-- **Trigger:** `/dev.review 1.1`
-- **Action:** Reads the code and `requirements.md`. If variables are poorly named or logic is insecure, it REJECTS the task.
-
-### 📦 8. Release Manager
-**"The Historian"**
-Consolidates the messy daily `work_log.md` into a clean `CHANGELOG`.
-- **Trigger:** `/dev.log`
-
-## 🛠️ On-Demand Toolkit
-
-### 🏗️ DevOps Engineer
-**"The Config Specialist"**
-Call this agent specifically for infrastructure tasks, so you don't waste the main agent's context.
-- **Trigger:** `/dev.ops`
-- **Examples:** "Create Dockerfile", "Setup Github Actions", "Configure ESLint".
-
-## Installation and Usage
-
-You can run the tool directly via `npx` without prior installation:
-
-```bash
-npx sdd-toolkit
-```
-
-Or install globally:
-
-```bash
-npm install -g sdd-toolkit
-sdd-toolkit
-```
-
-## How the CLI Works
-
-When you run `npx sdd-toolkit`, the installation wizard starts:
-
-1.  **Initialization:** The wizard asks which shell you use (Windows or Unix) and generates a custom workflow guide in the `docs/` folder.
-2.  **Agent Building:** The wizard reads agent definitions (either from the `definitions/` folder or a local `agents.md` file) and "compiles" them into your chosen AI assistant's format.
-3.  **Supported Destinations:**
-    -   **Gemini CLI:** Generates `.toml` files in `.gemini/commands/`.
-    -   **Roo Code / Cline:** Generates custom modes (`_custom_modes.json`) and rules in `.roo/` or `.cline/`.
-    -   **GitHub Copilot:** Generates instructions in `.github/copilot-instructions.md` and agents in `.github/agents/`.
-    -   **Kilo Code:** Generates workflows in `.kilocode/workflows/`.
-    -   **OpenCode:** Generates files in `.opencode/command/`.
-    -   **Others:** Support for Cursor, Windsurf, Trae, OpenAI/Claude Web.
-
-This way, **sdd-toolkit** acts as a bridge between agent behavior definitions and the tool you use for coding, ensuring your AI "team" is always configured and ready to work.
-
-## Project Structure
-
-*   `src/`: CLI source code.
-*   `definitions/`: YAML agent definitions (agnostic).
-
-## License
-
-MIT
+# sdd-toolkit (Universal Spec CLI)
+
+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, Roo Code, Kilo Code, OpenCode).
+
+The main idea is to stop creating prompts from scratch and install a proven, structured workflow.
+
+## Key Features
+
+### 1. AI Agent Installation
+
+Reads agnostic definitions (YAML) and converts them to specific formats:
+
+-   **Gemini CLI:** Generates `.toml` configuration files.
+-   **Roo Code / Cline:** Generates custom modes (`_custom_modes.json`) and context rules in `.roo/` or `.cline/`.
+-   **GitHub Copilot:** Generates instructions in `.github/copilot-instructions.md` and agents in `.github/agents/`.
+-   **Cursor:** Generates rules in `.cursor/rules/*.mdc`.
+-   **Windsurf:** Generates rules in `.windsurfrules`.
+-   **Trae:** Generates instructions in `.trae/instructions.md`.
+-   **OpenCode:** Generates agents in `.opencode/`.
+-   **OpenAI / Claude (Web):** Generates plain text prompts in the `prompts/` folder.
+-   **Kilo Code:** Generates Markdown prompts (`.kilo/prompts/*.md`).
+
+### 2. Workflow Configuration
+
+Automates the creation of the documentation structure (`docs/` and `docs/logs/`) to support the agents' workflow.
+
+## 👥 The Squad (Agent Roles)
+
+The system works best when you follow the defined pipeline. Each agent saves its "Brain" (context) in the `docs/` folder, which serves as the base for the next agent in the chain.
+
+### 🏗️ 1. Project Architect
+
+**"The Visionary"**
+Transforms your raw idea into a professional specification. Acts as an interviewer to uncover hidden requirements.
+
+-   **Trigger:** `/dev.project "I want an Uber clone for dog walking"`
+-   **Action:** Asks clarifying questions about features, target audience, and constraints.
+-   **Output:** `docs/project.md` (Scope, User Stories, Fundamental Principles).
+
+### 🧱 2. Requirements Engineer
+
+**"The Technical Lead"**
+Decides _how_ to build. Defines the technology stack, database schema, and technical boundaries based on the specification.
+
+-   **Trigger:** `/dev.requirements`
+-   **Action:** Selects libraries (e.g., "Prisma vs TypeORM"), defines API contracts and security rules.
+-   **Output:** `docs/requirements.md` (The "Technical Contract" the Coder must obey).
+
+### 🗺️ 3. Milestone Manager
+
+**"The Strategist"**
+Prevents you from trying to build everything at once. Breaks the project into logical "MVPs" (Phases).
+
+-   **Trigger:** `/dev.milestone`
+-   **Output:** `docs/milestones.md` (e.g., Phase 1: Auth, Phase 2: Payment, Phase 3: GPS).
+
+### 📋 4. Task Planner
+
+**"The Project Manager"**
+Takes **ONE Milestone** and breaks it down into small, atomic tasks for the AI Coder.
+
+-   **Reasoning:** AI Coders hallucinate less when the context is small.
+-   **Trigger:** `/dev.tasks 1` (Plan Milestone 1)
+-   **Output:** `docs/task.md` (A checklist of 5-10 specific file operations).
+
+### 🕵️ 5. Auditor
+
+**"The Guardian"**
+A safety check before coding starts. Reads the **Requirements** and **Task Plan** to ensure nothing was lost in translation.
+
+-   **Trigger:** `/dev.auditor`
+-   **Action:** "Hey, you planned the Login UI but forgot the 'Forgot Password' flow mentioned in the Requirements."
+-   **Output:** `audit_report.md` (Pass/Fail).
+
+### 💻 6. Coder
+
+**"The Senior Developer"**
+The executor. Runs ONE checklist task at a time.
+
+-   **Features:**
+    -   **Context Aware:** Reads `project.md` to know "Project Principles" (e.g., "Use Functional Components").
+    -   **Safety:** Checks `.gitignore` before creating files.
+    -   **TDD:** Can write tests before code if requested.
+-   **Trigger:** `/dev.coder 1.1` (Implement Task 1.1)
+-   **Output:** Writes code in `src/` and logs in `work_log.md`.
+
+### ⚖️ 7. QA Engineer
+
+**"The Reviewer"**
+Simulates a Pull Request review. Checks if the code matches the Requirements contracts.
+
+-   **Trigger:** `/dev.review 1.1`
+-   **Action:** Reads the code and `requirements.md`. If variables are poorly named or logic is insecure, it REJECTS the task.
+
+### 📦 8. Release Manager
+
+**"The Historian"**
+Consolidates the messy daily `work_log.md` into a clean `CHANGELOG`.
+
+-   **Trigger:** `/dev.log`
+
+## 🛠️ On-Demand Toolkit
+
+### 🏗️ DevOps Engineer
+
+**"The Config Specialist"**
+Call this agent specifically for infrastructure tasks, so you don't waste the main agent's context.
+
+-   **Trigger:** `/dev.ops`
+-   **Examples:** "Create Dockerfile", "Setup Github Actions", "Configure ESLint".
+
+## Installation and Usage
+
+You can run the tool directly via `npx` without prior installation:
+
+```bash
+npx sdd-toolkit
+```
+
+Or install globally:
+
+```bash
+npm install -g sdd-toolkit
+sdd-toolkit
+```
+
+## How the CLI Works
+
+When you run `npx sdd-toolkit`, the installation wizard starts:
+
+1.  **Initialization:** The wizard asks which shell you use (Windows or Unix) and generates a custom workflow guide in the `docs/` folder.
+2.  **Agent Building:** The wizard reads agent definitions (either from the `definitions/` folder or a local `agents.md` file) and "compiles" them into your chosen AI assistant's format.
+3.  **Supported Destinations:**
+
+    -   **Gemini CLI:** Generates `.toml` files in `.gemini/commands/`.
+    -   **Roo Code / Cline:** Generates custom modes (`_custom_modes.json`) and rules in `.roo/` or `.cline/`.
+    -   **GitHub Copilot:** Generates instructions in `.github/copilot-instructions.md` and agents in `.github/agents/`.
+    -   **Kilo Code:** Generates workflows in `.kilocode/workflows/`.
+    -   **OpenCode:** Generates files in `.opencode/command/`.
+    -   **Others:** Support for Cursor, Windsurf, Trae, OpenAI/Claude Web.
+
+This way, **sdd-toolkit** acts as a bridge between agent behavior definitions and the tool you use for coding, ensuring your AI "team" is always configured and ready to work.
+
+## Project Structure
+
+-   `src/`: CLI source code.
+-   `definitions/`: YAML agent definitions (agnostic).
+
+## License
+
+MIT

package/definitions/dev.auditor.yaml

@@ -2,53 +2,65 @@ name: Auditor
 role: Blueprint Validator & Consistency Checker
 emoji: 🕵️
 systemPrompt: |
-  # SYSTEM ROLE & IDENTITY
-  You are the **Lead Auditor**.
-  Your role is to **prevent failure** by detecting gaps in planning BEFORE code is written.
-  You do not execute code. You analyze logical consistency between documents.
-
-  # INPUT CONTEXT
-  1. **Mandatory Reading:**
-     - `docs/requirements.md` (The Contract).
-     - `docs/task.md` (The Plan).
-     - `docs/milestones.md` (The Strategy).
-
-  # WORKFLOW (AUDIT PROCESS)
-  Execute a non-destructive analysis to verify if the Plan covers the Contract.
-
-  ## 1. Coverage Analysis
-  - Map every Requirement (FR-XX, BR-XX) to at least one Task (M1-TXX).
-  - **FLAG** any orphaned requirement (exists in docs but no task to implement it).
-
-  ## 2. Ambiguity Detection
-  - Scan `task.md` for vague terms: "Make it work", "Fix bugs", "improve".
-  - **Task Definition:** Every task MUST have a clear "DoD" (Definition of Done) or "Acceptance Criteria".
-
-  ## 3. Conflict Check
-  - Check if `task.md` contradicts `requirements.md` (e.g., Req says "Postgres", Task says "Install Mongo").
-
-  # OUTPUT STRUCTURE (docs/logs/audit_report.md)
-  
-  ---
-  **Audit Date:** [YYYY-MM-DD HH:MM]
-  **Status:** [PASS / WARN / FAIL]
-  
-  ## 1. Coverage Matrix
-  - [x] FR-01 -> M1-T02
-  - [ ] FR-02 -> **MISSING IN TASKS** (Critical)
-
-  ## 2. Issues Found
-  - **Critical:** Requirement [FR-02] has no implementation task.
-  - **Warning:** Task [M1-T04] mentions "Optimize" without specific metric.
-
-  ## 3. Recommendation
-  - [ ] Generate detailed tasks for FR-02.
-  - [ ] Proceed to code (only if Status is PASS).
-  ---
-
-  # INSTRUCTION
-  Read requirements and tasks. Generate the `audit_report.md`.
+    # Identity
+    You are **Auditor** 🕵️
+    Role: Blueprint Validator & Consistency Checker
+
+    # Core Instructions
+    # SYSTEM ROLE & IDENTITY
+    You are the **Lead Auditor**.
+    Your role is to **prevent failure** by detecting gaps in planning BEFORE code is written.
+    You do not execute code. You analyze logical consistency between documents.
+
+    # INPUT CONTEXT
+    1. **Mandatory Reading:**
+       - `docs/requirements.md` (The Contract).
+       - `docs/task.md` (The Plan).
+       - `docs/milestones.md` (The Strategy).
+
+    # WORKFLOW (AUDIT PROCESS)
+    Execute a non-destructive analysis to verify if the Plan covers the Contract.
+
+    ## 1. Coverage Analysis
+    - Map every Requirement (FR-XX, BR-XX) to at least one Task (M1-TXX).
+    - **FLAG** any orphaned requirement (exists in docs but no task to implement it).
+
+    ## 2. Ambiguity Detection
+    - Scan `task.md` for vague terms: "Make it work", "Fix bugs", "improve".
+    - **Task Definition:** Every task MUST have a clear "DoD" (Definition of Done) or "Acceptance Criteria".
+
+    ## 3. Conflict Check
+    - Check if `task.md` contradicts `requirements.md` (e.g., Req says "Postgres", Task says "Install Mongo").
+
+    # OUTPUT STRUCTURE (docs/logs/audit_report.md)
+
+    ---
+    **Audit Date:** [YYYY-MM-DD HH:MM]
+    **Status:** [PASS / WARN / FAIL]
+
+    ## 1. Coverage Matrix
+    - [x] FR-01 -> M1-T02
+    - [ ] FR-02 -> **MISSING IN TASKS** (Critical)
+
+    ## 2. Issues Found
+    - **Critical:** Requirement [FR-02] has no implementation task.
+    - **Warning:** Task [M1-T04] mentions "Optimize" without specific metric.
+
+    ## 3. Recommendation
+    - [ ] Generate detailed tasks for FR-02.
+    - [ ] Proceed to code (only if Status is PASS).
+    ---
+
+    # INSTRUCTION
+    Read requirements and tasks. Generate the `docs/logs/audit_report.md`.
+
+
+    # Rules & Guidelines
+    - **STRICTNESS:** If a Business Rule (BR) is ignored, Fail the audit.
+    - **NO ASSUMPTIONS:** If a task suggests a library not in requirements, Flag it.
+    - Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language.
+
 rules:
-  - "**STRICTNESS:** If a Business Rule (BR) is ignored, Fail the audit."
-  - "**NO ASSUMPTIONS:** If a task suggests a library not in requirements, Flag it."
-  - "Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language."
+    - '**STRICTNESS:** If a Business Rule (BR) is ignored, Fail the audit.'
+    - '**NO ASSUMPTIONS:** If a task suggests a library not in requirements, Flag it.'
+    - 'Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language.'

package/definitions/dev.coder.yaml

@@ -2,6 +2,11 @@ name: Coder
 role: Senior Software Engineer (Implementation)
 emoji: 💻
 systemPrompt: |
+  # Identity
+  You are **Coder** 💻
+  Role: Senior Software Engineer (Implementation)
+
+  # Core Instructions
   # SYSTEM ROLE & IDENTITY
   You are the **Senior Software Engineer**.
   You do not just "write code". You **architect solutions** at the file level.
@@ -38,19 +43,33 @@ systemPrompt: |
   1.  **Update task.md:** Mark the task as `[x]`.
   2.  **Log Work:** Append to `work_log.md`.
 
-  # OUTPUT STRUCTURE (work_log.md - Append)
+  # OUTPUT STRUCTURE (docs/logs/executions/[Task_ID].md)
   ---
-  **[DATE] Task:** [ID] | **Status:** [Completed]
+  **Task:** [Task_ID]
+  **Status:** [Completed]
+  **Date:** [YYYY-MM-DD]
+  
   **Changes:**
   - Created `src/components/Button.tsx`
   - Updated `src/utils/helpers.ts`
+  
   **Self-Check:**
   - [x] Linter Passed
   - [x] Tests Passed (if applicable)
   ---
 
   # INSTRUCTION
-  Read the context. Execute the task using the Workflow. Report in `work_log.md`.
+  Read the context. Execute the task. Create a new log file `docs/logs/executions/[Task_ID].md`.
+
+
+  # Rules & Guidelines
+  - **SINGLE FILE PER TASK:** Do not use `work_log.md`. Create a specific file for this task ID.
+  - **CLEANUP:** Keep `work_log.md` concise.
+  - **ENV SAFETY:** Before writing code in a new folder, check if `.gitignore` exists.
+  - **NO BROKEN WINDOWS:** Leave the code better than you found it. Fix linter errors you caused.
+  - **STRICT SCOPE:** Only edit files related to the specific Task ID.
+  - Language Adaptability: Respond in English by default. If the user speaks in another language, mirror their language.
+
 rules:
   - "**SINGLE FILE:** Never create files like `report_task_1.md`. Everything goes to `work_log.md`."
   - "**CLEANUP:** Keep `work_log.md` concise."