@eskoubar95/spec 0.1.3 → 0.1.5

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

package/template/work/linear/SETUP.md

@@ -0,0 +1,75 @@
+# Linear Setup Guide
+
+This guide walks you through setting up Linear integration with the SDD workflow.
+
+## Prerequisites
+
+- A Linear workspace + team
+- Linear MCP configured in Cursor
+- Access to Linear Settings
+
+## Hard stop (recommended)
+
+If you enable Linear mode (`MODE=linear`), `/spec/plan` treats missing required status mappings as a **hard stop** for Linear sync:
+
+- Required keys in `work/linear/sync-config.md`:
+  - `STATUS_BACKLOG`
+  - `STATUS_IN_PROGRESS`
+  - `STATUS_DONE`
+  - `STATUS_BLOCKED`
+
+## Step 1: Create/choose a Linear team
+
+1. Create a team (if needed)
+2. Note the team ID for `work/linear/sync-config.md` (optional)
+
+## Step 2: Ensure statuses exist
+
+1. Go to Linear Settings → Statuses
+2. Ensure you have statuses that match your desired mapping (defaults: Backlog, In Progress, Done, Blocked)
+3. Use status **names** in `sync-config.md` (recommended), or IDs if you need fixed UUIDs
+
+## Step 3: Ensure labels exist (optional)
+
+Labels can be created automatically when missing, but you can also create them manually in Linear Settings → Labels.
+
+## Step 4: Configure sync config
+
+1. Create/update `work/linear/sync-config.md`
+2. Set `MODE=linear`
+3. Optionally set:
+   - `MCP_CONNECTION_NAME` (if you have multiple Linear MCP connections)
+   - `DEFAULT_TEAM_ID`
+4. Set status mapping keys:
+   - `STATUS_BACKLOG`, `STATUS_IN_PROGRESS`, `STATUS_DONE`, `STATUS_BLOCKED`
+5. Enable optional automation:
+   - `AUTO_ASSIGN_LABELS=true`
+   - `AUTO_CREATE_PROJECTS=true`
+   - `AUTO_CREATE_DOCUMENTS=true`
+
+## Step 5: Tag-driven label mapping (recommended)
+
+Use `**Tags:**` in `work/backlog/tasks.local.md` to drive labels:
+- See `work/linear/LABEL-MAPPING-GUIDE.md`
+
+## Step 6: Test
+
+- Run `/spec/plan` (creates projects/issues/docs if enabled)
+- Run `/task/start` and `/task/validate` on a Linear issue ID to verify status + comments
+
+## Troubleshooting
+
+- Fallback behavior: `work/linear/FALLBACK-STRATEGY.md`
+
+## What SDD can do automatically (once configured)
+
+- **/spec/plan**: create milestone projects (optional), create/update task issues, create/update spec documents (optional)
+- **/task/start**: update status + add a structured “Started …” comment
+- **/task/validate**: update status + add a structured “Validated …” comment
+
+## What the user must do manually
+
+- Configure the Linear MCP connection in Cursor (and provide `MCP_CONNECTION_NAME` if multiple)
+- Ensure your desired statuses exist in Linear (or adjust mappings)
+- Decide label taxonomy (recommended: `**Tags:**` in `work/backlog/tasks.local.md` → labels; see `LABEL-MAPPING-GUIDE.md`)
+

package/template/work/linear/sync-config.md

@@ -0,0 +1,86 @@
+# Linear Sync Configuration
+
+This file configures Linear MCP integration with the SDD workflow.
+
+## Mode
+
+Create this file and set:
+
+```
+MODE=linear
+```
+
+If the file does not exist (or MODE is not `linear`), the system runs in local mode only.
+
+## MCP Connection Configuration (optional)
+
+If you have multiple Linear MCP connections in Cursor, specify which one to use:
+
+```
+MCP_CONNECTION_NAME=linear
+```
+
+## Team Configuration (optional)
+
+Assign projects/issues to a default team:
+
+```
+DEFAULT_TEAM_ID=[team-id]
+```
+
+## Status Mapping
+
+Map SDD statuses to Linear statuses (names recommended):
+
+**Required when `MODE=linear` (hard requirement for `/spec/plan` Linear sync):**
+- `STATUS_BACKLOG`
+- `STATUS_IN_PROGRESS`
+- `STATUS_DONE`
+- `STATUS_BLOCKED`
+
+```
+STATUS_BACKLOG=Backlog
+STATUS_IN_PROGRESS=In Progress
+STATUS_DONE=Done
+STATUS_BLOCKED=Blocked
+```
+
+## Labels
+
+Enable tag-driven label assignment:
+
+```
+AUTO_ASSIGN_LABELS=true
+LABEL_PREFIX=
+```
+
+See `work/linear/LABEL-MAPPING-GUIDE.md`.
+
+## Projects
+
+Enable milestone → Linear project automation:
+
+```
+AUTO_CREATE_PROJECTS=true
+```
+
+## Documents
+
+Enable spec → Linear document automation:
+
+```
+AUTO_CREATE_DOCUMENTS=true
+```
+
+## Cycles (optional)
+
+```
+USE_CYCLES=false
+ACTIVE_CYCLE_ID=[cycle-id]
+```
+
+## Fallbacks + troubleshooting
+
+- `work/linear/FALLBACK-STRATEGY.md`
+- `work/linear/SETUP.md`
+