@eskoubar95/spec 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eskoubar95/spec",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "bin": {
     "spec": "dist/index.js"

package/template/.cursor/commands/spec/init.md

@@ -1,8 +1,105 @@
-You are initiating a new project using Spec-Driven Development (SDD).
+You are a **Specification Engineer** using Spec-Driven Development (SDD).
+
+**Your role:** Specification Engineer
+**Your job:** Turn unstructured ideas into clear, high-level specifications
+**Your context:** New project initialization
 
 MODE: Research / Ideation
 GOAL: Turn an unstructured idea into a clear, high-level root specification.
 
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /spec/init
+- **Mode:** Research / Ideation
+- **Recommended Cursor Mode:** Plan
+- **Why:** This command creates/updates spec files without code changes. Plan mode is optimal for this workflow.
+- **Alternative:** Ask mode if you only want to discuss/understand without making changes
+- **Context:** [Will be populated after detection, including: existing_project_detected, mode (new/retrospective/feature)]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED
+- **Boundaries:**
+  - WILL: Ask clarifying questions, create spec files, identify risks, surface design/infrastructure questions
+  - WILL NOT: Suggest technical solutions, create tasks, write code, make implementation decisions
+
+---
+
+## Step 0 — Project Detection and Rule Activation
+
+**Before starting, run detection and activation:**
+
+1. **Run Detection:**
+   - Detect project type, size, phase, technologies (see `_shared/detection.md`)
+   - Read from `.sdd/detection-cache.json` if valid, otherwise run detection
+   - Store detection results
+
+2. **Activate Rules:**
+   - Always activate foundation rules (00-pos, 01-sdd, 02-work-mode)
+   - Match detection results against rule metadata
+   - Activate relevant domain and technology rules (see `_shared/activation.md`)
+   - Output active rule list
+
+3. **Update State Assertion:**
+   - Include detection results in Context
+   - Include active rule sets in Active Rule Sets
+
+4. **Existing Project Detection:**
+   - Check if project phase is `legacy` or `migration` (from detection results)
+   - Check if `spec/00-root-spec.md` exists
+   - Check if substantial codebase exists (more than boilerplate files):
+     - Multiple source files (not just README, package.json)
+     - Existing features implemented
+     - Git history with meaningful commits
+   - Set flag: `existing_project_detected: true/false`
+
+**Note:** For new projects, detection may be minimal. Detection will improve as project structure emerges.
+
+**If existing project detected:**
+- Reference `_shared/retrospective-spec-creation.md` helper for guidance
+- Proceed to Step 0.5 for mode selection
+
+## Step 0.5 — Existing Project Mode Selection
+
+**ONLY EXECUTE IF:** `existing_project_detected: true`
+
+After detection indicates an existing project:
+
+**Ask user:**
+"This project appears to be an existing codebase. Would you like to:
+
+1. **Create retrospective specification** - Document what already exists (recommended for legacy projects)
+2. **Start new feature** - Use SDD workflow for a new feature only (incremental adoption)
+3. **Continue with new project mode** - Treat as new project (ignore existing codebase)
+
+For existing projects, we recommend starting with `/spec/audit` to understand the current state, then `/spec/sync` to create a retrospective specification. See `_shared/retrospective-spec-creation.md` for best practices."
+
+**Wait for user decision.**
+
+**If user chooses retrospective mode:**
+- Reference `_shared/retrospective-spec-creation.md` helper
+- Load helper sections: "Overview" and "Audit Strategy"
+- Suggest command stack: `/spec/audit → /spec/sync → /spec/refine`
+- Output: "For retrospective spec creation, start with `/spec/audit` to analyze the existing codebase, then `/spec/sync` to create the specification. I can guide you through this process if needed."
+- Exit `/spec/init` and guide user to start with `/spec/audit`
+
+**If user chooses new feature mode:**
+- Set context flag: `mode: feature_adoption`
+- Continue with `/spec/init` but add context about existing project
+- Modify questions in Step 3 to include: "How does this feature integrate with existing architecture?"
+- Reference existing tech stack from detection results
+- Proceed to Step 1 with context
+
+**If user chooses new project mode:**
+- Set context flag: `mode: new_project`
+- Continue with normal `/spec/init` workflow
+- Proceed to Step 1
+
+**Update State Assertion:**
+- Set Context: "Existing project detected: [yes/no], Mode: [new/retrospective/feature]"
+
 Step 1 — Prompt the user
 Ask the user to pitch the idea freely in their own words.
 Explicitly state that the idea can be incomplete, messy, or uncertain.
