sddx-workflow 0.6.0

package/templates/copilot-prompts/ask.prompt.md

@@ -0,0 +1,10 @@
+---
+description: Research and exploration — no code changes
+mode: agent
+---
+
+Execute the /ask command defined in .sdd/workflow.md.
+
+Research and exploration only — do not modify any files. Read, analyze, and summarize findings with explicit options or recommendations.
+
+Topic: ${input:topic}

package/templates/copilot-prompts/assume.prompt.md

@@ -0,0 +1,12 @@
+---
+description: Surface all assumptions before acting — stop for confirmation
+mode: agent
+---
+
+Execute the /assume command defined in .sdd/workflow.md.
+
+List every assumption being made about the task, codebase state, and technical decisions.
+For each: what you're assuming, why, and what changes if it's wrong.
+Stop and wait for confirmation before proceeding.
+
+Context: ${input:context}

package/templates/copilot-prompts/bootstrap.prompt.md

@@ -0,0 +1,11 @@
+---
+description: Populate project context via interview or codebase scan
+mode: agent
+---
+
+Execute the /bootstrap command defined in .sdd/workflow.md.
+
+If the project already has code, scan the codebase first (read structure, package files, schema, routes), infer what you can, then ask only about what the code cannot answer.
+If it's a new project, ask the 6 interview questions defined in workflow.md one at a time.
+
+Present the full draft of .sdd/project-overview.md and .sdd/conventions.md for approval before writing any file.

package/templates/copilot-prompts/bugfix.prompt.md

@@ -0,0 +1,12 @@
+---
+description: Reproduce → diagnose → fix → validate
+mode: agent
+---
+
+Execute the /bugfix command defined in .sdd/workflow.md.
+
+Follow the stages in order without skipping: Reproduce → Diagnose → Fix → Validate.
+Stop after Reproduce if the bug cannot be confirmed with a test or repro case.
+Escalate to /spec-new if the fix scope exceeds ~1 file or ~50 lines.
+
+Bug or error: ${input:bug}

package/templates/copilot-prompts/finish.prompt.md

@@ -0,0 +1,10 @@
+---
+description: Stage files and generate a conventional commit message
+mode: agent
+---
+
+Execute the /finish command defined in .sdd/workflow.md.
+
+Run git status and git diff. Stage all relevant files (exclude .env*, build artifacts, scratch files). Determine the commit type. Draft a conventional commit message following the format in workflow.md — one overview sentence, detailed bullets with reasoning, optional footer for non-obvious context.
+
+Stop and present the staged file list and commit message for approval before committing.

package/templates/copilot-prompts/refactor.prompt.md

@@ -0,0 +1,10 @@
+---
+description: Restructure without changing external behavior
+mode: agent
+---
+
+Execute the /refactor command defined in .sdd/workflow.md.
+
+Run existing tests first to establish a green baseline. Implement in small steps — tests must stay green throughout. No new features or bug fixes mixed in.
+
+Target: ${input:target}

package/templates/copilot-prompts/review.prompt.md

@@ -0,0 +1,10 @@
+---
+description: Final audit before closing a spec
+mode: agent
+---
+
+Execute the /review command defined in .sdd/workflow.md.
+
+Verify: all goals (G1, G2…) satisfied, every acceptance scenario has a passing test, full test suite passes, no out-of-scope changes, no speculative code, implementation is the simplest that meets requirements.
+
+Spec: ${input:specName}

package/templates/copilot-prompts/spec-new.prompt.md

@@ -0,0 +1,9 @@
+---
+description: Scaffold a spec folder for a new feature
+mode: agent
+---
+
+Execute the /spec-new command defined in .sdd/workflow.md.
+
+Create a specs/${input:featureName}/ folder by copying the three template files from specs/_template/.
+Replace <Feature Name> in each file title with the actual feature name.

package/templates/copilot-prompts/spec-plan.prompt.md

@@ -0,0 +1,9 @@
+---
+description: Generate technical plan — stops for approval before any code
+mode: agent
+---
+
+Execute the /spec-plan command defined in .sdd/workflow.md.
+
+Read specs/${input:specName}/1-requirements.md, run /assume to surface assumptions, then draft the technical plan in specs/${input:specName}/2-plan.md.
+Stop for explicit approval before writing any implementation code.

package/templates/copilot-prompts/spec-tasks.prompt.md

