Guides

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.

Last updated November 15, 2026View as Markdown

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.

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

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 vN, 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. The session gets the task's documents as context, and its assistant reads and writes them through EasyCode's tools:

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.

When documents pause

EasyCode staff can stop documents with documents, in the app and in harness tools. With live_editing off, documents open read-only at their last version. Nothing you wrote is lost. See kill switches and modules.

Something wrong or missing? Suggest a change

On this page