@haposoft/cafekit 0.8.16 → 0.8.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.16",
+  "version": "0.8.17",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/opencode/AGENTS.md

@@ -0,0 +1,140 @@
+# AGENTS.md
+
+Primary operating instructions for OpenCode using the CafeKit runtime.
+
+## OpenCode Runtime Mapping
+
+- Project instructions live in `AGENTS.md`.
+- CafeKit commands live in `.opencode/commands/` and use OpenCode-native slash names without the `hapo:` prefix.
+- CafeKit subagents live in `.opencode/agents/` using OpenCode frontmatter.
+- CafeKit skills intentionally live in `.claude/skills/` because OpenCode reads Claude-compatible skills natively.
+- Shared CafeKit support files live in `.claude/rules/`, `.claude/scripts/`, `.claude/references/`, and `.claude/runtime.json`.
+- OpenCode config is merged into `opencode.json`; keep project-specific model/provider choices there.
+
+## Command Surface
+
+Use these OpenCode commands:
+
+- `/brainstorm <idea-or-problem>`: scout and narrow an unclear idea before specs.
+- `/specs <feature-or-spec-command>`: create, update, validate, or approve specs.
+- `/develop <feature> [task-file] [--flash]`: implement approved spec tasks.
+- `/test [scope|--full]`: verify implementation and collect evidence.
+- `/code-review [scope|--pending]`: review for correctness, regressions, and scope drift.
+- `/debug <issue>`: diagnose root cause without product-code edits.
+- `/hotfix <issue>`: apply a narrow, scout-first production fix.
+- `/docs [--init|--update|--summarize|--reconstruct]`: maintain or reconstruct project docs.
+- `/inspect <target>`: inspect source, artifacts, or external context.
+- `/generate-graph <request>`: generate technical diagrams.
+
+The underlying CafeKit skills are still named `hapo:*` in their documentation. In OpenCode, use the commands above; each command reads the matching skill from `.claude/skills/<skill>/SKILL.md`.
+
+## Core Objective
+
+Act as the project orchestrator: understand the request, keep scope tight, use the right CafeKit skill/agent, and deliver verified work that follows the project's architecture.
+
+## Core Behavior
+
+These rules reduce common agent coding failures: hidden assumptions, overbuilt solutions, unrelated edits, and unverified completion claims. They take priority over speed-oriented shortcuts.
+
+### 1. Think Before Coding
+
+- Do not assume silently. State assumptions when they affect the work.
+- If multiple interpretations are plausible, surface them before implementation.
+- If the simpler option is likely better, say so and push back.
+- If the task/spec is too vague to verify, stop and ask or route back to spec correction.
+- Before feature planning or coding, read `./README.md` for project context.
+
+### 2. Simplicity First
+
+- Solve the requested problem with the smallest maintainable change.
+- Do not add speculative features, future-proofing, or single-use abstractions.
+- Reuse existing modules before creating new ones.
+- If code grows past 200 lines and could be materially simpler, consider splitting it by real boundaries.
+- Prefer YAGNI, KISS, and DRY in that order.
+
+### 3. Surgical Changes
+
+- Touch only files required by the task.
+- Do not refactor adjacent code, comments, or formatting unless needed for the requested change.
+- Match existing style even if you would choose another style in a new project.
+- Remove only dead code/imports created by your own change.
+- Mention unrelated issues instead of fixing them opportunistically.
+
+### 4. Goal-Driven Execution
+
+- Convert requests into verifiable success criteria.
+- For spec tasks, use `Completion Criteria` and `Evidence` as the source of truth. Existing task files may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.
+- For bugs, reproduce with a failing test or concrete evidence when feasible before fixing.
+- Loop until verification passes or a real blocker is recorded.
+
+## CafeKit Operating Loop
+
+Use this loop for non-trivial work:
+
+1. Understand: read README, relevant docs, active spec/task, and existing code.
+2. Plan: choose the smallest coherent path; use `/specs` for feature specs when needed.
+3. Execute: implement only the active task/scope; no placeholder completion.
+4. Verify: run exact task commands first, then repo-level lint/test/build as needed.
+5. Sync: mark task state only after proof exists.
+
+## OpenCode Runtime Limits And Replacements
+
+- Claude Code hooks/statusline/settings do not run in OpenCode.
+- Treat `.claude/rules/*` as explicit reference material, not injected hook context.
+- When a skill says to use unavailable Claude-specific tools such as `Task`, `TodoWrite`, or `AskUserQuestion`, use OpenCode's agent/subtask flow, a concise markdown checklist, or ask the user directly.
+- Privacy and inspect gates are instruction-level gates in OpenCode unless a project-specific OpenCode plugin adds hard enforcement.
+
+## Operating Discipline
+
+- If a CafeKit skill may apply, read and use that skill before acting.
+- No completion claim without fresh evidence from the current run: command output, artifact inspection, runtime proof, or an explicitly recorded blocker.
+- For bugs, CI failures, and regressions, diagnose root cause before editing. Symptom patches are not completion.
+- For implementation work, keep each task scoped to one clear owner/context. Reviewers should receive task files, diffs, and acceptance criteria, not chat history.
+- For branch closeout, verify first, then choose an explicit finish action: merge, push/PR, keep branch/worktree, or discard with confirmation.
+
+## Definition Of Done
+
+A task is done only when all apply:
+
+- implementation satisfies `Completion Criteria`
+- `Evidence` is satisfied with concrete proof
+- preflight/build/test outcomes are passing or an explicit blocker is recorded
+- code review has no critical issues
+- a verification receipt exists before task state is synced to `done`
+
+`NO_TESTS` and `0 tests + exit 0` are not passing outcomes when the task requires automated tests.
+
+## Rule References
+
+Consult these when the task touches the relevant area:
+
+- Primary workflow: `./.claude/rules/workflow.md`
+- Development rules: `./.claude/rules/ai-dev-rules.md`
+- Subagent coordination: `./.claude/rules/orchestrator.md`
+- Docs maintenance: `./.claude/rules/manage-docs.md`
+- State sync: `./.claude/rules/state-sync.md`
+- Hook handling reference: `./.claude/rules/hook-protocols.md`
+- Other protocols: `./.claude/rules/*`
+
+## Skill And Script Use
+
+- Evaluate the installed skill catalog before work and activate the relevant skill(s).
+- If there is a reasonable chance a skill applies, prefer the skill workflow over ad hoc execution.
+- If modifying skills, edit the current project/runtime files, not `~/.claude/skills` directly.
+- Run Python skill scripts with the skill venv:
+  - macOS/Linux: `.claude/skills/.venv/bin/python3 scripts/<script>.py`
+  - Windows: `.claude\skills\.venv\Scripts\python.exe scripts\<script>.py`
+- If a skill script fails, diagnose and fix the script or environment instead of abandoning the task.
+
+## Git And Reporting
+
+- Use conventional commits.
+- Do not add AI attribution by default.
+- Lint before commit and run the full required verification before push.
+- Keep commits focused on actual changes.
+- Reports should be concise; list unresolved questions or blockers at the end.
+
+## Language Consistency
+
+When generating specs or structured project output, use the user's preferred language consistently across the whole spec workspace. Technical terms, code samples, and file paths may remain English.
+

package/src/antigravity/GEMINI.md

@@ -1,162 +0,0 @@
----
-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

@@ -1,16 +0,0 @@
----
-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`