Architect

Facilitated Architecture Exploration

Explore architectural decisions through guided conversation. Each decision is derived from the product's actual needs, and each is recorded with the options that were weighed and what they were weighed on.

Everything this skill records is a typed tool call. It composes no markdown, allocates no numbers, names no files, and never reads back what it or another skill wrote.

Follow the shared conventions in dpm/shared/skill-conventions.md — read that file at startup. This skill uses Gate Presentation, Perspectives, Conversational Output, Written Deliverable Length, Cross-References and Artifact Publishing from it.

Input

Resolve the document these decisions belong to, in this order.

1. If $ARGUMENTS names a document — a ULID, or a human reference as another skill printed it — read it with the tool for its kind. A reference goes through mcp__plugin_dpm_dpm__resolve_reference first, which returns the row it names or refuses; a ULID is already the id and needs no resolving.
2. Otherwise mcp__plugin_dpm_dpm__list_product_brief, and offer the results with AskUserQuestion. Fall back to mcp__plugin_dpm_dpm__list_problem_brief, then mcp__plugin_dpm_dpm__list_spec, then mcp__plugin_dpm_dpm__list_discussion. Ask which one; never take the most recent.
3. If none exist, ask the user to describe the system, and say that the decisions will need a document to hang off before they can be recorded.

An ADR is a child document, and the parent is chosen here rather than derived. Four kinds may hold one — problem brief, product brief, spec and discussion — and mcp__plugin_dpm_dpm__create_adr refuses any other, so the choice made now is the one checked at write time.

Read the chosen document with the tool for its kind — mcp__plugin_dpm_dpm__read_product_brief, mcp__plugin_dpm_dpm__read_problem_brief, mcp__plugin_dpm_dpm__read_spec or mcp__plugin_dpm_dpm__read_discussion — and its prose with mcp__plugin_dpm_dpm__list_document_section and mcp__plugin_dpm_dpm__read_document_section with include_body. The constraints and success criteria it records are what makes a decision this product's rather than boilerplate, and they are in the section body a read that does not ask for it leaves out.

Then mcp__plugin_dpm_dpm__list_adr on that parent for decisions already recorded, and mcp__plugin_dpm_dpm__read_adr on each. Summarise them and ask whether they still hold. Facilitate only the gaps.

Startup

Session

Follow the shared Session Startup procedure with skill: 'dpm:architect'.

The resolved parent's id belongs in state, along with each decision settled so far, because Phase 3 iterates and a run resumed mid-iteration has no other way back to the decisions already agreed.

Roster

mcp__plugin_dpm_dpm__list_agent with include_body, for Perspectives in Phases 2 and 4. The traits are body columns, so without it the roster arrives as names and roles. Use only what the row carries.

Library

Follow the shared Library Check procedure with scope keyword architect. Carry what it returns into Phases 2 and 3 — an architecture document or a coding standard constrains which options are live, and an option a standard rules out should be presented as ruled out rather than quietly dropped.

Retro awareness

Follow the shared Retro Awareness procedure. If incorporated:

• Codebase discoveries inform Phase 2 — a surfaced limitation may be a load-bearing decision nobody has written down.
• Complexity underestimates inform Phase 3 — they name the axis this team habitually misreads.
• Patterns worth reusing inform Phase 3 — a proven approach belongs in the option set.
• Testing gaps inform Phase 4 — a decision that made something hard to verify is an operational cost, not a testing accident.

Codebase grounding

Survey what already exists — structure, dependency manifests, deployment configuration, conventions — and read enough of it to know the technology already in play. Carry it into every phase; Phase 1 reports it and Phase 2 derives from it. A greenfield project has none, which is a finding rather than a failure.

Process

Work through the phases one at a time, one gate per turn, each with AskUserQuestion.

Phase 1: Context

Summarise what already exists — stack, patterns, deployment shape, and the decisions already embedded in the code whether or not anyone wrote them down — together with the product context read in Input. Confirm the understanding before proposing anything.

Phase 2: Identify the decisions

Which decisions this product actually needs taken. Each has a label, a reason it matters for this product, and the feature or constraint that drives it.

A decision that could be asked of any product is boilerplate. "Choose a database" is not a decision; "where booking availability is held given concurrent writes" is. If the driving requirement cannot be named from the parent document or the codebase, that is the signal to drop it rather than to invent one.

Aim for three to eight. Present the list and refine it — the user will know of decisions already taken and of ones not worth taking yet.

Perspectives: after the list is drafted, follow the shared Perspectives procedure — two or three agents on what is missing, what is premature, and what is operational rather than structural.

Phase 3: Options and trade-offs

One decision at a time. For each: two to four options, each a path someone would genuinely take, and an assessment of each against the axes that matter.

