@eskoubar95/spec 0.1.3 → 0.1.5

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

package/template/.cursor/skills/sdd-validation-suite/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: sdd-validation-suite
+description: Run a lightweight, project-agnostic validation suite (lint, typecheck, build, tests when present) and summarize pass/fail with actionable error highlights.
+metadata:
+  sdd_category: validation
+---
+
+# SDD: Validation Suite
+
+## When to use
+
+- During `/task/validate` before opening/updating a PR.
+- During `/task/batch` after each task (and optionally after each logical unit).
+
+## Inputs
+
+- Project type + tooling (from detection or repo files)
+- Available scripts (package.json, makefile, etc.)
+- Optional: workspace scope (monorepo), e.g. `apps/storefront`
+
+## Output contract
+
+Return a compact report:
+- `lint`: pass/fail/skipped
+- `typecheck`: pass/fail/skipped
+- `tests`: pass/fail/skipped
+- `build`: pass/fail/skipped
+- `highlights`: top 3 actionable errors (if any)
+
+## Execution strategy (project-agnostic)
+
+- If JS/TS: prefer `npm run lint`, `npm run typecheck`, `npm test`, `npm run build` when scripts exist.
+- If Python: prefer `ruff`, `mypy`, `pytest` when configured.
+- If unknown: run the minimum safe checks available, and clearly mark skipped items.
+
+**Monorepo rule (if applicable):**
+- If the repo is a monorepo, run commands **scoped to the task workspace** (do not run repo-wide by default).
+- Examples:
+  - `pnpm -C <workspace> run lint`
+  - `npm --prefix <workspace> run test`
+  - `yarn --cwd <workspace> test`
+- If no workspace scope is provided for a monorepo task, treat validation as **blocked** until scope is clarified.
+
+## Rules
+
+- Do not invent commands that don’t exist.
+- If a step fails, stop and report errors before continuing.

package/template/spec/00-root-spec.md

@@ -19,6 +19,14 @@ What is the main value delivered to users?
 What feels in-scope right now?
 What explicitly feels out-of-scope?
 
+## 5.1 MVP vs Future (scope locking)
+
+### MVP (ship target)
+- [List the minimum set of capabilities required to ship an MVP.]
+
+### Future ideas / Roadmap (park here)
+- [If your initial prompt includes visionary “later” ideas, list them here so they don’t accidentally become MVP scope.]
+
 ## 6. Open Questions
 List uncertainties, assumptions, or things that need clarification.
 
@@ -32,5 +40,6 @@ Anything else discovered during discussion or research.
 If applicable, reference:
 - `spec/01-prd.md` (if PRD was created)
 - `spec/02-architecture.md` (if architecture is documented)
+- `spec/06-acceptance.md` (MVP ship checklist / definition of done)
 - `spec/07-design-system.md` (if design is critical)
 - `spec/08-infrastructure.md` (if infrastructure is critical)

package/template/spec/templates/02-architecture.md

@@ -0,0 +1,64 @@
+# Architecture
+
+## System Overview
+High-level description of system architecture and how components interact.
+
+## Component Architecture
+- Frontend: [Description]
+- Backend/API: [Description]
+- Database: [Description]
+- External Services: [Description]
+
+## Data Flow
+How data moves through the system:
+- User actions → [flow description]
+- Data fetching → [flow description]
+- Mutations → [flow description]
+
+## Design Patterns
+Architecture patterns used:
+- [Pattern name]: [Description and rationale]
+
+## Technology Stack
+
+Document the technologies, frameworks, and tools used in this project. This is the source of truth for framework/tool detection and rule activation.
+
+**Format:**
+- Frontend Framework: [Framework name, e.g., Next.js, Vite, React]
+- Backend Framework: [Framework name, e.g., Express, FastAPI, Flask]
+- CMS: [CMS name, e.g., Payload CMS, Strapi]
+- Database: [Database name, e.g., PostgreSQL, MongoDB]
+- Build Tool: [Build tool name, e.g., Vite, Webpack]
+- Language: [Language name, e.g., TypeScript, Python]
+- Other: [List other tools/libraries]
+
+**Example:**
+- Frontend Framework: Next.js
+- CMS: Payload CMS
+- Database: PostgreSQL
+- Build Tool: Vite (for admin)
+- Language: TypeScript
+
+**Note:** If tech stack is documented here, it should also be referenced in `spec/08-infrastructure.md` for consistency.
+
+## API Design (if applicable)
+- API structure: [Description]
+- Authentication: [Description]
+- Error handling: [Description]
+
+## Security Architecture (if critical)
+- Authentication flow: [Description]
+- Authorization: [Description]
+- Data protection: [Description]
+
+## Scalability Considerations
+- Current scale: [Description]
+- Future scale: [Description]
+- Scaling strategy: [Description]
+
+## CI/CD Architecture (if applicable)
+- CI pipeline: [Description of CI workflow]
+- CD pipeline: [Description of CD workflow]
+- Testing strategy: [Unit tests, integration tests, E2E tests]
+- Quality gates: [Required checks before merge/deploy]
+

package/template/spec/templates/06-acceptance.md

@@ -0,0 +1,59 @@
+# Acceptance Criteria / Ship Checklist
+
+This document defines what “done” means for the **MVP** (and optionally later phases).
+Use it as the project’s **ship gate** during planning and validation.
+
+## MVP definition (1–5 bullets)
+
+- [What must be true to call the MVP shipped?]
+
+## Success criteria (measurable if possible)
+
+- [Metric / outcome]
+
+## Scope boundaries
+
+### In scope (MVP)
+- [Feature / capability]
+
+### Out of scope (MVP)
+- [Feature / capability]
+
+### Future ideas / Roadmap (park here)
+- [Item]
+
+## Non-functional requirements (MVP)
+
+- **Performance**: [e.g., pages load < 2s on mid-tier device]
+- **Reliability**: [e.g., error budget / retries]
+- **Security**: [e.g., auth, roles, audit trail]
+- **Accessibility**: [e.g., WCAG AA]
+- **Privacy/Compliance**: [if applicable]
+
+## Quality gates (must pass to ship MVP)
+
+- [ ] Key user journeys verified end-to-end
+- [ ] Error/empty/loading states implemented for primary flows
+- [ ] Logging/monitoring in place (minimum viable observability)
+- [ ] Data migrations/backups strategy (if DB)
+- [ ] Security basics covered (auth, access control, secrets handling)
+- [ ] CI checks passing (lint/typecheck/tests/build as applicable)
+- [ ] Deployment pipeline ready (preview + production)
+
+## Test plan (MVP)
+
+- **Manual smoke tests**:
+  - [Flow 1]
+  - [Flow 2]
+- **Automated tests**:
+  - Unit: [yes/no]
+  - Integration: [yes/no]
+  - E2E: [yes/no]
+
+## Release plan (MVP)
+
+- **Rollout**: [gradual/full]
+- **Rollback**: [plan]
+- **Monitoring**: [what to watch]
+- **Support**: [who responds to incidents]
+