DOCS · REFERENCE · COMMANDS · BUILD

write-rfc/synthex:write-rfc

Build

RFC drafting with Architect & PM, parallel review pass.

Invocation

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

/synthex:write-rfc

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-rfc.md.

Last modified:

What it does, end-to-end

write-rfc/synthex:write-rfc produces a Request for Comments for a significant technical proposal — an architecture change, new system component, major refactor, or technology migration. Not bug fixes or small features.

  1. Loads config for the RFC directory and review-loop settings.

  2. Picks the next RFC number by scanning for NNNN-kebab-case-title.md files, creating the directory if needed.

  3. Gathers product context from the Product Manager: the user problem, product goals, success metrics, and supporting research. The PM supplies context but doesn't make the technical call.

  4. Runs an interactive design session led by the Architect, fed with the PM's context plus your existing specs, ADRs, previous RFCs, and CLAUDE.md. It covers the problem statement, proposed solution (with Mermaid diagrams, data models, API contracts), at least two genuine alternatives, migration strategy, risks, and acceptance criteria.

  5. Runs a review loop, up to max_cycles times. Each cycle:

    • spawns fresh reviewers in parallel — Architect (self-review: feasibility, consistency, scale), Product Manager (product alignment, metrics), Tech Lead (implementation feasibility, incremental delivery), and Security Reviewer (threat model, compliance);
    • merges their findings through the findings-consolidator, so overlapping findings arrive as one ranked list with attribution;
    • has the Architect resolve every finding at or above min_severity_to_address (CRITICAL and HIGH by default).

    Between cycles only the current draft, a one-line-per-finding summary of what's unresolved, and the cycle number carry forward. If cycles run out with CRITICAL or HIGH findings still open, they're recorded in the RFC's Open Questions.

  6. Writes the RFC and prints next steps.

Parameters

ParameterDescriptionDefaultRequired
titleShort title describing the proposalNoneYes
config_pathPath to synthex project config.synthex/config.yamlNo
--profile <tier>Override models.profile (economy, balanced, premium) for spawned reviewersmodels.profile config (balanced)No

Each spawned agent's model resolves in this order: --profile, then models.agents.<name>, then the models.profile delta, then the agent's own frontmatter. Claude Code applies this per call; on other hosts the model settings are advisory and used only where the host supports per-subagent model selection.

Configuration

KeyDefault
architecture.rfcs_pathdocs/specs/rfcs
architecture.review_loops.max_cyclesInherits review_loops.max_cycles (2)
architecture.review_loops.min_severity_to_addressInherits review_loops.min_severity_to_address (high)
models.profilebalanced

Review-loop settings resolve from architecture.review_loops first, then the global review_loops, then the hardcoded defaults.

Output

A file at {rfcs_path}/NNNN-{kebab-case-title}.md containing: Status (Draft, In Review, Accepted, Rejected, or Superseded), Date, Authors, Reviewers, Summary, Product Context, Problem Statement, Proposed Solution (Overview, Detailed Design, Implementation Plan), Alternatives Considered, Migration Strategy, a Risks and Mitigations table, Security Considerations (mandatory), Acceptance Criteria checkboxes, an Open Questions table, and Related Documents.

The implementation plan section must show incremental delivery — a big-bang rollout is treated as a red flag. The console summary lists status (Draft), the reviewers, and the count of open questions.

Examples

/synthex:write-rfc "Migrate order processing to event sourcing"
/synthex:write-rfc "Split the monolith's billing module into a service" --profile premium
/synthex:write-rfc "Adopt GraphQL federation" --profile economy

See also