/spec-design

name: spec-design
description: "Write OpenSpec design.md and tasks.md artifacts. TRIGGER when: producing a technical design or task checklist for a spec-driven feature. SKIP: writing proposal.md (use spec-research); executing tasks.md (use spec-develop)."

OpenSpec Design & Tasks Writing

Guide for creating `design.md` (WHAT + HOW) and `tasks.md` (implementation checklist).

Prerequisite

Read `{specs_path}/proposal.md` first. Reference its capabilities and impact sections.

**Path Enforcement**: The `specs_path` MUST be `.scaffolding/conversations/{UUID}/specs/` where `{UUID}` is a valid UUID (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). NEVER use descriptive folder names.

`.scaffolding/conversations/` is a symlink to `<share>/projects/<repo-name>/conversations` (paths below are unchanged; always go through the symlink).

design.md

Output Path

Write to: `{specs_path}/design.md`

Required Sections

| Section | Purpose | Format | |---------|---------|--------| | **Context** | Background, current state, constraints | Prose | | **Goals / Non-Goals** | Scope boundaries | Bullet lists | | **Specifications** | Requirements + scenarios | GIVEN/WHEN/THEN | | **Decisions** | Technical choices + rationale | Decision: Why X over Y | | **Risks / Trade-offs** | Known limitations | [Risk] -> Mitigation | | **Migration Plan** | Deploy + rollback steps | Checklist (if applicable) | | **Open Questions** | Unresolved items | Numbered list |

Specification Format

### Requirement: user-session-timeout

The system SHALL terminate idle sessions after 30 minutes.

#### Scenario: session expires after inactivity

- **GIVEN** a user has an active session
- **WHEN** no activity occurs for 30 minutes
- **THEN** the session is invalidated and user is redirected to login

Rules:

• Use SHALL/MUST for normative requirements (avoid should/may)
• Every requirement MUST have at least one scenario
• Each scenario is a potential test case
• Map capabilities from proposal.md to requirement groups

Decision Format

## Decisions

### Use Redis for session storage
**Alternatives**: PostgreSQL, in-memory
**Rationale**: Sub-millisecond lookups, built-in TTL, already in stack

Scaffolding Constraints

Include in all designs:

• Max 200 lines per Edit operation
• Files must stay under 500 lines
• Backend validation: `pytest`; Frontend: `npm run validate`
• Map steps to specific workflow chain agents

tasks.md

Output Path

Write to: `{specs_path}/tasks.md`

Format Rules

| Rule | Detail | |------|--------| | Group by `## N. Group Name` | Numbered headings | | Checkbox per task | `- [ ] N.M Task description` | | Dependency order | Tasks ordered by what must come first | | File paths | Include target file path in task | | Acceptance criteria | Each task independently verifiable | | Validation step | Include `pytest` / `npm run validate` per group | | Size | Each task completable in one session |

Template

## 1. Setup
- [ ] 1.1 Create `./backend` module structure
- [ ] 1.2 Add dependencies to `requirements.txt`

## 2. Core Implementation
- [ ] 2.1 Implement service in `./backend/service.py`
- [ ] 2.2 Add Pydantic schemas in `./backend/schemas.py`
- [ ] 2.3 Add router in `./backend/router.py`
- [ ] 2.4 Run validation: `pytest`

## 3. Frontend + Tests
- [ ] 3.1 Add types to `app/frontend/src/types/index.ts`
- [ ] 3.2 Create component, add unit + integration tests
- [ ] 3.3 Run validation: `npm run validate && pytest`

Quality Checklist

• [ ] design.md references proposal.md capabilities
• [ ] Every requirement has GIVEN/WHEN/THEN scenarios
• [ ] Decisions include alternatives considered
• [ ] Risks have specific mitigations
• [ ] tasks.md uses checkbox format (`- [ ]`)
• [ ] Tasks ordered by dependency
• [ ] Each group has a validation step
• [ ] File paths included in task descriptions