rfc-writer

name	rfc-writer
description	A CLI tool for creating, managing, and validating RFCs (Request for Comments) in a project. Invoke with `ion run rfc-writer`.
metadata	{"binary":"rfc-writer","version":"0.1.0"}

RFC Writer

Overview

RFC Writer is a CLI tool that manages an rfc/ directory in your project. It creates RFC documents from built-in templates, tracks metadata (authors, status, revisions), and validates that RFCs contain all required sections.

Use this tool when you need to:

• Propose a new feature, architecture change, or design decision
• Create a structured document for team review
• Ensure RFCs follow a consistent format

Commands

Initialize the RFC directory

ion run rfc-writer init

Creates the rfc/ directory in the current project. Run this once before creating RFCs.

Create a new RFC

ion run rfc-writer new \
  --title "Add user authentication" \
  --template standard \
  --author "username:[e-mail]" \
  --agent "claude-opus-4:co-author" \
  --description "Proposal for adding OAuth2-based authentication"

Required flags:

• --title — The RFC title (must be unique; errors if an RFC with the same title already exists)

Optional flags:

• --template — Template to use: standard (default), lightweight, architecture
• --author — Author in github_handle:email format (repeatable for multiple authors). If omitted, auto-detected from git config (github.user/user.name and user.email).
• --agent — AI agent in name:role format (repeatable)
• --description — Short description of the RFC

The RFC file is auto-numbered (e.g., rfc/0001-add-user-authentication.md) and initialized with status draft.

List all RFCs

ion run rfc-writer list

Shows all RFCs with their filename, title, and current status.

Validate an RFC

ion run rfc-writer validate rfc/0001-add-user-authentication.md

Checks that the RFC contains all sections required by its template and that its status is valid for the template type. Reports any missing sections or invalid status.

Update RFC status

ion run rfc-writer status rfc/0001-add-user-authentication.md -s review

Updates the status of an existing RFC. The new status must be one of the allowed values for the RFC's template (see below). Errors if the status is not permitted.

Required flags:

• -s / --set — The new status value

Record a revision

ion run rfc-writer revise rfc/0001-add-user-authentication.md \
  -m "Revised authentication flow to use PKCE" \
  --author "alice:[e-mail]" \
  --description "Updated proposal using PKCE flow" \
  --agent "claude-opus-4:co-author"

Appends a timestamped revision entry (with author) to the RFC's frontmatter and optionally updates the RFC description and agent list. Use this whenever you make meaningful changes to an existing RFC so the revision history is tracked.

Required flags:

• -m / --message — Description of what changed in this revision

Optional flags:

• --author — Revision author in github_handle:email format. Falls back to git config if omitted.
• --description — Update the RFC's short description
• --agent — AI agent in name:role format (repeatable, appended to RFC agent list; duplicates by name are ignored)

List available templates

ion run rfc-writer templates

Templates

Each template is a markdown file in src/templates/ with YAML frontmatter that configures its status_options and description. Required sections are derived from the H2 headings in the template body.

All templates must include the three special status options: draft, approved, implemented. These are displayed with color in list output (yellow, green, cyan respectively).

standard (default)

Full RFC for significant changes.

Allowed status options: draft, review, approved, rejected, superseded, withdrawn, implemented

Required sections:

• Summary — Brief explanation of the proposal
• Motivation — Why this change is needed, what problem it solves
• Detailed Design — Technical design with enough detail to implement
• Drawbacks — Reasons not to do this; impact on complexity and maintenance
• Alternatives — Other designs considered; impact of not doing this
• Unresolved Questions — Open questions and future work

lightweight

For smaller, well-scoped changes.

Allowed status options: draft, review, approved, rejected, withdrawn, implemented

Required sections:

• Summary — Brief explanation
• Proposal — The specific change and its scope
• Alternatives — Other approaches considered

architecture

Architecture Decision Record (ADR) style.

Allowed status options: draft, review, approved, superseded, withdrawn, implemented

Required sections:

• Context — The issue or constraint motivating the decision
• Decision — The change being made and how it addresses the context
• Consequences — What becomes easier or harder; positive and negative effects

RFC Metadata

Each RFC has YAML frontmatter with these fields:

---
title: "RFC Title"
description: "Short description of the proposal"
status: draft
authors:
  - github: "@username"
    email: "[e-mail]"
agents:
  - name: "claude-opus-4"
    role: "co-author"
created: "2026-03-21T12:00:00Z"
revisions:
  - timestamp: "2026-03-21T12:00:00Z"
    author:
      github: "@username"
      email: "[e-mail]"
    description: "Initial draft"
template: standard
---

Status values: Defined per template in its frontmatter (see Templates section). Three special statuses — draft, approved, implemented — are required for all templates and shown with color in list output.

How to Write a Good RFC

Before you start

• Identify the problem clearly. If you can't state the problem in one sentence, you need more thinking time.
• Check for existing RFCs that cover similar ground.
• Choose the right template: standard for significant changes, lightweight for small scoped work, architecture for infrastructure/design decisions.

Writing each section

Summary: Write this last. It should be 2-3 sentences that a busy reader can scan to decide whether to read the full RFC. Avoid jargon.

Motivation: Focus on the problem, not the solution. Include concrete examples, user pain points, or data. A reader who disagrees with the motivation will reject the RFC regardless of the design.

Detailed Design: Be specific enough that someone else could implement it. Include:

• API shapes, data models, or interface changes
• How it interacts with existing systems
• Error handling and edge cases
• Migration path if changing existing behavior

Drawbacks: Be honest. Every change has costs. Acknowledging them builds trust and often leads to better designs through discussion.

Alternatives: Show your work. Explain why rejected alternatives were worse, not just that they were considered. Include "do nothing" as an alternative when appropriate.

Unresolved Questions: Flag what you don't know yet. This invites focused feedback instead of broad bikeshedding.

Tips

• Keep the RFC focused on one decision. If you find yourself writing "additionally" or "also", consider splitting into multiple RFCs.
• Use concrete examples over abstract descriptions.
• Link to relevant code, issues, or prior art.
• Update the RFC status as it progresses through review.

Standard Commands

All binary skills support:

ion run rfc-writer self skill    # Output the SKILL.md
ion run rfc-writer self info     # Show version and build info
ion run rfc-writer self check    # Check for updates
ion run rfc-writer self update   # Update to the latest version