@haposoft/cafekit 0.7.14 → 0.7.16

package/bin/install.js

@@ -281,7 +281,8 @@ function copyRecursive(src, dest, options = {}) {
       fs.mkdirSync(dest, { recursive: true });
     }
     fs.readdirSync(src).forEach(childItemName => {
-      copyRecursive(path.join(src, childItemName), path.join(dest, childItemName), options);
+      const destItemName = childItemName === 'gitignore' ? '.gitignore' : childItemName;
+      copyRecursive(path.join(src, childItemName), path.join(dest, destItemName), options);
     });
   } else {
     if (fs.existsSync(dest) && !shouldOverwriteManagedFiles) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.14",
+  "version": "0.7.16",
   "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

@@ -6,6 +6,69 @@ This document serves as the primary configuration and instruction manual for Cla
 
 You act as the primary orchestrator for the project. Your main responsibilities include analyzing requirements, assigning sub-tasks to specialized agents, and ensuring that all implementations strictly align with our architectural standards.
 
+## Behavioral Principles
+
+> These principles shape how you approach every task. They take precedence over speed-oriented shortcuts.
+
+### 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+- State assumptions explicitly before implementing. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- Before starting any feature planning or coding, read the `./README.md` to acquire project context.
+
+### 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+- Before generating a new helper or module, check if an existing one can be reused.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated issues, mention them — don't fix them.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+> **These principles are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
 ## Operational Procedures
 
 Always consult the following procedure files to guide your actions:
@@ -21,7 +84,6 @@ Always consult the following procedure files to guide your actions:
 - **Compliance**: You are required to follow all rules specified in `./.claude/rules/ai-dev-rules.md` without exception.
 - **Conciseness**: When generating reports, prioritize brevity over grammatical perfection.
 - **Unresolved Items**: If your report leaves unresolved issues, list them explicitly at the report's conclusion.
-- **Pre-execution Context**: Before starting any feature planning or coding, read the `./README.md` to acquire project context.
 
 ## Git Conventions
 
@@ -62,7 +124,7 @@ When triggering Python scripts located under `.claude/skills/`, you must invoke
 - **Linux & macOS**: `.claude/skills/.venv/bin/python3 scripts/target_script.py`
 - **Windows**: `.claude\skills\.venv\Scripts\python.exe scripts\target_script.py`
 
-*Note: If a skill script throws an error, do not abandon the task. try run with venv. if error again, try fix and run
+*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
 
@@ -76,33 +138,41 @@ When you need to search the internet for information (research, docs lookup, tro
 
 **IMPORTANT**: When the user asks you to find information, research a topic, or investigate anything that requires internet access, you MUST use the Web Search Protocol above. **NEVER** reply with "I cannot search the web". **NEVER** attempt manual `Fetch` or Python-based scraping for search results if `web-search.cjs` provides an answer. Trust the grounding.
 
-## Code Refactoring Triggers
+## Code Quality
 
+### Refactoring Triggers
 - **Size Thresholds**: Automatically consider splitting code files that grow beyond 200 lines.
-- **Existing Abstractions**: Before generating a new helper or module, check if an existing one can be re-used.
 - **Logical Grouping**: Break down files based on logical boundaries (e.g., separating business logic from UI components).
 - **Naming Conventions**: Apply descriptive `kebab-case` naming for files. Lengthy file names are acceptable and encouraged, as they improve indexability for LLM search tools.
 - **Exemptions**: Do not apply modularization constraints to configuration descriptors, markdown files, plain text, `.env` files, or bash scripts.
 
-## Environment Management
-
-- Do not modify `.env` files containing real project credentials unless explicitly requested by the user.
-- Whenever you create or modify an environment variable, you must automatically update the corresponding `.env.example` file.
-
-## Coding & Testing Constraints
-
+### Coding & Testing
 - **Error Handling**: Never swallow errors. Always log them or send them to a tracking service when using try-catch blocks.
 - **Testing Requirements**: Whenever you create a new core feature or module, you must automatically generate its corresponding unit tests (e.g., `[filename].spec.ts` or `[filename].test.ts`).
 - **Styling Rules**: Enforce the use of Tailwind CSS for styling exclusively. Absolutely no inline CSS styles (`style={{...}}`) are permitted.
 
+### Environment Management
+- Do not modify `.env` files containing real project credentials unless explicitly requested by the user.
+- Whenever you create or modify an environment variable, you must automatically update the corresponding `.env.example` file.
+
 ## Communication Persona
 
-- **No Apologies**: Never use phrases like "I'm sorry" or "I apologize." If you make a mistake, simply fix the code directly.
-- **Direct & Concise**: Do not compliment, greet, or provide lengthy summaries. Reply strictly to the technical heart of the matter.
-- **No Unsolicited Explanations**: Unless the user specifically asks "Explain" or "Why", only output the necessary code changes.
+- **No Apologies or Fluff**: Never use phrases like "I'm sorry" or "I apologize." Do not compliment, greet, or provide lengthy pleasantries.
+- **Direct & Actionable**: Reply strictly to the technical heart of the matter. 
+- **Explain Tradeoffs, Not Code**: You MUST state your assumptions, tradeoffs, and clarifying questions before coding (as per *Think Before Coding*). However, **do not** provide unsolicited explanations of *how the code works* after you've written it, unless the user specifically asks "Explain" or "Why". Just output the necessary code changes.
 
 ## Documentation Requirements
 
 The system's core documentation resides in the `./docs` directory. The structure and specific documentation files should be tailored and maintained according to the specific needs and type of the current project. Ensure docs are kept up-to-date as the project evolves.
 
-**MANDATORY DIRECTIVE:** All directives within this document, particularly the **Operational Procedures**, are absolute core constraints. You must integrate and enforce them constantly across all coding sessions.
+## Language Consistency
+
+When generating spec documents (`requirements.md`, `design.md`, `research.md`, `task-*.md`) or any structured output:
+
+- **Detect the user's preferred language** from their conversation, project CLAUDE.md, or global rules. Use that language **consistently** across ALL spec output files within the same project.
+- **Do NOT mix languages** within a single document. If the project language is English, write entirely in English. If Vietnamese, write entirely in Vietnamese.
+- **Technical terms** (e.g., API, CRUD, schema, endpoint) may remain in English regardless of the document language.
+- **Code samples and file paths** are always in English.
+- If the user switches language mid-project, ask which language to standardize on and apply it uniformly to all new and regenerated spec files.
+
+**MANDATORY DIRECTIVE:** All directives within this document, particularly the **Behavioral Principles** and **Operational Procedures**, are absolute core constraints. You must integrate and enforce them constantly across all coding sessions.

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

@@ -2,7 +2,7 @@
 name: spec-maker
 description: "Specification Architect. Creates structured feature specifications from user requirements. Generates spec.json, requirements.md, design.md, research.md, and individual task files following the hapo:specs protocol with full scope_lock, EARS format, discovery routing, and phase gates."
 model: opus
-tools: Glob, Grep, Read, Edit, MultiEdit, Write, Bash, WebFetch, WebSearch, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage, Task(researcher)
+tools: Glob, Grep, Read, Edit, MultiEdit, Write, Bash, WebFetch, WebSearch, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage, Task(researcher), Task(hapo:ai-multimodal), Task(hapo:docx), Task(hapo:pdf), Task(hapo:pptx), Task(hapo:xlsx)
 ---
 
 # Spec Maker — Specification Architect

package/src/claude/gitignore

@@ -0,0 +1,17 @@
+# Environment and Sandbox credentials within .claude
+.env
+.env.*
+!.env.example
+
+# Virtual environments for python scripts (skills)
+skills/.venv/
+.venv/
+venv/
+__pycache__/
+*.pyc
+
+# System generated or logs
+hooks/.logs/
+agent-memory/
+settings.bak.json
+.mcp.json

package/src/claude/hooks/lib/config.cjs

@@ -1,5 +1,5 @@
 /**
- * Shared utilities for ClaudeKit hooks
+ * Shared utilities for CafeKit hooks
  *
  * Contains config loading, path sanitization, and common constants
  * used by session.cjs and other hooks
@@ -300,7 +300,7 @@ function execSafe(cmd, options = {}) {
  * - 'mostRecent': REMOVED - was causing stale plan pollution
  *
  * @param {string} sessionId - Session identifier (optional)
- * @param {Object} config - ClaudeKit config
+ * @param {Object} config - CafeKit config
  * @returns {{ path: string|null, resolvedBy: 'session'|'branch'|null }} Resolution result with tracking
  */
 function resolvePlanPath(sessionId, config) {

package/src/claude/migration-manifest.json

@@ -15,21 +15,24 @@
       "code-review",
       "develop",
       "devops",
+      "docx",
       "frontend-design",
       "frontend-development",
       "git",
       "hotfix",
       "impact-analysis",
       "inspect",
-      "ai-multimodal",
       "mobile-development",
+      "pdf",
+      "pptx",
       "react-best-practices",
       "research",
       "specs",
       "sync",
       "test",
       "ui-ux-pro-max",
-      "web-testing"
+      "web-testing",
+      "xlsx"
     ]
   },
   "agents": {

package/src/claude/skills/docx/LICENSE.txt

@@ -0,0 +1,30 @@
+© 2025 Anthropic, PBC. All rights reserved.
+
+LICENSE: Use of these materials (including all code, prompts, assets, files,
+and other components of this Skill) is governed by your agreement with
+Anthropic regarding use of Anthropic's services. If no separate agreement
+exists, use is governed by Anthropic's Consumer Terms of Service or
+Commercial Terms of Service, as applicable:
+https://www.anthropic.com/legal/consumer-terms
+https://www.anthropic.com/legal/commercial-terms
+Your applicable agreement is referred to as the "Agreement." "Services" are
+as defined in the Agreement.
+
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the
+contrary, users may not:
+
+- Extract these materials from the Services or retain copies of these
+  materials outside the Services
+- Reproduce or copy these materials, except for temporary copies created
+  automatically during authorized use of the Services
+- Create derivative works based on these materials
+- Distribute, sublicense, or transfer these materials to any third party
+- Make, offer to sell, sell, or import any inventions embodied in these
+  materials
+- Reverse engineer, decompile, or disassemble these materials
+
+The receipt, viewing, or possession of these materials does not convey or
+imply any license or right beyond those expressly granted above.
+
+Anthropic retains all right, title, and interest in these materials,
+including all copyrights, patents, and other intellectual property rights.

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

@@ -0,0 +1,200 @@
+---
+name: hapo:docx
+description: Create, edit, analyze .docx Word documents. Use for document creation, tracked changes, comments, formatting preservation, text extraction, template modification.
+license: Proprietary. LICENSE.txt has complete terms
+metadata:
+  author: haposoft
+  version: "1.0.0"
+---
+
+# DOCX creation, editing, and analysis
+
+## Overview
+
+A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
+
+## Workflow Decision Tree
+
+### Reading/Analyzing Content
+Use "Text extraction" or "Raw XML access" sections below
+
+### Creating New Document
+Use "Creating a new Word document" workflow
+
+### Editing Existing Document
+- **Your own document + simple changes**
+  Use "Basic OOXML editing" workflow
+
+- **Someone else's document**
+  Use **"Redlining workflow"** (recommended default)
+
+- **Legal, academic, business, or government docs**
+  Use **"Redlining workflow"** (required)
+
+## Reading and analyzing content
+
+### Text extraction
+If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:
+
+```bash
+# Convert document to markdown with tracked changes
+pandoc --track-changes=all path-to-file.docx -o output.md
+# Options: --track-changes=accept/reject/all
+```
+
+### Raw XML access
+You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.
+
+#### Unpacking a file
+`python ooxml/scripts/unpack.py <office_file> <output_directory>`
+
+#### Key file structures
+* `word/document.xml` - Main document contents
+* `word/comments.xml` - Comments referenced in document.xml
+* `word/media/` - Embedded images and media files
+* Tracked changes use `<w:ins>` (insertions) and `<w:del>` (deletions) tags
+
+## Creating a new Word document
+
+When creating a new Word document from scratch, use **docx-js**, which allows you to create Word documents using JavaScript/TypeScript.
+
+### Workflow
+1. **MANDATORY - READ ENTIRE FILE**: Read [`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
+2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
+3. Export as .docx using Packer.toBuffer()
+
+## Editing an existing Word document
+
+When editing an existing Word document, use the **Document library** (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.
+
+### Workflow
+1. **MANDATORY - READ ENTIRE FILE**: Read [`ooxml.md`](ooxml.md) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for the Document library API and XML patterns for directly editing document files.
+2. Unpack the document: `python ooxml/scripts/unpack.py <office_file> <output_directory>`
+3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md)
+4. Pack the final document: `python ooxml/scripts/pack.py <input_directory> <office_file>`
+
+The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.
+
+## Redlining workflow for document review
+
+This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. **CRITICAL**: For complete tracked changes, you must implement ALL changes systematically.
+
+**Batching Strategy**: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.
+
+**Principle: Minimal, Precise Edits**
+When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the `<w:r>` element from the original and reusing it.
+
+Example - Changing "30 days" to "60 days" in a sentence:
+```python
+# BAD - Replaces entire sentence
+'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'
+
+# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
+'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'
+```
+
+### Tracked changes workflow
+
+1. **Get markdown representation**: Convert document to markdown with tracked changes preserved:
+   ```bash
+   pandoc --track-changes=all path-to-file.docx -o current.md
+   ```
+
+2. **Identify and group changes**: Review the document and identify ALL changes needed, organizing them into logical batches:
+
+   **Location methods** (for finding changes in XML):
+   - Section/heading numbers (e.g., "Section 3.2", "Article IV")
+   - Paragraph identifiers if numbered
+   - Grep patterns with unique surrounding text
+   - Document structure (e.g., "first paragraph", "signature block")
+   - **DO NOT use markdown line numbers** - they don't map to XML structure
+
+   **Batch organization** (group 3-10 related changes per batch):
+   - By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
+   - By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
+   - By complexity: Start with simple text replacements, then tackle complex structural changes
+   - Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"
+
+3. **Read documentation and unpack**:
+   - **MANDATORY - READ ENTIRE FILE**: Read [`ooxml.md`](ooxml.md) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
+   - **Unpack the document**: `python ooxml/scripts/unpack.py <file.docx> <dir>`
+   - **Note the suggested RSID**: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.
+
+4. **Implement changes in batches**: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:
+   - Makes debugging easier (smaller batch = easier to isolate errors)
+   - Allows incremental progress
+   - Maintains efficiency (batch size of 3-10 changes works well)
+
+   **Suggested batch groupings:**
+   - By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")
+   - By change type (e.g., "Date changes", "Party name updates", "Legal term replacements")
+   - By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document")
+
+   For each batch of related changes:
+
+   **a. Map text to XML**: Grep for text in `word/document.xml` to verify how text is split across `<w:r>` elements.
+
+   **b. Create and run script**: Use `get_node` to find nodes, implement changes, then `doc.save()`. See **"Document Library"** section in ooxml.md for patterns.
+
+   **Note**: Always grep `word/document.xml` immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run.
+
+5. **Pack the document**: After all batches are complete, convert the unpacked directory back to .docx:
+   ```bash
+   python ooxml/scripts/pack.py unpacked reviewed-document.docx
+   ```
+
+6. **Final verification**: Do a comprehensive check of the complete document:
+   - Convert final document to markdown:
+     ```bash
+     pandoc --track-changes=all reviewed-document.docx -o verification.md
+     ```
+   - Verify ALL changes were applied correctly:
+     ```bash
+     grep "original phrase" verification.md  # Should NOT find it
+     grep "replacement phrase" verification.md  # Should find it
+     ```
+   - Check that no unintended changes were introduced
+
+
+## Converting Documents to Images
+
+To visually analyze Word documents, convert them to images using a two-step process:
+
+1. **Convert DOCX to PDF**:
+   ```bash
+   soffice --headless --convert-to pdf document.docx
+   ```
+
+2. **Convert PDF pages to JPEG images**:
+   ```bash
+   pdftoppm -jpeg -r 150 document.pdf page
+   ```
+   This creates files like `page-1.jpg`, `page-2.jpg`, etc.
+
+Options:
+- `-r 150`: Sets resolution to 150 DPI (adjust for quality/size balance)
+- `-jpeg`: Output JPEG format (use `-png` for PNG if preferred)
+- `-f N`: First page to convert (e.g., `-f 2` starts from page 2)
+- `-l N`: Last page to convert (e.g., `-l 5` stops at page 5)
+- `page`: Prefix for output files
+
+Example for specific range:
+```bash
+pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5
+```
+
+## Code Style Guidelines
+**IMPORTANT**: When generating code for DOCX operations:
+- Write concise code
+- Avoid verbose variable names and redundant operations
+- Avoid unnecessary print statements
+
+## Dependencies
+
+Required dependencies (install if not available):
+
+- **pandoc**: `sudo apt-get install pandoc` (for text extraction)
+- **docx**: `npm install -g docx` (for creating new documents)
+- **LibreOffice**: `sudo apt-get install libreoffice` (for PDF conversion)
+- **Poppler**: `sudo apt-get install poppler-utils` (for pdftoppm to convert PDF to images)
+- **defusedxml**: `pip install defusedxml` (for secure XML parsing)