spec-quality
Specification quality framework for planning. Defines the minimum bar for what a plan must address — alternatives, non-goals, blast radius, risk flags, and test strategy. Referenced by schema guidance fields during queue-phase note filling. Read this skill whenever filling requirements or design notes for any MCP work item.
Best use case
spec-quality is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Specification quality framework for planning. Defines the minimum bar for what a plan must address — alternatives, non-goals, blast radius, risk flags, and test strategy. Referenced by schema guidance fields during queue-phase note filling. Read this skill whenever filling requirements or design notes for any MCP work item.
Teams using spec-quality should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/spec-quality/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How spec-quality Compares
| Feature / Agent | spec-quality | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Specification quality framework for planning. Defines the minimum bar for what a plan must address — alternatives, non-goals, blast radius, risk flags, and test strategy. Referenced by schema guidance fields during queue-phase note filling. Read this skill whenever filling requirements or design notes for any MCP work item.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
# Specification Quality Framework This skill defines the minimum thinking floor for plans and specifications. The sections below represent what every plan must address. They are not a ceiling — if the problem demands additional analysis, add it. But these areas must not be skipped. The value of a spec is entirely in the thinking it forces before code is written. If a section doesn't change how you'd approach implementation, it isn't earning its place. Every sentence should either prevent a mistake or force a decision. --- ## Specification Disciplines These are the required areas of analysis. Each one exists because skipping it leads to a specific, recurring class of failure. ### Alternatives Considered Evaluate at least two real approaches. "Do nothing" always counts as one. For each alternative, state what it would look like and the specific trade-off that led to its rejection. If you can only think of one approach, you haven't explored the solution space — step back and look for a fundamentally different angle. The point is not to document alternatives for posterity. It's to catch yourself before committing to an approach that has a better option sitting next to it. *Anti-pattern: strawman alternatives.* "Alternative: rewrite everything from scratch. Rejected: too much work." This doesn't force any real thinking. ### Non-Goals Name what someone might reasonably expect this work to include but that is deliberately excluded. If you cannot name a single non-goal, the scope is not tight enough. Non-goals prevent scope creep during implementation. Without them, agents tend to gold-plate — adding adjacent improvements that weren't asked for and that introduce unplanned risk. ### Blast Radius Identify every module, file, and interface affected by the change. Trace downstream consumers — if you change a repository method signature, what tools call it? If you change a domain model default, what tests assume the old value? This analysis exists to catch "I didn't realize changing X breaks Y" before it happens. Read `references/project-concerns.md` for cross-cutting constraints specific to this codebase that frequently expand blast radius in non-obvious ways. ### Risk Flags Call out the one or two things most likely to go wrong. These might be areas of tight coupling, migration complexity, concurrency concerns, or simply parts of the codebase you don't fully understand yet. The purpose is to focus review attention where it matters and to make uncertainty explicit rather than hidden. ### Test Strategy Every plan must include a concrete test strategy. This is not "add tests" — it's a specific accounting of what will be verified and how. **Required coverage areas:** - **Happy paths** — the primary use cases the change enables. These confirm the feature works as intended under normal conditions. - **Failure paths** — what happens when inputs are invalid, dependencies are missing, or operations fail. These confirm the system fails gracefully rather than silently corrupting state or throwing unhandled exceptions. - **Edge cases** — boundary conditions specific to the change. Examples: empty collections, null/optional fields, maximum depth limits, circular references, concurrent access. Think about what a user or caller could do that you didn't explicitly design for. For each area, name the specific scenarios you'll test. "Test edge cases" is not a strategy. "Test that circular parent references are detected and rejected with a clear error" is. If the change modifies shared interfaces (domain models, repository contracts, tool parameters), note which existing tests may break and how you'll handle that — update them, or confirm they still pass with the new behavior. --- ## Using This Framework This framework sets a floor. The disciplines above are the minimum required analysis. Depending on the complexity of the work, additional analysis may be warranted — performance implications, migration strategies, API compatibility concerns, or anything else that would change the implementation approach if examined carefully. Add whatever the problem demands. The goal is a plan that lets someone implement the change confidently, understanding not just what to build but why this approach was chosen and what to watch out for.
Related Skills
session-retrospective
Analyze the current implementation run — evaluate schema effectiveness, delegation alignment, note quality, plan-to-execution fit. Captures cross-session trends and proposes improvements when patterns repeat. Use after implementation runs, or when user says 'retrospective', 'session review', 'what did we learn', 'analyze this run', 'how did that go', 'evaluate our process', 'wrap up', 'end of session review'. Also use when the output style's retrospective nudge fires after complete_tree.
review-quality
Review quality framework for the work-to-review transition gate. Guides verification of plan alignment, test quality, and code simplification before marking implementation complete. Referenced by schema guidance fields during review-phase note filling. Read this skill when filling review-checklist notes or when asked to review completed implementation work.
work-summary
Generate a hierarchical project dashboard showing all work items organized by container, with IDs, tags, status, and priority visible. Always use this skill for any request about project status, work summaries, or item overviews — never construct dashboards manually with raw MCP calls. Trigger on any of these phrases or intent: "project status", "what's active", "show me the dashboard", "work summary", "summary", "what should I work on", "project health", "what's blocked", "where did I leave off", "show items", "what's in the backlog", "overview", or any request to see or review the current state of work items. This includes session-start context gathering — if you need to understand current project state, use this skill.
status-progression
Navigate role transitions for MCP work items using advance_item. Shows current role, gate status, required notes, and the correct trigger to use. Use when a user says "advance this item", "move to work", "start this task", "complete this item", "what's the next status", "why can't I advance", "unblock this", "cancel this item", or "check gate status".
schema-workflow
Guide an MCP work item through its schema-defined lifecycle — filling required notes using guidancePointer and advancing through gate-enforced phases. Internal skill triggered by hooks and output styles during orchestration workflows. Use when an item has schema tags and needs to progress through queue, work, review, or terminal phases with note gates.
quick-start
Interactive onboarding for the MCP Task Orchestrator. Detects empty or populated workspaces and walks through how plan mode, persistent tracking, and the MCP work together. Use when a user says "get started", "how do I use this", "quick start", "first time setup", "onboard me", "what can this MCP do", or "help me learn task orchestrator".
pre-plan-workflow
Internal workflow for plan mode — checks MCP for existing work, note schemas, and gate requirements to set the definition floor before planning begins. Triggered automatically when entering plan mode for any non-trivial implementation task.
post-plan-workflow
Internal workflow for post-plan materialization — creates MCP items from the approved plan and dispatches implementation. Triggered automatically after plan approval when MCP tracking is active.
manage-schemas
Create, view, edit, delete, and validate note schemas for the MCP Task Orchestrator in .taskorchestrator/config.yaml — the templates that define which notes agents must fill at each workflow phase. Use when user says "create schema", "show schemas", "edit schema", "delete schema", "validate config", "what schemas exist", "add a note to schema", "remove note from schema", or "configure gates".
dependency-manager
Visualize, create, and diagnose dependencies between MCP work items. Use when a user says "what blocks this", "add a dependency", "show dependency graph", "why can't this start", "link these items", "unblock this", "remove dependency", or "show blockers".
create-item
Create an MCP work item from conversation context. Scans existing containers to anchor the item in the right place (Bugs, Features, Tech Debt, Observations, etc.), infers type and priority, creates single items or work trees, and pre-fills required notes. Use this whenever the conversation surfaces a bug, feature idea, tech debt item, or observation worth tracking persistently. Also use when user says "track this", "log this bug", "create a task for", or "add this to the backlog".
batch-complete
Complete or cancel multiple items at once — close out features, clean up old work, archive completed workstreams. Use when a user says "close out this feature", "complete everything under X", "cancel this workstream", "clean up old items", "bulk complete", "finish this feature", or "archive completed work".