@haposoft/cafekit 0.3.0

package/src/claude/commands/spec-tasks.md

@@ -0,0 +1,173 @@
+---
+name: spec-tasks
+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)
+- Resolve scope baseline from `spec.json.scope_lock` (fallback to derived baseline when missing)
+- **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
+- Only use valid in-scope requirement IDs from requirements.md
+- Every task MUST reference at least one valid in-scope requirement ID
+- Reject or defer task candidates that map only to out-of-scope capabilities
+- When documenting requirement coverage, list numeric requirement IDs only (comma-separated) without descriptive suffixes, parentheses, translations, or free-form labels
+- Ensure all in-scope 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 in-scope requirements must map to tasks
+- **Scope Lock**: Do not generate out-of-scope tasks; classify them as deferred when needed
+- **Requirement Mapping Integrity**: Each task must map to valid numeric in-scope requirement IDs
+- **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 in-scope requirements mapped to tasks
+   - ✅ Task dependencies verified
+   - ✅ Testing tasks included
+4. **Scope Guard**:
+   - ✅ Every task maps to valid in-scope requirement IDs
+   - ✅ Out-of-scope tasks deferred/blocked
+5. **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 in-scope requirements mapped to tasks. Review coverage."
+- **User Action Required**: Confirm intentional gaps or regenerate tasks
+
+**Out-of-Scope Tasks Detected**:
+- **Block/Defer**: Do not include out-of-scope tasks in primary task plan
+- **User Guidance**: Request explicit scope expansion approval if user wants those tasks promoted
+
+**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.
+
+**Invalid Requirement Mapping in Tasks**:
+- **Stop Execution**: If a generated task cannot map to valid in-scope numeric requirement IDs, remove/defer it and regenerate task mapping
+
+### 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/claude/commands/spec-validate.md

@@ -0,0 +1,118 @@
+---
+name: spec-validate
+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)
+
+Resolve scope lock first:
+- `scope_lock.source`
+- `scope_lock.in_scope[]`
+- `scope_lock.out_of_scope[]`
+- `scope_lock.expansion_policy`
+
+Extract decision points around in-scope trade-offs only:
+- 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 in-scope implementation
+- Each question must have 2-4 concrete options
+- Prefer in-scope confirmation questions first; scope-expansion questions are optional and only if needed
+
+### 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
+- Keep questions inside current scope by default
+- Open-scope expansion questions are allowed only when scope pressure is detected and must require explicit user approval
+
+### 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)
+- if explicit expansion approved by user, update `scope_lock.in_scope` / `scope_lock.out_of_scope` accordingly
+- 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
+- Do not introduce new capability domains during validation unless user explicitly approves scope expansion
+</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/claude/commands/test.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Run tests locally and analyze the summary report.
+---
+
+Use the `tester` subagent to run tests locally and analyze the summary report.
+
+**IMPORTANT**: **Do not** start implementing.
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

package/src/claude/migration-manifest.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "scope": "claude-only",
+  "commands": {
+    "core": [
+      "docs.md",
+      "spec-init.md",
+      "spec-requirements.md",
+      "spec-design.md",
+      "spec-validate.md",
+      "spec-tasks.md",
+      "spec-status.md",
+      "code.md",
+      "test.md",
+      "review.md",
+      "review/codebase.md",
+      "review/codebase/parallel.md"
+    ]
+  },
+  "skills": {
+    "required": [
+      "specs"
+    ]
+  },
+  "agents": {
+    "required": [
+      "tester.md",
+      "code-reviewer.md",
+      "fullstack-developer.md",
+      "debugger.md"
+    ]
+  },
+  "scripts": {
+    "required": []
+  },
+  "hooks": {
+    "assumed": []
+  }
+}

