project-specs

Project Specs

Capture a finished exploration as a durable, living implementation package inside the repository. The package must hold the desired last form of the product, the full version roadmap toward that destination, and enough context that an agent who never saw the brainstorm can implement the current slice and later continue after the spec is updated.

This skill is the step immediately before implementation, and the spec refresh after each meaningful step:

brainstorm → specification → version roadmap → executable near-term tasks → implement → update spec → next version

It does not implement the project.

Choose the mode

• Create when no project specification package exists yet. Write the destination, the whole roadmap, and executable tasks for the first version.
• Update when a matching package already exists, including after a version, task, or experiment landed. Read it first and follow the update behavior in spec-structure.md. Implementation reality wins over outdated planning assumptions.

If the request is only a small coding task, an ordinary design question, a main README rewrite, or general Markdown cleanup, do not use this skill.

Operate in this order

Follow this pipeline; do not begin by filling a template:

gather → inspect → classify → research → specify → decompose → review → summarize → stop

1. Gather. Use whatever is available: the current conversation, user notes or handoffs, existing code and experiments, mentioned URLs, and previous spec files. Do not require every input. Do not ask for missing optional material unless two interpretations would produce materially different packages.
2. Inspect. Map the repository enough to reuse real infrastructure: stack, packages, conventions, existing experiments, constraints, and nearby code. Prefer concrete paths over generic architecture. Do not read the entire codebase blindly.
3. Classify. Separate what is decided, provisional, speculative, or in contradiction with earlier brainstorm turns. Identify assumptions that need experiments, technical risks, existing systems to reuse, things that should not be built yet, and premature abstractions.
4. Research. Preserve every important external reference. If browsing is available and understanding a linked repository, article, demo, paper, model, or tool would materially improve the spec, inspect it instead of judging it from its title. Catalog what to borrow and what not to copy blindly.
5. Specify. Read spec-structure.md. Create or update the project directory. Prefer an established repository documentation convention when one already exists; otherwise use docs/<project-slug>/.
6. Decompose. Read task-design.md. Write the full version sequence through the desired last form. Thoroughly task-split the current near-term version (V0 on create; the next incomplete version on update). Keep far-future versions directional, but present.
7. Review. Read quality-checklist.md and fix inconsistencies before finishing.
8. Summarize, then stop. Return the compact handoff below. Do not start V0, scaffold production architecture, or "just implement the first task."