@eskoubar95/spec 0.1.4 → 0.1.5

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]
+

package/template/spec/templates/07-design-system.md

@@ -0,0 +1,145 @@
+# Design System (Tailwind + shadcn/ui default)
+
+This document defines the **visual direction, tokens, component conventions, and UI quality gates** for this project.
+It is intended to reduce “design babysitting” by making decisions explicit early.
+
+## Design goals (1–3 bullets)
+
+- [e.g., “Calm, professional dashboard UI with strong information hierarchy.”]
+- [e.g., “Fast to build with shadcn/ui primitives, customized via tokens.”]
+
+## References (2–3 links)
+
+- [Link 1]
+- [Link 2]
+- [Link 3] (optional)
+
+## Style direction
+
+- **Adjectives**: [e.g., minimal, calm, premium, technical, playful]
+- **Do**: [e.g., subtle borders, low saturation, consistent spacing]
+- **Don’t**: [e.g., heavy shadows everywhere, inconsistent radii, random colors]
+
+## Target surfaces
+
+- **Primary**: [e.g., dashboard, editor, settings]
+- **Secondary**: [e.g., marketing pages, onboarding]
+- **Dense data UI?**: [yes/no] (tables, filters, bulk actions)
+
+## UI stack assumptions (edit if different)
+
+- **Styling**: Tailwind CSS
+- **Component library**: shadcn/ui
+- **Icons**: [lucide-react / other]
+- **Typography**: [Inter / other]
+
+## Tokens
+
+### Color tokens (semantic-first)
+
+Define tokens by meaning, not by raw hex usage.
+
+#### Neutral scale
+
+- `background`: [hex]
+- `surface`: [hex]
+- `surfaceMuted`: [hex]
+- `border`: [hex]
+- `textPrimary`: [hex]
+- `textSecondary`: [hex]
+- `textMuted`: [hex]
+
+#### Brand / accent
+
+- `primary`: [hex]
+- `primaryForeground`: [hex]
+- `secondary`: [hex] (optional)
+- `secondaryForeground`: [hex] (optional)
+
+#### Semantic colors
+
+- `success`: [hex]
+- `successForeground`: [hex]
+- `warning`: [hex]
+- `warningForeground`: [hex]
+- `error`: [hex]
+- `errorForeground`: [hex]
+- `info`: [hex]
+- `infoForeground`: [hex]
+
+#### States
+
+- **Focus ring**: [color + thickness]
+- **Disabled**: [opacity + cursor rules]
+- **Hover/active**: [rule of thumb]
+
+### Typography tokens
+
+- **Font family**: [e.g., Inter]
+- **Scale**:
+  - `xs`: [size/line-height]
+  - `sm`: [size/line-height]
+  - `base`: [size/line-height]
+  - `lg`: [size/line-height]
+  - `xl`: [size/line-height]
+- **Weights**: [regular/medium/semibold/bold]
+
+### Spacing tokens
+
+- **Base unit**: 4px (default)
+- **Scale**: 4, 8, 12, 16, 24, 32, 48, 64 (edit as needed)
+
+### Radius + shadow tokens
+
+- **Radius**: `sm`, `md`, `lg` with definitions (or “use shadcn defaults”)
+- **Shadow**: [subtle / medium / none] (define when to use which)
+
+### Motion (optional)
+
+- **Animation duration**: [e.g., 150–250ms]
+- **Easing**: [e.g., ease-out]
+
+## Component conventions (shadcn/ui)
+
+### Phase 1 “must-have” components
+
+- Button, Input, Textarea, Select, Checkbox, RadioGroup, Switch
+- Dialog, Sheet/Drawer, DropdownMenu, Tooltip
+- Tabs, Table, Badge, Card, Skeleton
+- Toast/Sonner, Separator
+
+### Component rules
+
+- Variants must be token-driven (no ad-hoc colors).
+- Every interactive component must have:
+  - hover/active/disabled
+  - focus-visible state
+  - loading state (if async)
+  - error state (if form-related)
+
+## UI patterns
+
+- **Navigation**: [sidebar/topbar/breadcrumb rules]
+- **Forms**: validation rules, error copy tone, required vs optional
+- **Tables**: empty state, loading skeleton, pagination, bulk actions
+- **Empty/error/loading states**: required for primary flows
+
+## Accessibility (minimum)
+
+- **Target**: WCAG AA
+- **Contrast**: document minimum ratios for text and UI elements
+- **Keyboard**: all interactive UI must be reachable and operable
+- **Focus**: visible focus ring everywhere, no focus traps
+- **Screen readers**: labels/roles for inputs, dialogs, menus
+
+## UI Definition of Done (copy into tasks)
+
+- [ ] Matches tokens and component conventions
+- [ ] Responsive: mobile (320px), tablet (768px), desktop (1024px+)
+- [ ] No horizontal scrolling in primary flows
+- [ ] Keyboard navigation works end-to-end
+- [ ] Focus states are visible and consistent
+- [ ] Contrast meets WCAG AA
+- [ ] Empty/loading/error states implemented for the flow
+- [ ] No UI regressions in common paths (verify key screens)
+

