diff --git a/AGENTS.md b/AGENTS.md index 075abb2..83f1cf8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,12 @@ every harness; our spec contribution is the extension-management + bridge slot. capability negotiation; three transports (stdio / HTTP loopback / in-process). 6. **Spec-first.** Behavior changes start in `spec/`, get reviewed, then land in `packages/spec` as types + JSON Schema. +7. **scriptc-first packaging.** The `harness` binary ships via `scriptc --dynamic` + (owner decision — no Windows target yet; `bun --compile` is the Windows hatch). + The CLI must stay inside the island's constraints: JSON-only config (never + runtime TS eval), no TUI prompt libs (flag-driven), git ops via the `git` + binary, no `symlinkSync` (`ln`+copy fallback), console-shim logging — no + logtape/jiti/clack-class deps. ## Commit & branch conventions diff --git a/spec/README.md b/spec/README.md index 07c49dd..76f3876 100644 --- a/spec/README.md +++ b/spec/README.md @@ -27,3 +27,20 @@ Pinned interface names shared across specs: `Extension`, `ExtensionKind` (`skill - Agent Plugins 1.0 (`plugin.json`) — package manifest base - MCP — tool surface; `tools.call` in the bridge is a passthrough - A2A — agent↔agent (adjacent, not ours) + +## Governance & versioning + +These specs are **implementation-led**: they stabilize from real adopters, +not committee review. Documents carry a semver version; breaking changes +bump the spec's major, additive optional fields bump minor. + +Adoption pledge: the protocol and schemas are open — once **two or more +external harnesses** implement the bridge, stewardship moves toward a +neutral home (e.g. a foundation track such as AAIF) rather than staying +single-vendor. Until then, spec issues and change proposals go through this +repo's tracker. + +Schema `$id`s are minted under +`https://raw.githubusercontent.com/sigilco/agentplugins/v2/spec/` as an +interim domain — resolvable and surviving GitHub's repo-transfer redirects; +a canonical domain replaces it once the org's domain is set. diff --git a/spec/bridge/messages.schema.json b/spec/bridge/messages.schema.json index 733ad89..0af2f05 100644 --- a/spec/bridge/messages.schema.json +++ b/spec/bridge/messages.schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://spec.anyharness.dev/bridge/messages.schema.json", + "$id": "https://raw.githubusercontent.com/sigilco/agentplugins/v2/spec/bridge/messages.schema.json", "title": "AnyHarness Bridge Protocol v0.1 — message schemas", "description": "JSON-RPC 2.0 envelope and per-operation params/result schemas for the AnyHarness bridge protocol. Companion prose: protocol.md, operations.md, capabilities.md, transports.md, security.md. Sibling specs referenced by name: spec/manifest.md (plugin.json documents), spec/store-layout.md (paths), spec/lockfile.md (integrity), spec/trust.md (policy).", "type": "object", diff --git a/spec/lockfile.md b/spec/lockfile.md index d87b139..6f46ab9 100644 --- a/spec/lockfile.md +++ b/spec/lockfile.md @@ -92,10 +92,19 @@ Each value of `extensions` is an **Extension** — the installed unit | Field | Type | Required | Description | | ----- | ---- | -------- | ----------- | | `type` | string | yes | One of `git`, `github`, `registry`, `local`. Closed enum; new source types are a spec minor change. | -| `uri` | string | yes | Source identifier in canonical form for its type: `git` → clone URL; `github` → `owner/repo` or repo URL (SHOULD normalize to `owner/repo`); `registry` → registry URL + package coordinates; `local` → absolute or store-relative path at install time. | +| `uri` | string | yes | Source identifier in canonical form for its type: `git` → clone URL; `github` → `owner/repo` or repo URL (SHOULD normalize to `owner/repo`); `registry` → index URL + package coordinates (see registry note below); `local` → absolute or store-relative path at install time. | | `ref` | string | no | Resolved revision: commit SHA, tag, branch, or registry version. For `git`/`github` the installer MUST resolve floating refs to a commit SHA at install time and record the SHA — reproducibility depends on it. | | `path` | string | no | Subpath within the source where the package lives (monorepo sources), e.g. `plugins/deploy-tools`. | +Registry note (current posture): a `registry`-type source denotes an index +that resolves package coordinates to a concrete `git`/`github` source. The +first-party index is **discovery over GitHub topics** — publishers tag +extension repositories with a designated topic and the index answers +search/lookup queries from that corpus; a hosted skills.sh-style site MAY +later serve the same index. The lockfile records only the resolved source +(`type`, `uri`, `ref`), never index-internal state, so the file format is +agnostic to which index answered. + Interop note (skills.sh conventions): `uri`/`ref`/`installedAt`/`updatedAt` follow the same semantics as `sourceUrl`/`ref`/`installedAt`/`updatedAt` in skills.sh's lock entries, and `path` mirrors `skillPath`. An importer mapping diff --git a/spec/lockfile.schema.json b/spec/lockfile.schema.json index 8a95c5c..a14c7bf 100644 --- a/spec/lockfile.schema.json +++ b/spec/lockfile.schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://anyharness.dev/schemas/l0/0.1/lockfile.schema.json", + "$id": "https://raw.githubusercontent.com/sigilco/agentplugins/v2/spec/lockfile.schema.json", "title": "AnyHarness lockfile (harness/extensions.lock)", "description": "Machine-readable schema for ~/.agents/harness/extensions.lock (spec/lockfile.md). The spec text is authoritative if it conflicts with this schema.", "type": "object", diff --git a/spec/manifest.schema.json b/spec/manifest.schema.json index 1b50b4f..b7ea324 100644 --- a/spec/manifest.schema.json +++ b/spec/manifest.schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://anyharness.dev/schemas/l0/0.1/manifest.schema.json", + "$id": "https://raw.githubusercontent.com/sigilco/agentplugins/v2/spec/manifest.schema.json", "title": "AnyHarness manifest (plugin.json)", "description": "Machine-readable schema for an AnyHarness package manifest: the Agent Plugins 1.0 plugin.json base plus the dev.anyharness namespace (spec/manifest.md). The spec text is authoritative if it conflicts with this schema.", "type": "object", diff --git a/spec/store-layout.md b/spec/store-layout.md index 91a2636..a0e9479 100644 --- a/spec/store-layout.md +++ b/spec/store-layout.md @@ -108,6 +108,12 @@ a read/write shared location with the following compatibility guarantees: 4. AnyHarness MUST NOT treat `plugins/`, `harness/`, or any non-skill root entry as a skill. +The shared skills root is the **default** materialization target for +`skill`-kind Extensions — it is the standard every reader already scans. +`harness/packages//` remains an allowed per-Extension install target +for authors who want store-local containment; the lockfile `targets[]` +records whichever was used. + ### 5.2 `~/.agents/mcp.json` — shared MCP declarations `mcp.json` at the store root is a shared file in the de-facto diff --git a/spec/store-layout.schema.json b/spec/store-layout.schema.json index e5ce3e3..501acb2 100644 --- a/spec/store-layout.schema.json +++ b/spec/store-layout.schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://anyharness.dev/schemas/l0/0.1/store-layout.schema.json", + "$id": "https://raw.githubusercontent.com/sigilco/agentplugins/v2/spec/store-layout.schema.json", "title": "AnyHarness store descriptor (harness/store.json)", "description": "Machine-readable schema for the ~/.agents/harness/store.json descriptor defined by spec/store-layout.md §8. The spec text is authoritative if it conflicts with this schema.", "type": "object", diff --git a/spec/trust.schema.json b/spec/trust.schema.json index c5b4284..e55332b 100644 --- a/spec/trust.schema.json +++ b/spec/trust.schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://anyharness.dev/schemas/l0/0.1/trust.schema.json", + "$id": "https://raw.githubusercontent.com/sigilco/agentplugins/v2/spec/trust.schema.json", "title": "AnyHarness audit log record (harness/audit.log line)", "description": "Machine-readable schema for one JSONL record in ~/.agents/harness/audit.log (spec/trust.md §6). The spec text is authoritative if it conflicts with this schema.", "type": "object",