spec-code

name	spec-code
description	Design/document specifications following strict template structure (syncs to Notion). Use when creating technical specifications, documenting API designs, or synchronizing specs with Notion.
model	opus
context	fork
agent	general-purpose
allowed-tools	Bash, Write, Read, Edit, Task, WebSearch, WebFetch, Glob, Grep, TodoWrite, AskUserQuestion
argument-hint	<instruction> [--type=api|web-app|mobile|library|fullstack]

Spec Code

Design new project specifications OR retrospectively document existing implementations in DESIGN.md format, following strict Notion template structure. Works in three modes: CREATE (greenfield design), UPDATE (modify existing specs), or DOCUMENT (analyze and document existing code). Performs 2-way merge with Notion by default.

🎯 Purpose & Scope

What this command does NOT do:

• Generate implementation code (specification only)
• Make technology decisions without analysis
• Add features not in the template structure
• Create custom sections outside template

When to REJECT:

• Vague instructions without clear context
• Requests for code implementation instead of specs
• Instructions requiring undecided implementation details
• Requests to add sections not in template

🔄 Workflow

ultrathink: you'd perform the following steps

Step 1: Detect Mode and Load Materials

1. Determine Operation Mode:

   • CREATE mode: No DESIGN.md AND no Notion page AND no codebase
   • UPDATE mode: DESIGN.md exists OR Notion page found
   • DOCUMENT mode: Codebase exists but no DESIGN.md

2. Load Existing Design (if UPDATE mode)

3. Analyze Existing Codebase (if DOCUMENT mode)

4. Fetch Notion Template

5. Load Reference Documentation (if --reference provided)

6. Parse --sync-template Flag (if provided)

Step 2: Resolve Merge Conflicts

(Only if existing Notion pages found)

• Spawn Merge Resolution Subagent
• Compare local vs Notion content
• Ask user for each difference (Keep Local / Keep Remote / Keep Both / Skip)
• Apply decisions to create merged content and return a merge report

See references/merge-resolution.md for the full conflict-resolution protocol, AskUserQuestion decision tree, and merge report format.

Step 3: Gather Requirements

1. Parse Arguments
2. Clarify Scope (mode-dependent)
3. Create Todo List

Step 4: Research Tech Stack

• CREATE: Research appropriate stack
• UPDATE: Research only changed technologies
• DOCUMENT: Extract from existing code (no research)

For DOCUMENT mode, see references/document-mode.md for the full codebase-extraction workflow (project scan, package.json parsing, tech stack derivation, mapping to spec sections).

Step 5: Design Architecture

• CREATE: Design from scratch
• UPDATE: Modify aspects
• DOCUMENT: Extract from code

Step 6: Specify Components

• Identify components
• Detail specifications

Step 7: Design APIs (if applicable)

• Define API Contracts
• Design Data Models

Step 8: Design UI (if applicable)

• Define User Interface Structure
• Specify UI Components

Step 9: Generate or Update Files with Frontmatter

1. Prepare Frontmatter Metadata
2. Compile Design Document Following Template
3. Apply --sync-template if Provided
4. Write Main File with Frontmatter
5. Write Child Page Files with Frontmatter

See references/frontmatter.md for the exact frontmatter schema (notion_url, last_edited_at, last_synced_at, related_files), filename mapping, and update rules.

Step 10: Sync to Notion

(Unless --skip-notion-sync)

1. Spawn Notion Sync Subagent (create or update in Design Specification database)
2. Spawn Verification Subagent (fetch Notion content, compare vs local)
3. Spawn Patching Subagent (if verification fails, max 3 retries)
4. Update Frontmatter with Notion URLs and last_synced_at

See references/notion-sync.md for the full 4-step sync protocol, subagent inputs/responsibilities, and database/page property rules.

Step 11: Reporting

Output Format:

[✅/❌] Command: spec-code "$ARGUMENTS"

## Summary
- Mode: [CREATE / UPDATE / DOCUMENT]
- Package name: [name]
- Design document: [path]
- Child documents: [count and filenames]
- Template: Notion
- Project type: [type]
- Tech stack: [technologies]
- Notion sync: [Created/Updated/Skipped]
- Sync verification: [✅ Verified / ⚠️ Partial / Skipped]

## Actions Taken
1. [Actions based on mode]

## Files Created/Updated
- DESIGN.md (with frontmatter)
- REFERENCE.md (with frontmatter)
- [Other child files]

## Template Adherence
- Structure: Follows template exactly
- Sections: Only template sections included

## Next Steps
1. Review DESIGN.md and child files
2. Share with team for feedback
3. Begin implementation following specs

📝 Examples

CREATE Mode - New API

/spec-code "Create REST API for task management with user auth"
# Mode: CREATE
# Creates DESIGN.md with frontmatter
# Creates child page files
# Syncs to Notion

UPDATE Mode - Add Feature

/spec-code "Add caching layer using Redis"
# Mode: UPDATE
# Updates Architecture section only
# Preserves all other sections
# Syncs changes to Notion

DOCUMENT Mode - Document Existing Code

/spec-code "Document the existing Express API in this codebase"
# Mode: DOCUMENT (auto-detected)
# Analyzes codebase structure
# Documents actual implementation
# Creates DESIGN.md from code analysis

With Type Specification

/spec-code "Create SaaS platform" --type=fullstack
# Uses fullstack template patterns

Skip Notion Sync

/spec-code "Document microservices" --skip-notion-sync
# Creates local files only
# Does NOT sync to Notion

Sync Template

/spec-code "Update API" --sync-template
# Updates to latest template structure
# Preserves content, reorganizes structure

Error Cases

/spec-code "app"
# Error: Please provide more details
# Suggestion: Describe what the app does

/spec-code "Create API with custom section"
# Warning: Template does not include custom section
# Cannot add sections outside template