# Full Technical Reference: MySpec.dev - Spec-Driven Development Platform

## What is Spec-Driven Development (SDD)?
Spec-Driven Development (SDD) is an AI-first software engineering methodology where structured, version-controlled technical specifications precede code generation. Specs are the single source of truth for human engineers and AI coding agents alike; code, tests, and docs are derived from them. SDD eliminates AI hallucinations, context-window decay, and architectural drift because every constraint lives in a file the agent reads before it writes.

## How MySpec generates a spec bundle
1. **Interview** - the AI Architect asks 2–3 rounds of focused multiple-choice questions (product, users, journeys, MVP scope). No technical questions yet.
2. **Per-file stages** - each spec file goes through three substages: **collect** (targeted clarifying questions for that file), **generate** (draft against a strict template), **review** (an independent reviewer agent checks the draft against the template, the interview answers, and the previous files). The user approves, edits (WYSIWYG or chat), or sends it back with `/goback`.
3. **Complete** - files are stored as versioned revisions in the MySpec project (`specs/<bundle>/`), downloadable as a ZIP, shareable via public links, and readable/writable from any MCP client.

Supported output languages: English, Japanese, Vietnamese, Chinese. Models: Gemini, Claude, and GPT families selectable per session (Auto by default).

## Methodologies and workflows
| Workflow | Scope | Stages | Files and paths |
|---|---|---|---|
| MySpec generate-greenfield | New project | interview → constitution → requirements → solution → tasks | `specs/<bundle>/constitution.md`, `requirements.md`, `solution.md`, `tasks.md` |
| MySpec generate-brownfield | Existing codebase | interview (reads code) → proposal → requirements delta → tasks (optional) | `specs/<bundle>/proposal.md`, `requirements.md` (AR-/BR-/CR- coded), `tasks.md` |
| Spec Kit generate-greenfield | New feature (GitHub Spec Kit layout) | interview → constitution → specify → plan → tasks | `specs/memory/constitution.md`, `specs/<NNN-feature>/spec.md`, `plan.md`, `tasks.md` |
| OpenSpec generate-brownfield | Existing codebase (OpenSpec CLI layout) | explore (reads code) → proposal → specs → design → tasks | `openspec/changes/<change-id>/proposal.md`, `specs/<capability>/spec.md`, `design.md`, `tasks.md` |
| MySpec edit (greenfield / brownfield) | Any existing bundle | reference files → describe changes → review diffs | Edits existing revisions |

Brownfield workflows read the user's code either through a mounted Local Workspace folder (Chrome / Edge File System Access API) or through `npx -y @myspec/mcp-server reverse --root <dir>`, which exposes read-only `local_fs_list_dir`, `local_fs_read_file`, `local_fs_grep`, `local_pack_codebase`, and `local_pack_codebase_read_page` tools to the cloud architect.

## Spec file anatomy

### constitution.md (MySpec)
Sections, all required, in order: Project Vision; Core Principles; Technology Constraints (MUST use …); Architecture Constraints; Testing Approaches; Coding Standards; Security Constraints; Performance Targets; Integration Points ("N/A" allowed for the last three). 3–5 items per section; every constraint traceable to a user answer; no metadata footers.

### constitution.md (Spec Kit)
A `SYNC IMPACT REPORT` HTML comment, `# [PROJECT] Constitution`, Core Principles as Roman-numeral Articles (3–7, `(NON-NEGOTIABLE)` where applicable), Additional Constraints, Development Workflow, Governance, and a footer `**Version**: MAJOR.MINOR.PATCH | **Ratified**: YYYY-MM-DD | **Last Amended**: YYYY-MM-DD`. Written once per project to `specs/memory/constitution.md` and reused by later features.

### requirements.md (MySpec greenfield)
Overview; User Roles; Functional Requirements `### FR-001:` with Description, User Role, Acceptance Criteria in EARS+; Non-Functional Requirements `### NFR-001:` with Description, Target, Priority; Requirement Diagrams (Mermaid `requirementDiagram` for FRs and NFRs); Data Requirements (≤5 bullets); Integration Requirements (≤5 bullets). Technology-neutral: what, not how.

### requirements.md (MySpec brownfield - Requirements Delta)
`# Requirements Delta`; Overview; Impacted User Roles; one `## <Module>` section per impacted module; entries coded **AR-NNN** (added: Description, User Role, EARS+ ACs), **BR-NNN** (removed: Description + `Reference: file:line`), **CR-NNN** (changed: old AC `~~struck through~~` followed by the replacement). Optional final Requirement Diagram.

