rdimitrov · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026
diff --git a/.claude/skills/respond-to-rfc-comments/SKILL.md b/.claude/skills/respond-to-rfc-comments/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: respond-to-rfc-comments
-description: Help respond to review comments on an RFC pull request. Use when the user wants to address, reply to, or resolve feedback on an open RFC PR for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects.
+description: Help respond to review comments on an RFC pull request. Use when the user wants to address, reply to, or resolve feedback on an open RFC PR for any project in this repository (toolhive, mecatl, ...), including the toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard repositories.
 allowed-tools: Read, Glob, Grep, Bash(git:*), mcp__github__*, mcp__fetch__fetch, WebFetch, Edit, Write, AskUserQuestion
 ---
 
@@ -24,7 +24,7 @@ Gather all review feedback from the PR:
 
 ### Step 2: Read the RFC
 
-Read the full RFC document so you have context for every comment.
+Read the full RFC document so you have context for every comment. Also read the root `AGENTS.md` and the `AGENTS.md` in the RFC's project folder, so proposed changes follow the project's conventions.
 
 ### Step 3: Present Comments One at a Time
 
@@ -85,7 +85,7 @@ After replies are posted, ask the user if they want to commit and push. If confi
 - When renaming fields or terms, use `replace_all` to catch every occurrence.
 - When adding new sections, match the style of existing sections in the RFC.
 - When adding sections required by the template (e.g., Security Considerations), reference existing RFCs in the repo for structural patterns:
-  - Search for the section name across `rfcs/THV-*.md` files.
+  - Search for the section name across `<project>/<PREFIX>-*.md` files.
   - Use 2-3 examples to match the established format (threat model tables, subsection structure, etc.).
 
 ### PR-Level Comment Responses

diff --git a/.claude/skills/review-rfc/SKILL.md b/.claude/skills/review-rfc/SKILL.md
@@ -1,12 +1,12 @@
 ---
 name: review-rfc
-description: Review RFCs for the ToolHive ecosystem. Use when the user wants to review, critique, or provide feedback on an RFC for toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard projects.
+description: Review RFCs for any project in this repository (toolhive, mecatl, ...). Use when the user wants to review, critique, or provide feedback on an RFC, including ones for the toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard repositories.
 allowed-tools: Read, Glob, Grep, Bash(git:*), mcp__github__*, mcp__fetch__fetch, WebFetch, Task
 ---
 
 # Review RFC Skill
 
-This skill helps you thoroughly review RFCs for the ToolHive ecosystem, ensuring they meet quality standards, architectural alignment, and security requirements.
+This skill helps you thoroughly review RFCs for the projects in this repository, ensuring they meet quality standards, architectural alignment, and security requirements.
 
 ## Overview
 
@@ -18,27 +18,13 @@ When reviewing an RFC, you should evaluate it against multiple dimensions: compl
 
 First, read the RFC document completely. If provided a PR number or file path, fetch and read it.
 
-### Step 2: Fetch Architectural Context
+### Step 2: Load Project Context
 
-Before reviewing, gather context from the ToolHive architecture documentation. Use `mcp__github__get_file_contents` to read relevant docs from `stacklok/toolhive` repo's `docs/arch/` directory:
-
-| Document | When to Read |
-|----------|--------------|
-| `00-overview.md` | Always - understand platform concepts |
-| `01-deployment-modes.md` | RFCs affecting deployment, K8s, or local mode |
-| `02-core-concepts.md` | RFCs introducing new concepts or terminology |
-| `03-transport-architecture.md` | RFCs affecting MCP transports or proxy |
-| `04-secrets-management.md` | RFCs involving secrets or credentials |
-| `05-runconfig-and-permissions.md` | RFCs affecting configuration or permissions |
-| `06-registry-system.md` | RFCs affecting registry functionality |
-| `07-groups.md` | RFCs involving server grouping |
-| `08-workloads-lifecycle.md` | RFCs affecting workload management |
-| `09-operator-architecture.md` | RFCs affecting K8s operator or CRDs |
-| `10-virtual-mcp-architecture.md` | RFCs involving aggregation or virtual MCP |
+Read the root `AGENTS.md`, then the `AGENTS.md` in the RFC's project folder. Use its "Research before writing or reviewing" section to fetch the architecture docs relevant to this RFC (for example with `mcp__github__get_file_contents`), and use its architecture summary, design principles and conventions as the standard to review against.
 
 ### Step 3: Check Related Existing RFCs
 
