What is CafeKit Spec?#

CafeKit Spec is a spec-driven development workflow for AI coding assistants.

Command chain by platform:

• Claude Code: /spec-init, /spec-requirements, /spec-design, /spec-tasks, /code, /test, /review, /spec-status
• Antigravity: /spec-init (or @spec-init), /spec-requirements, /spec-design, /spec-tasks, /code, /test, /review, /spec-status

What is spec-driven development?#

Spec-driven development is a methodology where you:

1. Plan before coding - Define requirements and design upfront
2. Document decisions - Create specifications that serve as documentation
3. Break down work - Divide features into manageable, trackable tasks
4. Implement systematically - Build with clear guidance and verification

When should I use CafeKit Spec?#

Use CafeKit Spec for:

• Complex features (authentication, payments, admin dashboards)
• Multi-file changes that need coordination
• Features requiring architectural decisions
• Long-running work across multiple sessions
• Team projects needing shared context

Skip it for:

• Simple bug fixes (< 30 minutes)
• Copy changes or typo fixes
• Minor CSS adjustments
• One-line changes

How does it compare to regular AI coding?#

Result: Fewer bugs, better documentation, more consistent results.

Installation & Setup#

How do I install CafeKit Spec?#

npx @haposoft/cafekit-spec

This installs the spec workflow command set to your selected platform.

What are the prerequisites?#

• Node.js 18+
• AI coding assistant (Claude Code or Antigravity)
• Git (for version control)

Can I use CafeKit Spec with other AI assistants?#

CafeKit Spec supports multiple AI coding assistant platforms:

The installer automatically detects and configures for your platform.

Where are the spec files stored?#

Specs are stored in .specs/ directory in your project root:

.specs/
└── feature-name/
    ├── spec.json
    ├── requirements.md
    ├── design.md
    └── tasks.md

Using Spec Commands#

How do I start a new spec?#

Claude Code:

/spec-init my-feature-name

Antigravity:

/spec-init my-feature-name
# or @spec-init my-feature-name

This creates a .specs/my-feature-name/ directory with initial structure.

What happens in each phase?#

Can I skip phases?#

While possible, it's not recommended. Each phase builds on the previous:

• Design without requirements misses edge cases
• Tasks without design lack technical clarity
• Implementation without tasks is disorganized

How long does a spec take?#

• Simple feature (CRUD, form): 1-2 hours
• Medium feature (auth, API): 3-5 hours
• Complex feature (payments, real-time): 6+ hours

Time includes requirements, design, tasks, implementation, test, and review.

Can I work on multiple specs at once?#

Yes. Each spec is independent in its own .specs/feature-name/ directory. Switch between them by specifying the spec name:

/spec-status feature-a
/spec-status feature-b

Troubleshooting#

Command not found#

Problem: Spec commands don't work

Solutions:

1. Check files exist in the correct folder:
   • Claude Code: .claude/commands/
   • Antigravity: .agent/workflows/
2. Restart your AI coding assistant
3. Re-run installer: npx @haposoft/cafekit-spec
4. Verify you selected the correct platform during installation

Spec directory not created#

Problem: /spec-init runs but no .specs/ folder

Solution:

• Check you have write permissions in project root
• Ensure you're in the correct project directory
• Try creating .specs/ manually first

AI doesn't understand my feature#

Problem: Requirements or design are off-target

Solutions:

1. Be more specific in /spec-init description
2. Clarify during /spec-requirements Q&A
3. Edit generated files manually if needed
4. Re-run the phase with more context

Tasks are too big/too small#

Problem: Task breakdown doesn't fit your workflow

Solution:

• Edit .specs/[feature-name]/tasks.md manually
• Re-run /spec-tasks with different instructions
• Split or combine tasks as needed

Best Practices#

Should I commit specs to Git?#

Yes. Commit specs to share context with your team:

git add .specs/my-feature/
git commit -m "spec: add user authentication spec"

Specs serve as living documentation.

How do I handle changing requirements?#

1. Re-run /spec-requirements with new context
2. Re-run /spec-design to update architecture
3. Re-run /spec-tasks for new task breakdown
4. Continue implementation

Specs are iterative - update them as needs change.

What makes a good spec name?#

Use kebab-case, descriptive names:

✅ Good:

• user-authentication
• payment-gateway-integration
• dark-mode-toggle

❌ Avoid:

• feature-1
• new-stuff
• fix-bug

Advanced Questions#

Can I use the same spec across different platforms?#

Yes. Specs created with CafeKit are platform-agnostic. The .specs/ directory and its contents work identically whether you're using Claude Code or Antigravity. You can:

• Start a spec in Claude Code and continue in Antigravity
• Share specs between team members using different platforms
• Migrate between platforms without losing spec data

Can I customize the workflow?#

Yes. After installation, edit the .md files in your platform's commands folder:

Claude Code:

.claude/commands/
├── spec-init.md          # Customize init process
├── spec-requirements.md  # Change question style
└── ...

Antigravity:

.agent/workflows/
├── spec-init.md          # Customize init process
├── spec-requirements.md  # Change question style
└── ...

Changes take effect immediately.

How do I archive completed specs?#

Move specs to .specs/archive/ when done:

mv .specs/completed-feature .specs/archive/

This keeps your workspace clean while preserving documentation.

Can I use spec templates?#

Yes. Create steering context in .specs/steering/:

.specs/steering/
├── tech.md       # Technology standards
├── structure.md  # Project conventions
└── product.md    # Product context

All new specs will reference these files.

What if I get stuck during implementation?#

1. Run /spec-status to see current state
2. Review design.md for guidance
3. Check .specs/[feature-name]/tasks.md for current task details
4. Ask Claude Code specific questions about the task

Still Have Questions?#

• Browse GitHub Issues - See if others had similar questions
• Open a new issue - We're happy to help
• Check the Spec Workflow Guide - Detailed walkthrough

Happy spec-driven coding! ☕✨