### EARS / EARS+ patterns
Ubiquitous `The <system> SHALL <response>`; State-Driven `WHILE <state>, the <system> SHALL …`; Event-Driven `WHEN <trigger>, the <system> SHALL …`; Optional Feature `WHERE <feature>, …`; Unwanted Behaviour `IF <condition>, THEN the <system> SHALL …`; Complex (combined). EARS+ acceptance criteria: `WHEN <event> THEN <system> SHALL <response>`, `WHEN … AND <condition> THEN …`, `WHILE <state> THEN …`, `IF <pre-condition> THEN …`, `IF … WHEN … THEN …`.

### solution.md (MySpec)
Overview (Description, Technology Stack table ≤8 rows, Design Decisions Summary ≤6 rows); High-Level Architecture Design (description, Mermaid `flowchart`, C4 Context and Container diagrams, optional `sequenceDiagram`); System Modules (Responsibilities, Key Components, Key Interfaces, Data Models, Dependencies, Error Handling per module); Data Model (Mermaid `erDiagram` + entities); API / Protocol Design; Security Architecture; Deployment & Operations; Observability [optional]; Testing Strategy [optional]; Success Criteria (one row per measurable NFR); Key Solution Decisions (rationale + alternatives). Only technologies approved by the constitution.

### tasks.md (MySpec)
Overview (approach, total task count, total man-days, elapsed duration); `## Milestone N: <outcome it ships>` groups; each task `- [ ] N\. Title` with implementation details, Acceptance Criteria, `_Dependencies:_`, `_Requirements: FR-…_`, `_Complexity: Small/Medium/Large_` (Small ≤4h, Medium 1–2 days, Large >2 days; split anything >5 days), `_Estimate: N man-days_`; a delivery timeline (Mermaid Gantt) before the closing `## Dependency Graph`; a QA Verification milestone with one verification task per functional requirement (negative IF…THEN paths included).

### proposal.md (MySpec brownfield)
`# Change Proposal:` (wide scope) or `# Change Request:` (single module); `## Why`; `## What Changes`; `## Technical Solution` with `### Library/Framework Changes`, `### Core Flow Changes` (Mermaid sequence/flow), `### Data Model / DB Schema Changes` (Mermaid erDiagram), `### API Breaking Changes`; `## Impact`. Every claim grounded in files actually read.

### proposal.md (OpenSpec)
`## Why`; `## What Changes`; `## Capabilities` with `### New Capabilities` / `### Modified Capabilities` - each a stable kebab-case domain/module name (≤3 words / 25 chars) that becomes `openspec/changes/<id>/specs/<name>/spec.md`; `## Impact`.

### spec.md (Spec Kit feature spec)
Header (Feature Branch `<NNN-feature>`, Created, Status, Input); User Scenarios & Testing with prioritised User Stories P1/P2/P3 (Why this priority, Independent Test, Given/When/Then Acceptance Scenarios) and Edge Cases; Requirements (`FR-001` System MUST …, Key Entities); Success Criteria (`SC-001` measurable, technology-agnostic); Assumptions. ≤3 `[NEEDS CLARIFICATION: …]` markers.

### spec.md (OpenSpec delta spec, one per capability)
`## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, `## RENAMED Requirements` (only those that apply). Each ADDED/MODIFIED `### Requirement:` has SHALL/MUST text and at least one `#### Scenario:` with `- **WHEN**` / `- **THEN**` (/ `- **AND**`) bullets. RENAMED uses `- FROM:` / `- TO:` pairs.

### plan.md (Spec Kit)
Header (Branch, Date, Spec link); Summary; Technical Context (Language/Version, Primary Dependencies, Storage, Testing, Target Platform, Project Type, Performance Goals, Constraints, Scale/Scope - `NEEDS CLARIFICATION` where unknown, ≤3); Constitution Check (Simplicity, Anti-Abstraction, Integration-First gates); High-Level Architecture (Mermaid flowchart, optional sequence); System Modules; Data Model (Mermaid erDiagram); optional API / Security / Deployment / Observability; Testing Strategy mapped to user stories; Key Decisions; Complexity Tracking (only for gate violations).

