v1.0.0 to git:20260917.83580e3

- description: >

- Write a feature spec (*-spec.md) for an issue. The spec is the human-written

- requirements document that feeds into the planning agent. Part of the

- spec → plan → implement pipeline.

- allowed-tools:

- - Read

- - Write

- - Bash

- - Grep

- - Glob

- - ToolSearch

- version: "1.0.0"

- author: "Ed Becker"

- license: "MIT"

- # Write Feature Spec

-

- **Trigger:** `/write-spec <issue-id>` or `/write-spec <issue-id> <title>`

-

- ## The Spec → Plan Pipeline

-

- Overdeck uses a two-stage planning process:

-

- 1. **Spec** (`*-spec.md`) — Human-written (often with AI assistance). Defines WHAT to build and WHY. Contains requirements, constraints, scope, research, and design decisions.

- 2. **Plan** (`*-plan.md`) — Generated by the planning agent. Defines HOW to build it. Contains architecture, tasks with dependencies, file-level changes, and difficulty estimates.

-

- The planning agent reads the spec as its primary input, explores the codebase, asks clarifying questions, then produces the implementation plan.

-

- ## When to Write a Spec

-

- - **Complex features** (multi-file, cross-cutting, architectural) — always write a spec first

- - **Features with research** — when you've explored options, talked to stakeholders, or analyzed competitors

- - **Features with constraints** — when there are specific technical or UX requirements the agent needs to know

- - **Simple bug fixes or small changes** — skip the spec, go directly to planning or implementation

-

- ## Execution Steps

-

- ### 1. Identify the Issue

-

- Parse the issue ID from the command argument. Determine the project:

- - `MIN-XXX` → MYN project, docs at `~/Projects/myn/docs/`

- - `PAN-XXX` → Overdeck project, docs at `~/Projects/overdeck/docs/`

-

- ### 2. Gather Context

-

- - Fetch the issue from the tracker (Linear for MIN, GitHub for PAN) to get title, description, comments

- - Check if a spec already exists at `docs/prds/active/{issue-id-lowercase}-*-spec.md`

- - If updating an existing spec, read it first

-

- ### 3. Research (Interactive)

-

- Use AskUserQuestion or discussion to understand:

- - What problem does this solve?

- - Who benefits?

- - What's in scope vs out of scope?

- - Any technical constraints or preferences?

- - Are there related specs or prior art to reference?

-

- ### 4. Write the Spec

-

- Create the file at: `docs/prds/active/{issue-id-lowercase}-{short-title}-spec.md`

-

- Use this structure:

-

- ```markdown

- # {Issue ID}: {Title}

-

- ## Problem Statement

- What problem does this solve? Why does it matter?

-

- ## Requirements

- ### Must Have

- - Requirement 1

- - Requirement 2

-

- ### Should Have

- - Nice-to-have 1

-

- ### Out of Scope

- - Explicitly excluded items

-

- ## Design

- ### User Experience

- How should it work from the user's perspective?

-

- ### Technical Approach

- High-level technical direction (NOT implementation details — that's for the plan).

-

- ### Constraints

- - Performance requirements

- - Compatibility requirements

- - Security considerations

-

- ## References

- - Related issues: MIN-XXX, MIN-YYY

- - Prior art: links to existing code, docs, or external references

- - Research: any analysis or competitor research

-

- ## Open Questions

- - Questions to resolve during planning

- ```

-

- ### 5. Confirm File Location

-

- After writing, confirm:

- ```

- Spec written: docs/prds/active/{filename}-spec.md

-

- Next steps:

- 1. Review and edit the spec as needed

- 2. Click "Plan" on the issue in the dashboard

- 3. The planning agent will read this spec and produce an implementation plan

- ```

-

- ## File Naming Convention

- | Type | Pattern | Created By | Example |

- |------|---------|-----------|---------|

- | Spec | `{issue-id}-{title}-spec.md` | Human (this skill) | `min-734-kaia-openclaw-a2a-spec.md` |

- | Plan | `{issue-id}-plan.md` | Planning agent | `min-734-plan.md` |

- Both live in `docs/prds/active/`. Specs are never overwritten by agents.

- ## Important Notes

- - **Specs are for humans** — write clearly, include context and rationale

- - **Plans are for agents** — the planning agent produces structured, actionable tasks

- - **Don't over-specify implementation** — the planning agent + codebase exploration will figure out the HOW

- - **DO specify constraints** — things the agent can't discover on its own (performance targets, UX requirements, API contracts)

- - **Reference existing code** — point to patterns, files, or modules the agent should follow