Design/document specifications following strict template structure (syncs to Notion)
Generates project specifications following strict Notion template structure with 2-way Notion sync.
/plugin marketplace add alvis/.claude/plugin install specification@alvis<instruction> [--type=api|web-app|mobile|library|fullstack] [--stack=tech-hints] [--reference=docs] [--output=path] [--sync-template] [--skip-notion-sync]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, comparing local and remote content and requiring user confirmation for each discrepancy before syncing. All files maintain 1:1 mapping with Notion pages and include frontmatter metadata. Automatically syncs to Notion unless --skip-notion-sync is specified.
What this command does NOT do:
When to REJECT:
ultrathink: you'd perform the following steps
Actions:
Determine Operation Mode and Extract Package Name:
Load Existing Design (if UPDATE mode):
mcp__plugin_specification_notion__notion-fetchAnalyze Existing Codebase (if DOCUMENT mode):
Fetch Notion Template and Search Database:
mcp__plugin_specification_notion__notion-fetch to access template at: https://www.notion.so/2cc0248cba33432faba65985a2c65047mcp__plugin_specification_notion__notion-fetch for each childmcp__plugin_specification_notion__notion-search. Use fuzzy matching to find pages even if the Notion title doesn't exactly match the package name (account for case differences, special characters like @ or /, and partial matches). If an existing page is found in the database and the local frontmatter doesn't have a notion_url, store the found page URL for use in UPDATE mode during sync.Load Reference Documentation (if --reference provided):
mcp__plugin_specification_notion__notion-fetchParse --sync-template Flag (if provided):
Validate Setup:
[Conditional]: Only runs if existing Notion pages were found in Step 1
Actions:
Check Merge Requirement:
Spawn Merge Resolution Subagent:
mcp__plugin_specification_notion__notion-fetchWait for Merge Completion:
Update Todo List:
Proceed with Agreed State:
Actions:
Parse Arguments:
Clarify Scope (mode-dependent):
If CREATE mode:
If UPDATE mode:
If DOCUMENT mode (NEW):
Create Todo List:
[Mode-Dependent]: CREATE mode researches new stack. UPDATE mode researches only changed technologies. DOCUMENT mode extracts from existing code.
Actions:
Delegate Research:
If CREATE mode:
If UPDATE mode:
If DOCUMENT mode (NEW):
Process Results:
[Mode-Dependent]: CREATE designs from scratch. UPDATE modifies aspects. DOCUMENT extracts from code.
Actions:
Define System Architecture:
If CREATE mode:
If UPDATE mode:
If DOCUMENT mode (NEW):
Create Architecture Diagram:
[Mode-Dependent]: CREATE specifies all. UPDATE modifies affected. DOCUMENT extracts from code.
Actions:
Identify Components:
Detail Component Specifications:
Actions:
Define API Contracts:
Design Data Models:
Actions:
Define User Interface Structure:
Specify UI Components:
Actions:
Prepare Frontmatter Metadata:
Initialize frontmatter for all files:
---
notion_url: https://www.notion.so/... (if synced, else empty)
last_edited_at: 2025-10-25T10:30:00Z
last_synced_at: 2025-10-25T10:32:00Z (if synced, else empty)
related_files: [REFERENCE.md, ...] (for DESIGN.md) or [DESIGN.md] (for child files)
---
Use current ISO timestamp for last_edited_at
Leave notion_url and last_synced_at empty until Step 10
For DESIGN.md: related_files includes all child page files
For child files: related_files includes only DESIGN.md
Compile Design Document Following Template:
If CREATE mode:
If UPDATE mode:
If DOCUMENT mode (NEW):
Apply --sync-template if Provided:
Write Main File with Frontmatter:
Write Child Page Files with Frontmatter:
Update Todo List:
Only skip if --skip-notion-sync flag provided.
Actions:
Prepare Sync Payload:
Spawn Notion Sync Subagent:
notion-create-pages or notion-update-pageSpawn Verification Subagent:
notion-fetchSpawn Patching Subagent (if verification failed):
notion-update-pageUpdate Frontmatter (after successful sync):
Update DESIGN.md frontmatter:
---
notion_url: https://www.notion.so/main-page-id
last_edited_at: 2025-10-25T10:30:00Z
last_synced_at: 2025-10-25T10:32:00Z
related_files: [REFERENCE.md, ...]
---
Update each child page file frontmatter:
---
notion_url: https://www.notion.so/child-page-id
last_edited_at: 2025-10-25T10:30:00Z
last_synced_at: 2025-10-25T10:32:00Z
related_files: [DESIGN.md]
---
Use Edit tool for each file
Verify all files have non-empty notion_url
Count files updated (should match: 1 main + N children)
Update Todo List:
Output Format:
[✅/❌] Command: spec-code "$ARGUMENTS"
## Summary
- Mode: [CREATE / UPDATE / DOCUMENT]
- Package name: [name from package.json]
- Design document: [path]
- Child documents: [count and filenames]
- Template: Notion (https://www.notion.so/2cc0248cba33432faba65985a2c65047)
- Template sync: [Yes (--sync-template) / No]
- Project type: [type]
- Tech stack: [technologies or "Documented from code" if DOCUMENT mode]
- Sections [created/updated/documented]: [count]
- Frontmatter: Added to [count] files
- Notion database: Design Specification (https://www.notion.so/292b2572f78880fe95b9fdc8daeb862f)
- Notion sync: [Created in database / Updated existing page / Skipped]
- Database search: [Found existing page / No match found / Skipped]
- Sync verification: [✅ Verified / ⚠️ Partial / Skipped]
- Child pages synced: [count and URLs]
- All frontmatter populated: [Yes / No - missing: list]
- Merge performed: [Yes - Step 2 / No - new files]
- Conflicts detected: [count or N/A]
- Conflicts resolved: [count or N/A]
- User decisions: [Keep Local: X, Keep Remote: Y, Keep Both: Z, Skipped: W or N/A]
- Files merged: [list or N/A]
## Actions Taken
**If CREATE mode**:
1. Detected CREATE mode - greenfield design
2. Extracted package name from package.json: [package-name]
3. Loaded Notion template with [N] child pages
4. Searched Design Specification database - no existing page found
5. Researched tech stack: [technologies]
6. Designed architecture: [pattern]
7. Specified [N] components
8. [Designed API with N endpoints]
9. [Designed UI with N screens]
10. Generated DESIGN.md with frontmatter following template
11. Created [N] child files with frontmatter: [filenames]
12. [Synced to Notion database - created new page titled "[package-name]" with N child pages]
13. [Verified sync - ✅/⚠️]
14. Updated frontmatter in ALL files (main + N children) with Notion URLs and timestamps
**If UPDATE mode**:
1. Detected UPDATE mode - loaded existing design
2. Extracted package name from package.json: [package-name]
3. Loaded Notion template with [N] child pages
4. [Searched database - found existing page / used frontmatter URL]
5. [Performed 2-way merge - resolved X conflicts (Keep Local: Y, Keep Remote: Z, Keep Both: W, Skipped: V)]
6. Identified affected sections: [list]
7. [Updated architecture: changes]
8. [Modified components: list]
9. Merged changes preserving unaffected sections
10. Updated frontmatter timestamps
11. [Updated child files: list]
12. [Applied --sync-template: reorganized to match latest template]
13. [Synced to Notion database - updated existing page and N child pages]
14. [Verified sync - ✅/⚠️]
15. Updated frontmatter in ALL files (main + N children) with sync timestamps
**If DOCUMENT mode (NEW)**:
1. Detected DOCUMENT mode - analyzing existing codebase
2. Extracted package name from package.json: [package-name]
3. Loaded Notion template with [N] child pages
4. Searched Design Specification database - [found/not found] existing page
5. [Performed 2-way merge if existing page - resolved X conflicts]
6. Analyzed codebase structure in [directory]
7. Extracted tech stack from package.json: [technologies]
8. Documented architecture from file organization
9. Identified [N] components from code structure
10. [Extracted API endpoints from route files]
11. [Documented UI components from code]
12. Generated DESIGN.md with frontmatter documenting implementation
13. Created [N] child files with frontmatter: [filenames]
14. [Synced to Notion database - created/updated page titled "[package-name]" with N child pages]
15. [Verified sync - ✅/⚠️]
16. Updated frontmatter in ALL files (main + N children) with Notion URLs and timestamps
## Files Created/Updated
- DESIGN.md (with frontmatter)
- [Child page 1].md (with frontmatter)
- [Child page 2].md (with frontmatter)
- ...
## Frontmatter Details
All files include:
- notion_url: Notion page URL (1:1 mapping)
- last_edited_at: ISO timestamp of last edit
- last_synced_at: ISO timestamp of last Notion sync
- related_files: Array of related MD files ([child files] for DESIGN.md, [DESIGN.md] for child files)
## Template Adherence
- Structure: Follows template exactly
- Sections: Only template sections included
- Hierarchy: Matches template organization
- Diagrams: All in mermaid code blocks
- [Template sync applied: Yes/No]
## Notion Sync Details
- **Database**: Design Specification (https://www.notion.so/292b2572f78880fe95b9fdc8daeb862f)
- **Page title**: [package-name]
- **Main page**: [URL] - [✅/⚠️/❌]
- **Child pages**:
- [Page 1]: [URL] - [✅/⚠️]
- [Page 2]: [URL] - [✅/⚠️]
- **Fuzzy match applied**: [Yes - matched "X" to "Y" / No - exact match / No - new page]
- **1:1 Mapping**: Verified - all [N] files have notion_url populated
## Next Steps
1. Review DESIGN.md and child files
2. [Review Notion pages]
3. [Manually fix verification issues if needed]
4. Share with team for feedback
5. [Begin implementation following specs] (CREATE/UPDATE)
6. [Keep specs synchronized with code changes] (DOCUMENT)
/spec-code "Create REST API for task management with user auth"
# Mode: CREATE
# Extracts package name from package.json (e.g., "task-api")
# Creates DESIGN.md with frontmatter
# Creates child page files (REFERENCE.md, NOTES.md, UI.md, DATA.md)
# All files have frontmatter with timestamps and related_files
# Follows template structure exactly
# All diagrams created as mermaid code blocks
# Searches Design Specification database - no existing page found
# Creates new page in database titled "task-api"
# Creates child pages under main page
# Updates frontmatter in ALL files with notion_urls after sync
/spec-code "Add caching layer using Redis"
# Mode: UPDATE
# Extracts package name from package.json
# Checks frontmatter for existing notion_url
# If notion_url exists: Uses that page
# If not: Searches database for existing page
# Updates Architecture section only
# Updates frontmatter last_edited_at
# Preserves all other sections
# Syncs changes to Notion database
# Updates frontmatter in ALL files with last_synced_at
/spec-code "Update authentication flow"
# package.json has: "@company/auth-service"
# Local frontmatter has no notion_url
# Searches Design Specification database
# Finds existing page titled "Auth Service" via fuzzy matching
# (strips @, /, converts to lowercase, matches "auth-service" to "Auth Service")
# Updates that existing page in database
# Updates child pages
# Populates frontmatter in ALL files with notion_urls
/spec-code "Update architecture section"
# Step 1: Detects existing Notion pages
# Step 2: Spawn merge resolution subagent
# - Fetch Notion content
# - Compare with local files
# - Find 3 conflicts in DESIGN.md, 1 in REFERENCE.md
# - For each conflict:
# Conflict 1/4: Architecture Overview
# LOCAL: "Uses microservices architecture"
# NOTION: "Uses monolithic architecture"
# User selects: "Keep Local"
# Conflict 2/4: Tech Stack
# LOCAL: "Node.js 20, Express 5"
# NOTION: "Node.js 18, Express 4"
# User selects: "Keep Both"
# Conflict 3/4: New section in local
# LOCAL: "## Caching Strategy"
# NOTION: (missing)
# User selects: "Keep Local"
# Conflict 4/4: Removed section from local
# LOCAL: (missing)
# NOTION: "## Legacy API Support"
# User selects: "Keep Remote"
# - Apply decisions and update local files
# - Return merge report: 4 conflicts resolved
# Step 3-9: Continue with merged files as source of truth
# Step 10: Sync merged content to Notion
# Step 11: Report shows:
# - Merge performed: Yes
# - Conflicts detected: 4
# - Conflicts resolved: 4
# - User decisions: Keep Local: 2, Keep Remote: 1, Keep Both: 1, Skipped: 0
/spec-code "Add new feature section"
# Step 1: Detects existing Notion pages
# Step 2: Spawn merge resolution subagent
# - Fetch Notion content
# - Compare with local files
# - No conflicts found (local and Notion identical)
# - Skip merge, proceed immediately
# Step 3-9: Add new content to local files
# Step 10: Sync to Notion with only new additions
# Step 11: Report shows:
# - Merge performed: Yes
# - Conflicts detected: 0
# - Conflicts resolved: 0
# - User decisions: N/A
/spec-code "Refactor API documentation"
# Step 2: Merge resolution finds 5 conflicts
# - User resolves 3 conflicts (Keep Local/Remote/Both)
# - User skips 2 conflicts (marked as TODO for manual resolution)
# Local files updated with:
# - 3 resolved sections
# - 2 sections marked: "<!-- TODO: Resolve merge conflict -->"
# Step 10: Syncs to Notion with resolved content
# Step 11: Report shows:
# - Conflicts detected: 5
# - Conflicts resolved: 3
# - User decisions: Keep Local: 2, Keep Remote: 0, Keep Both: 1, Skipped: 2
# - Warning: 2 conflicts require manual resolution
/spec-code "Document the existing Express API in this codebase"
# Mode: DOCUMENT (auto-detected - codebase exists, no DESIGN.md)
# Extracts package name from package.json (e.g., "express-api")
# Analyzes codebase structure
# Extracts tech stack from package.json
# Documents actual architecture from code organization
# Identifies components from file structure
# Extracts API endpoints from route files
# Generates DESIGN.md documenting reality
# Creates child files with frontmatter
# Searches Design Specification database for "express-api"
# If found: Updates existing page with Status="Implemented"
# If not found: Creates new page in database with Status="Implemented"
# Creates/updates child pages
# Updates frontmatter in ALL files with notion_urls and timestamps
/spec-code "Retrospectively document this Next.js application" --type=web-app
# Mode: DOCUMENT
# Scans Next.js project structure
# Documents actual pages, components, API routes
# Extracts UI component tree from code
# Captures current tech decisions
# Follows template structure
# All files include frontmatter
# Syncs to Notion with 1:1 mapping
/spec-code "Add user analytics dashboard" --sync-template
# Mode: UPDATE
# Fetches latest template structure
# Adds missing sections from template
# Removes sections not in template
# Reorganizes content to match template
# Updates UI Design section with analytics
# Preserves all content, updates structure
# Updates frontmatter timestamps
# Syncs to Notion
/spec-code "Create e-commerce API" --type=api --sync-template
# Mode: CREATE
# Uses latest template structure
# Ensures strict template adherence
# Creates all sections matching template
# No custom sections added
# All files have frontmatter
# Syncs to Notion
/spec-code "Document existing microservices architecture" --skip-notion-sync
# Mode: DOCUMENT
# Analyzes microservices codebase
# Documents each service structure
# Creates DESIGN.md with frontmatter locally
# Creates child files with frontmatter
# Does NOT sync to Notion
# Frontmatter notion_url and last_synced_at remain empty
/spec-code "Update authentication to OAuth2" --output=docs/DESIGN.md
# Mode: UPDATE
# Updates docs/DESIGN.md
# Modifies auth-related sections
# Updates frontmatter in docs/DESIGN.md
# Updates child files in docs/ directory
# Syncs to Notion
/spec-code "Create SaaS platform" --type=fullstack --stack="Next.js, tRPC, Prisma" --reference="https://www.notion.so/saas-patterns"
# Mode: CREATE
# Fetches reference docs from Notion
# Uses suggested stack
# Follows template structure
# Creates DESIGN.md with frontmatter
# Creates all child page files with frontmatter
# Syncs to Notion
# Updates all frontmatter with URLs
/spec-code "app"
# Error: Please provide more details:
# - What does this app do?
# - Is this CREATE (new design), UPDATE (modify existing), or DOCUMENT (document code)?
# - What type of project?
/spec-code "Create API and add custom 'Future Enhancements' section"
# Warning: Template does not include 'Future Enhancements' section
# Cannot add sections outside template structure
# Please use only template sections or modify template first
/spec-code "Document the authentication module only"
# Mode: DOCUMENT
# Analyzes auth-related files only
# Documents auth component architecture
# Extracts auth API endpoints
# Creates focused DESIGN.md
# Follows template structure
# Includes frontmatter