write-rfc

name	write-rfc
description	Write RFCs for the ToolHive ecosystem. Use when the user wants to create a new RFC, proposal, or design document for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects.
allowed-tools	Read, Glob, Grep, Bash(git:*), mcp__github__*, mcp__fetch__fetch, WebFetch, Task, Edit, Write, AskUserQuestion

Write RFC Skill

This skill helps you write high-quality RFCs for the ToolHive ecosystem following established patterns and conventions.

Overview

ToolHive RFCs follow a specific format with the naming convention THV-{NUMBER}-{descriptive-name}.md. The NUMBER must match the PR number and be zero-padded to 4 digits.

Workflow

Step 1: Gather Requirements

Before writing an RFC, ask the user about:

1. Problem Statement: What problem are they trying to solve?
2. Target Repository: Which repo does this affect?
   • toolhive - Core runtime, CLI (thv), operator (thv-operator), proxy-runner (thv-proxyrunner), virtual MCP (vmcp)
   • toolhive-studio - Desktop UI application (Electron/TypeScript)
   • toolhive-registry - MCP server registry data
   • toolhive-registry-server - Registry API server (thv-registry-api)
   • toolhive-cloud-ui - Cloud/Enterprise web UI (Next.js)
   • dockyard - Container packaging for MCP servers
   • multiple - Cross-cutting changes
3. Scope: What are the goals and explicit non-goals?

Step 2: Research the Ecosystem

Before drafting, research the relevant codebase:

2.1 Fetch Architectural Documentation

Use mcp__github__get_file_contents to read from stacklok/toolhive repo's docs/arch/ directory:

Document	Content
00-overview.md	Platform overview, key components
01-deployment-modes.md	Local vs Kubernetes modes
02-core-concepts.md	Nouns (Workloads, Transports, Proxy, etc.) and Verbs
03-transport-architecture.md	stdio, SSE, streamable-http transports
04-secrets-management.md	Secrets handling, providers
05-runconfig-and-permissions.md	Configuration format, permission profiles
06-registry-system.md	Registry architecture, MCPRegistry CRD
07-groups.md	Server grouping concepts
08-workloads-lifecycle.md	Lifecycle management
09-operator-architecture.md	K8s operator, CRDs
10-virtual-mcp-architecture.md	Virtual MCP aggregation

2.2 Review Existing RFCs

Read rfcs/ directory in this repository to understand patterns and check for related proposals.

2.3 Search Relevant Codebases

Use mcp__github__search_code or mcp__github__get_file_contents to explore:

Repository	Purpose
stacklok/toolhive	Core platform, CLI, operator, proxy
stacklok/toolhive-studio	Desktop UI
stacklok/toolhive-registry-server	Registry API server
stacklok/toolhive-registry	Registry data
stacklok/toolhive-cloud-ui	Cloud/Enterprise UI
stacklok/dockyard	Container packaging

Step 3: Draft the RFC

Create the RFC following the template structure from rfcs/0000-template.md.

Required Metadata

# RFC-XXXX: Title

- **Status**: Draft
- **Author(s)**: Name (@github-handle)
- **Created**: YYYY-MM-DD
- **Last Updated**: YYYY-MM-DD
- **Target Repository**: [from step 1]
- **Related Issues**: [links if applicable]

Core Sections

1. Summary - 2-3 sentences capturing the essence
2. Problem Statement - Current limitation, who's affected, why it matters
3. Goals - Specific objectives (bulleted)
4. Non-Goals - Explicit scope boundaries
5. Proposed Solution
   • High-Level Design (with Mermaid diagrams)
   • Detailed Design: Component changes, API changes, configuration changes, data model changes
6. Security Considerations (REQUIRED) - See security checklist below
7. Alternatives Considered - Other approaches evaluated
8. Compatibility - Backward and forward compatibility
9. Implementation Plan - Phased approach with tasks
10. Testing Strategy - Unit, integration, E2E, performance, security tests
11. Documentation - What needs documenting
12. Open Questions - Unresolved items
13. References - Related links

Security Considerations Checklist (REQUIRED)

Every RFC MUST address:

• Threat Model - Potential threats, attacker capabilities
• Authentication and Authorization - Auth changes, permission models
• Data Security - Sensitive data handling, encryption
• Input Validation - User input, injection vectors
• Secrets Management - Credentials storage, rotation
• Audit and Logging - Security events, compliance
• Mitigations - Security controls implemented

Step 4: Use Proper Conventions

Code Examples

• Use Go for API changes in toolhive, toolhive-registry-server
• Use TypeScript for toolhive-studio, toolhive-cloud-ui changes
• Use YAML for configuration examples
• Use Mermaid for diagrams (flowcharts, sequence diagrams)

Kubernetes CRDs

If the RFC involves Kubernetes, include CRD examples:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: example
spec:
  # ...

CRD types: MCPServer, MCPRegistry, MCPToolConfig, MCPExternalAuthConfig, MCPGroup, VirtualMCPServer

Step 5: File Naming

The RFC file should be named THV-XXXX-{descriptive-name}.md where XXXX is the PR number. Since you don't know the PR number yet, use a placeholder like THV-XXXX-{name}.md and remind the user to rename it to match the PR number after creating the PR.

Step 6: Review Checklist

Before finalizing, verify:

• Problem is clearly stated
• Goals and non-goals are explicit
• Security section is complete (all 7 areas addressed)
• Alternatives are discussed
• Diagrams illustrate complex flows
• Code examples are concrete and in the correct language
• Implementation phases are defined
• Testing strategy covers all levels
• File follows naming convention

ToolHive Architecture Summary

Platform Overview

ToolHive is a platform for MCP server management (not just a container runner):

• Proxy layer with middleware (auth, authz, audit, rate limiting)
• Security by default (network isolation, permission profiles)
• Aggregation via Virtual MCP Server
• Registry for curated MCP servers
• Multi-deployment: Local (CLI/UI) and Kubernetes (operator)

Key Binaries

Binary	Location	Purpose
thv	toolhive	Main CLI
thv-operator	toolhive	Kubernetes operator
thv-proxyrunner	toolhive	K8s proxy container
vmcp	toolhive	Virtual MCP server (aggregation)
thv-registry-api	toolhive-registry-server	Registry API server

Transport Types

• stdio - Standard input/output (requires protocol translation)
• SSE - Server-Sent Events (HTTP, transparent proxy)
• streamable-http - HTTP streaming (transparent proxy)

Design Principles

1. Platform abstraction over direct execution
2. Security by default (network isolation, permissions)
3. Extensibility through middleware
4. Cloud-native (K8s operators, containers)
5. RunConfig as portable API contract

Reference Files

• Template: rfcs/0000-template.md
• Contributing guide: CONTRIBUTING.md
• Existing RFCs: rfcs/THV-*.md