From f8c8bfc0e93dd0c09a54740819946d191da64240 Mon Sep 17 00:00:00 2001 From: Pedram Amini Date: Sun, 11 Jan 2026 06:09:50 -0600 Subject: [PATCH] MAESTRO: Fix speckit-commands.md documentation inaccuracies - Fix intro claiming prompts are "automatically synced" (they require manual Check for Updates) - Add Storage Location row to comparison table (.specify/ vs Auto Run Docs/Initiation/) - Expand Viewing & Managing Commands section with Reset to Default and badge indicator - Add exact file paths for all commands: - /speckit.constitution: .specify/memory/constitution.md - /speckit.specify: specs/-/spec.md - /speckit.clarify: Updates spec.md with Clarifications section - /speckit.plan: plan.md, research.md, data-model.md, contracts/, quickstart.md - /speckit.tasks: tasks.md with phase structure - /speckit.implement: Auto Run Docs/SpecKit--Phase-XX-[Description].md - Rewrite /speckit.checklist section to explain "unit tests for requirements" concept - Add /speckit.taskstoissues requirements (gh CLI + GitHub MCP server tool) - Rename "Auto-Updates" to "Updating Commands" with accurate manual process description - Expand Tips section with additional actionable advice --- docs/speckit-commands.md | 113 ++++++++++++++++++++++++++++----------- 1 file changed, 82 insertions(+), 31 deletions(-) diff --git a/docs/speckit-commands.md b/docs/speckit-commands.md index 2b7e937d..c36f2823 100644 --- a/docs/speckit-commands.md +++ b/docs/speckit-commands.md @@ -4,7 +4,7 @@ description: Structured specification workflow for AI-assisted development using icon: file-text --- -Spec-Kit is a structured specification workflow from [GitHub's spec-kit project](https://github.com/github/spec-kit) that helps teams create clear, actionable specifications before implementation. Maestro bundles these commands and keeps them updated automatically. +Spec-Kit is a structured specification workflow from [GitHub's spec-kit project](https://github.com/github/spec-kit) that helps teams create clear, actionable specifications before implementation. Maestro bundles these commands and you can check for updates manually via Settings. ![Spec-Kit Commands in Settings](./screenshots/speckit-commands.png) @@ -19,6 +19,7 @@ Maestro offers two paths to structured development: | **Output** | Constitution, specs, tasks → Auto Run docs | Phase 1 Auto Run document | | **Control** | Full control at each step | Streamlined, opinionated | | **Learning Curve** | Moderate | Low | +| **Storage Location** | `.specify/` directory in project root | `Auto Run Docs/Initiation/` | **Use Spec-Kit when:** - You want fine-grained control over specification phases @@ -37,10 +38,12 @@ Both approaches ultimately produce markdown documents for Auto Run execution. Access Spec-Kit commands via **Settings → AI Commands** tab. Here you can: -- **View all commands** with descriptions -- **Check for Updates** to pull the latest prompts from GitHub -- **Expand commands** to see their full prompts -- **Customize prompts** (modifications are preserved across updates) +- **View all commands** — See descriptions and expand to view full prompts +- **Check for Updates** — Manually pull the latest prompts from GitHub releases +- **Edit prompts** — Customize any command (modifications are preserved across updates) +- **Reset to Default** — Restore a modified prompt to the bundled version + +Commands marked with a Maestro badge (`/speckit.help`, `/speckit.implement`) are Maestro-specific and not updated from upstream. ## Core Workflow (Recommended Order) @@ -48,71 +51,119 @@ Access Spec-Kit commands via **Settings → AI Commands** tab. Here you can: Start here to establish your project's foundational values, constraints, and guidelines. The constitution guides all subsequent specifications and ensures consistency across features. -**Creates:** A constitution document with core principles, technical constraints, and team conventions. +**Creates:** `.specify/memory/constitution.md` — A versioned constitution document with core principles, technical constraints, team conventions, and governance rules. ### 2. `/speckit.specify` — Create Feature Specification -Define the feature you want to build with clear requirements, acceptance criteria, and boundaries. +Define the feature you want to build with clear requirements, acceptance criteria, and boundaries. Creates a new numbered Git branch and initializes the spec directory structure. -**Creates:** A detailed feature specification with scope, requirements, and success criteria. +**Creates:** `specs/-/spec.md` — A detailed feature specification with scope, functional requirements, user scenarios, and success criteria. Also creates a `checklists/requirements.md` validation checklist. ### 3. `/speckit.clarify` — Identify Gaps -Review your specification for ambiguities, missing details, and edge cases. The AI asks clarifying questions to strengthen the spec before implementation. +Review your specification for ambiguities, missing details, and edge cases. The AI asks up to 5 targeted clarification questions sequentially, encoding answers directly into the spec. -**Tip:** Run `/speckit.clarify` multiple times — each pass catches different gaps. +**Updates:** `specs/-/spec.md` — Adds a `## Clarifications` section with session-dated answers, and propagates clarifications to relevant spec sections. + +**Tip:** Run `/speckit.clarify` multiple times — each pass catches different gaps. Use early termination signals ("done", "good", "no more") to stop questioning. ### 4. `/speckit.plan` — Implementation Planning -Convert your specification into a high-level implementation plan with phases and milestones. +Convert your specification into a high-level implementation plan. Includes technical context, constitution compliance checks, and multi-phase design workflow. -**Creates:** A phased implementation roadmap with dependencies and risk areas. +**Creates:** Multiple artifacts in the feature directory: +- `plan.md` — Implementation plan with phases and milestones +- `research.md` — Resolved unknowns and technology decisions (Phase 0) +- `data-model.md` — Entities, fields, and relationships (Phase 1) +- `contracts/` — API contracts in OpenAPI/GraphQL format (Phase 1) +- `quickstart.md` — Getting started guide (Phase 1) ### 5. `/speckit.tasks` — Generate Tasks -Break your plan into specific, actionable tasks with dependencies clearly mapped. +Break your plan into specific, actionable tasks with dependencies clearly mapped. Tasks are organized by user story and structured in phases. -**Creates:** A dependency-ordered task list ready for execution. +**Creates:** `specs/-/tasks.md` — A dependency-ordered task list with: +- **Phase 1:** Setup (project initialization) +- **Phase 2:** Foundational (blocking prerequisites) +- **Phase 3+:** User stories in priority order (P1, P2, P3...) +- **Final Phase:** Polish & cross-cutting concerns + +Each task has an ID (T001, T002...), optional `[P]` marker for parallelizable tasks, and `[US#]` labels linking to user stories. ### 6. `/speckit.implement` — Execute with Auto Run **Maestro-specific command.** Converts your tasks into Auto Run documents that Maestro can execute autonomously. This bridges spec-kit's structured approach with Maestro's multi-agent capabilities. -**Creates:** Markdown documents in `Auto Run Docs/` with task checklists. +**Creates:** Markdown documents in `Auto Run Docs/` with naming pattern: +``` +Auto Run Docs/SpecKit--Phase-01-[Description].md +Auto Run Docs/SpecKit--Phase-02-[Description].md +``` + +Each phase document is self-contained, includes Spec Kit context references, preserves task IDs (T001, T002...) and user story markers ([US1], [US2]) for traceability. ## Analysis & Quality Commands ### `/speckit.analyze` — Cross-Artifact Analysis -Verify consistency across your constitution, specifications, and tasks. Catches contradictions and gaps between documents. +Verify consistency across your constitution, specifications, and tasks. Performs a read-only analysis that catches: +- **Duplications** — Near-duplicate requirements +- **Ambiguities** — Vague adjectives lacking measurable criteria +- **Underspecification** — Missing acceptance criteria or undefined components +- **Constitution violations** — Conflicts with project principles (always CRITICAL severity) +- **Coverage gaps** — Requirements without tasks, or orphaned tasks -### `/speckit.checklist` — Generate QA Checklist +**Outputs:** A structured Markdown report with severity ratings (Critical/High/Medium/Low), coverage metrics, and suggested next actions. Does not modify any files. -Create a custom checklist for your feature based on the specification. Useful for QA, code review, and acceptance testing. +### `/speckit.checklist` — Requirements Quality Validation + +Generate "unit tests for requirements" — checklists that validate the *quality* of your requirements, not the implementation. Each checklist item tests whether requirements are complete, clear, consistent, and measurable. + +**Creates:** `specs/-/checklists/.md` (e.g., `ux.md`, `api.md`, `security.md`) + +Example items: +- "Are visual hierarchy requirements defined with measurable criteria?" [Completeness] +- "Is 'fast loading' quantified with specific timing thresholds?" [Clarity] +- "Are error handling requirements defined for all API failure modes?" [Gap] + +**Note:** This is NOT for QA testing implementation — it validates that requirements are well-written before implementation begins. ### `/speckit.taskstoissues` — Export to GitHub Issues -Convert your tasks directly into GitHub Issues. Requires `gh` CLI to be installed and authenticated. +Convert your tasks directly into GitHub Issues. + +**Requirements:** +- `gh` CLI installed and authenticated +- GitHub MCP server tool (`github/github-mcp-server/issue_write`) +- Remote must be a GitHub URL + +**Caution:** Only creates issues in the repository matching your Git remote — will refuse to create issues elsewhere. ## Getting Help -Run `/speckit.help` to get an overview of the workflow and tips for best results. +Run `/speckit.help` to get an overview of the workflow and tips for best results. This Maestro-specific command provides: +- Command overview with recommended workflow order +- Integration tips for Auto Run +- Links to upstream documentation -## Auto-Updates +## Updating Commands -Spec-Kit prompts are automatically synced from the [GitHub spec-kit repository](https://github.com/github/spec-kit): +Spec-Kit prompts can be updated from the [GitHub spec-kit repository](https://github.com/github/spec-kit) releases: 1. Open **Settings → AI Commands** -2. Click **Check for Updates** -3. New commands and prompt improvements are downloaded -4. Your custom modifications are preserved +2. Click **Check for Updates** button +3. Latest prompts are downloaded from the most recent GitHub release +4. Your custom modifications are preserved — edited prompts are not overwritten -The version number and last update date are shown at the top of the Spec Kit Commands section. +The version number (e.g., `v0.0.90`) and last refresh date are shown at the top of the Spec Kit Commands section. + +**Note:** Custom Maestro commands (`/speckit.help`, `/speckit.implement`) are bundled with Maestro and not updated from upstream. ## Tips for Best Results -- **Start with constitution** — Even for small projects, defining principles helps maintain consistency -- **Iterate on specifications** — Use `/speckit.clarify` multiple times to refine your spec -- **Keep specs focused** — One feature per specification cycle works best -- **Review before implementing** — Use `/speckit.analyze` to catch issues early -- **Leverage parallelism** — With Maestro, run multiple spec-kit workflows simultaneously across different agents +- **Start with constitution** — Even for small projects, defining principles helps maintain consistency and catch violations early +- **Iterate on specifications** — Use `/speckit.clarify` multiple times to refine your spec; accept recommended answers for faster iteration +- **Keep specs focused** — One feature per specification cycle works best; use numbered branches (`1-feature-name`, `2-other-feature`) +- **Review before implementing** — Use `/speckit.analyze` after `/speckit.tasks` to catch issues before coding +- **Validate requirements first** — Use `/speckit.checklist` to verify requirements are clear and complete before implementation +- **Leverage parallelism** — With Maestro, run multiple spec-kit workflows simultaneously across different agents using worktrees