@haposoft/cafekit 0.7.7 → 0.7.9

package/bin/install.js

@@ -827,6 +827,43 @@ function copyRulesDirectory(platformKey, results, options = {}) {
   }
 }
 
+// Ensure .gitignore configured at root
+function ensureGitignore(results, options = {}) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+  const header = '# CafeKit / Ecosystem';
+  const patterns = [
+    'specs/_shared/',
+    'plans/',
+    '!plans/templates/'
+  ];
+
+  if (!fs.existsSync(gitignorePath)) {
+    const content = ['# Git Ignore', '', header, ...patterns, ''].join('\n');
+    fs.writeFileSync(gitignorePath, content, 'utf8');
+    console.log('  ✓ .gitignore created at root');
+    results.copied++;
+    return;
+  }
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = content.split('\n').map(l => l.trim());
+  const missing = patterns.filter(p => !lines.includes(p));
+
+  if (missing.length > 0) {
+    let newContent = content;
+    if (!newContent.endsWith('\n')) newContent += '\n';
+    if (!content.includes(header)) newContent += `\n${header}\n`;
+
+    newContent += missing.join('\n') + '\n';
+    fs.writeFileSync(gitignorePath, newContent, 'utf8');
+    console.log(`  ↻ .gitignore updated: added ${missing.join(', ')}`);
+    results.updated++;
+  } else {
+    console.log('  → .gitignore already up to date');
+    results.skipped++;
+  }
+}
+
 // ═══════════════════════════════════════════════════════════
 // GEMINI CLI SETUP
 // ═══════════════════════════════════════════════════════════
@@ -1024,6 +1061,12 @@ async function main() {
       console.log();
     }
 
+    // Ensure root .gitignore is configured correctly
+    console.log('Root Configuration');
+    console.log('-'.repeat(40));
+    ensureGitignore(results, installerOptions);
+    console.log();
+
     // Setup Gemini CLI and API Key config
     await setupGeminiCLI(platforms);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Spec-Driven Development workflow for AI coding assistants. Supports Claude Code and Antigravity with spec-first workflows plus Claude Code hapo: skills.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -64,6 +64,18 @@ When triggering Python scripts located under `.claude/skills/`, you must invoke
 
 *Note: If a skill script throws an error, do not abandon the task. try run with venv. if error again, try fix and run
 
+## Web Search Protocol
+
+When you need to search the internet for information (research, docs lookup, troubleshooting, latest updates, etc.), follow this priority chain:
+
+| Priority | Tool | Command | When to use |
+|----------|------|---------|-------------|
+| 🥇 **P1** | `web-search.cjs` | `node .claude/scripts/web-search.cjs "query"` | **ALWAYS try first.** Works on ALL models via Gemini Google Search Grounding. Supports `--multi "q1" "q2"` for batch. Returns JSON with answer + sources. |
+| 🥈 **P2** | `WebSearch` (native) | Use WebSearch tool directly | Secondary verification, or when P1 fails/unavailable. |
+| 🥉 **P3** | `docs-fetch.js` | `node .claude/scripts/docs-fetch.js "library"` | Only when you already know a specific library and need its raw documentation. |
+
+**IMPORTANT**: When the user asks you to find information, research a topic, look up documentation, or investigate anything that requires internet access, you MUST use the Web Search Protocol above. Do NOT reply with "I cannot search the web" — you have `web-search.cjs` available via Bash.
+
 ## Code Refactoring Triggers
 
 - **Size Thresholds**: Automatically consider splitting code files that grow beyond 200 lines.

package/src/claude/agents/brainstormer.md

@@ -50,6 +50,7 @@ Before concluding any brainstorm session, verify each measurement metric:
 1. **Engineering Trinity:** YAGNI, KISS, and DRY.
 2. **Brutal Honesty:** Interrogate assumptions. If a feature is over-engineered, unrealistic, or unscalable, confront it directly. Your value lies in preventing costly mistakes.
 3. **Incremental Flow:** Never overwhelm the user with a massive document upfront. Proceed step by step, section by section.
