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 and changes them in 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.

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.

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+) 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. 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:

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.

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 and Connect your coding agent.