@haposoft/cafekit 0.3.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@haposoft/cafekit",
+  "version": "0.3.0",
+  "description": "Spec-Driven Development workflow for AI coding assistants. Supports Claude Code and Antigravity with spec-first and code-test-review workflows.",
+  "author": "Haposoft <nghialt@haposoft.com>",
+  "license": "MIT",
+  "private": false,
+  "bin": {
+    "cafekit": "./bin/install.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haposoft/cafekit.git",
+    "directory": "packages/spec"
+  },
+  "homepage": "https://github.com/haposoft/cafekit#readme",
+  "bugs": {
+    "url": "https://github.com/haposoft/cafekit/issues"
+  },
+  "keywords": [
+    "haposoft",
+    "cafekit",
+    "spec-driven",
+    "workflow",
+    "claude-code",
+    "antigravity",
+    "ai-coding",
+    "specification",
+    "requirements",
+    "sdd"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/antigravity/GEMINI.md

@@ -0,0 +1,162 @@
+---
+trigger: always_on
+---
+
+# GEMINI.md - Antigravity Kit
+
+> This file defines how the AI behaves in this workspace.
+
+---
+
+## CRITICAL: AGENT & SKILL PROTOCOL (START HERE)
+
+> **MANDATORY:** You MUST read the appropriate agent file and its skills BEFORE performing any implementation. This is the highest priority rule.
+
+### 1. Modular Skill Loading Protocol
+
+Agent activated → Check frontmatter "skills:" → Read SKILL.md (INDEX) → Read specific sections.
+
+- **Selective Reading:** DO NOT read ALL files in a skill folder. Read `SKILL.md` first, then only read sections matching the user's request.
+- **Rule Priority:** P0 (GEMINI.md) > P1 (Agent .md) > P2 (SKILL.md). All rules are binding.
+
+### 2. Enforcement Protocol
+
+1. **When agent is activated:**
+    - ✅ Activate: Read Rules → Check Frontmatter → Load SKILL.md → Apply All.
+2. **Forbidden:** Never skip reading agent rules or skill instructions. "Read → Understand → Apply" is mandatory.
+3. **Artifact Ban:** DO NOT create "Implementation Plan" artifacts (sidebar artifacts) unless the user EXPLICITLY asks for them. Use standard markdown files in `docs/` or text responses instead.
+
+---
+
+## 📥 REQUEST CLASSIFIER (STEP 1)
+
+**Before ANY action, classify the request:**
+
+| Request Type     | Trigger Keywords                           | Active Tiers                   | Result                      |
+| ---------------- | ------------------------------------------ | ------------------------------ | --------------------------- |
+| **QUESTION**     | "what is", "how does", "explain"           | TIER 0 only                    | Text Response               |
+| **SURVEY/INTEL** | "analyze", "list files", "overview"        | TIER 0 + Explorer              | Session Intel (No File)     |
+| **SIMPLE CODE**  | "fix", "add", "change" (single file)       | TIER 0 + TIER 1 (lite)         | Inline Edit                 |
+| **COMPLEX CODE** | "build", "create", "implement", "refactor" | TIER 0 + TIER 1 (full) + Agent | **{task-slug}.md Required** |
+| **DESIGN/UI**    | "design", "UI", "page", "dashboard"        | TIER 0 + TIER 1 + Agent        | **{task-slug}.md Required** |
+| **SLASH CMD**    | /spec-init, /spec-requirements, /spec-design, /spec-tasks, /spec-status, /code, /test, /review, /docs-init, /docs-update | Command-specific flow | Variable |
+
+---
+
+## TIER 0: UNIVERSAL RULES (Always Active)
+
+### 💬 Response Format
+
+All responses must generally follow this structure:
+1. **Explanation**: Brief context/problem/solution.
+2. **Implementation**: Code/Action with clear comments.
+3. **Usage/Caveats**: (If applicable)
+4. **Next Action:** (MANDATORY) Specific proposed next step.
+   - Example: "Use `/spec-init` to start", "Review `docs/PLAN-x.md`", "Run `pytest`".
+
+### 🌐 Language Handling
+
+When user's prompt is NOT in English:
+
+1. **Internally translate** for better comprehension
+2. **Respond in user's language** - match their communication
+3. **Code comments/variables** remain in English
+
+### 🧹 Clean Code (Global Mandatory)
+
+- **Code**: Concise, direct, no over-engineering. Self-documenting.
+- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
+- **Performance**: Measure first. Adhere to 2025 standards (Core Web Vitals).
+- **Infra/Safety**: 5-Phase Deployment. Verify secrets security.
+- Concise, direct, solution-focused
+- No verbose explanations
+- No over-commenting
+- No over-engineering
+- **Artifact Control:** DO NOT create "Implementation Plan" artifacts (sidebar artifacts) unless the user EXPLICITLY asks for them. Use standard markdown files in `docs/` or text responses instead.
+- **Self-Documentation:** Every agent is responsible for documenting their own changes in relevant `.md` files.
+
+### 🗺️ System Map Read
+
+**Path Awareness:**
+
+- Skills: `.agent/skills/` (Project)
+- Workflows: `.agent/workflows/` (Project)
+- Models: `.agent/models/` (Project)
+- Specs: `.specs/` (Project)
+
+### 🧠 Read → Understand → Apply
+
+```
+❌ WRONG: Read agent file → Start coding
+✅ CORRECT: Read → Understand WHY → Apply PRINCIPLES → Code
+```
+
+**Before coding, answer:**
+
+1. What is the GOAL of this agent/skill?
+2. What PRINCIPLES must I apply?
+3. How does this DIFFER from generic output?
+
+---
+
+## TIER 1: CODE RULES (When Writing Code)
+
+### 🛑 GLOBAL SOCRATIC GATE (TIER 0)
+
+**MANDATORY: Every user request must pass through the Socratic Gate before ANY tool use or implementation.**
+
+| Request Type            | Strategy       | Required Action                                                   |
+| ----------------------- | -------------- | ----------------------------------------------------------------- |
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions                                 |
+| **Code Edit / Bug Fix** | Context Check  | Confirm understanding + ask impact questions                      |
+| **Vague / Simple**      | Clarification  | Ask Purpose, Users, and Scope                                     |
+| **Full Orchestration**  | Gatekeeper     | **STOP** subagents until user confirms plan details               |
+| **Direct "Proceed"**    | Validation     | **STOP** → Even if answers are given, ask 2 "Edge Case" questions |
+
+**Protocol:**
+
+1. **Never Assume:** If even 1% is unclear, ASK.
+2. **Handle Spec-heavy Requests:** When user gives a list (Answers 1, 2, 3...), do NOT skip the gate. Instead, ask about **Trade-offs** or **Edge Cases** (e.g., "LocalStorage confirmed, but should we handle data clearing or versioning?") before starting.
+3. **Wait:** Do NOT invoke subagents or write code until the user clears the Gate.
+
+---
+
+## 📁 AVAILABLE WORKFLOWS
+
+### Spec-Driven Development
+
+| Command | Mô tả |
+|---------|-------|
+| `/spec-init <mô tả>` | Khởi tạo spec mới từ ý tưởng |
+| `/spec-requirements <feature>` | Sinh requirements (EARS format) |
+| `/spec-design <feature>` | Sinh design doc + research |
+| `/spec-tasks <feature>` | Sinh task list |
+| `/code <feature>` | Implement task từ spec và chuyển qua test/review |
+| `/spec-status <feature>` | Xem trạng thái hiện tại |
+
+### Documentation
+
+| Command | Mô tả |
+|---------|-------|
+| `/docs-init` | Initialize project documentation |
+| `/docs-update` | Update existing documentation |
+
+**Usage:**
+- Read `.agent/skills/specs/SKILL.md` for detailed workflow information
+- Each workflow has its own file in `.agent/workflows/` with specific instructions
+
+---
+
+## 📁 QUICK REFERENCE
+
+### Skills
+
+- **specs**: Complete SDD workflow from idea to implementation
+
+### Workflows Location
+
+- Workflows: `.agent/workflows/`
+- Skill definitions: `.agent/skills/`
+- Spec data: `.specs/<feature-name>/`
+
+---

package/src/antigravity/workflows/code.md

@@ -0,0 +1,16 @@
+---
+description: Implement approved work from specification tasks and then hand off to test and review.
+allowed-tools: Read, Glob, Grep, Edit, Write, Bash
+argument-hint: <feature-name>
+---
+
+# /code - Implement from spec tasks
+
+Use this workflow after `/spec-tasks`.
+
+1. Read `.specs/$ARGUMENTS/tasks.md` and identify the next pending task.
+2. Implement only that task following project standards.
+3. Run `/test`.
+4. Run `/review`.
+
+Preferred flow: `/spec-init` - `/spec-requirements` - `/spec-design` - `/spec-tasks` - `/code` - `/test` - `/review`

package/src/antigravity/workflows/docs-init.md

@@ -0,0 +1,432 @@
+---
+description: Initialize comprehensive documentation for the project. Use when setting up docs for the first time or creating documentation skeleton from existing codebase.
+---
+
+# /docs-init - Initialize Project Documentation
+
+## Overview
+
+This workflow creates comprehensive documentation structure for your project:
+- Generates 7 core documentation files
+- Creates project context file (.agent/rules/AGENTS.md)
+- Uses repomix for codebase analysis
+
+## ⚠️ IMPORTANT: Execute Immediately
+
+**DO NOT create an implementation plan.** This workflow should be executed directly without planning mode.
+- Run all steps sequentially
+- Create files immediately as described
+- No approval needed between steps
+
+---
+
+## Step 1: Check Prerequisites
+
+**Check if docs/ already exists:**
+```bash
+ls -la docs/ 2>/dev/null && echo "EXISTS" || echo "NOT_FOUND"
+```
+
+**If docs/ exists:**
+- Ask user: "docs/ already exists. Overwrite / Merge / Skip?"
+- Default: "Merge" (preserve existing, add missing)
+
+---
+
+## Step 2: Install Repomix
+
+**Check if repomix is installed:**
+```bash
+which repomix 2>/dev/null || npm list -g repomix 2>/dev/null
+```
+
+**If repomix not found:**
+- Detect package manager:
+  ```bash
+  test -f pnpm-lock.yaml && PM="pnpm"
+  test -f yarn.lock && PM="yarn"
+  test -f bun.lockb && PM="bun"
+  PM="${PM:-npm}"
+  ```
+
+// turbo
+- Run `$PM install -g repomix`
+- Verify: `which repomix`
+
+---
+
+## Step 3: Run Repomix Analysis
+
+// turbo
+```bash
+repomix
+ls -la ./repomix-output.xml
+```
+
+---
+
+## Step 4: Auto-Detect Project Information
+
+**Detect Package Manager & Tech Stack:**
+```bash
+test -f pnpm-lock.yaml && echo "PNPM"
+test -f yarn.lock && echo "YARN"
+test -f package-lock.json && echo "NPM"
+test -f bun.lockb && echo "BUN"
+test -f requirements.txt && echo "PIP"
+test -f poetry.lock && echo "POETRY"
+test -f go.mod && echo "GO"
+test -f Cargo.toml && echo "CARGO"
+```
+
+**Read Config Files:**
+- Read `package.json` for name, version, scripts, dependencies
+- Read `pyproject.toml` if Python project
+- Read `go.mod` if Go project
+- Read `README.md` for description
+
+**Extract:**
+- Project name, version, description
+- Tech stack with versions
+- Available scripts/commands
+- Key dependencies
+
+---
+
+## Step 5: Detect Project Structure
+
+**Get directory structure:**
+```bash
+find . -maxdepth 3 -type d ! -path './node_modules/*' ! -path './.git/*' ! -path './.*' 2>/dev/null | sort | head -40
+```
+
+**Detect Platforms & Tools:**
+- **Deployment**: `vercel.json`, `netlify.toml`, `Dockerfile`, `fly.toml`, `.github/workflows`
+- **Database**: `prisma/schema.prisma`, `drizzle.config.ts`
+- **API**: `src/app/api`, `src/routes`, `pages/api`
+- **Testing**: Check package.json for `vitest`, `jest`, `playwright`, `cypress`
+- **UI**: Check for `tailwind`, `@base-ui`, `shadcn`, etc.
+
+---
+
+## Step 6: Create docs/ Directory
+
+// turbo
+```bash
+mkdir -p docs/
+```
+
+---
+
+## Step 7: Generate Documentation Files
+
+### 7.1 Create docs/codebase-summary.md
+
+```markdown
+# Codebase Summary
+
+> Auto-generated project overview
+
+## Project Info
+| Property | Value |
+|----------|-------|
+| **Name** | {from package.json} |
+| **Version** | {from package.json} |
+| **Type** | {detected} |
+| **Package Manager** | {detected} |
+
+## Statistics
+| Metric | Value |
+|--------|-------|
+| Files | {from repomix} |
+| Tokens | {from repomix} |
+| Generated | {timestamp} |
+
+## Tech Stack
+| Layer | Technology |
+|-------|------------|
+| Framework | {detected with version} |
+| Language | {detected} |
+| Styling | {detected} |
+| UI Library | {detected} |
+| Database | {if detected} |
+| Testing | {if detected} |
+
+## Project Structure
+```
+{directory tree from analysis}
+```
+
+## Key Directories
+| Directory | Purpose |
+|-----------|---------|
+| {detected} | {inferred purpose} |
+```
+
+### 7.2 Create docs/project-overview-pdr.md
+
+```markdown
+# Project Overview (PDR)
+
+## Identity
+- **Name:** {name}
+- **Type:** {type}
+- **Status:** Active
+
+## Description
+{from package.json description or README}
+
+## Features
+{extract from codebase}
+
+## Roadmap
+- [ ] Current sprint
+- [ ] Next milestones
+```
+
+### 7.3 Create docs/code-standards.md
+
+```markdown
+# Code Standards
+
+## Stack
+- Language: {detected}
+- Framework: {detected}
+- Linting: {detected}
+
+## Conventions
+{inferred from codebase patterns}
+
+## Patterns
+{common patterns detected}
+
+## File Organization
+{detected structure}
+```
+
+### 7.4 Create docs/system-architecture.md
+
+```markdown
+# System Architecture
+
+## Overview
+{architecture type: monolith, microservices, serverless, etc.}
+
+## Components
+| Component | Tech | Purpose |
+|-----------|------|---------|
+| Frontend | {detected} | UI layer |
+| Backend | {detected} | API layer |
+| Database | {detected} | Data persistence |
+
+## Data Flow
+{simple description}
+
+## API Structure
+{if detected}
+
+## Database Schema
+{if detected}
+```
+
+### 7.5 Create docs/design-guidelines.md
+
+```markdown
+# Design Guidelines
+
+## System
+- CSS Framework: {Tailwind/Styled/etc}
+- UI Library: {detected}
+- Icons: {detected}
+
+## Patterns
+{detected patterns}
+
+## Responsive
+{breakpoints if Tailwind}
+
+## Theme
+{dark/light mode setup}
+```
+
+### 7.6 Create docs/deployment-guide.md
+
+```markdown
+# Deployment Guide
+
+## Platform
+{detected platform}
+
+## Quick Deploy
+```bash
+{platform-specific commands}
+```
+
+## Environment Variables
+{from .env.example if exists}
+
+## Available Commands
+| Command | Purpose |
+|---------|---------|
+| {from package.json} | {description} |
+```
+
+### 7.7 Create docs/project-roadmap.md
+
+```markdown
+# Project Roadmap
+
+## Current
+{detected state}
+
+## Short Term (30 days)
+- [ ] Tasks
+
+## Medium Term (90 days)
+- [ ] Enhancements
+
+## Long Term (6 months)
+- [ ] Scale
+
+## Technical Debt
+{detected issues}
+```
+
+---
+
+## Step 8: Create .agent/rules/AGENTS.md (Optional)
+
+**Check if .agent/rules/ exists:**
+```bash
+test -d .agent/rules && echo "EXISTS" || echo "NOT_FOUND"
+```
+
+**If not exists, create it:**
+// turbo
+```bash
+mkdir -p .agent/rules
+```
+
+**Create .agent/rules/AGENTS.md:**
+
+```markdown
+---
+activation: always_on
+---
+
+# {Project Name}
+
+> Project-specific context for AI agents (Antigravity, Claude Code, etc.). See `.agent/` for workflows and skills.
+
+---
+
+## Project Overview
+
+{description from package.json or README}
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| {detected} | {with versions} |
+
+---
+
+## Key Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| {detected} | {description} |
+
+---
+
+## Quick Commands
+
+| Task | Command |
+|------|---------|
+| {from package.json scripts} | `{pm} run {script}` |
+
+---
+
+## Project Docs (On-demand)
+
+| Doc | Purpose | Load when |
+|-----|---------|-----------|
+| `docs/codebase-summary.md` | Project overview | "summary", "overview" |
+| `docs/project-overview-pdr.md` | Product requirements | "requirements", "pdr" |
+| `docs/code-standards.md` | Coding conventions | "standards", "conventions" |
+| `docs/system-architecture.md` | Architecture | "architecture", "design" |
+| `docs/design-guidelines.md` | UI/UX standards | "design", "ui", "ux" |
+| `docs/deployment-guide.md` | Deployment | "deploy", "production" |
+| `docs/project-roadmap.md` | Roadmap | "roadmap", "future" |
+
+---
+
+## Agent Workflows
+
+Available workflows in `.agent/workflows/`:
+- `/docs-init` - Initialize documentation
+- `/docs-update` - Update documentation
+
+---
+
+**Last Updated:** {timestamp}
+```
+
+**Note:**
+- File `.agent/rules/AGENTS.md` với `activation: always_on` sẽ được **always active** trong Antigravity
+- Đặt trong `.agent/rules/` để Antigravity tự động nhận diện và load
+- Có thể đồng thờI tạo symlink `AGENTS.md` ở root để dùng cho Claude Code
+
+---
+
+## Step 9: Generate Report
+
+**Output success message:**
+
+```
+✅ Documentation initialized!
+
+📊 Detected:
+   - Project: {name}
+   - Type: {type}
+   - Stack: {summary}
+   - Files: {count} | Tokens: {count}
+
+📁 Generated (docs/):
+   ✓ codebase-summary.md
+   ✓ project-overview-pdr.md
+   ✓ code-standards.md
+   ✓ system-architecture.md
+   ✓ design-guidelines.md
+   ✓ deployment-guide.md
+   ✓ project-roadmap.md
+
+📝 Also created:
+   ✓ repomix-output.xml (AI context)
+   ✓ .agent/rules/AGENTS.md (always-active project context)
+
+🚀 Next: Run `/docs-update` after code changes
+```
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| repomix not found | Warn, continue with manual analysis |
+| No package.json | Ask user for project type |
+| docs/ exists | Ask: Overwrite/Merge/Skip |
+| Permission denied | Report path, suggest fix |
+
+---
+
+## Notes
+
+- Always use detected values, never placeholders
+- Include versions: "Next.js 14.1.0" not "Next.js"
+- repomix-output.xml helps AI understand full context
+- 7 docs files = comprehensive coverage