## Unified Resource Architecture for agr / agrx

This proposal revises the architecture based on the documented primitives across
Claude Code, OpenCode, Codex, Copilot, and the Agent Skills standard. The goal is
to keep agr/agrx clean and future-proof while adding first-class support for
skills, rules/memory, subagents, commands, and instruction files.

### Executive Summary

We should move from a Claude-specific, skills-only installer to a tool-agnostic
resource model with tool adapters. The core should reason about resources and
install plans, while adapters map those resources into each tool’s file layout
and features. This keeps the core stable, makes it trivial to add new tools, and
prevents feature creep from becoming cross-cutting changes.

### What We Learned From the Docs

#### Claude Code
- Skills live in `.claude/skills/<name>/SKILL.md` (project) and `~/.claude/skills/<name>/SKILL.md` (user).
- Skill frontmatter supports: `name`, `description`, `argument-hint`,
  `disable-model-invocation`, `user-invocable`, `allowed-tools`, `model`,
  `context`, `agent`, `hooks`.
- Subagents live in `.claude/agents/` and `~/.claude/agents/`.
  Frontmatter includes `name`, `description`, `tools`, `disallowedTools`,
  `permissionMode`, `skills`, `hooks`.
- Memory is based on `CLAUDE.md` plus modular rules under `.claude/rules/`.

#### Agent Skills Standard (agentskills.io)
- `SKILL.md` has required frontmatter: `name`, `description`.
- Optional: `license`, `compatibility`, `metadata`, `allowed-tools`.
- Optional directories: `scripts/`, `references/`, `assets/`.
- Progressive disclosure: metadata is loaded early; content is loaded on use.

#### OpenCode
- Skills live in `.opencode/skills/<name>/SKILL.md` and `~/.config/opencode/skills/<name>/SKILL.md`.
- Recognized frontmatter is limited to `name`, `description`, `license`,
  `compatibility`, `metadata`.
- Commands are markdown files in `.opencode/commands/` and
  `~/.config/opencode/commands/`.
- Agents (subagents) are markdown files in `.opencode/agents/` and
  `~/.config/opencode/agents/`, or in `opencode.json`.

#### Codex
- Skills follow the Agent Skills standard and use `SKILL.md` directories with
  optional `scripts/`, `references/`, `assets/`.
- Codex supports explicit and implicit skill invocation.
- Custom prompts exist in `~/.codex/prompts/` but are deprecated in favor of skills.
- Instructions are encouraged via `AGENTS.md`.

#### GitHub Copilot
- Skills are in `.github/skills/` or `.claude/skills/` (project) and
  `~/.copilot/skills/` or `~/.claude/skills/` (user).
- `SKILL.md` uses YAML frontmatter with `name`, `description`, and optional `license`.

### Architectural Principles

1. **Resource-first core:** The core should not care about tool layouts.
2. **Adapters for tools:** Each tool maps resources into its file layout and
   optional config.
3. **Manifest-first discovery:** Allow explicit repo manifests; fall back to
   conventions when no manifest exists.
4. **Standards-aligned:** `SKILL.md` should remain compatible with the Agent
   Skills standard and the superset features of tools like Claude.
5. **Plan-based installs:** Compute a deterministic install plan before writing.

### Proposed Core Model

#### Resource Types
- `skill` (SKILL.md directory)
- `rule` (memory rules or instruction fragments)
- `instruction` (top-level instruction files like `CLAUDE.md` or `AGENTS.md`)
- `command` (slash-command definitions)
- `subagent` (agent config files)

#### ResourceSpec
- `type`: one of the above
- `name`: normalized identifier
- `source`: handle or local path
- `path`: relative location inside the source repo
- `tool_targets`: list of tools (default: the configured default tool)
- `metadata`: parsed frontmatter or extra config data

### Tool Adapter Layer

Each tool adapter provides:
- `install(resource_spec, repo_root)` -> filesystem actions
- `validate(resource_spec)` -> tool-specific rules
- `run(resource_spec, prompt, mode)` -> optional for agrx

#### Tool Mapping Examples

