---
title: "Core concepts"
description: "The building blocks of MySpec, from organizations and projects to sessions, spec files, revisions and MCP."
---

> 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.

# Core concepts

This page defines the words you will see in MySpec. Each section links to the
page with the details.

## Organization (workspace)

An **organization** is the shared space for a team. It holds your projects,
your members and your settings. During sign-up the app calls it a
**workspace**; everywhere else it says **organization**. They are the same
thing.

You can belong to more than one organization and switch between them. You
always work in one **active** organization at a time.

See [Organizations and members](/guides/organizations/).

## Members and roles

Everyone in an organization is a **member** with one of three roles:

| Role | What it adds |
|---|---|
| **Member** | Creates projects, and works on each project as their [project role](#project-roles-and-teams) allows. |
| **Admin** | Also opens **Organization settings**: invites people, removes members, manages teams, the default project access, Custom Skills and the **Spec integrations** switch. Always **Admin** on every project. |
| **Owner** | Everything an admin can do, and can also remove admins. The person who creates an organization is its owner. |

Your **professional role** (for example Developer or Solution Architect) is
different. It is not a permission. It tells the AI how you work so it can
tailor its questions. See [Sign-in and your account](/guides/account/#professional-role).

## Project roles and teams

A **project role** says what you can do on one project:

| Role | What it allows |
|---|---|
| **Read** | View everything in the project, but change nothing. |
| **Write** | Also edit specs, comment and chat with the AI. |
| **Admin** | Also change the project's settings and who has access. |

Your role on a project is the highest of your organization's **default project
access**, the access the project gives you, and the access it gives your teams.
Organization owners and admins are always Admin, and whoever creates a project
gets Admin on it. With no role, you can't see the project.

A **team** is a group of members that owners and admins create. When a project
gives a team a role, every member of the team gets it.

See [Teams and project access](/guides/teams-and-project-access/).

## Project

A **project** holds everything for one product or codebase: its chats, spec
files and attachments. Each project has a type:

| Type | Meaning |
|---|---|
| **Greenfield** | A new product built from scratch. You describe what you want to build. |
| **Brownfield** | An existing codebase you want to change. MySpec explores the code first. |
| **Auto** | Not decided yet. MySpec offers every workflow and the one you pick decides. |

The type decides which workflows a new chat offers. See [Projects](/guides/projects/).

## Session (chat)

A **session** is one conversation with the AI that writes or changes spec
files. The **Chats** tab of a project lists sessions; the Usage page counts
them as **Sessions**. There are two kinds:

- **Generate** sessions write a new set of spec files.
  See [Generate sessions](/guides/generate-sessions/).
- **Edit** sessions change spec files you already have.
  See [Edit sessions](/guides/edit-sessions/).

A session can be **In progress** or **Completed**. You can archive a session
to make it read-only, and unarchive it later.

### Workflows and stages

Every session follows a **workflow**: a fixed series of **stages**. Most
stages write one spec file, and you review each file before the next stage
starts.

| Workflow | Project type | Stages |
|---|---|---|
| MySpec (default) | Greenfield | Interview → Constitution → Requirements → Solution → Tasks |
| SpecKit | Greenfield | Interview → Constitution → Specify → Plan → Tasks |
| OpenSpec | Brownfield | Explore → Proposal → Specs → Solution → Tasks |
| MySpec brownfield | Brownfield | Interview → Proposal → Requirements (→ optional Tasks) |
| MySpec edit | Greenfield | Reference → Describe → Review |
| MySpec edit for brownfield | Brownfield | Reference → Describe → Review, with access to your codebase |

The Interview and Explore stages write no file. They gather what the AI needs
for the stages that follow. For work on an existing codebase, see
[Work on an existing codebase](/guides/brownfield/).

## Spec files and bundles

A **spec file** is a Markdown document the AI writes, such as
`constitution.md` or `requirements.md`. You can read, edit, comment on and
download it. See [Spec files](/spec-files/) for what each file contains and
[View and edit spec files](/guides/spec-editor/) for the editor.

A **bundle** is the folder of spec files one Generate session produces. The
file explorer on the project page shows each bundle as a folder. You can
rename a bundle and download it as a ZIP file.

Files you remove go to the **Trash Bin**, where you can restore them.

## Revisions

Every saved change to a spec file creates a new **revision**. The 10 most recent
revisions stay available, so you can open them and compare them with each other. Each
revision shows who wrote it: you, a teammate or the AI assistant.

## Attachments

**Attachments** are files you upload to a project, such as PDFs or other
documents, for the AI to read as background. Each file can be up to 10 MB.
See [Attachments and local files](/guides/attachments/).

## Custom Skills

A **Custom Skill** is a piece of your team's domain knowledge, such as a
glossary or a compliance rule. Owners and admins write skills for the whole
organization, and each project picks the skills its sessions should use.
See [Custom Skills](/guides/custom-skills/).

## Comments

**Comments** are discussion threads on a spec file, attached to the text you
select. You can mention a teammate, reply and resolve a thread when it is
done. See [Comments](/guides/comments/).

## Share links

A **share link** is a public, read-only link to a snapshot of the spec files
you choose. Anyone with the link can view the files until it expires or you
revoke it. See [Share links](/guides/share-links/).

## API tokens

An **API token** lets a program use MySpec as you without a browser sign-in,
for example a coding agent on a server or in CI. Tokens start with `msp_pat_`
and belong to one organization. See [API tokens](/mcp/api-tokens/).

## MCP

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) connects AI
tools to data. MySpec uses it in two directions:

| Direction | What it does | Read more |
|---|---|---|
| Your agent uses MySpec | Claude, ChatGPT, Cursor and other MCP clients list your projects and read or update spec files. | [Connect your coding agent](/mcp/) |
| MySpec uses your servers | The AI in your sessions calls tools from MCP servers you add, such as your issue tracker. | [Connect your own MCP servers](/guides/your-mcp-servers/) |

Source: https://docs.myspec.dev/get-started/concepts/index.mdx