Agency

Agency is a local-first package manager and security layer for AI capabilities across agent harnesses.

Agency helps users create, manage, use, and safely share agents.

Product direction

Agency maintains a local cache of agents, plugins, skills, tools, and MCP servers sourced from Eve, agent-plugins, and other locations. Its local workflow is centered on discovering, inspecting, composing, installing, updating, and removing skillsets and other agent customizations. It imports them, normalizes their metadata, records provenance and capabilities, and installs or updates harness-specific versions for environments such as Pi, Claude Code, Cursor, and other agent harnesses.

Agency is primarily an agent customization package manager and trust layer, not another general-purpose chat UI. Agents define designed persons—identity, soul, emotions, values, and general system behavior. Plugins are collections of customizations applied to agents; they add capabilities and workflows without redefining that personhood.

Agency is a local service with multiple clients: CLI/API for automation, a TUI for terminal-native human workflows, an MCP server for harness integration, and an optional desktop/web client later.

Current local commands

agency sync pull REMOTE [DIRECTORY]
agency sync push PLUGIN REMOTE
agency publish plugin PLUGIN REGISTRY
agency catalog REGISTRY [VISIBILITY]
agency team grant PACKAGE REGISTRY MEMBER...
agency install-published PACKAGE REGISTRY DESTINATION
agency registry serve REGISTRY [PORT]

The registry and team controls are local filesystem/HTTP primitives. Production authentication, hosted storage, payments, and billing are not included.

Core lifecycle

1. Create/import an agent or plugin.
2. Discover and compose plugins, skills, tools, and MCP integrations.
3. Inspect provenance, capabilities, attestations, and policy impact.
4. Install/use the agent or plugin through a supported harness.
5. Manage versions, dependencies, permissions, drift, and updates.
6. Sync or publish the bundle when useful.

Bundles

A bundle is a packaging and distribution container. It is not itself an agent or a plugin. Agency is the application; a bundle may contain an agent, a plugin, or both.

Agency (application) → bundle → agent and/or plugin
                                  ├── skills
                                  ├── tools
                                  ├── MCP integrations
                                  └── assets and references

An agent is a designed person. It owns identity-level behavior such as its soul, emotions, values, voice, and general system prompt. A plugin is a collection of customizations applied to an agent; it adds skills, tools, references, workflows, or integrations without redefining the agent's personhood or general system behavior. One plugin can be applied to multiple agents, and one agent can use multiple plugins.

A bundle groups related content under a stable identity:

customer-support/
├── agents/
├── skills/
├── plugins/
├── assets/
├── agency.yaml
└── agency.lock

The bundle is the same conceptual object at every stage of its lifecycle:

local → private remote → team workspace → public → optional paid distribution

Visibility and ownership are separate concerns:

• local — only on the user's machine
• private — remotely synchronized and accessible to its owner
• team — shared with invited collaborators or an organization
• public — discoverable and distributable
• distribution — free or paid, independently of visibility where appropriate

A stable identity might look like acme/customer-support or don/customer-support.

Import and discovery

Eve and agent-plugins do not fully specify how agents and plugins should be imported. Agency therefore needs a cautious discovery layer that supports common source forms:

/path/to/agent
/path/to/agent.md
https://example.com/agent
https://github.com/org/repo/tree/main/agent
git@github.com:org/repo.git
agency://eve/agent-name

Import flow:

source → discovery → normalized manifest → target renderer → install

For a directory or repository, Agency should:

1. Resolve the requested source and path.
2. Prefer an explicit Agency manifest if present.
3. Check Eve and agent-plugins metadata/manifests.
4. Probe known filenames and directory conventions.
5. Classify discovered agents, plugins, skills, assets, docs, and unknown files.
6. Ask for confirmation when detection is ambiguous.
7. Generate a normalized Agency manifest.
8. Cache the source, revision, manifest, and checksums.

For a file source, treat the file as the entry point and inspect its containing directory when available.

Detection should be ranked and conservative:

1. Agency manifest
2. Eve or agent-plugins manifest
3. Known filenames such as AGENTS.md, SKILL.md, plugin.md, or manifest.json
4. Directory naming conventions
5. Content heuristics

Agency should not silently include every nearby file. Unknown files should be shown for review. Import must not execute source content, and should guard against secrets, symlink escapes, archive path traversal, and unsafe generated paths.

Example discovery result:

Found:
  agent: ./AGENTS.md
  plugin: ./plugins/github/plugin.md
  supporting file: ./references/search.md