@@ -0,0 +1,10 @@
+---
+description: Execute approved plan one task at a time, TDD-first
+mode: agent
+---
+
+Execute the /spec-tasks command defined in .sdd/workflow.md.
+
+Read the approved specs/${input:specName}/2-plan.md and execute tasks one at a time.
+Write the test first (red), implement until green, run the full suite, then move to the next task.
+Stop immediately if tests fail or a task reveals new scope.

package/templates/cursor-rules/sddx-workflow.mdc

@@ -0,0 +1,27 @@
+---
+description: SDD Protocol — read before starting any task in this project
+alwaysApply: true
+---
+
+This project uses the SDD Protocol. Before starting any task, read:
+
+1. `.sdd/workflow.md` — all commands, ceremony levels, and stop points
+2. `.sdd/project-overview.md` — what this app is, its non-goals, and domains
+3. `.sdd/conventions.md` — project-specific conventions and patterns
+
+## Available commands
+
+| Command | Purpose |
+|---|---|
+| `/bootstrap` | Populate project context — interview or codebase scan |
+| `/ask` | Research only — no code changes |
+| `/assume` | List assumptions and stop for confirmation |
+| `/bugfix` | Reproduce → diagnose → fix → validate |
+| `/refactor` | Restructure without behavior change |
+| `/spec-new` | Scaffold a spec folder |
+| `/spec-plan` | Generate technical plan — stop for approval |
+| `/spec-tasks` | Execute plan one task at a time, TDD-first |
+| `/review` | Final audit before closing |
+| `/finish` | Stage files and generate commit message |
+
+Full definitions for each command are in `.sdd/workflow.md`.

package/templates/domains/auth.md

@@ -0,0 +1,31 @@
+# Domain: Auth
+
+## Responsibility
+
+Authentication and session management.
+
+## Boundaries
+
+- Owns: login, logout, session tokens, password reset flows
+- Does NOT own: user profile data, role-based permissions (see roles domain)
+
+## Key Concepts
+
+- **Session**: short-lived token, validated server-side on every request
+- **Refresh token**: long-lived, rotated on use
+- **Auth state**: derived on the server per request — never trusted from client payload
+
+## Critical Rules
+
+- Never log tokens, passwords, or raw session data
+- Validate session on the server before acting on user identity — never trust client-supplied user IDs
+- Auth failures return generic errors to the client (no user enumeration)
+- Password reset tokens are single-use and expire
+
+## Files
+
+<!-- List key files once the domain is built:
+- lib/auth/session.ts
+- app/_actions/auth.ts
+- middleware.ts
+-->

package/templates/domains/email.md

@@ -0,0 +1,30 @@
+# Domain: Email / Notifications
+
+## Responsibility
+
+Transactional emails and in-app notifications.
+
+## Boundaries
+
+- Owns: email templates, notification dispatch, delivery status
+- Does NOT own: user preferences for notification opt-in/out (see user-preferences domain)
+
+## Key Concepts
+
+- **Transactional email**: triggered by a user action (welcome, reset, receipt)
+- **Delivery status**: sent → delivered → opened, tracked via provider webhooks
+
+## Critical Rules
+
+- Send emails via a queue — never block a request on email delivery
+- Marketing emails must include an unsubscribe link (CAN-SPAM / GDPR)
+- Never include sensitive data (tokens, PII) in email subject lines
+- Delivery failures are non-fatal — log and alert, don't crash the originating flow
+
+## Files
+
+<!-- List key files once the domain is built:
+- lib/email/client.ts
+- lib/email/templates/
+- app/_actions/notifications.ts
+-->

package/templates/domains/payments.md

@@ -0,0 +1,32 @@
+# Domain: Payments
+
+## Responsibility
+
+Payment processing, subscriptions, and billing.
+
+## Boundaries
+
+- Owns: payment intents, subscriptions, invoices, provider webhooks
+- Does NOT own: user accounts, product catalog
+
+## Key Concepts
+
+- **Payment Intent**: server-side object representing a charge attempt
+- **Webhook**: provider event — must be verified with signature before processing
+- **Idempotency key**: required on every payment mutation to prevent double-charges
+
+## Critical Rules
+
+- Never log card data, raw tokens, or payment provider secrets
+- Always verify webhook signatures before processing events
+- Include an idempotency key on every payment mutation
+- Use server-side API keys only — never expose secret keys to the client
+- Failed payments are events to handle, not errors to throw
+
+## Files
+
+<!-- List key files once the domain is built:
+- lib/payments/stripe.ts
+- app/api/webhooks/stripe/route.ts
+- app/_actions/payments.ts
+-->

package/templates/domains/storage.md

