@eskoubar95/spec 0.1.4 → 0.1.5

package/template/.cursor/commands/task/batch.md

@@ -0,0 +1,112 @@
+You are an **Implementation Engineer** using Spec-Driven Development (SDD).
+
+**Your role:** Implementation Engineer
+**Your job:** Execute multiple tasks safely with clear scope, correctness, and discipline
+**Your context:** Batch task execution (milestone or task list)
+
+MODE: Execution / Batch
+GOAL: Execute a batch of tasks sequentially while maintaining SDD discipline (one task at a time), Git hygiene, and validation evidence.
+
+---
+
+## State Assertion (REQUIRED)
+
+**Before starting, output:**
+
+**SDD MODE:** /task/batch
+- **Mode:** Execution
+- **Recommended Cursor Mode:** Agent
+- **Why:** This command results in code changes across multiple tasks. Agent mode is optimal for multi-file changes and long runs.
+- **Context:** [Milestone/task list, project detection summary, and batch policies]
+- **Active Rule Sets:** [Will be populated after activation]
+- **Implementation:** BLOCKED (until Step 3 confirmation)
+- **Boundaries:**
+  - WILL: Execute tasks sequentially, validate each task, keep scope tight to the selected tasks
+  - WILL NOT: Expand scope beyond selected tasks, perform unrelated refactors, merge without validation evidence
+
+---
+
+## Step 0 — Project Detection and Rule Activation
+
+Run detection and activation first (same as `/task/start`):
+- Detect project type, size, phase, technologies (see `_shared/detection.md`)
+- Activate relevant rules (see `_shared/activation.md`)
+- Read tech stack from `spec/08-infrastructure.md` or `spec/02-architecture.md` if present
+
+**If project is a monorepo (REQUIRED discipline):**
+- Each task must have `**Workspace:** <path>` in `work/backlog/tasks.local.md`.
+- If any selected task is missing `**Workspace:**` → **HARD STOP** before execution.
+- Validate and build **per workspace**, not repo-wide.
+
+## Step 1 — Select batch scope
+
+Choose exactly one:
+
+1) **Milestone batch**
+- Read `work/backlog/milestones.md` and pick a milestone ID (e.g. `M3`)
+- Collect its tasks from `work/backlog/tasks.local.md`
+
+2) **Task list batch**
+- Provide an ordered list of task IDs (e.g. `T1.1, T1.2, T1.3`)
+- Verify each exists in `work/backlog/tasks.local.md`
+
+## Step 2 — Define batch policies (must be explicit)
+
+Set the following policies before execution:
+
+- **Base branch**: resolve `defaultBranch` (do not assume `main`)
+  - Preferred: skill `/sdd-git-default-branch`
+  - Fallback: helper `_shared/branch-detection.md`
+- **Branching**:
+  - One branch per task: `task/<task-id>-<short-description>`
+- **Commit granularity**:
+  - Small logical units (recommended): skill `/sdd-commit-unit`
+  - Or: commit at task completion only
+- **Validation**:
+  - Preferred: skill `/sdd-validation-suite`
+  - Or: project-specific scripts (lint/typecheck/tests/build) if present
+- **PR strategy (optional)**:
+  - Preferred: skill `/sdd-pr-create-or-update` (with correct base branch)
+  - Or: manual PR creation after the batch
+
+## Step 3 — Batch execution method (choose one)
+
+### Option A (recommended): Use the `batch-runner` subagent
+
+Launch the `batch-runner` subagent with:
+
+- Batch scope (milestone ID or task list)
+- Source-of-truth paths:
+  - `work/backlog/milestones.md`
+  - `work/backlog/tasks.local.md`
+  - `spec/tasks/**` (if present)
+- Git policies:
+  - resolved `defaultBranch`
+  - branch naming rules
+  - commit policy
+- Validation + PR policies
+
+The subagent must return:
+- completed task IDs
+- blocked task IDs + reasons
+- evidence (what ran; pass/fail)
+- notes (risks/open questions discovered)
+
+### Option B: Manual sequential execution (no subagent)
+
+For each task in order:
+1. Run `/task/start` for the task (preflight + branch)
+2. Implement only what the task requires
+3. Commit (per policy)
+4. Run `/task/validate` for the task (per policy)
+5. Record outcomes (what changed + evidence + next blocker)
+
+---
+
+## Completion criteria
+
+This batch is complete when:
+- Every task is either completed with validation evidence OR explicitly blocked with a reason
+- No task is merged without validation evidence
+- Any new risks/questions discovered are captured (`spec/03-risks.md`, `spec/04-open-questions.md`)
+

