@haposoft/cafekit 0.9.0 → 0.9.1

package/README.md

@@ -2,7 +2,7 @@
 
 > Claude Code-first spec-driven workflow and runtime bundle for AI coding assistants.
 
-[![Version](https://img.shields.io/badge/version-0.9.0-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.9.1-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Primary-orange.svg)](https://claude.ai/code)
 
@@ -11,7 +11,7 @@
 CafeKit installs a structured workflow so an AI coding agent can move cleanly from:
 
 ```text
-Idea -> QS when unclear -> Brainstorm -> Spec -> Design -> Task Files -> Implementation -> Test -> Review
+Question -> Question answer -> Brainstorm -> Spec -> Design -> Task Files -> Implementation -> Test -> Review
 ```
 
 Claude Code install support:
@@ -102,7 +102,7 @@ cat .opencode/cafekit.json
 
 CafeKit ships many skills, but the main release surface is:
 
-- `/hapo:qs <request-or-context> [--batch|--spec-ready|--stakeholder]`: clarify missing decisions, acceptance criteria, scope, constraints, and next workflow readiness
+- `/hapo:question <question> [--repo|--web|--both|--brief|--deep]`: answer questions using repo evidence first, then external/current sources when local evidence is insufficient
 - `/hapo:brainstorm <idea-or-problem>`: scout the repo, clarify exact requirements, compare approaches, and hand off to specs
 - `/hapo:specs <feature-description>`: create or resume a structured spec workflow
 - `/hapo:develop <feature-name>`: implement from approved spec artifacts
@@ -126,7 +126,7 @@ node .claude/scripts/generate-skill-catalog.cjs --skills
 Claude Code:
 
 ```bash
-/hapo:qs "What is still unclear before the Google Meet transcript extension spec?" --spec-ready
+/hapo:question "Which files define the current CafeKit install/runtime behavior?" --repo
 /hapo:brainstorm Explore approaches for a Google Meet transcript extension
 /hapo:specs Build a Google Meet transcript extension with AI summaries
 /hapo:develop meet-transcript-mvp
@@ -137,7 +137,7 @@ Claude Code:
 OpenCode uses the generated command names without the Claude `hapo:` prefix:
 
 ```bash
-/qs "What is still unclear before the Google Meet transcript extension spec?" --spec-ready
+/question "Which files define the current CafeKit install/runtime behavior?" --repo
 /brainstorm Explore approaches for a Google Meet transcript extension
 /specs Build a Google Meet transcript extension with AI summaries
 /develop meet-transcript-mvp

package/bin/lib/opencode-install.js

@@ -32,11 +32,11 @@ const OPENCODE_COMMAND_TEMPLATES = [
     description: 'Explore and narrow an idea before writing a CafeKit spec.'
   },
   {
-    fileName: 'qs.md',
-    skillName: 'qs',
-    agent: 'brainstormer',
+    fileName: 'question.md',
+    skillName: 'question',
+    agent: 'inspector',
     subtask: true,
-    description: 'Clarify requirements, scope, acceptance criteria, and workflow readiness.'
+    description: 'Answer questions using repo evidence first, then external sources when needed.'
   },
   {
     fileName: 'specs.md',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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/claude/CLAUDE.md

@@ -15,7 +15,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 - 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, use `/hapo:qs` or ask one grounded clarification before planning.
+- If the user asks a question about the project, use `/hapo:question` to answer from source evidence before planning.
 - Before feature planning or coding, read `./README.md` for project context.
 
 ### 2. Simplicity First
@@ -46,7 +46,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 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 `/hapo:qs` when requirements are unclear and `/hapo:specs` for feature specs when ready.
+2. **Plan** — choose the smallest coherent path; use `/hapo:question` for evidence-backed project questions and `/hapo:specs` for feature specs when ready.
 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.

package/src/claude/migration-manifest.json

@@ -27,7 +27,7 @@
       "mobile-development",
       "pdf",
       "pptx",
-      "qs",
+      "question",
       "react-best-practices",
       "research",
       "specs",

package/src/claude/rules/skill-domain-routing.md

@@ -29,7 +29,7 @@ User wants to...
 
 ```text
 User wants to...
-├── clarify missing requirements or acceptance criteria   -> /hapo:qs
+├── answer questions from source code/docs/specs/config    -> /hapo:question
 ├── find files, locate code, scan project structure       -> /hapo:inspect
 ├── diagnose an error or failing check                    -> /hapo:debug
 ├── understand possible side effects                      -> /hapo:impact-analysis
@@ -42,7 +42,7 @@ Local source truth comes from `/hapo:inspect`; external/current knowledge comes
 
 ```text
 User wants to...
-├── prepare stakeholder/customer questions before docs     -> /hapo:qs --batch
+├── ask/answer documentation questions from source         -> /hapo:question
 ├── create missing project docs                           -> /hapo:docs --init
 ├── update docs after source changes                      -> /hapo:docs --update
 ├── summarize codebase quickly                            -> /hapo:docs --summarize

package/src/claude/rules/skill-workflow-routing.md

@@ -7,12 +7,13 @@ Do not inject or force a skill when the user explicitly asks for a direct answer
 ## Core Specification Workflow
 
 ```text
-/hapo:qs -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
+/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
 ```
 
 | User intent | Suggested start |
 |---|---|
-| vague request, missing acceptance criteria, unclear scope, stakeholder questions | `/hapo:qs` |
+| ask about source code, docs, specs, config, dependencies, or external/current technical facts | `/hapo:question` |
+| vague request, missing acceptance criteria, unclear scope, stakeholder questions | ask one clarification or use `/hapo:brainstorm` |
 | unclear idea, possible approaches, scope tradeoffs | `/hapo:brainstorm` |
 | create requirements, design, task breakdown, validate spec | `/hapo:specs` |
 | implement an approved spec or a specific task file | `/hapo:develop` |
@@ -82,5 +83,6 @@ Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local sourc
 - Add a secondary skill only when it materially changes execution.
 - Prefer explicit user commands over this table.
 - If two workflows conflict, ask one concise clarification.
-- If missing information blocks workflow selection, use `/hapo:qs` before choosing brainstorm/specs/develop.
+- If the user asks a factual or project question before workflow selection, use `/hapo:question`.
+- If missing information blocks workflow selection, ask one concise clarification or use `/hapo:brainstorm`.
 - If the user asks to "fix" and root cause is unknown, start with `/hapo:debug` unless the issue is trivial and local.

package/src/claude/skills/question/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: hapo:question
+description: "Answer questions with evidence. Use when the user asks about project behavior, source code, specs, docs, configuration, dependencies, or external technical information; inspect the repo first, use internet/current docs when repo evidence is insufficient, and ask back only when the question cannot be answered safely."
+argument-hint: "<question> [--repo|--web|--both|--brief|--deep]"
+version: 1.0.0
+---
+
+# Question Skill
+
+`hapo:question` is an evidence-backed question-answering skill. It answers user questions by checking the local project first, then external/current sources when the repository cannot answer the question.
+
+## Core Stance
+
+- Answer the question; do not turn every question into a spec or planning session.
+- Source-first: prefer README, docs, specs, code, config, tests, logs, and package metadata before assumptions.
+- Use external/current sources when the local repo is missing the answer, the topic is version-sensitive, or the user asks about outside tools, libraries, APIs, laws, pricing, or best practices.
+- Ask back only when the question is too broad, has no target, needs credentials/private context, or any answer would be misleading.
+- Do not edit files, implement code, create specs, or change project state.
+
+<ANSWER-ONLY-GATE>
+Do NOT implement, scaffold, refactor, modify files, generate full specs, or make final architecture decisions.
+The output is an answer, evidence, confidence, and a follow-up only when needed.
+</ANSWER-ONLY-GATE>
+
+## When To Use
+
+Use `hapo:question` when the user asks:
+- "Trong hệ thống này X làm gì?"
+- "Luồng này đang xử lý ở đâu?"
+- "Config/version/package hiện tại là gì?"
+- "Có dùng thư viện/công nghệ/cách làm nào không?"
+- "Requirement/spec này có khớp code không?"
+- "Tool/library/framework này nên dùng thế nào?"
+- "Theo best practice/current docs thì sao?"
+- "Tôi nên hiểu phần này như thế nào?"
+
+Do not use it when:
+- The user asks to implement, fix, debug, test, commit, or publish.
+- The user wants ideation/tradeoff exploration; use `hapo:brainstorm`.
+- The user wants a formal spec; use `hapo:specs`.
+- The user wants full legacy documentation reconstruction; use `hapo:docs --reconstruct`.
+- The user wants root-cause diagnosis for a failure; use `hapo:debug`.
+
+## Modes
+
+- Default: repo-first answer. Use external sources only if local evidence is insufficient.
+- `--repo`: answer from local source only. If not enough evidence, say so and do not use web.
+- `--web`: answer from external/current sources. Still read local context if the question mentions this project.
+- `--both`: explicitly combine local source evidence and external/current evidence.
+- `--brief`: short answer, minimal evidence.
+- `--deep`: broader evidence scan, include trace and tradeoffs.
+
+If modes conflict, prefer the most explicit source mode in this order: `--both`, `--repo`, `--web`, then default. Apply `--brief` or `--deep` as output depth modifiers.
+
+## Workflow
+
+### 1. Classify The Question
+
+Pick one primary answer type:
+
+```text
+source-code behavior | config/version | spec/docs consistency | dependency/library | workflow/process | external/current knowledge | unclear
+```
+
+If `unclear`, ask one focused follow-up with the minimum choices needed.
+
+### 2. Gather Evidence
+
+Repo evidence priority:
+1. `README.md`, `AGENTS.md`, `CLAUDE.md`
+2. relevant `docs/`, `specs/`, `.claude/`, `.opencode/`
+3. source files, tests, scripts, package manifests, config files
+4. git history only when the question asks about changes or provenance
+
+Use focused search (`rg`, targeted file reads) instead of broad scans. Use `hapo:inspect` when the user asks where something lives or the source surface is unclear.
+
+External evidence:
+- Use external/current docs when repo evidence is absent, stale, or not authoritative.
+- Prefer official docs, standards, source repositories, or primary vendor docs.
+- State clearly when an answer is inferred from external docs rather than confirmed in the repo.
+
+### 3. Decide Whether To Answer Or Ask Back
+
+Answer directly when at least one of these is true:
+- repo evidence answers the question,
+- external/current evidence answers the non-project part,
+- a cautious answer can separate known facts from inference.
+
+Ask back when:
+- the target system/module is not named and multiple targets are plausible,
+- the needed file/source is blocked or private,
+- the question requires business/domain judgment not present in source,
+- the answer would require guessing customer intent,
+- the question bundles multiple unrelated topics.
+
+Ask only one follow-up question. Include 2-3 concrete options if helpful.
+
+### 4. Output Contract
+
+Default output:
+
+```markdown
+**Answer**
+...
+
+**Evidence**
+- `path/to/file`: what it proves
+- External: source name/link, what it proves
+
+**Confidence**
+high | medium | low
+
+**Gaps**
+- ...
+
+**Next**
+...
+```
+
+Use `templates/question.md` when the user asks to save or document the answer.
+
+## Answer Style
+
+- Lead with the answer, not the research process.
+- Use file paths and line references when local evidence is used.
+- Separate "confirmed by source" from "inferred".
+- Keep the answer proportional: concise for simple questions, structured for complex ones.
+- If external sources were used, include source links or names.
+- If no evidence exists, say "không thấy bằng chứng trong source hiện tại" and explain what was checked.
+
+## Examples
+
+### Source Question
+
+```text
+/hapo:question "Trong hệ thống này cafekit dùng file nào để bật/tắt skill routing?"
+```
+
+Expected behavior:
+- read runtime/config/install files,
+- answer with exact config file and relevant keys,
+- say whether it is runtime-driven or hard-coded.
+
+### Mixed Source + Web Question
+
+```text
+/hapo:question "Dự án này đang dùng React version nào, và version đó có còn phù hợp theo best practice hiện tại không?" --both
+```
+
+Expected behavior:
+- read `package.json` or lockfile,
+- check current React docs/release info if needed,
+- separate local version from external recommendation.
+
+### Ask Back
+
+```text
+/hapo:question "Hệ thống này có ổn không?"
+```
+
+Expected behavior:
+- ask one narrowing question because "ổn" could mean architecture, security, performance, UX, tests, or deploy readiness.

package/src/claude/skills/question/templates/question.md

@@ -0,0 +1,32 @@
+# Question Answer: {{TITLE}}
+
+## Question
+{{QUESTION}}
+
+## Answer
+{{ANSWER}}
+
+## Evidence
+| Source | Finding | Confidence |
+|---|---|---|
+| {{SOURCE}} | {{FINDING}} | {{CONFIDENCE}} |
+
+## Source Trace
+- Repo files checked: {{REPO_FILES}}
+- External/current sources checked: {{EXTERNAL_SOURCES}}
+- Search terms or commands: {{SEARCH_TRACE}}
+
+## Confirmed Facts
+- {{FACT}}
+
+## Inferences
+- {{INFERENCE}}
+
+## Gaps / Unknowns
+- {{GAP}}
+
+## Follow-up Question
+{{FOLLOW_UP_OR_NONE}}
+
+## Next
+{{NEXT_STEP}}

package/src/opencode/AGENTS.md

@@ -16,7 +16,7 @@ Primary operating instructions for OpenCode using the CafeKit runtime.
 Use these OpenCode commands:
 
 - `/brainstorm <idea-or-problem>`: scout and narrow an unclear idea before specs.
-- `/qs <request-or-context> [--batch|--spec-ready|--stakeholder]`: clarify requirements, missing decisions, and next workflow readiness.
+- `/question <question> [--repo|--web|--both|--brief|--deep]`: answer questions using repo evidence first, then external/current sources when needed.
 - `/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.
@@ -42,7 +42,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 - 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, use `/qs` or ask one grounded clarification before planning.
+- If the user asks a question about the project, use `/question` to answer from source evidence before planning.
 - Before feature planning or coding, read `./README.md` for project context.
 
 ### 2. Simplicity First
@@ -73,7 +73,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 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 `/qs` when requirements are unclear and `/specs` for feature specs when ready.
+2. Plan: choose the smallest coherent path; use `/question` for evidence-backed project questions and `/specs` for feature specs when ready.
 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.

package/src/claude/skills/qs/SKILL.md

@@ -1,177 +0,0 @@
----
-name: hapo:qs
-description: "Clarify vague requests before planning or implementation. Use when requirements, acceptance criteria, scope, constraints, stakeholder decisions, or next workflow readiness are unclear."
-argument-hint: "<request_or_context> [--batch|--spec-ready|--stakeholder]"
-version: 1.0.0
----
-
-# QS Skill
-
-`hapo:qs` turns unclear intent into answerable questions and a readiness verdict. It is a clarification gate before `hapo:brainstorm`, `hapo:specs`, `hapo:docs --reconstruct`, `hapo:debug`, or `hapo:develop`.
-
-## Core Stance
-
-- Context before questions. Read the useful project/spec/docs/source context before asking.
-- Questions are work products. Make them specific, prioritized, and easy to answer.
-- One thing at a time in interactive mode.
-- Prefer multiple-choice options with a recommended default when the context supports it.
-- Do not design the solution unless the user explicitly moves to `hapo:brainstorm`.
-- Do not create specs or write code from this skill.
-
-<CLARIFICATION-ONLY-GATE>
-Do NOT implement, scaffold, edit product code, generate full specs, or make architecture decisions as final.
-The output is questions, assumptions, readiness, and next-step guidance.
-</CLARIFICATION-ONLY-GATE>
-
-## When To Use
-
-Use `hapo:qs` when:
-- The request is too vague to verify.
-- Acceptance criteria are missing.
-- Scope boundary is unclear.
-- Stakeholder/customer input is needed before specs.
-- The user asks "what should I ask?", "what is missing?", "can this go to specs?", or "is this clear enough?"
-- A spec/task has ambiguity that would make `hapo:develop` risky.
-- A legacy reconstruction or bug report lacks enough scope to start the correct workflow.
-
-Do not use it when:
-- The user asks for a direct factual answer that can be answered safely.
-- The user already gave exact output, acceptance criteria, scope, constraints, and target files.
-- The right action is clearly `hapo:debug`, `hapo:inspect`, `hapo:research`, or `hapo:docs --reconstruct`.
-
-## Modes
-
-- Default interactive mode: ask one highest-value question, then wait.
-- `--batch`: produce a grouped question list for a stakeholder/customer/team.
-- `--spec-ready`: audit whether the request can move to `hapo:specs`.
-- `--stakeholder`: write business-friendly questions with minimal implementation jargon.
-
-If multiple modes appear, use the most restrictive mode in this order: `--spec-ready`, `--batch`, `--stakeholder`, default.
-
-## Workflow
-
-### 1. Context Scout
-
-Read only enough context to make the questions concrete:
-- `README.md`
-- relevant `docs/`
-- relevant `specs/`
-- relevant source files when the request names a feature, module, API, UI, or bug
-
-Use `hapo:inspect` or focused search when the location is unclear. Do not scan the whole repo unless the question is about the whole repo.
-
-### 2. Build The Clarification Map
-
-Create a private map with these fields:
-
-```text
-Known facts:
-Assumptions:
-Missing decisions:
-Blocking unknowns:
-Non-blocking unknowns:
-Possible next workflow:
-```
-
-Classify each unknown:
-- `P0`: blocks correct next action.
-- `P1`: high-risk ambiguity; should answer before implementation.
-- `P2`: useful detail; can defer.
-
-### 3. Ask Or Report
-
-Default interactive mode:
-- Ask exactly one `P0` question.
-- Make it concrete and grounded in observed context.
-- If possible, provide 2-3 options.
-- Put the recommended option first and explain the tradeoff in one sentence.
-
-`--batch` or `--stakeholder`:
-- Produce grouped questions by priority.
-- Keep each question answerable.
-- Include recommended options only when they are justified by context.
-
-`--spec-ready`:
-- Return a readiness checklist and verdict.
-- Do not ask a long question list unless verdict is `not-ready`.
-
-### 4. Readiness Verdict
-
-End with one of:
-- `not-ready`: missing P0 decisions.
-- `brainstorm-ready`: enough to explore solution options, but not enough for specs.
-- `specs-ready`: enough to run `/hapo:specs <request>`.
-- `develop-ready`: an approved spec/task exists and no blocking ambiguity remains.
-
-### 5. Next Step
-
-Suggest exactly one next command:
-- `/hapo:qs ...` when another clarification round is required.
-- `/hapo:brainstorm ...` when design/options are still open.
-- `/hapo:specs ...` when requirements are clear enough.
-- `/hapo:debug ...` when the issue is a bug with unknown root cause.
-- `/hapo:docs --reconstruct <scope>` when the task is legacy/as-is docs.
-- `/hapo:develop <feature>` only when an approved spec/task is already clear.
-
-## Output Formats
-
-### Default Interactive Output
-
-```markdown
-**Context Read**
-- ...
-
-**Known**
-- ...
-
-**Blocking Unknown**
-- P0: ...
-
-**Question**
-...
-
-**Options**
-- A. ... (Recommended) - ...
-- B. ... - ...
-- C. ... - ...
-
-**Readiness**
-not-ready | brainstorm-ready | specs-ready | develop-ready
-
-**Next**
-/hapo:qs ...
-```
-
-### Batch Output
-
-Use `templates/qs.md` when the user asks to save or document the question set.
-
-```markdown
-**Question Set**
-
-**P0 - Must Answer**
-1. ...
-
-**P1 - Should Answer**
-1. ...
-
-**P2 - Can Defer**
-1. ...
-
-**Assumptions To Confirm**
-- ...
-
-**Readiness**
-...
-
-**Next**
-...
-```
-
-## Quality Bar
-
-- Every P0 question must explain what decision it unlocks.
-- No generic "please clarify" questions.
-- No more than one interactive question per response.
-- No implementation plan unless the next command is `hapo:brainstorm` or `hapo:specs`.
-- If no P0/P1 unknown exists, do not invent questions. Say it is ready and name the next command.

package/src/claude/skills/qs/templates/qs.md

@@ -1,30 +0,0 @@
-# Question Set: {{TITLE}}
-
-## Context Read
-- {{CONTEXT_ITEM}}
-
-## Known Facts
-- {{KNOWN_FACT}}
-
-## Assumptions
-- {{ASSUMPTION}}
-
-## P0 - Must Answer
-1. **Question:** {{P0_QUESTION}}
-   - **Why it matters:** {{WHY_IT_MATTERS}}
-   - **Recommended answer:** {{RECOMMENDED_ANSWER}}
-   - **Other options:** {{OTHER_OPTIONS}}
-
-## P1 - Should Answer
-1. **Question:** {{P1_QUESTION}}
-   - **Risk if unanswered:** {{RISK}}
-
-## P2 - Can Defer
-1. **Question:** {{P2_QUESTION}}
-   - **Can defer until:** {{DEFER_POINT}}
-
-## Readiness Verdict
-`not-ready | brainstorm-ready | specs-ready | develop-ready`
-
-## Next Command
-`/hapo:qs ... | /hapo:brainstorm ... | /hapo:specs ... | /hapo:debug ... | /hapo:docs --reconstruct ... | /hapo:develop ...`