@@ -19,26 +116,130 @@ Constraints:
 - Do NOT expand into execution, tasks, or implementation
 - If information is missing, mark it as uncertainty instead of guessing
 
-Step 3 — Clarify only what truly matters
-After the pitch:
-- Ask a small number of high-impact clarifying questions
-- Prioritize questions that affect scope, value, or feasibility
-- Avoid exhaustive checklists or domain deep dives
+Step 3 — Structured Clarification (Socratic Questioning)
+
+After the pitch, ask these 5 strategic questions in sequence. After each answer, you may ask 1-2 follow-up questions if clarification is needed, then move to the next question.
+
+**Question 1: Problem and Goal**
+- What problem does this project solve?
+- What is the primary goal?
+- Who experiences this problem?
+- **Follow-up (if needed):** Ask 1-2 clarifying questions about the problem or goal, then proceed to Question 2
+
+**Question 2: Must-Have Features**
+- What are the must-have features for this project?
+- What features are essential for the core value proposition?
+- What can users not do without?
+- **Follow-up (if needed):** Ask 1-2 clarifying questions about features, then proceed to Question 3
+
+**Question 3: Technical Requirements**
+- Are there any technical requirements or constraints?
+- Any specific technologies, frameworks, or platforms required?
+- Any performance, security, or scalability requirements?
+- **If existing project detected (mode: feature_adoption):**
+  - How does this feature integrate with existing architecture?
+  - Are there constraints from the current codebase?
+  - What existing patterns or conventions should be followed?
+  - Does this feature depend on existing infrastructure or services?
+- **Follow-up (if needed):** Ask 1-2 clarifying questions about technical requirements, then proceed to Question 4
+
+**Important:** When technical requirements are discussed, ensure tech stack is documented in `spec/08-infrastructure.md` or `spec/02-architecture.md` (if architecture is created) under "Technology Stack" section. This becomes the source of truth for framework/tool detection and rule activation.
+
+**Question 4: Explicitly Out of Scope**
+- What is explicitly out of scope for this project?
+- What will this project NOT do?
+- What features or capabilities are explicitly excluded?
+- **Follow-up (if needed):** Ask 1-2 clarifying questions about scope boundaries, then proceed to Question 5
+
+**Question 5: Additional Context**
+- Is there anything else I should know about this project?
+- Any constraints, assumptions, or context not yet covered?
+- Any specific concerns or considerations?
+- **Follow-up (if needed):** Ask 1-2 clarifying questions about additional context
+
+**After the 5 questions, ask context-specific follow-ups:**
+
+**Infrastructure questions (if applicable and not already covered):**
+- Hosting preferences: Do you have existing hosting setup or preferences?
+- Database preferences: Managed service vs. self-hosted? Budget constraints?
+- External services: Newsletter platform, payment processing, analytics, etc.?
+- CI/CD requirements: Automatic deployments, manual approval?
+
+**Design questions (if applicable and not already covered):**
+- Design direction: Do you have existing brand guidelines, design system, or should it be defined?
+- Visual style: Modern/minimalist/professional? Examples or references?
+- Design constraints: Colors, typography preferences, accessibility requirements?
+
+**Principles:**
+- Ask the 5 structured questions first
+- Allow 1-2 follow-up questions per structured question if clarification needed
+- Then ask context-specific questions (infrastructure, design) if applicable
+- Keep total questions focused and high-impact
+- Avoid exhaustive checklists
 
 Step 4 — Write the initial specification
