Distilled First Principles & Core Essence

The Fundamental Insight

agr is building a package manager for AI agent resources across multiple tools. The same architectural challenge that npm solved for JavaScript packages across environments, agr must solve for agent resources
(skills, rules, commands, subagents, instructions) across tools (Claude Code, Cursor, Copilot, Codex, OpenCode).

---
First Principles

1. Resources and Tools form a Matrix
- Resources are the what: skills, rules, commands, subagents, instructions
- Tools are the where: Claude, Cursor, Copilot, Codex, OpenCode
- The core must be agnostic to both dimensions—extensibility is O(1) for adding new resource types or tools

2. Stable Interfaces over Hardcoded Logic
- Tool differences belong in configuration (ToolSpec/Adapter), not control flow
- Resource differences belong in specs (ResourceSpec), not conditionals
- New tools or resources are added via registration, not refactoring

3. Skills are the Open Standard
- SKILL.md with YAML frontmatter is the canonical, cross-tool format
- Everything else (rules, commands, subagents) is tool-specific and requires adapters
- Skills need minimal transformation; other resources need transformers

4. Unified Core, Unified CLI
- agr (permanent install) and agrx (temporary run) share the same orchestration pipeline
- No duplicate logic—divergence between them is a bug

---
Core Architecture

┌─────────────────────────────────────────────┐
│                  CLI Layer                  │
│              (agr / agrx)                   │
└─────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│               Orchestrator                  │
│  - Parse handle                             │
│  - Fetch repo                               │
│  - Discover resource (via ResourceSpec)     │
│  - Validate                                 │
│  - Transform (via ToolAdapter)              │
│  - Install                                  │
└─────────────────────────────────────────────┘
        │                       │
        ▼                       ▼
┌─────────────────┐    ┌─────────────────────┐
│  ResourceSpec   │    │    ToolAdapter      │
│  - marker file  │    │  - config dir       │
│  - search paths │    │  - resource mapping │
│  - frontmatter  │    │  - transformations  │
└─────────────────┘    └─────────────────────┘

---
The Five Resource Types
┌─────────────┬───────────────────────────────────────┬─────────────────────┐
│    Type     │              Description              │      Standard?      │
├─────────────┼───────────────────────────────────────┼─────────────────────┤
│ skill       │ Reusable capability (SKILL.md)        │ Yes - open standard │
├─────────────┼───────────────────────────────────────┼─────────────────────┤
│ rule        │ Context/memory fragments              │ Tool-specific       │
├─────────────┼───────────────────────────────────────┼─────────────────────┤
│ command     │ Slash commands                        │ Tool-specific       │
├─────────────┼───────────────────────────────────────┼─────────────────────┤
│ subagent    │ Agent configurations                  │ Tool-specific       │
├─────────────┼───────────────────────────────────────┼─────────────────────┤
│ instruction │ Project memory (CLAUDE.md, AGENTS.md) │ Tool-specific       │
└─────────────┴───────────────────────────────────────┴─────────────────────┘
---
Key Design Decisions

1. Resource-first, not skill-first — The core models generic resources; skills are just one kind
2. Adapters encapsulate tool quirks — Claude puts skills in .claude/skills/, Cursor puts rules in .cursor/rules/, Copilot uses .github/skills/—adapters handle this
3. Manifest-first, convention fallback — Explicit manifest.toml when present; scan for SKILL.md markers when not
4. Plan-based installs — Compute a deterministic install plan before writing anything
5. Backward compatible evolution — agr.toml gains optional kind, tool, scope fields; old configs work unchanged

---
What Makes This World-Class
┌──────────────────┬──────────────────────────────────────────────────────────────────┐
│     Property     │                        How It's Achieved                         │
├──────────────────┼──────────────────────────────────────────────────────────────────┤
│ Extensibility    │ Add tools/resources via spec registration, not code changes      │
├──────────────────┼──────────────────────────────────────────────────────────────────┤
│ Interoperability │ Skills work across Claude, Copilot, Codex—one format, many tools │
├──────────────────┼──────────────────────────────────────────────────────────────────┤
│ Simplicity       │ Core logic is ~3 concepts: Resource, Tool, Orchestrator          │
├──────────────────┼──────────────────────────────────────────────────────────────────┤
│ Reliability      │ Shared pipeline means agr and agrx can't diverge                 │
├──────────────────┼──────────────────────────────────────────────────────────────────┤
│ User Trust       │ No breaking changes; old configs continue to work                │
└──────────────────┴──────────────────────────────────────────────────────────────────┘
---
Implementation Priorities

Phase 1: Core abstractions (ResourceSpec, ToolSpec, Orchestrator) + refactor existing skill logic to use them

Phase 2: Multi-tool foundation (tool detection, --tool flag, Cursor/Copilot specs)

Phase 3: Rules support (RuleSpec, SKILL.md → .mdc transformation)

Phase 4: Subagents + commands

Phase 5: Instruction files (CLAUDE.md, AGENTS.md)

---
The One-Liner Vision

"Install once, work everywhere" — a resource installable for any tool without changing its format or forking.