@haposoft/cafekit 0.7.17 → 0.7.20

package/package.json

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

@@ -2,7 +2,7 @@
 name: hapo:specs
 description: "Structured specification workflow — from vague idea to actionable task list. Includes init, requirements, design, task breakdown, review, and archiving."
 version: 2.0.0
-argument-hint: "<feature-description> | status | resume | review | archive"
+argument-hint: "<feature-description> | status | resume | --validate | archive"
 ---
 
 # Specs (SDD — Specification-Driven Development)
@@ -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:
@@ -67,7 +67,7 @@ Display selection menu via `AskUserQuestion`:
       { "label": "Create new spec", "description": "Initialize spec from a feature description" },
       { "label": "status", "description": "View status of all specs in specs/" },
       { "label": "resume", "description": "Continue an in-progress spec" },
-      { "label": "review", "description": "Review spec (auto-decides: red team or validation)" },
+      { "label": "--validate", "description": "Review spec (auto-decides: red team or validation)" },
       { "label": "archive", "description": "Archive completed specs + write journal" }
     ],
     "multiSelect": false
@@ -82,12 +82,17 @@ System auto-analyzes the description:
 - If task is simple (small bugfix, config change) → suggest "A spec may not be needed for this. Continue anyway?"
 - If task is complex (multi-module, security/migration related) → auto-activate deep research, ask user 3 scope questions
 
+### When called WITH `--validate` argument
+
+System IMMEDIATELY jumps to **Step 9: Validation Review**.
+The system MUST NOT execute Steps 1-8. Instead, load `references/review.md`, adopt Red Team personas, and read the entire `specs/` directory to hunt for flaws before interviewing the user.
+
 ## Workflow Diagram
 
 ```mermaid
 flowchart TD
     A["Call /hapo:specs"] --> B{Has description?}
-    B -->|No| C["Menu: init / status / resume / review / archive"]
+    B -->|No| C["Menu: init / status / resume / --validate / archive"]
     B -->|Yes| D["Step 1: Analyze description"]
     D --> E{Clear enough?}
     E -->|No| F["Ask user 1-2 clarifying questions"]
@@ -170,14 +175,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
@@ -254,8 +262,8 @@ Load: `references/task-hydration.md`
 - If TaskCreate tool unavailable → fallback to `TodoWrite`
 - Task files are the single source of truth — hydration is just a convenience
 
-### Step 9: Review (Optional)
-Load: `references/review.md`
+### Step 9: Validation Review (Optional)
+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
@@ -295,6 +303,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
 
 ```
@@ -323,7 +347,7 @@ specs/
 |---|---|---|
 | `/hapo:specs status` | View status of all specs | — |
 | `/hapo:specs resume <feature>` | Continue an in-progress spec | — |
-| `/hapo:specs review <feature>` | Review spec (auto: red team + validate based on complexity) | `references/review.md` |
+| `/hapo:specs --validate <feature>` | Validate spec (auto: red team + validate based on complexity) | `references/review.md` |
 | `/hapo:specs archive` | Archive completed specs + write journal | `references/archive-workflow.md` |
 
 ## Quality Standards
@@ -350,12 +374,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
 
@@ -385,12 +415,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

@@ -50,7 +50,7 @@ Assess how many other parts of the system are affected if this change breaks or
 
 ## 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?"

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.)