Not classified:
  ./README.md
  ./logo.png

Warnings:
  No version found
  No explicit manifest
  Plugin target is ambiguous

Normalized manifest

External metadata may be imported, but Agency needs an Agency-owned normalized manifest describing the complete installable unit.

schema: agency/v1
name: research-agent
version: 0.1.0
kind: agent
source:
  type: git
  url: https://github.com/example/research-agent
  revision: abc123

entrypoints:
  - path: AGENTS.md
    type: instructions

plugins:
  - name: github
    path: plugins/github
    required: true

files:
  - path: AGENTS.md
  - path: plugins/github/plugin.md
  - path: references/search.md

targets:
  pi:
    install: skills/research-agent
  claude-code:
    install: agents/research-agent.md

checksums:
  AGENTS.md: sha256:...

Important manifest data includes:

• stable identity and ownership
• source provenance and exact revision
• discovered files and entrypoints
• dependencies
• target-specific renderings/install paths
• checksums
• capabilities and required permissions
• warnings and confidence for inferred metadata
• security attestations and their covered revisions

Use two files when appropriate:

• agency.yaml — editable package declaration and intended contents
• agency.lock — resolved source revisions, dependency versions, and checksums

Harness adapters

Keep source definitions separate from rendered harness output. One agent may install differently into Pi, Claude Code, Cursor, or another harness.

source bundle → harness adapter → installed files/configuration

Adapters should be responsible for rendering and installation; the bundle manifest should remain harness-neutral wherever possible. Each harness needs a thin adapter for its own mechanics: skill and plugin discovery paths, installation format, MCP configuration, subagent invocation, approval handling, and result/event translation. The adapter must not redefine Agency's agent/person, plugin/skillset, task, policy, provenance, or version models.

Agency should support multiple targeting strategies, choosing the least invasive strategy that works for each harness:

link       native files can be referenced directly
render     source must be transformed into harness-specific files
copy       symlinks are unsupported or unsafe
register   harness exposes an installation/registration API

The default should be linking into the harness's normal discovery directories. This keeps the direct-install path simple and lets harnesses consume ordinary files. Rendering, copying, or registration are fallbacks for harnesses with incompatible formats, restricted filesystems, internal stores, or explicit APIs.

Installation and removal must only modify Agency-owned files or links. Before replacing or deleting a target, verify its Agency ownership marker and never remove an unrelated user file. Updates should be atomic so a harness cannot observe partially written content.

Harness notification should be optional. Prefer filesystem discovery or the next harness launch; add reload signals or restart prompts only for targets that need them.

Runtime mediation

Agency supports two complementary execution paths. Local Agency's primary job is managing plugins and skillsets; execution is a secondary, optional path:

Direct install:     Agency cache → link/render/copy → harness
Managed execution:  harness → Agency runtime layer → selected agent/plugin

Direct installation is the compatibility path. Managed execution is the control path for users who want dynamic loading, runtime policy, and stronger security enforcement. Agency can provide this through a local MCP server that the target harness connects to. Local subagents remain harness-native—for example, Pi can use pi-subagents to launch a child Pi session—while remote or paid agents can use MCP or another provider protocol.

The managed runtime should be able to:

• resolve an agent and its plugins by stable identity and version
• dynamically load the selected cached revisions
• verify checksums and scanner attestations before execution
• enforce declared capabilities and user/team policy
• mediate tool, network, filesystem, and MCP-server access where technically possible
• capture structured execution events and outcomes
• apply time, resource, depth, and recursion limits
• stop, quarantine, or block content after revocation or policy changes
• return results through a stable CLI, API, or MCP interface

MCP bridge

Agency supports two ways to make a bundle available to a target harness:

Installed mode:
Agency → link/render/copy/register → harness-native agent, skill, tool, or MCP server

Hosted mode:
target harness → Agency MCP server → dynamically resolved agent, skill, tool, or MCP server

Installed mode is best when the content is already compatible with the harness and should be visible as a normal local file. Hosted mode is best when Agency needs to resolve content dynamically, enforce policy, verify attestations, load a selected revision, or mediate access at execution time.

The Agency MCP server should expose a small stable surface rather than mirror every internal object. Likely primitives include:

• discover available agents and plugins
• inspect an agent, plugin, skill, tool, or MCP server
• install, update, or remove an approved plugin
• read an approved managed resource or skill
• invoke an approved managed tool or managed agent
• report execution status and results

