@haposoft/cafekit 0.7.16 → 0.7.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.7.16",
+  "version": "0.7.18",
   "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/agents/spec-maker.md

@@ -39,30 +39,14 @@ Init → Requirements → Design → Tasks
 4. **After each phase**: Update `spec.json` with correct `phase`, `progress`, `timestamps`, and approval fields
 
 ### Auto-Approval Behavior
-- When running the full pipeline end-to-end, auto-approve between phases (set `approved: true` before proceeding)
-- When running a single phase, stop and report status after completion
+- When running the full pipeline end-to-end, follow the auto-approval rules defined in `SKILL.md`.
+- When running a single phase, stop and report status after completion.
 
 ## Scope Lock Protocol (MANDATORY)
 
-Every specification MUST have a `scope_lock` in `spec.json`:
-
-```json
-{
-  "scope_lock": {
-    "source": "<original user description>",
-    "in_scope": ["<confirmed capability 1>", "<confirmed capability 2>"],
-    "out_of_scope": ["<excluded capability 1>", "<excluded capability 2>"],
-    "expansion_policy": "requires-user-approval"
-  }
-}
-```
-
-### Scope Lock Rules
-- **Initialize** `scope_lock` during Init phase from user description + clarifying questions
-- **Filter** all requirements against `scope_lock.in_scope` during Requirements phase
-- **Reject** design elements that don't map to in-scope requirement IDs during Design phase
-- **Defer** out-of-scope task candidates during Tasks phase
-- **NEVER** expand scope without explicit user approval
+Every specification MUST govern its scope through the `scope_lock` object in `spec.json`.
+- **NEVER** expand scope without explicit user approval.
+- Follow the rules defined in `SKILL.md` precisely.
 
 ## Requirements Protocol
 
@@ -108,7 +92,7 @@ Before writing `design.md`, select a discovery mode and record the reason:
 ## Task Generation Protocol
 
 ### Task File Structure
-- Create **individual task files**: `tasks/task-01-<slug>.md`, `task-02-<slug>.md`...
+- Create **individual task files**: `tasks/task-R{N}-{SEQ}-<slug>.md`
 - Each file follows `{{SKILLS_DIR}}/specs/templates/task.md`
 - Load `{{SKILLS_DIR}}/specs/rules/tasks-generation.md`
 
@@ -149,19 +133,7 @@ Task(subagent_type="researcher", prompt="Research [feature topic]")
 
 ## Pre-Completion Checklist
 
-Before finalizing any specification, assert:
-
-- [ ] **scope_lock** initialized and respected throughout all phases
-- [ ] **EARS format** applied to all acceptance criteria in requirements.md
-- [ ] **Numeric requirement IDs** assigned to every requirement
-- [ ] **Discovery mode** selected and recorded in spec.json.design_context
-- [ ] **Requirements traceability** matrix present in design.md
-- [ ] **Every task file** maps to at least 1 valid in-scope requirement ID
-- [ ] **State Machine Blueprint:** design.md contains Mermaid diagrams for non-trivial flows
-- [ ] **Dependency graph complete**: no task can start before its blockers are listed
-- [ ] **Risk matrix filled**: likelihood × impact, with mitigation for High items
-- [ ] **Test strategy defined**: what gets unit tested, integration tested, e2e validated
-- [ ] **spec.json fully updated**: phase, progress, timestamps, approvals, design_context
+Before finalizing any specification, assert all 11 points in the `Pre-Finalization Checklist` defined in `SKILL.md`. Do not exit or declare completion until verifiable.
 
 ## Execution Workflow Summary
 
@@ -182,8 +154,8 @@ specs/<feature>/
 ├── design.md              # Architecture with traceability matrix and diagrams
 ├── research.md            # Research findings
 └── tasks/
-    ├── task-01-<name>.md  # Individual task files with requirement mapping
-    ├── task-02-<name>.md
+    ├── task-R0-01-<slug>.md  # Individual task files with requirement mapping
+    ├── task-R1-01-<slug>.md
     └── ...
 ```
 

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

@@ -11,10 +11,10 @@ argument-hint: "<feature-description> | status | resume | review | archive"
 
 ## Overview
 
-This skill provides a 7-phase workflow to transform ideas into specs and real implementations:
+This skill provides a 10-step workflow to transform ideas into specs:
 
 ```