-Search this repository for related RFCs that might:
+Search the project folder for related RFCs that might:
 - Conflict with the proposal
 - Be superseded by the proposal
 - Provide context or dependencies
@@ -92,12 +78,11 @@ The Security Considerations section MUST address all of these:
 
 ### C. Technical Accuracy
 
-- [ ] **Correct terminology**: Uses ToolHive concepts correctly (Workloads, Transports, Middleware, etc.)
-- [ ] **Architecture alignment**: Follows established patterns and principles
+- [ ] **Correct terminology**: Uses the project's concepts correctly (see the project's `AGENTS.md`)
+- [ ] **Architecture alignment**: Follows the design principles in the project's `AGENTS.md`
 - [ ] **Code examples**: Syntactically correct, idiomatic for the language
 - [ ] **API design**: Consistent with existing APIs in the target repo
-- [ ] **CRD design**: Follows Kubernetes conventions if applicable
-- [ ] **Configuration format**: Matches existing RunConfig patterns
+- [ ] **Project conventions**: Follows the "Conventions" section of the project's `AGENTS.md` (CRDs, configuration formats, etc.)
 
 ### D. Diagrams and Examples
 
@@ -114,35 +99,9 @@ The Security Considerations section MUST address all of these:
 - [ ] **Performance impact**: Considered where relevant?
 - [ ] **Cross-repo impact**: If `multiple` repos, are all impacts identified?
 
-## ToolHive Ecosystem Context
-
-### Target Repositories
-
-| Repository | Type | Key Considerations |
-|------------|------|-------------------|
-| `toolhive` | Go | Core platform, CLI, operator, proxy, virtual MCP |
-| `toolhive-studio` | TypeScript | Desktop UI, Electron app |
-| `toolhive-registry-server` | Go | Registry API, MCP Registry spec compliance |
-| `toolhive-registry` | Go/JSON | Registry data, server definitions |
-| `toolhive-cloud-ui` | TypeScript/Next.js | Cloud UI, OIDC integration |
-| `dockyard` | Go | Container packaging, security scanning |
-
-### Key Architecture Principles to Verify
-
-1. **Platform, not runner**: Does this enhance the platform abstraction?
-2. **Security by default**: Does this maintain or improve security posture?
-3. **Middleware composability**: Can this be implemented as middleware if appropriate?
-4. **RunConfig portability**: Does this preserve configuration portability?
-5. **Cloud-native**: Is this Kubernetes-friendly where applicable?
-
-### CRD Types (for K8s-related RFCs)
+## Project Context
 
-- `MCPServer` - Individual MCP server deployment
-- `MCPRegistry` - Registry configuration
-- `MCPToolConfig` - Tool filtering and configuration
-- `MCPExternalAuthConfig` - External authentication
-- `MCPGroup` - Server grouping
-- `VirtualMCPServer` - Aggregation of multiple servers
+Target repositories, architecture principles to verify, and domain-specific checks (such as CRD types for Kubernetes RFCs) are defined per project in `<project>/AGENTS.md`. Verify the RFC against each design principle listed there.
 
 ## Review Output Format
 
@@ -172,7 +131,7 @@ Structure your review as follows:
 [Specific feedback on the security section]
 
 ### Architectural Alignment
