@haposoft/cafekit 0.3.0

package/src/antigravity/workflows/spec-status.md

@@ -0,0 +1,95 @@
+---
+description: Display current status of a specification.
+---
+
+# /spec-status - View Specification Status
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Hiển thị trạng thái hiện tại của một spec hoặc liệt kê tất cả specs.
+
+---
+
+## Task
+
+### Execution Steps
+
+**If `$ARGUMENTS` is provided:**
+
+1. Read `.specs/$ARGUMENTS/spec.json`
+2. Display:
+   - Feature name
+   - Current phase
+   - Approval status
+   - Discovery mode (if available)
+   - Validation status and last validated time (if available)
+   - **Backward compatibility fallback (older specs):**
+     - If `design_context` is missing, show Discovery mode as `n/a`
+     - If `validation` is missing, show Validation as `not-run` and Last validated as `n/a`
+   - Created/Updated timestamps
+   - Summary of files
+
+**If no arguments:**
+
+1. Glob `.specs/*/spec.json`
+2. List all specs with their status
+
+---
+
+## Output Format
+
+### Single Spec Status
+
+```markdown
+## 📊 Spec Status: `<feature-name>`
+
+| Property | Value |
+|----------|-------|
+| **Phase** | `<phase>` |
+| **Discovery Mode** | `<minimal/light/full or n/a>` |
+| **Validation** | `<completed/pending/n/a>` |
+| **Last Validated** | `<timestamp or n/a>` |
+| **Created** | `<timestamp>` |
+| **Updated** | `<timestamp>` |
+
+### Approvals
+- Requirements: ✅/❌ Generated | ✅/❌ Approved
+- Design: ✅/❌ Generated | ✅/❌ Approved
+- Tasks: ✅/❌ Generated | ✅/❌ Approved
+
+### Files
+- `spec.json` ✅
+- `requirements.md` ✅/❌
+- `research.md` ✅/❌
+- `design.md` ✅/❌
+- `tasks.md` ✅/❌
+
+### Next Action
+- If phase = `requirements-generated`: Run `/spec-design <feature-name>`
+- If phase = `design-generated`: Run `/spec-tasks <feature-name>`
+- If phase = `tasks-generated`: Run `/code <feature-name>`, then `/test`, then `/review`
+```
+
+### All Specs List
+
+```markdown
+## 📊 All Specs
+
+| Feature | Phase | Last Updated |
+|---------|-------|--------------|
+| `mobile-app` | tasks-generated | 2026-01-21 |
+| `auth-module` | design-generated | 2026-01-20 |
+```
+
+---
+
+## Usage Examples
+
+```
+/spec-status mobile-app
+/spec-status
+```

package/src/antigravity/workflows/spec-tasks.md

