Artifacts Reference

Artifacts are the core document units in the SuperSpec workflow. This document provides detailed information about each artifact's purpose and structure.

Artifact Overview

Artifact	Mode	Purpose
proposal.md	Standard/Boost	Change proposal (Standard: requirements + tech solution; Boost: requirements background)
spec.md	Boost	Requirement details + interactions (US/FR/AC)
design.md	Boost	Design document (optional, auto-detected)
tasks.md	Standard/Boost	Task checklist
checklist.md	Standard/Boost	Quality gate (Standard: /10 after proposal; Boost: /25 after spec)
clarify.md	Standard/Boost	Clarification record
context.md	Auto-generated	Context restoration

Standard Mode vs Boost Mode

CLI superspec create only creates folder + git branch. AI generates artifacts on demand via /ss-create.

Standard Mode

superspec/changes/<name>/
├── proposal.md     # AI generates (requirements + technical solution)
├── checklist.md    # AI generates (quality gate /10)
├── tasks.md        # AI generates via /ss-tasks
└── clarify.md     # On demand

Boost Mode

superspec/changes/<name>/
├── proposal.md     # AI generates (requirements background)
├── spec.md         # AI generates (requirement details + interactions)
├── design.md       # AI generates when needed (optional)
├── checklist.md    # AI generates (quality gate /25)
├── tasks.md        # AI generates via /ss-tasks
└── clarify.md     # On demand

---

proposal.md

Purpose

Standard: Requirements + technical solution (self-contained, ready to split tasks).

Boost: Requirements background describing:

• Goals, Non-Goals
• Impact and Risks
• Solution Overview

When to Use

• Starting a new feature or fix
• Defining change scope
• Getting team buy-in

Best Practices

Do:

• Clearly describe the problem
• Define measurable success criteria
• List key trade-offs

Avoid:

• Excessive implementation details
• Lengthy background introductions
• Vague success criteria

---

spec.md (Boost Mode)

Purpose

Requirement details + interactions, providing:

• User Stories (US)
• Functional Requirements (FR)
• Acceptance Criteria (AC)

Structure

User Stories (US)
├── US-1: ...
├── US-2: ...
└── ...

Functional Requirements (FR)
├── FR-1: ... (related to US-1)
├── FR-2: ... (related to US-1, US-2)
└── ...

Acceptance Criteria (AC)
├── AC-1: ... (related to FR-1)
├── AC-2: ... (related to FR-2)
└── ...

Cross-References

Each element should have clear reference relationships:

US-1 ←→ FR-1, FR-2 ←→ AC-1, AC-2

Use validate --check-deps to verify reference integrity.

---

design.md (Boost Mode, Optional)

Purpose

Technical design document (auto-generated when cross-system or major architecture), including:

• Architecture overview
• Component design
• Data model
• API design
• Technology choices

When to Use

• Complex features requiring design review
• Introducing new technologies or patterns
• Cross-team collaboration

Best Practices

Do:

• Use diagrams to illustrate architecture
• Define interfaces in detail
• Document technology choice reasoning

Avoid:

• Copying spec content
• Overly detailed implementation code
• Ignoring non-functional requirements

---

tasks.md

Purpose

Task checklist that breaks specs into executable tasks:

• Organized by phases
• Each task < 1 hour
• Parallel tasks marked

Task Granularity

Each task should:

• Be independently completable
• Have clear completion criteria
• Take < 1 hour

Parallel Marker

Use [P] to mark tasks that can run in parallel:

### Task 1: Create database model
### Task 2: Create API routes [P]
### Task 3: Create frontend components [P]
### Task 4: Integration tests

Tasks 2 and 3 can be executed in parallel with Task 1.

---

checklist.md (Both Modes)

Purpose

Quality gates ensuring changes meet quality standards. Standard: /10 after proposal. Boost: /25 after spec. Auto-invoked during /ss-create, also callable manually.

• Code quality
• Test coverage
• Security checks
• Performance requirements
• Documentation completeness

When to Use

• Run /ss-checklist before apply
• Ensure all items pass before archiving

---

clarify.md

Purpose

Record requirement clarifications and design decisions:

• Questions raised
• Discussion process
• Final decisions
• Decision reasoning

When to Use

• When requirements are unclear
• When multiple implementation approaches exist
• When important decisions need to be recorded

---

context.md (Auto-generated)

Purpose

Auto-generated by the sync command for Vibe Coding:

• Change overview
• Current progress
• Git diff
• Pending tasks

When Generated

• Running superspec sync
• Running /ss-resume (auto-triggers sync)

Do Not Edit Manually

context.md is regenerated on each sync; manual edits will be overwritten.

---

Artifact Status

Each artifact has a status defined in its frontmatter:

Status	Description
draft	Draft, not yet complete
ready	Ready, content complete
done	Done, validated

---
name: add-user-auth
status: ready
---

Use superspec status to view all artifact statuses.

---

Size Limits

To optimize AI context windows, each artifact has size limits:

Limit	Default
Target	300 lines
Hard limit	400 lines

Use superspec lint to check for violations.

Handling Violations

1. Trim content: Remove non-essential information
2. Split changes: Break large changes into multiple smaller ones
3. Use references: Reference external documents instead of inlining