Your First Spec

This tutorial will guide you through creating your first specification document.

Prerequisites

• Node.js 18+ installed
• SuperSpec CLI installed

# Verify installation
superspec --version

Scenario

Let's add an avatar upload feature to a web application.

Step 1: Initialize Project

If your project hasn't been initialized with SuperSpec:

cd your-project
superspec init

This creates:

.superspec/
├── AGENTS.md           # AI assistant instructions
├── superspec.config.json   # Configuration
└── changes/            # Changes directory

Step 2: Create Change

In your AI assistant:

/ss-create avatarUpload

The CLI creates folder + git branch. AI generates proposal.md and checklist.md. After checklist passes, proceed.

Step 3: Review Proposal

AI generates proposal. Example content:

# Proposal: avatarUpload

## Overview
Add avatar upload functionality with cropping and preview.

## Background
Users currently have no avatar feature. Product wants to
increase user engagement and personalization.

## Goals
1. Users can upload images as avatars
2. Support cropping and preview before upload
3. Limit image size and format

## Approach
- Frontend: React + react-image-crop
- Backend: New /api/avatar endpoint
- Storage: Cloud storage (S3/OSS)

## Scope
- Frontend: UserProfile component
- Backend: user.controller.ts, user.service.ts
- Database: Add avatar_url to users table

Step 4: Generate Tasks

Use AI assistant to generate tasks:

/ss-tasks

AI reads proposal.md and generates tasks.md:

# Tasks: avatarUpload

## Task List

- [ ] 1. Database: Add avatar_url column to users table
- [ ] 2. Backend: Create POST /api/avatar endpoint
- [ ] 3. Backend: Image validation (size, format)
- [ ] 4. Backend: Cloud storage upload logic
- [ ] 5. Frontend: AvatarUpload component
- [ ] 6. Frontend: Image cropping functionality
- [ ] 7. Frontend: Preview functionality
- [ ] 8. Frontend: Integrate into UserProfile
- [ ] 9. Testing: API tests
- [ ] 10. Testing: E2E tests

## Progress
- Total: 10
- Done: 0
- In Progress: 0

Step 5: Execute Tasks

Implement tasks one by one using /ss-apply:

/ss-apply 1

AI implements task 1 (database migration) and updates tasks.md:

- [x] 1. Database: Add avatar_url column to users table

Continue with other tasks...

Step 6: Archive

When all tasks are complete, archive the change:

superspec archive avatarUpload

This moves the change to .superspec/archive/ preserving complete history.

Summary

Through this tutorial, you learned:

1. Initialize - superspec init
2. Create - /ss-create (folder + branch, then AI generates proposal + checklist)
3. Review proposal - AI generates, you confirm
4. Generate tasks - /ss-tasks
5. Execute - /ss-apply
6. Archive - superspec archive

Next Steps

• Team Workflow - Team collaboration
• Complex Feature - Using Boost mode
• CLI Reference - All commands