Scheduling infrastructure for absolutely everyone.
feat: add claude specs (#26852)
Udit Takkarcfa0783ebcbe
diff --git a/.gitignore b/.gitignoreindex 0be912ac412..7ff27b28b8f 100644--- a/.gitignore+++ b/.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.triggeragents/devin-knowledge.jsondiff --git a/AGENTS.md b/AGENTS.mdindex 891f39c149c..471787e123f 100644--- a/AGENTS.md+++ b/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 DocumentationFor detailed information, see the `agents/` directory:diff --git a/SPEC-WORKFLOW.md b/SPEC-WORKFLOW.mdnew file mode 100644index 00000000000..4971a28c453--- /dev/null+++ b/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.mddiff --git a/specs/README.md b/specs/README.mdnew file mode 100644index 00000000000..40cc609b7fe--- /dev/null+++ b/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.diff --git a/specs/_templates/AGENTS.md b/specs/_templates/AGENTS.mdnew file mode 100644index 00000000000..b144df61c23--- /dev/null+++ b/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}diff --git a/specs/_templates/CLAUDE.md b/specs/_templates/CLAUDE.mdnew file mode 120000index 00000000000..47dc3e3d863--- /dev/null+++ b/specs/_templates/CLAUDE.md@@ -0,0 +1 @@+AGENTS.md\ No newline at end of filediff --git a/specs/_templates/decisions.md b/specs/_templates/decisions.mdnew file mode 100644index 00000000000..8d036b408a1--- /dev/null+++ b/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}diff --git a/specs/_templates/design.md b/specs/_templates/design.mdnew file mode 100644index 00000000000..8fe9c39df54--- /dev/null+++ b/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}diff --git a/specs/_templates/docs/README.md b/specs/_templates/docs/README.mdnew file mode 100644index 00000000000..2ba8b7d3b09--- /dev/null+++ b/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 2: {Second Step}++{Description}++++## 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}diff --git a/specs/_templates/docs/screenshots/.gitkeep b/specs/_templates/docs/screenshots/.gitkeepnew file mode 100644index 00000000000..e69de29bb2ddiff --git a/specs/_templates/future-work.md b/specs/_templates/future-work.mdnew file mode 100644index 00000000000..f4b0b0b56a4--- /dev/null+++ b/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 Havediff --git a/specs/_templates/implementation.md b/specs/_templates/implementation.mdnew file mode 100644index 00000000000..db8d3da9a22--- /dev/null+++ b/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 Notesdiff --git a/specs/_templates/prompts.md b/specs/_templates/prompts.mdnew file mode 100644index 00000000000..72885479ca8--- /dev/null+++ b/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)