# Multi-Tool Resource Architecture for agr/agrx

Date: 2026-01-22

## Executive Summary

This proposal defines a world-class architecture for expanding agr/agrx beyond skills to support rules, subagents, commands, and instruction files across multiple tools (Claude Code, Cursor, GitHub Copilot, Codex, Open Code). The core design treats resources and tools as a matrix and uses a small set of stable abstractions to minimize change when adding new tools or resource types. It preserves backward compatibility and the current agr/agrx ergonomics while enabling a roadmap for future capability growth.

Key outcomes:

- A **Resource-Tool Matrix** abstraction with plug-in tool specs and resource specs.
- **Skills remain the open standard** and require minimal transformation across tools.
- **Tool-specific resources** (rules, commands, subagents, instructions) use adapters.
- agr and agrx stay unified with shared orchestration logic.
- The architecture supports multi-tool and multi-resource with O(1) extensibility.

## Context and Ground Truth from Documentation

This architecture is grounded in the official documentation for each tool (Claude Code, Cursor, GitHub Copilot, Codex, Open Code). The key facts that drive the design are:

- **Skills are an open standard** (SKILL.md with YAML frontmatter) used by Claude Code and GitHub Copilot, and importable by Cursor.
- **Claude Code**:
  - Skills live at `.claude/skills/<skill>/SKILL.md`
  - Subagents live at `.claude/agents/` and have frontmatter (description, tools, skills, hooks).
  - CLAUDE.md provides project memory/instructions.
  - Slash commands are handled via skills (skills are command-like).
- **Cursor**:
  - Rules live in `.cursor/rules/*.md` or `.mdc` with frontmatter (description, globs, alwaysApply).
  - Legacy `.cursorrules` still supported but deprecated.
  - Cursor can import Agent Skills as rules.
  - Commands and subagents have their own docs.
- **GitHub Copilot**:
  - Skills live in `.github/skills/` or `.claude/skills/`.
  - SKILL.md frontmatter requires name and description.
  - Custom instructions live in `.github/copilot-instructions.md`.

These facts imply that **skills are the canonical standard**, while other resource types remain tool-specific and must be adapted.

## Design Principles

1. **Single Responsibility**: Separate concerns for resource discovery, tool configuration, installation, and orchestration.
2. **Stable Interfaces**: Add new tools/resource types without modifying core logic.
3. **Backward Compatibility**: Preserve current CLI behavior and agr.toml format; expand without breaking existing users.
4. **Low Friction Extensibility**: New resources or tools can be introduced through registration, not refactoring.
5. **Unified agr/agrx**: Both commands use the same orchestration and resource handling core.

## Core Model

### 1) Resource Types

- `SKILL`: Standard open format, directory resource with `SKILL.md`.
- `RULE`: Tool-specific markdown or mdc rule files.
- `COMMAND`: Tool-specific, generally markdown or skill-based.
- `SUBAGENT`: Tool-specific agent configuration directories/files.
- `INSTRUCTION`: Single file instructions (CLAUDE.md, copilot-instructions.md, AGENTS.md, .cursorrules).

Resource types are categorized:

- **Standard**: Skills, no transformation required for Claude/Copilot.
- **Tool-Specific**: Rules, commands, subagents.
- **Project-Level**: Instruction files.

### 2) ResourceSpec (Resource-Level Metadata)

Defines:

- Marker file (e.g., `SKILL.md`, `AGENT.md`)
- Search paths in repositories
- Whether resource is directory or file-based
- Required and optional frontmatter fields

This allows discovery and validation to be resource-type driven rather than hardcoded.

### 3) ToolSpec (Tool-Level Metadata)

Defines:

- Config directory (`.claude`, `.cursor`, `.github`)
- Resource mapping (`ResourceType` -> subdir, file extensions)
- Detection markers (to auto-detect tool)
- Naming format for installed resources
- Optional transformation functions for tool-specific resource mapping

ToolSpecs encode where and how a tool stores each resource.

### 4) Orchestrator

The Orchestrator is the single coordination layer that:

1. Parses handles and resolves resource type.
2. Fetches repository or local path.
3. Discovers the resource via ResourceSpec.
4. Validates it.
5. Applies tool-specific transformations.
6. Installs into the correct tool directory.

Both `agr` and `agrx` use this same orchestrator for consistent behavior.

## Architecture Overview

```
CLI (agr / agrx)
   |
   v
Orchestrator
   |
   +--> Resource Discovery (ResourceSpec)
   |
   +--> Tool Mapping (ToolSpec)
   |
   +--> Installer (file/dir based)
   |
   +--> Config Persistence (agr.toml)
```

This structure ensures that tool differences and resource differences are isolated in configuration, not control flow.

## Concrete Tool Support

### Claude Code

