@haposoft/cafekit 0.9.0 → 0.9.2

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.2-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.2",
   "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/hooks/state.cjs

@@ -26,6 +26,8 @@ try {
 
   const EXPIRY_DAYS = 7;
   const MAX_ARCHIVES = 5;
+  const MAX_AGENT_SECTIONS = 3;
+  const MAX_MODIFIED_FILES_DISPLAY = 5;
   const TRACKED_POST_TOOL_EVENTS = new Set(['Task', 'TaskCreate', 'TaskUpdate', 'TodoWrite']);
 
   function stateDir(cwd) {
@@ -126,7 +128,7 @@ try {
       }).trim();
 
       if (diff) {
-        data.modifiedFiles = diff.split('\n').slice(0, 20);
+        data.modifiedFiles = diff.split('\n').slice(0, MAX_MODIFIED_FILES_DISPLAY);
       }
     } catch {
       // fail-open
@@ -157,27 +159,40 @@ try {
   }
 
   function buildAgentSection(data) {
-    const agentType = data.agent_type || 'unknown';
+    const agentType = data.agent_type || '';
+    if (!agentType || agentType === 'unknown') return '';
     const time = new Date().toISOString().slice(11, 19);
     return `\n## Agent Result: ${agentType} (${time})\n- Completed at ${time}\n`;
   }
 
+  function takeRecentAgentSections(sections) {
+    if (!Array.isArray(sections) || sections.length <= MAX_AGENT_SECTIONS) return sections || [];
+    return sections.slice(-MAX_AGENT_SECTIONS);
+  }
+
   function mergeAgentSections(existing, content) {
     if (!existing) return content;
 
     const agentSections = existing.match(/## Agent Result:.+?(?=\n## |$)/gs);
     if (!agentSections) return content;
 
+    const kept = takeRecentAgentSections(agentSections);
     const marker = '\n## Key Files Modified';
     if (content.includes(marker)) {
-      return content.replace(marker, `\n${agentSections.join('\n')}${marker}`);
+      return content.replace(marker, `\n${kept.join('\n')}${marker}`);
     }
 
-    return `${content.trimEnd()}\n\n${agentSections.join('\n')}\n`;
+    return `${content.trimEnd()}\n\n${kept.join('\n')}\n`;
   }
 
   function appendAgentSection(existing, agentSection) {
     if (!existing) return agentSection.trimStart();
+    if (!agentSection) {
+      const sections = existing.match(/## Agent Result:.+?(?=\n## |$)/gs) || [];
+      if (sections.length <= MAX_AGENT_SECTIONS) return existing;
+      const kept = takeRecentAgentSections(sections);
+      return existing.replace(/(## Agent Result:.+?(?=\n## |$))+/gs, kept.join('\n'));
+    }
 
     const marker = '\n## Key Files Modified';
     if (existing.includes(marker)) {
@@ -226,8 +241,10 @@ try {
     }
 
     if (event === 'SubagentStop') {
-      const file = path.join(dir, 'latest.md');
       const agentSection = buildAgentSection(data);
+      if (!agentSection) process.exit(0);
+
+      const file = path.join(dir, 'latest.md');
       const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
       const updated = existing
         ? appendAgentSection(existing, agentSection)

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/brainstorm/SKILL.md

@@ -69,17 +69,30 @@ Leverage these specific tools or sub-agents to execute the workflow effectively:
 - `brainstormer`: Call only for medium/high-complexity architecture trade-offs.
 - **Ecosystem Swarm (`SendMessage`):** Call `researcher` (validation), `docs-keeper` (architecture boundaries), or `project-manager` (scope warnings) for deeply complex specs.
 
+## Discovery Question Framework
+
+Load and follow `references/question-framework.md` before the first user-facing discovery question.
+
+Use it to:
+- Generate questions from scout evidence, user intent, exact requirement gaps, matching domain matrices, and risk surfaces.
+- Avoid asking the user to answer technical facts that should be verified from code, docs, or current provider/browser documentation.
+- Prioritize only questions that can materially change architecture, MVP scope, UX, cost/privacy/security, acceptance criteria, or delivery format.
+- Record every user-confirmed decision in a decision register in the final report.
+
+If the framework conflicts with the general "one question at a time" rule, prefer the framework's question budget and batching limits: one high-impact question by default, up to 3 independent questions in one `AskUserQuestion` call only when batching reduces friction without mixing unrelated decisions.
+
 ## Authoritative Workflow
 
 ```mermaid
 flowchart TD
     A["Run /hapo:inspect or narrow scout"] --> B["Summarize codebase findings"]
-    B --> C["Ask one grounded clarifying question"]
-    C --> D{"Exact requirements captured?"}
-    D -->|No| C
+    B --> C["Load question framework"]
+    C --> DQ["Ask highest-impact grounded question"]
+    DQ --> D{"Exact requirements captured?"}
+    D -->|No| DQ
     D -->|Yes| E{"Multiple independent subsystems?"}
     E -->|Yes| F["Decompose into sub-projects"]
-    F --> C
+    F --> DQ
     E -->|No| G{"Medium/high complexity?"}
     G -->|Yes| H["Call brainstormer/researcher/docs-keeper as needed"]
     G -->|No| I["Propose 2-3 approaches"]
@@ -107,10 +120,14 @@ flowchart TD
 
 ### 2. Discovery Phase
 
-- Ask exactly **one question at a time**. Do not stack multiple unrelated questions.
+- Load `references/question-framework.md`.
+- Ask exactly **one high-impact question at a time** by default. Do not stack unrelated questions.
+- You may batch up to 3 independent questions only when each question maps to a different required decision surface and none requires explanation before the user can answer.
 - Prefer multiple-choice options grounded in scout findings.
 - Push vague intent into concrete examples, sample inputs/outputs, or acceptance criteria.
 - Challenge the first proposed solution when the underlying goal suggests a simpler path.
+- Do not ask users to decide technical facts. Research browser/runtime/provider/package facts first; then ask only the product or trade-off decision.
+- Track decisions as you go so the final report can distinguish `User Decision`, `Assumption`, and `Open Question`.
 
 ### 3. Scope Guard
 
@@ -154,7 +171,7 @@ Before passing the completed design to the user for final review, you must inter
 ### 8. Final Handoff & Documentation
 Upon the user's explicit final approval of the sanitized design document:
 1. Generate the final **Design Doc / Summary Report**.
-2. Include: problem statement, exact requirements, evaluated approaches, recommended solution, risks, validation criteria, and next steps.
+2. Include: problem statement, exact requirements, evaluated approaches, recommended solution, risks, validation criteria, decision register, open questions, and next steps.
 3. Invoke `/hapo:specs` with the report context to hand off into CafeKit's structured specification phase.
 4. Optionally update an existing project notes, docs, or report file if the approved design context should be persisted for future work.
 

package/src/claude/skills/brainstorm/references/question-framework.md

@@ -0,0 +1,232 @@
+# Brainstorm Question Framework
+
+Use this reference to decide **what to ask**, **what not to ask**, and **how to record decisions** during `hapo:brainstorm`.
+
+The goal is not to ask many questions. The goal is to ask the smallest set of questions that can materially change the design.
+
+## Source Hierarchy
+
+Generate questions from this hierarchy, in order:
+
+1. **Scout evidence** — repo type, framework, existing modules, docs, specs, plans, runtime config, and constraints.
+2. **User intent** — nouns, verbs, success language, target users, examples, and implied deliverables in the prompt.
+3. **Exact requirement gaps** — expected output, acceptance criteria, scope boundary, non-negotiable constraints, touchpoints.
+4. **Domain matrix** — only domains that actually apply to the request.
+5. **Risk matrix** — security, privacy, cost, runtime limits, provider failure, migration, compliance, maintainability.
+
+Never ask a question that the repository, docs, or trusted technical research can answer directly.
+
+## Ask / Do Not Ask
+
+Ask the user when the answer changes:
+
+- product scope or MVP boundaries
+- target user workflow or UX surface
+- expected output artifact or delivery format
+- acceptance criteria
+- business priority, timeline, or rollout
+- cost, privacy, API-key ownership, external provider choice
+- irreversible workspace action such as renaming/moving/deleting
+- whether to accept a trade-off after you explain it
+
+Do **not** ask the user when the answer is a technical fact you should verify:
+
+- browser or runtime limits
+- package/API compatibility
+- dependency maintenance state
+- security best practice
+- exact syntax for framework config
+- existing code location, schema, endpoint, or convention
+
+If a topic mixes user preference and technical fact, verify the technical facts first, then ask the preference question with those facts included.
+
+## Prioritization
+
+Before asking, score each candidate question:
+
+| Signal | Score |
+|---|---:|
+| Could change architecture, data model, or platform | +3 |
+| Could change MVP scope or exclude a feature | +3 |
+| Could affect cost, privacy, security, or compliance | +3 |
+| Defines observable acceptance criteria | +2 |
+| Defines UX flow or primary user surface | +2 |
+| Can be answered from repo/docs/research | -4 |
+| Merely names an implementation detail with a safe default | -2 |
+
+Ask only the highest-impact question. If several are tied and independent, ask at most 3 in one `AskUserQuestion` batch; otherwise ask one at a time.
+
+## Required Decision Surfaces
+
+Every brainstorm must eventually resolve these surfaces:
+
+| Surface | Question Intent |
+|---|---|
+| Outcome | What does the user expect to exist or happen after the work? |
+| Done | How will the user verify it works? |
+| Scope | What is explicitly not included now? |
+| Constraints | What cannot change: stack, platform, naming, runtime, compatibility, deadline? |
+| Touchpoints | Which existing files/modules/contracts will this affect? |
+
+If any surface is missing, ask a grounded question before proposing architecture.
+
+## Domain Matrix
+
+Use only the domains that match the request.
+
+### Product / UX
+
+Ask when the prompt includes UI, workflow, dashboard, extension, app, or user-facing behavior.
+
+- Primary user: who uses this first?
+- Primary flow: what is the shortest successful path?
+- Surface: page, overlay, sidebar, modal, command, background task?
+- State: loading, empty, error, partial result, retry?
+- Accessibility or localization expectations?
+
+### Browser Extension
+
+Ask when the work involves Chrome, Edge, Firefox, YouTube, DOM injection, content scripts, popup, options page, or browser APIs.
+
+- Target browser/runtime and manifest version?
+- UI surface: content overlay, sidebar, popup, options page, or all?
+- Permissions posture: minimal host permissions or broader convenience?
+- Storage: browser storage, IndexedDB, sync storage, or no persistence?
+- Publishing target: dev-only, Chrome Web Store, enterprise install?
+
+Verify instead of asking:
+
+- Manifest V3 service worker lifetime.
+- Browser-reserved shortcut conflicts.
+- Content script isolated-world vs main-world behavior.
+- Current Chrome API compatibility.
+
+### AI / LLM
+
+Ask when the work involves translation, summarization, agents, prompt output, generation, or provider choice.
+
+- Provider ownership: user API key, app-owned key, proxy, or local model?
+- Provider shape: fixed provider, multi-provider, or custom base URL?
+- Output contract: prose, JSON, markdown, SRT, code, patch?
+- Failure behavior: retry, fallback, partial result, ask user, or stop?
+- Cache policy: never, per session, persistent, or shared?
+- Privacy boundary: what content may leave the browser/server?
+
+Verify instead of asking:
+
+- Whether a provider is Anthropic-compatible vs OpenAI-compatible.
+- Whether a provider supports tool use / JSON schema / streaming.
+- Current API endpoint paths and auth header format.
+
+### Data / Transcript / Documents
+
+Ask when the work transforms documents, captions, data, logs, OCR, audio, video, or legacy code into another artifact.
+
+- Source priority and fallback order?
+- Output format and fidelity level?
+- Confidence / evidence tracking requirement?
+- Missing/unknown handling?
+- Export/import requirements?
+
+### Backend / API / Database
+
+Ask when the work includes server endpoints, persistence, auth, jobs, integrations, or migrations.
+
+- API contract: endpoint, method, request/response shape?
+- Persistence: new table, existing table, no DB?
+- Auth/permission model?
+- Idempotency, retries, and background job behavior?
+- Migration and rollback constraints?
+
+### Docs / Legacy Reconstruction
+
+Ask when the work is documentation, legacy analysis, or requirement reconstruction.
+
+- Scope path/module to reconstruct?
+- Output docs required: overview, requirements, architecture, evidence map, unknowns?
+- Evidence level: observed-only or inferred allowed with confidence?
+- Review gate: who approves the reconstructed docs?
+- Change request follows reconstruction or is separate?
+
+### Release / Packaging
+
+Ask when the work includes publish, store listing, npm release, versioning, or deployment.
+
+- Target release channel?
+- Version bump type?
+- Required checks before publish?
+- Store/listing metadata ownership?
+- Rollback or deprecation plan?
+
+## Question Format
+
+Use `AskUserQuestion` when available.
+
+- Use 2-4 concrete options.
+- Put the recommended option first and label it `(Recommended)`.
+- Include a one-sentence impact description per option.
+- Do not add an explicit "Other" option; the tool supplies it.
+- Avoid abstract labels like "Option A" unless paired with concrete meaning.
+
+Good:
+
+> "Where should transcript fallback live?"
+> - "Defer STT for MVP (Recommended)" — Ships faster; no fragile audio extraction now.
+> - "Browser-only STT" — No backend, but fragile and heavy.
+> - "Companion backend" — More robust, but requires hosting and ops.
+
+Bad:
+
+> "What architecture do you want?"
+
+## Explain Before Asking
+
+When the user cannot reasonably know the answer, first explain the trade-off briefly, then ask.
+
+Use this pattern:
+
+1. State why the decision matters.
+2. Give 2-3 viable options with consequences.
+3. Recommend one.
+4. Ask the user to confirm or override.
+
+Do not force a choice before explaining hidden technical risk.
+
+## Decision Register
+
+Every final brainstorm report must include a decision register.
+
+```markdown
+## Decision Register
+
+| ID | Question | Options Presented | User Decision | Rationale | Impact |
+|---|---|---|---|---|---|
+| D-001 | Where does transcript fallback live? | Defer STT / Browser-only / Backend | Defer STT | Ships MVP safely | Phase 7 becomes graceful fallback |
+```
+
+Rules:
+
+- Record only decisions actually made by the user or explicitly accepted in chat.
+- Do not write "user selected" unless `AskUserQuestion` or direct user text confirms it.
+- If you infer a default, label it as `Assumption`, not `User Decision`.
+- Carry unresolved decisions into `Open Questions`.
+
+## Maximum Question Budget
+
+Default budget:
+
+- Small change: 1-2 questions.
+- Medium feature: 3-6 questions.
+- Large/greenfield/architecture-heavy: 6-10 questions across multiple rounds.
+
+Stop asking when the next question would only refine an implementation detail with a safe default. Propose the design and list remaining assumptions instead.
+
+## Final Self-Check
+
+Before presenting design:
+
+- Did each asked question map to one of the required decision surfaces or domain risks?
+- Did any question ask the user to answer a technical fact that should have been researched?
+- Are all user decisions captured in the decision register?
+- Are assumptions clearly separated from user decisions?
+- Are open questions truly blocking, or can they be deferred?

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 ...`