# Mauromedda Agent Toolkit Spec Driven Dev > ABOUTME: Spec-driven development orchestrator with subcommand interface - Skill: `tomevault-io/mauromedda-agent-toolkit-spec-driven-dev` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/mauromedda-agent-toolkit-spec-driven-dev` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mauromedda-agent-toolkit-spec-driven-dev/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/mauromedda-agent-toolkit-spec-driven-dev --- # ABOUTME: Spec-driven development orchestrator with subcommand interface # ABOUTME: Manages lifecycle: /spec.plan -> /spec.refine -> /spec.clarify -> /spec.tasks -> /spec.run # Spec-Driven Development Iterative feature development framework ensuring zero ambiguity before execution. ## Quick Reference | Command | Purpose | Input | |---------|---------|-------| | `/spec.plan ` | Create spec from "I want to build/add X" | Feature description | | `/spec.refine [section]` | Improve spec with research/Gemini | Optional section focus | | `/spec.clarify ` | Answer clarification questions | Your response | | `/spec.tasks` | Break spec into executable tasks | None (uses active spec) | | `/spec.run [task#]` | Execute tasks with TDD | Optional task number | ## Core Principle **Iterate until clarity**: No task execution begins until ALL questions are resolved and the spec is unambiguous. Claude must be able to execute without interruptions. --- ## Phase 1: `/spec.plan` - Create Specification **Trigger**: `/spec.plan ` or "I want to build/add X" ### Workflow 1. **Check `specs/` folder**: - If missing: Create `specs/` and `specs/README.md` - If exists: Read `specs/README.md` for project overrides 2. **Detect project context**: - Scan repo for language indicators (go.mod, pyproject.toml, package.json, etc.) - Note primary language(s) for later skill invocation - Check `specs/README.md` for language overrides 3. **Generate spec file**: - Filename: `specs/{feature-slug}.md` (kebab-case) - Use template from `references/templates.md` 4. **Fill initial sections**: - Parse user intent into Objective - List initial requirements (functional/non-functional) - Mark status as `DRAFT` 5. **Generate clarifying questions**: - Identify ambiguities, edge cases, unknowns - List as numbered questions in "Open Questions" section - **STOP and present questions to user** ### Output ``` Created: specs/feature-name.md (DRAFT) Questions requiring clarification: 1. [Question about scope] 2. [Question about behavior] 3. [Question about constraints] Use `/spec.clarify` to answer, or `/spec.refine` to research solutions. ``` --- ## Phase 2: `/spec.refine` - Research & Improve **Trigger**: `/spec.refine [section]` (e.g., `/spec.refine solution`, `/spec.refine requirements`) ### Workflow 1. **Load active spec**: Find most recent DRAFT spec in `specs/` 2. **Check project conventions**: - Read `specs/README.md` for behavior overrides - Load relevant language skill (auto-detected or overridden) - Load `design-patterns` skill for architectural guidance 3. **Research phase**: - If user requests Gemini: `gemini -m gemini-3-pro-preview "Analyze spec..." .` - Search codebase for similar patterns - Check skill references for best practices 4. **Update spec**: - Fill "Technical Strategy" with concrete approach - Add architecture decisions with rationale - Update requirements based on findings 5. **Re-evaluate clarity**: - Are there new questions? - Are existing questions resolved? - **If questions remain: STOP and present them** ### Gemini Integration (User-Invoked) ```bash # For design validation /spec.refine --gemini "Review architecture approach" # For alternative exploration /spec.refine --gemini "What are alternatives to this solution?" ``` --- ## Phase 3: `/spec.clarify` - Answer Questions **Trigger**: `/spec.clarify ` or `/spec.clarify Q1: answer, Q2: answer` ### Workflow 1. **Load active spec** with open questions 2. **Parse user response**: - Match answers to numbered questions - Accept free-form responses for single questions 3. **Update spec**: - Move answered questions to relevant sections - Add decisions/constraints to Requirements or Strategy - Remove resolved questions from "Open Questions" 4. **Check for new questions**: - Does the answer introduce new ambiguities? - **If questions remain: present them** - **If no questions: announce spec is ready for `/spec.tasks`** ### Example ``` User: /spec.clarify Q1: We need OAuth2 with Google provider only. Q2: No, admin can also delete. Updated specs/auth-system.md: - Added OAuth2/Google to Technical Strategy - Updated permissions: admin can delete Remaining questions: None Spec is ready. Use `/spec.tasks` to create task breakdown. ``` --- ## Phase 4: `/spec.tasks` - Task Breakdown **Trigger**: `/spec.tasks` ### Prerequisites - Active spec must have status `DRAFT` or `APPROVED` - "Open Questions" section must be empty - If questions exist: **STOP and redirect to `/spec.clarify`** ### Workflow 1. **Validate spec readiness**: ``` If open_questions > 0: ERROR: Spec has unresolved questions. Use /spec.clarify first. ``` 2. **Mark spec as APPROVED** 3. **Generate task file**: `specs/{feature-slug}.tasks.md` 4. **Break down by component**: - Group tasks by logical component/module - Each task = one logical unit (not TDD-granular) - TDD practice enforced during `/run`, not here 5. **Add task metadata**: - Link back to spec - Context summary - Acceptance criteria per task 6. **Final review**: - Present task list to user - Ask: "Any tasks missing or need splitting?" ### Task Granularity Tasks should be **high-level logical units**: - "Implement authentication middleware" - "Create user model and repository" - "Add API endpoints for user CRUD" TDD cycle (Red-Green-Refactor) happens WITHIN each task during `/spec.run`. --- ## Phase 5: `/spec.run` - Execute Tasks **Trigger**: `/spec.run [task#]` (e.g., `/spec.run`, `/spec.run 3`) ### Prerequisites - Task file must exist: `specs/{feature}.tasks.md` - If no task file: **STOP and redirect to `/spec.tasks`** ### Workflow 1. **Load task file** and find next unchecked task (or specified task#) 2. **Load context**: - Read linked spec for requirements - Read `specs/README.md` for project overrides - Invoke appropriate language skill 3. **Execute with TDD** (per CLAUDE.md rules): - **RED**: Write failing test first - **GREEN**: Minimal code to pass - **REFACTOR**: Clean up - **COMMIT**: After each phase 4. **Update task file**: - Mark task as `[x]` complete - Add notes if needed 5. **Continue or pause**: - If more tasks: Ask "Continue to next task?" - If blocked: Document blocker, ask for input - If all done: Mark spec as `COMPLETED` ### Execution Rules - **No interruptions**: If questions arise during execution, the spec was not ready - **Invoke skills**: Auto-invoke `/python`, `/golang`, etc. based on file type - **Respect hooks**: Pre-commit hooks must pass before marking complete - **Gemini review**: Follow CLAUDE.md thresholds (>100 lines or >3 files) --- ## Project Configuration: `specs/README.md` Override default behaviors per-project: ```markdown # Spec Configuration ## Language Override Primary: golang Secondary: python ## Conventions - All specs require security section - Tasks must include rollback plan - Use feature branches: feature/{spec-name} ## Templates Use custom templates from: ./templates/ ## Auto-invoke - Always run /trivy before marking complete - Require /gemini-review for all specs ``` --- ## State Management ### Spec Status Flow ``` DRAFT -> APPROVED -> IN_PROGRESS -> COMPLETED | | v v (questions?) (blocked?) | | v v DRAFT IN_PROGRESS ``` ### File Structure ``` project/ └── specs/ ├── README.md # Project overrides ├── auth-system.md # Spec (APPROVED) ├── auth-system.tasks.md # Task breakdown ├── user-dashboard.md # Spec (DRAFT) └── ... ``` --- ## Cross-Skill Integration | When | Invoke | |------|--------| | Writing `.py` files | `/python` skill | | Writing `.go` files | `/golang` skill | | Writing `.sh` files | `/bash` skill | | Writing `Makefile` | `/make` skill | | Writing `.tf` files | `/terraform` skill | | Architecture decisions | `/design-patterns` skill | | User-requested review | `gemini -m gemini-3-pro-preview ...` | --- ## Session Resume On context compaction or session resume: 1. Check `specs/` for files with status `IN_PROGRESS` 2. Check `.tasks.md` files for unchecked items 3. Report: "Found in-progress spec: X with Y tasks remaining" 4. Ask: "Continue with `/spec.run`?" --- ## Error Handling | Situation | Response | |-----------|----------| | `/spec.tasks` with open questions | "Spec has N unresolved questions. Use `/spec.clarify` first." | | `/spec.run` without task file | "No task file found. Use `/spec.tasks` first." | | `/spec.clarify` without active spec | "No active spec. Use `/spec.plan` to create one." | | Ambiguity during `/spec.run` | "Execution blocked: [issue]. Spec needs refinement. Use `/spec.refine`." | --- ## Templates See `references/templates.md` for: - Spec file template - Task file template - README.md template --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/mauromedda) — claim your Tome and manage your conversions.