**Claude**
- `skill` -> `.claude/skills/<name>/SKILL.md`
- `subagent` -> `.claude/agents/<name>.md`
- `rule` -> `.claude/rules/*.md`
- `instruction` -> `CLAUDE.md`
- `command` -> modeled as skills (Claude treats skills as slash commands)

**OpenCode**
- `skill` -> `.opencode/skills/<name>/SKILL.md`
- `command` -> `.opencode/commands/<name>.md`
- `subagent` -> `.opencode/agents/<name>.md`
- `instruction` -> `AGENTS.md` (optional support)
- `rule` -> tool rules config (future adapter expansion)

**Codex**
- `skill` -> Codex skill locations (Agent Skills standard)
- `command` -> `~/.codex/prompts/<name>.md` (deprecated, optional)
- `instruction` -> `AGENTS.md`

**Copilot**
- `skill` -> `.github/skills/<name>/SKILL.md` or `.claude/skills/<name>/SKILL.md`

### Discovery: Manifest First, Convention Fallback

#### Optional Manifest
`resources/manifest.toml` (or `agent-resources.toml`) can explicitly define
resources:

```
[[resources]]
type = "skill"
name = "commit"
path = "resources/skills/commit"
tools = ["claude", "opencode"]

[[resources]]
type = "rule"
name = "security"
path = "resources/rules/security.md"
tools = ["claude"]
```

#### Convention Fallback
If no manifest exists:
- `resources/skills/<name>/SKILL.md` -> `skill`
- `.claude/skills/<name>/SKILL.md` -> `skill` (Claude-compatible)
- `.opencode/skills/<name>/SKILL.md` -> `skill`
- `.github/skills/<name>/SKILL.md` -> `skill` (Copilot)
- `.claude/rules/*.md` -> `rule`
- `CLAUDE.md` -> `instruction`
- `AGENTS.md` -> `instruction`
- `.opencode/commands/*.md` -> `command`
- `.opencode/agents/*.md` -> `subagent`
- `.claude/agents/*.md` -> `subagent`

### agr.toml Evolution

Backwards compatible extensions:

```
dependencies = [
  { handle = "user/skills/frontend", type = "skill" },
  { handle = "user/agents", type = "subagent", tools = ["claude"] },
  { handle = "user/rules", type = "rule", tools = ["claude"] },
  { handle = "user/opencode-kit", types = ["command", "subagent"], tools = ["opencode"] },
]
```

Defaults:
- `type = "skill"` if omitted.
- `tools = ["claude"]` if omitted.

### agrx Evolution

`agrx` should call `ToolAdapter.run(...)`:
- `skill` -> `/skill-name` for tools that support slash command invocation.
- `command` -> `/command-name` where applicable (OpenCode, Codex prompts).
- `subagent` -> trigger subagent by name where supported.
- `instruction` and `rule` -> install only, then open a session.

### Installation Plan Flow

1. Resolve handles or local paths.
2. Discover resources (manifest or convention).
3. Normalize to `ResourceSpec`s.
4. Build an install plan per tool adapter.
5. Apply the plan atomically (copy, rename, validate).

### Why This Architecture Scales

- **Tools are adapters**: adding Cursor or another agent becomes a new adapter
  without altering core logic.
- **Resources are stable**: new resource types map cleanly into the same pipeline.
- **Standards-based**: SKILL.md remains compatible with Agent Skills, Copilot,
  Codex, and OpenCode.
- **Explicit configuration**: manifest support prevents ambiguity in large repos.

### Implementation Phasing (Suggested)

1. Introduce `ResourceSpec` and adapter scaffolding while keeping current behavior.
2. Add discovery for rules, instructions, subagents, and commands.
3. Add tool adapters for OpenCode + Codex (Copilot mapping is trivial for skills).
4. Add multi-tool targeting in `agr.toml`.
5. Add `agrx` routing based on resource type.

### Tests (Required)

- Resource discovery unit tests (manifest + convention).
- Adapter mapping tests (Claude + OpenCode + Codex + Copilot).
- Installation plan integration tests for `agr add` and `agr sync`.
- `agrx` routing tests per resource type.

---

This proposal aligns agr with the real-world primitives used by current tools,
keeps the core minimal and stable, and preserves compatibility with the open
Agent Skills standard while allowing tool-specific features like Claude hooks
and subagent permissions.