-Init → Requirements → Design → Tasks → Code → Test → Review
+Analyze → Dependency Scan → Complexity Assessment → Init → Requirements → Design → Tasks → Hydration → Review → Completion
 ```
 
 **CRITICAL:** Before starting, the system MUST:
@@ -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
@@ -164,14 +170,17 @@ Load: `references/scope-inquiry.md`
 - Analyze existing codebase if this is an enhancement (not greenfield)
 - **MANDATORY Research:** Spawn `researcher` subagent to gather best practices, documentation, and technical foundation before detailing requirements. Use `Task(subagent_type="researcher", prompt="Research [feature]", description="Research")`.
 - Write requirements in **EARS** format (see `rules/ears-format.md`)
+- **Feasibility Check:** Cross-check each requirement against known technical constraints from `research.md`.
 - Each requirement gets a unique numeric ID
+- **Verify Quality:** Before proceeding, assert each requirement is: *Singular, Unambiguous, Testable, and has a numeric ID*. Include Non-Functional Requirements (Performance, Security, Scalability, Reliability, Accessibility).
 - Record any findings in `research.md` from template `templates/research.md`
 - Update `spec.json` phase + timestamps
 
 ### Step 6: Design
-- Read `spec.json` — stop if requirements aren't ready
-- Read project docs before designing (see `references/codebase-analysis.md`)
-- Pick discovery mode:
+- Read `spec.json` — stop if requirements haven't completed
+- Pick discovery mode: `minimal` / `light` / `full` based on complexity. **Default: `light`** unless certain it is simple UI (minimal) or complex integration (full).
+- Load `rules/design-principles.md`
+- Load `rules/design-discovery-[mode].md`:
   - **minimal**: UI-only or simple CRUD
   - **light**: extending existing system
   - **full**: integration, security, schema, or performance
@@ -249,7 +258,7 @@ Load: `references/task-hydration.md`
 - Task files are the single source of truth — hydration is just a convenience
 
 ### Step 9: Review (Optional)
-Load: `references/review.md`
+Load: `references/review.md` + `rules/design-review.md`
 - System auto-evaluates spec complexity and decides review depth:
   - **< 3 task files, no security concerns** → Validate only (lightweight interview)
   - **>= 5 task files OR security/migration keywords** → Red Team first, then Validate
@@ -289,6 +298,22 @@ When user calls `hapo:specs`, system checks `specs/`:
 
 **State persistence:** Update `spec.json` `phase` field on each transition. `spec.json` is the single source of truth.
 
+### spec.json Update Rules (MANDATORY)
+
+**Timestamps:** Each `timestamps.*_done` field MUST use the **actual current time** (ISO 8601 with timezone) when that specific phase completes. Do NOT reuse the `init` timestamp for later phases. If running the full pipeline end-to-end, capture a fresh timestamp at each phase transition.
+
+**Approvals (auto-approval behavior):**
+- When running the **full pipeline end-to-end** (init → tasks in one session): set `approvals.{phase}.generated = true` AND `approvals.{phase}.approved = true` for each completed phase before proceeding to the next.
+- When running a **single phase**: set `generated = true` but leave `approved = false` — user must explicitly approve before continuing.
+
+**`ready_for_implementation`:** This field MUST only be set to `true` when ALL of the following conditions are met:
+1. `approvals.requirements.approved = true`
+2. `approvals.design.approved = true`
+3. `approvals.tasks.approved = true`
+4. `progress.tasks = "done"`
+
+If any approval is `false`, `ready_for_implementation` MUST remain `false`.
+
 ## Output Structure
 
 ```
@@ -344,12 +369,18 @@ specs/
 - No over-engineering: if a function suffices, don't create a class
 
 ### Pre-Finalization Checklist
-- [ ] Every requirement has an ID and is testable
-- [ ] Design covers all requirements (no gaps)
-- [ ] Every task file maps to at least 1 requirement ID
-- [ ] No task is outside scope_lock
-- [ ] No dependency cycles between task files
-- [ ] `spec.json` has updated phase and timestamps
+Before finalizing any specification, assert all the following:
+- [ ] **scope_lock** initialized and respected throughout all phases
+- [ ] **EARS format** applied to all acceptance criteria in requirements.md
+- [ ] **Numeric requirement IDs** assigned to every requirement
+- [ ] **Discovery mode** selected and recorded in spec.json.design_context
+- [ ] **Requirements traceability** matrix present in design.md
+- [ ] **Every task file** maps to at least 1 valid in-scope requirement ID
+- [ ] **State Machine Blueprint:** design.md contains Mermaid diagrams for non-trivial flows
+- [ ] **Dependency graph complete**: no task can start before its blockers are listed
+- [ ] **Risk matrix filled**: likelihood × impact, with mitigation for High items
+- [ ] **Test strategy defined**: what gets unit tested, integration tested, e2e validated
+- [ ] **spec.json fully updated**: phase, progress, timestamps, approvals, design_context
 
 ## When TO Use
 