package/template/spec/templates/08-infrastructure.md

@@ -0,0 +1,76 @@
+# Infrastructure
+
+## 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
+
+## Monorepo / Workspaces (if applicable)
+
+If this repository is a **monorepo**, document the workspace boundaries explicitly so tasks, validation, and rules can be scoped correctly.
+
+**Workspace map (recommended):**
+
+- Workspace: [path, e.g., `apps/storefront`]
+  - Frontend Framework: [e.g., Next.js]
+  - Language: [e.g., TypeScript]
+  - Build Tool: [e.g., pnpm / npm / yarn]
+  - Notes: [scripts, deployment target, env vars]
+
+- Workspace: [path, e.g., `apps/backend`]
+  - Backend Framework: [e.g., Medusa / FastAPI]
+  - Language: [e.g., TypeScript / Python]
+  - Notes: [DB, services, migrations]
+
+## Hosting
+- Provider: [Provider name]
+- Region: [Region]
+- Pricing: [Free tier/Paid/etc.]
+- URL: [production URL]
+
+## Database
+- Provider: [Provider name]
+- Type: [PostgreSQL/MySQL/MongoDB/etc.]
+- Connection: [Managed/Self-hosted/etc.]
+- Pricing: [Free tier/Paid/etc.]
+
+## External Services
+- Newsletter: [Platform name, API quality, pricing, webhook support]
+- Analytics: [Platform name]
+- Payment: [Platform name]
+- Other: [list]
+
+## CI/CD
+- Provider: [Provider name, e.g., GitHub Actions, CircleCI, GitLab CI]
+- Deployment strategy: [Automatic/Manual/etc.]
+- Branch strategy: [main only/main + staging/etc.]
+
+## GitHub Actions (if using GitHub)
+- Workflows: [List workflow files, e.g., ci.yml, deploy.yml, pr-checks.yml]
+- CI checks: [List checks, e.g., tests, linting, type checking, build]
+- Deployment: [Describe deployment workflow if applicable]
+- PR requirements: [List required PR checks, e.g., tests passing, code review]
+
+## Environment Variables
+- Required: [list of required env vars]
+- Secrets: [list of secret env vars]
+- Optional: [list of optional env vars]
+
+## Known Issues
+- [List any known infrastructure issues or limitations]
+

package/template/spec/templates/09-sitemap.md

