The web app: write, review, publish.

Core concepts

Read this once. Every screen and every MCP tool builds on these terms.

Goal statuses

Getting started

Create an account

Go to the sign-up page and you'll be asked for:

• A display name (optional).
• Your email.
• A password of at least 8 characters — a strength meter shows as you type.

Submit and you land on a Check your email screen. Open the email, click the verification link, and you're signed in and sent to your workspace list.

Sign in

Enter your email and password on the login page. From here you can also resend a verification email or start a password reset.

Workspaces

The workspace list

After login you land on Workspaces, a card grid of every workspace you belong to. Each card shows the name, description, and member count. If you own a workspace, a menu on the card gives you Workspace settings and Leave workspace.

Create a workspace

Click New workspace, enter a name and description, and submit. You go straight into the new workspace.

The workspace dashboard

Inside a workspace you have three tabs:

• Dashboard — the overview, with recent activity and highlights.
• Specifications — lists feature specs and foundational documents.
• Goals — lists every goal.

From here you create specs, foundational documents, and goals.

Workspace settings

Workspace owners get a settings page with:

• Name and description, editable.
• Members, with a role badge on each: owner or member. You can remove a member as long as one owner remains.
• Invite members. Search for a user by name, then click to send an invitation. A toast confirms it was sent. Pending invitations show with a Withdraw button.
• AI agents. Create and manage the agent users that connect over MCP and pick up goals.
• Delete workspace, which asks for confirmation.

Accept an invitation

Click the invitation link. SpecDeck accepts it and sends you to the workspace dashboard. If you are signed in as the wrong account, it offers to sign you in as a different one.

Specifications

Create a specification

From the Specifications tab:

• New specification creates a feature-scope spec with a product section and an engineering section. You can seed either section from a template.
• New document creates a foundational-scope spec with a single foundational section.

Edit a section

Open a spec to see its section tabs and the section editor. Each section is Markdown. To change a published section you work through a draft:

1. 1
   If no draft exists, the section shows Create Draft. Click it. SpecDeck copies the current published content into an editable draft.
2. 2
   Edit the Markdown.
3. 3
   The versions rail on the right lists every branch and version: drafts, proposals, published versions numbered v1, v2, and so on, and published branches. Click any entry to view or edit it.

Add a Mermaid diagram

Sections are plain Markdown, so you can add a diagram with a fenced code block tagged mermaid. Put the diagram source inside and close the fence. There is nothing to enable or store.

```mermaid
graph LR
  A[Draft] --> B[Proposal] --> C[Published]
```

The diagram renders in the published spec view and the read view of sections, in goal views (summary and acceptance criteria), in the Markdown editor live preview pane, and in the Assistant chat. The raw Markdown view always shows the source.

Submit and publish changes

When a draft is ready, publish it back to the section:

• No conflict: the draft publishes immediately as a new version.
• Conflict: SpecDeck opens the merge screen so you can resolve it.

Review a proposal

When an AI agent finishes editing a section, it creates a proposal. A proposal is a draft marked ready for review, and it is read-only until a person acts on it. When a proposal, or your own draft, conflicts with changes published since it branched, publishing it opens the three-panel merge screen:

A counter tracks X of Y conflicts resolved. Once every block is resolved, click Complete merge. The result publishes as a new version and you return to the spec.

The Assistant

The Assistant is a panel that helps you write and refine specs. Open it from the toggle next to the section editor, and it also appears on the new-goal form. It works on the current section. It does not write code.

It can:

• Chat about the section you have open.
• Run quick actions. Under / Actions it offers Spelling & grammar and Workspace consistency, which checks the section against the published specs in the workspace.
• Propose rewrites. Suggested edits arrive as an inline diff. You review and accept them before anything is published.
• Draft a goal. On the goal form it can draft a goal from the selected specification.

An AI Level dropdown sets how much capability each request uses, from Lite (fastest and cheapest) up to Max (most capable). You choose the level, and SpecDeck runs the right model behind the scenes. Free workspaces include Lite and Standard; organization workspaces add Pro and Max. Usage is covered by a weekly per-user AI budget, shown as a meter in the panel, that resets each week.

Goals

Create a goal

From the Goals tab, New goal is a split button:

• The main action opens the goal form. Link the goal to a specification, give it a title, and optionally add a summary and acceptance criteria.
• The dropdown offers Generate goal prompt, which gives you a prompt to hand to an AI agent so the agent creates the goal through the MCP server instead.

On the goal form, the Assistant can draft a goal from the selected specification.

The goal view

A goal page shows:

• Header: title, author, created date, and buttons to edit the goal and change its status or assignee.
• Status: idle, in progress, or done, set from the header.
• Summary and acceptance criteria: add or edit these inline.
• Pending questions: questions an AI agent asked, each with an Answer button. Answer them here to unblock the agent.
• Activity stream: every entry in time order, each tagged with a type and an author icon for human or AI. Blockers have a control to mark them resolved. At the bottom you can add a Note, Ask question, or Flag blocker.
• Right rail: the goal's assignee, any spec-change branches this goal produced, and the linked specification section.

How goals move

A goal starts idle. Assign it to an AI agent or a teammate and it moves to in progress. When the work is finished and any proposed spec changes are reviewed, mark it done. Agents can claim, update, and submit goals through the MCP server.

User settings

Your personal settings page covers:

• Appearance: dark or light mode, saved on toggle.
• Profile: display name (editable) and email (read-only).
• Date and time: timezone, date format, and 12 or 24 hour clock, with a live preview.
• Change password: current password plus a new one of at least 8 characters.