@@ -0,0 +1,156 @@
+---
+description: Generate implementation tasks for a specification
+allowed-tools: Glob, Grep, Read, Write, Edit, WebSearch, WebFetch
+argument-hint: <feature-name> [-y] [--sequential]
+---
+
+# Implementation Tasks Generator
+
+<background_information>
+- **Mission**: Generate detailed, actionable implementation tasks that translate technical design into executable work items
+- **Success Criteria**:
+  - All requirements mapped to specific tasks
+  - Tasks properly sized (1-3 hours each)
+  - Clear task progression with proper hierarchy
+  - Natural language descriptions focused on capabilities
+</background_information>
+
+<instructions>
+## Core Task
+Generate implementation tasks for feature **$ARGUMENTS** based on approved requirements and design.
+
+## Execution Steps
+
+### Step 0: Validate Phase State (Plan-Style Gate)
+
+- Read `.specs/$ARGUMENTS/spec.json` first
+- If feature directory or `spec.json` is missing: stop and instruct user to run `/spec-init <project-description>`, `/spec-requirements <feature-name>`, and `/spec-design <feature-name>` first
+- If design has not been generated yet (phase before design): stop and instruct user to run `/spec-design $ARGUMENTS`
+- If `phase` is already `tasks-generated`: explain tasks phase already exists and only continue for explicit regeneration/merge intent
+
+### Step 1: Load Context
+
+**Read all necessary context**:
+- `.specs/$ARGUMENTS/spec.json`, `requirements.md`, `design.md`
+- `.specs/$ARGUMENTS/tasks.md` (if exists, for merge mode)
+- `.specs/$ARGUMENTS/research.md` (if exists, includes validation log)
+- **Entire `.specs/steering/` directory** for complete project memory (if exists)
+- **Load project docs context (Plan-style quality gate)** when available:
+  - `docs/codebase-summary.md`
+  - `docs/code-standards.md`
+  - `docs/system-architecture.md`
+  - `docs/project-overview-pdr.md`
+- If any docs file is missing, continue and mention missing context in execution output (do not block generation)
+
+**Validate approvals**:
+- If `-y` flag provided: Auto-approve requirements and design in spec.json
+- Otherwise: Verify both approved (stop if not, see Safety & Fallback)
+- **Backward compatibility fallback (older specs):**
+  - If `validation` object is missing, treat validation status as `not-run`
+  - If `design_context` object is missing, treat `validation_recommended` as `false`
+- If `spec.json.validation.status == "completed"`, treat validation as satisfied
+- If validation is missing and `design_context.validation_recommended == true`, warn user to run `/spec-validate $ARGUMENTS` before continuing (do not hard-block)
+- Determine sequential mode based on presence of `--sequential`
+
+### Step 2: Generate Implementation Tasks
+
+**Load generation rules and template**:
+- Read `{{SKILLS_DIR}}/specs/rules/tasks-generation.md` for principles
+- If `sequential` is **false**: Read `{{SKILLS_DIR}}/specs/rules/tasks-parallel-analysis.md` for parallel judgement criteria
+- Read `{{SKILLS_DIR}}/specs/templates/tasks.md` for format (supports `(P)` markers)
+
+**Generate task list following all rules**:
+- Use language specified in spec.json
+- Map all requirements to tasks
+- When documenting requirement coverage, list numeric requirement IDs only (comma-separated) without descriptive suffixes, parentheses, translations, or free-form labels
+- Ensure all design components included
+- Verify task progression is logical and incremental
+- Collapse single-subtask structures by promoting them to major tasks and avoid duplicating details on container-only major tasks (use template patterns accordingly)
+- Apply `(P)` markers to tasks that satisfy parallel criteria (omit markers in sequential mode)
+- Mark optional test coverage subtasks with `- [ ]*` only when they strictly cover acceptance criteria already satisfied by core implementation and can be deferred post-MVP
+- If existing tasks.md found, merge with new content
+
+### Step 3: Finalize
+
+**Write and update**:
+- Create/update `.specs/$ARGUMENTS/tasks.md`
+- Update spec.json metadata:
+  - Set `phase: "tasks-generated"`
+  - Set `approvals.tasks.generated: true, approved: false`
+  - Set `approvals.requirements.approved: true`
+  - Set `approvals.design.approved: true`
+  - Update `updated_at` timestamp
+
+## Critical Constraints
+- **Follow rules strictly**: All principles in tasks-generation.md are mandatory
+- **Natural Language**: Describe what to do, not code structure details
+- **Complete Coverage**: ALL requirements must map to tasks
+- **Maximum 2 Levels**: Major tasks and sub-tasks only (no deeper nesting)
+- **Sequential Numbering**: Major tasks increment (1, 2, 3...), never repeat
+- **Task Integration**: Every task must connect to the system (no orphaned work)
+</instructions>
+
+## Tool Guidance
+- **Read first**: Load all context, rules, and templates before generation
+- **Write last**: Generate tasks.md only after complete analysis and verification
+
+## Output Description
+
+Provide brief summary in the language specified in spec.json:
+
+1. **Status**: Confirm tasks generated at `.specs/$ARGUMENTS/tasks.md`
+2. **Task Summary**: 
+   - Total: X major tasks, Y sub-tasks
+   - All Z requirements covered
+   - Average task size: 1-3 hours per sub-task
+3. **Quality Validation**:
+   - ✅ All requirements mapped to tasks
+   - ✅ Task dependencies verified
+   - ✅ Testing tasks included
+4. **Next Action**: Review tasks and proceed when ready
+
+**Format**: Concise (under 200 words)
+
+## Safety & Fallback
+
+### Error Scenarios
+
+**Requirements or Design Not Approved**:
+- **Stop Execution**: Cannot proceed without approved requirements and design
+- **User Message**: "Requirements and design must be approved before task generation"
+- **Suggested Action**: "Run `/spec-tasks $ARGUMENTS -y` to auto-approve both and proceed"
+
+**Missing Requirements or Design**:
+- **Stop Execution**: Both documents must exist
+- **User Message**: "Missing requirements.md or design.md at `.specs/$ARGUMENTS/`"
+- **Suggested Action**: "Complete requirements and design phases first"
+
+**Incomplete Requirements Coverage**:
+- **Warning**: "Not all requirements mapped to tasks. Review coverage."
+- **User Action Required**: Confirm intentional gaps or regenerate tasks
+
+**Template/Rules Missing**:
+- **User Message**: "Template or rules files missing in `{{SKILLS_DIR}}/specs/`"
+- **Fallback**: Use inline basic structure with warning
+- **Suggested Action**: "Check repository setup or restore template files"
+
+**Missing Numeric Requirement IDs**:
+- **Stop Execution**: All requirements in requirements.md MUST have numeric IDs. If any requirement lacks a numeric ID, stop and request that requirements.md be fixed before generating tasks.
+
+### Next Phase: Implementation
+
+**Before Starting Implementation**:
+- **IMPORTANT**: Clear conversation history and free up context before running `/code`
+- This applies when starting first task OR switching between tasks
+- Fresh context ensures clean state and proper task focus
+
+**If Tasks Approved**:
+- Execute coding pass from approved spec tasks: `/code $ARGUMENTS`
+- After coding, run `/test` then `/review`
+- Repeat in small passes and clear context between iterations when needed
+
+**If Modifications Needed**:
+- Provide feedback and re-run `/spec-tasks $ARGUMENTS`
+- Existing tasks used as reference (merge mode)
+
+**Note**: Continue with `/test` then `/review` after `/code` to complete the workflow.