@@ -0,0 +1,30 @@
+# Domain: Storage
+
+## Responsibility
+
+File upload, storage, and retrieval.
+
+## Boundaries
+
+- Owns: upload flows, signed URLs, file metadata
+- Does NOT own: access permissions (enforced via storage policies), rendering/display
+
+## Key Concepts
+
+- **Signed URL**: temporary, scoped URL for accessing or uploading a file
+- **Bucket**: top-level container — one per access pattern (public vs. private)
+- **Storage policy**: access rules applied at the storage layer — always configured
+
+## Critical Rules
+
+- Private files are always served via signed URLs, never direct bucket access
+- Validate file type and size on the server, not just the client
+- Storage policies must match the application-level permission model
+- Scan or validate uploads before making them accessible to other users
+
+## Files
+
+<!-- List key files once the domain is built:
+- lib/storage/client.ts
+- app/_actions/upload.ts
+-->

package/templates/project-overview.md

@@ -0,0 +1,31 @@
+# Project Overview
+
+<!-- Populated by /bootstrap. Update this file as the project evolves.
+     The AI agent reads this before starting any task. -->
+
+## What This App Does
+
+<!-- One paragraph: problem solved, target user, core value proposition. -->
+
+## What It Does NOT Do
+
+<!-- Explicit non-goals. As important as the goals — prevents scope creep
+     at the product level, not just the task level. -->
+
+## Main Domains
+
+<!-- The primary business domains and what each one owns.
+     Example:
+     - Auth — session management, login/logout, password reset
+     - Orders — creation, status transitions, fulfillment
+     - Inventory — stock levels, reservations, restocking -->
+
+## Architecture Decisions
+
+<!-- Key decisions already locked in: why this stack, why this structure,
+     constraints that must not be violated. -->
+
+## Definition of Done
+
+<!-- What "production ready" means for this project:
+     performance targets, security requirements, compliance, accessibility. -->

package/templates/specs/_template/1-requirements.md

@@ -0,0 +1,81 @@
+# Requirements: <Feature Name>
+
+## Status
+
+- [ ] Draft
+- [ ] Reviewed
+- [ ] Ready for /spec-plan — all open questions resolved, all scenarios written
+
+---
+
+## Problem Statement
+
+<!-- Who has this problem? What is the pain? How often does it happen?
+     What is the cost of NOT solving it?
+
+     ✗ Weak:  "Users want to see their files better."
+     ✓ Strong: "Users who manage 100+ files have no way to know which files
+               they recently opened — they re-navigate from scratch every session,
+               which wastes time and causes them to re-open the wrong version." -->
+
+## Goals
+
+<!-- Label each goal so plans and tasks can reference them by ID.
+     Write in measurable, user-visible terms.
+     ✗ Weak:  "Improve the file browsing experience."
+     ✓ Strong: "Users can see the last-opened timestamp on any file." -->
+
+- **G1**:
+- **G2**:
+- **G3**: <!-- add or remove lines as needed -->
+
+## Non-Goals
+
+<!-- Explicitly state what this does NOT cover.
+     This section is as important as Goals — it prevents scope creep before planning starts.
+
+     Example:
+     - Does not include sorting files by last-opened date (separate feature)
+     - Does not track access history — only the most recent timestamp
+     - Does not apply to folders -->
+
+## Acceptance Criteria
+
+<!-- Each scenario is a verifiable contract. Write them so a test can be derived
+     directly from the prose. Name real fields, status codes, UI elements, routes.
+
+Scenario: file that has been opened shows its last-opened timestamp
+  Given: a file has been opened at least once (last_accessed_at is not null)
+  When: the user opens the file info modal
+  Then: a "Last opened" row is visible with the formatted timestamp
+    And: the timestamp matches the most recent recorded access time
+
+Scenario: file that has never been opened hides the timestamp row
+  Given: a file has never been opened (last_accessed_at is null)
+  When: the user opens the file info modal
+  Then: the "Last opened" row is not rendered
+
+Scenario: <add one scenario per distinct behavior>
+  Given: <precondition — system state before the action>
+  When: <action or event that triggers the behavior>
+  Then: <primary expected outcome>
+    And: <secondary outcome, if any>
+-->
+
+## Constraints
+
+<!-- Group by type. Be explicit — vague constraints produce unexpected tradeoffs.
+
+     Technical:  "Must not add a DB migration — the column already exists with a default."
+     Business:   "Must ship before the Q2 demo on May 15."
+     UX:         "Must match the existing row layout in the info modal — no redesign." -->
+
+## Open Questions
+
+<!-- Mark each question by whether it blocks planning or can be decided during it.
+
+     ⛔ Blocking — /spec-plan cannot start until this is resolved:
+        Does folder navigation count as "opening" a file?
+
+     ⚠️ Non-blocking — can be decided during planning with a reasonable default:
+        Should the timestamp be relative ("3 days ago") or absolute ("Apr 12, 14:30")? -->

