Skip to content

protocol.md

Latest commit

 

History

History
118 lines (98 loc) · 4.26 KB

protocol.md

File metadata and controls

118 lines (98 loc) · 4.26 KB

🔬 ARCA Protocol Deep-Dive

ARCA (Asset Resolution for AI Assistants) is a decentralized standard for distributing, versioning, and consuming agentic assets (rules, skills, instructions).

🎭 1. Actors

Actor Responsibility
🧑‍💻 Maintainer Publishes assets to a Source Repository (hosting the arca-manifest.yaml).
👤 Consumer Developers and tools using assets via .arca-assets.yaml.
📦 Source Repository A Git-based or local host containing asset files and the manifest.
☁️ Provider Hosting services (GitHub, Azure DevOps, Local FS).
⚙️ ARCA CLI The Go binary used to resolve, fetch, and verify assets.
🤖 AI Assistant The consumer (GitHub Copilot, Claude Code, ChatGPT, Antigravity, Cursor, Manus, etc.) that utilizes the projected assets.

📐 2. Technical Specification

ARCA operates using three primary data structures: the Manifest, the Configuration, and the Lockfile.

2.1 📋 The Manifest (arca-manifest.yaml)

Generated by arca init or arca publish

Located at the root of an asset source, this file defines what assets are available and their version history.

schema: 1.0
assets:
  <asset-id>:
    kind: skill | instruction
    description: "Brief description taken from the asset Frontmatter"
    versions:
      <version-string>:
        path: "path/to/file.md"
        ref: "v1.0.0" # Optional. Git tag/commit.

2.2 ⚙️ The Configuration (.arca-assets.yaml)

Generated by arca install

Located in the consumer's project, this file declares which assets the project depends on and where they should be projected.

schema: 1.0
sources:
  my-org:
    type: git | local
    url: "https://github.com/my-org/agent-assets"
    path: "~/local-assets" # if type: local
assets:
  - id: refactor-logic
    kind: instruction | skill
    source: my-org
    version: "^1.2.0"
    projections:
      default: ".github/instructions/refactor.md"
      cursor: ".cursor/instructions/refactor.md"

2.3 🔒 The Lockfile (.arca-assets.lock)

Generated by ARCA, this ensures that everyone on the project uses the exact same content.

{
  "assets": [
    {
      "id": "refactor-logic",
      "version": "1.2.5",
      "source": "my-org",
      "commit": "abc12345",
      "sha256": "df7a8b9c...",
      "manifestHash": "...",
      "resolvedAt": "2026-02-17T..."
    }
  ]
}

🔄 3. Resolution Flow

flowchart TD
    A["📄 .arca-assets.yaml"] -->|"arca sync / install"| B["🔍 Discovery
      Fetch arca-manifest.yaml from source"]
    B --> C["🔢 Version Matching
      Resolve SemVer constraints"]
    C --> D["📥 Download
      Fetch asset at resolved Git ref/SHA"]
    D --> E["🧹 LF-Normalization
      Normalize line endings to LF"]
    E --> F["🔐 Validation
      Compute SHA-256 & compare to lockfile"]
    F -->|"✅ Valid"| G["💾 Caching
      Store in ~/.arca-cache"]
    F -->|"❌ Mismatch"| ERR["🚨 Error
      Integrity check failed"]
    G --> H["🗂️ Projection
      Symlink/copy to tool-specific paths"]
    H --> I["📝 Write .arca-assets.lock"]
    H --> J["📂 .github/instructions/"]
    H --> K["📂 .cursor/rules/"]
    H --> L["📂 Other AI tool paths..."]
Loading
  1. 🔍 Discovery: Read .arca-assets.yaml and fetch the latest arca-manifest.yaml from its source.
  2. 🔢 Version Matching: Resolve SemVer constraints to a specific version.
  3. 📥 Download: Fetch the asset content from the source repository at the resolved Git ref/SHA.
  4. 🧹 LF-Normalization: Normalize all text-based assets to LF (\n) for platform-independent hashing.
  5. 🔐 Validation: Compute SHA-256 and compare against the lockfile (if present).
  6. 💾 Caching: Store validated content in the global ~/.arca-cache.
  7. 🗂️ Projection: Create symlinks (or copies) from the cache to the project's tool-specific paths — allowing one asset to be used by multiple AI assistants simultaneously.

🖥️ 4. CLI Interface

The ARCA CLI provides machine-readable output (--json) to allow IDE extensions and other tools to integrate seamlessly.

Previous: Getting Started | Documentation Index | Next: Contribution Guide