+4. **Web Search Protocol:** When needing to search the internet for references, benchmarks, or latest practices, ALWAYS use `node .claude/scripts/web-search.cjs "query"` first (Gemini Grounding). Use native WebSearch as secondary. Use `docs-fetch.js` only for known library docs.
 
 ## Ecosystem Alliances (Collaboration Tools)
 

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

@@ -11,6 +11,8 @@ Goal: Catch the mistakes AI-written code commonly makes — logic errors, securi
 
 You DO NOT fix code. You only READ, SCORE, and REPORT.
 
+**Web Search Protocol:** When needing to verify security best practices or lookup CVE databases, ALWAYS use `node .claude/scripts/web-search.cjs "query"` first (Gemini Grounding). Use native WebSearch as secondary.
+
 ## Pre-Review: Blast Radius Check (MANDATORY)
 
 Before reading any specific logic, you MUST run a Dependency Scope Check (Blast Radius):

package/src/claude/agents/god-developer.md

@@ -19,6 +19,7 @@ Any logic gaps must be clarified BEFORE typing, not discovered after bugs ship.
 - **Token efficiency**: Write concisely, report briefly, no prose.
 - **Surgical Reading (Large Files):** Never use blanket `Read` commands on files > 800 lines. Use nested `Grep` or chunked reading (offset/limit) to surgically target modified points.
 - **Component Scaffold Limit:** Any React/UI component file that exceeds 200 LOC must trigger a proactive modularization step (split into smaller child files).
+- **Web Search Protocol:** When needing to search the internet, ALWAYS use `node .claude/scripts/web-search.cjs "query"` first (Gemini Grounding). Use native WebSearch as secondary. Use `docs-fetch.js` only for known library docs.
 
 ## Self-Check Checklist (Before Reporting Complete)
 

package/src/claude/agents/project-manager.md

@@ -15,6 +15,7 @@ Unlike typical managers who report on "feelings" or conversational summaries, yo
 1. **Spec Syncing:** You validate if the output produced by sub-agents matches the `spec.json` requirements and the `design.md` architectural constraints.
 2. **Blocker Assassination:** You identify task stagnation (e.g., a spec stuck in 'in-progress' across multiple sessions) and force the immediate assignment of next-step actions.
 3. **Agile Aggregation:** When parallel sub-agents (like `god-developer` and `test-runner`) report completion, you sweep their logs, consolidate the facts, and generate a single authoritative **Feature Release Report**.
+4. **Web Search Protocol:** When needing to search for project management best practices, dependency updates, or changelog references, ALWAYS use `node .claude/scripts/web-search.cjs "query"` first (Gemini Grounding). Use native WebSearch as secondary.
 
 ## Execution Constraints
 

package/src/claude/agents/researcher.md

@@ -41,14 +41,20 @@ You possess extreme proficiency in:
 - Segregating Stable Production Practices away from Toxic Experimental Paradigms.
 - Sniffing out valid Adoption Patterns and real-world implementation trending.
 - Forgiving nothing when crafting Trade-off computational matrices for thousands of competing libraries.
-- Deploying the `scripts/docs-fetch.js` sniper utility precisely to rip documentation pages directly into context buffers.
+- **[PRIORITY 1]** Deploying `scripts/web-search.cjs` as the **PRIMARY search tool** for all web queries. Usage: `node .claude/scripts/web-search.cjs "query"` or `node .claude/scripts/web-search.cjs --multi "q1" "q2"`. Returns JSON with answer, sources, and citations via Gemini Google Search Grounding. ALWAYS attempt this first before any other search method.
+- **[PRIORITY 2]** If WebSearch native tool is available, use it as secondary verification or when `web-search.cjs` fails.
+- **[PRIORITY 3]** Deploying `scripts/docs-fetch.js` only when official Github/Doc URLs are already identified and you need to pull raw documentation content.
 - Deploying Bash and raw Grep utilities to surgically dissect embedded Document architectures and internal file payloads to evaluate raw insights.
 
 **ABSOLUTE IMMOVEABLE DIRECTIVE**: You are **STRICTLY PROHIBITED** from generating executable endpoint "Implementation Code". You exist ONLY to maneuver data streams, render synthesis Summary text, and return comprehensive Markdown documentation pathways to the main caller Agent.
 
