Design docs

Create a design doc when one change needs a spec, an implementation plan and a record of what lands. You keep those variations together under a number such as DD-0001. Numbers increase within your organization and are never reused, including after deletion.

Choose what to write

The three document presets give each variation a separate job:

Each document variation has a Brief with fields defined by its type. Read the brief to decide whether you need the full text. Computed fields, such as mentioned records and open questions, come from the saved record. An agent supplies a brief with its text; a brief is not approval or verification.

Mention catalog objects and documents in the text to connect the change to your architecture. Use the mention picker for an existing service. In Markdown written over MCP, [[Exact object name]] links an existing object and [[new: Proposed service]] records a proposed object. A person accepts a proposed object into the catalog or drops it. Writing a proposal does not create a catalog object.

Keep unanswered choices in Open questions, where each question has its own discussion and answer. You can add options and a preferred answer, assign a person, then answer or drop the question with a reason. Agents record a person's decision or a fact they checked; an agent report is not verification or approval.

Read the status

The document status comes from its variations and lifecycle actions:

Shipping freezes document variations. Later text edits require an amendment with a reason. Journals keep accepting entries after shipping.

Change sizes are optional and off by default. With sizes off, the rules use Standard. On Team and above, an administrator can enable Small, Standard and Large in Settings > Design docs. Size changes which variations and approval counts apply; an agent cannot change size to reduce review requirements.

One complete workflow

1. Open Design docs and create a doc with a title and location. Free includes one persistent design doc in addition to the example; Team includes unlimited design docs.
2. Open Spec, write what must be true and mention the services the change affects. Keep the brief consistent with the text.
3. Add tracked questions for unresolved choices. Discuss them, then record the answers people decide or drop questions that no longer apply. The default ship policy warns about remaining open questions and requires acknowledgement.
4. Write Implementation plan with the ordered work and checks. An agent can import a Markdown plan with import_plan_file and a brief through MCP.
5. Choose Planned changes. As work lands, use Recorded changes > Record a change, or ask your agent to call record_architecture_change. A missing recorded change never implies missing implementation.
6. On Business or Enterprise, enable evidence tracking and link pull requests. On Free or Team, record your outcome and checks in Evidence of work without GitHub evidence.
7. On Free, mark the Spec and Implementation plan ready. On Team, use Mark ready when your organization has enabled the approvals feature; with it off, you can ship from Draft. Review the ship dialog and select Mark shipped. If early-access criteria block shipping, a person with verification:manage can choose Mark shipped with exception and give a reason. The exception keeps the criterion results and does not bypass variation or open-question requirements.

A merged PR, a passing check, a closed issue and a correct deployment are different facts. Recording Shipped does not establish general availability or deployment correctness.

Plans and permissions

For acceptance criteria and the in-app Work Log tab: Early access. Email hello@archdocs.io to turn it on for your organization.

Deleting a design doc after it has content does not restore the Free allowance. Deleting one that has never had content returns its slot. Other upload and organization storage limits still apply. Free starts with readiness tracking on, sizes off and GitHub evidence tracking off. Configurable organizations with no saved settings start with approvals, sizes and evidence tracking off. Enabling the approvals feature on Team provides readiness controls; human review and approval still require Business or Enterprise.

The server requires docs:read to list, read and export design docs, and docs:write to create or edit them, manage questions, mark ready, request review, approve and ship. Deletion requires docs:delete. Plan entitlement and record visibility are checked separately. Organization settings and variation-type changes require org:manage; criteria authorization and evidence review require verification:review and a person. Verification policy edits and ship exceptions require verification:manage and a person. Resetting plan defaults requires both org:manage and verification:manage.

Read reviews and approvals, evidence and plan versus actual, acceptance criteria, work logs and handoffs and task context for each part of the workflow. The MCP tool reference lists agent inputs and effects.