package/templates/specs/_template/2-plan.md

@@ -0,0 +1,128 @@
+# Technical Plan: <Feature Name>
+
+## Status
+
+- [ ] Draft
+- [ ] **Approved** ← AI must not write code until this is checked
+
+---
+
+## Goals This Plan Addresses
+
+<!-- List the goal IDs from 1-requirements.md that this plan covers.
+     If a goal is out of scope for this plan, say so explicitly.
+
+     G1 ✓ — covered by Tasks 1–2
+     G2 ✓ — covered by Task 3
+     G3 ✗ — out of scope for this plan (deferred to specs/payments-v2/) -->
+
+## Assumptions
+
+<!-- Every assumption that shapes this plan. Format: what + why + impact if false.
+     Run /assume before writing this section — list what came up there.
+
+     1. **`last_accessed_at` column already exists on `files`** — confirmed in schema.ts.
+        If false: a migration is required before any task in this plan can run.
+
+     2. **Fire-and-forget is acceptable for access recording** — a missed event
+        is not a product defect for this use case.
+        If false: need a queue with guaranteed delivery (significant scope increase). -->
+
+## Approach
+
+<!-- The simplest solution that satisfies the requirements. State it directly.
+     If you considered a simpler approach and rejected it, say why in one line.
+
+     Example: "A dedicated POST /api/files/[id]/access endpoint that issues a
+     targeted UPDATE on last_accessed_at only, leaving updated_at untouched.
+     Alternative: updating last_accessed_at in the existing PATCH /api/files/[id]
+     — rejected because it would bump updated_at on every read, corrupting
+     the 'modified' timestamp shown to users." -->
+
+## Tradeoffs
+
+<!-- Conscious sacrifices the chosen approach makes. Only include if they exist.
+     Format: what we gain → what we give up → why that's acceptable here.
+
+     Example:
+     - Fire-and-forget for access recording → we may miss an event if the request
+       fails silently → acceptable because a missed timestamp is not a product defect;
+       showing a slightly stale "last opened" is better than adding latency to every open.
+     - Separate POST endpoint instead of reusing PATCH → one extra HTTP round-trip
+       per file open → acceptable because it keeps updated_at semantics clean,
+       which is more important than saving a request.
+
+     If the approach has no meaningful tradeoffs, write "none." -->
+
+## Components Affected
+
+<!-- Every file that will be modified. Distinguish writes from read-only references.
+
+     New:      app/api/files/[id]/access/route.ts
+     Modified: components/file-manager/itemButton.tsx — call recordFileAccess on open
+     Modified: components/file-manager/FileInfoModal.tsx — add "Last opened" row
+     Reference (no changes): lib/db/schema.ts — verify column type only -->
+
+## New Artifacts
+
+<!-- New files, types, DB objects, or migrations that don't exist yet.
+
+     File:      lib/file-manager/recordFileAccess.ts — client-side fire-and-forget helper
+     Migration: none — column already exists
+     Type:      none — reuses existing FileRecord -->
+
+## What This Plan Does NOT Do
+
+<!-- Mirror the non-goals from 1-requirements.md. Keeps the agent from drifting.
+
+     - Does not sort files by last-opened date
+     - Does not track access history — only the single most recent timestamp
+     - Does not apply to folders — folder navigation is intentionally excluded -->
+
+## External Dependencies
+
+<!-- New packages, APIs, or services this plan introduces. If none, write "none". -->
+
+## Risks & Open Questions
+
+<!-- Technical risks that could change this plan. Unresolved items block approval.
+
+     Risk: concurrent writes to last_accessed_at from multiple tabs.
+     → Acceptable — last-write-wins is fine; no ordering guarantee needed.
+
+     Open: should the client retry the POST if it fails silently?
+     → Decision needed before Task 2 starts. -->
+
+## Abort Criteria
+
+<!-- Conditions that require stopping /spec-tasks and returning to this plan.
+     Define them before starting — not when you're already stuck mid-execution.
+
+     - Any assumption above is found to be false
+     - recordFileAccess introduces measurable latency on file open (> 50ms p95)
+     - A component listed in "Components Affected" has been significantly refactored
+       since this plan was written, changing its interface
+     - A task requires touching files not listed here -->
+
+## Verification
+
+<!-- How to confirm each task is done. Link explicitly to scenarios in 1-requirements.md.
+
+     Task 1: POST /api/files/[id]/access returns 200 and updates only last_accessed_at
+             (run: check DB row — last_accessed_at changed, updated_at unchanged)
+     Task 2: opening a file via any of the four paths triggers the POST
+             (run: network tab or test spy — POST fires on lightbox, drawer, viewer, canvas)
+     Task 3: "Scenario: file that has been opened…" and "Scenario: file that has
+             never been opened…" both pass as integration tests -->
+
+## Task Count Estimate
+
+<!-- Rough count: N tasks -->
+
+---
+
+## Approval
+
+Date:
+Approved by:
+Notes:

