feat: add sds CLI alias and update validation documentation

- Add 'sds' as short alias for 'spec-driven-steroids' CLI
- Update AGENTS.md to reference CLI-based validation (not MCP)
- Update skill instructions with CLI validation discovery sections
- Enforce only requirements.md, design.md, and tasks.md as valid spec documents
- Update tests to expect 'sds validate' command syntax

Version bump: 0.8.0 -> 0.9.0

Author: lindoelio

AGENTS.md

@@ -11,7 +11,7 @@ You are a **Spec-Driven Development Engineer** working on the Spec-Driven Steroi
 **Core Principles:**
 1. **Spec-First**: All changes begin with requirements (EARS), design (Mermaid), and tasks
 2. **Traceability**: Every design element and task links back to requirements
-3. **Validation First**: Use MCP tools to validate specs before implementation
+3. **Validation First**: Use CLI commands to validate specs before implementation (`sds validate...`)
 4. **Platform Native**: Work within existing AI tool ecosystems
 
 ---
@@ -109,15 +109,17 @@ packages/
 
 ## Validation Commands
 
-The CLI provides 5 validation commands under `spec-driven-steroids validate`:
+The CLI provides 5 validation commands under `sds validate` (or `spec-driven-steroids validate` - both work interchangeably):
 
 | Command | Purpose |
 |---------|---------|
-| `validate structure` | Validates folder structure and file existence |
-| `validate requirements` | Validates EARS patterns and REQ-X numbering |
-| `validate design` | Validates Mermaid diagrams and DES-X traceability |
-| `validate tasks` | Validates task checkboxes and phase structure |
-| `validate spec` | Cross-file validation and traceability |
+| `sds validate structure <slug>` | Validates folder structure and file existence |
+| `sds validate requirements <path>` | Validates EARS patterns and REQ-X numbering |
+| `sds validate design <path>` | Validates Mermaid diagrams and DES-X traceability |
+| `sds validate tasks <path>` | Validates task checkboxes and phase structure |
+| `sds validate spec <slug>` | Cross-file validation and traceability |
+
+**Note:** Both `sds` and `spec-driven-steroids` work interchangeably as CLI command names.
 
 ### MCP Server Configuration
 

packages/cli/CHANGELOG.md

@@ -1,5 +1,16 @@
 # spec-driven-steroids
 
+## 0.9.0
+
+### Minor Changes
+
+- Add `sds` CLI alias and update validation documentation
+
+  - Add `sds` as short alias for `spec-driven-steroids` CLI
+  - Update AGENTS.md to reference CLI-based validation (not MCP)
+  - Update skill instructions with CLI validation discovery sections
+  - Enforce only requirements.md, design.md, and tasks.md as valid spec documents
+
 ## 0.8.0
 
 ### Minor Changes

packages/cli/package.json