package/template/.cursor/commands/task/start.md

@@ -73,6 +73,24 @@ Inputs (source of truth):
 - `spec/06-acceptance.md` (if it exists)
 - `work/backlog/tasks.local.md`
 
+## Step 0.9 — Workspace scope (REQUIRED for monorepos)
+
+**ONLY EXECUTE IF:** detection indicates `projectType=monorepo`
+
+Before selecting/implementing a task, ensure the task has an explicit workspace scope:
+
+- If the task is local (from `tasks.local.md`):
+  - Read the task block and require `**Workspace:** <path>` (e.g. `apps/storefront`, `apps/backend`).
+  - If missing → **HARD STOP** and ask the user to add `**Workspace:**` to the task before continuing.
+
+- If the task is a Linear issue:
+  - If the issue description contains a workspace path, use it.
+  - Otherwise → **HARD STOP** and ask the user to specify the workspace path for this task.
+
+**Rules:**
+- All commands (install/lint/typecheck/test/build) must be executed **scoped to the workspace**, not the repo root.
+- If the monorepo uses pnpm/yarn/turbo/nx, prefer workspace-scoped commands (e.g., `pnpm -C <workspace> …` or `npm --prefix <workspace> …`).
+
 Step 1 — Select the task
 
 **Support for både local og Linear tasks:**
@@ -111,8 +129,9 @@ Step 1 — Select the task
    - If status not found → guide user to create custom status
 
 3. **Create Linear comment:**
-   - Add comment to Linear issue: "Task started via SDD workflow at [timestamp]"
-   - If task-level spec exists → add comment with spec summary
+   - Add a structured comment to Linear issue:
+     - “Started `<task-id>` via SDD. Branch: `<branch>`. Plan: `<1–3 bullets>`.”
+   - If task-level spec exists → add a second comment with a short spec summary + acceptance focus
 
 **Error Handling:**
 - If Linear MCP unavailable → continue with local mode only
@@ -230,10 +249,13 @@ Before implementation, ensure:
    - If uncommitted changes exist → pause and ask: "Uncommitted changes detected. Commit, stash, or discard?"
    - If untracked files exist → pause and ask: "Untracked files detected. Should they be committed?"
 
-2. Ensure clean main branch:
-   - Checkout main branch (or default branch)
-   - Pull latest changes (if remote exists): `git pull origin main` (or default branch name)
-   - Verify main is clean (no uncommitted changes)
+2. Ensure clean base branch (project-agnostic):
+   - Resolve `defaultBranch` (do not assume `main`) using one of:
+     - Skill (Cursor 2.4+): `/sdd-git-default-branch`
+     - Helper: `.cursor/commands/_shared/branch-detection.md` (if present in the project)
+   - Checkout base branch: `git checkout <default-branch>`
+   - Pull latest changes (if remote exists): `git pull origin <default-branch>`
+   - Verify base is clean (no uncommitted changes)
 
 3. Create task branch:
    - Branch name format: `task/{task-id}-{short-description}` (e.g., `task/t1.2-setup-database`)

package/template/.cursor/commands/task/validate.md

@@ -78,6 +78,14 @@ Ask what evidence exists:
 - Manual verification steps
 - Screenshots, logs, or other proof
 
+## Workspace scope (REQUIRED for monorepos)
+
+**ONLY EXECUTE IF:** detection indicates `projectType=monorepo`
+
+- Require an explicit workspace scope for the task (from `work/backlog/tasks.local.md` `**Workspace:**` or from the Linear issue description).
+- Run validation commands scoped to that workspace only.
+- If workspace scope is missing → **HARD STOP** and require the user to define it (do not run repo-wide validation).
+
 **Documentation Lookup (if framework-specific issue found):**
 
 **ONLY READ IF framework/tool detected or documentation needed:**