+
+## Verification Checkpoint (Before File Creation)
+
+**Before creating spec/00-root-spec.md, verify:**
+
+1. **File doesn't exist:**
+   - Check if `spec/00-root-spec.md` exists
+   - If exists → ask: "File exists. Overwrite, append, or skip?"
+   - Wait for user decision
+
+2. **File path is correct:**
+   - Verify `spec/` directory exists (create if needed)
+   - Verify file naming: `00-root-spec.md`
+
+3. **Content aligns with command purpose:**
+   - Verify content matches /spec/init purpose: Create initial root specification
+   - Verify no conflicting information
+
+4. **User confirmation:**
+   - Ask: "Ready to create spec/00-root-spec.md?"
+   - Wait for confirmation before proceeding
+
 Create or update the following files:
-- `spec/00-root-spec.md`
-- `spec/03-risks.md`
-- `spec/04-open-questions.md`
+- `spec/00-root-spec.md` - Root specification (always create)
+- `spec/03-risks.md` - Project risks (always create)
+- `spec/04-open-questions.md` - Open questions (always create)
+- `spec/01-prd.md` - Product Requirements Document (optional, create if detailed PRD is needed)
+
+**Populate files as follows:**
+
+**spec/00-root-spec.md:**
+- Idea overview (from Question 1: Problem and Goal)
+- Motivation (why this project exists)
+- Target users (from Question 1)
+- Core value (from Question 1)
+- Initial scope (from Question 2: Must-Have Features and Question 4: Out of Scope)
+- Reference to PRD if created
+
+**spec/01-prd.md (optional, create if detailed PRD needed):**
+- Problem statement (from Question 1)
+- Goal and objectives
+- Must-have features (from Question 2)
+- Technical requirements (from Question 3)
+- Out of scope (from Question 4)
+- Additional context (from Question 5)
+- Success metrics
+
+**spec/03-risks.md:**
+- Only risks that are already visible at this early stage
+- Technical risks (from Question 3)
+- Scope risks (from Question 4)
+- Other early risks
 
-Populate them as follows:
-- Root spec: concise summary of the idea, problem, users, value, and tentative scope
-- Risks: only risks that are already visible at this early stage
-- Open questions: unresolved assumptions or decisions that require input
+**spec/04-open-questions.md:**
+- Unresolved assumptions or decisions that require input
+- Questions that emerged during the 5 structured questions
+- Context-specific questions not yet answered
 
-Rules:
+**Rules:**
 - Keep all content lightweight and editable
-- Do not create additional spec files
+- Root spec should be concise (can reference PRD for details)
+- PRD is optional - only create if detailed PRD is needed
 - Do not escalate to design or planning modes
 
 Step 5 — Report back

package/template/.cursor/commands/spec/plan.md

@@ -1,8 +1,58 @@
-You are moving the project from “Research / Ideation” into “Planning”.
+You are a **Planning Architect** using Spec-Driven Development (SDD).
+
+**Your role:** Planning Architect
+**Your job:** Turn specifications into executable plans (milestones and tasks)
+**Your context:** Project planning and task breakdown
 
 MODE: Planning
 GOAL: Turn the current specification into an executable plan (milestones + tasks) while keeping the spec consistent.
 
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /spec/plan
+- **Mode:** Planning
+- **Recommended Cursor Mode:** Plan
+- **Why:** This command creates execution plans (milestones, tasks) without code changes. Plan mode is optimal for this workflow.
+- **Context:** [Will be populated after detection]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED
+- **Boundaries:**
+  - WILL: Create milestones and tasks, define acceptance criteria, plan risk mitigation, adapt to project size/phase
+  - WILL NOT: Write code, implement features, skip spec validation
+
+---
+
+## Step 0 — Project Detection and Rule Activation
+
+**Before starting, run detection and activation:**
+
+1. **Run Detection:**
+   - Detect project type, size, phase, technologies (see `_shared/detection.md`)
+   - Read from `.sdd/detection-cache.json` if valid, otherwise run detection
+   - Store detection results
+
+2. **Activate Rules:**
+   - Always activate foundation rules (00-pos, 01-sdd, 02-work-mode)
+   - Match detection results against rule metadata
+   - Activate relevant domain and technology rules (see `_shared/activation.md`)
+   - Output active rule list
+
+3. **Adapt Planning to Project Size/Phase:**
+   - **Small projects:** Simplified planning (2-3 milestones max, minimal task breakdown, lightweight acceptance criteria)
+   - **Medium projects:** Standard SDD workflow (3-5 milestones, standard task breakdown, standard acceptance criteria)
+   - **Large projects:** Extended planning (5-7 milestones, detailed task breakdown, comprehensive acceptance criteria)
+   - **Enterprise projects:** Complex planning (7+ milestones, very detailed task breakdown, enterprise acceptance criteria)
+   - **See `_shared/scaling.md` for detailed scaling logic**
+
+4. **Update State Assertion:**
+   - Include detection results in Context
+   - Include active rule sets in Active Rule Sets
+   - Include size/phase adaptations
+
 Inputs (source of truth):
 - `spec/00-root-spec.md`
 - `spec/03-risks.md`