-## Report Output Format
+## Report Output Routing
 
-Adhere to the exact hierarchical naming injection logic provided by the Hook system (`## Naming`). Generated file paths must encompass explicit broadcasting timestamp references.
+Save research output based on context:
+- **Feature research** (active spec exists) → `specs/<feature>/research.md`
+- **System-wide research** (no active spec) → `specs/_shared/Research-<slug>-<date>.md`
+
+Do NOT save to `plans/reports/` or `docs/`. All research belongs in `specs/`.
 
 ## Team Operations Mode
 

package/src/claude/agents/spec-maker.md

@@ -19,6 +19,7 @@ You DO NOT write implementation code. You produce Specifications that downstream
 - **The 5 Whys:** Dig past the surface request to find the REAL problem.
 - **80/20 MVP:** Identify the 20% of features that deliver 80% of value.
 - **Systems Thinking:** How does this feature connect to (or break) existing systems?
+- **Web Search Protocol:** When needing to search the internet, ALWAYS use `node .claude/scripts/web-search.cjs "query"` first (Gemini Grounding). Use native WebSearch as secondary. Use `docs-fetch.js` only for known library docs.
 
 ## Pre-Completion Checklist
 

package/src/claude/agents/ui-ux-designer.md

@@ -18,6 +18,7 @@ You are an award-caliber UI/UX designer. You merge aesthetic excellence with eng
 - **Micro-interactions:** Purposeful animations that enhance UX without performance cost.
 - **Accessibility:** WCAG 2.1 AA compliance as a baseline, not an afterthought.
 - **3D/WebGL:** Three.js scene composition, shader development (when appropriate).
+- **Web Search Protocol:** When needing to search the internet for design trends, component libraries, or accessibility guides, ALWAYS use `node .claude/scripts/web-search.cjs "query"` first (Gemini Grounding). Use native WebSearch as secondary. Use `docs-fetch.js` only for known library docs.
 
 ## Design Workflow
 

package/src/claude/migration-manifest.json