- Skills: `.claude/skills/<skill>/SKILL.md`
- Subagents: `.claude/agents/<name>.md`
- Commands: Skills (slash commands)
- Instructions: `CLAUDE.md` project root (or nested)

### Cursor

- Rules: `.cursor/rules/*.md` or `.mdc`
- Skills: `.cursor/skills/` (standard SKILL.md)
- Commands: `.cursor/commands/`
- Instructions: `.cursorrules` (legacy) or `AGENTS.md`

### GitHub Copilot

- Skills: `.github/skills/` or `.claude/skills/`
- Instructions: `.github/copilot-instructions.md`
- Agents: `.github/agents/`

## Installation Strategy

Installation is split into two strategies:

- **Directory installer**: Copy resource directories (skills, subagents).
- **File installer**: Place single files (rules, instructions).

Each installer is generic; tools provide only:

- The destination directory
- The filename extension
- A transformer to adapt resource content

## File Structure Proposal

```
agr/
  core/
    resource.py        # ResourceType, ResourceSpec, Resource
    tool.py            # ToolSpec, ToolResourceConfig
    registry.py        # Resource and Tool registries
    discovery.py       # Resource discovery logic
    installer.py       # Install/uninstall logic
    orchestrator.py    # Central coordination
  tools/
    specs.py           # Claude, Cursor, Copilot specs
    transforms.py      # Tool-specific transformations
  resources/
    skill.py           # Skill validation helpers
    rule.py            # Rule parsing helpers
    subagent.py        # Subagent parsing helpers
  commands/
    add.py, sync.py, remove.py, list.py, init.py
agrx/
  main.py              # Uses Orchestrator, no duplicate logic
```

## agr.toml Evolution (Backwards Compatible)

Current:

```
dependencies = [
  { handle = "user/skill", type = "skill" },
]
```

Extended:

```
[settings]
tool = "claude"  # default (auto-detected if omitted)

dependencies = [
  { handle = "user/skill", type = "skill" },
  { handle = "user/rules/eslint", type = "rule", tool = "cursor" },
]
```

This is fully backward compatible and supports per-dependency tool overrides.

## Handle Parsing Strategy

Handles remain the same but support an optional type prefix:

- `user/skill` → skill
- `rule:user/rules/eslint` → explicit rule
- `agent:user/agents/reviewer` → subagent

If no prefix is provided, the resource type is inferred from the command context or defaults to skill.

## Roadmap / Migration Plan

### Phase 1: Core Refactor

- Add core abstractions (ResourceSpec, ToolSpec, Orchestrator).
- Keep existing functionality for skills unchanged.
- agr and agrx use shared orchestration.
- Tests updated for new core modules.

### Phase 2: Multi-Tool Foundation

- Add tool detection and `--tool` CLI flag.
- Implement Cursor and Copilot ToolSpecs.
- Extend agr.toml settings and dependency schema.

### Phase 3: Rules Support

- Add RuleSpec and file installer.
- Implement SKILL.md -> .mdc transformation for Cursor rules.
- Add `--type rule` in CLI commands.

### Phase 4: Subagents + Commands

- Add SubagentSpec and support `.claude/agents`.
- Add Cursor commands support.
- Add validation for subagent frontmatter.

### Phase 5: Instructions

- Support CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md.
- Provide command to install instruction resources.

## Testing Strategy (Required)

All phases include tests:

- **Unit tests** for ResourceSpec discovery and validation.
- **Unit tests** for ToolSpec mapping.
- **Integration tests** for install/uninstall across tools.
- **CLI tests** for new flags and resource types.

Tests should cover multi-tool installations in a temp repo with a simulated `.git` root.

## Risks and Mitigations

- **Risk: Tool docs evolve quickly**
  - Mitigation: centralize ToolSpecs so updates are localized.
- **Risk: Conflicts between resource formats**
  - Mitigation: transformations are tool-specific and isolated.
- **Risk: Users mixing tools**
  - Mitigation: tool detection plus explicit `--tool`.
- **Risk: Behavior divergence between agr and agrx**
  - Mitigation: shared Orchestrator and core modules.

## Architectural Decisions (Summary)

1. Skills are treated as a standard format and are not transformed between Claude and Copilot.
2. Tool differences are modeled in ToolSpec, not control flow.
3. Resource discovery is spec-driven and resource-agnostic.
4. All install/remove/sync flows go through the Orchestrator.
5. agr and agrx are unified at the core level.

## Next Steps

1. Implement the core abstractions and registries.
2. Refactor current skill logic to use ResourceSpec and Orchestrator.
3. Add Cursor and Copilot ToolSpecs with minimal transformations.
4. Expand CLI commands to accept resource type and tool selection.
5. Add tests per the testing strategy.