@@ -177,21 +185,22 @@ Assess whether the task is:
 1. Pre-merge checks:
    - Verify all changes are committed
    - Run build/test (if applicable)
-   - Check for merge conflicts with main: `git fetch origin main && git merge-base HEAD origin/main`
+   - Resolve `defaultBranch` (do not assume `main`) using `/sdd-git-default-branch` or `branch-detection.md`
+   - Check for merge conflicts with base: `git fetch origin <default-branch> && git merge-base HEAD origin/<default-branch>`
 
-2. Merge to main:
-   - Checkout main (or default branch): `git checkout main`
-   - Pull latest (if remote exists): `git pull origin main`
+2. Merge to base branch:
+   - Checkout base (default branch): `git checkout <default-branch>`
+   - Pull latest (if remote exists): `git pull origin <default-branch>`
    - Merge task branch: `git merge task/{task-id}-{short-description}`
-   - Push to remote (if configured): `git push origin main`
+   - Push to remote (if configured): `git push origin <default-branch>`
 
 3. Post-merge cleanup:
    - Delete local task branch (optional, ask first): `git branch -d task/{task-id}-{short-description}`
-   - Verify main is clean
+   - Verify base branch is clean
 
 **Ask user preference:**
 - "Should I auto-commit on task completion?" (if not already committed)
-- "Should I auto-merge to main on validation?" (if validated)
+- "Should I auto-merge to the base branch on validation?" (if validated)
 - "Should I delete task branch after merge?" (optional)
 
 If follow-up is required:
@@ -226,14 +235,9 @@ Conclude with one of the following outcomes:
    - If status not found → guide user to create custom status
 
 3. **Create Linear comment with validation summary:**
-   - Add comment to Linear issue:
-     ```
-     "Task validated: [result]
-     Acceptance criteria: [summary]
-     Issues found: [list] (if any)
-     Next steps: [list] (if any)"
-     ```
-   - Include relevant context from validation
+   - Add a structured comment to Linear issue (recommended format):
+     - “Validated `<task-id>` via SDD: `<pass/fail>`. Evidence: `<lint/tests/build>`. PR: `<url>` (if any).”
+   - Include acceptance summary (1–3 bullets) and any follow-up actions (if any)
 
 **Error Handling:**
 - If Linear MCP unavailable → continue without Linear update

package/template/.cursor/scripts/{validate-helpers.js → validate-helpers.cjs}