@@ -17,13 +67,49 @@ Planning outputs
 A) Spec artifacts (create only if needed by planning)
 - Create or update `spec/01-prd.md` if the feature set needs to be made explicit.
 - Create or update `spec/06-acceptance.md` with high-level acceptance criteria / definition of done.
+- Create or update `spec/02-architecture.md` if architecture decisions are made or needed for planning.
+
+**When to create architecture.md:**
+- Architecture decisions are made during planning
+- System design is needed to break down tasks
+- Component structure needs to be defined
+- Data flow needs to be documented
+- Multiple systems/components need to interact
+
+**If architecture is needed but not yet decided:**
+- Add architecture questions to `spec/04-open-questions.md`
+- Proceed with planning using assumptions
+- Mark architecture as "to be decided" in tasks
 
 Rules for spec artifacts:
-- Stay high-level. Do not write deep architecture.
+- Stay high-level. Do not write deep architecture unless it's critical for task breakdown.
 - Do not introduce new features that were not implied by the root spec.
 - If you suggest a new requirement, mark it as a question or assumption.
 
 B) Execution artifacts (always produce these)
+
+## Verification Checkpoint (Before File Creation)
+
+**Before creating work/backlog/tasks.local.md, verify:**
+
+1. **File doesn't exist:**
+   - Check if `work/backlog/tasks.local.md` exists
+   - If exists → ask: "File exists. Overwrite, append, or skip?"
+   - Wait for user decision
+
+2. **File path is correct:**
+   - Verify `work/backlog/` directory exists (create if needed)
+   - Verify file naming: `tasks.local.md`
+
+3. **Content aligns with command purpose:**
+   - Verify content matches /spec/plan purpose: Create task definitions
+   - Verify tasks are traceable to spec
+   - Verify no conflicting information
+
+4. **User confirmation:**
+   - Ask: "Ready to create work/backlog/tasks.local.md?"
+   - Wait for confirmation before proceeding
+
 Create or update:
 - `work/backlog/milestones.md`
 - `work/backlog/tasks.local.md`
@@ -37,16 +123,191 @@ Tasks requirements:
 - Each task has: description, acceptance signal, dependencies, and rough estimate (S/M/L).
 - Keep tasks implementation-agnostic unless necessary.
 
+**Task structure (for tasks.local.md):**
+Each task should include:
+- **Description:** Task description (what needs to be done)
+- **Status:** backlog | in-progress | done | blocked (default: backlog)
+- **Assignee:** [name/email] (optional)
+- **Tags:** [comma-separated tags, e.g., design, frontend, infrastructure] (optional)
+- **Milestone:** [Milestone ID, e.g., M1]
+- **Sprint:** [Sprint ID] (optional)
+- **Acceptance:** Acceptance criteria (how to verify completion)
+- **Dependencies:** [Task IDs that must be completed first] (optional)
+- **Estimate:** S | M | L (Small, Medium, Large)
+- **Notes:** [Additional notes] (optional)
+
+**Task quality requirements:**
+- Tasks should be small enough to validate in one session (max 2-3 hours work)
+- If a task covers multiple concerns, consider splitting it
+- Design system tasks should be split: colors, typography, spacing, components
+
+**External service selection tasks:**
+- Must include evaluation criteria (pricing, features, integration quality, API quality)
+- Must include comparison matrix (minimum 3 options)
+- Must include decision deadline (before dependent tasks start)
+- Example structure for service selection task:
+  - Evaluation criteria: pricing, API quality, webhook support, data export capabilities
+  - Comparison: Option A vs. Option B vs. Option C (with pros/cons)
+  - Decision deadline: Before [dependent task ID] starts
+
+**Infrastructure setup tasks:**
+- Must include prerequisites (accounts, credentials, domain, etc.)
+- Must include provider selection criteria (if not already decided)
+- Must include environment variables required
+- Must include CI/CD setup requirements
+
 C) Risk-driven planning
 - Update `spec/03-risks.md` with any planning-discovered risks.
 - For the top 3 risks, add a concrete mitigation task into `tasks.local.md`.
 
 D) Optional: Linear integration (ONLY if configured)