package/src/common/skills/specs/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: specs
+description: Specs workflow for creating comprehensive feature specifications. Use for new features, complex changes, or when you need structured requirements, design, and task breakdown.
+---
+
+# Specs (SDD)
+
+> Hệ thống tạo specification có cấu trúc, từ ý tưởng mơ hồ đến task list cụ thể.
+
+## Overview
+
+Skill này cung cấp quy trình 7 bước để biến ý tưởng thành spec và triển khai thực tế:
+
+```
+Idea - Requirements - Design - Tasks - Code - Test - Review
+```
+
+## Available Workflows
+
+| 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 tasks |
+| `/test` | Run tests cho phần code vừa implement |
+| `/review` | Review code quality trước khi merge |
+| `/spec-status <feature>` | Xem trạng thái hiện tại |
+
+## Quick Start
+
+```bash
+# 1. Khởi tạo spec
+/spec-init Tạo app mobile cho hệ thống quản lý
+
+# 2. Sinh requirements
+/spec-requirements mobile-app
+
+# 3. Sinh design
+/spec-design mobile-app
+
+# 4. Sinh tasks
+/spec-tasks mobile-app
+
+# 5. Code
+/code mobile-app
+
+# 6. Test
+/test
+
+# 7. Review
+/review
+```
+
+## Data Structure
+
+Mỗi feature spec được lưu trong `.specs/<feature-name>/`:
+
+```
+.specs/
+└── mobile-app/
+    ├── spec.json           # Metadata & state
+    ├── requirements.md     # Requirements (EARS format)
+    ├── research.md         # Research log
+    ├── design.md           # Design document
+    └── tasks.md            # Task list
+```
+
+## Resources
+
+Skill này bao gồm:
+
+### Templates (`templates/`)
+- `init.json` - Schema metadata
+- `requirements-init.md` - Template requirements rỗng
+- `requirements.md` - Template requirements đầy đủ
+- `design.md` - Template design doc
+- `research.md` - Template research log
+- `tasks.md` - Template task list
+
+### Rules (`rules/`)
+- `ears-format.md` - Chuẩn viết Requirements (EARS)
+- `design-principles.md` - Nguyên tắc thiết kế
+- `design-discovery-full.md` - Quy trình research đầy đủ
+- `design-discovery-light.md` - Quy trình research nhẹ
+- `tasks-generation.md` - Quy tắc chia task
+- `tasks-parallel-analysis.md` - Phân tích task song song
+
+## When to Use
+
+✅ **Dùng khi:**
+- Tạo feature mới phức tạp
+- Cần documentation trước khi code
+- Làm việc với team (cần review spec)
+- Dự án cần audit trail
+
+❌ **Không cần khi:**
+- Fix bug đơn giản
+- Thay đổi nhỏ (< 1 giờ)
+- Hotfix khẩn cấp

package/src/common/skills/specs/rules/design-discovery-full.md

