feat(docs): revamp homepage demo + SDD documentation

.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
     "email": "hello@multivmlabs.com"
   },
   "metadata": {
-    "description": "Autonomous AI coding loops — fetch specs from GitHub, Linear, Notion, Figma, and Todoist, then orchestrate coding agents to build software automatically.",
+    "description": "Autonomous AI coding loops — fetch specs from GitHub, Linear, Notion, Figma, and OpenSpec, then orchestrate coding agents to build software automatically.",
     "version": "0.4.0"
   },
   "plugins": [

CLAUDE.md

@@ -13,7 +13,7 @@ Note: ralph-starter itself supports any package manager in user projects via `de
 
 ## What is ralph-starter?
 
-A CLI tool that runs autonomous AI coding loops. It fetches specs from GitHub, Linear, Notion, Figma, and Todoist, then orchestrates coding agents to build software automatically. Each loop iteration spawns a fresh agent process with a progressively trimmed context — continuity is maintained through the filesystem (`IMPLEMENTATION_PLAN.md`, `.ralph/iteration-log.md`), not conversation history.
+A CLI tool that runs autonomous AI coding loops. It fetches specs from GitHub, Linear, Notion, Figma, and OpenSpec, then orchestrates coding agents to build software automatically. Each loop iteration spawns a fresh agent process with a progressively trimmed context — continuity is maintained through the filesystem (`IMPLEMENTATION_PLAN.md`, `.ralph/iteration-log.md`), not conversation history.
 
 ## Quick Commands
 
@@ -43,7 +43,6 @@ pnpm typecheck    # Type-check without emitting
 - Linear: Tickets by team/project
 - Notion: Pages and databases
 - Figma: Design specs and tokens
-- Todoist: Tasks and projects
 
 **Agents** - AI coding assistants ralph-starter orchestrates:
 - Claude Code, Cursor, OpenCode, OpenAI Codex, GitHub Copilot, Gemini CLI, Amp, Openclaw
@@ -78,7 +77,7 @@ pnpm typecheck    # Type-check without emitting
 
 | Directory | Purpose |
 |-----------|---------|
-| `auth/` | OAuth providers (Anthropic, OpenAI, Linear, Notion, Todoist) |
+| `auth/` | OAuth providers (Anthropic, OpenAI, Linear, Notion) |
 | `automation/` | Git operations (commit, push, PR creation) |
 | `commands/` | CLI commands (run, init, plan, auto, fix, pause, resume, etc.) |
 | `config/` | Configuration management |

CONTRIBUTING.md

@@ -37,7 +37,7 @@ ralph-starter/
 │   ├── commands/           # CLI commands (run, init, plan, etc.)
 │   ├── sources/            # Input source system
 │   │   ├── builtin/        # File, URL, PDF sources
-│   │   └── integrations/   # Todoist, Linear, Notion, GitHub
+│   │   └── integrations/   # GitHub, Linear, Notion, Figma
 │   ├── wizard/             # Interactive wizard & idea mode
 │   ├── loop/               # Autonomous loop engine
 │   ├── mcp/                # MCP server implementation

docs/docs/cli/auth.md

@@ -2,12 +2,12 @@
 sidebar_position: 7
 title: auth
 description: Browser-based OAuth authentication for integrations
-keywords: [cli, auth, command, oauth, authentication, linear, notion, github, todoist]
+keywords: [cli, auth, command, oauth, authentication, linear, notion, github]
 ---
 
 # ralph-starter auth
 
-Browser-based OAuth authentication for integrations. Supports OAuth PKCE flows for services like Linear, and manages manual API key configuration for services like Notion, Todoist, and GitHub.
+Browser-based OAuth authentication for integrations. Supports OAuth PKCE flows for services like Linear, and manages manual API key configuration for services like Notion and GitHub.
 
 ## Synopsis
 
@@ -31,7 +31,7 @@ Credentials are stored locally in the ralph-starter sources configuration file.
 
 | Argument | Description |
 |----------|-------------|
-| `service` | The service to authenticate with (e.g., `linear`, `notion`, `todoist`, `github`) |
+| `service` | The service to authenticate with (e.g., `linear`, `notion`, `github`) |
 
 ## Options
 
@@ -46,7 +46,6 @@ Credentials are stored locally in the ralph-starter sources configuration file.
 |---------|-------------|---------|
 | `linear` | Browser OAuth (PKCE) | Seamless browser-based flow. Requires `RALPH_LINEAR_CLIENT_ID` env var. |
 | `notion` | Manual API key | Set via `ralph-starter config set notion.apiKey <key>`. Get key at [notion.so/my-integrations](https://www.notion.so/my-integrations). |
-| `todoist` | Manual API key | Set via `ralph-starter config set todoist.apiKey <key>`. Get key at [todoist.com/prefs/integrations](https://todoist.com/prefs/integrations). |
 | `github` | Manual API key | Set via `ralph-starter config set github.apiKey <key>`. Get token at [github.com/settings/tokens](https://github.com/settings/tokens). |
 
 ## Examples
@@ -75,8 +74,6 @@ Credentials stored in: /home/user/.config/ralph-starter/sources.json
   ✓ Linear - Authenticated
   ○ Notion - Manual API key
       Run: ralph-starter config set notion.apiKey <your-key>
-  ○ Todoist - Manual API key
-      Run: ralph-starter config set todoist.apiKey <your-key>
   ○ GitHub - Manual API key
       Run: ralph-starter config set github.apiKey <your-key>
 ```
@@ -96,9 +93,6 @@ For services that do not support OAuth PKCE, configure API keys manually:
 # Notion
 ralph-starter config set notion.apiKey ntn_your_api_key_here
 
-# Todoist
-ralph-starter config set todoist.apiKey your_todoist_api_key
-
 # GitHub
 ralph-starter config set github.apiKey ghp_your_github_token
 ```

docs/docs/cli/spec.md

@@ -0,0 +1,94 @@
+---
+sidebar_position: 15
+title: spec
+description: Validate, list, and summarize specs
+keywords: [cli, spec, validate, sdd, spec driven development]
+---
+
+# ralph-starter spec
+
+Validate, list, and summarize specs for spec-driven development workflows.
+
+## Synopsis
+
+```bash
+ralph-starter spec <action> [options]
+```
+
+## Actions
+
+### validate
+
+Validate spec completeness across the project.
+
+```bash
+ralph-starter spec validate
+ralph-starter spec validate --path openspec/changes/add-auth
+```
+
+Auto-detects the spec format (OpenSpec, Spec-Kit, or raw markdown) and validates each spec against a 0-100 completeness score.
+
+**Checks performed:**
+
+| Check | Points | Description |
+|-------|--------|-------------|
+| Proposal | 20 | Has a proposal, rationale, or overview section |
+| RFC 2119 | 25 / 10 | 25 if SHALL, MUST, SHOULD, or MAY keywords present; 10 if absent but content >200 chars |
+| Design | 15 | Has a design, architecture, or technical section |
+| Tasks | 15 | Has a tasks section or checkbox items |
+| Criteria | 15 | Has Given/When/Then acceptance criteria |
+| Depth | 10 / 5 | 10 if content >= 500 chars; 5 if 200-499 chars |
+
+Specs scoring below 40 are flagged as failing.
+
+### list
+
+List available specs from any detected source.
+
+```bash
+ralph-starter spec list
+```
+
+Outputs all discovered specs with their available files.
+
+### summary
+
+Show spec completeness metrics.
+
+```bash
+ralph-starter spec summary
+```
+
+Displays format, change count, average completeness score.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--path <path>` | Path to a specific spec file or directory to validate |
+
+## Examples
+
+```bash
+# Validate all specs in an OpenSpec project
+ralph-starter spec validate
+#   PASS add-auth (85/100)
+#   FAIL fix-login (30/100)
+#        No acceptance criteria found.
+
+# Validate a specific file
+ralph-starter spec validate --path specs/api-spec.md
+
+# Quick overview
+ralph-starter spec summary
+#   Format:  OpenSpec
+#   Changes: 3 active, 1 archived
+#   Specs:   5 global
+#   Average: 72/100 completeness
+```
+
+## See also
+
+- [Spec Driven Development guide](/docs/guides/spec-driven-development)
+- [OpenSpec source](/docs/sources/openspec)
+- [run --spec-validate](/docs/cli/run) -- Validate before running a loop

docs/docs/guides/spec-driven-development.md

@@ -0,0 +1,207 @@
+---
+sidebar_position: 7
+title: Spec Driven Development
+description: How ralph-starter implements Spec Driven Development for AI coding agents
+keywords: [sdd, spec driven development, openspec, spec-kit, specs, workflow]
+---
+
+# Spec Driven Development
+
+Spec Driven Development (SDD) is a methodology where you write a structured specification before any code is generated. The spec becomes the contract between human intent and AI execution.
+
+ralph-starter is built around this principle: **pull specs from where they already live, validate them, then run autonomous loops until done.**
+
+## Why specs matter for AI coding
+
+Without a spec, AI agents guess. A vague prompt like "add authentication" produces plausible but wrong code. You waste iterations fixing misunderstandings.
+
+With a clear spec:
+- **2 loops** instead of 5
+- **$0.50** instead of $3+
+- **Correct output** instead of close-but-wrong
+
+The spec is the highest-leverage investment in any AI coding workflow.
+
+## How ralph-starter does SDD
+
+```
+Spec → Validate → Plan → Agent builds → Lint/Build/Test → Commit → PR
+```
+
+### 1. Pull specs from any source
+
+Your specs already exist somewhere. ralph-starter fetches them:
+
+```bash
+# From OpenSpec directories
+ralph-starter run --from openspec:add-auth
+
+# From GitHub issues
+ralph-starter run --from github --project myorg/api --label ready
+
+# From Linear tickets
+ralph-starter run --from linear --project "Backend"
+
+# From Notion docs
+ralph-starter run --from notion --project "https://notion.so/spec-abc"
+
+# From Figma designs
+ralph-starter figma
+```
+
+### 2. Validate before building
+
+The `--spec-validate` flag checks completeness before spending tokens:
+
+```bash
+ralph-starter run --from openspec:add-auth --spec-validate
+```
+
+The validator scores specs 0-100 based on:
+
+| Check | Points | What it looks for |
+|-------|--------|-------------------|
+| Proposal/rationale | 20 | `## Proposal`, `## Why`, `## Overview` section |
+| RFC 2119 keywords | 25 / 10 | 25 if SHALL, MUST, SHOULD, MAY present; 10 partial credit if absent but content >200 chars |
+| Design section | 15 | `## Design`, `## Architecture`, `## Technical` |
+| Task breakdown | 15 | `## Tasks` or `- [ ]` checklists |
+| Acceptance criteria | 15 | Given/When/Then blocks |
+| Content depth | 10 / 5 | 10 if >= 500 chars; 5 if 200-499 chars |
+
+Specs scoring below 40/100 are flagged before the loop starts.
+
+### 3. Autonomous execution
+
+Once validated, ralph-starter runs the loop:
+1. Build iteration context from spec + plan
+2. Spawn the AI agent with trimmed prompt
+3. Collect agent output
+4. Run validation (lint, build, tests)
+5. If validation fails, feed errors back to agent
+6. If validation passes, commit
+7. Repeat until task is complete
+
+## The `spec` command
+
+ralph-starter includes a dedicated CLI for spec operations:
+
+```bash
+# Validate all specs in the project
+ralph-starter spec validate
+
+# List available specs (auto-detects format)
+ralph-starter spec list
+
+# Show completeness metrics
+ralph-starter spec summary
+```
+
+It auto-detects **OpenSpec**, **Spec-Kit**, or **raw markdown** format.
+
+## Comparison: ralph-starter vs other SDD tools
+
+| Capability | ralph-starter | OpenSpec | Spec-Kit | Kiro |
+|-----------|--------------|---------|---------|------|
+| **Spec format** | Any (OpenSpec, Spec-Kit, raw, GitHub, Linear, Notion, Figma) | OpenSpec only | Spec-Kit only | EARS notation |
+| **Execution** | Fully autonomous loops | Manual (`/opsx:apply`) | Manual per phase | IDE-integrated agents |
+| **Agent support** | Claude Code, Cursor, Codex, OpenCode, Amp | Any chat agent | Any chat agent | Kiro agents only |
+| **Validation** | Lint + build + test + visual | None | None | Agent hooks |
+| **Spec validation** | 0-100 scoring with RFC 2119 check | Zod schema | Phase gates | Auto-generated |
+| **Multi-source** | GitHub, Linear, Notion, Figma, OpenSpec, URLs, files | Local filesystem | Local filesystem | IDE workspace |
+| **Cost tracking** | Per-iteration token + cost tracking | N/A | N/A | Subscription model |
+| **Lock-in** | None (CLI, any OS) | None | GitHub ecosystem | AWS account required |
+| **Pricing** | Free + pay-per-API | Free | Free | $19-39/month |
+
+## Writing good specs
+
+A spec does not need to be long. 10-20 lines is enough:
+
+```markdown
+## Proposal
+
+Add JWT authentication to the Express API.
+
+## Requirements
+
+- POST /api/auth/login takes { email, password }, validates against users table
+- Return { token, expiresIn } on success, 401 with { error } on failure
+- Token TTL: 24h
+- Auth middleware in src/middleware/auth.ts (Authorization: Bearer header)
+- The API MUST reject expired tokens with 401
+- The API SHALL rate-limit login attempts to 5/minute per IP
+
+## Tasks
+
+- [ ] Create auth middleware
+- [ ] Add login endpoint
+- [ ] Add token refresh endpoint
+- [ ] Write tests
+
+## Acceptance Criteria
+
+Given: A user with valid credentials
+When: They POST to /api/auth/login
+Then: They receive a JWT token with 24h TTL
+
+Given: A request with an expired token
+When: It hits a protected endpoint
+Then: The API returns 401 Unauthorized
+```
+
+This spec takes 3 minutes to write. It tells the agent exactly what to build, where to put it, and how to verify it works.
+
+## Supported spec formats
+
+### OpenSpec
+
+```
+openspec/
+├── changes/
+│   └── add-auth/
+│       ├── proposal.md
+│       ├── design.md
+│       ├── tasks.md
+│       └── specs/
+│           └── auth/
+│               └── spec.md
+└── specs/
+    └── api/
+        └── spec.md
+```
+
+```bash
+ralph-starter run --from openspec:add-auth
+```
+
+### Spec-Kit (GitHub)
+
+```
+specs/
+├── constitution.md
+├── specification.md
+├── plan.md
+└── tasks.md
+```
+
+```bash
+ralph-starter spec validate   # auto-detects Spec-Kit format
+```
+
+### Raw markdown
+
+```
+specs/
+├── auth-spec.md
+├── api-spec.md
+└── db-migration.md
+```
+
+```bash
+ralph-starter run --from ./specs/auth-spec.md
+```
+
+## Next steps
+
+- [OpenSpec source docs](/docs/sources/openspec) -- How to use OpenSpec with ralph-starter
+- [Spec CLI reference](/docs/cli/spec) -- Full `ralph-starter spec` command docs
+- [Workflow presets](/docs/guides/workflow-presets) -- Pre-configured SDD presets