@@ -1,11 +1,12 @@
 {
     "name": "spec-driven-steroids",
-    "version": "0.8.0",
+    "version": "0.9.0",
     "description": "Inject Spec-Driven workflow into your favorite AI Agents. Rigorous. Simple. Frictionless.",
     "type": "module",
     "main": "dist/cli/index.js",
     "bin": {
-        "spec-driven-steroids": "dist/cli/index.js"
+        "spec-driven-steroids": "dist/cli/index.js",
+        "sds": "dist/cli/index.js"
     },
     "files": [
         "dist",

packages/cli/src/cli/index.ts

@@ -98,6 +98,7 @@ const program = new Command();
 
 program
   .name('spec-driven-steroids')
+  .alias('sds')
   .description('Inject Spec-Driven standards into your repository')
   .version(getCliVersion());
 

packages/cli/templates/universal/agents/spec-driven.agent.md

@@ -61,7 +61,7 @@ Invoke the `spec-driven-requirements-writer` skill.
 3. Load the `long-running-work-planning` skill at the start of the phase when available.
 4. Invoke the `spec-driven-requirements-writer` skill.
 5. Wait for the skill to produce requirements content.
-6. Validate with `spec-driven validate requirements .specs/changes/<slug>/requirements.md`.
+6. Validate with `sds validate requirements .specs/changes/<slug>/requirements.md`.
 7. Write `.specs/changes/<slug>/requirements.md`.
 8. Invoke the `quality-grading` skill in `grade-and-fix` mode on `.specs/changes/<slug>/requirements.md`. Apply any auto-fixes before proceeding.
 9. **STOP**. Summarize the artifact and ask: `Approve Phase 1, and I'll move to Phase 2 (design).`
@@ -75,7 +75,7 @@ Invoke the `spec-driven-technical-designer` skill.
 2. Load the `long-running-work-planning` skill at the start of the phase when available.
 3. Invoke the `spec-driven-technical-designer` skill.
 4. Wait for the skill to produce design content.
-5. Validate with `spec-driven validate design .specs/changes/<slug>/design.md`.
+5. Validate with `sds validate design .specs/changes/<slug>/design.md`.
 6. Write `.specs/changes/<slug>/design.md`.
 7. Invoke the `quality-grading` skill in `grade-and-fix` mode on `.specs/changes/<slug>/design.md`. Apply any auto-fixes before proceeding.
 8. **STOP**. Summarize the artifact and ask: `Approve Phase 2, and I'll move to Phase 3 (tasks).`
@@ -89,8 +89,8 @@ Invoke the `spec-driven-task-decomposer` skill.
 2. Load the `long-running-work-planning` skill at the start of the phase when available.
 3. Invoke the `spec-driven-task-decomposer` skill.
 4. Wait for the skill to produce tasks content.
-5. Validate with `spec-driven validate tasks .specs/changes/<slug>/tasks.md`.
-6. Validate the full spec with `spec-driven validate spec <slug>`.
+5. Validate with `sds validate tasks .specs/changes/<slug>/tasks.md`.
+6. Validate the full spec with `sds validate spec <slug>`.
 7. Write `.specs/changes/<slug>/tasks.md`.
 8. Invoke the `quality-grading` skill in `grade-and-fix` mode on `.specs/changes/<slug>/tasks.md`. Apply any auto-fixes before proceeding.
 9. **STOP**. Summarize the artifact and ask: `Approve Phase 3, and I'll move to Phase 4 (implementation), which includes Phase 5 (code review) before quality grading.`

packages/cli/templates/universal/skills/spec-driven-requirements-writer/SKILL.md

@@ -30,7 +30,7 @@ If `long-running-work-planning` is available, load it at the start of this phase
 4. Extract actors, actions, and constraints
 5. Write requirements using valid EARS syntax
 6. Define glossary terms if domain-specific terminology is needed
-7. **Validate**: Run `spec-driven validate requirements .specs/changes/<slug>/requirements.md` to ensure compliance
+7. **Validate**: Run `sds validate requirements .specs/changes/<slug>/requirements.md` to ensure compliance
 8. **Write Before Review**: Save to `.specs/changes/<slug>/requirements.md` before asking for approval
 
 ## Per-Phase Todo List
@@ -57,6 +57,23 @@ When this skill begins execution, create a todo list containing the following it
 
 `.specs/changes/<slug>/requirements.md`
 
+**IMPORTANT:** Only `requirements.md` is a valid spec document name for requirements. Do NOT create `spec.md`, `overview.md`, `architecture.md`, or any other document name. The spec-driven workflow strictly requires exactly three document types: `requirements.md`, `design.md`, and `tasks.md`.
+
+## CLI Validation Discovery
+
+After writing the requirements file, validate it using the CLI:
+
+```bash
+sds validate requirements .specs/changes/<slug>/requirements.md
+```
+
+Example:
+```bash
+sds validate requirements .specs/changes/my-feature/requirements.md
+```
+
+**Note:** Both `sds` and `spec-driven-steroids` work interchangeably as the CLI command name.
+
 ## Required Document Structure
 
 ```markdown
@@ -225,7 +242,7 @@ Instead: proceed with reasonable assumptions and document them in `## Assumption
 
 ### CLI Validation Failures
 
-When `spec-driven validate requirements` returns errors:
+When `sds validate requirements` returns errors:
 
 1. Fix missing or invalid sections
 2. Rewrite acceptance criteria with correct EARS syntax

packages/cli/templates/universal/skills/spec-driven-task-decomposer/SKILL.md

@@ -30,8 +30,8 @@ If `long-running-work-planning` is available, load it at the start of this phase
 7. **Create Atomic Tasks**: Break each design element into tasks that are concrete and usually completable within one focused session.
 8. **Add Acceptance Criteria Testing**: Create a dedicated penultimate testing phase covering every acceptance criterion.
 9. **Add Final Checkpoint**: Create a final phase that verifies all requirements and overall spec completeness.
-10. **Validate Tasks**: Run `spec-driven validate tasks .specs/changes/<slug>/tasks.md` using `tasks.md` and `design.md` content.
-11. **Validate Full Spec**: Run `spec-driven validate spec <slug>`.
+10. **Validate Tasks**: Run `sds validate tasks .specs/changes/<slug>/tasks.md` using `tasks.md` and `design.md` content.
+11. **Validate Full Spec**: Run `sds validate spec <slug>`.
 12. **Write Before Review**: Save to `.specs/changes/<slug>/tasks.md` before asking for approval.
 
 ## Per-Phase Todo List
@@ -61,6 +61,25 @@ When this skill begins execution, create a todo list containing the following it
 
 `.specs/changes/<slug>/tasks.md`
 
+**IMPORTANT:** Only `tasks.md` is a valid spec document name for tasks. Do NOT create `implementation.md`, `plan.md`, `spec.md`, or any other document name. The spec-driven workflow strictly requires exactly three document types: `requirements.md`, `design.md`, and `tasks.md`.
+
+## CLI Validation Discovery
+
+After writing the tasks file, validate it using the CLI:
+
+```bash
+sds validate tasks .specs/changes/<slug>/tasks.md
+sds validate spec <slug>
+```
+
+Examples:
+```bash
+sds validate tasks .specs/changes/my-feature/tasks.md
+sds validate spec my-feature
+```
+
+**Note:** Both `sds` and `spec-driven-steroids` work interchangeably as the CLI command name.
+
 ## Required Document Structure
 
 Your output must use this structure.
@@ -261,7 +280,7 @@ Ask a clarifying question only if the ambiguity would materially change:
 
 ### CLI Validation Failures
 
-When `spec-driven validate tasks` or `spec-driven validate spec` returns errors:
+When `sds validate tasks` or `sds validate spec` returns errors:
 
 1. Add missing required sections or phases.
 2. Fix task numbering and checkbox formatting.

packages/cli/templates/universal/skills/spec-driven-task-implementer/SKILL.md

@@ -22,7 +22,7 @@ Read `references/task-execution-patterns.md` when you need examples for resuming
 
 1. **Read Project Guidelines** (if they exist): Use `Glob` and `Read` to inspect `AGENTS.md`, `ARCHITECTURE.md`, `STYLEGUIDE.md`, `TESTING.md`, and `SECURITY.md`.
 2. **Read the Feature Spec**: Read `.specs/changes/<slug>/requirements.md`, `design.md`, and `tasks.md`.
-3. **Validate the Spec**: Run `spec-driven validate spec <slug>` before implementation. Resolve blocking spec issues first.
+3. **Validate the Spec**: Run `sds validate spec <slug>` before implementation. Resolve blocking spec issues first.
 4. **Inspect Existing Code**: Use `Glob`, `Read`, and `Grep` to understand the files, modules, and patterns referenced by the design.
 5. **Select the Next Eligible Task**: Choose the requested task, requested phase, or the next pending task whose dependencies are satisfied.
 6. **Execute the Task Loop**: Mark the task in progress, implement it, verify it, then mark it complete.
@@ -194,7 +194,7 @@ When a conflict appears:
 
 ### Spec Validation Failures
 
-If `spec-driven validate spec` reports blocking errors before implementation:
+If `sds validate spec` reports blocking errors before implementation:
 
 1. Do not start coding yet.
 2. Identify whether the issue is in requirements, design, or tasks.

packages/cli/templates/universal/skills/spec-driven-technical-designer/SKILL.md

@@ -28,7 +28,7 @@ If `long-running-work-planning` is available, load it at the start of this phase
 5. **Classify the Change**: Determine the change type and scope the design accordingly.
 6. **Design the Architecture**: Define design elements, responsibilities, boundaries, and requirement coverage.
 7. **Select Optional Sections**: Include only the sections that add design value for this change.
-8. **Validate**: Run `spec-driven validate design .specs/changes/<slug>/design.md` using the design content and requirements content.
+8. **Validate**: Run `sds validate design .specs/changes/<slug>/design.md` using the design content and requirements content.
 9. **Write Before Review**: Save to `.specs/changes/<slug>/design.md` before asking for approval.
 
 ## Per-Phase Todo List
@@ -56,6 +56,23 @@ When this skill begins execution, create a todo list containing the following it
 
 `.specs/changes/<slug>/design.md`
 
+**IMPORTANT:** Only `design.md` is a valid spec document name for design. Do NOT create `architecture.md`, `spec.md`, `overview.md`, or any other document name. The spec-driven workflow strictly requires exactly three document types: `requirements.md`, `design.md`, and `tasks.md`.
+
+## CLI Validation Discovery
+
+After writing the design file, validate it using the CLI:
+
+```bash
+sds validate design .specs/changes/<slug>/design.md
+```
+
+Example:
+```bash
+sds validate design .specs/changes/my-feature/design.md
+```
+
+**Note:** Both `sds` and `spec-driven-steroids` work interchangeably as the CLI command name.
+
 ## Change Type Classification
 
 Choose one primary change type and use it to determine depth and section inclusion.
@@ -343,7 +360,7 @@ Ask a clarifying question only if the ambiguity would materially change:
 
 ### CLI Validation Failures
 
-When `spec-driven validate design` returns errors:
+When `sds validate design` returns errors:
 
 1. Add any missing required sections.
 2. Fix Mermaid syntax by simplifying diagrams first.

packages/cli/tests/unit/template-validation-guidance.test.ts

@@ -27,8 +27,8 @@ describe('Unit: template validation guidance', () => {
     it('requires tasks and complete-spec validation in planner templates', async () => {
         // Universal template is the source of truth
         const content = await readTemplate('universal/agents/spec-driven.agent.md');
-        expect(content).toContain('spec-driven validate tasks');
-        expect(content).toContain('spec-driven validate spec');
+        expect(content).toContain('sds validate tasks');
+        expect(content).toContain('sds validate spec');
     });
 
     it('hardens Codex planner templates against phase-skipping', async () => {
@@ -61,11 +61,11 @@ describe('Unit: template validation guidance', () => {
 
         for (const target of targets) {
             const content = await readTemplate(target);
-            expect(content).toContain('spec-driven validate spec');
+            expect(content).toContain('sds validate spec');
         }
 
         const decomposerContent = await readTemplate('universal/skills/spec-driven-task-decomposer/SKILL.md');
-        expect(decomposerContent).toContain('spec-driven validate tasks');
+        expect(decomposerContent).toContain('sds validate tasks');
     });
 
     it('requires behavior-focused testing task names with REQ IDs only in traceability tags', async () => {