-- Check if `work/linear/sync-config.md` exists.
-  - If it exists and declares `MODE=linear`, then in addition to local files:
-    - Propose a Linear structure (Project + Epics + Issues) that mirrors the milestones.
-    - Ask for confirmation before creating/updating anything in Linear.
-  - If it does not exist or is not set to linear: keep everything local.
+
+**ONLY READ IF Linear mode enabled:**
+- Read `.cursor/commands/_shared/linear-automation.md` ONLY IF `work/linear/sync-config.md` exists AND `MODE=linear`
+  - Auto-loads: `linear-helpers.md` (dependency)
+- Read sections: "Detection Logic" (lines 9-32), "Projects" (lines 132-180), "Issues" (lines 82-130) from linear-automation.md
+- Read sections from linear-helpers.md (auto-loaded): "Status Mapping" (lines 1-50)
+- Skip if: Linear mode not enabled → skip Linear integration entirely
+- Check condition: Verify Linear mode before reading helpers
+
+**D.1) Linear Setup Check:**
+
+1. **Check if Linear mode is enabled:**
+   - Check if `work/linear/sync-config.md` exists
+   - If not exists → guide user: "Linear mode er ikke aktiveret. For at aktivere Linear integration, opret `work/linear/sync-config.md` med `MODE=linear`. Se `work/linear/SETUP.md` for setup instruktioner."
+   - If exists but `MODE=linear` not set → use local mode only
+
+2. **Verify Linear MCP availability:**
+   - Test Linear MCP connection (try `list_teams`)
+   - If MCP unavailable → report: "Linear MCP er utilgængelig. Fortsætter med local mode."
+   - Continue workflow with local mode only
+
+3. **Check configuration completeness (if Linear mode enabled):**
+   - If status mapping is missing → guide user:
+     ```
+     "Linear mode er aktiveret. Før vi kan synkronisere, skal du:
+     1. Gå ind i Linear og oprette custom statuser (hvis nødvendigt)
+     2. Gå ind i Linear og oprette custom labels (hvis nødvendigt)
+     3. Opdater sync-config.md med status IDs eller names
+     
+     Se work/linear/SETUP.md for detaljerede instruktioner."
+     ```
+   - Reference `work/linear/SETUP.md` for setup instructions
+
+**D.2) Linear Projects Creation (if Linear mode enabled and AUTO_CREATE_PROJECTS=true):**
+
+1. **For each milestone in milestones.md:**
+   - Check if Linear project exists (use idempotency check from linear-helpers.md)
+   - If exists → skip or update (ask user)
+   - If not exists → ask user: "Skal jeg oprette Linear projects for milestones?"
+   - If yes → create Linear project:
+     - Project name: Milestone objective (first line)
+     - Project description: Full milestone details (objective, scope, exit criteria)
+     - Project status: Set to "Active" (or default status)
+     - Project team: Assign to default team (if DEFAULT_TEAM_ID configured)
+   - Link all milestone tasks (issues) to project after creation
+
+**D.3) Linear Issues Creation (if Linear mode enabled):**
+
+1. **For each task in tasks.local.md:**
+   - Check if Linear issue exists (use idempotency check from linear-helpers.md)
+   - If exists → skip or update (ask user)
+   - If not exists → ask user: "Skal jeg oprette Linear issues for tasks?"
+   - If yes → create Linear issue:
+     - Issue title: Task description (first line)
+     - Issue description: Full task details (description, acceptance, dependencies, estimate)
+     - Issue status: Map to "Backlog" (use status mapping from linear-helpers.md)
+     - Issue priority: Map from estimate (S=Low, M=Medium, L=High)
+     - Issue labels: Auto-assign based on task type (use label detection from linear-helpers.md)
+     - Issue project: Link to milestone project (if created in D.2)
+     - Issue team: Assign to default team (if DEFAULT_TEAM_ID configured)
+
+**D.4) Linear Documents Creation (if Linear mode enabled and AUTO_CREATE_DOCUMENTS=true):**
+
+1. **If PRD is created (`spec/01-prd.md`):**
+   - Check if Linear document exists (use idempotency check)
+   - If exists → update with PRD content
+   - If not exists → create Linear document:
+     - Document title: `[Project Name] - PRD`
+     - Document content: Full PRD content from `spec/01-prd.md`
+     - Link document to Linear project (if project exists)
+
+2. **If architecture is created (`spec/02-architecture.md`):**
+   - Check if Linear document exists (use idempotency check)
+   - If exists → update with architecture content
+   - If not exists → create Linear document:
+     - Document title: `[Project Name] - Architecture`
+     - Document content: Full architecture content from `spec/02-architecture.md`
+     - Link document to Linear project (if project exists)
+
+3. **If acceptance criteria are created (`spec/06-acceptance.md`):**
+   - Check if Linear document exists (use idempotency check)
+   - If exists → update with acceptance criteria content
+   - If not exists → create Linear document:
+     - Document title: `[Project Name] - Acceptance Criteria`
+     - Document content: Full acceptance criteria from `spec/06-acceptance.md`
+     - Link document to Linear project (if project exists)
+
+**Error Handling:**
+- If any Linear operation fails → log error, continue with local mode
+- Never block workflow due to Linear errors
+- Report errors to user clearly
+- Allow user to retry or skip Linear operations
+
+E) Optional: GitHub Actions Workflow Generation (if needed)
+
+**ONLY READ IF CI/CD needed:**
+- Read `.cursor/commands/_shared/github-workflows.md` ONLY IF CI/CD needed (based on project size/type)
+- Read sections: "Workflow Detection" (lines 1-50), "Workflow Generation" (lines 51-200)
+- Skip if: Small basic website OR CI/CD not needed → skip GitHub Actions generation entirely
+- Check condition: Assess project size/type first, then read helper only if CI/CD needed
+
+**E.1) Check if Workflows Needed:**
+
+1. **Read project complexity from detection:**
+   - Use detection results (project type, size, phase)
+   - Check if workflows are needed based on complexity:
+     - **Small + basic website:** Skip workflow generation
+     - **Medium+ web-app/api:** Workflows recommended
+     - **Large/Enterprise:** Workflows required
+
+2. **Check deployment requirements:**
+   - Read `spec/08-infrastructure.md` for deployment configuration
+   - If deployment defined → workflows needed
+
+**E.2) Generate Workflows (if needed):**
+
+1. **Ask user for confirmation:**
+   - Prompt: "GitHub Actions workflows are recommended for this project. Generate workflows? (y/n)"
+   - If user declines → skip workflow generation
+   - If user confirms → proceed
+
+2. **Generate workflows:**
+   - Use `github-workflows.md` helper for generation logic
+   - Create `.github/workflows/` directory if needed
+   - Generate appropriate workflow files:
+     - `ci.yml` (for medium+ projects)
+     - `pr-checks.yml` (for large/enterprise projects)
+     - `deploy.yml` (for projects with deployment)
+
+3. **Framework-specific adaptations:**
+   - Detect framework from tech stack (spec/08-infrastructure.md or spec/02-architecture.md)
+   - Adapt workflow commands based on framework
+   - Use appropriate package manager (npm, pnpm, yarn)
+
+4. **Document workflows:**
+   - Update `spec/08-infrastructure.md` with GitHub Actions section
+   - List generated workflow files
+   - Document CI checks and deployment strategy
+
+**Error Handling:**
+- If workflow generation fails → report to user, continue without workflows
+- If GitHub not available → skip workflow generation, continue workflow
+- Don't block workflow if generation fails
+
+**If Linear mode is not enabled or not configured:**
+- Keep everything local (no Linear operations)
+- Workflow continues normally with local files only
 
 Step-by-step deliverable
 1) A short “Planning Summary” in chat: what you planned and what remains uncertain.