@@ -0,0 +1,50 @@
+# Sitemap / Information Architecture
+
+This document prevents “missing pages” by making the UI surface area explicit **before implementation**.
+
+## MVP sitemap (required)
+
+Write the MVP navigation as a tree. Keep it user-facing (not technical routes).
+
+Example:
+
+```text
+/
+  - Landing
+  - Pricing
+  - Sign in
+  - Sign up
+
+/app
+  - Dashboard
+  - Projects
+    - Project details
+  - Settings
+```
+
+## Route notes (optional)
+
+- **Auth-gated areas**: [list pages]
+- **Roles**: [who can see what]
+- **SEO pages**: [list]
+- **Deep links**: [list]
+
+## Page inventory (MVP)
+
+For each page, define the minimum:
+
+- **Page**: [name]
+  - **Goal**: [what user achieves]
+  - **Primary actions**: [1–3]
+  - **Data**: [entities needed]
+  - **States required**: loading / empty / error
+
+## Future pages / Roadmap (park here)
+
+- [Page]
+
+## Planning rule
+
+- Every MVP feature must map to **at least one page** (or an explicit API-only surface).
+- Every page must be represented in tasks (at least: scaffold + basic states).
+

package/template/work/backlog/tasks.local.md

@@ -17,6 +17,8 @@ Each task follows this structure:
 
 **Tags:** [comma-separated tags, e.g., design, frontend, infrastructure]
 
+**Workspace:** [path within repo, e.g., apps/storefront] (optional; REQUIRED for monorepos)
+
 **Milestone:** [Milestone ID, e.g., M1]
 
 **Sprint:** [Sprint ID, e.g., Sprint 1] (optional)
@@ -51,6 +53,8 @@ Each task follows this structure:
 
 **Tags:** infrastructure, setup
 
+**Workspace:** (optional; for monorepos)
+
 **Milestone:** M1
 
 **Acceptance:** 
@@ -75,6 +79,8 @@ Each task follows this structure:
 
 **Tags:** engineering, backend, security
 
+**Workspace:** (optional; for monorepos)
+
 **Milestone:** M1
 
 **Acceptance:**

package/template/work/linear/FALLBACK-STRATEGY.md

@@ -0,0 +1,84 @@
+# Linear MCP Fallback Strategy
+
+This document defines how the SDD workflow should behave when Linear integration is unavailable or a Linear operation fails.
+
+## Goals
+
+- **Never block the SDD workflow** if Linear is unavailable.
+- **Log clearly** what failed (operation + error), and what fallback is used.
+- **Keep local artifacts authoritative** (`work/backlog/*`) even when Linear sync is enabled.
+
+## Detecting Linear mode
+
+Linear mode is enabled when:
+- `work/linear/sync-config.md` exists, and
+- it contains `MODE=linear`
+
+If Linear mode is not enabled, operate in local mode only.
+
+## Connectivity verification
+
+Before critical Linear operations:
+- Read `MCP_CONNECTION_NAME` from `work/linear/sync-config.md` (optional).
+- Run a simple “health” call (e.g. `list_teams`).
+
+If the call fails or times out → treat Linear MCP as unavailable for this run.
+
+## Fallback cases
+
+### 1) MCP connection unavailable
+
+**Behavior:**
+- Continue with **local mode only**.
+- Report: “Linear MCP is unavailable. Continuing in local mode.”
+- Skip all Linear operations (projects/issues/documents/comments/status updates).
+
+### 2) A specific Linear operation fails
+
+**Behavior:**
+- Log the failure clearly:
+  - operation name (e.g. `create_issue`, `update_issue`, `create_project`)
+  - the error message
+- Continue the workflow in **local mode** for the rest of the run (do not retry endlessly).
+- Allow a user-initiated retry later (next command run).
+
+### 3) Resource not found (status/label/project/issue)
+
+**Behavior:**
+- **Status not found**: guide user to create the status in Linear (or update `sync-config.md` to use a status ID).
+- **Label not found**: try to create the label automatically; if that fails, guide user to create it manually in Linear.
+- **Project not found**: create it only if `AUTO_CREATE_PROJECTS=true` and user confirmed creation.
+- **Issue not found**: guide user to verify the issue exists or re-run `/spec/plan` to re-sync tasks.
+
+### 4) Partial failure (some operations succeed)
+
+**Behavior:**
+- Keep the successful operations.
+- Log what failed.
+- Do not rollback.
+
+## Recovery strategy
+
+When Linear becomes available again:
+- Re-run `/spec/plan` to ensure milestones/projects and tasks/issues are in sync.
+- Re-run `/task/start` or `/task/validate` to re-apply status/comments for the active task.
+
+## Where to log
+
+When in Linear mode:
+- Add a brief **Linear comment** on the issue for:
+  - task start
+  - task validation result
+  - errors (if any)
+
+Always keep local artifacts updated:
+- `work/backlog/tasks.local.md` remains the primary source of truth for tasks and status in local mode.
+
+## Related docs
+
+- `work/linear/SETUP.md`
+- `work/linear/sync-config.md`
+- `work/linear/LABEL-MAPPING-GUIDE.md`
+- `.cursor/commands/_shared/linear-automation.md`
+- `.cursor/commands/_shared/linear-helpers.md`
+

