DOCS · REFERENCE · COMMANDS · BUILD

write-adr/synthex:write-adr

Build

Interactive ADR authoring with the Architect.

Invocation

Run from inside Claude Code in any project where Synthex is installed:

/synthex:write-adr

Some commands accept parameters; see the source-of-truth file linked below for the full parameter list and workflow.

Lifecycle phase

Build. Parallel-executed, peer-reviewed task delivery.

  • Tech Lead · Full-stack orchestrator. Breaks tasks down, delegates to specialists, rolls up the result.
  • Lead Frontend Engineer · Coordinates frontend delivery, enforces UX quality, accessibility, and design-system fidelity.
  • Architect · System design, ADRs, plan-review feasibility, technology trade-offs.
  • Code Reviewer · Craftsmanship review — correctness, maintainability, reuse, conventions.
  • Security Reviewer · Mandatory gate. Secrets, injection, auth, supply chain, OWASP.
  • Quality Engineer · Test strategy, gap analysis, behavior-driven test authoring.
  • Design System · Token ownership, component governance, compliance audit.
  • Technical Writer · API docs, guides, migrations, changelogs verifiable against code.

Source

The command's parameters, workflow, and sub-agent invocations are defined in markdown at bluminal/lumenai/blob/main/plugins/synthex/commands/write-adr.md.

Last modified:

What it does, end-to-end

write-adr/synthex:write-adr records a technical decision as an Architecture Decision Record through an interactive session with the Architect agent. You make the call; the Architect advises.

  1. Loads config for the decisions directory (architecture.decisions_path).
  2. Picks the next ADR number by scanning that directory for NNNN-kebab-case-title.md files. Numbers are sequential and never reused, even for deprecated ADRs. The directory is created if it doesn't exist.
  3. Runs the Architect in ADR authoring mode, giving it your title, the existing ADRs (so it can cite related decisions), and your CLAUDE.md and specs. The session walks through:
    • Context — what problem, what constraints, what triggered the decision.
    • Alternatives — at least two genuine options besides the chosen one, with pros, cons, and trade-offs. "Do nothing" counts when the status quo is viable.
    • Decision — the Architect summarizes trade-offs; you decide.
    • Consequences — what gets easier, what gets harder, what risks it creates.
  4. Writes the ADR and prints a confirmation.

Parameters

ParameterDescriptionDefaultRequired
titleShort title describing the decisionNoneYes
config_pathPath to synthex project config.synthex/config.yamlNo

Configuration

KeyDefaultPurpose
architecture.decisions_pathdocs/specs/decisionsWhere ADRs are written

Output

A file at {decisions_path}/NNNN-{kebab-case-title}.md with these sections: Status (Proposed, Accepted, Deprecated, or Superseded by ADR-XXXX), Date, Context, Decision, Alternatives Considered (each with description, pros, cons, and why it wasn't chosen), Consequences (Positive, Negative, Risks), and Related Decisions.

Every ADR is meant to stand on its own — a reader shouldn't need other documents to follow it. Consequences always include both positive and negative outcomes.

Then a summary:

ADR-0007 written to docs/specs/decisions/0007-use-postgresql.md.

Status: Accepted
Decision: Use PostgreSQL as the primary datastore
Alternatives considered: 3

To reference this decision, link to: ADR-0007
To supersede this decision later, create a new ADR and update the Status field.

Examples

/synthex:write-adr "Use PostgreSQL for the primary datastore"
/synthex:write-adr "Adopt event sourcing for orders"
/synthex:write-adr "Replace REST polling with WebSockets" config/synthex.yaml

When to use an RFC instead

An ADR records one decision. For a significant proposal that needs product context, a detailed design, and multi-reviewer sign-off, use write-rfc/synthex:write-rfc.

See also

  • ADRs
  • write-rfc/synthex:write-rfc