package/templates/specs/_template/3-tasks.md

@@ -0,0 +1,53 @@
+# Tasks: <Feature Name>
+
+## Status
+
+Plan approved: <!-- date -->
+
+---
+
+## Rules
+
+- One task at a time — finish it completely before moving on
+- Write the test first — it must fail (red) before any implementation; implement until green; then run the full suite
+- Each task touches only what's needed — no cleanup of adjacent code
+- If a task reveals new scope, STOP and update 2-plan.md before continuing
+
+---
+
+## Tasks
+
+- [ ] **Task 1**: <!-- Single-line description of what this task does.
+                      Example: "Create POST /api/files/[id]/access route that updates
+                      last_accessed_at without bumping updated_at" -->
+  - Test: <!-- What to write first, and what "red" looks like before implementation.
+              Example: "POST /api/files/[id]/access with a valid fileId returns 200
+              and the DB row shows last_accessed_at updated, updated_at unchanged
+              — must fail before the route file exists." -->
+  - Changes: <!-- Files to touch and what specifically changes in each.
+                 Example: "create app/api/files/[id]/access/route.ts — PATCH targeting
+                 only last_accessed_at; create lib/files/recordFileAccess.ts — thin
+                 fetch wrapper, fire-and-forget, no return value." -->
+  - Goal: <!-- Goal ID from 1-requirements.md this task moves forward. Example: "G1" -->
+  - Criterion: <!-- Acceptance scenario this task satisfies. Example: "Scenario: file that has been opened shows its last-opened timestamp" -->
+  - Tradeoff: <!-- what we gain → what we give up → why acceptable. Omit if not applicable. -->
+
+- [ ] **Task 2**: <!-- description -->
+  - Test: <!-- what to write first and what red looks like -->
+  - Changes: <!-- files + specific changes in each -->
+  - Goal: <!-- goal ID from 1-requirements.md -->
+  - Criterion: <!-- scenario name from 1-requirements.md -->
+  - Tradeoff: <!-- omit if not applicable -->
+
+<!-- Add tasks as needed. One logical change per task.
+     If two changes always need to happen together to keep tests green, they are one task.
+     If two changes can be verified independently, they are two tasks. -->
+
+---
+
+## Completion
+
+- [ ] All tasks done
+- [ ] Every acceptance scenario in 1-requirements.md covered by a passing test
+- [ ] /review completed
+- [ ] Spec moved to `specs/_done/<name>/`

package/templates/windsurf-rules/sddx-workflow.md

@@ -0,0 +1,26 @@
+---
+trigger: always_on
+---
+
+This project uses the SDD Protocol. Before starting any task, read:
+
+1. `.sdd/workflow.md` — all commands, ceremony levels, and stop points
+2. `.sdd/project-overview.md` — what this app is, its non-goals, and domains
+3. `.sdd/conventions.md` — project-specific conventions and patterns
+
+## Available commands
+
+| Command | Purpose |
+|---|---|
+| `/bootstrap` | Populate project context — interview or codebase scan |
+| `/ask` | Research only — no code changes |
+| `/assume` | List assumptions and stop for confirmation |
+| `/bugfix` | Reproduce → diagnose → fix → validate |
+| `/refactor` | Restructure without behavior change |
+| `/spec-new` | Scaffold a spec folder |
+| `/spec-plan` | Generate technical plan — stop for approval |
+| `/spec-tasks` | Execute plan one task at a time, TDD-first |
+| `/review` | Final audit before closing |
+| `/finish` | Stage files and generate commit message |
+
+Full definitions for each command are in `.sdd/workflow.md`.