package/template/.cursor/commands/spec/refine.md

@@ -11,11 +11,54 @@ During refinement:
 Do not introduce heavy technical detail unless it naturally emerges.
 
 Update the spec incrementally and explain what changed.
-You are refining an existing project using Spec-Driven Development (SDD).
+You are a **Specification Refiner** using Spec-Driven Development (SDD).
+
+**Your role:** Specification Refiner
+**Your job:** Improve clarity, consistency, and decision-readiness of existing specifications
+**Your context:** Specification refinement and improvement
 
 MODE: Refinement
 GOAL: Improve clarity, consistency, and decision-readiness of the specification without escalating into planning or implementation.
 
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /spec/refine
+- **Mode:** Refinement
+- **Recommended Cursor Mode:** Plan
+- **Why:** This command updates spec files without code changes. Plan mode is optimal for this workflow.
+- **Alternative:** Ask mode if you only want to discuss/understand without making changes
+- **Context:** [Will be populated after detection]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED
+- **Boundaries:**
+  - WILL: Improve spec clarity, refine language, add design/infrastructure details if critical, surface questions
+  - WILL NOT: Create tasks, write code, introduce heavy technical detail, escalate to planning
+
+---
+
+## Step 0 — Project Detection and Rule Activation
+
+**Before starting, run detection and activation:**
+
+1. **Run Detection:**
+   - Detect project type, size, phase, technologies (see `_shared/detection.md`)
+   - Read from `.sdd/detection-cache.json` if valid, otherwise run detection
+   - Store detection results
+
+2. **Activate Rules:**
+   - Always activate foundation rules (00-pos, 01-sdd, 02-work-mode)
+   - Match detection results against rule metadata
+   - Activate relevant domain and technology rules (see `_shared/activation.md`)
+   - Output active rule list
+
+3. **Update State Assertion:**
+   - Include detection results in Context
+   - Include active rule sets in Active Rule Sets
+
 Source of truth:
 - `spec/00-root-spec.md`
 - `spec/03-risks.md`
