@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.
Files changed (49) hide show
  1. package/README.md +866 -0
  2. package/bin/install.js +773 -0
  3. package/package.json +40 -0
  4. package/src/antigravity/GEMINI.md +162 -0
  5. package/src/antigravity/workflows/code.md +16 -0
  6. package/src/antigravity/workflows/docs-init.md +432 -0
  7. package/src/antigravity/workflows/docs-update.md +245 -0
  8. package/src/antigravity/workflows/review.md +15 -0
  9. package/src/antigravity/workflows/spec-design.md +220 -0
  10. package/src/antigravity/workflows/spec-init.md +78 -0
  11. package/src/antigravity/workflows/spec-requirements.md +122 -0
  12. package/src/antigravity/workflows/spec-status.md +95 -0
  13. package/src/antigravity/workflows/spec-tasks.md +156 -0
  14. package/src/antigravity/workflows/spec-validate.md +106 -0
  15. package/src/antigravity/workflows/test.md +13 -0
  16. package/src/claude/ROUTING.md +101 -0
  17. package/src/claude/agents/code-reviewer.md +131 -0
  18. package/src/claude/agents/debugger.md +137 -0
  19. package/src/claude/agents/fullstack-developer.md +95 -0
  20. package/src/claude/agents/tester.md +105 -0
  21. package/src/claude/commands/code.md +17 -0
  22. package/src/claude/commands/docs.md +609 -0
  23. package/src/claude/commands/review/codebase/parallel.md +122 -0
  24. package/src/claude/commands/review/codebase.md +49 -0
  25. package/src/claude/commands/review.md +16 -0
  26. package/src/claude/commands/spec-design.md +247 -0
  27. package/src/claude/commands/spec-init.md +118 -0
  28. package/src/claude/commands/spec-requirements.md +138 -0
  29. package/src/claude/commands/spec-status.md +98 -0
  30. package/src/claude/commands/spec-tasks.md +173 -0
  31. package/src/claude/commands/spec-validate.md +118 -0
  32. package/src/claude/commands/test.md +8 -0
  33. package/src/claude/migration-manifest.json +39 -0
  34. package/src/common/skills/specs/SKILL.md +101 -0
  35. package/src/common/skills/specs/rules/design-discovery-full.md +93 -0
  36. package/src/common/skills/specs/rules/design-discovery-light.md +49 -0
  37. package/src/common/skills/specs/rules/design-principles.md +182 -0
  38. package/src/common/skills/specs/rules/design-review.md +110 -0
  39. package/src/common/skills/specs/rules/ears-format.md +49 -0
  40. package/src/common/skills/specs/rules/gap-analysis.md +144 -0
  41. package/src/common/skills/specs/rules/steering-principles.md +90 -0
  42. package/src/common/skills/specs/rules/tasks-generation.md +131 -0
  43. package/src/common/skills/specs/rules/tasks-parallel-analysis.md +34 -0
  44. package/src/common/skills/specs/templates/design.md +276 -0
  45. package/src/common/skills/specs/templates/init.json +41 -0
  46. package/src/common/skills/specs/templates/requirements-init.md +9 -0
  47. package/src/common/skills/specs/templates/requirements.md +26 -0
  48. package/src/common/skills/specs/templates/research.md +61 -0
  49. 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
+ [![Version](https://img.shields.io/badge/version-0.2.2-blue.svg)](https://github.com/haposoft/cafekit)
6
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7
+ [![Claude Code](https://img.shields.io/badge/Claude%20Code-Supported-orange.svg)](https://claude.ai/code)
8
+ [![Antigravity](https://img.shields.io/badge/Antigravity-Supported-purple.svg)](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>