writing-specs

# Writing Specifications

## Overview

A **specification** defines WHAT to build and WHY. It is NOT an implementation plan.

**Core principle:** Reference constitutions, link to docs, keep it lean. The `/plan` command handles task decomposition.

**Spec = Requirements + Architecture**
**Plan = Tasks + Dependencies**

## When to Use

Use this skill when:
- Invoked from `/spectacular:spec` slash command
- Creating a new feature specification from scratch
- Need the complete spec workflow (Run ID, worktree, brainstorm, spec, validation)

Do NOT use for:
- Implementation plans with task breakdown - Use `/spectacular:plan` instead
- API documentation - Goes in code comments or separate docs
- Runbooks or operational guides - Different document type

**Announce:** "I'm using the writing-specs skill to create a feature specification."

## Workspace Detection

Before starting the spec workflow, detect the workspace mode:

```bash
# Detect workspace mode
REPO_COUNT=$(find . -maxdepth 2 -name ".git" -type d 2>/dev/null | wc -l | tr -d ' ')
if [ "$REPO_COUNT" -gt 1 ]; then
  echo "Multi-repo workspace detected ($REPO_COUNT repos)"
  WORKSPACE_MODE="multi-repo"
  WORKSPACE_ROOT=$(pwd)
  # List detected repos
  find . -maxdepth 2 -name ".git" -type d | xargs -I{} dirname {} | sed 's|^\./||'
else
  echo "Single-repo mode"
  WORKSPACE_MODE="single-repo"
fi
```

**Single-repo mode (current behavior):**
- Specs stored in `specs/{runId}-{feature}/spec.md` at repo root
- Worktree created at `.worktrees/{runId}-main/`
- Constitution referenced from `@docs/constitutions/current/`

**Multi-repo mode (new behavior):**
- Specs stored in `./specs/{runId}-{feature}/spec.md` at WORKSPACE root
- NO worktree created (specs live at workspace level, not inside any repo)
- Each repo's constitution referenced separately

## Constitution Adherence

**All specifications MUST follow**: @docs/constitutions/current/
- architecture.md - Layer boundaries, project structure
- patterns.md - Mandatory patter