package/src/antigravity/workflows/spec-validate.md

@@ -0,0 +1,106 @@
+---
+description: Validate design decisions with interview questions before task generation
+allowed-tools: Read, Write, Edit, Glob, AskUserQuestion
+argument-hint: <feature-name>
+---
+
+# Specification Validation Interview
+
+<background_information>
+- **Mission**: Validate critical design decisions, assumptions, and trade-offs before generating implementation tasks.
+- **Success Criteria**:
+  - Ask targeted, concrete questions about high-impact decisions
+  - Record answers in spec artifacts for future traceability
+  - Update spec metadata to reflect validation status
+</background_information>
+
+<instructions>
+## Core Task
+Run a structured interview for feature **$ARGUMENTS** and persist decisions.
+
+## Execution Steps
+
+### Step 0: Resolve & Validate State
+- Require `$ARGUMENTS` as feature name
+- Read `.specs/$ARGUMENTS/spec.json`
+- Stop with guidance if spec does not exist
+- Ensure `requirements.md` and `design.md` exist before validation
+
+### Step 1: Load Validation Context
+Read:
+- `.specs/$ARGUMENTS/spec.json`
+- `.specs/$ARGUMENTS/requirements.md`
+- `.specs/$ARGUMENTS/design.md`
+- `.specs/$ARGUMENTS/research.md` (if exists)
+
+Extract decision points around:
+- architecture and boundaries
+- assumptions and defaults
+- integration risks
+- scope and sequencing
+- testing/security/performance trade-offs
+
+### Step 2: Determine Question Budget
+Use injected session validation settings when available (`Validation: mode=X, questions=MIN-MAX`).
+- If unavailable, use 3-6 questions
+- Ask only meaningful questions that can change implementation
+- Each question must have 2-4 concrete options
+
+### Step 3: Interview User
+Use `AskUserQuestion` in batches (max 4 questions per call).
+Rules:
+- Include one recommended option when a safe default exists
+- Keep options mutually exclusive
+- Do not ask redundant questions
+
+### Step 4: Persist Validation Log
+Append to `.specs/$ARGUMENTS/research.md` under `## Validation Log`.
+If section missing, create it.
+
+Session format:
+```markdown
+## Validation Log
+
+### Session N — YYYY-MM-DD
+- Questions asked: X
+
+1. [Category] Question text
+   - Options: A | B | C
+   - Answer: ...
+   - Rationale: why this decision matters
+
+#### Confirmed Decisions
+- ...
+
+#### Follow-up Actions
+- [ ] ...
+```
+
+### Step 5: Update Metadata
+Update `.specs/$ARGUMENTS/spec.json`:
+- `approvals.requirements.approved: true`
+- `approvals.design.approved: true`
+- `validation.last_validated_at: <ISO timestamp>`
+- `validation.questions_asked: <number>`
+- `validation.status: "completed"`
+- increment `validation.session_count` (initialize to 1 if absent)
+- update `updated_at`
+
+## Constraints
+- Keep input/output contract of existing `spec-*` commands unchanged
+- Validation must be traceable and append-only (never overwrite old sessions)
+- Ask fewer questions when artifact is simple; quality over quantity
+</instructions>
+
+## Output Description
+Provide concise summary:
+1. Validation status and files updated
+2. Number of questions asked
+3. Top confirmed decisions
+4. Recommended next command:
+   - `/spec-tasks $ARGUMENTS` when ready
+
+## Safety & Fallback
+- Missing spec/design artifacts: stop and instruct the exact preceding command
+- Empty decision surface: ask only 1-2 high-value confirmation questions
+- Write failure: report exact path and retry guidance