Default axes: complexity, scalability, team capability, operational cost, time to market. They are a starting set rather than a schema — a decision turning on data residency or on reversibility adds that axis, and one where an axis is irrelevant drops it. Use the same axes across the options of a single decision, because the comparison is the point: an option assessed on axes the others were not is an option nobody can weigh.

Then the recommendation and why, and what the choice constrains or depends on among the other decisions.

Gate each decision before moving to the next. Record what was settled in the session state as it is settled.

Phase 4: Operational architecture

Deployment, monitoring, failure modes, data lifecycle, security boundaries. Not every concern applies; skip what does not. Some of these become decisions of their own and go back through Phase 3; the rest is context that sharpens decisions already taken.

Perspectives: follow the shared Perspectives procedure — two or three agents on what breaks in production and how anyone would know.

Phase 5: Dependencies

Present the decisions as a set: which constrain which, which must be taken first, which are independent. Flag any cycle or conflict and work it through with the user.

Phase 6: Record the decisions

One ADR per decision. Render it in the message body from what the phases settled, then gate: "Approve this decision?" with Approve / Request changes / Stop. On approval, write it:

1. mcp__plugin_dpm_dpm__create_adr with the resolved parent as parent_id, a short kebab-case slug, a title, and the choice in one sentence as decision.
2. Its context and its consequences as mcp__plugin_dpm_dpm__create_document_section rows against the id it returned, with headings and position: Context, Consequences.
3. Each option as mcp__plugin_dpm_dpm__create_adr_option with name, position, and the reasoning as rationale — the rejected options carry theirs too, which is what makes the record worth having. chosen goes on the one taken.
4. Each assessment as mcp__plugin_dpm_dpm__create_adr_option_tradeoff with the option, the axis and the assessment.
5. mcp__plugin_dpm_dpm__update_adr setting decision_status to accepted.

The order matters and the tool enforces it. An accepted ADR has exactly one chosen option, so the status is written last — an ADR has no options at the moment it is created, and a second chosen is refused rather than stored. decision_status also has values for a decision that has not settled: leave one proposed where the user is not ready, and rejected records that the question was asked and answered no.

The axes are rows, not a layout. Each assessment is its own row keyed by option and axis, which is why the same axes can be compared down a column. Do not format a table — the projection renders one from the rows.

Then the relationships from Phase 5: mcp__plugin_dpm_dpm__create_dependency with kind: 'constrains', the constraining decision as source_document_id and the constrained one as target_document_id. Check the kinds available with mcp__plugin_dpm_dpm__list_dependency_kind rather than assuming this list is current.

Write nothing until the decision is approved. A half-written ADR is one a later run will read back as settled, and nothing on it says which of its options were real.

Revisiting a decision

When a decision replaces an earlier one, three calls in this order: mcp__plugin_dpm_dpm__create_adr for the new decision, then mcp__plugin_dpm_dpm__create_dependency with kind: 'supersedes', the new ADR as source_document_id and the old one as target_document_id, then mcp__plugin_dpm_dpm__update_adr moving the old one's decision_status to superseded.

The edge comes before the status, because the old decision is only findable through it. A superseded ADR with nothing pointing at it is a decision a reader can see was abandoned and cannot see what replaced it — which is the state the integrity register reports, and writing the edge is what stops it being created. Do not edit the old ADR's prose to say it was superseded: the status is a column and the replacement is an edge, and a sentence saying so is a third copy that will disagree with them.

Output

There is no file to save. An ADR renders inside the document it hangs off — its options, their axes and its prose all in place — and the projection decides where that is.

Do not tell the user a path. Building one from a number and a slug is the filename construction this skill does without, and an ADR has no number of its own to build one from.

An artifact can be published from this output on request — follow the shared Artifact Publishing procedure. It is separately confirmed and never the default.

For architect the artifact is a decision map: the ADRs as one connected set, drawn from the constrains and supersedes edges — so the decision everything hangs off is visible, and so is the one nothing references. A single ADR cannot show that, because the relation lives between them. If you cannot write the one-line justification for what the visual carries that the prose cannot, it has not earned its place.

Record it only once published, with mcp__plugin_dpm_dpm__create_artifact carrying its address, title and publication time, then mcp__plugin_dpm_dpm__create_artifact_document binding it to the parent document — so the rows never claim a visual a reader cannot reach.

After the decisions

• /dpm:spec to build requirements with these decisions as architectural context
• /dpm:epics where a spec already exists and needs aligning to them

Guidelines

• Facilitate, let the user lead. Present analysis, not prescriptions.
• Explore before proposing. Understand what exists before suggesting what should.
• Product-derived decisions. A decision that cannot name its driving requirement is boilerplate.
• Honest trade-offs. Every option carries its genuine costs, including the one recommended.
• Operational architecture is architecture. Deployment, monitoring, failure and security get the same rigour as structure.
• One decision at a time in Phase 3, and one gate per decision in Phase 6.
• Correct yourself sparingly, per the shared convention.