Rfc

RFC Manager

Manage architecture RFCs with 5 operations: create, review, list, update, status.

Argument Parsing

Parse $ARGUMENTS to determine the action:

| First word | Remaining args | Operation | |------------|---------------|-----------| | create | ` | Draft a new RFC | | review | | Review an existing RFC | | list | (none) | List all RFCs | | update | | Update specific RFC sections | | status | ` | Transition RFC status with validation and side effects | | (empty) | | Ask the user which action to perform |

If the first word does not match any action, treat the entire $ARGUMENTS as a topic and default to create.

RFC Directory Discovery

Used by all operations. Search for RFC files across all convention paths (exclude *.spec.md companion files):

1. docs/rfcs/*.md
2. docs/20-architecture/rfcs/*.md (jd-docs — detected via .jd-config.json or docs/20-architecture/ directory)
3. .arkhe/rfcs/*.md (arkhe convention)
4. arkhe/rfcs/*.md

For create and update, resolve a write directory:

• If jd-docs detected → docs/20-architecture/rfcs/
• Else if docs/rfcs/ exists → docs/rfcs/
• Else → create docs/rfcs/ as default

Operation: create

Draft a populated RFC — NOT a blank template. Gather context, write a spec, then write a real first draft with honest self-assessment.

1. Determine topic from args after create (or ask if empty)
2. Gather context — search conversation, research artifacts (docs/30-research/, docs/50-research/, docs/research/), memory files, relevant source code, and ADRs (docs/20-architecture/22-adr/, docs/20-architecture/adr/, docs/adr/). See [WORKFLOW.md](WORKFLOW.md) for detail.
3. Confirm scope with user before drafting — present what you found and proposed scope. Use AskUserQuestion for meaningful alternatives.
4. Resolve number and slug — discover write directory, glob all convention paths for highest existing number, assign next (zero-padded 4 digits). Confirm title with user, generate kebab-case slug. Both spec and RFC will use NNNN-.
5. Write spec file — read spec template at ${CLAUDE_SKILL_DIR}/templates/rfc-spec-template.md. Fill Problem Statement, Key Constraints, Success Criteria, and Scope Boundaries with concrete content. Write to /NNNN-.spec.md. Present to user for confirmation via AskUserQuestion. See [WORKFLOW.md](WORKFLOW.md) for spec guidance.
6. Read RFC template at ${CLAUDE_SKILL_DIR}/templates/rfc-template.md for section structure
7. Draft populated RFC filling every section with substantive content. See [WORKFLOW.md](WORKFLOW.md) for per-section guidance. Set Author to git user name, Status to Draft, Date to today.
8. Append Author's Notes — below Open Questions, record: shortcuts taken, unverified assumptions, areas of uncertainty, low-confidence sections. Aim for 3-8 items. Be specific — these feed the adversarial review. See [WORKFLOW.md](WORKFLOW.md) for confession guidelines.
9. Write RFC to /NNNN-.md
10. Suggest next steps: /rfc review for adversarial design review (uses rfc-critic agent)

Operation: review

Adversarial review of the RFC using the rfc-critic agent — a dedicated red-team reviewer that reads the Author's Notes as attack vectors and checks spec alignment.

1. Read RFC at the given path (if empty, ask — suggest globbing docs/rfcs/*.md and docs/20-architecture/rfcs/*.md)
2. Load spec file — check for a companion NNNN-.spec.md alongside the RFC. If found, read it.
3. Discover architecture standards (check in order, use first found):

• .arkhe/roadmap/architecture.md (arkhe convention)
• docs/20-architecture/ directory (jd-docs convention)
• docs/architecture.md or docs/architecture/ (generic)
• Fall back to general best practices

1. Spawn rfc-critic agent — use the Agent tool (subagent_type: doc:rfc-critic). Pass: the RFC content, spec content (if found), architecture standards (if found). See [WORKFLOW.md](WORKFLOW.md) for delegation details.
2. Present review output — the agent returns a structured review with confidence score, verdict, concerns by severity (each with evidence citations), and improvements. Display to user.
3. Verdict criteria:

• Approve: No critical concerns, minor issues only
• Approve with changes: No critical concerns, has major concerns with clear fixes
• Needs redesign: Has critical concerns or fundamental architecture issues

1. Flag missing RFC template sections as Minor concerns
2. Suggest next steps: /rfc update to address findings

Operation: list

List all architecture RFCs with their current status.

1. Search all convention paths (see RFC Directory Discovery)
2. For each RFC, extract from headers: Number/Filename, Title (from # RFC: [Title] or first # heading), Status (Draft/Review/Approved/Rejected/Superseded — default "Unknown"), Author (default "—"), Date (default "—")
3. Output markdown table sorted by number descending (newest first):

# Architecture RFCs

| # | Title | Status | Author | Date |
|---|-------|--------|--------|------|

**Summary**: X total — Y Draft, Z Review, W Approved

1. If no RFCs found, suggest /rfc create

Operation: update

Re-draft specific sections of an existing RFC based on new context or feedback.

1. Read RFC at the given path (if empty, ask for path)
2. Identify sections to update:

• If user specified sections in conversation, update those
• If invoked after a /rfc review, use review findings to identify sections needing changes
• Otherwise, ask the user which sections to revise

1. Gather fresh context from conversation, research, and codebase for the sections being updated
2. Re-draft sections — rewrite identified sections with improved content. Preserve all unchanged sections exactly as-is.
3. Update Date to today. Keep Status unchanged unless user requests a transition.
4. Handle Author's Notes — if status transitions to Approved, strip the Author's Notes section entirely. If major sections were re-drafted, refresh the confessions. See [WORKFLOW.md](WORKFLOW.md) for lifecycle rules.
5. Check spec alignment — if a companion .spec.md file exists and the update touches Goals, Non-Goals, or Architecture Overview, verify the RFC still aligns with the spec. Flag drift to the user.
6. Show diff summary — list which sections were changed and a brief description of each change
7. Suggest next steps: /rfc review to verify the updates

Operation: status

Transition RFC status with validation, warnings, and side effects.

1. Find RFC — resolve number to file path by globbing all convention paths for NNNN-*.md. Read current status from **Status**: field.
2. Validate transition — check against valid transitions. Warn (but allow) on unusual paths:

• Valid: Draft → Review → Approved/Rejected, any → Superseded
• Warn: Draft → Approved (skipping Review), Approved → Draft (going backwards)
• On warning, use AskUserQuestion to confirm

1. Apply status change — update **Status**: field in the RFC
2. Side effects:

• → Approved: Strip ## Author's Notes section entirely

1. Confirm — show old status → new status, side effects applied

Valid statuses: Draft | Review | Approved | Rejected | Superseded

Note: The update operation still handles inline status changes during content updates. Use /rfc status for dedicated status transitions with validation.

Quality Standards

• Every section must contain real content, not placeholder text like [describe here]
• Reference specific files, packages, and patterns from the codebase
• If a section doesn't apply, state that explicitly with a one-line rationale
• Drafts should be good enough to review immediately, not skeletons to fill in later

Progressive Disclosure

• [WORKFLOW.md](WORKFLOW.md) — detailed per-operation workflows
• [EXAMPLES.md](EXAMPLES.md) — usage examples for all operations
• [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — common issues and solutions

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: joaquimscosta
• Source: joaquimscosta/arkhe-claude-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.