@@ -379,12 +410,13 @@ specs/
 - `design-principles.md` — Design principles
 - `design-discovery-full.md` — Full research workflow
 - `design-discovery-light.md` — Lightweight research workflow
-- `tasks-generation.md` — Task generation rules
+- `design-review.md` — Design review GO/NO-GO process
+- `tasks-generation.md` — Task generation rules (includes spike task rules)
 - `tasks-parallel-analysis.md` — Parallel task analysis
 
 ### References (`references/`)
 - `cross-spec-dependency.md` — Cross-spec dependency detection
-- `scope-inquiry.md` — Scope inquiry (3 questions)
+- `scope-inquiry.md` — 5-Dimension Complexity Assessment (Semantic, Hypothesis, Gap, Risk/Cynefin, Blast Radius)
 - `research-strategy.md` — Research strategy (7 tools)
 - `codebase-analysis.md` — Codebase analysis (4 mandatory files)
 - `task-hydration.md` — Task files → Claude Tasks conversion

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

@@ -17,14 +17,14 @@ Provide tools and methods to gather necessary information before writing require
 | 2 | **Sequential thinking** | Step-by-step reasoning, avoids context overload | Multi-step logic analysis, tangled problems |
 | 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 |
+| 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 |
 | 7 | **Debugger delegation** | Hand off to debugger agent for analysis | Investigate root cause of bugs |
 
 ## Workflow
 
 ### 1. Identify What Needs Research
-After drafting initial requirements, list unanswered questions:
+Before detailing requirements, list unanswered questions:
 - Which technology is most suitable?
 - Is there an existing pattern/library that solves this?
 - How does the current codebase handle similar functionality?

package/src/claude/skills/specs/references/review.md

@@ -212,5 +212,5 @@ Validate: {Q} questions asked, {D} decisions confirmed
 
 Files modified: {list}
 
-📌 Next step: /code <feature>
+📌 Next step: /hapo:develop <feature>
 ```

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

@@ -11,26 +11,46 @@ 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
 
-After answering the 3 questions, present via `AskUserQuestion`:
+After completing the 5-Dimension Assessment, present via `AskUserQuestion`:
 
 **Title:** "Scope Inquiry"
 **Question:** "Based on analysis, what scope level do you want?"
@@ -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]
 ```

package/src/claude/skills/specs/references/task-hydration.md

@@ -70,7 +70,7 @@ Convert task files (persistent storage) into Claude Tasks (session-scoped only),
 3. Skips re-creation, begins implementing directly
 
 ### New session (resume)
-1. User runs `/code <feature>` in a new session
+1. User runs `/hapo:develop <feature>` in a new session
 2. Code reads `TaskList` → empty (tasks died with old session)
 3. Code reads task files → re-hydrates from `[ ]` items
 4. `[x]` items = done, skip those

package/src/claude/skills/specs/rules/design-principles.md

@@ -3,9 +3,9 @@
 ## Core Design Principles
 
 ### 1. Type Safety is Mandatory
-- **NEVER** use `any` type in TypeScript interfaces
+- **NEVER** use generic/loosely-typed patterns (e.g., `any` in TypeScript, `object` in Python, `interface{}` in Go unless strictly necessary)
 - Define explicit types for all parameters and returns
-- Use discriminated unions for error handling
+- Use discriminated unions for error handling where supported
 - Specify generic constraints clearly
 
 ### 2. Design vs Implementation

package/src/claude/skills/specs/rules/ears-format.md