### tasks.md (Spec Kit)
`[ID] [P?] [Story] Description` format with `T001…` numbering across phases: Phase 1 Setup, Phase 2 Foundational (blocking), one phase per User Story in priority order (Goal, Independent Test, tasks tagged `[US1]`, Checkpoint), Polish & Cross-Cutting (includes running plan.md's Testing Strategy), Dependencies & Execution Order. `[P]` marks parallelisable tasks; every task names a file path.

### design.md (OpenSpec, optional)
`## Context`; `## Goals / Non-Goals`; `## Decisions` (decision - rationale - alternatives); `## Risks / Trade-offs` (risk - mitigation).

### tasks.md (OpenSpec)
Numbered groups `## N. <capability>` with `- [ ] N.M` checkbox tasks, one group per capability named in the proposal; planning level only.

## MCP server - `@myspec/mcp-server` (stdio) and `mcp.myspec.dev` (HTTP)
Install: `npx -y @myspec/mcp-server login` (browser OAuth; `--paste` for remote machines; `--org <slug>` to pin an organization), then add `{"command":"npx","args":["-y","@myspec/mcp-server"]}` to `.mcp.json` / Claude Desktop config, or `claude mcp add --scope user myspec -- npx -y @myspec/mcp-server`. Unattended: `MYSPEC_API_TOKEN=msp_pat_…` (created in the webapp under avatar → API tokens → Create token; scoped to one organization, read-only or read-write, both fixed at creation; expiry 30/90/180/365 days, 90 by default, extendable up to two years total; shown once). Hosted / no-filesystem clients: `POST https://mcp.myspec.dev/mcp` with `Authorization: Bearer msp_pat_…` (stateless Streamable HTTP; optional `X-MCP-Tools` header narrows the tool list).

Tools (31 on each server):
- Projects: `list_projects`, `get_project`, `create_project`, `update_project`, `archive_project`, `unarchive_project`, `delete_project` (archive first).
- Spec files: `list_spec_file` (with `trashed=true` for the Trash Bin), `get_spec_file` (returns `content_version`, an integer), `read_spec_file` (paginated by line, 2,000 lines and 1 MiB per response, files above 8 MiB refused; stdio caches under `~/.myspec`), `download_spec_file` (stdio only; binary-safe, up to 50 MiB, lands in `.specs/` by default), `upload_spec_file`, `update_spec_file` (pass `expected_version` to refuse overwriting a concurrent edit - required on HTTP, optional on stdio).
- Trash: `move_spec_file_to_trash`, `restore_spec_file_from_trash` (list entries with `list_spec_file trashed=true`; HTTP keeps a deprecated `list_trashed_spec_files` alias).
- Attachments: `list_attachments`, `get_attachment`, `read_attachment` (text paginated by line, images inline), `upload_attachment` (PDF, DOCX, XLSX, UTF-8 text ≤10 MiB).
- Spec sessions: `list_spec_sessions`, `get_spec_session`, `rename_spec_session`, `archive_spec_session`, `unarchive_spec_session`, `delete_spec_session` (archive first; chat transcripts are never returned).
- Artifacts (new, MCP only - no browser UI yet): `list_artifacts`, `get_artifact`, `read_artifact_file`, `create_artifact`, `write_artifact_revision`, `rollback_artifact` - multi-file bundles versioned as one snapshot (50 files, 2 MiB per file, 10 MiB per revision); `rollback_artifact` appends a revision rather than rewriting history.
- Reverse mode (`reverse --root <dir>`): `local_fs_list_dir`, `local_fs_read_file`, `local_fs_grep`, `local_pack_codebase`, `local_pack_codebase_read_page` - read-only, sandboxed to the root, secrets excluded.

Spec file paths must be rooted at `specs/` or `openspec/` and nest at most three directory levels. Environment variables: `MYSPEC_API_TOKEN`, `MYSPEC_USER_AUTH_URL`, `MYSPEC_DOWNLOAD_ROOT`, `MYSPEC_AI_AGENT_WS_URL`.

## Pricing
Open Beta is live; pricing kicks in at GA. Plans: Free (20 projects, 100 spec files, 20 public share links/month, 1 member), Pro (100 projects, unlimited specs and share links, 5× the AI limit of Free, 2 members), Team (unlimited projects and specs, 10× the AI limit of Free per seat with a 2-seat minimum, shared projects & roles, centralized billing). Enterprise is contract-priced. Export the full bundle ZIP anytime.