feat: add claude specs (#26852)

* feat: claude templates

* refactor: new file

* feat: symlink

.gitignore

@@ -108,6 +108,9 @@ packages/**/.yarn/ci-cache/
 .claude/plans/
 .claude/settings.local.json
 
+# Spec drafts (rough work, not ready for review)
+specs/**/_drafts/
+
 # trigger.dev
 .trigger
 agents/devin-knowledge.json

AGENTS.md

@@ -226,6 +226,14 @@ import { ProfileRepository } from "@calcom/features/profile/repositories/Profile
 - Fix type errors before test failures - they're often the root cause
 - Run `yarn prisma generate` if you see missing enum/type errors
 
+## Spec-Driven Development (Opt-In)
+
+For complex features, you can use spec-driven development when explicitly requested.
+
+**To enable:** Tell the AI "use spec-driven development" or "follow the spec workflow"
+
+See [SPEC-WORKFLOW.md](SPEC-WORKFLOW.md) for the full workflow documentation.
+
 ## Extended Documentation
 
 For detailed information, see the `agents/` directory:

SPEC-WORKFLOW.md

@@ -0,0 +1,105 @@
+# Spec-Driven Development Workflow
+
+This workflow is **opt-in**. Use it when explicitly requested by saying "use spec-driven development" or "follow the spec workflow".
+
+## Design Documents
+
+The `specs/` folder contains design documents for features in development.
+
+Each spec follows this structure:
+
+```
+specs/{feature}/
+├── CLAUDE.md           # Feature-specific instructions (read this first)
+├── design.md           # The specification
+├── implementation.md   # Current status and what's done
+├── decisions.md        # Why decisions were made
+├── prompts.md          # Reusable prompts
+├── future-work.md      # What's deferred
+└── docs/               # Documentation with screenshots
+```
+
+**Workflow:**
+
+1. Read the spec's `CLAUDE.md` for specific instructions
+2. Read `design.md` to understand what we're building
+3. Check `implementation.md` for current status
+4. Find the relevant code in the codebase
+5. Implement in small pieces, update `implementation.md` after each
+
+---
+
+## When Implementing Features (Spec Mode)
+
+1. **Check for design doc** in `specs/` — if it exists, follow it
+2. **If no spec exists** — ask if you should create one first
+3. **Look at existing patterns** — find similar code and follow conventions
+4. **Update implementation.md** — mark what's done after each piece
+5. **Update decisions.md** — when choosing between approaches
+
+---
+
+## Creating a New Spec
+
+When user asks to build a new feature:
+
+1. Copy the template: `cp -r specs/_templates specs/{feature-name}`
+2. Explore the codebase to understand existing patterns
+3. Write `design.md` with technical spec
+4. Write `CLAUDE.md` with feature-specific instructions
+5. Initialize `implementation.md` with "not-started" status
+6. Ask user to review before implementing
+
+---
+
+## Updating Spec Files
+
+### implementation.md — After completing each piece:
+
+```markdown
+## Status: in-progress
+
+## Completed
+- [x] Database schema
+- [x] Migration file
+
+## In Progress
+- tRPC endpoints
+
+## Next Steps
+1. UI components
+2. Tests
+
+## Session Notes
+### 2024-01-15
+- Done: Added schema, created migration
+- Next: Implement tRPC router
+```
+
+### decisions.md — When choosing between approaches:
+
+```markdown
+## ADR-001: Use Separate Table for Custom Locations
+
+### Context
+Need to store user-defined locations.
+
+### Options
+1. JSON field — simpler, but harder to query
+2. Separate table — more flexible, better indexing
+
+### Decision
+Separate table for better querying.
+
+### Consequences
+- Need migration
+- Need new tRPC router
+```
+
+---
+
+## Don't (When Using Spec-Driven Development)
+
+- Don't implement features without checking for a design doc first
+- Don't skip updating implementation.md after completing work
+- Don't make architectural decisions without recording them in decisions.md

specs/README.md

@@ -0,0 +1,82 @@
+# Spec-First Development
+
+This folder contains design documents for features in development. Claude reads these to understand what to build and track progress.
+
+## How It Works
+
+1. **Before implementing a feature**, create a spec folder with design docs
+2. **Claude reads the design** before writing any code
+3. **Progress is tracked** in implementation.md for session continuity
+4. **Decisions are recorded** in decisions.md for future reference
+5. **Docs are generated** with screenshots when feature is complete
+
+## Starting a New Feature
+
+```bash
+cp -r specs/_templates specs/{feature-name}
+```
+
+Then tell Claude:
+```
+"I want to build {feature}. Here's my idea: [description].
+Review the codebase and fill in specs/{feature}/design.md"
+```
+
+## File Structure
+
+Each feature has:
+
+| File/Folder | Purpose |
+|-------------|---------|
+| `CLAUDE.md` | Instructions for Claude when working on this feature |
+| `design.md` | Source of truth - what to build and how |
+| `implementation.md` | Progress tracking - what's done, in progress, blocked |
+| `decisions.md` | Architecture Decision Records (ADRs) |
+| `prompts.md` | Reusable prompts for common tasks |
+| `future-work.md` | Deferred ideas and enhancements |
+| `docs/` | Internal documentation with screenshots |
+| `docs/screenshots/` | Screenshots captured during development |
+
+## Session Continuity
+
+When starting a new Claude session:
+```
+"Continue working on {feature}"
+```
+
+Claude will read `implementation.md` to pick up where it left off.
+
+## Generating Documentation
+
+When a feature is ready for documentation:
+```
+"Generate docs with screenshots for {feature}"
+```
+
+Claude will:
+1. Open the feature in browser
+2. Take screenshots of key UI states
+3. Save to `specs/{feature}/docs/screenshots/`
+4. Update `specs/{feature}/docs/README.md`
+
+## Promoting to Public Docs
+
+When internal docs are ready for customers:
+```
+"Promote {feature} docs to public"
+```
+
+Claude will:
+1. Copy content to `docs/{feature}.mdx` (Mintlify format)
+2. Move screenshots to `docs/images/{feature}/`
+3. Update `docs/mint.json` navigation
+4. Adjust language for customer audience
+
+## The Most Important Rule
+
+Every PR must be reviewable in under 10 minutes:
+- Max 5-7 files changed (excluding tests)
+- Max 500 lines changed
+- One focused change per PR
+
+If your change is bigger, split it into multiple PRs.

specs/_templates/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md — {Feature Name}
+
+## Project Context
+
+{Brief description of what this feature does}
+
+## Before Starting Work
+
+1. Read specs/{feature}/design.md
+2. Check specs/{feature}/implementation.md for current progress
+3. Look at existing patterns in {relevant directories}
+
+## Code Patterns
+
+{Key patterns to follow, reference implementations}
+
+## Don't
+
+- Don't add features not in design.md
+- Don't skip tests
+- {Feature-specific don'ts}

specs/_templates/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

specs/_templates/decisions.md

@@ -0,0 +1,20 @@
+# {Feature Name} Decisions
+
+## ADR-001: {Decision Title}
+
+### Context
+
+{What situation required a decision?}
+
+### Options Considered
+
+1. {Option A} — {pros/cons}
+2. {Option B} — {pros/cons}
+
+### Decision
+
+{What was decided and why}
+
+### Consequences
+
+- {Impact of this decision}

specs/_templates/design.md

@@ -0,0 +1,35 @@
+# {Feature Name} Design
+
+## Overview
+
+{What this feature does in 2-3 sentences}
+
+## Problem Statement
+
+{What problem does this solve? Why build this?}
+
+## User Stories
+
+- As a {user type}, I want to {action} so that {benefit}
+
+## Technical Design
+
+### Database Changes
+
+{Schema changes, new tables, migrations}
+
+### API Changes
+
+{New endpoints, tRPC routers, request/response shapes}
+
+### UI Changes
+
+{Components, pages, user flows}
+
+## Edge Cases
+
+{Important edge cases to handle}
+
+## Out of Scope
+
+{What this feature explicitly does NOT include}

specs/_templates/docs/README.md

@@ -0,0 +1,45 @@
+# {Feature Name}
+
+## Overview
+
+{Brief description of what this feature does and why users would use it}
+
+## How to Use
+
+### Step 1: {First Step}
+
+{Description}
+
+![Step 1 Screenshot](./screenshots/step-1.png)
+
+### Step 2: {Second Step}
+
+{Description}
+
+![Step 2 Screenshot](./screenshots/step-2.png)
+
+## Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| {option} | {description} | {default} |
+
+## Common Use Cases
+
+### {Use Case 1}
+
+{Description of use case and how to achieve it}
+
+### {Use Case 2}
+
+{Description of use case and how to achieve it}
+
+## FAQ
+
+### {Common Question 1}
+
+{Answer}
+
+### {Common Question 2}
+
+{Answer}

specs/_templates/future-work.md

@@ -0,0 +1,9 @@
+# {Feature Name} Future Work
+
+Ideas and enhancements deferred from initial implementation.
+
+## Enhancements
+
+## Technical Debt
+
+## Nice to Have

specs/_templates/implementation.md

@@ -0,0 +1,15 @@
+# {Feature Name} Implementation
+
+## Status: not-started
+
+## Completed
+
+## In Progress
+
+## Blocked
+
+## Next Steps
+
+1. {First item to implement}
+
+## Session Notes

specs/_templates/prompts.md

@@ -0,0 +1,40 @@
+# {Feature Name} Prompts
+
+## Sync Implementation Status
+
+Review what's been implemented for {feature} and update specs/{feature}/implementation.md
+
+## Generate Tests
+
+Write tests for {component}. Follow existing test patterns.
+
+## Code Review
+
+Review changes for: type safety, error handling, security, edge cases
+
+## Continue Feature
+
+Continue working on {feature}. Read specs/{feature}/implementation.md for current status.
+
+## Generate Docs with Screenshots
+
+Generate documentation for {feature} with screenshots:
+
+1. Open the feature in the browser
+2. Take screenshots of key UI states using the browser extension
+3. Save screenshots to specs/{feature}/docs/screenshots/
+4. Create/update specs/{feature}/docs/README.md with:
+   - Feature overview
+   - How to use (step-by-step with screenshots)
+   - Configuration options
+   - Common use cases
+
+## Promote Docs to Public
+
+Promote internal docs to public Mintlify docs:
+
+1. Review specs/{feature}/docs/README.md
+2. Copy/adapt content to docs/{feature}.mdx
+3. Move screenshots to docs/images/{feature}/
+4. Update docs/mint.json navigation
+5. Ensure customer-appropriate language (no internal details)