@haposoft/cafekit 0.7.21 → 0.7.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.21",
+  "version": "0.7.23",
   "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/skills/develop/SKILL.md

@@ -30,7 +30,7 @@ DO NOT write implementation code until an approved spec exists.
 | "No need to scout first" | Coding without knowing the architecture is blind. ALWAYS call `inspect` to scan files. |
 | "Review process is too tedious, let me just finish it myself" | The system needs an audit trail through agents. ALWAYS delegate via `Task` tool. |
 
-## Absolute 4-Step Workflow
+## Absolute Workflow
 
 ```mermaid
 flowchart TD
@@ -40,7 +40,8 @@ flowchart TD
     C --> D[Step 3: Implement Code (god-developer)]
     D --> E[Step 4: Auto-Fix Code Review / Max 3 rounds]
     E -->|Fail (code-auditor)| D
-    E -->|Pass| F[Report Completion]
+    E -->|Pass| F[Step 5: Incremental Docs Sync]
+    F --> G[Report Completion]
 ```
 
 ### Step 1: Initialize & Load Spec
@@ -66,6 +67,12 @@ The moment you finish coding, DO NOT proceed further. Switch to `references/qual
 
 - Only escalate to the user after 3 consecutive failed review rounds.
 
+### Step 5: Incremental Docs Sync
+- After passing the Quality Gate, evaluate if any actual codebase modifications occurred (e.g., check pending files via git status).
+- If files were created or modified: Trigger `docs-keeper` automatically to execute `repomix` and update the global `/docs/` and project logs.
+- **CWD Protocol (CRITICAL):** When spawning `docs-keeper`, you MUST ensure the agent's Current Working Directory (CWD context) is explicitly set to the **Workspace Root**, NOT the inner package directory you were just coding in. Otherwise, `docs-keeper` will search for the root `docs/` folder in the wrong place and crash.
+- Do NOT skip this step! The user explicitly requires documentation to be synced immediately after every `/hapo:develop` action, overriding the default Phase 3-only rule.
+
 ---
 ## Attached References
 - `references/quality-gate.md` - Rules for the Code Review loop.

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

@@ -120,7 +120,7 @@ flowchart TD
     K --> L
     L --> M["Step 5: Requirements — write EARS"]
     M --> N{Need deep research?}
-    N -->|Yes| O["Research: researchers + scout + docs"]
+    N -->|Yes| O["Research: researchers + inspector + docs"]
     O --> P["Write research.md"]
     N -->|No| P
     P --> Q["Step 6: Design — pick discovery mode"]
@@ -240,6 +240,7 @@ tasks/
 - If a requirement has only 1 natural task, create 1 file (no forced splitting)
 - If a requirement has many acceptance criteria spanning different concerns → split into multiple task files
 - After generating all tasks: verify **every requirement ID** appears as primary in at least one task file — gaps = failure
+- **Legacy Protection:** If the `research.md` identified existing codebase files or tests that will be broken (Blast Radius), you MUST generate explicitly tasked files (e.g., `task-R5-01-update-legacy-tests.md`) to fix those breakages. Do not leave broken tests out of scope.
 
 **Dependency ordering:** Tasks within the same requirement are ordered by natural implementation flow. Cross-requirement dependencies use `Dependencies:` field referencing other task file names.
 
@@ -349,7 +350,7 @@ specs/
     │   └── ...
     └── reports/               # Auxiliary reports
         ├── researcher-01.md
-        ├── scout-report.md
+        ├── inspect-report.md
         └── red-team-report.md
 ```
 

package/src/claude/skills/specs/references/codebase-analysis.md

@@ -6,7 +6,7 @@ Understand the current codebase before designing solutions — ensure the new sp
 
 ## Skip Conditions
 
-- Already provided with scout reports → skip, use directly
+- Already provided with inspector reports → skip, use directly
 
 ## 4 Mandatory Files to Read First
 
@@ -17,7 +17,12 @@ Understand the current codebase before designing solutions — ensure the new sp
 | 3 | `./docs/code-standards.md` | Coding conventions, language-specific patterns | High |
 | 4 | `./docs/design-guidelines.md` | Design system, branding, UI/UX conventions | If exists |
 
