@haposoft/cafekit 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +866 -0
- package/bin/install.js +773 -0
- package/package.json +40 -0
- package/src/antigravity/GEMINI.md +162 -0
- package/src/antigravity/workflows/code.md +16 -0
- package/src/antigravity/workflows/docs-init.md +432 -0
- package/src/antigravity/workflows/docs-update.md +245 -0
- package/src/antigravity/workflows/review.md +15 -0
- package/src/antigravity/workflows/spec-design.md +220 -0
- package/src/antigravity/workflows/spec-init.md +78 -0
- package/src/antigravity/workflows/spec-requirements.md +122 -0
- package/src/antigravity/workflows/spec-status.md +95 -0
- package/src/antigravity/workflows/spec-tasks.md +156 -0
- package/src/antigravity/workflows/spec-validate.md +106 -0
- package/src/antigravity/workflows/test.md +13 -0
- package/src/claude/ROUTING.md +101 -0
- package/src/claude/agents/code-reviewer.md +131 -0
- package/src/claude/agents/debugger.md +137 -0
- package/src/claude/agents/fullstack-developer.md +95 -0
- package/src/claude/agents/tester.md +105 -0
- package/src/claude/commands/code.md +17 -0
- package/src/claude/commands/docs.md +609 -0
- package/src/claude/commands/review/codebase/parallel.md +122 -0
- package/src/claude/commands/review/codebase.md +49 -0
- package/src/claude/commands/review.md +16 -0
- package/src/claude/commands/spec-design.md +247 -0
- package/src/claude/commands/spec-init.md +118 -0
- package/src/claude/commands/spec-requirements.md +138 -0
- package/src/claude/commands/spec-status.md +98 -0
- package/src/claude/commands/spec-tasks.md +173 -0
- package/src/claude/commands/spec-validate.md +118 -0
- package/src/claude/commands/test.md +8 -0
- package/src/claude/migration-manifest.json +39 -0
- package/src/common/skills/specs/SKILL.md +101 -0
- package/src/common/skills/specs/rules/design-discovery-full.md +93 -0
- package/src/common/skills/specs/rules/design-discovery-light.md +49 -0
- package/src/common/skills/specs/rules/design-principles.md +182 -0
- package/src/common/skills/specs/rules/design-review.md +110 -0
- package/src/common/skills/specs/rules/ears-format.md +49 -0
- package/src/common/skills/specs/rules/gap-analysis.md +144 -0
- package/src/common/skills/specs/rules/steering-principles.md +90 -0
- package/src/common/skills/specs/rules/tasks-generation.md +131 -0
- package/src/common/skills/specs/rules/tasks-parallel-analysis.md +34 -0
- package/src/common/skills/specs/templates/design.md +276 -0
- package/src/common/skills/specs/templates/init.json +41 -0
- package/src/common/skills/specs/templates/requirements-init.md +9 -0
- package/src/common/skills/specs/templates/requirements.md +26 -0
- package/src/common/skills/specs/templates/research.md +61 -0
- package/src/common/skills/specs/templates/tasks.md +21 -0
package/README.md
ADDED
|
@@ -0,0 +1,866 @@
|
|
|
1
|
+
# @haposoft/cafekit
|
|
2
|
+
|
|
3
|
+
> Spec-Driven Development workflow for AI coding assistants
|
|
4
|
+
|
|
5
|
+
[](https://github.com/haposoft/cafekit)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://claude.ai/code)
|
|
8
|
+
[](https://github.com/google/antigravity)
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
CafeKit Spec is a **multi-platform** CLI tool that installs a structured workflow for AI coding assistants. It helps teams move from idea to implementation systematically using natural language commands.
|
|
13
|
+
|
|
14
|
+
**Supported Platforms:**
|
|
15
|
+
| Platform | Status | Installation Path |
|
|
16
|
+
|----------|--------|-------------------|
|
|
17
|
+
| [Claude Code](https://claude.ai/code) | ✅ Supported | `.claude/commands/` |
|
|
18
|
+
| [Antigravity](https://antigravity.google/) | ✅ Supported | `.agent/workflows/` |
|
|
19
|
+
| Cursor | 🔮 Planned | `.cursor/commands/` |
|
|
20
|
+
| GitHub Copilot | 🔮 Planned | TBD |
|
|
21
|
+
| Windsurf | 🔮 Planned | TBD |
|
|
22
|
+
|
|
23
|
+
**What it does:**
|
|
24
|
+
- Installs workflow commands into your AI editor command/workflow folder
|
|
25
|
+
- Enables spec-driven development with clear phase separation
|
|
26
|
+
- Creates living documentation for every feature
|
|
27
|
+
- Works with zero configuration
|
|
28
|
+
- **Idempotent by default** - Safe to re-run, skips existing files
|
|
29
|
+
- **Upgrade mode available** - Use `--upgrade` (or `--force`) to refresh managed templates
|
|
30
|
+
|
|
31
|
+
**What it doesn't do:**
|
|
32
|
+
- Generate code (commands guide AI to help you write code)
|
|
33
|
+
- Require configuration (zero-config installation)
|
|
34
|
+
- Lock you to a specific AI editor
|
|
35
|
+
|
|
36
|
+
## Features
|
|
37
|
+
|
|
38
|
+
- **🎯 Multi-platform** - Works with Claude Code, Antigravity, and future AI editors
|
|
39
|
+
- **📋 Spec-first workflow** - `spec-init - spec-requirements - spec-design - spec-tasks` + `code - test - review`
|
|
40
|
+
- **📝 Documentation workflow** - `/docs init` and `/docs update` for project documentation
|
|
41
|
+
- **⚡ Zero-config** - Works out of the box with sensible defaults
|
|
42
|
+
- **🔄 Idempotent** - Safe to re-run, skips existing files
|
|
43
|
+
- **📦 No global install** - Use directly with `npx`
|
|
44
|
+
- **🚀 Future-proof** - Easy to add support for new AI editors
|
|
45
|
+
|
|
46
|
+
## Installation
|
|
47
|
+
|
|
48
|
+
### Prerequisites
|
|
49
|
+
|
|
50
|
+
- Node.js 18+
|
|
51
|
+
- An AI coding assistant (Claude Code or Antigravity)
|
|
52
|
+
|
|
53
|
+
### Install Spec Workflow
|
|
54
|
+
|
|
55
|
+
Run in your project root:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npx @haposoft/cafekit
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The installer will:
|
|
62
|
+
1. **Auto-detect** your AI editor configuration (`.claude/` or `.agent/`)
|
|
63
|
+
2. **Prompt** you to select platform if not detected
|
|
64
|
+
3. **Copy** workflow commands to the appropriate directory
|
|
65
|
+
4. **Install** shared skills for spec-driven development
|
|
66
|
+
5. **Ensure dependencies** for `code - test - review` by installing missing command/agent templates
|
|
67
|
+
|
|
68
|
+
Installer modes:
|
|
69
|
+
- **Default install mode**: `npx @haposoft/cafekit` (skip existing files)
|
|
70
|
+
- **Upgrade mode**: `npx @haposoft/cafekit --upgrade` (overwrite managed templates)
|
|
71
|
+
- **Alias**: `--force` / `-f` behaves the same as `--upgrade`
|
|
72
|
+
|
|
73
|
+
**Example output (Claude Code):**
|
|
74
|
+
```
|
|
75
|
+
CafeKit Spec Installer
|
|
76
|
+
===============================
|
|
77
|
+
|
|
78
|
+
✓ Detected platforms: claude
|
|
79
|
+
|
|
80
|
+
Installing for: .claude/
|
|
81
|
+
------------------------
|
|
82
|
+
[.claude/skills] Installed skill: spec-driven-development
|
|
83
|
+
[.claude/commands] Copied: spec-init.md
|
|
84
|
+
[.claude/commands] Copied: spec-requirements.md
|
|
85
|
+
[.claude/commands] Copied: spec-design.md
|
|
86
|
+
[.claude/commands] Copied: spec-tasks.md
|
|
87
|
+
[.claude/commands] Copied: code.md
|
|
88
|
+
[.claude/commands] Copied: spec-status.md
|
|
89
|
+
|
|
90
|
+
Installation complete!
|
|
91
|
+
Copied Files: 7
|
|
92
|
+
Skipped Files: 0
|
|
93
|
+
Installed Skills: Yes
|
|
94
|
+
Dependency Checks: 6
|
|
95
|
+
Installed Deps: 6
|
|
96
|
+
Missing Deps: 0
|
|
97
|
+
Targets: .claude/commands
|
|
98
|
+
|
|
99
|
+
Next steps:
|
|
100
|
+
1. Run /spec-init <feature-name>
|
|
101
|
+
2. Follow the spec workflow: requirements - design - tasks - code - test - review
|
|
102
|
+
|
|
103
|
+
Documentation: https://github.com/haposoft/cafekit
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Workflows
|
|
107
|
+
|
|
108
|
+
CafeKit Spec provides two workflow categories:
|
|
109
|
+
|
|
110
|
+
### 1. Spec-Driven Development Workflows (`spec-*`)
|
|
111
|
+
|
|
112
|
+
**Purpose:** Structured feature development from idea to implementation
|
|
113
|
+
|
|
114
|
+
**Claude Code Commands:**
|
|
115
|
+
| Command | Purpose | Phase |
|
|
116
|
+
|---------|---------|-------|
|
|
117
|
+
| `/spec-init` | Initialize new feature spec | 1 |
|
|
118
|
+
| `/spec-requirements` | Generate EARS requirements | 2 |
|
|
119
|
+
| `/spec-design` | Create technical design | 3 |
|
|
120
|
+
| `/spec-validate` | Validate design decisions via interview | 4 |
|
|
121
|
+
| `/spec-tasks` | Break down into tasks | 5 |
|
|
122
|
+
| `/code` | Implement tasks from spec artifacts | 6 |
|
|
123
|
+
| `/test` | Run tests for implemented changes | 7 |
|
|
124
|
+
| `/review` | Review code quality and risks | 8 |
|
|
125
|
+
| `/spec-status` | Check progress | 9 |
|
|
126
|
+
|
|
127
|
+
**Antigravity Workflows:**
|
|
128
|
+
| Workflow | Purpose | Phase |
|
|
129
|
+
|----------|---------|-------|
|
|
130
|
+
| `/spec-init` | Initialize new feature spec | 1 |
|
|
131
|
+
| `/spec-requirements` | Generate EARS requirements | 2 |
|
|
132
|
+
| `/spec-design` | Create technical design | 3 |
|
|
133
|
+
| `/spec-validate` | Validate design decisions via interview | 4 |
|
|
134
|
+
| `/spec-tasks` | Break down into tasks | 5 |
|
|
135
|
+
| `/code` | Implement tasks from spec artifacts | 6 |
|
|
136
|
+
| `/test` | Run tests for implemented changes | 7 |
|
|
137
|
+
| `/review` | Review code quality and risks | 8 |
|
|
138
|
+
| `/spec-status` | Check progress | 9 |
|
|
139
|
+
|
|
140
|
+
**Generated Files:**
|
|
141
|
+
```
|
|
142
|
+
.specs/
|
|
143
|
+
└── feature-name/
|
|
144
|
+
├── spec.json
|
|
145
|
+
├── requirements.md
|
|
146
|
+
├── design.md
|
|
147
|
+
└── tasks/
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
### 2. Documentation Workflows (`docs`)
|
|
153
|
+
|
|
154
|
+
**Purpose:** Project documentation management and maintenance
|
|
155
|
+
|
|
156
|
+
**Claude Code Commands:**
|
|
157
|
+
| Command | Purpose |
|
|
158
|
+
|---------|---------|
|
|
159
|
+
| `/docs init` | Initialize comprehensive documentation |
|
|
160
|
+
| `/docs update` | Update docs after code changes |
|
|
161
|
+
|
|
162
|
+
**Antigravity Workflows:**
|
|
163
|
+
| Workflow | Purpose |
|
|
164
|
+
|----------|---------|
|
|
165
|
+
| `/docs-init` | Initialize comprehensive documentation |
|
|
166
|
+
| `/docs-update` | Update docs after code changes |
|
|
167
|
+
|
|
168
|
+
**Generated Files:**
|
|
169
|
+
```
|
|
170
|
+
docs/
|
|
171
|
+
├── codebase-summary.md
|
|
172
|
+
├── project-overview-pdr.md
|
|
173
|
+
├── code-standards.md
|
|
174
|
+
├── system-architecture.md
|
|
175
|
+
├── design-guidelines.md
|
|
176
|
+
├── deployment-guide.md
|
|
177
|
+
└── project-roadmap.md
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Quick Start
|
|
183
|
+
|
|
184
|
+
### A. Spec Workflow - Building User Authentication
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
# Step 1: Initialize spec
|
|
188
|
+
/spec-init User authentication with JWT and refresh tokens
|
|
189
|
+
|
|
190
|
+
# AI creates:
|
|
191
|
+
# - .specs/user-authentication/
|
|
192
|
+
# - .specs/user-authentication/spec.json
|
|
193
|
+
# - .specs/user-authentication/requirements.md
|
|
194
|
+
|
|
195
|
+
# Step 2: Generate requirements
|
|
196
|
+
/spec-requirements user-authentication
|
|
197
|
+
|
|
198
|
+
# AI analyzes codebase and generates:
|
|
199
|
+
# - Functional requirements (EARS format)
|
|
200
|
+
# - Acceptance criteria
|
|
201
|
+
# - Constraints
|
|
202
|
+
|
|
203
|
+
# Step 3: Create design
|
|
204
|
+
/spec-design user-authentication
|
|
205
|
+
|
|
206
|
+
# AI generates:
|
|
207
|
+
# - Architecture decisions
|
|
208
|
+
# - API endpoints
|
|
209
|
+
# - Database schema
|
|
210
|
+
# - Component structure
|
|
211
|
+
|
|
212
|
+
# Step 4: Validate design decisions (recommended for medium/high-risk features)
|
|
213
|
+
/spec-validate user-authentication
|
|
214
|
+
|
|
215
|
+
# AI confirms:
|
|
216
|
+
# - Critical trade-offs and assumptions
|
|
217
|
+
# - Risk-sensitive defaults
|
|
218
|
+
# - Follow-up actions before task generation
|
|
219
|
+
|
|
220
|
+
# Step 5: Break down tasks
|
|
221
|
+
/spec-tasks user-authentication
|
|
222
|
+
|
|
223
|
+
# AI creates:
|
|
224
|
+
# - Prioritized task list
|
|
225
|
+
# - Dependencies
|
|
226
|
+
# - Estimated complexity
|
|
227
|
+
|
|
228
|
+
# Step 6: Code
|
|
229
|
+
/code user-authentication
|
|
230
|
+
|
|
231
|
+
# Step 7: Test
|
|
232
|
+
/test
|
|
233
|
+
|
|
234
|
+
# Step 8: Review
|
|
235
|
+
/review
|
|
236
|
+
|
|
237
|
+
# Step 9: Check status
|
|
238
|
+
/spec-status user-authentication
|
|
239
|
+
|
|
240
|
+
# AI reports:
|
|
241
|
+
# - Progress (5/8 tasks complete)
|
|
242
|
+
# - Blockers
|
|
243
|
+
# - Next steps
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
## Workflow Overview
|
|
247
|
+
|
|
248
|
+
### Workflow Diagram
|
|
249
|
+
|
|
250
|
+
```
|
|
251
|
+
Idea - /spec-init - /spec-requirements - /spec-design - /spec-validate - /spec-tasks - /code - /test - /review - /spec-status
|
|
252
|
+
|<----------------------------------------------|-----------------------------|
|
|
253
|
+
|
|
|
254
|
+
iterate
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
### 1. /spec-init
|
|
258
|
+
|
|
259
|
+
**Purpose:** Initialize a new specification from a project description.
|
|
260
|
+
|
|
261
|
+
**When to use:** Starting a new feature, enhancement, or component.
|
|
262
|
+
|
|
263
|
+
**What it does:**
|
|
264
|
+
- Generates feature name from description
|
|
265
|
+
- Creates `.specs/[feature-name]/` directory
|
|
266
|
+
- Initializes `spec.json` metadata
|
|
267
|
+
- Creates `requirements.md` template
|
|
268
|
+
|
|
269
|
+
**Example:**
|
|
270
|
+
```bash
|
|
271
|
+
/spec-init Dark mode toggle with user preference persistence
|
|
272
|
+
|
|
273
|
+
# Creates:
|
|
274
|
+
# .specs/dark-mode-toggle/
|
|
275
|
+
# ├── spec.json
|
|
276
|
+
# └── requirements.md (with initial description)
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
**Tips:**
|
|
280
|
+
- Be specific (5+ words describing what to build)
|
|
281
|
+
- Avoid vague terms like "improve" or "better" without context
|
|
282
|
+
- Include key nouns (e.g., "login form", "dashboard chart")
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
### 2. /spec-requirements
|
|
287
|
+
|
|
288
|
+
**Purpose:** Generate comprehensive requirements in EARS format.
|
|
289
|
+
|
|
290
|
+
**When to use:** After initialization, before design phase.
|
|
291
|
+
|
|
292
|
+
**What it does:**
|
|
293
|
+
- Analyzes existing codebase for related code
|
|
294
|
+
- Loads project steering context (`.specs/steering/`)
|
|
295
|
+
- Generates functional requirements with acceptance criteria
|
|
296
|
+
- Documents constraints and assumptions
|
|
297
|
+
|
|
298
|
+
**Example:**
|
|
299
|
+
```bash
|
|
300
|
+
/spec-requirements dark-mode-toggle
|
|
301
|
+
|
|
302
|
+
# Updates requirements.md with:
|
|
303
|
+
# - Functional Requirements (EARS format)
|
|
304
|
+
# - "When user clicks toggle, system shall switch theme"
|
|
305
|
+
# - "When theme changes, system shall persist preference"
|
|
306
|
+
# - Acceptance Criteria
|
|
307
|
+
# - Constraints (browser support, accessibility)
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
**EARS format example:**
|
|
311
|
+
```markdown
|
|
312
|
+
## Functional Requirements
|
|
313
|
+
|
|
314
|
+
### FR-1: Theme Toggle
|
|
315
|
+
When user clicks the theme toggle button,
|
|
316
|
+
the system shall switch between light and dark themes
|
|
317
|
+
and update UI within 200ms.
|
|
318
|
+
|
|
319
|
+
**Acceptance Criteria:**
|
|
320
|
+
- Toggle state reflects current theme
|
|
321
|
+
- Animation is smooth (no flash)
|
|
322
|
+
- All components respect theme
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
### 3. /spec-design
|
|
328
|
+
|
|
329
|
+
**Purpose:** Create detailed technical design from requirements.
|
|
330
|
+
|
|
331
|
+
**When to use:** After requirements are finalized, before task breakdown.
|
|
332
|
+
|
|
333
|
+
**What it does:**
|
|
334
|
+
- Generates architecture decisions
|
|
335
|
+
- Defines API contracts (if needed)
|
|
336
|
+
- Creates database schema (if needed)
|
|
337
|
+
- Specifies component structure
|
|
338
|
+
- Documents technology choices
|
|
339
|
+
|
|
340
|
+
**Example:**
|
|
341
|
+
```bash
|
|
342
|
+
/spec-design dark-mode-toggle
|
|
343
|
+
|
|
344
|
+
# Creates design.md with:
|
|
345
|
+
# - Architecture: Context API for theme state
|
|
346
|
+
# - Components: ThemeToggle.tsx, ThemeProvider.tsx
|
|
347
|
+
# - Storage: localStorage with 'theme' key
|
|
348
|
+
# - CSS: Tailwind dark: variants
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
**Output structure:**
|
|
352
|
+
```markdown
|
|
353
|
+
# Design Specification
|
|
354
|
+
|
|
355
|
+
## Architecture Decisions
|
|
356
|
+
- Use React Context for global theme state
|
|
357
|
+
- Tailwind CSS dark mode (class strategy)
|
|
358
|
+
|
|
359
|
+
## Component Structure
|
|
360
|
+
- ThemeProvider (context wrapper)
|
|
361
|
+
- ThemeToggle (button component)
|
|
362
|
+
- useTheme hook (consume context)
|
|
363
|
+
|
|
364
|
+
## Data Flow
|
|
365
|
+
User clicks -> dispatch action -> update context -> localStorage -> re-render
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
### 4. /spec-validate
|
|
371
|
+
|
|
372
|
+
**Purpose:** Validate design assumptions, trade-offs, and risk-sensitive decisions before task generation.
|
|
373
|
+
|
|
374
|
+
**When to use:** After `/spec-design`, especially for medium/high-risk features or external integrations.
|
|
375
|
+
|
|
376
|
+
**What it does:**
|
|
377
|
+
- Interviews critical decision points using structured questions
|
|
378
|
+
- Appends validation log to `research.md`
|
|
379
|
+
- Updates validation metadata in `spec.json`
|
|
380
|
+
- Recommends follow-up actions before task breakdown
|
|
381
|
+
|
|
382
|
+
**Example:**
|
|
383
|
+
```bash
|
|
384
|
+
/spec-validate dark-mode-toggle
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
---
|
|
388
|
+
|
|
389
|
+
### 5. /spec-tasks
|
|
390
|
+
|
|
391
|
+
**Purpose:** Break design into implementable tasks.
|
|
392
|
+
|
|
393
|
+
**When to use:** After design is approved, before implementation.
|
|
394
|
+
|
|
395
|
+
**What it does:**
|
|
396
|
+
- Generates prioritized task list
|
|
397
|
+
- Identifies dependencies between tasks
|
|
398
|
+
- Estimates complexity (simple/medium/complex)
|
|
399
|
+
- Creates execution order
|
|
400
|
+
|
|
401
|
+
**Example:**
|
|
402
|
+
```bash
|
|
403
|
+
/spec-tasks dark-mode-toggle
|
|
404
|
+
|
|
405
|
+
# Creates tasks.md with:
|
|
406
|
+
# Task #1: Create ThemeContext and Provider (simple)
|
|
407
|
+
# Task #2: Build ThemeToggle button component (simple)
|
|
408
|
+
# Task #3: Implement localStorage persistence (medium)
|
|
409
|
+
# Task #4: Add dark mode CSS variables (medium)
|
|
410
|
+
# Task #5: Test theme switching across pages (medium)
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
**Task format:**
|
|
414
|
+
```markdown
|
|
415
|
+
## Task #1: Create ThemeContext
|
|
416
|
+
- **Priority:** High
|
|
417
|
+
- **Complexity:** Simple
|
|
418
|
+
- **Dependencies:** None
|
|
419
|
+
- **Files:** src/context/ThemeContext.tsx
|
|
420
|
+
- **Description:** Set up React Context with theme state
|
|
421
|
+
- **Status:** pending
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
### 5. /code
|
|
427
|
+
|
|
428
|
+
**Purpose:** Implement a specific task from the task list.
|
|
429
|
+
|
|
430
|
+
**When to use:** After `/spec-tasks`, to implement approved tasks from spec artifacts.
|
|
431
|
+
|
|
432
|
+
**What it does:**
|
|
433
|
+
- Reads spec artifacts (`tasks.md`, `design.md`, `requirements.md`)
|
|
434
|
+
- Implements approved work with minimal scope
|
|
435
|
+
- Hands off to `/test` and `/review`
|
|
436
|
+
- Reports blockers and next actions
|
|
437
|
+
|
|
438
|
+
**Example:**
|
|
439
|
+
```bash
|
|
440
|
+
# Implement from approved spec tasks
|
|
441
|
+
/code dark-mode-toggle
|
|
442
|
+
|
|
443
|
+
# Then run quality gates
|
|
444
|
+
/test
|
|
445
|
+
/review
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
**Iteration pattern:**
|
|
449
|
+
```bash
|
|
450
|
+
# Repeat the quality loop after each coding pass
|
|
451
|
+
/code dark-mode-toggle
|
|
452
|
+
/test
|
|
453
|
+
/review
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
---
|
|
457
|
+
|
|
458
|
+
### 6. /test
|
|
459
|
+
|
|
460
|
+
**Purpose:** Run tests after `/code`.
|
|
461
|
+
|
|
462
|
+
**When to use:** Immediately after each coding pass.
|
|
463
|
+
|
|
464
|
+
**Example:**
|
|
465
|
+
```bash
|
|
466
|
+
/test
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
### 7. /review
|
|
472
|
+
|
|
473
|
+
**Purpose:** Review recent changes for quality and risk.
|
|
474
|
+
|
|
475
|
+
**When to use:** After `/test` passes.
|
|
476
|
+
|
|
477
|
+
**Example:**
|
|
478
|
+
```bash
|
|
479
|
+
/review
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
### 8. /spec-status
|
|
485
|
+
|
|
486
|
+
**Purpose:** Check progress and next steps.
|
|
487
|
+
|
|
488
|
+
**When to use:** Anytime during or after implementation.
|
|
489
|
+
|
|
490
|
+
**What it does:**
|
|
491
|
+
- Reads `tasks.md` for completion status
|
|
492
|
+
- Calculates progress percentage
|
|
493
|
+
- Identifies blockers or pending tasks
|
|
494
|
+
- Suggests next actions
|
|
495
|
+
|
|
496
|
+
**Example:**
|
|
497
|
+
```bash
|
|
498
|
+
/spec-status dark-mode-toggle
|
|
499
|
+
|
|
500
|
+
# Output:
|
|
501
|
+
# Progress: 3/5 tasks completed (60%)
|
|
502
|
+
# Completed: #1, #2, #3
|
|
503
|
+
# Pending: #4, #5
|
|
504
|
+
# Next: Implement Task #4 (Add dark mode CSS variables)
|
|
505
|
+
# Blockers: None
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
**Status indicators:**
|
|
509
|
+
- `pending` - Not started
|
|
510
|
+
- `in-progress` - Partially implemented
|
|
511
|
+
- `completed` - Finished
|
|
512
|
+
- `blocked` - Waiting on dependency
|
|
513
|
+
|
|
514
|
+
---
|
|
515
|
+
|
|
516
|
+
### B. Docs Workflow - Initialize Project Documentation
|
|
517
|
+
|
|
518
|
+
**Claude Code:**
|
|
519
|
+
```bash
|
|
520
|
+
# Initialize documentation
|
|
521
|
+
/docs init
|
|
522
|
+
|
|
523
|
+
# AI creates:
|
|
524
|
+
# - docs/codebase-summary.md
|
|
525
|
+
# - docs/project-overview-pdr.md
|
|
526
|
+
# - docs/code-standards.md
|
|
527
|
+
# - docs/system-architecture.md
|
|
528
|
+
# - docs/design-guidelines.md
|
|
529
|
+
# - docs/deployment-guide.md
|
|
530
|
+
# - docs/project-roadmap.md
|
|
531
|
+
# - .agent/rules/AGENTS.md (for Antigravity) or CLAUDE.md (for Claude Code)
|
|
532
|
+
|
|
533
|
+
# Update after code changes
|
|
534
|
+
/docs update
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
**Antigravity:**
|
|
538
|
+
```bash
|
|
539
|
+
# Initialize documentation
|
|
540
|
+
/docs-init
|
|
541
|
+
|
|
542
|
+
# AI creates the same 7 docs files + AGENTS.md
|
|
543
|
+
|
|
544
|
+
# Update after code changes
|
|
545
|
+
/docs-update
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
---
|
|
549
|
+
|
|
550
|
+
## File Structure
|
|
551
|
+
|
|
552
|
+
### Platform-Specific Installation
|
|
553
|
+
|
|
554
|
+
**Claude Code** (`.claude/`):
|
|
555
|
+
```
|
|
556
|
+
.claude/
|
|
557
|
+
├── commands/
|
|
558
|
+
│ ├── spec-init.md # Spec workflows
|
|
559
|
+
│ ├── spec-requirements.md
|
|
560
|
+
│ ├── spec-design.md
|
|
561
|
+
│ ├── spec-tasks.md
|
|
562
|
+
│ ├── code.md
|
|
563
|
+
│ ├── test.md
|
|
564
|
+
│ ├── review.md
|
|
565
|
+
│ ├── spec-status.md
|
|
566
|
+
│ └── docs.md # Docs workflows
|
|
567
|
+
└── skills/
|
|
568
|
+
└── spec-driven-development/
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
**Antigravity** (`.agent/`):
|
|
572
|
+
```
|
|
573
|
+
.agent/
|
|
574
|
+
├── workflows/ # Antigravity workflows (hyphen naming)
|
|
575
|
+
│ ├── spec-init.md
|
|
576
|
+
│ ├── spec-requirements.md
|
|
577
|
+
│ ├── spec-design.md
|
|
578
|
+
│ ├── spec-tasks.md
|
|
579
|
+
│ ├── code.md
|
|
580
|
+
│ ├── test.md
|
|
581
|
+
│ ├── review.md
|
|
582
|
+
│ ├── spec-status.md
|
|
583
|
+
│ ├── docs-init.md # Docs workflows
|
|
584
|
+
│ └── docs-update.md
|
|
585
|
+
├── skills/
|
|
586
|
+
│ └── spec-driven-development/
|
|
587
|
+
└── rules/
|
|
588
|
+
└── GEMINI.md # System rules (always_on)
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
**Command Naming:**
|
|
592
|
+
- **Claude Code:** Uses hyphens (`/spec-init`, `/docs init`)
|
|
593
|
+
- **Antigravity:** Uses hyphens (`/spec-init`, `/docs-init`)
|
|
594
|
+
|
|
595
|
+
### Generated Specs Directory
|
|
596
|
+
|
|
597
|
+
Specs are created in `.specs/` (shared across all platforms):
|
|
598
|
+
```
|
|
599
|
+
.specs/
|
|
600
|
+
├── steering/ # Project-wide conventions
|
|
601
|
+
│ ├── tech.md
|
|
602
|
+
│ ├── structure.md
|
|
603
|
+
│ └── product.md
|
|
604
|
+
└── feature-name/ # Individual feature specs
|
|
605
|
+
├── spec.json
|
|
606
|
+
├── requirements.md
|
|
607
|
+
├── design.md
|
|
608
|
+
├── research.md
|
|
609
|
+
└── tasks/
|
|
610
|
+
└── sprint-1.md
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
---
|
|
614
|
+
|
|
615
|
+
## FAQ
|
|
616
|
+
|
|
617
|
+
### Q: Which AI editors are supported?
|
|
618
|
+
|
|
619
|
+
A: Currently supports:
|
|
620
|
+
- ✅ **Claude Code** - `.claude/commands/`
|
|
621
|
+
- ✅ **Antigravity** - `.agent/workflows/`
|
|
622
|
+
|
|
623
|
+
Planned for future:
|
|
624
|
+
- 🔮 **Cursor** - `.cursor/commands/`
|
|
625
|
+
- 🔮 **GitHub Copilot** - TBD
|
|
626
|
+
- 🔮 **Windsurf** - TBD
|
|
627
|
+
|
|
628
|
+
### Q: Can I use multiple AI editors on the same project?
|
|
629
|
+
|
|
630
|
+
A: Yes! You can install CafeKit Spec for multiple platforms:
|
|
631
|
+
```bash
|
|
632
|
+
npx @haposoft/cafekit
|
|
633
|
+
# Select "Both" when prompted
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
This installs commands to both `.claude/` and `.agent/`. The `.specs/` directory is shared, so your specifications work across all editors.
|
|
637
|
+
|
|
638
|
+
### Q: Can I customize the workflow steps?
|
|
639
|
+
|
|
640
|
+
A: Yes. Edit the `.md` files in `.claude/commands/` (Claude Code) or `.agent/workflows/` (Antigravity) after installation.
|
|
641
|
+
|
|
642
|
+
### Q: Is it safe to re-run `npx @haposoft/cafekit`?
|
|
643
|
+
|
|
644
|
+
A: Yes. Default mode is idempotent and skips existing files.
|
|
645
|
+
|
|
646
|
+
### Q: How do I update existing installed templates to the latest version?
|
|
647
|
+
|
|
648
|
+
A: Run installer in upgrade mode:
|
|
649
|
+
```bash
|
|
650
|
+
npx @haposoft/cafekit --upgrade
|
|
651
|
+
# or
|
|
652
|
+
npx @haposoft/cafekit --force
|
|
653
|
+
```
|
|
654
|
+
This overwrites files managed by the installer (commands/workflows, managed dependencies, and routing/rules templates).
|
|
655
|
+
|
|
656
|
+
### Q: What language is the spec generated in?
|
|
657
|
+
|
|
658
|
+
A: Defaults to English.
|
|
659
|
+
|
|
660
|
+
### Q: Can I use this for multiple features simultaneously?
|
|
661
|
+
|
|
662
|
+
A: Yes. Each spec has its own directory in `.specs/`. Work on multiple in parallel.
|
|
663
|
+
|
|
664
|
+
### Q: Why are the command names different between Claude Code and Antigravity?
|
|
665
|
+
|
|
666
|
+
A: Each platform has different conventions:
|
|
667
|
+
- **Claude Code** uses hyphens: `/spec-init`, `/docs update`
|
|
668
|
+
- **Antigravity** uses hyphens: `/spec-init`, `/docs-init`
|
|
669
|
+
|
|
670
|
+
The functionality is identical, only the naming convention differs.
|
|
671
|
+
|
|
672
|
+
---
|
|
673
|
+
|
|
674
|
+
## Troubleshooting
|
|
675
|
+
|
|
676
|
+
### "No platform configuration detected"
|
|
677
|
+
|
|
678
|
+
**Cause:** Neither `.claude/` nor `.agent/` folder exists in your project.
|
|
679
|
+
|
|
680
|
+
**Solution:**
|
|
681
|
+
```bash
|
|
682
|
+
# Option 1: Create Claude Code folder
|
|
683
|
+
mkdir -p .claude/commands
|
|
684
|
+
|
|
685
|
+
# Option 2: Create Antigravity folder
|
|
686
|
+
mkdir -p .agent/workflows
|
|
687
|
+
|
|
688
|
+
# Option 3: Run installer and it will prompt you to select platform
|
|
689
|
+
npx @haposoft/cafekit
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
### "Command not found" after installation
|
|
693
|
+
|
|
694
|
+
**Claude Code:**
|
|
695
|
+
- Commands load automatically
|
|
696
|
+
- If not visible, restart Claude Code extension
|
|
697
|
+
- Verify: `ls .claude/commands/spec-*.md`
|
|
698
|
+
|
|
699
|
+
**Antigravity:**
|
|
700
|
+
- Workflows load automatically when IDE opens the project
|
|
701
|
+
- Verify: `ls .agent/workflows/*.md`
|
|
702
|
+
- Check `GEMINI.md` is in `.agent/rules/` for system rules
|
|
703
|
+
|
|
704
|
+
---
|
|
705
|
+
|
|
706
|
+
## Best Practices
|
|
707
|
+
|
|
708
|
+
### 1. Phase Separation
|
|
709
|
+
|
|
710
|
+
Complete each phase before moving to the next:
|
|
711
|
+
- Don't skip requirements (even for "simple" features)
|
|
712
|
+
- Finalize design before creating tasks
|
|
713
|
+
- Implement tasks sequentially (respect dependencies)
|
|
714
|
+
|
|
715
|
+
### 2. Incremental Implementation
|
|
716
|
+
|
|
717
|
+
Break large features into smaller specs:
|
|
718
|
+
```bash
|
|
719
|
+
# Instead of:
|
|
720
|
+
/spec-init Complete e-commerce system
|
|
721
|
+
|
|
722
|
+
# Do:
|
|
723
|
+
/spec-init Product listing page
|
|
724
|
+
/spec-init Shopping cart functionality
|
|
725
|
+
/spec-init Checkout flow
|
|
726
|
+
```
|
|
727
|
+
|
|
728
|
+
### 3. Steering Context
|
|
729
|
+
|
|
730
|
+
For projects with shared conventions:
|
|
731
|
+
1. Create `.specs/steering/` directory
|
|
732
|
+
2. Add files like `tech.md`, `structure.md`, `product.md`
|
|
733
|
+
3. All specs will automatically reference these
|
|
734
|
+
|
|
735
|
+
Example `.specs/steering/tech.md`:
|
|
736
|
+
```markdown
|
|
737
|
+
# Technology Standards
|
|
738
|
+
|
|
739
|
+
- Frontend: React 18 + TypeScript
|
|
740
|
+
- Styling: Tailwind CSS v4
|
|
741
|
+
- State: Zustand
|
|
742
|
+
- Testing: Vitest + Playwright
|
|
743
|
+
```
|
|
744
|
+
|
|
745
|
+
### 4. Version Control
|
|
746
|
+
|
|
747
|
+
Commit after each phase:
|
|
748
|
+
```bash
|
|
749
|
+
/spec-init feature-name
|
|
750
|
+
git add .specs/feature-name/
|
|
751
|
+
git commit -m "spec: init feature-name"
|
|
752
|
+
|
|
753
|
+
/spec-requirements feature-name
|
|
754
|
+
git add .specs/feature-name/requirements.md
|
|
755
|
+
git commit -m "spec: requirements for feature-name"
|
|
756
|
+
|
|
757
|
+
# ... continue for design, tasks, impl
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
### 5. Task Granularity
|
|
761
|
+
|
|
762
|
+
Good task size: 30-60 minutes of work.
|
|
763
|
+
|
|
764
|
+
Too large:
|
|
765
|
+
```markdown
|
|
766
|
+
Task #1: Build entire authentication system
|
|
767
|
+
```
|
|
768
|
+
|
|
769
|
+
Better:
|
|
770
|
+
```markdown
|
|
771
|
+
Task #1: Create User model and migration
|
|
772
|
+
Task #2: Implement JWT generation
|
|
773
|
+
Task #3: Add login endpoint
|
|
774
|
+
Task #4: Add protected route middleware
|
|
775
|
+
```
|
|
776
|
+
|
|
777
|
+
---
|
|
778
|
+
|
|
779
|
+
## Contributing
|
|
780
|
+
|
|
781
|
+
- **Report issues:** https://github.com/haposoft/cafekit/issues
|
|
782
|
+
- **Suggest improvements:** Open a GitHub Discussion
|
|
783
|
+
|
|
784
|
+
---
|
|
785
|
+
|
|
786
|
+
## Support
|
|
787
|
+
|
|
788
|
+
- **GitHub:** https://github.com/haposoft/cafekit
|
|
789
|
+
- **Issues:** https://github.com/haposoft/cafekit/issues
|
|
790
|
+
- **Discussions:** https://github.com/haposoft/cafekit/discussions
|
|
791
|
+
|
|
792
|
+
---
|
|
793
|
+
|
|
794
|
+
## Changelog
|
|
795
|
+
|
|
796
|
+
### [0.2.2] - 2026-02-25
|
|
797
|
+
|
|
798
|
+
#### Changed
|
|
799
|
+
- Added `scope_lock` contract to spec initialization metadata (`source`, `in_scope`, `out_of_scope`, `expansion_policy`)
|
|
800
|
+
- Updated `/spec-requirements`, `/spec-design`, `/spec-validate`, and `/spec-tasks` to enforce scope lock across the full spec lifecycle
|
|
801
|
+
- Reduced default expansion in `/spec-design`: uncertain cases now default to light discovery and only escalate to full on explicit triggers
|
|
802
|
+
- Clarified steering usage in requirements phase: steering is constraints-only and must not introduce new capability domains
|
|
803
|
+
- Added task-generation guardrail: every task must map to valid in-scope numeric requirement IDs
|
|
804
|
+
- Added installer sync for specs template files in Claude mode to reduce stale runtime copy drift
|
|
805
|
+
|
|
806
|
+
#### Regression Guard (installer CLI upgrade mode)
|
|
807
|
+
Use this checklist after running `npx @haposoft/cafekit --upgrade`:
|
|
808
|
+
- Run `/spec-init` with an installer-CLI-scoped feature description and verify `spec.json.scope_lock` is populated
|
|
809
|
+
- Run `/spec-requirements`, `/spec-design`, `/spec-validate`, `/spec-tasks` in order
|
|
810
|
+
- Verify requirements/design/tasks do **not** introduce API/mobile/DynamoDB domains unless explicitly approved
|
|
811
|
+
- Verify task entries reference valid in-scope numeric requirement IDs only
|
|
812
|
+
- If scope expansion is explicitly approved during validation, verify `scope_lock` updates are reflected in `spec.json`
|
|
813
|
+
|
|
814
|
+
### [0.1.7] - 2026-02-24
|
|
815
|
+
|
|
816
|
+
#### Changed
|
|
817
|
+
- Unified workflow naming around hyphens for Antigravity workflows
|
|
818
|
+
- Replaced `spec-impl` in primary flow with `code - test - review`
|
|
819
|
+
- Installer now ensures dependency templates for `code/test/review` commands and required agents
|
|
820
|
+
- Updated docs workflow naming to `/docs-init` and `/docs-update` for Antigravity
|
|
821
|
+
|
|
822
|
+
### [0.1.5] - 2026-02-11
|
|
823
|
+
|
|
824
|
+
#### Added
|
|
825
|
+
- **Documentation workflow for Antigravity** - New `/docs-init` and `/docs-update` workflows
|
|
826
|
+
- **GEMINI.md rule file** - Auto-installs `.agent/rules/GEMINI.md` with system rules for Antigravity
|
|
827
|
+
- **Full Antigravity support** - Documentation commands now work on both Claude Code and Antigravity
|
|
828
|
+
- **AGENTS.md auto-generation** - Created automatically when running `/docs-init` or `/docs-update`
|
|
829
|
+
|
|
830
|
+
### [0.1.2] - 2026-02-04
|
|
831
|
+
|
|
832
|
+
#### Changed
|
|
833
|
+
- **Multi-platform support** - Renamed from "Claude Code only" to "AI coding assistants"
|
|
834
|
+
- Updated documentation to reflect dual-platform support (Claude Code + Antigravity)
|
|
835
|
+
- Improved platform detection and installation UX
|
|
836
|
+
- Added platform compatibility matrix
|
|
837
|
+
|
|
838
|
+
### [0.1.1] - 2026-02-03
|
|
839
|
+
|
|
840
|
+
#### Added
|
|
841
|
+
- Dual-platform installer supporting both Claude Code and Antigravity
|
|
842
|
+
- Auto-detection of existing `.claude/` and `.agent/` configurations
|
|
843
|
+
- Interactive platform selection when no configuration detected
|
|
844
|
+
|
|
845
|
+
### [0.1.0] - 2026-02-02
|
|
846
|
+
|
|
847
|
+
#### Added
|
|
848
|
+
- Initial release of CafeKit Spec workflow
|
|
849
|
+
- Initial spec workflow foundation
|
|
850
|
+
- Zero-config installation via npx
|
|
851
|
+
- Idempotent file copying (safe to re-run)
|
|
852
|
+
- Comprehensive documentation
|
|
853
|
+
|
|
854
|
+
---
|
|
855
|
+
|
|
856
|
+
## License
|
|
857
|
+
|
|
858
|
+
MIT License - See [LICENSE](LICENSE) for details
|
|
859
|
+
|
|
860
|
+
---
|
|
861
|
+
|
|
862
|
+
**Made with care by the CafeKit Team**
|
|
863
|
+
|
|
864
|
+
<p align="center">
|
|
865
|
+
<sub>Multi-platform Spec-Driven Development for AI Coding Assistants</sub>
|
|
866
|
+
</p>
|