@eskoubar95/spec 0.1.0 → 0.1.2

package/template/.cursor/commands/_shared/scaling.md

@@ -0,0 +1,264 @@
+---
+helper_id: scaling
+load_when:
+  - task_start
+  - spec_plan
+sections:
+  workflow_variants:
+    title: "Workflow Variants"
+    lines: [1, 100]
+  complexity:
+    title: "Complexity Assessment"
+    lines: [101, 200]
+always_load: false
+---
+
+# Scaling Logic
+
+Scaling logic adapts workflows based on project size and phase, ensuring appropriate level of detail and process.
+
+## Purpose
+
+Different project sizes and phases require different workflows:
+- Small projects: Simplified, lightweight process
+- Medium projects: Standard SDD workflow
+- Large projects: Extended, detailed process
+- Enterprise projects: Complex, comprehensive process
+
+## Size-Based Workflows
+
+### Small Projects (< 50 files, < 10 dependencies)
+
+**Spec Structure:**
+- Minimal spec files (00-root-spec.md, 03-risks.md, 04-open-questions.md)
+- Lightweight content, focus on essentials
+- Skip detailed design/infrastructure docs unless critical
+
+**Planning:**
+- Simplified milestones (2-3 milestones max)
+- Direct task execution (skip planning for simple tasks)
+- Minimal task breakdown
+
+**Validation:**
+- Manual validation only
+- Lightweight checklist
+- Quick verification
+
+**Example Workflow:**
+```
+/spec/init → /spec/plan (simplified) → /task/start → /task/validate (manual)
+```
+
+### Medium Projects (50-200 files, 10-50 dependencies)
+
+**Spec Structure:**
+- Standard spec files (all standard files)
+- Moderate detail level
+- Include design/infrastructure if applicable
+
+**Planning:**
+- Standard SDD workflow
+- 3-5 milestones
+- Full task breakdown
+- Standard acceptance criteria
+
+**Validation:**
+- Automated checks (linter, build, type check)
+- Manual testing
+- Standard checklist
+
+**Example Workflow:**
+```
+/spec/init → /spec/refine → /spec/plan → /task/start → /task/validate
+```
+
+### Large Projects (200-1000 files, 50-200 dependencies)
+
+**Spec Structure:**
+- Extended spec (multiple spec files, detailed sections)
+- Comprehensive documentation
+- Design system and infrastructure docs required
+
+**Planning:**
+- Detailed planning (milestones, epics, tasks)
+- 5-7 milestones
+- Comprehensive task breakdown
+- Detailed acceptance criteria
+
+**Validation:**
+- Comprehensive validation (automated + manual + integration)
+- Full test suite
+- Detailed checklist
+
+**Example Workflow:**
+```
+/spec/init → /spec/refine → /spec/plan (detailed) → /task/start → /task/validate (comprehensive)
+```
+
+### Enterprise Projects (> 1000 files, > 200 dependencies)
+
+**Spec Structure:**
+- Enterprise spec structure (multiple levels, comprehensive docs)
+- Full documentation suite
+- Architecture documentation
+- Design system and infrastructure required
+
+**Planning:**
+- Complex planning (programs, epics, milestones, tasks)
+- 7+ milestones
+- Very detailed task breakdown
+- Comprehensive acceptance criteria
+
+**Validation:**
+- Full validation suite (automated, manual, integration, performance)
+- Complete test coverage
+- Enterprise checklist
+
+**Example Workflow:**
+```
+/spec/init → /spec/refine → /spec/plan (complex) → /task/start → /task/validate (enterprise)
+```
+
+## Phase-Based Workflows
+
+### Initialization Phase
+
+**Characteristics:**
+- New project
+- Empty or initial spec
+- No or minimal code
+
+**Workflow:**
+- Full spec → plan → task workflow
+- Comprehensive setup
+- Detailed planning
+
+**Commands:**
+- `/spec/init` - Create initial spec
+- `/spec/refine` - Refine spec
+- `/spec/plan` - Create detailed plan
+- `/task/start` - Begin implementation
+
+### Expansion Phase
+
+**Characteristics:**
+- Active development
+- Growing spec
+- Regular commits
+
+**Workflow:**
+- Spec refine → plan → task workflow
+- Feature-focused
+- Incremental planning
+
+**Commands:**
+- `/spec/refine` - Refine spec for new feature
+- `/spec/plan` - Plan new feature
+- `/task/start` - Implement feature
+- `/task/validate` - Validate feature
+
+### Maintenance Phase
+
+**Characteristics:**
+- Stable codebase
+- Stable spec
+- Bugfix/refactor commits
+
+**Workflow:**
+- Direct task execution
+- Minimal spec changes
+- Bugfix-focused
+
+**Commands:**
+- `/task/start` - Direct task execution (minimal spec changes)
+- `/task/validate` - Validate fix
+- `/spec/evolve` - Update spec if needed
+
+### Migration Phase
+
+**Characteristics:**
+- Framework upgrade
+- Architecture change
+- Spec updates
+
+**Workflow:**
+- Spec update → plan → task workflow
+- Architecture-focused
+- Comprehensive planning
+
+**Commands:**
+- `/spec/refine` - Update spec for migration
+- `/spec/plan` - Plan migration tasks
+- `/task/start` - Execute migration
+- `/task/validate` - Validate migration
+
+### Legacy Phase
+
+**Characteristics:**
+- Existing codebase
+- Old spec
+- Minimal changes
+
+**Workflow:**
+- Spec audit → sync → refine workflow
+- Documentation-focused
+- Alignment-focused
+
+**Commands:**
+- `/spec/audit` - Audit spec compliance
+- `/spec/sync` - Sync spec with code
+- `/spec/refine` - Refine spec
+- `/spec/evolve` - Evolve spec
+
+## Workflow Adaptation
+
+**In Commands:**
+
+1. **Detect project size and phase** (from detection engine)
+2. **Adapt workflow accordingly:**
+   - Small projects: Simplified steps, skip non-essential
+   - Medium projects: Standard steps
+   - Large projects: Extended steps, more detail
+   - Enterprise projects: Comprehensive steps, full detail
+
+3. **Adapt to phase:**
+   - Initialization: Full workflow
+   - Expansion: Feature workflow
+   - Maintenance: Direct workflow
+   - Migration: Update workflow
+   - Legacy: Sync workflow
+
+**Example in /spec/plan:**
+
+```markdown
+## Adapt Planning to Project Size
+
+**Small Projects:**
+- 2-3 milestones max
+- Simplified task breakdown
+- Lightweight acceptance criteria
+
+**Medium Projects:**
+- 3-5 milestones
+- Standard task breakdown
+- Standard acceptance criteria
+
+**Large Projects:**
+- 5-7 milestones
+- Detailed task breakdown
+- Comprehensive acceptance criteria
+
+**Enterprise Projects:**
+- 7+ milestones
+- Very detailed task breakdown
+- Enterprise acceptance criteria
+```
+
+## Usage in Commands
+
+All commands should:
+1. Read project size and phase from detection
+2. Adapt workflow steps accordingly
+3. Show adapted workflow to user
+4. Execute with appropriate level of detail
+

