# Write a spec with your team

Write a spec together on a task: live editing, comments, review requests and versions, then hand it to a session to build.

A spec in EasyCode is a **document** that lives on a task. Your team writes it together in the app, comments on it, asks for a review, and then a session started on the task reads it while it builds.

Before you start:

- Documents are off by default. EasyCode support turns them on, org by org. Until then a document page says _Documents aren't on for this org_, and your task is fine.
- A document follows its task: whoever may read or edit the task may read or edit its documents. A person with read access only sees _You can read this document_.
- You type on a computer. On a phone you can read, comment and answer a review.

## Create the spec

Open the task from the **Board**. See [workflows, gates and the board](/guides/workflows-and-the-board).

Under **Documents**, choose **New document**.

Set **Type** to **Spec**, give it a **Title**, and leave **Start from** on _The spec template_, or pick _A blank page_.

Choose **Create**. The spec template starts with _Summary_, _Acceptance criteria_ and _Out of scope_.

The other types are **Plan**, **Doc**, **Decision**, **Research**, **Review** and **Note**. A type sets the starting template and a label. It grants nothing.

## Write it together

Everyone on the page edits the same text live, and the header shows who is here now. There is no Save button: the badge says _Saving…_ and then _Saved_. If your connection drops, the page says _Reconnecting…_ and keeps your edits in that tab until you're back.

- Type **/** at the start of a line for blocks: **Heading**, **List**, **Task**, **Table**, **Code**, **Mermaid**, **Callout**, **Toggle**, **Image**, **Quote** and **Divider**.
- Type **@** to mention a person.
- The page menu has **Copy link**, **Copy as markdown**, **Rename** and **Archive**.

At 10 MB a document becomes read-only. **Copy to a new document** carries its text on.

## Comment on a passage

Select text or a block, then choose **Comment**. The **Comments** tab beside the document lists every thread. Reply in a thread, and **Resolve** it when it's done. A comment can sit on one block, or on the whole document.

## Ask for a review

Open the **Review** tab and choose **Request a review**.

Pick the **Reviewers**, add a **Note for the reviewers** if you want, and choose **Send request**.

EasyCode keeps the text exactly as it was when you asked, and tells each reviewer. A reviewer reads that version, sees what changed since the version they last reviewed, and answers once: **Mark &#x76;_&#x4E;_ reviewed** or **Ask for changes**. If you edit after asking, **Request again** asks about the latest text.

A review is a request. It holds back no run, push, pull request or publish. To make approval a real stop, put a gate in a workflow that shows the spec. Its approvers then decide on a pinned version of the document, and need read access to it. See [how do I set who approves a gate](/guides/workflows-and-the-board#how-do-i-set-who-approves-a-gate).

Only a person in the app can answer a review. A session can read it and comment.

## Read the history

The **History** tab lists every version: who changed it, and when. For any version you can show its **Text**, the **Changes from the one before**, or the changes **Against the latest**. Someone with edit access can choose **Revert to &#x76;_&#x4E;_**, which makes a new version and loses nothing. A version held by a gate or a review shows _Held by_.

Someone with full access can **Redact** an older version, for example one that held a secret by mistake. Its text is then gone for everyone. The latest version can't be redacted, so edit the text out first.

## Hand the spec to a session

Start a session on the task, from **Start task** on the task page or from the desktop app. See [start a session](/guides/start-a-session). The session gets the task's documents as context, and its assistant reads and writes them through EasyCode's tools:

- [`document_list`](/reference/mcp-tools#document-list) and [`document_get`](/reference/mcp-tools#document-get) read the spec.
- [`document_update`](/reference/mcp-tools#document-update) edits it, which makes a new version you can compare.
- [`document_comments`](/reference/mcp-tools#document-comments) and [`document_comment`](/reference/mcp-tools#document-comment) read and answer your comments.

So you can ask the assistant to tighten the acceptance criteria, then compare its version with yours in **History**.

A document that should outlive its task, such as reusable guidance, can go to the library: **Propose to Library** creates a draft for review. See [propose a library change](/guides/propose-a-library-change).

> **When documents pause**
>
> EasyCode staff can stop documents with [`documents`](/reference/kill-switches-and-modules#documents), in the app and in harness tools. With [`live_editing`](/reference/kill-switches-and-modules#live-editing) off, documents open read-only at their last version. Nothing you wrote is lost. See [kill switches and modules](/reference/kill-switches-and-modules).
