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:

# 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 patterns (next-safe-action, ts-pattern, etc.)
• schema-rules.md - Database design philosophy
• tech-stack.md - Approved libraries and versions
• testing.md - Testing requirements