# MySpec (myspec.dev) - Spec-Driven Development Platform & MCP Server

> MySpec is the AI Senior Architect for Spec-Driven Development (SDD). It interviews you with focused multiple-choice questions, then writes implementation-ready specification bundles file by file - `constitution.md`, `requirements.md`, `solution.md`, `tasks.md` (plus `proposal.md` for brownfield changes) - with a collect → generate → review gate on every file, and streams them into Cursor, Claude Code, Claude Desktop, and any MCP client via `@myspec/mcp-server`.

## Core Concepts & Philosophy

- **Spec-Driven Development (SDD)**: A software engineering methodology where structured, version-controlled specifications precede code generation to eliminate AI hallucinations, context window decay, and architectural drift.
- **The MySpec Spec Bundle** (written to `specs/<bundle>/`):
  - `constitution.md`: Project Vision, Core Principles, Technology / Architecture Constraints, Testing Approaches, Coding Standards, Security Constraints, Performance Targets, Integration Points.
  - `requirements.md`: User Roles, FR-xxx functional requirements with EARS+ acceptance criteria, NFR-xxx with measurable targets, Data and Integration requirements, requirement diagrams. Brownfield variant: a Requirements Delta coded AR- (add) / BR- (remove) / CR- (change).
  - `solution.md`: Technology stack, architecture (Mermaid flowchart + C4 diagrams), system modules, data model (Mermaid erDiagram), API design, security, deployment, success criteria, key decisions. Older bundles named this file `design.md`.
  - `tasks.md`: Milestones of sized (Small/Medium/Large) tasks with acceptance criteria, dependencies, requirement traceability, man-day estimates, a QA verification milestone, and a dependency graph.
  - `proposal.md` (brownfield): Why, What Changes, Technical Solution (library / flow / schema / API changes with Mermaid diagrams), Impact.
- **Three supported methodologies / four generate workflows**:
  - MySpec greenfield: interview → constitution → requirements → solution → tasks.
  - MySpec brownfield: interview (explores the codebase) → proposal → requirements delta → optional tasks.
  - Spec Kit greenfield (GitHub Spec Kit-compatible): interview → constitution (`specs/memory/constitution.md`) → specify (`specs/NNN-feature/spec.md`) → plan (`plan.md`) → tasks (`tasks.md`).
  - OpenSpec brownfield (OpenSpec CLI-compatible): explore → proposal → delta specs (`openspec/changes/<change-id>/specs/<capability>/spec.md`) → design (`design.md`) → tasks.
  - An Edit workflow refines existing files: reference files → describe changes → review diffs.
- **EARS / EARS+ Syntax**: Easy Approach to Requirements Syntax with 6 patterns (Ubiquitous, State-Driven WHILE, Event-Driven WHEN, Optional Feature WHERE, Unwanted Behaviour IF…THEN, Complex) and EARS+ acceptance-criteria patterns (WHEN/AND/THEN, WHILE, IF…THEN, IF…WHEN…THEN).

## Key Pages & Documentation

- [Homepage](https://myspec.dev/): Platform overview, interactive 3D bundle visualizer, workflow tour, roadmap, pricing.
- [Spec-Driven Development Guide](https://myspec.dev/spec-driven-development/): The complete engineering guide and topical authority hub on SDD.
- [Spec File Field Guide](https://myspec.dev/spec-driven-development/spec-files/): Every spec file type with anatomy, specimens, and review rules - [constitution.md](https://myspec.dev/spec-driven-development/spec-files/constitution-md/), [requirements.md](https://myspec.dev/spec-driven-development/spec-files/requirements-md/), [solution.md](https://myspec.dev/spec-driven-development/spec-files/solution-md/), [tasks.md](https://myspec.dev/spec-driven-development/spec-files/tasks-md/), [proposal.md](https://myspec.dev/spec-driven-development/spec-files/proposal-md/), [spec.md](https://myspec.dev/spec-driven-development/spec-files/spec-md/), [plan.md](https://myspec.dev/spec-driven-development/spec-files/plan-md/), [design.md](https://myspec.dev/spec-driven-development/spec-files/design-md/).
- [SDD Workflows Compared](https://myspec.dev/spec-driven-development/workflows/): [MySpec Workflow](https://myspec.dev/spec-driven-development/workflows/myspec/), [Spec Kit Workflow](https://myspec.dev/spec-driven-development/workflows/spec-kit/), [OpenSpec Workflow](https://myspec.dev/spec-driven-development/workflows/openspec/).
- [MCP Server Setup](https://myspec.dev/mcp-server/): How to configure `@myspec/mcp-server` (stdio) and the hosted HTTP server at `https://mcp.myspec.dev/mcp` in Cursor, Claude Code, and Claude Desktop.
- [Claude Code Plugin Quick Start](https://myspec.dev/spec-driven-development/claude-code-plugin/): Install the official MySpec plugins for Claude Code (`myspecs/claude-plugins`): `myspec-mcp` (the MCP server plus implement, analyze, spec-authoring, and reverse-bridge skills) and `myspec-factory` (the Software Factory Manager).
- [The AI Software Factory](https://myspec.dev/spec-driven-development/software-factory/): What an AI software factory is (and the older Japanese, Microsoft, and DoD meanings), the five levels from spicy autocomplete to the dark factory, light vs dark factories, software factory vs DevOps, and how to build a spec-driven factory with Claude Code and the Software Factory Manager.
- [GitHub Spec-Kit vs MySpec](https://myspec.dev/spec-kit-vs-myspec/): Comparison between manual CLI templates and the MySpec AI Senior Architect.
- [EARS Syntax Cheatsheet](https://myspec.dev/ears-syntax/): The 6 EARS patterns and EARS+ acceptance-criteria patterns.
- [Vibe Coding Best Practices](https://myspec.dev/vibe-coding-best-practices/): How to vibe code at 10x velocity without breaking production.
- [Project Constitution Templates](https://myspec.dev/templates/constitution-md/): Free constitution.md templates for Next.js and FastAPI.
- [Why ChatPRD Fails Developers](https://myspec.dev/ai-prd-generator/): Interactive benchmark comparing generic PM PRDs against machine-readable spec bundles.
- [The SDD Manifesto](https://myspec.dev/manifesto/): A declaration of intent for developers who believe clarity precedes code.
- [FAQ](https://myspec.dev/faq/): Greenfield vs brownfield, every spec file, workflows, and the MCP server.

## Model Context Protocol (MCP) Quickstart

```bash
# Sign in once (browser OAuth), then add to Cursor / Claude Code / Claude Desktop
npx -y @myspec/mcp-server login
```

```json
{ "mcpServers": { "myspec": { "command": "npx", "args": ["-y", "@myspec/mcp-server"] } } }
```

Claude Code users can install the official plugin instead, which registers the same server and adds SDD skills (restart Claude Code, then run the `login` command above):

```text
/plugin marketplace add myspecs/claude-plugins
/plugin install myspec-mcp@myspec
```

Unattended (CI, containers): set `MYSPEC_API_TOKEN=msp_pat_…` in the server's `env` block instead of running `login`. Hosted agents with no filesystem: `POST https://mcp.myspec.dev/mcp` with `Authorization: Bearer msp_pat_…`.