package/template/.cursor/commands/_shared/state-assertions.md

@@ -0,0 +1,174 @@
+---
+helper_id: state-assertions
+load_when:
+  - always
+sections:
+  mode_boundaries:
+    title: "Mode Boundaries"
+    lines: [1, 50]
+  state_checks:
+    title: "State Checks"
+    lines: [51, 100]
+always_load: true
+---
+
+# State Assertions
+
+State assertions provide explicit mode, boundaries, and context before each command executes.
+
+## Purpose
+
+State assertions ensure:
+- **Explicit Mode**: Clear understanding of current mode
+- **Clear Boundaries**: What will and won't be done
+- **Context Awareness**: Detection results and active rules
+- **Implementation Status**: Whether code changes are allowed
+
+## State Assertion Template
+
+**Before starting any command, output:**
+
+```markdown
+## State Assertion (REQUIRED)
+
+**SDD MODE:** [Command Name]
+- **Mode:** [Research/Ideation | Refinement | Planning | Execution | Validation]
+- **Recommended Cursor Mode:** [Plan | Ask | Agent | Debug]
+- **Why:** [Explanation of why this mode fits this command]
+- **Alternative:** [Alternative modes if applicable]
+- **Context:** [Detected context from activation system]
+- **Active Rule Sets:** 
+  - Foundation: [List foundation rules]
+  - Domain: [List domain rules]
+  - Technology: [List technology rules]
+- **Implementation:** [BLOCKED | AUTHORIZED]
+- **Boundaries:**
+  - WILL: [What will be done]
+  - WILL NOT: [What will not be done]
+```
+
+## Mode Definitions
+
+**Research/Ideation:**
+- Understanding and exploration
+- No code changes
+- No spec changes (except initial creation)
+- Focus on questions and clarification
+
+**Refinement:**
+- Improving existing specifications
+- No code changes
+- Spec updates only
+- Focus on clarity and precision
+
+**Planning:**
+- Creating execution plans
+- No code changes
+- Creating tasks and milestones
+- Focus on structure and traceability
+
+**Execution:**
+- Implementing code
+- Code changes allowed
+- Following spec and plan
+- Focus on correctness and scope
+
+**Validation:**
+- Verifying completion
+- No new code changes (only fixes)
+- Testing and evidence gathering
+- Focus on quality and completeness
+
+## Context from Detection
+
+Include detection results in state assertion:
+- Project type (web-app, cli-tool, etc.)
+- Project size (small, medium, large, enterprise)
+- Project phase (initialization, expansion, etc.)
+- Technologies (nextjs, postgres, etc.)
+
+## Active Rule Sets
+
+List all active rules organized by category:
+- **Foundation:** Always active rules
+- **Domain:** Context-based rules (engineering, design, business)
+- **Technology:** Auto-activated rules (nextjs, api-design, database, etc.)
+
+## Implementation Status
+
+**BLOCKED:**
+- No code changes allowed
+- Spec/planning mode
+- Research/ideation mode
+
+**AUTHORIZED:**
+- Code changes allowed
+- Execution mode
+- After explicit confirmation
+
+## Boundaries
+
+**WILL:**
+- List what the command will do
+- Be specific and concrete
+- Include detection-based adaptations
+
+**WILL NOT:**
+- List what the command will not do
+- Explicitly exclude out-of-scope actions
+- Prevent scope creep
+
+## Cursor Mode Recommendations
+
+**Recommended Cursor Modes by Command Type:**
+
+- **Spec commands** (init, refine, plan, evolve, sync): **Plan mode** - Creates/updates spec files without code changes
+- **Spec audit:** **Debug mode** - For runtime evidence and debugging, **Plan mode** as alternative for static analysis
+- **Task start:** **Agent mode** - For code changes and implementation, **Plan mode** as alternative for planning only
+- **Task validate:** **Debug mode** - For debugging issues, **Plan mode** as alternative for validation only
+
+**Why Cursor Mode Matters:**
+- **Plan mode:** Optimal for spec/planning work, no code changes
+- **Ask mode:** Read-only exploration and understanding
+- **Agent mode:** Full code changes and implementation
+- **Debug mode:** Runtime analysis, debugging, and evidence gathering
+
+## Self-Correction Protocol
+
+**Common Mistakes to Detect:**
+
+1. **Mode Mixing:**
+   - DETECT: Suggesting code during spec mode, or introducing spec concerns during task mode
+   - CORRECT: "I apologize - I was [mixing modes]. Let me return to [correct mode]."
+   - EXAMPLE: During /spec/init, if suggesting implementation → "I apologize - I was introducing execution concerns. Let me return to specification mode."
+
+2. **Scope Creep:**
+   - DETECT: Adding features not in spec, expanding beyond defined boundaries
+   - CORRECT: "I apologize - I was expanding scope. Let me return to the defined scope."
+   - EXAMPLE: During /task/start, if adding features not in task → "I apologize - I was expanding scope beyond the task definition. Let me return to the defined task scope."
+
+3. **Assumption Making:**
+   - DETECT: Guessing instead of asking, making assumptions not in spec
+   - CORRECT: "I apologize - I was making assumptions. Let me ask for clarification."
+   - EXAMPLE: During /spec/init, if guessing user preferences → "I apologize - I was making assumptions about [assumption]. Let me ask for clarification."
+
+4. **Skipping Validation:**
+   - DETECT: Skipping validation steps, proceeding without acceptance criteria
+   - CORRECT: "I apologize - I was skipping validation. Let me return to validation steps."
+   - EXAMPLE: During /task/validate, if skipping checks → "I apologize - I was skipping validation steps. Let me return to the validation checklist."
+
+**Protocol:**
+1. **DETECT:** Recognize the mistake immediately
+2. **STOP:** Immediately halt execution
+3. **CORRECT:** Acknowledge mistake explicitly with specific correction
+4. **RESUME:** Continue correctly from point of error
+
+## Usage in Commands
+
+All commands must:
+1. Output state assertion before starting
+2. Include detection results
+3. Include active rule sets
+4. Explicitly state boundaries
+5. Follow self-correction protocol if violated
+