package/src/antigravity/workflows/test.md

@@ -0,0 +1,13 @@
+---
+description: Run project tests and report failures concisely.
+allowed-tools: Bash, Read, Grep
+argument-hint: [scope]
+---
+
+# /test
+
+Run the project's test command and report:
+- total passed/failed
+- failing test names
+- root cause hints
+- next fix action

package/src/claude/ROUTING.md

@@ -0,0 +1,101 @@
+# CafeKit Routing Guide
+
+> Project-specific routing and conventions for CafeKit. Complements Claude Code CLI's built-in agent system.
+
+---
+
+## Quick Agent Selection
+
+| Domain | Keywords | Agent File |
+|--------|----------|------------|
+| **Frontend** | ui, component, react, css, layout | `.claude/agents/ui-ux-designer.md` |
+| **Backend** | api, route, server, endpoint | `.claude/agents/fullstack-developer.md` |
+| **Database** | schema, migration, query, table | `.claude/agents/fullstack-developer.md` |
+| **Security** | auth, login, jwt, password | `.claude/agents/code-reviewer.md` |
+| **Mobile** | react native, flutter, ios, android | `.claude/agents/fullstack-developer.md` |
+| **Debug** | error, bug, crash, not working | `.claude/agents/debugger.md` |
+| **Testing** | test, coverage, unit, e2e | `.claude/agents/tester.md` |
+| **DevOps** | deploy, docker, ci/cd | `.claude/agents/fullstack-developer.md` |
+| **Performance** | slow, optimize, cache | `.claude/agents/code-reviewer.md` |
+| **Docs** | documentation, readme | `.claude/agents/docs-manager.md` |
+
+**Multi-domain:** Use `fullstack-developer` and coordinate with `tester` + `code-reviewer`.
+
+---
+
+## Project-Specific Rules
+
+### Socratic Gate (Complex Tasks)
+
+**MANDATORY:** Use `AskUserQuestion` for:
+- "Build/Create/Make [thing]" without details
+- Complex features or architecture
+- Vague requirements
+
+**Protocol:**
+1. STOP - Do NOT start coding
+2. INVOKE - Use AskUserQuestion tool
+3. WAIT - For user answers
+4. PROCEED - With clarified requirements
+
+### Clean Code Standards
+
+| Principle | Rule |
+|-----------|------|
+| **SRP** | One function = one thing |
+| **DRY** | Extract duplicates, reuse |
+| **KISS** | Simplest solution that works |
+| **YAGNI** | Don't build unused features |
+
+**Naming:**
+- Variables: `userCount` not `n`
+- Functions: `getUserById()` not `user()`
+- Booleans: `isActive`, `hasPermission`
+
+### Before Editing Files
+
+1. **Check imports:** Who depends on this file?
+2. **Identify impact:** What else needs updating?
+3. **Edit together:** File + all dependents in same task
+
+---
+
+## Slash Commands
+
+| Command | Purpose | Args |
+|---------|---------|------|
+| `/docs init` | Create docs | `[--focus=dirs]` |
+| `/docs update` | Update docs | `[--focus=dirs]` |
+| `/spec-init` | Init spec | `<description>` |
+| `/spec-requirements` | Requirements | `<feature>` |
+| `/spec-design` | Design doc | `<feature> [-y]` |
+| `/spec-tasks` | Task list | `<feature> [-y]` |
+| `/code` | Implement | `<feature> [task-id]` |
+| `/test` | Validate implementation | `[scope]` |
+| `/review` | Review code quality | `[scope]` |
+| `/spec-status` | View status | `[feature]` |
+
+---
+
+## Core Skills
+
+| Skill | Use When | Location |
+|-------|----------|----------|
+| **specs** | New features, specs | `{{SKILLS_DIR}}/specs/` |
+
+**All skills:** `{{SKILLS_DIR}}/`
+
+---
+
+## Project Context
+
+| File | Purpose | Load When |
+|------|---------|-----------|
+| `CLAUDE.md` | Project overview | Every session |
+| `docs/codebase-summary.md` | Stats, structure | "overview" |
+| `docs/system-architecture.md` | Architecture | "architecture" |
+| `repomix-output.xml` | Full codebase | Deep analysis |
+
+---
+
+**Last Updated:** 2026-02-24

