spec
Create or modify spec files following project methodology, and drive SDD (spec-first development). Use when writing, editing, or reviewing specs/ files; before implementing any feature or behavior change that affects a contract documented in specs/; and whenever the user asks anything about spec-first development — the SDD workflow, spec versioning rules, impact analysis, or what belongs in specs/ vs CLAUDE.md — even if they only ask a question rather than request an edit. Do not use for writing or debugging tests, including contract tests.
- License 许可
- MIT
- 最近更新
- 2026-10-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- spec
- description
- Create or modify spec files following project methodology, and drive SDD (spec-first development). Use when writing, editing, or reviewing specs/ files; before implementing any feature or behavior change that affects a contract documented in specs/; and whenever the user asks anything about spec-first development — the SDD workflow, spec versioning rules, impact analysis, or what belongs in specs/ vs CLAUDE.md — even if they only ask a question rather than request an edit. Do not use for writing or debugging tests, including contract tests.
- allowed-tools
- Bash, Read, Write, Edit, Glob, Grep
02 资源文件 5
- 参考文档references/curation-guide.md7.3 KB
- 脚本scripts/sdd-reminder.sh1.3 KB
- 参考文档templates/examples/example_format_spec.md1.6 KB
- 参考文档templates/index_template.md780 B
- 参考文档templates/spec_template.md611 B
03 SKILL.md 正文
Spec Maintenance
Apply this methodology when creating or modifying spec files.
TL;DR
Spec-first → Cross-file scan → Bump version → Implement → Full conformance check → Commit
| What you're doing | How to do it |
|---|---|
| Feature / bug fix | Spec first, bump version, then code |
| Impact scan (key!) | grep CLAUDE.md, README.md, other specs/ for references to the changed contract — add to change list |
| New definition | Minor bump (v1.0 → v1.1) |
| Behavioral change (breaking) | Major bump (v1.2 → v2.0) |
| Clarification / wording | Update date only, keep version |
| Commit | List all affected specs/docs in body |
| Unsure if content belongs | See curation-guide.md |
SDD Workflow (Spec-Driven Development)
Any feature or behavior change that touches a contract documented in specs/ MUST follow this loop. Specs describe the target state — code follows specs, not the other way around.
Phase 1 — Spec First (before writing any code)
- Impact analysis: determine which spec files/sections the change affects. If none, the SDD loop does not apply — proceed with normal development.
- Cross-file scan (mandatory): search the entire repo for other files that
reference the contract being changed — CLAUDE.md, README.md, other specs in
specs/, and any doc files. These are also affected and must be updated. Usegrep -rn "<key-term>" CLAUDE.md README.md specs/to find ripple effects. - Update all affected docs: the primary spec first (bump version per §Version Management), then every cross-referenced file found in step 2.
- Confirm the contract: present the spec change to the user for approval before implementing.
Phase 2 — Implement
- Write code to satisfy the updated spec. If during implementation the contract turns out to be wrong, go back to Phase 1 and change the spec — never silently diverge in code.
Phase 3 — Conformance Check (after code is complete)
- Primary spec: Re-read every section touched in Phase 1. Verify each contract line against the implementation: signatures, behaviors, edge cases, error/exit codes.
- Ripple check (mandatory): Re-read every cross-referenced file found in Phase 1 step 2. Verify they are still aligned with the implementation — stale keyboard shortcuts, outdated pipeline descriptions, missing new parameters, etc.
- On divergence: code bug → fix the code; contract was wrong → fix the spec (re-bump version), then re-verify.
Commit Ordering
- Spec and code changes belong to the same commit series; the spec commit precedes or accompanies the code commit.
- The feat/fix commit body lists all affected files — primary spec(s) plus any cross-referenced docs (CLAUDE.md, README.md) found in Phase 1 step 2.
- Any ripple-fix commits (CLAUDE.md, README.md alignment) discovered during Phase 3 belong in the same series, not deferred to a later session.
Specs Serve Two Readers
| Reader | Needs from specs |
|---|---|
| Agent (AI coding assistant) | Behavioral contracts — "what is correct" to verify compliance |
| Human developer | Understanding — "why" a contract exists and "what are the boundaries" |
Both readers matter. Content that explains a contract (not just defines it) should be kept.
Classification Principle
For each piece of content, ask: "When would I read this while writing code?"
| Answer | Layer | Typical Content |
|---|---|---|
| "Every change" | CLAUDE.md | Architecture hard constraints, global conventions (ordering/naming), high-frequency gotchas (encoding rules, state cleanup patterns), critical implementation details that affect every edit |
| "Specific task" | Specs — WHAT layer | External contract definitions — what the outside world expects from this system. Data formats, API/protocol specs, metric definitions, interface contracts with external systems. Includes explanations that clarify contract semantics (e.g., "why this field uses center coordinates, not top-left"). |
| "Specific task" | Specs — HOW layer | Internal module contracts — public API signatures, design constraints, option/parameter definitions, dependency rules, exception types and exit codes. How modules relate to each other, not how they are implemented internally. |
| "Neither" | Delete | — |
WHAT layer naming depends on project domain (see §Spec Directory Structure for the project-type mapping). HOW has exactly one modules/ layer.
Content Curation
The key question: does this define or help understand a behavioral contract? If unsure, see the curation guide for detailed judgment rules (6 content types, pre-deletion checks, interface-vs-implementation table).
Spec Directory Structure
WHAT vs HOW Separation
specs/
├── <contract-layer-1>/ # WHAT — external data/interface/protocol contracts
│ ├── index.md
│ └── spec_<topic>.md
│
├── <contract-layer-2>/ # WHAT — other contract layers (optional)
│ ├── index.md
│ └── spec_<topic>.md
│
└── modules/ # HOW — internal module architecture
├── index.md # Architecture diagram + hard constraints (single source of truth for module dependencies)
├── spec_<module-1>.md
├── spec_<module-2>.md
└── ...
WHAT layer naming depends on project domain:
| Project Type | Suggested Name | Example Content |
|---|---|---|
| Data processing / format conversion | formats/ |
Data format definitions, conversion rules |
| Web API | api/ |
REST/GraphQL interface contracts |
| Library / SDK | interfaces/ |
Public API signatures, type definitions |
| Evaluation / benchmarking | evaluate/ |
Metric definitions, baselines |
| Protocol / communication | protocols/ |
Message formats, state machines |
WHAT layers may have multiple; HOW has exactly one modules/, mirroring code modules.
Index Template
When creating a new layer index, use this template:
# <Layer Name> — Specification Index
> **Status:** Canonical — these documents define the authoritative
> <contract-type> for <project-name>.
## What This Layer Covers
Briefly describe what this layer defines and what it is the ground truth for.
## Documents
| # | Document | Purpose |
|---|----------|---------|
| 1 | `spec_xxx.md` | One-line description |
## Relationship to Other Layers
- This layer (WHAT) maps to which modules in `modules/` (HOW)
- This layer is independent of which other layers
## Reading Order
Recommended reading order by task:
- Newcomer → what to read first
- Specific task → what to read
What Each Spec Should Answer
| Spec Type | Questions It Answers |
|---|---|
| Data format / protocol spec | What does this external contract look like? What required fields are defined? |
| Conversion / adapter spec | How does A become B? How are edge cases handled? |
| Module spec | What are this module's public interfaces, design constraints, and behavioral contracts? |
A spec file should not answer both "what does the data look like" and "how does the code implement it" simultaneously. If both appear, split them.
Version Management
Each spec file starts with a version and last-updated date:
> **Version:** vX.Y | **Last Updated:** YYYY-MM-DD
| Scenario | Version Change |
|---|---|
| New definitions / extending existing contracts | Minor increment (v1.0 → v1.1) |
| Behavioral change (breaking change) | Major increment (v1.2 → v2.0) |
| Clarification / wording fix (no behavior change) | Update date only, keep version |
Bootstrap (First Use in a New Project)
The methodology itself needs no configuration. The SDD enforcement hook ships with the plugin and is active whenever the plugin is installed and enabled — no project-side hook setup.
The only project-side piece is documentation. If the project follows SDD (has a specs/ directory) but its CLAUDE.md lacks the SDD hard rules, append this section on first use:
## Spec Maintenance
**SDD hard rules:**
1. **Invoke `/maestro:spec` before any edit to `specs/` files** — the methodology must be loaded before touching spec content.
2. **Spec-first ordering**: any feat/fix that affects a contract documented in `specs/` must (a) update the affected spec to the target state **before** implementing, (b) verify the implementation against the spec **after** coding (conformance check), and (c) list the affected spec files in the commit body.
Degraded mode: if the plugin is not installed, there is no hook and no methodology to load — the project's CLAUDE.md rules (above) remain self-sufficient for manual adherence. If the user declines to add the rules, apply the methodology per this skill without persisting anything.
Required Configuration
None for the methodology itself — templates are bundled in templates/ within this skill's directory.
SDD enforcement is provided by the plugin:
- PreToolUse hook (
hooks/hooks.json) injects the SDD reminder onspecs/edits — active automatically while the plugin is enabled - CLAUDE.md "SDD hard rules" are the project-side documentation (see Bootstrap above)
04 同仓库更多 Skills
release
暂无简介
commit
Create git commits following project conventions. Use when committing code or preparing a commit message, and whenever the user asks anything about commit conventions — the commit message format, Conventional Commit type classification, the mandatory Co-Authored-By lines, or CHANGELOG maintenance rules (subsections, breaking-change marking, what to skip) — even if they only ask a question rather than request a commit.
claude
Write or update CLAUDE.md following project conventions. Use when adding gotchas, restructuring CLAUDE.md, or updating project documentation.
dataflow-cv
Use the dataflow-cv library (v3.0.0+) — CLI commands (analyse stats/split/filter/partition/sample, convert yolo2coco/yolo2labelme/labelme2yolo/labelme2coco/coco2yolo/coco2labelme, visualize yolo/labelme/coco, evaluate detection/segmentation with --prf1) and Python API (label handlers, 5 analysers, 3 converters, 3 visualizers, 2 evaluators, compute_pr_f1, LogConfig/LogManager). Use when working with dataflow-cv — building dataset pipelines, converting YOLO/LabelMe/COCO annotations, evaluating detections, debugging dataflow-cv errors — and whenever the user asks anything about dataflow-cv — CLI usage, API signatures, metric computation, format conversion rules, or install extras — even if they only ask a question rather than request an action. Do not use for other CV libraries, generic OpenCV usage, or general numpy questions.