@@ -0,0 +1,93 @@
+# Full Discovery Process for Technical Design
+
+## Objective
+Conduct comprehensive research and analysis to ensure the technical design is based on complete, accurate, and up-to-date information.
+
+## Discovery Steps
+
+### 1. Requirements Analysis
+**Map Requirements to Technical Needs**
+- Extract all functional requirements from EARS format
+- Identify non-functional requirements (performance, security, scalability)
+- Determine technical constraints and dependencies
+- List core technical challenges
+
+### 2. Existing Implementation Analysis
+**Understand Current System** (if modifying/extending):
+- Analyze codebase structure and architecture patterns
+- Map reusable components, services, utilities
+- Identify domain boundaries and data flows
+- Document integration points and dependencies
+- Determine approach: extend vs refactor vs wrap
+
+### 3. Technology Research
+**Investigate Best Practices and Solutions**:
+- **Use WebSearch** to find:
+  - Latest architectural patterns for similar problems
+  - Industry best practices for the technology stack
+  - Recent updates or changes in relevant technologies
+  - Common pitfalls and solutions
+
+- **Use WebFetch** to analyze:
+  - Official documentation for frameworks/libraries
+  - API references and usage examples
+  - Migration guides and breaking changes
+  - Performance benchmarks and comparisons
+
+### 4. External Dependencies Investigation
+**For Each External Service/Library**:
+- Search for official documentation and GitHub repositories
+- Verify API signatures and authentication methods
+- Check version compatibility with existing stack
+- Investigate rate limits and usage constraints
+- Find community resources and known issues
+- Document security considerations
+- Note any gaps requiring implementation investigation
+
+### 5. Architecture Pattern & Boundary Analysis
+**Evaluate Architectural Options**:
+- Compare relevant patterns (MVC, Clean, Hexagonal, Event-driven)
+- Assess fit with existing architecture and steering principles
+- Identify domain boundaries and ownership seams required to avoid team conflicts
+- Consider scalability implications and operational concerns
+- Evaluate maintainability and team expertise
+- Document preferred pattern and rejected alternatives in `research.md`
+
+### 6. Risk Assessment
+**Identify Technical Risks**:
+- Performance bottlenecks and scaling limits
+- Security vulnerabilities and attack vectors
+- Integration complexity and coupling
+- Technical debt creation vs resolution
+- Knowledge gaps and training needs
+
+## Research Guidelines
+
+### When to Search
+**Always search for**:
+- External API documentation and updates
+- Security best practices for authentication/authorization
+- Performance optimization techniques for identified bottlenecks
+- Latest versions and migration paths for dependencies
+
+**Search if uncertain about**:
+- Architectural patterns for specific use cases
+- Industry standards for data formats/protocols
+- Compliance requirements (GDPR, HIPAA, etc.)
+- Scalability approaches for expected load
+
+### Search Strategy
+1. Start with official sources (documentation, GitHub)
+2. Check recent blog posts and articles (last 6 months)
+3. Review Stack Overflow for common issues
+4. Investigate similar open-source implementations
+
+## Output Requirements
+Capture all findings that impact design decisions in `research.md` using the shared template:
+- Key insights affecting architecture, technology alignment, and contracts
+- Constraints discovered during research
+- Recommended approaches and selected architecture pattern with rationale
+- Rejected alternatives and trade-offs (documented in the Design Decisions section)
+- Updated domain boundaries that inform Components & Interface Contracts
+- Risks and mitigation strategies
+- Gaps requiring further investigation during implementation

package/src/common/skills/specs/rules/design-discovery-light.md

@@ -0,0 +1,49 @@
+# Light Discovery Process for Extensions
+
+## Objective
+Quickly analyze existing system and integration requirements for feature extensions.
+
+## Focused Discovery Steps
+
+### 1. Extension Point Analysis
+**Identify Integration Approach**:
+- Locate existing extension points or interfaces
+- Determine modification scope (files, components)
+- Check for existing patterns to follow
+- Identify backward compatibility requirements
+
+### 2. Dependency Check
+**Verify Compatibility**:
+- Check version compatibility of new dependencies
+- Validate API contracts haven't changed
+- Ensure no breaking changes in pipeline
+
+### 3. Quick Technology Verification
+**For New Libraries Only**:
+- Use WebSearch for official documentation
+- Verify basic usage patterns
+- Check for known compatibility issues
+- Confirm licensing compatibility
+- Record key findings in `research.md` (technology alignment section)
+
+### 4. Integration Risk Assessment
+**Quick Risk Check**:
+- Impact on existing functionality
+- Performance implications
+- Security considerations
+- Testing requirements
+
+## When to Escalate to Full Discovery
+Switch to full discovery if you find:
+- Significant architectural changes needed
+- Complex external service integrations
+- Security-sensitive implementations
+- Performance-critical components
+- Unknown or poorly documented dependencies
+
+## Output Requirements
+- Clear integration approach (note boundary impacts in `research.md`)
+- List of files/components to modify
+- New dependencies with versions
+- Integration risks and mitigations
+- Testing focus areas