package/src/claude/agents/code-reviewer.md

@@ -0,0 +1,131 @@
+---
+name: code-reviewer
+description: "Comprehensive code review with scout-based edge case detection. Use after implementing features, before PRs, for quality assessment, security audits, or performance optimization."
+---
+
+Senior software engineer specializing in code quality assessment. Expertise in TypeScript, JavaScript, Dart (Flutter), security, and performance.
+
+**IMPORTANT**: Ensure token efficiency. Use `scout` and `code-review` skills for protocols.
+
+## Core Responsibilities
+
+1. **Code Quality** - Standards adherence, readability, maintainability, code smells, edge cases
+2. **Type Safety & Linting** - TypeScript checking, linter results, pragmatic fixes
+3. **Build Validation** - Build success, dependencies, env vars (no secrets exposed)
+4. **Performance** - Bottlenecks, queries, memory, async handling, caching
+5. **Security** - OWASP Top 10, auth, injection, input validation, data protection
+6. **Task Completeness** - Verify spec task completion and workflow handoff status
+
+## Review Process
+
+### 1. Edge Case Scouting (NEW - Do First)
+
+Before reviewing, scout for edge cases the diff doesn't show:
+
+```bash
+git diff --name-only HEAD~1  # Get changed files
+```
+
+Use `/scout` with edge-case-focused prompt:
+```
+Scout edge cases for recent changes.
+Changed: {files}
+Find: affected dependents, data flow risks, boundary conditions, async races, state mutations
+```
+
+Document scout findings for inclusion in review.
+
+### 2. Initial Analysis
+
+- Read `.specs/<feature>/tasks.md` and related changed files
+- Focus on recently changed files (use `git diff`)
+- For full codebase: use `repomix` to compact, then analyze
+- Wait for scout results before proceeding
+
+### 3. Systematic Review
+
+| Area | Focus |
+|------|-------|
+| Structure | Organization, modularity |
+| Logic | Correctness, edge cases from scout |
+| Types | Safety, error handling |
+| Performance | Bottlenecks, inefficiencies |
+| Security | Vulnerabilities, data exposure |
+
+### 4. Prioritization
+
+- **Critical**: Security vulnerabilities, data loss, breaking changes
+- **High**: Performance issues, type safety, missing error handling
+- **Medium**: Code smells, maintainability, docs gaps
+- **Low**: Style, minor optimizations
+
+### 5. Recommendations
+
+For each issue:
+- Explain problem and impact
+- Provide specific fix example
+- Suggest alternatives if applicable
+
+### 6. Update Spec Task Status
+
+Mark reviewed task status and add next steps in workflow handoff.
+
+## Output Format
+
+```markdown
+## Code Review Summary
+
+### Scope
+- Files: [list]
+- LOC: [count]
+- Focus: [recent/specific/full]
+- Scout findings: [edge cases discovered]
+
+### Overall Assessment
+[Brief quality overview]
+
+### Critical Issues
+[Security, breaking changes]
+
+### High Priority
+[Performance, type safety]
+
+### Medium Priority
+[Code quality, maintainability]
+
+### Low Priority
+[Style, minor opts]
+
+### Edge Cases Found by Scout
+[List issues from scouting phase]
+
+### Positive Observations
+[Good practices noted]
+
+### Recommended Actions
+1. [Prioritized fixes]
+
+### Metrics
+- Type Coverage: [%]
+- Test Coverage: [%]
+- Linting Issues: [count]
+
+### Unresolved Questions
+[If any]
+```
+
+## Guidelines
+
+- Constructive, pragmatic feedback
+- Acknowledge good practices
+- Respect `./.claude/rules/development-rules.md` and `./docs/code-standards.md`
+- No AI attribution in code/commits
+- Security best practices priority
+- **Verify spec task checklist completion**
+- **Scout edge cases BEFORE reviewing**
+
+## Report Output
+
+Use naming pattern from `## Naming` section in hooks.
+
+Thorough but pragmatic - focus on issues that matter, skip minor style nitpicks.