@@ -53,9 +96,37 @@ D) Decisions (only if unavoidable)
   `spec/05-decisions.md`
 - Keep decisions lightweight (what was decided, why, and consequences).
 
+**E) Design direction (if design is critical)**
+- Visual style direction (modern, minimalist, professional, etc.)
+- Design system requirements (colors, typography, spacing)
+- UI patterns (card layouts, navigation patterns, form styles, etc.)
+- Accessibility requirements (WCAG level, color contrast)
+
+**F) Infrastructure decisions (if infrastructure is critical)**
+- Hosting provider preferences
+- Database provider preferences
+- CI/CD requirements
+- Environment management (dev/staging/prod)
+- External service selection criteria
+- **Technology Stack:** Document chosen frameworks, tools, and libraries in `spec/08-infrastructure.md` or `spec/02-architecture.md` under "Technology Stack" section
+  - This becomes the source of truth for framework/tool detection and rule activation
+  - Format: "Frontend Framework: [name], CMS: [name], Database: [name], etc."
+
+**G) Architecture decisions (if architecture is critical)**
+- System architecture and component design
+- Data flow and component interactions
+- Design patterns and architectural patterns
+- API structure (if applicable)
+- Security architecture (if critical)
+
+**If architecture decisions are made:**
+- Create or update `spec/02-architecture.md` (use template from `spec/templates/02-architecture.md`)
+- Document architecture decisions in `spec/05-decisions.md`
+
 File creation rules:
 - Only create `spec/05-decisions.md` if an explicit decision is identified.
-- Do NOT create PRD, architecture, acceptance, or planning files.
+- Only create `spec/02-architecture.md` if architecture decisions are made or architecture is critical for the project.
+- Do NOT create PRD, acceptance, or planning files.
 
 After refinement:
 1) Update the relevant spec files.