@@ -2,7 +2,7 @@
 
 /**
  * Helper Metadata Validation Script
- * 
+ *
  * Validates helper metadata for consistency and correctness:
  * - All helpers have YAML frontmatter
  * - Section line ranges match actual section markers
@@ -33,17 +33,17 @@ function log(message, color = 'reset') {
 function parseYAMLFrontmatter(content) {
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (!frontmatterMatch) return null;
-  
+
   const frontmatter = {};
   const lines = frontmatterMatch[1].split('\n');
-  
+
   let currentKey = null;
   let currentValue = [];
   let inArray = false;
-  
+
   for (const line of lines) {
     if (line.trim() === '') continue;
-    
+
     // Check for array start
     if (line.match(/^(\s*)([a-z_]+):\s*$/)) {
       if (currentKey) {
@@ -54,13 +54,13 @@ function parseYAMLFrontmatter(content) {
       inArray = true;
       continue;
     }
-    
+
     // Check for array item
     if (inArray && line.match(/^\s*-\s*(.+)$/)) {
       currentValue.push(line.match(/^\s*-\s*(.+)$/)[1]);
       continue;
     }
-    
+
     // Check for key-value
     if (line.match(/^(\s*)([a-z_]+):\s*(.+)$/)) {
       if (currentKey) {
@@ -72,25 +72,25 @@ function parseYAMLFrontmatter(content) {
       inArray = false;
       continue;
     }
-    
+
     // Check for nested structure (sections)
     if (line.match(/^\s+([a-z_]+):/)) {
       // This is a nested key, skip for now (simplified parsing)
       continue;
     }
   }
-  
+
   if (currentKey) {
     frontmatter[currentKey] = currentValue.length === 1 ? currentValue[0] : currentValue;
   }
-  
+
   return frontmatter;
 }
 
 function findSectionMarkers(content) {
   const sections = [];
   const lines = content.split('\n');
-  
+
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     const sectionMatch = line.match(/^## Section: (.+?) \(Lines (\d+)-(\d+)\)$/);
@@ -103,7 +103,7 @@ function findSectionMarkers(content) {
       });
     }
   }
-  
+
   return sections;
 }
 
@@ -111,14 +111,14 @@ function validateHelper(helperFile) {
   const filePath = path.join(HELPERS_DIR, helperFile);
   const content = fs.readFileSync(filePath, 'utf-8');
   const issues = [];
-  
+
   // 1. Check frontmatter exists
   const frontmatter = parseYAMLFrontmatter(content);
   if (!frontmatter) {
     issues.push({ type: 'error', message: 'Missing YAML frontmatter' });
     return { file: helperFile, issues };
   }
-  
+
   // 2. Check required fields
   const requiredFields = ['helper_id', 'load_when', 'sections', 'always_load'];
   for (const field of requiredFields) {
@@ -126,7 +126,7 @@ function validateHelper(helperFile) {
       issues.push({ type: 'error', message: `Missing required field: ${field}` });
     }
   }
-  
+
   // 3. Check section markers match metadata
   const sections = findSectionMarkers(content);
   if (sections.length > 0 && frontmatter.sections) {
@@ -141,23 +141,22 @@ function validateHelper(helperFile) {
       }
     }
   }
-  
+
   return { file: helperFile, frontmatter, sections, issues };
 }
 
 function validateRegistry() {
   const content = fs.readFileSync(METADATA_FILE, 'utf-8');
-  const helperFiles = fs.readdirSync(HELPERS_DIR)
-    .filter(f => f.endsWith('.md') && f !== 'helper-metadata.md');
-  
+  const helperFiles = fs.readdirSync(HELPERS_DIR).filter((f) => f.endsWith('.md') && f !== 'helper-metadata.md');
+
   const registryHelpers = [];
   const registryMatch = content.match(/### ([a-z-]+)\.md/g);
   if (registryMatch) {
-    registryHelpers.push(...registryMatch.map(m => m.replace('### ', '').replace('.md', '')));
+    registryHelpers.push(...registryMatch.map((m) => m.replace('### ', '').replace('.md', '')));
   }
-  
+
   const issues = [];
-  
+
   // Check all helpers are in registry
   for (const helperFile of helperFiles) {
     const helperId = helperFile.replace('.md', '');
@@ -168,7 +167,7 @@ function validateRegistry() {
       });
     }
   }
-  
+
   // Check registry has all helpers
   for (const registryHelper of registryHelpers) {
     if (!helperFiles.includes(`${registryHelper}.md`)) {
@@ -178,20 +177,19 @@ function validateRegistry() {
       });
     }
   }
-  
+
   return { helperFiles, registryHelpers, issues };
 }
 
 function main() {
   log('🔍 Validating Helper Metadata...\n', 'blue');
-  
-  const helperFiles = fs.readdirSync(HELPERS_DIR)
-    .filter(f => f.endsWith('.md') && f !== 'helper-metadata.md');
-  
+
+  const helperFiles = fs.readdirSync(HELPERS_DIR).filter((f) => f.endsWith('.md') && f !== 'helper-metadata.md');
+
   let totalIssues = 0;
   let totalErrors = 0;
   let totalWarnings = 0;
-  
+
   // Validate each helper
   for (const helperFile of helperFiles) {
     const result = validateHelper(helperFile);
@@ -211,11 +209,11 @@ function main() {
       log(`✅ ${helperFile}`, 'green');
     }
   }
-  
+
   // Validate registry
   log('\n📋 Validating Helper Registry...\n', 'blue');
   const registryResult = validateRegistry();
-  
+
   if (registryResult.issues.length > 0) {
     for (const issue of registryResult.issues) {
       if (issue.type === 'error') {
@@ -230,7 +228,7 @@ function main() {
   } else {
     log('✅ Helper registry is consistent', 'green');
   }
-  
+
   // Summary
   log('\n' + '='.repeat(50), 'blue');
   if (totalIssues === 0) {

package/template/.cursor/skills/sdd-commit-unit/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: sdd-commit-unit
+description: Create small, reviewable commits per logical unit of work with consistent messages tied to the task ID. Use during implementation and batch runs.
+metadata:
+  sdd_category: git
+---
+
+# SDD: Commit a Logical Unit
+
+## When to use
+
+- After completing a coherent step (not after every file).
+- Before switching focus or running validation.
+- During batch runs after each “unit” completes.
+
+## Inputs
+
+- Task ID (from `work/backlog/tasks.local.md` or user input)
+- Current diff (`git diff` and `git status`)
+- Commit message style: concise, why-focused, task-linked
+
+## Output contract
+
+Return:
+- `commitCreated`: yes/no
+- `commitHash` (if created)
+- `message`
+- `filesChangedSummary`
+
+## Rules
+
+- Never commit secrets (`.env`, credential files, tokens).
+- If there are no changes, do not create an empty commit.
+- Keep commits small and reviewable; split if multiple concerns.
+
+## Suggested commit message pattern
+
+- Title: `<task-id>: <verb> <scope> (<why>)`
+- Body (optional): 1–3 bullets explaining intent and risk
+
+Example:
+- `t1.2: add branch detection helper (avoid hardcoded main)`

package/template/.cursor/skills/sdd-design-system-bootstrap/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: sdd-design-system-bootstrap
+description: Bootstrap a usable design system early (Tailwind + shadcn/ui) to avoid design babysitting later. Produces spec/07-design-system.md and a UI Definition of Done checklist.
+metadata:
+  sdd_category: design
+---
+
+# SDD: Design System Bootstrap (Tailwind + shadcn/ui)
+
+## When to use
+
+- During `/spec/init` or `/spec/refine` when design direction is unclear or repeatedly causes rework.
+- Before `/spec/plan` so design work can be turned into concrete, non-babysat tasks.
+
+## Inputs (ask if missing)
+
+- Product vibe / adjectives (3–5)
+- Target surfaces (primary screens + whether data-dense)
+- Brand constraints (logo, existing colors, typography)
+- Accessibility target (default: WCAG AA)
+
+## Output contract
+
+Produce or update `spec/07-design-system.md` with:
+- Style direction (do/don’t)
+- Token table (semantic colors, typography, spacing, radius/shadows)
+- Component conventions (shadcn/ui)
+- UI patterns (nav/forms/tables/states)
+- UI Definition of Done checklist
+
+## Rules
+
+- Make it usable, not aspirational.
+- Prefer semantic tokens over raw colors.
+- Keep it compatible with Tailwind + shadcn/ui defaults (can be overridden intentionally).

package/template/.cursor/skills/sdd-git-default-branch/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sdd-git-default-branch
+description: Resolve default/development/production branches consistently across projects. Use before creating task branches, counting commits, creating PRs, or generating diffs.
+metadata:
+  sdd_category: git
+---
+
+# SDD: Resolve Git Default Branch
+
+## When to use
+
+- You are about to create a task branch.
+- You need to compute diffs/commit counts against the base branch.
+- You are about to create or update a PR.
+- You see any workflow text hardcoding `main`/`develop`/`staging` and need to make it project-agnostic.
+
+## Inputs
+
+- Optional: `.sdd/git-config.json` (project-specific config; preferred)
+- Git remote metadata: `origin` HEAD branch (if available)
+- Local/remote branch existence
+
+## Output contract (what you must return)
+
+Return a short structured result:
+
+- `defaultBranch`: the branch to use as PR base and “clean base” checkout
+- `developmentBranch`: optional; defaults to `defaultBranch` if not known
+- `productionBranch`: optional; defaults to `defaultBranch` if not known
+- `source`: `config` | `remoteHead` | `fallback`
+
+## Algorithm (project-agnostic)
+
+1. **Config (highest priority)**: If `.sdd/git-config.json` exists, read:
+   - `default_branch` OR `development_branch` as `defaultBranch`
+   - `development_branch` as `developmentBranch` (fallback: `defaultBranch`)
+   - `production_branch` as `productionBranch` (fallback: `defaultBranch`)
+2. **Remote HEAD**: If `origin` exists, read the remote default branch (e.g., `git remote show origin` and parse `HEAD branch`).
+3. **Fallback**: If remote HEAD is unavailable, pick the first existing branch in this order (local OR remote):
+   - `main`
+   - `master`
+   - `develop`
+4. If nothing is detectable, return `defaultBranch: "main"` and include a warning in your explanation.
+
+## Rules
+
+- Do not assume `staging` exists. If a project uses `staging`, it should be configured in `.sdd/git-config.json`.
+- Never hardcode `main` as “the” default branch in documentation. Use `defaultBranch` (resolved by this skill).
+- If the project has `work/backlog/tasks.local.md`, include the task ID in downstream commit/PR titles (but this skill itself only resolves branches).

package/template/.cursor/skills/sdd-pr-create-or-update/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: sdd-pr-create-or-update
+description: Create or update a PR with correct base branch, task-linked title, and a structured body (changes, testing, acceptance). Use after validation or at milestone boundaries.
+metadata:
+  sdd_category: github
+---
+
+# SDD: Create or Update Pull Request
+
+## When to use
+
+- After `/task/validate` passes (or passes with known exceptions).
+- During `/task/batch` when configured to open PRs per task or per milestone.
+
+## Inputs
+
+- Base branch: resolve via `/sdd-git-default-branch`
+- Task ID + short title
+- Git changes: commits since base branch, `git diff <base>...HEAD --stat`
+- Validation result summary (lint/tests/build)
+
+## Output contract
+
+Return:
+- `action`: created/updated/noop
+- `prUrl` (if created/updated)
+- `baseBranchUsed`
+
+## Body template
+
+Use a structured PR body:
+
+- **Summary**: 1–3 bullets
+- **Test plan**: checklist
+- **Notes / risks**: optional
+
+## Rules
+
+- Never assume base is `main`.
+- Prefer updating an existing PR over creating duplicates.
+- Do not push unless user asked to push (or the workflow explicitly requires it).

package/template/.cursor/skills/sdd-task-preflight/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: sdd-task-preflight
+description: Prepare a task workspace safely before implementation: clean working tree, correct base branch, and task branch naming. Use before /task/start execution work.
+metadata:
+  sdd_category: git
+---
+
+# SDD: Task Preflight (Git Safety)
+
+## When to use
+
+- Right before starting implementation for a task (single task or batch task).
+- When you suspect you’re on the wrong branch or have dirty state.
+
+## Inputs
+
+- Task context (ideally: `taskId`, short description)
+- Repo state: `git status`, current branch, remotes
+- Base branch: resolve via `/sdd-git-default-branch` (preferred) or helper `branch-detection.md`
+
+## Output contract
+
+Return:
+- `baseBranch`
+- `taskBranch`
+- `actionsTaken` (bullets)
+- `blockingIssues` (bullets; empty if none)
+
+## Procedure
+
+1. **Validate working tree is clean**
+   - If dirty/untracked: stop and report as `blockingIssues` (do not auto-stash).
+2. **Resolve `baseBranch`**
+   - Use `/sdd-git-default-branch` to resolve `defaultBranch`.
+3. **Ensure base branch is up to date**
+   - Checkout `baseBranch`
+   - If remote exists: pull latest (`git pull origin <baseBranch>`)
+4. **Create/checkout task branch**
+   - Naming: `task/<task-id>-<short-description>` (kebab-case)
+   - If exists locally: checkout
+   - Else: create from `baseBranch`
+
+## Rules
+
+- Never merge/rebase in preflight.
+- Never commit anything in preflight.
+- Never assume `main`.