---
title: "Spec files"
description: "What spec files and bundles are, where they live in a project, and what each file type contains."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec files

A **spec file** is a Markdown document that describes part of what you are
going to build: its principles, requirements, technical design or work plan.
MySpec writes spec files in [Generate sessions](/guides/generate-sessions/) and
changes them in [Edit sessions](/guides/edit-sessions/). You and your team can
also edit them by hand, comment on them and share them.

## Spec files and bundles

- A **spec file** is one `.md` file, such as `requirements.md`. Every time the
  AI or a person saves it, MySpec keeps the new version as a **revision**.
- A **bundle** is the set of spec files one Generate session produces, kept
  together in one folder. The AI picks a short name for it, such as
  `acme-portal`, and shows it in the chat. When the session completes, the
  **Session completed** card shows the bundle name.

You download a bundle as a ZIP file. See
[Finish a session and build](/guides/finishing-a-session/#download-your-specs).

## Where files live

Every project and session page has a file explorer. Spec files are listed under
**Specs**, in folders that follow their paths. A bundle from a session that is
still running shows **In Progress**; a finished one shows **Completed**.

| Workflow | Folder | Files |
|---|---|---|
| MySpec | `specs/<bundle>/` | `constitution.md`, `requirements.md`, `solution.md`, `tasks.md` |
| SpecKit | `specs/memory/` and `specs/<number>-<feature>/` | `constitution.md` in `specs/memory/`, shared by the project; `spec.md`, `plan.md` and `tasks.md` in the feature folder |
| MySpec brownfield | `specs/<bundle>/` | `proposal.md`, `requirements.md` and, if you run the optional Tasks stage, `tasks.md` |
| OpenSpec | `openspec/changes/<change-id>/` | `proposal.md`, `specs/<capability>/spec.md` (one per capability), `design.md`, `tasks.md` |

SpecKit numbers its feature folders: the first is `001-<feature>`, the next
SpecKit session in the same project uses `002-…`, and so on.

### Rename a bundle

Select **Rename bundle** next to a bundle in the file explorer. Use lowercase
letters, numbers and hyphens; one `/` adds a sub-folder. Bundles can be nested
at most three folders deep. All spec files in the bundle move to the new path.

## Files from the MySpec workflow

### constitution.md

Your project's guiding principles and non-negotiable rules. Every later spec
must stay consistent with it. It usually covers the project vision, core
principles, and constraints for technology, architecture, testing, coding
standards, security, performance and integrations.

### requirements.md

What the system must do, written so that each requirement can be tested:

- **Overview** and **User Roles**.
- **Functional Requirements**, numbered `FR-001`, `FR-002` and so on. Each has a
  description, the user roles it applies to and its acceptance criteria.
- **Non-Functional Requirements**, numbered `NFR-001` and so on, each with a
  measurable target and a priority.
- **Data Requirements** and **Integration Requirements**, when they apply.

Requirements describe what, not how: they don't prescribe technologies. See
[Writing requirements (EARS+)](/spec-files/ears-plus/) for how acceptance
criteria are written.

### solution.md

The technical blueprint: the technology stack and key design decisions, the
high-level architecture with a diagram, the system modules, the data model with
an entity-relationship diagram, API design, security architecture, deployment
and operations, and success criteria. Diagrams are written in Mermaid, so they
render in the viewer.

### tasks.md

An ordered work plan, grouped into milestones. Each task is a checkbox item
with implementation details, acceptance criteria, its dependencies, the
requirements it covers (for example `FR-001`) and a complexity of Small, Medium
or Large. A **Dependency Graph** section at the end shows the critical path and
what can run in parallel.

## Files from the SpecKit workflow

### constitution.md

The project's numbered core principles (a principle can be marked
non-negotiable), additional constraints, the development workflow and how the
constitution is governed, with a version number. SpecKit keeps one constitution
for the whole project in `specs/memory/`. Later SpecKit sessions update it
rather than writing a new one.

### spec.md

What to build and why, independent of implementation details:

- **User Scenarios & Testing**: user stories with a priority (P1, P2, P3), why
  each has that priority, how to test it on its own, and acceptance scenarios.
- **Edge Cases**.
- **Requirements**: functional requirements and the key entities involved.
- **Success Criteria**: measurable outcomes.
- **Assumptions**.

### plan.md

The technical implementation plan: a summary, the technical context (language,
main dependencies, storage, testing, target platform, performance goals and
constraints), a check against the constitution, the high-level architecture,
system modules and data model.

### tasks.md

Tasks in phases: setup, foundational work, then one phase per user story in
priority order (the first is the MVP), and a final polish phase. Each task has
an ID such as `T001`. `[P]` marks tasks that can run in parallel, and a story
tag such as `[US1]` links a task to its user story.

## Files for an existing codebase

These files come from the [Brownfield workflows](/guides/brownfield/). They
describe a change to existing code, not a product from scratch.

### proposal.md

Why the change is needed and what it changes, based on what the AI read in your
code.

- **MySpec brownfield**: **Why**, **What Changes**, a **Technical Solution**
  (library or framework changes, core flow changes, data model or database
  schema changes and breaking API changes) and **Impact**.
- **OpenSpec**: **Why**, **What Changes**, **Capabilities** (the parts of the
  system that get a delta spec, split into new and modified) and **Impact**.

### requirements.md (MySpec brownfield)

A requirements delta: only what changes. It lists the impacted user roles, then
one section per affected module. Each entry has one of three codes:

| Code | Meaning | Contains |
|---|---|---|
| `AR-001` | Added requirement | Description, user roles and acceptance criteria |
| `BR-001` | Removed requirement | Why it is removed, and a reference to the file and line in your code that describes the original requirement |
| `CR-001` | Changed requirement | What changes and why. Old acceptance criteria are struck through, with the new ones below |

### Delta spec files (OpenSpec)

One `spec.md` per capability, in `specs/<capability>/` inside the change
folder. Each uses up to four sections: **ADDED Requirements**, **MODIFIED
Requirements**, **REMOVED Requirements** and **RENAMED Requirements**. Every
added or modified requirement states what the system SHALL do and has at least
one scenario written as **WHEN** … **THEN** … bullets.

### design.md (OpenSpec)

The technical approach for the change: context, goals and non-goals, decisions,
and risks and trade-offs. This is the OpenSpec workflow's Solution stage.

### tasks.md

A numbered checklist of implementation tasks. OpenSpec groups the tasks by
capability. MySpec brownfield groups them into milestones and ends with a
dependency graph.

## How files change over time

Spec files are living documents. Each save, by the AI in a session or by a
person in the editor, adds a new revision; the 10 most recent revisions stay
available. In a chat, a spec file card shows its revision, such as **Rev 2**.

In the file explorer, open a file's revision list to read any revision, see who
saved it, and compare two revisions as a diff. See
[View and edit spec files](/guides/spec-editor/).

## How coding agents read them

Coding agents read your spec files over MCP. An agent can list a project's spec
files, read the latest revision or any earlier one, and update a file. When it
updates a file, it can pass the version it read: if someone else saved the file
in the meantime, the update is rejected instead of overwriting their work. See
[Tool reference](/mcp/tools/) and
[Connect your coding agent](/mcp/).

Source: https://docs.myspec.dev/spec-files/index.mdx