From coordinator
Write a specification document — the contract between product (what), engineering (how), and QA (verify). Produces a structured spec with user stories, acceptance criteria, API contracts, and data model. Use after decompose-initiative to define what will be built before development starts.
npx claudepluginhub hpsgd/turtlestack --plugin coordinatorThis skill is limited to using the following tools:
Write a specification document for $ARGUMENTS. The spec is the contract between product (what), engineering (how), and QA (verify). Use `/coordinator:decompose-initiative` first to identify workstreams, then write a spec for each workstream before development starts.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Calculates TAM/SAM/SOM using top-down, bottom-up, and value theory methodologies for market sizing, revenue estimation, and startup validation.
Write a specification document for $ARGUMENTS. The spec is the contract between product (what), engineering (how), and QA (verify). Use /coordinator:decompose-initiative first to identify workstreams, then write a spec for each workstream before development starts.
Before specifying a solution, establish what problem exists and for whom:
### Problem Definition
| Question | Answer |
|---|---|
| **What problem are we solving?** | [Specific problem — not "improve the experience"] |
| **Who has this problem?** | [Specific user type — not "users"] |
| **How do we know it's a problem?** | [Evidence — support tickets, analytics, user research, business metric] |
| **What does success look like?** | [Measurable criteria — "reduce checkout abandonment from 40% to 25%"] |
| **What happens if we don't solve it?** | [Cost of inaction — quantified if possible] |
Scan the codebase for existing implementations related to this feature. Use Glob and Grep to find relevant code, tests, and documentation that inform the spec.
Output: Completed problem definition table with evidence.
For each distinct user need, write a story in standard format with RICE scoring:
### User Stories
| ID | Story | RICE Score | Priority |
|---|---|---|---|
| US-1 | As a [user type], I want [capability] so that [benefit] | R:_ I:_ C:_ E:_ = _ | P0/P1/P2 |
| US-2 | ... | ... | ... |
RICE components:
Stories must be independent, negotiable, valuable, estimable, small, and testable (INVEST).
Output: Prioritised user story table with RICE scores.
For each user story, write acceptance criteria in Given/When/Then format covering happy path, error cases, and edge cases:
### US-1: [Story title]
#### Happy path
- **Given** [precondition]
- **When** [action]
- **Then** [expected outcome]
#### Error cases
- **Given** [precondition]
- **When** [invalid action or failure condition]
- **Then** [error handling — message, rollback, retry]
#### Edge cases
- **Given** [boundary condition — empty, maximum, concurrent, timeout]
- **When** [action at boundary]
- **Then** [expected behaviour at boundary]
Every story must have at least: 1 happy path, 2 error cases, and 2 edge cases. If you cannot write acceptance criteria for a story, the story is too vague — rewrite it.
Output: Acceptance criteria for every user story.
For each endpoint or interface the feature requires:
### API Contract
#### [METHOD] /path/to/resource
**Purpose:** [What this endpoint does]
**Request:**
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
| field_name | string | Yes | max 255, regex pattern | [What it represents] |
**Response (200):**
```json
{
"id": "uuid",
"field": "value",
"created_at": "ISO8601"
}
Error responses:
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | [Specific trigger] |
| 404 | NOT_FOUND | [Specific trigger] |
| 409 | CONFLICT | [Specific trigger] |
| 422 | UNPROCESSABLE | [Specific trigger] |
If an [OpenAPI](https://www.openapis.org/) specification exists in the codebase, reference and extend it rather than duplicating.
**Output:** API contract for every endpoint with request/response schemas and error codes.
## Step 5: Define Data Model
Document entities, relationships, and constraints:
```markdown
### Data Model
#### [Entity Name]
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | UUID | PK, generated | Primary identifier |
| field_name | varchar(255) | NOT NULL, UNIQUE | [Purpose] |
| status | enum | CHECK(status IN ('active','archived')) | [State machine description] |
| created_at | timestamptz | NOT NULL, DEFAULT now() | Record creation time |
#### Relationships
- [Entity A] 1:N [Entity B] via `entity_a_id` FK
- [Entity C] M:N [Entity D] via `entity_c_d` join table
#### Indexes
| Index | Columns | Type | Rationale |
|---|---|---|---|
| idx_entity_status | status, created_at | btree | Filter active records by date |
#### Migration notes
- [Breaking changes, backfill requirements, rollback strategy]
Check existing models in the codebase with Grep to ensure consistency with established patterns.
Output: Data model with entities, relationships, constraints, indexes, and migration notes.
### Non-Functional Requirements
| Category | Requirement | Measurement | Target |
|---|---|---|---|
| **Performance** | API response time | p95 latency | < 200ms |
| **Performance** | Throughput | Requests/second | > 100 rps |
| **Scalability** | Concurrent users | Load test | [target] |
| **Security** | Authentication | [mechanism] | [standard] |
| **Security** | Authorisation | [model — RBAC, ABAC] | [policy] |
| **Accessibility** | WCAG compliance | Automated + manual audit | WCAG 2.1 AA |
| **Reliability** | Availability | Uptime monitoring | 99.9% |
| **Observability** | Logging/metrics | [tools] | [what to capture] |
Output: NFR table with measurable targets.
Exhaustively enumerate edge cases — this is where bugs hide:
### Edge Cases
| # | Category | Scenario | Expected Behaviour |
|---|---|---|---|
| E1 | Empty state | No data exists yet | [Behaviour — empty state UI, default values] |
| E2 | Maximum | Field at max length/value | [Behaviour — validation, truncation] |
| E3 | Concurrent | Two users edit same record | [Behaviour — optimistic locking, conflict resolution] |
| E4 | Network | Request timeout mid-operation | [Behaviour — retry, idempotency, partial state] |
| E5 | Permissions | User lacks required role | [Behaviour — 403, UI state] |
| E6 | Migration | Existing data with old schema | [Behaviour — backfill, defaults] |
Output: Edge case table — minimum 10 entries for any non-trivial feature.
### Open Questions (BLOCKS development)
| # | Question | Owner | Deadline | Impact if unresolved |
|---|---|---|---|---|
| Q1 | [Unresolved decision] | [Who decides] | [Date] | [What is blocked] |
### Out of Scope
| Item | Reason | Future consideration? |
|---|---|---|
| [Excluded capability] | [Why excluded] | [Yes — v2 / No — never] |
Open questions must be resolved before development starts on the affected area.
Output: Open questions with owners and deadlines; explicit out-of-scope list.
Request sign-off from all three perspectives:
### Three Amigos Review
| Role | Reviewer | Status | Comments |
|---|---|---|---|
| **Product** | [name/role] | [Pending/Approved/Changes requested] | [Feedback] |
| **Architecture** | [name/role] | [Pending/Approved/Changes requested] | [Feedback] |
| **QA** | [name/role] | [Pending/Approved/Changes requested] | [Feedback] |
**Review date:** [date]
**Spec status:** [Draft / In review / Approved / Superseded]
Output: Review tracker with sign-off status.
# Specification: [Feature Name]
**Version:** [number] | **Date:** [date] | **Status:** [Draft/In review/Approved]
## 1. Problem Definition
[From Step 1]
## 2. User Stories
[From Step 2 — prioritised with RICE scores]
## 3. Acceptance Criteria
[From Step 3 — per story, Given/When/Then]
## 4. API Contract
[From Step 4 — endpoints, schemas, errors]
## 5. Data Model
[From Step 5 — entities, relationships, migrations]
## 6. Non-Functional Requirements
[From Step 6 — measurable targets]
## 7. Edge Cases
[From Step 7 — exhaustive list]
## 8. Open Questions & Out of Scope
[From Step 8 — blockers and exclusions]
## 9. Review Status
[From Step 9 — three amigos sign-off]
/coordinator:decompose-initiative — produces workstreams that need specs. Decompose the initiative first, then write a spec for each workstream./qa-lead:test-strategy — detailed test strategy for the feature. Write the spec first, then define how to test it./product-owner:write-user-story — story format and refinement guidance. Use when stories need deeper elaboration.