-> If a file doesn't exist → skip it silently. If all are missing → use scout to explore the codebase directly.
+### Validation & Fallback Protocol (MANDATORY)
+1. **Trust but Verify:** If `codebase-summary.md` or `code-standards.md` exists, you MUST verify their technical claims by cross-checking `package.json`, `go.mod`, etc. (e.g., if Docs say Redux but package.json only has Zustand → Flag documentation as STALE in your research).
+2. **The "Blind Flight" Halt:** If ALL 4 mandatory docs are missing in a non-empty repository:
+   - **DO NOT** blindly use `inspector` to scan the whole repo.
+   - **HALT** the spec process immediately.
+   - Ask the User: *"No codebase documentation found. Exploring blind will drain tokens and produce inaccurate specs. Shall I trigger `docs-keeper` or `/hapo:docs` to generate a baseline `codebase-summary.md` first?"*
 
 ## Analysis Activities
 
@@ -27,28 +32,40 @@ Understand the current codebase before designing solutions — ensure the new sp
 - Identify required dependencies
 - Understand build and deployment processes
 
+### 2. Core Data Structures (MANDATORY for Enhancements)
+Before designing any logic, you must identify and read the existing schemas:
+- Tell `inspector` to grep for database schema files (`schema.ts`, `schema.prisma`, entities, migrations).
+- Identify Global State setups (Redux stores, Zustand, React Context).
+- Output the relational impact: How will the new feature alter existing tables or state structures?
+
 ### 2. Pattern Recognition
 - Study existing patterns in codebase
 - Identify conventions and architectural decisions
 - Note consistency in implementation approaches
 - Understand error handling patterns
 
-### 3. Integration Planning
+### 4. Integration Planning
 - Identify how new features integrate with existing architecture
 - Map dependencies between components
 - Understand data flow and state management
 - Consider backward compatibility
 
-### 4. Scout Usage (when needed)
-- Use scout agents for targeted file discovery in large codebases
-- Each scout targets a specific aspect of the task
-- Wait for all scouts to report before analysis
-- Save results to `reports/scout-report.md`
+### 5. Blast Radius & Regression Check
+Write a "Collateral Damage" section in your `research.md`:
+- List EXACTLY which existing files will need to be modified.
+- **Test Invalidation:** Identify which existing `.test.ts` or `.spec.ts` files will break because of these modifications.
+- Ensure the mitigation for these breaking changes is passed downstream to the Task generation phase.
+
+### 6. Inspector Usage (when needed)
+- Use inspector agents for targeted file discovery in large codebases
+- Each inspector targets a specific aspect of the task
+- Wait for all inspectors to report before analysis
+- Save results to `reports/inspect-report.md`
 
 ## Best Practices
 
 - Start with documentation before diving into code
-- Use scouts for targeted file discovery
+- Use inspectors for targeted file discovery
 - Document patterns found for consistency
 - Note any inconsistencies or technical debt
 - Consider impact on existing features

package/src/claude/skills/specs/references/research-strategy.md

@@ -18,7 +18,7 @@ Provide tools and methods to gather necessary information before writing require
 | 3 | **Docs seeker** | Look up framework/package docs from official sources | Need to understand external APIs/libraries, find best practices |
 | 4 | **GitHub analysis** (`gh`) | Read action logs, PRs, issues, discussions | Need context from project history, understand past decisions |
 | 5 | **Repomix remote** (`repomix --remote <url>`) | Generate codebase summary from remote repo | Reference how other repos solve similar problems. *(If not installed, use WebFetch as fallback)* |
-| 6 | **Scout agents** | Search for files across large codebases | Find relevant files faster than grep in large projects |
+| 6 | **Inspector agents** | Search for files across large codebases | Find relevant files faster than grep in large projects |
 | 7 | **Debugger delegation** | Hand off to debugger agent for analysis | Investigate root cause of bugs |
 
 ## Workflow
@@ -32,7 +32,7 @@ Before detailing requirements, list unanswered questions:
 
 ### 2. Pick the Right Tool
 - Framework/API questions → Docs seeker
-- Current codebase questions → Scout agents
+- Current codebase questions → Inspector agents
 - Architecture/approach questions → Researcher agents
 - Complex multi-step reasoning → Sequential thinking
 - Historical decision questions → GitHub analysis
@@ -46,7 +46,7 @@ Before detailing requirements, list unanswered questions:
 ### 4. Record Findings
 - Write to `research.md` using template `templates/research.md`
 - Save researcher reports to `reports/researcher-{NN}.md`
-- Save scout reports to `reports/scout-report.md`
+- Save inspector reports to `reports/inspect-report.md`
 
 ## Best Practices