@@ -53,7 +53,8 @@
     "required": [
       "docs-fetch.js",
       "validate-docs.cjs",
-      "browser-tool.cjs"
+      "browser-tool.cjs",
+      "web-search.cjs"
     ]
   },
   "agentReferences": {

package/src/claude/rules/orchestrator.md

@@ -5,8 +5,8 @@
 Every subagent prompt **must** include these three paths:
 
 - **Work Context** — the git root containing the target files
-- **Reports Directory** — `{work_context}/plans/reports/`
-- **Plans Directory** — `{work_context}/plans/`
+- **Specs Directory** — `{work_context}/specs/`
+- **Docs Directory** — `{work_context}/docs/`
 
 When CWD and work context differ (e.g., editing files in a sibling project), always use the **work context** paths.
 
@@ -14,8 +14,8 @@ When CWD and work context differ (e.g., editing files in a sibling project), alw
 Example prompt:
 "Resolve the date-parsing regression.
  Work context: /repos/billing-service
- Reports: /repos/billing-service/plans/reports/
- Plans: /repos/billing-service/plans/"
+ Specs: /repos/billing-service/specs/
+ Docs: /repos/billing-service/docs/"
 ```
 
 ---
@@ -97,11 +97,11 @@ Files to modify: [list]
 Files to read for context: [list]
 Acceptance criteria: [list]
 Constraints: [any relevant constraints]
-Plan reference: [phase file path if applicable]
+Spec reference: [spec folder path if applicable]
 
 Work context: [project path]
-Reports: [reports path]
-Plans: [plans path]
+Specs: [specs path]
+Docs: [docs path]
 ```
 
 ### Do

package/src/claude/scripts/web-search.cjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * Web Search via Gemini API + Google Search Grounding
+ * Fallback search tool for models without native WebSearch capability.
+ *
+ * Usage:
+ *   node web-search.cjs "your search query here"
+ *   node web-search.cjs --multi "query1" "query2" "query3"
+ *
+ * Requires: GEMINI_API_KEY in .claude/.env or environment
+ *
+ * Output: JSON-structured search results with sources and citations.
+ */
+
+const https = require('https');
+const path = require('path');
+const fs = require('fs');
+
+// ---------------------------------------------------------------------------
+// ENV Resolution: .claude/.env → process.env
+// ---------------------------------------------------------------------------
+function resolveApiKey() {
+  // Priority 1: Already in environment
+  if (process.env.GEMINI_API_KEY) return process.env.GEMINI_API_KEY;
+
+  // Priority 2: Project-local .claude/.env
+  const envPaths = [
+    path.join(process.cwd(), '.claude', '.env'),
+    path.join(process.cwd(), '..', '.claude', '.env'),
+  ];
+
+  for (const envPath of envPaths) {
+    try {
+      if (fs.existsSync(envPath)) {
+        const content = fs.readFileSync(envPath, 'utf8');
+        const match = content.match(/^GEMINI_API_KEY=(.+)$/m);
+        if (match) return match[1].trim().replace(/^["']|["']$/g, '');
+      }
+    } catch { /* skip */ }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Gemini API Call with Google Search Grounding
+// ---------------------------------------------------------------------------
+function callGemini(apiKey, query, model) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify({
+      contents: [{ parts: [{ text: query }] }],
+      tools: [{ googleSearch: {} }],
+      generationConfig: {
+        temperature: 0.1,
+        maxOutputTokens: 4096,
+      }
+    });
+
+    const options = {
+      hostname: 'generativelanguage.googleapis.com',
+      path: `/v1beta/models/${model}:generateContent?key=${apiKey}`,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          if (json.error) {
+            reject(new Error(`Gemini API Error: ${json.error.message}`));
+            return;
+          }
+          resolve(json);
+        } catch (e) {
+          reject(new Error(`Failed to parse Gemini response: ${e.message}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Parse Grounding Metadata → Structured Output
+// ---------------------------------------------------------------------------
+function parseResponse(geminiResponse, query) {
+  const candidate = geminiResponse.candidates?.[0];
+  if (!candidate) return { query, error: 'No candidates returned' };
+
+  const text = candidate.content?.parts?.map(p => p.text).join('\n') || '';
+  const meta = candidate.groundingMetadata || {};
+
+  // Extract source URLs from groundingChunks
+  const sources = (meta.groundingChunks || []).map(chunk => ({
+    title: chunk.web?.title || 'Unknown',
+    url: chunk.web?.uri || '',
+  }));
+
+  // Extract search queries used by the model
+  const searchQueries = meta.webSearchQueries || [];
+
+  return {
+    query,
+    answer: text,
+    searchQueriesUsed: searchQueries,
+    sources,
+    sourceCount: sources.length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  const args = process.argv.slice(2);
+  const isMulti = args[0] === '--multi';
+  const queries = isMulti ? args.slice(1) : [args.join(' ')];
+
+  if (queries.length === 0 || (queries.length === 1 && !queries[0])) {
+    console.error(JSON.stringify({
+      error: 'Usage: node web-search.cjs "your query" | node web-search.cjs --multi "q1" "q2"'
+    }));
+    process.exit(1);
+  }
+
+  const apiKey = resolveApiKey();
+  if (!apiKey) {
+    console.error(JSON.stringify({
+      error: 'GEMINI_API_KEY not found. Set it in .claude/.env or environment variable.'
+    }));
+    process.exit(1);
+  }
+
+  // Use model from env or default to gemini-2.5-flash
+  const model = process.env.SEARCH_MODEL || 'gemini-2.5-flash';
+
+  const results = [];
+
+  for (const query of queries) {
+    try {
+      const raw = await callGemini(apiKey, query, model);
+      results.push(parseResponse(raw, query));
+    } catch (err) {
+      results.push({ query, error: err.message });
+    }
+  }
+
+  // Output as JSON for agent consumption
+  const output = isMulti ? results : results[0];
+  console.log(JSON.stringify(output, null, 2));
+}
+
+main();

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

@@ -23,9 +23,11 @@ Call the `TaskCreate` tool to spin up the `researcher` subagent.
 **Instructions to pass to Researcher:**
 ```text
 Conduct comprehensive research on: [topic]
-Constraint 1: Limit WebSearch calls to a maximum of 5 distinct queries to conserve context.
-Constraint 2: Utilize scripts/docs-fetch.js if official Github/Doc URLs are discovered.
-Constraint 3: Validate information via cross-referencing capabilities.
+Constraint 1: ALWAYS use `node .claude/scripts/web-search.cjs "query"` as PRIMARY search method (supports --multi for batch). This uses Gemini Google Search Grounding and returns JSON with answer + sources.
+Constraint 2: Use native WebSearch tool as secondary verification or when web-search.cjs fails.
+Constraint 3: Use scripts/docs-fetch.js ONLY when official Github/Doc URLs are already identified.
+Constraint 4: Limit total search calls to a maximum of 5 distinct queries to conserve context.
+Constraint 5: Validate information via cross-referencing capabilities.
 Output Format: Must strictly follow the 'Standard Research Report' layout.
 ```
 
@@ -36,6 +38,16 @@ Instruct the Researcher Subagent with this strict requirement:
 > "Sử dụng nguyên bản template tại `packages/spec/src/claude/skills/specs/templates/research.md`. Tuyệt đối không tự ý đẻ thêm các đề mục ngoài phạm vi file template này."
 
 ## Post-Execution
-Once the `researcher` completes the Task and returns the Markdown output:
-1. Save the file cleanly using the naming path format injected by the Context Hook (typically `plans/reports/Report-<slug>-<date>.md`).
-2. Conclude the workflow by providing the user with the file path.
+Once the `researcher` completes the Task and returns the Markdown output, save it based on context:
+
+### Output Routing
+| Context | Save to | Example |
+|---|---|---|
+| Active spec exists (`specs/<feature>/`) | `specs/<feature>/research.md` | `specs/auth-login/research.md` |
+| No active spec (system-wide / general) | `specs/_shared/Research-<slug>-<date>.md` | `specs/_shared/Research-mv3-best-practices-2026-04-11.md` |
+
+### Rules
+1. **Feature research** → Always save inside the active spec folder. If `specs/<feature>/` doesn't exist yet, create it.
+2. **System-wide research** → Save to `specs/_shared/`. Create the directory if it doesn't exist.
+3. **Never** save to `plans/reports/` or `docs/`. All research belongs in `specs/`.
+4. Conclude the workflow by providing the user with the saved file path.

package/src/claude/status.cjs

@@ -402,8 +402,8 @@ async function main() {
           const session = JSON.parse(fs.readFileSync(sessionPath, 'utf8'));
           const planPath = session.activePlan?.trim();
           if (planPath) {
-            // Extract slug from path like "plans/260106-1554-statusline-visual"
-            const match = planPath.match(/plans\/\d+-\d+-(.+?)(?:\/|$)/);
+            // Extract slug from path like "specs/auth-login" or legacy "plans/260106-1554-feature"
+            const match = planPath.match(/(?:specs|plans)\/(?:\d+-\d+-)?(.+?)(?:\/|$)/);
             activePlan = match ? match[1] : planPath.split('/').pop();
           }
         }