This page is an agent-readable workflow for Deck. Humans can follow along. Coding agents should treat the steps as the source of truth.

Build from evidence — agent workflow

• Use it when: the user says "build this Project", "implement what customers asked for in this Project" or "fix the issues in this Deck Project".
• Outcome: the code change does what the Project asks. Each requirement cites the Deck insights behind it. Tests pass. The Deck Project shows in_progress.
• Needs: Deck MCP and write access to the codebase. To read a linked Linear or Jira item, the client needs its own Linear or Jira tools. Deck stores only the link.

1. Probe Deck MCP

Call get_user_context. This must be a real tool call.

• 401 Unauthorized: tell the user to connect Deck MCP in this client (Settings → Connections). Stop.
• No Deck tools: fetch and follow https://docs.getdeck.io/docs/agents/getting-started/prompts/ai-pm.md. Stop this workflow until the tools work.

2. Open the Project

• The user pasted a Deck link: call get_platform_links with urls. Use the project_id from the result.
• The user named the Project: call list_projects with query.
• The user named nothing: call explore_workspace with view: "members" to get the user's own user_id. Then call list_projects with owner_user_id and status: "not_started". Ask the user to pick one.

Call explore_build_projects with the project_id. Read the overview, the success metrics, evidence.active_references, external_links and the parent initiative.

If the Project has no evidence, stop. Offer to find evidence with explore_insights and query, or with explore_subthemes and view: "insights". Add it with add_project_insights after a yes.

3. Read the evidence

Call explore_insights with each insight_id from evidence.active_references, at the same time. Read at most 20 first. Read the name, the category, the sentiment, the quotes and the source.

• For a bug, call read_transcript with the feedback_id of the insight. Look for the steps, the screen and the error text.
• When external_links has a Linear or Jira item, read it with the client's own Linear or Jira tool. Deck tools do not read the item body.

4. Write the requirements

Group the insights by the problem they describe. For each group, write:

• Requirement: one sentence that a test can check.
• Evidence: the insight IDs and the number of insights in the group.
• Type: a bug (BUGS_AND_ERRORS), a usability issue (USABILITY_ISSUES) or a feature request (FEATURE_REQUESTS).

List the requests that you leave out, with the reason. When customers ask for opposite things, write both and ask the user to choose.

5. Map the requirements to the code

Search the codebase for the screens, the routes and the error text in the quotes. For each requirement, name the files to change and the test to add. For a bug, write a failing test that shows the bug before you fix it.

6. Show the plan

Show the user the requirements, the files, the tests and the Deck updates in steps 7 and 8. Get a yes before you change code or call write tools.

7. Build

Call update_project_status with project_id and status: "in_progress" before you change code. Do not set completed. The team sets it when the change ships.

Follow the rules of the repository, for example its AGENTS.md or CLAUDE.md file. Keep the change inside the approved requirements. If you find more work, ask before you add it. Run the tests and the type check of the repository.

8. Collect feedback on the change (optional)

Call create_feedback_widget with name and project_id. Then call explore_widgets with the widget_id and follow its install_prompt to install the SDK on the new surface. New feedback then shows on the Project's Feedback tab. The prompt reads the publishable key from an environment variable. Never put a key in the code. See SDKs.

9. Write the pull request

In the pull request description, add:

• The deck_url of the Project.
• Each requirement with the Deck links of its insights. Each explore_insights result from step 3 has a deck_url.
• The tests that you added.

Rules

• Build only what the evidence and the Project sections support.
• Each requirement cites at least one insight ID from Deck. Never invent IDs.
• Never copy customer names, emails or quotes with personal data into code, test data, commits or pull requests. Link to the insight in Deck.
• Quote Deck's numbers. Do not compute your own.
• Show the plan and get a yes before you call write tools.
• Deck tools do not change Linear or Jira.
• Never ask for a dk_ API key.

Done when

• Each approved requirement has code and a test, and the tests pass.
• The pull request links the Deck Project and the insights.
• explore_build_projects shows the Project as in_progress.
• After the release, offer the Release impact check and Customer follow-up workflows.

See also: Projects, Insights and Model Context Protocol.