CafeKit Spec
Docs
Getting started
Quick Start

What You'll Build#

In this quickstart, you'll create a spec for a user login feature using the full workflow of the CafeKit workflow.

Time to complete: 5-10 minutes

Before You Start: Set Up Documentation (Optional)#

For the best results when working with AI, it's recommended to set up your project documentation first. This helps the AI understand your project structure and conventions before you start creating specs.

/docs init

This will analyze your codebase and create:

  • docs/ folder with project standards and architecture context
  • docs/ folder with coding standards, architecture, and guidelines

You can also update docs later with /docs update.

Step 1: Initialize Spec#

Start by creating a new spec workspace:

/spec-init login-feature

What happens:

  • Creates .specs/login-feature/ directory
  • Generates initial folder structure
  • Sets up tracking files

Expected output:

✅ Spec initialized: login-feature
📁 Created .specs/login-feature/
📄 Next step: Run /spec-requirements

Step 2: Gather Requirements#

Define what your feature needs to do:

/spec-requirements login-feature

The AI assistant will ask you questions like:

  • What is the main goal of this feature?

    • "Allow users to log in with email and password"

  • Who will use this feature?

    • "End users of the application"

  • What are the must-have functionalities?

    • Email/password validation
    • Session management
    • Error handling for invalid credentials

  • Any constraints or technical requirements?

    • Must work on mobile and desktop
    • Use JWT for authentication
    • Password requirements: min 8 chars, 1 uppercase, 1 number

What happens:

  • AI guides you through Socratic questioning
  • Captures all functional and non-functional requirements
  • Creates requirements.md in .specs/login-feature/

Expected output:

✅ Requirements captured
📄 Saved to .specs/login-feature/requirements.md
📋 Next step: Run /spec-design

Step 3: Create Design Document#

Generate a technical design from your requirements:

/spec-design login-feature

What happens:

  • AI reads your requirements
  • Creates architecture diagram
  • Defines API endpoints, database schema, UI components
  • Identifies edge cases and error scenarios
  • Generates design.md

Sample design output:

# Login Feature - Design Document

## Architecture
- Frontend: React login form component
- Backend: POST /api/auth/login endpoint
- Database: users table with hashed passwords

## API Design
POST /api/auth/login
{
  "email": "user@example.com",
  "password": "SecurePass123"
}

## Database Schema
users table:
- id (UUID, primary key)
- email (string, unique)
- password_hash (string)
- created_at (timestamp)

## UI Components
- LoginForm.tsx
- PasswordInput.tsx (with visibility toggle)
- ErrorMessage.tsx

## Security Measures
- bcrypt password hashing
- Rate limiting (5 attempts per minute)
- JWT token expiry (24 hours)

Expected output:

✅ Design document created
📄 Saved to .specs/login-feature/design.md
🎯 Next step: Run /spec-tasks

Step 4: Generate Task Breakdown#

Break the design into actionable implementation tasks:

/spec-tasks login-feature

What happens:

  • AI analyzes design document
  • Creates prioritized task list
  • Estimates time for each task
  • Defines dependencies between tasks
  • Generates tasks.md (sprint plan)

Sample tasks output:

# Login Feature - Sprint Plan

## TASK 1: Setup Database Schema (30 min)
**Priority:** P0 (Blocker)
**Dependencies:** None

- Create users table migration
- Add email uniqueness constraint
- Test migration rollback

## TASK 2: Implement Password Hashing (45 min)
**Priority:** P0 (Blocker)
**Dependencies:** TASK 1

- Install bcrypt
- Create hashPassword() utility
- Create verifyPassword() utility
- Write unit tests

## TASK 3: Create Login API Endpoint (1 hour)
**Priority:** P0 (Blocker)
**Dependencies:** TASK 1, TASK 2

- POST /api/auth/login route
- Validate email/password
- Generate JWT token
- Handle errors (invalid credentials, rate limiting)

## TASK 4: Build Login Form UI (1 hour)
**Priority:** P1 (High)
**Dependencies:** TASK 3

- Create LoginForm component
- Form validation (email format, password requirements)
- Loading states
- Error message display

Expected output:

✅ Task breakdown created
📄 Saved to .specs/login-feature/tasks.md
🚀 Next step: Run /code login-feature

Step 5: Implement Tasks#

Start implementing based on your sprint plan:

/code login-feature

What happens:

  • AI reads task breakdown
  • Selects the next pending task
  • Implements that task
  • Hands off to /test and /review

Sample interaction:

AI: Reading tasks.md for login-feature...
AI: Next pending task is TASK 1: Setup Database Schema
✅ Created migration file: migrations/001_create_users_table.sql
✅ Added email uniqueness constraint
✅ TASK 1 complete
➡️ Next: run /test login-feature
➡️ Then: run /review login-feature

Step 6: Track Progress#

Monitor your implementation status:

/spec-status login-feature

What happens:

  • AI reads completed tasks
  • Shows progress dashboard
  • Identifies blockers or pending items

Sample status output:

# Login Feature - Status Report

## Progress: 75% (3/4 tasks complete)

✅ TASK 1: Setup Database Schema (DONE)
✅ TASK 2: Implement Password Hashing (DONE)
✅ TASK 3: Create Login API Endpoint (DONE)
⏳ TASK 4: Build Login Form UI (IN PROGRESS)

## Blockers: None

## Next Steps:
- Complete TASK 4 (LoginForm UI)
- Run end-to-end tests
- Deploy to staging

Congratulations!#

You've completed your first CafeKit spec workflow. You learned how to:

  • ✅ Initialize a spec with /spec-init
  • ✅ Gather requirements with /spec-requirements
  • ✅ Design architecture with /spec-design
  • ✅ Break down tasks with /spec-tasks
  • ✅ Implement with /code
  • ✅ Validate and review with /test and /review
  • ✅ Track progress with /spec-status

Next Steps#

Questions? Check our FAQ or open an issue on GitHub.

Previous
Installation
Next
Overview