package/template/work/linear/LABEL-MAPPING-GUIDE.md

@@ -0,0 +1,72 @@
+# Linear Label + Status Mapping Guide
+
+This guide defines how SDD task metadata maps to Linear statuses, labels, and projects.
+
+## Status mapping
+
+SDD status values (from `work/backlog/tasks.local.md`) map to Linear issue statuses via `work/linear/sync-config.md`:
+
+- `backlog` → `STATUS_BACKLOG`
+- `in-progress` → `STATUS_IN_PROGRESS`
+- `done` → `STATUS_DONE`
+- `blocked` → `STATUS_BLOCKED`
+
+Use **status names** (recommended) unless you need fixed status IDs.
+
+## Label strategy (project-agnostic)
+
+### 1) Source of truth: task tags
+
+Prefer using `**Tags:**` in `work/backlog/tasks.local.md`.
+
+Example:
+
+```markdown
+**Tags:** backend, security, documentation
+```
+
+**Rule:** Each tag can be used as a Linear label name.
+
+- If `LABEL_PREFIX` is set in `sync-config.md`, prepend it to every auto-assigned label.
+- If a label does not exist, the system may try to create it. If creation fails, guide the user to create it manually.
+
+### 2) Recommended label groups (optional)
+
+These are suggestions, not requirements. Your team can rename them freely.
+
+- **Core / domain labels**: `backend`, `frontend`, `infrastructure`, `security`, `design`, `documentation`, `performance`, `observability`, `integration`
+- **Type labels (only when true)**: `feature`, `bug`, `improvement`
+- **Decision label**: `decision` (for explicit choices / comparisons)
+- **Release label**: `release`
+
+### 3) Avoid default “Feature everywhere”
+
+Do **not** auto-add a “feature” label to all issues by default.
+Only add `feature` if the task is actually a new feature (best: include `feature` explicitly in `**Tags:**`).
+
+## Projects / milestones
+
+If `AUTO_CREATE_PROJECTS=true` in `sync-config.md`:
+- Each milestone in `work/backlog/milestones.md` can be represented as a Linear project.
+- Tasks link to projects via `**Milestone:** Mx` in `tasks.local.md`.
+
+## Comment templates (recommended)
+
+### Task started
+
+- “Started `<task-id>` via SDD. Branch: `<branch>`. Plan: `<1–3 bullets>`.”
+
+### Task validated
+
+- “Validated `<task-id>` via SDD: `<pass/fail>`. Evidence: `<lint/tests/build>`. PR: `<url>` (if any).”
+
+### Error / fallback
+
+- “Linear operation `<op>` failed: `<error>`. Continuing in local mode.”
+
+## Related docs
+
+- `work/linear/SETUP.md`
+- `work/linear/sync-config.md`
+- `work/linear/FALLBACK-STRATEGY.md`
+