Stats
Actions
Tags
From compozy
Use when writing tech specs, creating task manifests, decomposing features into tasks, or authoring architecture documents from requirements
How this skill is triggered — by the user, by Claude, or both
Slash command
/compozy:spec-authoringThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Technical specifications bridge the gap between product requirements and implementation. A well-written spec enables parallel execution by multiple agents, each working on independent tasks without conflicts. This skill provides the knowledge and templates needed to author specs that are precise enough for automated implementation.
Technical specifications bridge the gap between product requirements and implementation. A well-written spec enables parallel execution by multiple agents, each working on independent tasks without conflicts. This skill provides the knowledge and templates needed to author specs that are precise enough for automated implementation.
Key concepts:
Every section of the spec template exists for a reason. Skipping sections creates ambiguity that surfaces as bugs during implementation. When in doubt, be explicit.
A spec is ready when someone unfamiliar with the codebase can implement it by following the spec alone. This means:
The spec must enable multiple agents to work simultaneously without conflicts:
Every requirement maps to at least one acceptance criterion. Criteria use concrete, verifiable language:
{\"error\": \"not_found\"} when user ID doesn't exist" (testable)Metadata: title, author, date, status (draft/approved/implemented), PRD source reference, and version.
2-3 paragraphs explaining what is being built and why. Written for someone with no context. Include the user problem being solved and the high-level approach.
Two tables — Functional Requirements (FR) and Non-Functional Requirements (NFR). Each row has an ID (FR-1, NFR-1), description, priority (must/should/could), and source (which part of the PRD).
Design decisions with rationale. Component diagram showing how pieces interact. ADR-style entries for significant choices: "We chose X over Y because Z."
Per-component detail: responsibility, public API, internal structure, dependencies. This is the largest section and should be exhaustive.
Schema definitions, type definitions, database migrations. Include field types, constraints, defaults, and indexes.
Critical for parallelization. A table mapping every file to be created or modified to exactly one task. No file appears in more than one task. Shared code goes in earlier waves.
Request/response schemas, function signatures, event payloads. These contracts are the "handshake" between components built by different tasks.
How each error type is handled: validation errors, network failures, auth failures, unexpected exceptions. Include error response formats and logging requirements.
Numbered list of testable conditions that must pass for the spec to be considered implemented. Map back to requirements IDs.
Explicitly list what this spec does NOT cover. Prevents scope creep during implementation and review.
Table of risks with likelihood, impact, and mitigation strategy. Include both technical risks (performance, compatibility) and process risks (timeline, dependencies).
Tasks are grouped into waves. All tasks in a wave can execute in parallel. Waves execute sequentially — wave N+1 starts only after all tasks in wave N complete.
Wave ordering rules:
The most important constraint for parallel execution: each file is owned by exactly one task. If two tasks need to modify the same file, either:
Tasks should be large enough to be meaningful (not "add one import") but small enough to be independent (not "implement the entire feature"). A good task typically:
Vague component specs: "The auth module handles authentication" tells an implementer nothing. Specify endpoints, middleware, token formats, storage, and error responses.
Missing interface contracts: Two components that need to communicate must have their interface defined in the spec. Otherwise, each task's agent will guess differently.
Circular dependencies between tasks: If Task A needs output from Task B and Task B needs output from Task A, they can't run in parallel. Restructure to break the cycle.
Forgetting existing code: Specs for modifications must reference the current state of the code. Include file paths and relevant function names.
Over-decomposition: 20 tiny tasks with complex dependencies are harder to manage than 6 substantial tasks with simple wave ordering.
For templates and examples, see files in references/ and examples/ directories.
npx claudepluginhub higoralves/claude-plugin --plugin compozyWrites structured specifications before coding. Use when requirements are ambiguous, starting a new project/feature, or changes touch multiple files.
Writes OpenSpec design.md and tasks.md artifacts for spec-driven features. Useful when producing technical designs or task checklists from a proposal.
Decomposes an approved design document into vertical specs (requirements, design, tasks) for independent delivery. Orders work hardest-first with approval gates.