MCP terminology should remain clear: tools are callable operations, resources provide readable context, and prompts/skills provide reusable instructions. A subagent is normally exposed as a managed tool or task operation rather than pretending it is a native MCP primitive. MCP is a portable transport and capability interface, not a complete universal agent-to-agent protocol. Agency should define a harness-neutral task/provider contract above it so the same remote agent can support MCP, HTTP, A2A-style protocols, or future transports.

Each request should resolve a pinned revision, verify its attestation and policy, apply the caller's permission context, and record the execution. Agency must not silently expand the target harness's permissions.

Runtime mediation is not automatically a security boundary. Agency must report which controls are enforced by the underlying harness or operating system and which are advisory.

The runtime interface should remain stable across harnesses:

resolve → verify → authorize → load → execute → observe → unload

Initial commands / UX

Possible CLI equivalents:

agency init customer-support
agency create agent native-sdk-expert
agency add plugin native-sdk
agency add skill refund-policy
agency run acme/triage --input "Handle this task" --json

agency login
agency sync
agency share --team support
agency publish
agency publish --price 10
agency search research
agency install eve/research-agent
agency update
agency list
agency remove eve/research-agent
agency tui

The app could organize these capabilities into:

• My Bundles — local and synchronized bundles
• Workspace — team-owned bundles
• Catalog — public, free, and paid bundles

TUI / GUI surfaces

The first human interface should be a terminal UI (TUI), with a later desktop/web GUI using the same service APIs. A TUI fits terminal-based harness workflows, SSH sessions, and local-first operation, but it is a client rather than the integration layer.

The human interface has two primary parts:

Library and management

The management surface organizes and controls what is available:

• browse local, private, team, and public bundles
• create and import agents, skills, tools, plugins, and MCP servers
• inspect files, capabilities, permissions, provenance, versions, and attestations
• run scans and review findings
• compare revisions and approve or reject updates
• install, link, render, update, rollback, and remove targets
• configure scanner and execution policies

Runtime monitor

The monitoring surface shows what is currently running through Agency or exposed through its MCP bridge:

• active agents, subagents, tools, and MCP calls
• parent/child execution relationships
• selected bundle and exact revision
• requested and granted capabilities
• scanner and policy decisions
• input/output summaries and generated artifacts
• timing, resource usage, and errors
• cancellation, pause, or quarantine controls where supported

The monitor should distinguish Agency-managed executions from direct harness executions. Agency can only display or control direct harness activity when that harness exposes the necessary events or APIs.

The TUI should connect to the same local Agency daemon used by the CLI, MCP server, and future GUI:

Agency daemon/core
├── CLI and JSON API
├── MCP server
├── TUI client
└── optional desktop/web client

MCP, CLI, structured events, and APIs—not the TUI—are the actual harness integration surfaces. This avoids trying to embed a separate terminal UI inside another harness while still making Agency feel native to terminal workflows.

Security scanning and policy

Security scanning is a pluggable part of import, update, publish, and managed execution workflows. Agency should facilitate trust decisions without becoming the single authority that declares a package safe.

Agency should ship with a free built-in scanner that runs locally and provides a useful baseline without requiring an account or network access. Paid cloud scanners can be installed as providers for deeper analysis, proprietary detection rules, threat intelligence, sandboxing, or organization-level policy enforcement. Remote services may issue signed, revision-specific security attestations—a seal of approval from that scanning organization—but no attestation is a permanent guarantee of safety.

All scanners should implement the same provider contract and return normalized findings:

scanner → findings → policy decision → user-facing report

A finding should include at least:

• severity and confidence
• affected file, package, or dependency
• rule/category and explanation
• remediation guidance
• scanner name and version
• whether the finding blocks import, install, update, publish, or execution

The built-in scanner should check obvious risks such as secrets, unsafe paths, suspicious executable content, prompt-injection markers, undeclared network/tool capabilities, and dependency issues where metadata is available. The runtime layer may also perform pre-execution and runtime checks where the harness permits. These controls are a baseline, not a security guarantee.

Cloud scanners must require explicit opt-in before uploading package contents. Agency should show what data will be sent, support local-only scanning, and preserve scanner provenance in the manifest or scan report. Results should be cacheable by source revision and scanner version. A scanner may additionally publish an attestation describing its conclusion for that exact immutable revision.

Pre-scanned catalog

Agency can build a growing database of independently assessed agents, skills, tools, plugins, and MCP servers through two complementary paths:

1. Opt-in result sharing from local installations — a local Agency installation posts scan metadata and results for a source revision.
2. Hosted scanning and listing — a service accepts public or explicitly submitted packages, scans them, and lists the resulting security record in a catalog.

The catalog entry should include:

• package identity, source, version, and immutable revision
• content checksums and scan timestamp
• scanner name, version, and rule-set version
• normalized findings and severity summary
• scan coverage and limitations
• supported harnesses and package type
• whether results came from local submission or hosted scanning
• signature or other proof that the result belongs to the scanned content

Consumers should be able to inspect scan history and filter or block packages based on policy. A scan result or attestation is evidence about a specific revision, not a permanent safety guarantee; results should expire, be superseded, or be revoked when content, scanner rules, or threat intelligence change.

Sharing must be explicit and privacy-preserving. Local submissions should avoid uploading private package contents, credentials, prompts, or personally identifying data by default. For private packages, share only aggregate or redacted findings unless the owner explicitly permits content submission.

Independent security attestations

Agency should not be the single authority that declares an agent safe. Remote security-scanning services can issue independent, revision-specific attestations—effectively seals of approval from the scanning organization—while Agency acts as the client and aggregator.

A package may therefore have multiple attestations:

acme/research-agent @ sha256:...
  Scanner A: approved, 2025-01-10
  Scanner B: conditional, medium finding
  Scanner C: not evaluated

Agency should track scanner identity, methodology, coverage, reputation, freshness, and historical outcomes rather than collapse everything into one permanent trust score. Users and organizations can choose their own trust policy:

require: 2 approved scanners
prefer: scanners with organization trust
block: any critical finding
allow: conditional findings with review

Scanner reputation can evolve through transparent signals such as accuracy, coverage, false-positive rate, response time, independence, and community or organizational adoption. Reputation must not override the underlying attestations, and package approval must remain bound to an immutable content revision.

Attestations should support expiration, supersession, and revocation. A changed package, changed scanner rules, newly discovered vulnerability, or shifting organizational policy should cause Agency to re-evaluate the package without pretending that an earlier seal was permanent.

The practical trust model is therefore:

scanner attestations + provenance + capabilities + user policy → install decision

Agency facilitates comparison and policy enforcement; it does not become the final party being trusted.

Phased roadmap

The roadmap keeps the first product useful without requiring a hosted service or universal harness integration, while preserving a path to Agency-managed runtime execution.

Phase 0 — Define the contract

Goal: establish the smallest stable model that all later features can build on.

Deliverables:

• Define Agency terminology: application, bundle, agent/person, plugin, skill, tool, and MCP server.
• Define agency.yaml for editable bundle metadata.
• Define agency.lock for resolved revisions, dependencies, and checksums.
• Define the normalized capability and permission vocabulary.
• Define the scanner provider interface and normalized finding format.
• Select the first supported harness and document its discovery paths.
• Use a local daemon/core with CLI/API, MCP server, and TUI clients; defer a desktop/web client until needed.

Exit criteria:

• A sample bundle can describe its contents, source, capabilities, target, and policy requirements.
• The model distinguishes instructions from executable or network-capable content.
• No hosted account is required for the local workflow.

Phase 1 — Local bundle manager (MVP)

Goal: make Agency immediately useful for local skillset and plugin management.

Deliverables:

• agency init, add, import, list, inspect, and remove.
• Import from local paths, files, Git repositories, URLs, Eve, and agent-plugins.
• Cautious discovery with explicit confirmation for ambiguous imports.
• Content-addressed or revision-keyed local cache.
• Normalized manifest generation.
• Local free scanner running during import and before installation.
• Capability, permission, provenance, and scan inspection.
• Install into the first harness using links by default.
• Safe Agency-owned link tracking and atomic target updates.
• status, diff, update, and rollback.
• An optional Agency-managed execution path for one agent type or harness; execution is secondary to local plugin and skillset management.

Exit criteria:

• A user can import a real agent/plugin bundle, inspect what it will install, approve it, and use it in the target harness.
• Reinstalling from the lockfile produces the same content.
• Updating a bundle shows an understandable diff before changing installed files.
• Removing a bundle does not damage unrelated user files.

Phase 2 — Runtime mediation, portability, and policy

Goal: provide a controlled execution path while making bundles reproducible across machines and harnesses.

Deliverables:

• Stable Agency runtime CLI/API and structured JSON protocol.
• Local Agency MCP server for managed execution.
• Dynamic loading of cached agent, skill, tool, plugin, and MCP-server revisions.
• Pre-execution verification of checksums, capabilities, policy, and available attestations.
• Runtime authorization for tools, network access, filesystem access, code execution, and MCP servers where enforceable.
• Execution events, outcomes, resource limits, cancellation, and recursion limits.
• Additional targeting strategies: link, render, copy, and register.
• Harness adapter contract and a second supported harness.
• Capability-based install and execution policy.
• Drift detection for manually changed or deleted Agency-managed targets.
• Checksums, signatures where available, and immutable revision tracking.
• Clear local-only mode and offline operation.
• Export/import of bundles and lockfiles.

Exit criteria:

• A parent harness can invoke a managed Agency agent through the stable CLI/API.
• Agency can block or require confirmation before execution based on capabilities and policy.
• The same lockfile can recreate a bundle on another machine.
• Agency clearly reports which runtime controls are enforced versus advisory.
• Harness-specific behavior is isolated in adapters rather than bundle definitions.

Phase 3 — Private sync and team bundles

Goal: support organic growth from personal use to shared work.

Deliverables:

• Login and private remote synchronization, initially Git-backed where practical.
• Sync/pull/push with conflict and lockfile handling.
• Stable bundle ownership and namespace.
• Team membership and repository-permission integration.
• Reviewable bundle changes and version history.
• Organization policies for required scanners, blocked capabilities, and approved sources.
• Opt-in sharing of redacted local scan results.

Exit criteria:

• A user can move a local bundle to a private remote without recreating it.
• A team can review, install, update, and roll back the same bundle.
• Private package contents are not uploaded to scanners or shared by default.

Phase 4 — Independent attestations and catalog

Goal: make security evidence discoverable without making Agency the authority.

Deliverables:

• Hosted scanning service for explicitly submitted public packages.
• Scanner-provider integrations for paid cloud scanners.
• Signed, revision-specific attestations with expiration, supersession, and revocation.
• Catalog entries for agents, skills, tools, plugins, and MCP servers.
• Scan history, coverage, methodology, and scanner provenance.
• User-configurable policies such as scanner quorum and severity thresholds.
• Opt-in local result submissions with privacy-preserving metadata.
• Reputation signals for scanner quality, kept separate from package approval.

Exit criteria:

• Users can compare independent scanner results for an exact package revision.
• Agency can enforce a local policy without requiring a universal trust score.
• A changed or revoked package causes existing installations to be re-evaluated.

Phase 5 — Public and paid distribution

Goal: enable sustainable sharing while preserving provenance and user control.

Deliverables:

• Public bundle publishing and discoverability.
• Maintainer identity and ownership transfer.
• License and compatibility metadata.
• Free and paid distribution options.
• Download/install analytics that respect privacy.
• Abuse reporting, takedown, package quarantine, and vulnerability disclosure workflows.
• Billing and entitlement checks where paid packages require them.

Exit criteria:

• A maintainer can publish a bundle with its manifest, source, revisions, capabilities, and attestations.
• A consumer can inspect the evidence and policy impact before installation.
• Paid distribution does not bypass provenance, scanning, or local policy checks.

Deliberate non-goals

Do not initially build:

• a general-purpose agent runtime unrelated to package management, trust, and harness mediation
• treating plugins as agents or allowing plugin installation to silently redefine an agent's identity
• a universal orchestration framework
• real-time collaborative editing
• a custom hosted Git replacement
• a single Agency-wide safety score
• a marketplace before local installation and reproducibility work well

Private sync can initially use Git remotes and existing repository permissions. A custom hosted collaboration or billing backend can wait until those are proven requirements.

Open decisions

• Which local daemon lifecycle and IPC/API protocol should the CLI, TUI, and MCP server use?
• Which harness is the first supported target?
• Does Agency own a hosted registry, or initially remain a thin client for Eve and agent-plugins?
• What exact agent/plugin formats and filenames should the first detectors recognize?
• Which harness adapters should be supported first, and what is the minimum adapter contract for local installation and remote provider access?
• Which capabilities and permissions must every bundle declare?
• Is the canonical installable object called a bundle, package, or something else?
• How should paid distribution, licensing, and trust/review work for public packages?
• What is the scanner provider API and normalized finding schema?
• Which checks belong in the free built-in scanner?
• What explicit consent, redaction, and data-retention rules apply to paid cloud scanners?
• How are scanner attestations signed, verified, expired, superseded, and revoked?
• Which reputation signals can inform discovery without becoming a universal trust score?
• How should users configure scanner quorum and package policy?