@haposoft/cafekit 0.7.16 → 0.7.17

package/package.json

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

@@ -1,4 +1,4 @@
-# AI Agent Directives
+# CLAUDE.md
 
 This document serves as the primary configuration and instruction manual for Claude Code cli (or any AI agent) operating within this codebase.
 

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

@@ -93,10 +93,14 @@ flowchart TD
     E -->|No| F["Ask user 1-2 clarifying questions"]
     F --> D
     E -->|Yes| G["Step 2: Scan specs/ for related specs"]
-    G --> H["Step 3: Assess complexity"]
-    H --> I{Need scope inquiry?}
-    I -->|Yes| J["Ask 3 Scope questions → user picks level"]
-    I -->|No| K["Keep default scope"]
+    G --> H["Step 3: 5-Dimension Assessment"]
+    H --> H1{Risk level?}
+    H1 -->|Chaotic| HX["Exit → redirect to hapo:hotfix"]
+    H1 -->|Complex| H2["Include spike/prototype tasks"]
+    H1 -->|Clear/Complicated| H3{Need scope inquiry?}
+    H2 --> H3
+    H3 -->|Yes| J["Present 5D summary → user picks Expand/Hold/Reduce"]
+    H3 -->|No| K["Keep default scope"]
     J --> L["Step 4: Init — create specs/<feature>/"]
     K --> L
     L --> M["Step 5: Requirements — write EARS"]
@@ -140,9 +144,11 @@ Load: `references/cross-spec-dependency.md`
 
 ### Step 3: Complexity Assessment & Scope Inquiry
 Load: `references/scope-inquiry.md`
-- Apply when task complexity is medium or higher
-- Ask 3 questions: What exists already? What's the minimum change? How complex?
-- User picks: Expand / Hold / Reduce
+- Evaluate the request across **5 dimensions**: Semantic Intent, Implementation Hypothesis, Gap Sizing, Risk/Uncertainty (Cynefin), and Blast Radius
+- If Risk = **Chaotic** → exit spec workflow, redirect to `hapo:hotfix`
+- If Risk = **Complex** → include spike/prototype tasks in the spec
+- If Blast Radius = **Critical Path** → spec MUST include rollback strategy and test coverage requirements
+- User picks scope level: Expand / Hold / Reduce
 - **Skip if:** trivial task (< 20 words, 1 file, user says "just do it")
 
 ### Step 4: Init

package/src/claude/skills/specs/references/scope-inquiry.md

@@ -11,22 +11,42 @@ Skip Scope Inquiry when:
 - Description is under 20 words and unambiguous
 - User signals urgency ("just do it", "quick", etc.)
 
-## 3 Core Questions
+## 5-Dimension Complexity Assessment
 
-### 1. What already exists?
-- Scan codebase for reusable code/patterns
-- Check existing utilities, services, patterns
-- Warn if spec would rebuild something that already exists
+Evaluate complexity across **5 dimensions** to avoid blind spots. A task may be architecturally small but extremely risky, or seemingly simple but with a huge blast radius.
 
-### 2. What's the minimum change?
-- Identify work that can be deferred without affecting the main goal
-- Detect scope creep: nice-to-haves disguised as requirements
-- Ruthlessly separate essential from aspirational
+### Dimension 1: Semantic Intent & Current State
+- What is the core business or technical meaning of the request?
+- How does the system currently behave in this area? What existing patterns, services, or infrastructure can be leveraged?
+- Would this spec rebuild something that already exists? If yes, warn before proceeding.
 
-### 3. How complex is this?
-- If spec affects **> 8 files**: challenge whether fewer files are possible
-- If spec adds **> 2 new classes/services**: demand justification for each
-- If spec needs **> 3 major tasks**: explore consolidation
+### Dimension 2: High-Level Implementation Hypothesis
+- Conceptually, how must the architecture adapt to fulfill the semantic intent?
+- Hypothesize the structural impact: Does this require new database models, API contracts, third-party integrations, or is it strictly localized logic/UI changes?
+
+### Dimension 3: Gap Analysis & Sizing
+Evaluate the gap between Current State and Hypothesis:
+- **Small**: No architectural changes. Extending existing patterns, adding UI components, or patching localized logic.
+- **Medium**: Modifying data flows, adding new API endpoints, or bridging two previously unconnected modules.
+- **Large**: New persistence models, security/auth changes, cross-system migrations, or touching core system foundations.
+- **Scope check**: Separate aspirational goals (nice-to-haves) from what is strictly necessary to bridge the core gap.
+
+### Dimension 4: Risk & Uncertainty (Cynefin-inspired)
+Classify the *knowability* of the solution path:
+- **Clear**: Well-understood problem with established patterns and documentation (e.g., CRUD endpoints, standard auth flows). Proceed with confidence.
+- **Complicated**: Solution exists but requires expert analysis or research (e.g., payment gateway integration, complex query optimization). Plan carefully, may need `researcher` subagent.
+- **Complex**: Outcome is uncertain; solution emerges through experimentation (e.g., AI/ML tuning, novel UX interactions, performance bottleneck with unknown root cause). Requires prototyping or spike tasks before committing to a full spec.
+- **Chaotic**: No clear path; urgent stabilization needed first (e.g., production outage, data corruption). Skip spec workflow entirely — use `hapo:hotfix` instead.
+
+> **Rule**: If Dimension 4 = Complex or Chaotic, flag this to the user immediately. Complex tasks should include explicit spike/prototype tasks in the spec. Chaotic tasks should exit the spec workflow.
+
+### Dimension 5: Dependency & Blast Radius
+Assess how many other parts of the system are affected if this change breaks or behaves unexpectedly:
+- **Isolated**: Change is self-contained within a single module or feature. No shared interfaces touched.
+- **Moderate**: Change touches shared utilities, common components, or API contracts consumed by 2-3 other modules.
+- **Critical Path**: Change affects core infrastructure (auth, data layer, routing, state management) or shared libraries used system-wide. A bug here cascades everywhere.
+
+> **Rule**: If Blast Radius = Critical Path, the spec MUST include rollback strategy and explicit test coverage requirements in the task files.
 
 ## Level Selection
 
@@ -52,8 +72,11 @@ After answering the 3 questions, present via `AskUserQuestion`:
 
 ```
 Scope Inquiry:
-- Existing code: [list reusable code/patterns]
-- Minimum change: [list essential vs deferrable]
-- Complexity: [estimate files, new abstractions, major tasks]
+- Semantic Intent: [Core meaning of request]
+- Hypothesis: [High-level architectural adaptation needed]
+- Gap Size: [Small/Medium/Large] — [reason]
+- Risk Level: [Clear/Complicated/Complex/Chaotic] — [reason]
+- Blast Radius: [Isolated/Moderate/Critical Path] — [affected modules]
+- Minimum Change: [Essential gap vs Niceties]
 - User chose: [Expand / Hold / Reduce]
 ```