-[How well does this align with ToolHive architecture?]
+[How well does this align with the project's architecture and design principles?]
 
 ### Questions for the Author
 - [Clarifying questions that need answers]
@@ -212,6 +171,8 @@ Structure your review as follows:
 
 ## Reference Files
 
-- Template: `rfcs/0000-template.md`
+- Shared rules: `AGENTS.md`
+- Project rules: `<project>/AGENTS.md`
+- Template: `template.md`
 - Contributing guide: `CONTRIBUTING.md`
-- Existing RFCs: `rfcs/THV-*.md`
+- Existing RFCs: `<project>/<PREFIX>-*.md`
diff --git a/.claude/skills/write-rfc/SKILL.md b/.claude/skills/write-rfc/SKILL.md
@@ -1,76 +1,40 @@
 ---
 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.
+description: Write RFCs for any project in this repository (toolhive, mecatl, ...). Use when the user wants to create a new RFC, proposal, or design document for a project covered here, including the toolhive, toolhive-studio, toolhive-registry, toolhive-registry-server, toolhive-cloud-ui, or dockyard repositories.
 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.
+This skill helps you write high-quality RFCs for the projects in this repository 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.
+RFCs live in one folder per project and are named `<project>/<PREFIX>-{NUMBER}-{descriptive-name}.md`. The NUMBER must match the PR number and be zero-padded to 4 digits. Project-specific knowledge (scope, repositories, architecture docs, conventions) lives in `<project>/AGENTS.md`, not in this skill.
 
 ## Workflow
 
-### Step 1: Gather Requirements
+### Step 1: Identify the Project and Gather Requirements
 
-Before writing an RFC, ask the user about:
+1. Read the root `AGENTS.md`.
+2. Determine the project (folder). If the user hasn't said, ask. Then read `<project>/AGENTS.md`; it defines the prefix, target repositories, architecture docs and conventions.
+
+Then 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
+2. **Target Repository**: Which repository does this affect? Offer the list from the project's `AGENTS.md`, plus `multiple` for 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
+### Step 2: Research
 
-Read `rfcs/` directory in this repository to understand patterns and check for related proposals.
+Before drafting:
 
-#### 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 |
+1. Read the architecture docs and code locations listed under "Research before writing or reviewing" in the project's `AGENTS.md` (use `mcp__github__get_file_contents` or `mcp__github__search_code`).
+2. Read the existing RFCs in `<project>/` to understand patterns and find related proposals.
 
 ### Step 3: Draft the RFC
 
-Create the RFC following the template structure from `rfcs/0000-template.md`.
+Create the RFC following the template structure from `template.md`.
 
 #### Required Metadata
 
@@ -117,31 +81,14 @@ Every RFC MUST address:
 
 ### Step 4: Use Proper Conventions
 
-#### Code Examples
+Follow the "Conventions" section of the project's `AGENTS.md` (code example languages, API and CRD conventions, terminology). Generally:
 
-- 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:
-
-```yaml
-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.
+Name the file `<project>/<PREFIX>-XXXX-{descriptive-name}.md`, where `<PREFIX>` comes from the project's `AGENTS.md` and XXXX is the PR number. Since you don't know the PR number yet, use the `XXXX` placeholder and remind the user to rename the file to match the PR number after creating the PR.
 
 ### Step 6: Review Checklist
 
@@ -155,46 +102,13 @@ Before finalizing, verify:
 - [ ] 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
+- [ ] File is in the project folder and follows the naming convention
+- [ ] Project-specific conventions from `<project>/AGENTS.md` are followed
 
 ## Reference Files
 
-- Template: `rfcs/0000-template.md`
+- Shared rules: `AGENTS.md`
+- Project rules: `<project>/AGENTS.md`
+- Template: `template.md`
 - Contributing guide: `CONTRIBUTING.md`
-- Existing RFCs: `rfcs/THV-*.md`
+- Existing RFCs: `<project>/<PREFIX>-*.md`