@@ -45,5 +45,6 @@ Keep EARS trigger keywords and fixed phrases in English (`When`, `If`, `While`,
 
 ## Quality Criteria
 - Requirements must be testable, verifiable, and describe a single behavior.
+- **Measurability:** Avoid qualitative terms (e.g. "safe state", "fast", "some coverage"). Replace with measurable thresholds (e.g., "HTTP 400 error", "< 500ms response", ">= 80% coverage").
 - Use objective language: "shall" for mandatory behavior, "should" for recommendations; avoid ambiguous terms.
 - Follow EARS syntax: [condition], the [system] shall [response/action].

package/src/claude/skills/specs/rules/tasks-generation.md

@@ -79,6 +79,33 @@ Grouping tasks vertically by requirement carries the risk of "siloed" or fragmen
 2. **Shared Interfaces (Horizontal Contracts)**: Sub-tasks that touch shared cross-requirement architecture (like registering a new page in a global `router.ts` or adding a column to a shared table) MUST explicitly reference the shared contract defined in `design.md`. 
 3. **Integration Enforcers**: If R1 and R2 interact (e.g., R2 UI displays data fetched by R1 backend), the later task MUST have a sub-task explicitly dedicated to "Wiring/Integrating with [Previous Feature] output".
 
+### 3d. Spike Tasks for Complex/Uncertain Areas (MANDATORY)
+
+When the 5-Dimension Complexity Assessment (Step 3) flags a component or requirement as **Risk = Complex** (Cynefin), the task breakdown MUST include a dedicated **spike/prototype task** before the main implementation task for that area.
+
+**Purpose**: Validate assumptions and reduce uncertainty before committing to full implementation.
+
+**Naming convention:** `tasks/task-R{N}-00-spike-<slug>.md`
+- Use `00` as the sequence number to ensure it runs FIRST within its requirement group.
+
+**Spike task structure:**
+1. **Objective**: State the specific uncertainty to resolve (e.g., "Validate that Google Meet captions DOM can be reliably scraped across account types")
+2. **Success Criteria**: Define what a successful spike looks like (e.g., "Demonstrate caption text extraction from 3 different Meet account types")
+3. **Time-box**: Maximum 4 hours. If spike exceeds time-box, escalate to user.
+4. **Output**: A brief findings report (can be inline in the task file) and a go/no-go recommendation.
+5. **Dependencies**: The main implementation task for this area MUST depend on the spike task.
+
+**When NOT to create spike tasks:**
+- Risk = Clear or Complicated → skip spike, proceed directly.
+- The uncertain area is already covered by research.md with concrete evidence (real API tests, not just documentation links).
+
+### 6. Risk Assessment Table (MANDATORY)
+
+Every task file MUST contain the Risk Assessment table, even if no risks are identified.
+- **Rule**: If there are risks, list them with Severity and Mitigation.
+- **Rule**: If no risks are found, you MUST still include the table and write `| None identified | — | — |`.
+- Never skip the `## Risk Assessment` section.
+
 ### 4. Requirements Mapping
 
 **End each task detail section with**:

package/src/claude/skills/specs/templates/design.md

@@ -252,10 +252,10 @@ Error tracking, logging, and health monitoring implementation.
 - E2E/UI Tests (if applicable): 3–5 critical user paths (e.g., forms, dashboards)
 - Performance/Load (if applicable): 3–4 items (e.g., concurrency, high-volume ops)
 
-## Optional Sections (include when relevant)
+## Conditional Sections (Include when relevant)
 
 ### Security Considerations
-_Use this section for features handling auth, sensitive data, external integrations, or user permissions. Capture only decisions unique to this feature; defer baseline controls to steering docs._
+_**REQUIRED** when features handle user data, authentication, PII, external integrations, or permissions. Omit only for purely internal UI changes._
 - Threat modeling, security controls, compliance requirements
 - Authentication and authorization patterns
 - Data protection and privacy considerations

package/src/claude/skills/specs/templates/requirements.md

@@ -24,3 +24,15 @@
 2. When [event] and [condition], the [system] shall [response/action]
 
 <!-- Additional requirements follow the same pattern -->
+
+## Non-Functional Requirements (NFRs)
+
+### Performance & Scalability
+- The [system] shall [measurable performance metric, e.g. "respond within 500ms"]
+- The [system] shall [measurable scale metric, e.g. "support 100 concurrent users"]
+
+### Security & Privacy
+- The [system] shall [measurable security behavior, e.g. "encrypt data at rest using AES-256"]
+
+### Reliability & Availability
+- If [failure condition], the [system] shall [recovery behavior]

package/src/claude/skills/specs/templates/research.md

@@ -1,4 +1,4 @@
-# Research & Design Decisions Template
+# Research & Design Decisions
 
 ---
 **Purpose**: Capture discovery findings, architectural investigations, and rationale that inform the technical design.
@@ -45,6 +45,7 @@ Record major decisions that influence `design.md`. Focus on choices with signifi
   2. Option B — short description
 - **Selected Approach**: What was chosen and how it works
 - **Rationale**: Why this approach fits the current project context
+- **Status**: [Proposed / Accepted / Superseded]
 - **Trade-offs**: Benefits vs. compromises
 - **Follow-up**: Items to verify during implementation or testing
 

package/src/claude/skills/specs/templates/task.md

@@ -11,6 +11,12 @@
 
 {{Brief 1-2 sentence objective detailing WHAT to accomplish, not HOW. Must relate directly to requirement R{{REQ_NUMBER}}.}}
 
+## Constraints
+
+- **MUST**: {{Non-negotiable requirement or technical constraint}}
+- **SHOULD**: {{Recommended approach or optimization}}
+- **MUST NOT**: {{Explicitly forbidden action or approach}}
+
 ## Implementation Steps
 
 - [ ] 1. {{MAJOR_STEP_1}}

package/src/claude/skills/specs/rules/gap-analysis.md

@@ -1,144 +0,0 @@
-# Gap Analysis Process
-
-## Objective
-Analyze the gap between requirements and existing codebase to inform implementation strategy decisions.
-
-## Analysis Framework
-
-### 1. Current State Investigation
-
-- Scan for domain-related assets:
-  - Key files/modules and directory layout
-  - Reusable components/services/utilities
-  - Dominant architecture patterns and constraints
-
-- Extract conventions:
-  - Naming, layering, dependency direction
-  - Import/export patterns and dependency hotspots
-  - Testing placement and approach
-
-- Note integration surfaces:
-  - Data models/schemas, API clients, auth mechanisms
-
-### 2. Requirements Feasibility Analysis
-
-- From EARS requirements, list technical needs:
-  - Data models, APIs/services, UI/components
-  - Business rules/validation
-  - Non-functionals: security, performance, scalability, reliability
-
-- Identify gaps and constraints:
-  - Missing capabilities in current codebase
-  - Unknowns to be researched later (mark as "Research Needed")
-  - Constraints from existing architecture and patterns
-
-- Note complexity signals:
-  - Simple CRUD / algorithmic logic / workflows / external integrations
-
-### 3. Implementation Approach Options
-
-#### Option A: Extend Existing Components
-**When to consider**: Feature fits naturally into existing structure
-
-- **Which files/modules to extend**:
-  - Identify specific files requiring changes
-  - Assess impact on existing functionality
-  - Evaluate backward compatibility concerns
-
-- **Compatibility assessment**:
-  - Check if extension respects existing interfaces
-  - Verify no breaking changes to consumers
-  - Assess test coverage impact
-
-- **Complexity and maintainability**:
-  - Evaluate cognitive load of additional functionality
-  - Check if single responsibility principle is maintained
-  - Assess if file size remains manageable
-
-**Trade-offs**:
-- ✅ Minimal new files, faster initial development
-- ✅ Leverages existing patterns and infrastructure
-- ❌ Risk of bloating existing components
-- ❌ May complicate existing logic
-
-#### Option B: Create New Components
-**When to consider**: Feature has distinct responsibility or existing components are already complex
-
-- **Rationale for new creation**:
-  - Clear separation of concerns justifies new file
-  - Existing components are already complex
-  - Feature has distinct lifecycle or dependencies
-
-- **Integration points**:
-  - How new components connect to existing system
-  - APIs or interfaces exposed
-  - Dependencies on existing components
-
-- **Responsibility boundaries**:
-  - Clear definition of what new component owns
-  - Interfaces with existing components
-  - Data flow and control flow
-
-**Trade-offs**:
-- ✅ Clean separation of concerns
-- ✅ Easier to test in isolation
-- ✅ Reduces complexity in existing components
-- ❌ More files to navigate
-- ❌ Requires careful interface design
-
-#### Option C: Hybrid Approach
-**When to consider**: Complex features requiring both extension and new creation
-
-- **Combination strategy**:
-  - Which parts extend existing components
-  - Which parts warrant new components
-  - How they interact
-
-- **Phased implementation**:
-  - Initial phase: minimal viable changes
-  - Subsequent phases: refactoring or new components
-  - Migration strategy if needed
-
-- **Risk mitigation**:
-  - Incremental rollout approach
-  - Feature flags or configuration
-  - Rollback strategy
-
-**Trade-offs**:
-- ✅ Balanced approach for complex features
-- ✅ Allows iterative refinement
-- ❌ More complex planning required
-- ❌ Potential for inconsistency if not well-coordinated
-### 4. Out-of-Scope for Gap Analysis
-
-- Defer deep research activities to the design phase.
-- Record unknowns as concise "Research Needed" items only.
-
-### 5. Implementation Complexity & Risk
-
-  - Effort:
-    - S (1–3 days): existing patterns, minimal deps, straightforward integration
-    - M (3–7 days): some new patterns/integrations, moderate complexity
-    - L (1–2 weeks): significant functionality, multiple integrations or workflows
-    - XL (2+ weeks): architectural changes, unfamiliar tech, broad impact
-  - Risk:
-    - High: unknown tech, complex integrations, architectural shifts, unclear perf/security path
-    - Medium: new patterns with guidance, manageable integrations, known perf solutions
-    - Low: extend established patterns, familiar tech, clear scope, minimal integration
-
-### Output Checklist
-
-- Requirement-to-Asset Map with gaps tagged (Missing / Unknown / Constraint)
-- Options A/B/C with short rationale and trade-offs
-- Effort (S/M/L/XL) and Risk (High/Medium/Low) with one-line justification each
-- Recommendations for design phase:
-  - Preferred approach and key decisions
-  - Research items to carry forward
-
-## Principles
-
-- **Information over decisions**: Provide analysis and options, not final choices
-- **Multiple viable options**: Offer credible alternatives when applicable
-- **Explicit gaps and assumptions**: Flag unknowns and constraints clearly
-- **Context-aware**: Align with existing patterns and architecture limits
-- **Transparent effort and risk**: Justify labels succinctly

package/src/claude/skills/specs/rules/steering-principles.md

@@ -1,90 +0,0 @@
-# Steering Principles
-
-Steering files are **project memory**, not exhaustive specifications.
-
----
-
-## Content Granularity
-
-### Golden Rule
-> "If new code follows existing patterns, steering shouldn't need updating."
-
-### ✅ Document
-- Organizational patterns (feature-first, layered)
-- Naming conventions (PascalCase rules)
-- Import strategies (absolute vs relative)
-- Architectural decisions (state management)
-- Technology standards (key frameworks)
-
-### ❌ Avoid
-- Complete file listings
-- Every component description
-- All dependencies
-- Implementation details
-- Agent-specific tooling directories (e.g. `.cursor/`, `.gemini/`, `.claude/`)
-- Detailed documentation of `.sdd/` metadata directories (settings, automation)
-
-### Example Comparison
-
-**Bad** (Specification-like):
-```markdown
-- /components/Button.tsx - Primary button with variants
-- /components/Input.tsx - Text input with validation
-- /components/Modal.tsx - Modal dialog
-... (50+ files)
-```
-
-**Good** (Project Memory):
-```markdown
-## UI Components (`/components/ui/`)
-Reusable, design-system aligned primitives
-- Named by function (Button, Input, Modal)
-- Export component + TypeScript interface
-- No business logic
-```
-
----
-
-## Security
-
-Never include:
-- API keys, passwords, credentials
-- Database URLs, internal IPs
-- Secrets or sensitive data
-
----
-
-## Quality Standards
-
-- **Single domain**: One topic per file
-- **Concrete examples**: Show patterns with code
-- **Explain rationale**: Why decisions were made
-- **Maintainable size**: 100-200 lines typical
-
----
-
-## Preservation (when updating)
-
-- Preserve user sections and custom examples
-- Additive by default (add, don't replace)
-- Add `updated_at` timestamp
-- Note why changes were made
-
----
-
-## Notes
-
-- Templates are starting points, customize as needed
-- Follow same granularity principles as core steering
-- All steering files loaded as project memory
-- Light references to `.sdd/specs/` and `.sdd/steering/` are acceptable; avoid other `.sdd/` directories
-- Custom files equally important as core files
-
----
-
-## File-Specific Focus
-
-- **product.md**: Purpose, value, business context (not exhaustive features)
-- **tech.md**: Key frameworks, standards, conventions (not all dependencies)
-- **structure.md**: Organization patterns, naming rules (not directory trees)
-- **Custom files**: Specialized patterns (API, testing, security, etc.)