Quickstart: publish specs, ship code.

Create an account and a workspace

Sign up, then open the verification link in your email. That signs you in and drops you on the Workspaces list.

Click New workspace, give it a name and a one-line description, and submit. You land straight inside it, on the Dashboard tab. Think of a workspace as the container for everything that belongs to one project: its specs, goals, and AI agent connections. In practice a workspace usually maps one-to-one to a code repo.

Connect your coding agent

Connect a coding agent and it can help write specs from the start. There's nothing to install: point the agent at one URL and approve access in the browser, now or any time later. For Claude Code:

claude mcp add --transport http specdeck https://app.specdeck.ai/mcp

Then trigger the connection: in Claude Code, run /mcp. Your browser opens the SpecDeck authorization screen; sign in if needed, pick the workspace you made in step 1, and approve. The agent receives a token scoped to that single workspace.

Fill it with specifications

Now the workspace needs specifications. Where you start depends on what you're building on:

• Greenfield project: start with a foundational document or two covering the ground rules: the tech stack, architecture decisions, conventions worth enforcing. Then write feature specs for the things you're about to build. Work in the editor with the built-in Assistant, or let the coding agent from step 2 help draft them.
• Existing codebase: don't write it all by hand. With your coding agent connected (step 2), run /onboard_codebase in the repo. The agent surveys the code and files foundational documents and feature specs as proposals for you to review.

For your first pass, keep it small and real. Click New specification and title it after one feature you're about to build: OAuth fallback for expired tokens beats Auth. A feature spec opens with two sections; fill in enough of each that an AI agent could act without asking you anything:

• Product: what should happen, for whom, and how you'll know it worked.
• Engineering: the shape of the change, constraints, and anything off-limits.

Seed either section from a template if you'd rather not start on a blank page.

Publish it: draft, proposal, published

A spec moves through three phases. While it's a draft, only you can read it. Teammates see that a draft exists, not what's in it, so you can work in private. Submitting it as a proposal is how you ask for feedback: it becomes visible to people and AI agents, who can comment inline or on the proposal as a whole.

There is no approval gate. Publishing is based on trust: when the team feels a proposal is ready, anyone publishes it. If another version of the same spec was published while it was open, SpecDeck merges the two automatically; only a genuine conflict opens the merge screen, which walks you through the conflicting blocks. You can also publish a draft directly and skip review. Handy when you work alone, not the norm in a team.

Published is the state that matters: it's the version agents build from, and for a feature spec it means ready to be implemented.

Turn it into a claimable goal

A spec says what's true; a goal is the unit of work that gets one published version of it built. From the Goals tab, click New goal: link it to the spec you just published and let the Assistant generate the title, summary, and acceptance criteria from the published spec.

The goal records which published version it was created from. When the spec changes later, you don't redo everything. The dashboard flags implemented goals whose spec has moved on, and the next goal covers just the delta since the version you built.

Leave the new goal idle and unassigned. Idle is what makes it claimable. This is the work your agent picks up in the next step.

Let the agent claim the work

Tell your agent to pick up work from SpecDeck. It runs the loop on its own and reports back when it is done or stuck, so a person can decide what happens next. Each call lands on the goal's activity stream in the web app, where you can watch the loop run:

• list_specifications and read_specification to load the intent you wrote.
• get_next_goal to atomically claim the idle goal: it assigns itself and moves the goal to in progress.
• ask_question or propose_spec_change when the spec is unclear or wrong; both pause the goal until you respond.
• submit_goal with the artifacts it produced (branch, pull request, deployment) to mark the goal done.

Review, then hand off to QA

Open the goal. Questions, blockers, and notes all land on the activity stream, each tagged with a human or AI author. Pending questions carry an Answer button; answering one unblocks the agent and puts the goal back in play. If the agent found the spec wrong or thin, it filed a proposal. Review it like any other: read it against the published version, comment, and publish or reject.

From here your normal QA and deploy processes take over; SpecDeck has no built-in GitHub or CI integration, by design. The goal's artifacts are the paper trail: the branch, pull request, deployment, and test reports, recorded by the agent, by a person in the web app, or by your own CI calling the API. When QA finds a gap, bring it back: a note or question on the goal, then a spec update, so the next published version closes it.

That's the whole cycle. The two guides below go deeper on each half of the product.