diff --git a/.claude-plugin/marketplace.base.json b/.claude-plugin/marketplace.base.json index b298e5b..bf0fdd3 100644 --- a/.claude-plugin/marketplace.base.json +++ b/.claude-plugin/marketplace.base.json @@ -9,7 +9,7 @@ "plugins": [], "metadata": { "description": "Agent collaboration plugin marketplace", - "version": "4.9.0", + "version": "4.9.1", "repository": "https://github.com/sumitake/agent-collab" } } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a621f60..528532a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ { "name": "agent-collab", "description": "Unified dynamic-host collaboration package. Centralized skills and async coordination work without legacy packages; every model-execution route requires the verified signed plugin artifact.", - "version": "4.9.0", + "version": "4.9.1", "author": { "name": "John Osumi" }, @@ -32,7 +32,7 @@ ], "metadata": { "description": "Agent collaboration plugin marketplace", - "version": "4.9.0", + "version": "4.9.1", "repository": "https://github.com/sumitake/agent-collab" } } diff --git a/README.md b/README.md index 12fd0c5..c3923d3 100644 --- a/README.md +++ b/README.md @@ -4,724 +4,262 @@ [![CodeQL](https://github.com/sumitake/agent-collab/actions/workflows/codeql.yml/badge.svg)](https://github.com/sumitake/agent-collab/actions/workflows/codeql.yml) [![Secret Scan](https://github.com/sumitake/agent-collab/actions/workflows/secret-scan.yml/badge.svg)](https://github.com/sumitake/agent-collab/actions/workflows/secret-scan.yml) -**agent-collab** turns a collection of AI coding agents from different vendors — -Claude, Codex, Gemini, Grok, and OpenCode-hosted models — into one governed -engineering team: any of them can lead a session, delegate work to the others -through managed, verified routes, and none of them can approve, merge, or -expand its own authority without independent review from a different model -family. - -## Why this exists - -A single AI agent working alone has structural problems that no amount of -prompting fixes. It shares blind spots with every other instance of its own -model family, so the errors it makes are exactly the errors it cannot catch in -review. It can misreport what it did — vendors themselves disclose -reward-hacking behavior in frontier coding models — so its claims of "tests -pass" or "review converged" need verification that does not come from itself. -And when it can execute, review, and merge in one unaccountable loop, a single -hallucination can propagate into governing documents and tooling unchecked. - -This project exists to close those three gaps structurally rather than by -trust: - -- **Cross-family reviewer independence, enforced at selection.** The - coordinator resolves the active primary's family and the artifact author's - family at call time and *excludes both* from reviewer, worker, tiebreaker, - and fallback selection — fail-closed, so an unknown family refuses a - governance route rather than guessing. Review therefore comes from a - different vendor's model than the one that wrote the change. Different - families fail differently; that is the point. -- **Written evidence with an honest boundary.** Every governed merge carries a - compliance trace — tier, cross-check verdict, and the standing directives - followed — and CI hard-fails a PR whose trace is missing, malformed, or - under-declares its tier. Two different mechanisms do two different jobs: the - coordinator enforces family independence when it *selects* a route - (fail-closed), and CI validates the **form and presence** of the recorded - evidence. What neither does today is cryptographically authenticate a quoted - verdict — that is discrepancy detection, with per-agent signing on the - roadmap. The managed Gemini leg additionally returns a signed broker - proof, and this project's own workspace layers stricter requirements - (reviewer identity, reviewed SHA, distinct-family peer review) on top for - its highest tier. -- **Operator final-say where it is codified.** Agents coordinate with each - other and self-merge converged, green, recorded changes; operator-reserved - paths (CODEOWNERS-gated files, including the governance contract itself) and - the codified operator-required classes route to the human instead. Not every - sensitive change is machine-forced to a human — the reserved set and tier - rules define the boundary — and the operator can revert, redirect, or revoke - the arrangement at any time. - -## What it delivers in practice - -- **Coverage a single model cannot give you.** At minimum one adversarial - review leg from a family other than the author's — and on the highest tier, - this project runs a three-family triangle (author, cross-check, and a peer - reviewer distinct from both), the direction the contract is converging on. In production use on this project, cross-family - reviewers have repeatedly caught real defects — silently drifted CI gates, - falsified historical records, contract-weakening edits, overclaiming - documentation — that same-family review missed. -- **Cost-tiered delegation, explicitly targeted.** Bulk reading, mechanical - codegen, and long-context work can be sent to cheaper provider pools while - frontier reasoning and the merge decision stay with the primary. Targets are - named explicitly per call today, with automatic cost-aware worker routing the - next step on that path; an explicit target never silently substitutes another - provider, and model plus reasoning effort are disclosed per invocation, so - cost and quality stay auditable. Delegate selection follows a fixed order: - capability first (the delegate must clear the task's quality bar — an - under-capable cheap choice that forces rework costs more than it saves), - availability second (an exhausted quota pool is infeasible, not merely - expensive), and only then cost rank, preferring routes that conserve the - primary's own family pool — models of one vendor family draw one shared - quota, so a cheaper same-family model still spends the budget that funds - frontier work. -- **A hard security boundary around providers.** Provider CLIs are reached - only through a signed, notarized native runtime with per-member digest - verification, socket-activated zero-idle execution, and typed-unavailable - failure — never raw provider invocations, ambient credentials, or silent - fallbacks. -- **One plugin for every host.** A single package serves Claude Code, Codex, - Antigravity, OpenCode, ZCode, and custom hosts, resolving the active - primary's identity, model, and session dynamically — no per-host forks to - drift out of sync. - -This public repository distributes that one package, **agent-collab** (v4.9.0), and is -the source of truth for the coordinator policy, skills, migration tooling, the -fail-closed runtime client, contribution governance, and release-safety checks. -The signed and notarized darwin-arm64 native runtime is committed in this -repository and advertised through a closed activation manifest; the build -credentials and signing infrastructure that produce it remain in a separate -private build/sign system. - -Contributors need no access to the private build/sign system. See -[public governance](docs/public-governance.md), -[migration guidance](docs/migration-from-legacy-packages.md), and the -[security policy](SECURITY.md). -## What this is not - -- Not an open-source grant. It is source-available under the PolyForm Strict - License 1.0.0 (see [License](#license)). -- Not a shipper of provider executor source, raw provider invocation recipes, - downloaders, post-install hooks, or a runtime cache. The private build/sign - system stays private. -- Not a collection of host-specific plugins. One package carries native metadata - for every supported host. -- Not a synchronous Claude path. Claude remains asynchronous inbox-only; the - shared runtime never creates a synchronous Claude route. - -## What it provides - -- One unified `/agent-collab:*` skill surface (review, intent, code/security, - QA, logic, brainstorming, debate, research, long-context, delegation, - orchestration, readiness, teamwork, migration, and native inbox-monitor - lifecycle management) across every host. -- Dynamic primary-identity resolution (primary id, family, active model, host - runtime, session) with cross-family reviewer, worker, tiebreaker, and fallback - independence enforced fail-closed. -- Managed, broker-only provider routes (Codex, Gemini, OpenCode, and unified - Grok 4.5), each with explicit, non-substitutable `target=` selection and - sealed action authorities. -- A verified native runtime client: per-member SHA-256, Developer ID signature, - online notarization, and Mach-O checks before any provider launch, with a - typed-unavailable fallback on any failure. -- Zero-idle execution: a per-user launchd socket starts the signed runtime only - when a request arrives and exits after one bounded response, with no resident - process, polling loop, or ambient credentials. -- A provider-free migration doctor, policy-only safe mode, and a byte-level - clean-public-repository history gate. -- Reproducible releases: signed annotated tags, deterministic SHA-256 evidence, - an SPDX 2.3 SBOM, and matrix CI with CodeQL, Gitleaks, and secret scanning. - -## Current package - -| Package | Version | Role | -|---|---:|---| -| `agent-collab` | 4.9.0 | Unified skills, dynamic host policy, migration preflight, and verified native-runtime client | - -## What's new - v4.9.0 - -- **Conditional decomposition guidance for `orchestrate` and `teamwork`.** - When a graph or milestone plan decomposes product-feature implementation, - both skills now prefer tracer-bullet vertical slices (complete narrow path - through every layer, demoable or independently verifiable, sized to one - bounded worker invocation with explicit acceptance criteria) and treat wide - refactors as the exception: atomically codemoddable changes run as - checkpointed, fully verified batches, and expand–contract sequencing is - reserved for migrations where old and new forms must genuinely coexist. - The guidance names its own inapplicability (research, operations, - configuration, decision-only work). Adapted portions from the MIT-licensed - mattpocock/skills `to-tickets` skill (pinned `2ab95809`); both specs carry - the full MIT notice and both members' SPDX expression is - `LicenseRef-PolyForm-Strict-1.0.0 AND MIT`. - -## What's new - v4.8.0 - -- **Code review gains spec-fidelity and smell-baseline lenses.** The - `code-review` skill's JSONL contract is extended backward-compatibly with - `Spec` and `Smell` severities plus an optional `spec_ref` field (consumers - filtering the four defect severities are unaffected). The primary - materializes the originating spec before the call under explicit precedence - and ambiguity rules (never synthesized, never inferred from branch names, - always treated as untrusted data), and a fixed Fowler smell baseline applies - as subordinate, evidence-bound maintainability heuristics that documented - repo standards override. Spec and smell findings stay semantically separate - from defect aggregation through synthesis. The two-axis structure is adapted - from the MIT-licensed mattpocock/skills `code-review` skill (pinned commit - `2ab95809`); the touched spec carries the full MIT notice for the adapted - portions, SPDX declares the member `LicenseRef-PolyForm-Strict-1.0.0 AND - MIT`, and `NOTICE` now points at the provenance document generically. - -## What's new - v4.7.0 - -- **Engineering-process skill pack (MIT-derived).** Three self-executed skills - join the package: `decision-map` (multi-session planning as a shared map of - decision tickets on the issue tracker, with an explicit user-approval gate - before any tracker write), `prototype` (throwaway logic/UI prototypes that - answer one design question, isolated from the caller's branch), and - `architecture-review` (a codebase sweep for module-deepening opportunities - with a self-contained visual report, composing with the routed `architect` - consultation). They are derived from the MIT-licensed - [mattpocock/skills](https://github.com/mattpocock/skills) repository at - pinned commit `2ab95809` and adapted for this package; the derived portions - remain MIT-licensed, each generated `SKILL.md` carries the full MIT notice, - release SPDX evidence declares those members `MIT`, and - `docs/third-party-skill-provenance.md` records per-file provenance. No - coordinator, provider, or routing surface is touched. - -Earlier release notes live as per-release fragments in +`agent-collab` is a source-available plugin for governed collaboration among +AI coding agents. It gives the trusted primary reusable workflows for independent +review, planning, assurance, delegation, knowledge work, orchestration, and +domain expertise while keeping reviewer independence and execution authority +explicit. + +The core idea is simple: different model families fail differently. A review +from the author's own family is useful, but it is not independent governance +evidence. `agent-collab` resolves current lineage, excludes ineligible families, +seals each managed route to a declared authority, and returns typed failures +instead of silently widening permissions or invoking a raw provider fallback. + +## What it is—and is not + +`agent-collab` provides: + +- one unified package and `/agent-collab:*` skill namespace; +- 50 generated skills spanning review, planning, delegation, orchestration, + engineering process, and specialist domains; +- dynamic primary and artifact-author lineage with cross-family independence; +- closed read-only and output-only managed routes; +- provider-free migration and runtime-readiness checks; +- a verified, manifest-selected native runtime boundary where the selected + source tree or release contains activation material; and +- public contribution, CI, security, and release-safety contracts. + +It is not: + +- a general AI swarm with equal authority for every agent; +- a raw provider CLI wrapper or provider-executor source distribution; +- a set of host- or provider-specific plugins; +- an autonomous merge, deployment, or governance service; +- a guarantee that every listed route is active on every host; or +- an open-source license grant. The public code is source-available under + PolyForm Strict 1.0.0. + +## Why the controls matter + +- **Independent failure modes:** governance review excludes the active primary + and reviewed artifact's known author family. +- **Least authority:** advisory work stays read-only; output-only workers return + artifacts for the primary to inspect and apply. +- **Honest uncertainty:** unknown lineage, unavailable native contracts, + migration conflicts, and same-family requests remain typed and fail closed. +- **Separation of duties:** provider output cannot merge, deploy, change policy, + or approve itself. +- **Operator control:** reserved security, governance, release, activation, and + recovery decisions remain with the operator where public policy requires it. + +Read [Governance and authority](docs/architecture/governance-and-authority.md) +for the complete model and its documented residuals. + +## Current package and evidence state + +| Package | Source version | Role | +| --- | ---: | --- | +| **agent-collab** (v4.9.1) | 4.9.1 | Unified skills, host policy, migration, verified runtime client, and public release checks. | + +Version words are easy to misuse. This README describes the current repository +source. A signed tag, GitHub release, installed package, selected package, and +runtime-ready host are separate facts. + +At the 2026-08-05 authoring snapshot, `origin/main` began at 4.9.0, the latest +GitHub release record was v4.5.1, a signed v4.6.0 tag existed without a GitHub +release record, and the repository contained newer staged changelog fragments. +This change advances repository source to 4.9.1. It makes no claim about a +specific host installation or active route. + +See [Status and evidence](docs/architecture/status-and-evidence.md) for the +binding lifecycle vocabulary and dated evidence matrix. + +## What's new - v4.9.1 + +- Added an indexed, sanitized public architecture handbook covering system + context, capabilities, governance, lifecycle operations, repository/release + architecture, and evidence-state distinctions. +- Rebuilt this README as a public entry point instead of a second low-level + protocol reference. +- Corrected stale package metadata and technical-reference statements about the + committed activation artifact, package version, signing anchor, and current + manifest generation. +- Added a design-evidence registry that distinguishes current cited design + sections from superseded and historical review material. + +Earlier release and staged change notes live in [`changelog.d/`](changelog.d/) and are compiled into -[CHANGELOG.md](CHANGELOG.md) at each release cut. +[`CHANGELOG.md`](CHANGELOG.md) by the release flow. -## System architecture +## Architecture at a glance ```mermaid flowchart LR - H["Claude, Codex, Antigravity, OpenCode, ZCode, or custom host"] --> C0["Plugin-relative public coordinator"] - C0 --> P["Immutable primary and artifact snapshots"] - P --> G["Governance and family-independence policy"] - G --> S["Sealed route/action preflight"] - S --> N["Observed non-model seam
host async-inbox readiness only"] - S --> C["Verified plugin-relative native runtime client"] - C --> B["Per-user launchd socket
zero idle process"] - B --> Q["Signed guardian + acknowledged gate"] - Q --> X1["Managed Codex, Gemini, OpenCode,
and unified Grok 4.5 roles"] - C --> X2["Local runtime management"] - W["Private build/sign system"] -. "signed and notarized bundle" .-> C - W -. "same exact digest" .-> B + Host["Supported AI host"] --> Primary["Trusted primary"] + Primary --> Skill["agent-collab skill"] + Skill --> Local["Primary-executed playbook"] + Skill --> Policy["Identity, independence, and authority policy"] + Local --> Primary + Policy --> Runtime["Verified manifest-selected runtime"] + Runtime --> Role["Managed reviewer or worker role"] + Role --> Result["Typed result and evidence"] + Result --> Primary + Primary --> Verify["Local integration, tests, and governed landing"] + Producer["Private native producer"] -. "final signed bundle only" .-> Runtime ``` -The plugin runtime client accepts no binary or member override. It selects only -the Darwin-arm64 standalone-bundle entry in `runtime-manifest.json`, requires -the fixed plugin-relative bundle and entrypoint, rejects links, path aliases, -unknown members, writable modes, and parent traversal, then verifies every -member's size, SHA-256, Mach-O type, architecture, minimum macOS, signing -profile, and the domain-separated whole-bundle identity. Production also -requires the pinned Developer ID team and notarization assessment. It then uses -the fixed broker/provider protocols with a scrubbed environment. Every artifact -advertises its exact route/action contracts; -the client rejects unadvertised rows, mismatched route/authority combinations, -and author-family provenance drift. Missing, blocked, unsigned, mismatched, or -unsupported artifacts fail closed with typed status. - -Codex, Gemini, OpenCode, Grok, and Composer use a digest-bound, per-user launchd Unix socket. Launchd -owns the mode-`0600` socket and starts the exact signed runtime only when a -request arrives. The broker accepts one bounded request, runs it through the -managed backend, returns one bounded response, and exits; there is no -`KeepAlive`, `RunAtLoad`, polling loop, interval, calendar trigger, or resident -agent process. At idle, launchd retains only the job registration and one -mode-`0600` Unix listening socket; the installed immutable bundle consumes disk -but no provider process, polling CPU, provider memory, or network traffic. Only -local runtime-management calls retain the fixed direct exact-entrypoint path. -Missing, stale, or mismatched broker state is a typed -failure and never falls back to direct execution for any broker-only route. -Updates use a legacy-default blue/green selector. A candidate dispatcher is -published under a distinct content-derived label and socket, then proven with a -no-provider ping while blue remains selected. Every request captures its lane -ordering once: an in-flight blue request completes on blue, while the next -request after atomic selector commitment selects green. Green may fall back to -the still-proven blue lane only before any request bytes are accepted; it never -retries blue after green accepts a request. Blue is retained until an explicit -drain operation proves green, observes blue quiescence, receives the private -registry/lock drain gate, and confirms host-client finalization. Codex host -updates use a distinct marketplace-qualified candidate because a same-selector -update deletes the prior cache; the migration doctor permits this bounded -two-selector overlap because both entries are the unified `agent-collab` -package, while retired package names remain blocking. The old selector/cache is -removed only after fresh sessions prove the candidate selector, version, and -loaded-path digest with zero old-client sessions. - -Gemini, Grok, and OpenCode use one canonical cross-lane lock for the entire -request through provider teardown. The packaged lock probe proves both -contention and acquisition against that namespace without reading credentials -or invoking a provider. This makes mixed old/new host clients safe while all -normal traffic remains blue and prevents blue and green from concurrently -mutating the same provider state. -The broker removes the Codex Desktop outer-Seatbelt marker before backend -dispatch because socket activation does not inherit the client's Seatbelt. -Every brokered Grok and Composer attempt must therefore build and validate its -own nested read-only sandbox. Provider children receive closed backend-specific -environment allowlists with canonical passwd HOME for reliable authenticated -state plus fresh private temporary/cwd roots rather than the broker's ambient -environment. Grok uses real serialized `~/.grok`; OpenCode keeps private XDG -roots and selected-provider auth; Codex keeps a sealed per-call `CODEX_HOME`, -SQLite, and XDG overlay. Provider-specific policy overlays may narrow -credentials or tools without replacing process HOME. Broker frames cannot -invoke local runtime-management actions. -The runtime resolves the canonical user HOME from passwd for provider -authentication while keeping the caller checkout read-only by default. Every -request receives a private temporary workspace where the selected provider may -clone or copy inputs, edit, build, use tools, and reason agentically. Only -explicit provider-state paths are writable outside that workspace, in-request -binary auto-update is disabled, execution is bounded, descendants are reaped, -and temporary cleanup is positively verified. OpenCode build is sealed -output-only: its private-workspace changes are returned for trusted-primary -review and application rather than written into the caller checkout. -Canonical HOME is not a deny-all-read confidentiality boundary: providers -operate under explicit same-UID read trust so authenticated CLIs, -loaders, and tools remain reliable. The structural boundary confines writes, -execution/lifecycle, provider-state access, protected paths, and request -cleanup; provider-specific overlays may narrow reads further. - -A blocked access attempt inside an established boundary is containment success -and does not by itself fail an invocation. A structural containment failure is -reserved for failure to establish the boundary before launch or positive -evidence that a write escaped allowed paths or changed protected -source/credentials. Authentication, protocol/output, timeout, provider, -teardown, and cleanup failures stay orthogonal; `rc=0`, empty output, or stderr -wording never manufacture a containment result. Direct CLI use is not a normal -reliability fallback for a managed route. -If the client disconnects, the broker propagates cancellation through every -managed provider route, reaps provider child groups, -and discards partial output. Disconnect-driven cancellation is never retried; -when too little deadline remains to establish the managed boundary, the route -returns typed `timeout` before provider setup. -Gemini uses the managed agy backend with canonical passwd HOME, mandatory PTY, -serialized state, and write containment. `gemini/governance` is distinct from -advisory/long-context and emits complete artifact-bound broker proof; ordinary -Gemini output cannot be presented as governance evidence. -Proof v1 and v2 are exact, disjoint response-consistency schemas, not -cryptographic attestations. The proof hash catches malformed or inconsistent -output inside the verified native-runtime boundary; it does not claim to defeat -a process that can already rewrite the verified runtime or its private -anonymous stdout pipe. The client rechecks the selected executable identity -immediately before direct child launch, uses no external response-ingest path, -and rejects any runtime rewrite before opening that pipe. Within that boundary, -a complete legacy v1 proof remains intentionally accepted for retained-lane -rollback continuity, while any received v2 discriminator selects only the v2 -schema. Dual-version consumers should use -`GEMINI_GOVERNANCE_PROOF_KEYSETS`; the legacy -`GEMINI_GOVERNANCE_PROOF_KEYS` name remains a v1-only compatibility alias. - -The broker rejects cross-UID, stale/replayed, substituted-artifact, and -connecting-process mismatches. It does not claim to protect provider -credentials from arbitrary malicious code already running as the same operator -UID, which can already read that user's auth state. The exact immutable bundle, -entrypoint path, member inventory, and identity are revalidated for each -request. - -The expected Apple Developer ID Team ID is pinned in the public -`plugins/agent-collab/signing_policy.py` policy source, independently of the -runtime manifest, and is checked against every runtime member's signature during -verification. An activation release refuses to publish unless the committed -bundle matches that pinned team and passes notarization; a policy-only release -carries no runtime and keeps every native route typed unavailable. - -Governance plus applicable review, fallback, and worker calls carry the -captured artifact separately from the instruction prompt. The sealed native -JSON represents its exact bytes -as base64 plus SHA-256, byte size, author model, and derived author family. The -client decodes and verifies the representation before launch; neither the -coordinator nor the native runtime may reconstruct the artifact from a prompt -copy. - -The signed and notarized darwin-arm64 runtime bundle is committed in this -repository (first shipped in the v4.2.x activation release). Native Codex, -Gemini, OpenCode, and Grok 4.5 routes activate once a host installs the plugin, -verifies the runtime, and installs the broker; until then they remain typed -unavailable, and a policy-only fallback keeps every native route unavailable by -design. Deterministic tests use temporary fixture bundles only. The release gate -requires every platform artifact to expose the complete required contract -matrix, including the `composer/codegen` compatibility route. - -## Production lifecycle - -1. Public policy or protocol changes are reviewed and validated in this - repository; private runtime changes remain inside the build/sign system. -2. The private producer runs its containment, provenance, and - authority-boundary tests without exporting implementation source. -3. The private producer builds one Darwin-arm64 standalone bundle, signs every - nested Mach-O before the entrypoint with hardened runtime, notarizes the - closed bundle, and records whole-bundle plus per-member evidence. -4. A policy-only plugin release omits the runtime and keeps every native route - typed unavailable. An activation release commits the final signed and - notarized bundle, its closed manifest metadata, and the exact third-party - notice/license tree; no private source implementation crosses the boundary. -5. Plugin CI validates both Claude and Codex manifests/marketplaces, schemas, - skills, migration behavior, runtime fixtures, the dependency-free secret - scan, CodeQL security analysis, release consistency, and public-export - safety. -6. A policy-only signed-tag release proves the runtime manifest is empty and - the archive contains no runtime. For activation, a macOS verification job - binds every member's codesign/Mach-O evidence, entrypoint notarization, - manifest digest, whole-bundle identity, and commit SHA before the publish job - may include the bundle. SPDX 2.3 - evidence distinguishes project-owned PolyForm material from the embedded - CPython, Nuitka, and incorporated third-party components. -7. Hosts update one package, run the migration doctor, restart, and verify the - resolved profile plus eligible routes. Initial activation hosts run the - co-packaged `runtime_setup.py status` and `prepare` commands, then explicitly - run `install-broker`. Subsequent updates stage a distinct dispatcher, install - every dual-lane client beside the old client while blue remains selected, - prove ping and canonical locks, then commit, session-gate old-client - finalization, and separately drain through the private manager. Managed Grok - device login is exposed only as `runtime_setup.py login-grok`. -8. Dispatcher updates copy only manifest-listed regular bundle members and the - manifest into an immutable artifact-plus-manifest digest directory. Staging - writes only candidate plist/state plus a blue-selected selector, verifies the - exact candidate job/socket, executes one protocol-only ping, and proves the - process exits. Failure restores the prior selector bytes and removes only the - candidate. Commitment is a one-generation selector CAS and never bootouts - blue. Bounded `launchctl` timeout/output failures remain typed lifecycle - errors rather than escaping as host tracebacks. - -Rollback uses policy-only safe mode. Set `AGENT_COLLAB_SAFE_MODE=1` in the -active host runtime environment and restart that host; all model-execution -requests then return typed unavailable. An independently configured host inbox -may still report readiness, but the public coordinator never sends through it; -without a current availability observation it is unavailable too. Unset safe -mode and restart after validation. Rollback never reinstalls an old package. - -## Install and migrate - -Claude Code: +The public repository owns skills, coordinator policy, client behavior, +migration, governance, tests, and release checks. Native provider +implementation and build/sign credentials remain in a separate private +producer. The repository may receive only the final reviewed standalone bundle, +its closed manifest metadata, and required license evidence. -```text -/plugin marketplace add sumitake/agent-collab -/plugin install agent-collab@agent-collab -/agent-collab:migration-doctor -``` - -Codex CLI/app: - -```text -codex plugin marketplace add sumitake/agent-collab -codex plugin add agent-collab@agent-collab -``` - -The same package carries native metadata for both hosts: -`plugins/agent-collab/.claude-plugin/plugin.json` for Claude-compatible package -managers and `plugins/agent-collab/.codex-plugin/plugin.json` for Codex. The -repository Codex marketplace is generated at -`.agents/plugins/marketplace.json`; it contains only `agent-collab`. - -Then invoke the `agent-collab` migration-doctor skill from a new Codex task. -Antigravity, OpenCode, ZCode, and custom hosts must select the same single -package through their compatible plugin manager; if that host has no native -plugin surface, it cannot install this package directly and must remain -temporarily unsupported rather than recreating a provider-specific shim. - -The retired standalone packages migrate to the unified `agent-collab`: - -- `codex-tools →` managed Codex backend in `agent-collab` -- `glm-worker →` managed OpenCode backend in `agent-collab`, with - `opencode-go/glm-5.2` as the current Zhipu-family model preset -- host-specific collaboration packages → dynamic host profiles in - `agent-collab` +The package's current public policy distinguishes read-only review/context +roles from output-only code generation. Output-only work occurs in a private +temporary workspace and returns material for trusted-primary review; it does +not receive caller-workspace write authority. Direct CLI use is not a normal +fallback for a managed route. -The exhaustive namespace and skill table is in -[docs/migration-from-legacy-packages.md](docs/migration-from-legacy-packages.md). +Start with the [architecture handbook](docs/architecture/README.md). The +[package reference](plugins/agent-collab/README.md) retains the low-level +coordinator and runtime contracts. -An activation release adds a closed signed-runtime management surface beside -the coordinator. Resolve the installed plugin root and run only: +## Features and workflows -```text -python3 "/runtime_setup.py" status -python3 "/runtime_setup.py" prepare -python3 "/runtime_setup.py" install-broker -python3 "/runtime_setup.py" broker-status -python3 "/runtime_setup.py" dispatcher-status -python3 "/runtime_setup.py" login-grok -``` - -These operations accept no provider, model, path, environment, binary, tool, -or raw-argument overrides. The public client keeps the process environment -scrubbed and sends only `generic` or `codex_desktop` as a closed host-context -observation; the signed runtime derives and validates its own state roots from -the OS login identity. Exact supported Codex, OpenCode, and Grok CLIs remain -external prerequisites and must be installed and authenticated through their -vendor-supported interfaces. No workspace checkout or provider-specific plugin -is required. Policy-only releases report the management surface unavailable. - -Broker lifecycle is always explicit: import, readiness, route invocation, and -package auto-update do not install or modify launchd state. The private rollout -manager invokes these closed update primitives in order after its host and -provider gates: +| Need | Start with | +| --- | --- | +| Independent review | `second-opinion`, `code-review`, `governance-review`, `red-team`, `qa-verify` | +| Architecture and planning | `architect`, `brainstorm`, `architecture-review`, `intent-check`, `decision-map` | +| Delegated research or implementation | `delegate`, `dev-delegate`, `worker`, `teamwork` | +| Reproducible multi-step work | `chain`, `chain-configurator`, `orchestrate` | +| Large-context synthesis | `knowledge-compile`, `long-context` | +| Readiness and migration | `agent-readiness`, `agent-runtime-status`, `migration-doctor`, `route` | +| Specialist engineering | Language, infrastructure, reliability, data, AI, evaluation, and writing-quality skill packs | -```text -python3 "/runtime_setup.py" stage-dispatcher -python3 "/runtime_setup.py" dispatcher-ping -python3 "/runtime_setup.py" dispatcher-lock-probe --provider gemini --timeout-ms 5000 -python3 "/runtime_setup.py" commit-selector -python3 "/runtime_setup.py" drain-retiring -``` +Some skills are primary-executed playbooks; others use managed synchronous +routes. Claude and Antigravity can participate through host-owned async +coordination only after explicit target/session readiness is observed. The +public coordinator never sends and never invokes Claude headlessly. Visual +skills remain primary-only where the protocol has no typed image transport. -Reject an uncommitted candidate or rebuild mutable files from the committed -selector without changing desired provider binaries: +The full map is in +[Capabilities and workflows](docs/architecture/capabilities-and-workflows.md). -```text -python3 "/runtime_setup.py" abort-candidate -python3 "/runtime_setup.py" recover-last-committed-control-plane -``` +## Install -Manual historical switching and complete removal remain separately named and -are never invoked by package auto-update: +### Claude Code ```text -python3 "/runtime_setup.py" rollback-broker -python3 "/runtime_setup.py" uninstall-broker +/plugin marketplace add sumitake/agent-collab +/plugin install agent-collab@agent-collab +/agent-collab:migration-doctor ``` -`broker-status` is read-only and value-free: it reports only installation, -the canonical selected lane, job/socket state, artifact/manifest digests, -closed liveness readiness, rollback availability, and the fact that no -persistent process is configured. It never invokes a provider. Lifecycle -commands accept no caller-selected path, label, socket, environment, provider, -model, or raw argument. - -Remove every old package reported by the doctor, then run the doctor again. -The doctor reads filesystem/registry state and Codex -`[plugins."name@marketplace"]` entries from `~/.codex/config.toml`, distinguishes -enabled from installed-disabled state, preserves the observed source host, and -prints uninstall commands for that host's package manager. It also requires -the signed runtime and canonical broker path to pass a provider-free closed -liveness exchange. Provider routing stays blocked while a retired package -remains installed or active or executable broker readiness is unproven. Cached -but unselected residue is reported separately. - -For an unknown/custom primary, explicitly configure: - -| Profile field | Environment variable | -|---|---| -| `primary_id` | `AGENT_COLLAB_PRIMARY_ID` | -| `primary_family` | `AGENT_COLLAB_PRIMARY_FAMILY` | -| `active_model` | `AGENT_COLLAB_ACTIVE_MODEL` | -| `host_runtime` | `AGENT_COLLAB_HOST_RUNTIME` | -| `session_identifier` | `AGENT_COLLAB_SESSION_ID` | -| asynchronous inbox availability | `AGENT_COLLAB_ASYNC_INBOX` | - -Known profiles still refresh their active model/family observation before each -invocation. OpenCode is a host runtime, not a model family; GLM output carries -Zhipu provenance. Model lineage is parsed from exact provider and model-id -segments; conflicting lineage signals or incidental substrings resolve to -unknown rather than whichever family happens to match first. Automatic -detection relies on strong session signals -(`CODEX_THREAD_ID`, `CLAUDE_CODE_SESSION_ID`/entrypoint, -`ANTIGRAVITY_SESSION_ID`, or `ZCODE_SESSION_ID`), never ambient installation -paths such as `CODEX_HOME` or `OPENCODE_CONFIG`. -When Codex Desktop omits `CODEX_ACTIVE_MODEL`, the policy resolves the exact -lowercase-UUID thread's same-owner rollout file from the fixed Codex sessions -tree and uses its newest complete, internally consistent OpenAI turn context. -Ambiguous, linked, writable, malformed, oversized, or conflicting evidence -fails governance closed; no model is guessed from configuration or defaults. -The OpenCode model is selected on every request in this order: a strong live -OpenCode or ZCode active-model observation, explicit central -`primary.opencode_model` configuration, then the fixed current preset -`opencode-go/glm-5.2`. Row-level model fields are not selection fallbacks. A -live session switch therefore changes provenance on the next request; an -Anthropic or unknown selected model is prohibited. Hosts that require the -OpenCode Go subscription set -`AGENT_COLLAB_OPENCODE_PROVIDER=opencode-go`; while that guard is present, the -policy rejects malformed provider configuration and every selected model -outside the exact `opencode-go/` namespace before native execution. -This blocks the standard metered OpenCode Zen namespace without enabling its -optional balance fallback. - -`AGENT_COLLAB_ASYNC_INBOX=available` (or request field -`primary.async_inbox="available"`) is an availability observation, not a send -primitive. The public coordinator accepts only `inbox/async` with -`operation=readiness`, non-governance authority, and an exact target row: -`{"target_id":"claude|antigravity","target_family":"anthropic|google","target_session_identifier":"..."}`. -The id/family pair and nonblank target session must be trustworthy, and the -target family must differ from the current primary family. Execute or -governance requests are schema errors; the coordinator never sends and never -invokes Claude headlessly. The host-owned async transport performs any later -handoff. - -## Skill surface - -The unified package includes review, intent, code/security, QA, logic, -brainstorming, debate, research, long-context, visual-workflow, delegation, orchestration, -engineering-process (`decision-map`, `prototype`, `architecture-review`), -readiness, teamwork, migration, native inbox-monitor lifecycle, and explicit managed-routing skills under the -single `/agent-collab:*` namespace. Provider targets are request parameters, -not plugin identities. - -The current protocol has no typed image or binary-media field. `visual-review` -and `ui-to-code` therefore provide an explicitly primary-only workflow or -report managed independent visual review unavailable; they never invent a -path-based attachment or raw-provider fallback. - -Explicit `target=gemini`, `target=codex`, and `target=opencode` requests are -fail-closed and never silently substituted. Gemini has separate read-only -advisory, governance, and long-context actions; Codex advisory, OpenCode plan, -and OpenCode private-workspace/output-only build authority are sealed -separately and never promote or demote into one another. Codex build is -a resolvable mutation-capable request but returns typed unavailable until a -hardened mutation backend exists; it never widens advisory. - -Managed xAI targets are equally explicit: `target=grok` has separate read-only -architecture, governance, and huge-context actions; `target=composer` is the -compatibility name for constrained Grok 4.5 output-only code generation. That -route has no file, shell, test, worktree, PR, or merge authority. All remain -deterministically temporarily -unavailable until the signed runtime advertises their exact route/action contracts. -Codex, Gemini, OpenCode, Grok, and Composer requests are broker-only and never fall back to direct runtime -execution. Grok prose accepts only an explicit `EndTurn` terminal; exact -`Cancelled` is a named non-success with no retained assistant text and may be -retried once only when more than ten seconds remain under the original -deadline. Final UTF-8 input above the inclusive 1,048,576-byte managed ceiling -returns `input_limit` before provider authentication or spawn. -Grok 4.5 is reachable only through sealed `architecture`, `governance`, or -`huge_context` actions; generic advisory, brainstorm, debate, QA, and fallback -requests cannot select it. OpenCode build is a distinct tool-capable, -private-workspace/output-only action and never aliases its read-only plan -action or writes the caller checkout. -Applicable non-governance review, fallback, and worker requests may include an -exact immutable artifact snapshot; its author model is resolved independently -and that family is excluded from selection alongside the active primary family. An -unknown artifact-author family emits an independence warning for -non-governance work and fails governance closed. - -For non-trivial code generation, Grok 4.5 through `composer/codegen` must receive a comprehensive coding -packet produced by the primary architect and reviewed by an eligible -distinct-family synchronous architecture complement. The packet defines scope, -invariants, authority boundaries, exact files and symbols, error taxonomy, -lifecycle, tests, and acceptance criteria. Claude and Codex frontier primaries -are the strongest default architecture seats; Grok 4.5 is the qualified -near-peer/adversarial architecture complement. The compatibility codegen route implements the -converged packet; it never plans the architecture. Asynchronous inbox review is -a fallback only when no eligible synchronous complement is available. - -## Clean public repository invariant - -This repository, every reachable ref, and every release archive must remain -free of provider executor source, raw provider invocation recipes, private -absolute paths, credentials, retired package trees, and unreviewed native -artifacts. The byte-level history gate inspects every ref and reachable commit, -tree, blob, annotated-tag object, and message, including direct non-commit refs. -It validates release-tag form and targets, recursively scans nested archive -members under cumulative depth, member-count, per-member, and decompressed-size -limits, and rejects provider-backend archive directories, symlinks, and other -unsafe tree modes. Python AST evaluation also catches statically constructed -provider argv; only explicit harmless audit-literal declarations are masked. - -Pull-request workflows use GitHub-hosted runners and receive no private -build/sign credentials. If contamination is suspected, stop publication and -report it privately under [SECURITY.md](SECURITY.md); do not copy the suspected -material into a public issue or pull request. +### Codex CLI/app ```text -python3 scripts/check-public-export-safety.py --active-tree --history +codex plugin marketplace add sumitake/agent-collab +codex plugin add agent-collab@agent-collab ``` -## CI and security - -Comprehensive CI runs the full repository and script suites on Python 3.10, -3.12, and 3.14. A separate repository-contract job checks generated skills and -marketplaces, changelog and release consistency, policy-archive construction, -checksum/SPDX evidence, JSON, workflow syntax, public-export safety, secrets, -and whitespace. Existing specialized governance and release gates remain -independently visible. +Start a new Codex task, then invoke `agent-collab:migration-doctor` and +`agent-collab:agent-runtime-status`. -All pull-request code runs on GitHub-hosted runners without private build or -signing credentials. Every third-party GitHub Action uses a full commit SHA pin; -Dependabot proposes reviewed updates to those pins. +Claude Code and Codex have native package manifests in this repository. Other +hosts need a compatible plugin manager and must preserve the same single-package +boundary; otherwise they are unsupported. -Security scanning is layered: +For verification, updates, safe mode, troubleshooting, rollback, and removal, +use the complete [Lifecycle and operations guide](docs/architecture/lifecycle-and-operations.md). -- CodeQL analyzes Python with the `security-extended` query suite on pull - requests, `main`, a weekly schedule, and manual dispatch. -- The dependency-free local scanner fails closed on high-confidence credential - patterns in tracked and non-ignored untracked bytes. -- Gitleaks scans complete repository history on pull requests, `main`, a weekly - schedule, and manual dispatch. -- GitHub native secret scanning and push protection provide server-side - detection before and after a push. +## Migration from retired packages -Branch protection requires current CI, CodeQL, secret-scan, and governance -results. Sensitive workflow, security, legal, and instruction surfaces have -explicit CODEOWNERS coverage. Repository settings allow squash merges only, -delete merged branches, require signed commits and linear history, keep the -default workflow token read-only, and require third-party Actions to be pinned -to full commit SHAs. +The old standalone generation maps into the unified package: -## Development and release verification - -Run the deterministic gates before a release candidate: +- `codex-tools →` managed Codex backend in `agent-collab`; +- `glm-worker →` managed OpenCode backend in `agent-collab`; and +- host-specific collaboration packages → dynamic host profiles in + `agent-collab`. + +Routing stays blocked while an active or installed retired package remains or +provider-free native readiness is unproven. Cached-but-unselected residue is +reported separately. Safe mode is the rollback boundary; reinstalling a +retired package is not. + +See [Unified agent-collab migration](docs/migration-from-legacy-packages.md). + +## Documentation + +| Document | Audience | +| --- | --- | +| [Architecture handbook](docs/architecture/README.md) | Users, contributors, reviewers, and maintainers who need the whole system map. | +| [Lifecycle and operations](docs/architecture/lifecycle-and-operations.md) | Users installing, verifying, updating, troubleshooting, rolling back, or removing the package. | +| [Capabilities and workflows](docs/architecture/capabilities-and-workflows.md) | Users choosing the right skill or collaboration shape. | +| [Governance and authority](docs/architecture/governance-and-authority.md) | Reviewers and maintainers evaluating independence and permissions. | +| [Repository and release architecture](docs/architecture/repository-and-release.md) | Contributors and release maintainers. | +| [Package technical reference](plugins/agent-collab/README.md) | Maintainers integrating the closed coordinator/runtime contract. | +| [Public repository governance](docs/public-governance.md) | Contributors and merge reviewers. | +| [Security policy](SECURITY.md) | Private vulnerability reporting. | +| [Design and review evidence](docs/design/README.md) | Maintainers researching design history without treating it as current by default. | +| [Third-party skill provenance](docs/third-party-skill-provenance.md) | License and provenance reviewers. | + +## Security and public boundary + +Every active path, locally reachable ref, and release archive must stay free of +provider executor source, raw provider invocation recipes, private absolute +paths, credentials, retired package trees, and unreviewed native artifacts. +Suspected exposure is reported privately under [SECURITY.md](SECURITY.md); +scanner output must not be pasted into a public issue or pull request. + +Security checks include: + +- CodeQL with the `security-extended` query suite; +- a dependency-free tracked/untracked credential scanner; +- Gitleaks across repository history; +- GitHub native secret scanning and push protection; +- full commit SHA pins for third-party GitHub Actions; and +- reviewed Dependabot updates for those pins. + +Pull-request jobs use GitHub-hosted runners without private build/sign +credentials. Current repository rules require a pull request, required checks, +signed commits, linear history, and resolved review threads. See +[Governance and authority](docs/architecture/governance-and-authority.md) for +the hosting-platform bypass caveat and no-admin-bypass merge rule. + +## Contributing and validation + +Read [`AGENTS.md`](AGENTS.md) and +[`docs/public-governance.md`](docs/public-governance.md) before changing the +repository. Edit `skill-specs/`, not generated skill copies, and commit one +unique `changelog.d/` fragment for a user-visible change. Do not commit a +feature-branch compilation of `CHANGELOG.md`. + +Required local validation: ```text python3 scripts/build_skills.py --check python3 scripts/build_marketplace.py --check -python3 scripts/build-changelog.py --check +python3 scripts/build-changelog.py --dry-run python3 -m unittest discover -s tests -t . -v python3 -m unittest discover -s scripts -p 'test_*.py' -v python3 scripts/check_release_consistency.py -python3 scripts/build_plugin_archive.py --output /tmp/agent-collab.plugin python3 scripts/secret_scan.py python3 scripts/check-public-export-safety.py --active-tree git diff --check ``` -The archive builder classifies and verifies either the current policy-only -package or an activation package. For an activation candidate, also run -`python3 scripts/verify_runtime_release.py --git-sha "$(git rev-parse HEAD)"` -on Darwin arm64; that verifier intentionally remains activation-only and fails -closed against an empty manifest. - -Activation packaging also requires the exact digest-pinned -`THIRD-PARTY-NOTICES.txt` and `third-party-licenses/` tree. Missing, extra, -linked, hardlinked, unsafe, or modified legal members fail before archive or -SBOM publication. Policy-only archives intentionally omit that tree. - -`CHANGELOG.md` remains generated at release time from `changelog.d/` fragments. -Historical changelog entries may name retired packages only as clearly -historical records; they are not active install or rollback instructions. -Release tags must be signed annotated tags whose target is the checked-out -commit on `origin/main`; the release workflow verifies the GitHub tag signature -and main ancestry before accepting macOS runtime evidence or building archives. -Activation runtime evidence also binds inspection of a thin arm64 Mach-O with -exactly one macOS `LC_BUILD_VERSION` declaring minimum macOS 14.0; manifest -labels alone do not establish architecture or deployment target. In policy-only -mode, the archive builder requires an empty artifact list and proves that no -runtime path is packaged; the activation-only verifier is not run. -Release consistency additionally requires the Claude and Codex plugin -manifests to have the same name/version and the generated Codex marketplace to -contain exactly the one local unified package. +Release preparation adds deterministic archive/evidence, secret, history, tag, +and—for activation—Darwin arm64 signature/notarization verification. The +complete lifecycle is documented in +[Repository and release architecture](docs/architecture/repository-and-release.md). ## License -The public repository and distributed package use the unmodified -[PolyForm Strict License 1.0.0](LICENSE). This is a source-available license, -not an open-source grant: it permits the uses described in the license and does -not permit redistribution, changes, derivative works, or commercial use. - -Copyright is owned by John Osumi. Commercial use requires separate, explicit -written approval administered by Osumi Consulting LLC. Repository access, -installation, GitHub activity, and an accepted contribution do not constitute -approval. See [NOTICE](NOTICE) and -[COMMERCIAL-LICENSING.md](COMMERCIAL-LICENSING.md) for the exact ownership and -approval boundary. - -An activation archive also redistributes CPython 3.13.14, Nuitka 4.1.3 runtime -material, and their incorporated components under their own terms. The exact, -digest-pinned inventory is shipped as `THIRD-PARTY-NOTICES.txt` and -`third-party-licenses/` inside the plugin package. Those files are excluded from -policy-only archives because no native runtime is present. - -The `decision-map`, `prototype`, and `architecture-review` skills contain -material derived from the MIT-licensed -[mattpocock/skills](https://github.com/mattpocock/skills) repository -(Copyright (c) 2026 Matt Pocock). Those portions are and remain MIT-licensed -in every archive; each derived `SKILL.md` carries the full MIT permission -notice, and [docs/third-party-skill-provenance.md](docs/third-party-skill-provenance.md) -records the pinned upstream commit and per-file provenance. +The repository and package use the unmodified +[PolyForm Strict License 1.0.0](LICENSE), except for identified MIT-derived +skill portions that retain their MIT terms. This is source-available software, +not an open-source grant. Commercial use requires separate explicit written +approval administered by Osumi Consulting LLC. See [NOTICE](NOTICE), +[COMMERCIAL-LICENSING.md](COMMERCIAL-LICENSING.md), and +[third-party provenance](docs/third-party-skill-provenance.md). diff --git a/changelog.d/2026-08-06-public-architecture-handbook.md b/changelog.d/2026-08-06-public-architecture-handbook.md new file mode 100644 index 0000000..d2acbc0 --- /dev/null +++ b/changelog.d/2026-08-06-public-architecture-handbook.md @@ -0,0 +1,15 @@ +### Changed + +- agent-collab 4.9.1 adds a sanitized, indexed public architecture handbook + covering system context, capabilities, governance and authority, lifecycle + operations, repository/release architecture, and lifecycle-state evidence. +- Refocus the root README on general users and link maintainers to the existing + low-level package reference instead of duplicating its protocol detail. + +### Fixed + +- Correct stale public statements about the package version, committed + activation artifact, reviewed signing anchor, and current runtime-manifest + schema while removing private-producer provenance from active documentation. +- Add a design-evidence registry so cited design-of-record sections, + superseded drafts, and historical adversarial reviews are not conflated. diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000..bd7da34 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,108 @@ +# agent-collab architecture handbook + +This handbook explains the public architecture of `agent-collab` for users, +contributors, reviewers, and release maintainers. It describes stable +boundaries and public contracts. It does not reproduce private runtime +implementation, build credentials, operator-specific paths, or machine state. + +The handbook is descriptive. Source, tests, manifests, release evidence, and +the contribution contract remain authoritative for their respective claims. +When two generations differ, use the status vocabulary below instead of +silently treating them as the same thing. + +## Read this handbook in order + +1. [System context](system-context.md) explains what the project is, what it is + not, its actors, and its public/private boundary. +2. [Capabilities and workflows](capabilities-and-workflows.md) maps the skill + surface to common user jobs and explains availability limits. +3. [Governance and authority](governance-and-authority.md) explains family + independence, sealed authority, review evidence, and operator control. +4. [Lifecycle and operations](lifecycle-and-operations.md) covers installation, + verification, use, updates, troubleshooting, safe mode, rollback, and + removal. +5. [Repository and release architecture](repository-and-release.md) maps the + public package, generated sources, validation, and release flow. +6. [Status and evidence](status-and-evidence.md) defines the binding lifecycle + labels and records the dated evidence snapshot used by this documentation. + +Historical and design material is indexed separately in +[`docs/design/README.md`](../design/README.md). It is not automatically the +current runtime contract. + +## Status vocabulary + +| Label | Meaning | Appropriate evidence | +| --- | --- | --- | +| **current** | The behavior or contract is present in the checked-out public repository baseline and covered by current source, manifests, or tests. | Merged source plus focused tests or generated-manifest checks. | +| **repository-only** | The implementation or artifact exists in the repository, but no cited release and host observation proves it is installed and selected. | Repository source or artifact identity only. | +| **staged** | Material is prepared for a later compilation, publication, activation, or selection step. | A changelog fragment, candidate artifact, tag input, or generated release input. | +| **installed/active** | A specific version has been positively observed as installed, selected, and ready on a specific host. | Host package inventory plus provider-free readiness evidence. | +| **proposed** | A design or change has not become the current merged contract. | Draft, branch, issue, or unmerged design. | +| **historical** | Retained evidence explains earlier decisions but does not define current behavior. | Changelog, superseded design, or past review record. | +| **retired** | The public source explicitly removes or blocks the old surface. | Migration policy, absence tests, and clean-package checks. | + +These labels are deliberately narrower than words such as “released” or +“available.” A manifest can advertise a route while a host still reports it +unavailable. A tag can exist without a GitHub release. A repository version can +be newer than both. See [Status and evidence](status-and-evidence.md). + +## Architectural invariants + +The public repository and package preserve these invariants: + +1. There is one installable package, `agent-collab`, not one plugin per host or + provider. +2. Callers select a skill or logical collaboration job. They do not receive a + raw provider-execution escape hatch. +3. Governance review requires a model family independent of the active primary + and the reviewed artifact's known author family. +4. Route authorities are closed. Read-only, output-only, and unavailable + actions do not promote themselves because another route failed. +5. Provider output is an artifact for the trusted primary to inspect. It does + not merge, deploy, or change policy by returning successfully. +6. Native execution is optional at the package level and fail-closed. A listed + skill or advertised contract does not prove current host readiness. +7. The public package may contain only the final reviewed native bundle and + closed manifest metadata. Native implementation and build/sign credentials + remain outside this repository. +8. Retired packages are migration evidence, not rollback targets. + +## Sanitization contract + +Architecture documentation is public only when it records portable boundaries +rather than one operator's environment. These pages therefore: + +- use repository-relative paths and generic roles; +- omit personal account names, host names, network details, tokens, + credentials, local cache paths, and private repository locations; +- describe managed provider roles without publishing raw provider invocation + recipes or discovery commands; +- distinguish public artifact-verification requirements from the private + systems that produce those artifacts; and +- label uncertainty instead of inferring installed or active state. + +Do not add copied diagnostic output, private build identifiers, notarization +submission identifiers, environment dumps, or secret-bearing examples to this +handbook. Suspected exposure follows [the security policy](../../SECURITY.md), +not a public issue or pull request. + +## Source map + +| Question | Start here | Authoritative public evidence | +| --- | --- | --- | +| What does the package install? | [System context](system-context.md) | Host manifests, generated marketplaces, package tree, and distribution tests. | +| Which workflows exist? | [Capabilities and workflows](capabilities-and-workflows.md) | `skill-specs/`, generated skills, package reference, and skill-contract tests. | +| Who may review, write, or merge? | [Governance and authority](governance-and-authority.md) | Host policy, coordinator, public governance contract, PR template, and compliance checks. | +| Is a route usable now? | [Status and evidence](status-and-evidence.md) | Installed version plus provider-free readiness on that host. Repository presence alone is insufficient. | +| How do I install or recover? | [Lifecycle and operations](lifecycle-and-operations.md) | Current host CLI, migration doctor, runtime-management surface, and migration policy. | +| How is a release produced? | [Repository and release architecture](repository-and-release.md) | Release scripts, workflows, signed-tag contract, archive checks, and release evidence. | + +## Maintenance rule + +Update the relevant architecture page in the same change when a public +component, authority boundary, host surface, route contract, lifecycle state, +or release boundary changes. Keep each claim tied to repository-relative source +and focused evidence. If delivery evidence lags source, keep both observations +and label them; do not “fix” the discrepancy by declaring one generation +active everywhere. diff --git a/docs/architecture/capabilities-and-workflows.md b/docs/architecture/capabilities-and-workflows.md new file mode 100644 index 0000000..caf60e3 --- /dev/null +++ b/docs/architecture/capabilities-and-workflows.md @@ -0,0 +1,148 @@ +# Capabilities and workflows + +< [Architecture handbook index](README.md) + +The unified package exposes 50 generated skills under the +`agent-collab` namespace. A skill is a workflow contract: it defines when to +use the capability, what evidence to gather, which authority is acceptable, +and when to stop. It is not a promise that every managed route is currently +available on every host. + +The definitive low-level inventory remains the +[package reference](../../plugins/agent-collab/README.md#skills); this page +organizes that inventory by user outcome. + +## Capability map + +| User job | Skills | Typical outcome | +| --- | --- | --- | +| Identity, routing, and readiness | `agent-readiness`, `agent-runtime-status`, `migration-doctor`, `route`, `start-inbox-monitor`, `teamwork` | Establish which host, family, route, or async target is eligible before relying on it. | +| Planning and architecture | `architect`, `brainstorm`, `compose-skills`, `intent-check`, `second-opinion` | Clarify a design, widen options, select workflows, or obtain an independent read. | +| Governance and assurance | `autonomy-readiness`, `code-review`, `governance-review`, `logic-check`, `qa-verify`, `red-team`, `untrusted-audit` | Test correctness, independence, security, provenance, and completion evidence. | +| Deliberation and stakeholder lenses | `debate`, `simulate-user` | Expose conflicting arguments or test a proposal against a persona. | +| Delegation and implementation | `delegate`, `dev-delegate`, `worker` | Return bounded research or output for the primary to integrate. | +| Large-context and knowledge work | `knowledge-compile`, `long-context` | Extract or synthesize a bounded corpus with explicit provenance. | +| Reproducible workflows | `chain`, `chain-configurator`, `orchestrate` | Define and execute repeatable multi-step coordination. | +| Integration and conflict handling | `merge-resolve` | Analyze and resolve a bounded merge conflict while preserving intent. | +| Visual guidance | `ui-to-code`, `visual-review` | Guide primary-only visual work when typed image transport is absent; never invent a managed attachment path. | +| Language expertise | `rust-engineer`, `go-engineer`, `elixir-engineer`, `sql-engineer` | Apply domain-specific engineering practices. | +| Infrastructure and reliability | `kubernetes-specialist`, `terraform-engineer`, `sre-engineer`, `incident-responder` | Design, review, or troubleshoot operational systems. | +| Data and AI | `mlops-engineer`, `llm-architect`, `postgres-engineer`, `data-engineer` | Apply data, model, database, and pipeline expertise. | +| Evaluation and writing quality | `eval-engineer`, `prompt-regression-tester`, `hallucination-investigator`, `ai-writing-auditor` | Evaluate model-backed behavior, prompt drift, factual failure, or prose quality. | +| Engineering process | `decision-map`, `prototype`, `architecture-review` | Create decision tickets, answer one design question with a throwaway prototype, or sweep module boundaries. | + +## Execution shapes + +### Managed synchronous routes + +Routed review, context, planning, governance, and worker workflows submit a +bounded request through the installed package's public coordinator. Policy +selects an eligible managed route and preserves one of the authorities defined +in [Governance and authority](governance-and-authority.md). + +Current repository route contracts cover: + +- Gemini advisory, governance, and long-context work; +- Codex advisory and governance work; +- OpenCode planning and output-only build work; +- Grok read-only architecture, governance, and huge-context work; and +- Composer-compatible output-only code generation. + +Codex build is recognized but typed unavailable in this repository generation. +The route list is a **current repository contract**, not installed/active +evidence. Readiness is resolved immediately before use. + +### Primary-executed workflows + +Some skills guide the active primary directly rather than selecting a managed +provider. The engineering-process pack is explicitly self-executed. Visual +skills also remain primary-only where the current protocol has no typed image +or binary-media transport. These workflows can still require local tools, +tests, or user approval; “primary-executed” is not “unchecked.” + +### Async coordination + +Claude and Antigravity participation can use host-owned asynchronous inbox +transport after the exact target identity, family, session, and current +readiness are observed. The public coordinator exposes readiness only. It does +not send, does not create a synchronous Claude route, and does not treat an +async reply as independent governance merely because it arrived. + +### Reproducible composition + +- `chain` executes a versioned YAML-defined sequence of skill invocations. +- `chain-configurator` helps create a chain definition interactively. +- `orchestrate` coordinates a dependency graph with bounded tasks and explicit + gates. +- `teamwork` coordinates role-based milestones and stop conditions. + +Composition does not erase the authority of individual steps. A read-only +review inside a chain remains read-only, and a worker artifact still returns to +the primary for integration. + +## Common workflows + +### Independent review + +1. Identify the exact artifact and its author lineage. +2. Invoke `second-opinion`, `code-review`, `governance-review`, `red-team`, or + `qa-verify` according to the risk. +3. Policy excludes the primary and artifact-author families where independence + is required. +4. Preserve the raw finding and typed status. +5. The primary adjudicates, changes the artifact if needed, and re-verifies the + exact head. + +### Bounded delegation + +1. The primary keeps objective interpretation and integration ownership. +2. A worker receives a bounded scope, authority, evidence contract, and stop + condition. +3. Read-heavy work can use a cheaper capable tier; judgment and landing stay + with the primary. +4. Output-only code is returned as an artifact from a private temporary + workspace; it is not written into the caller's checkout. +5. The primary reviews and tests all delegated output before it becomes source. + +### Architecture and planning + +Use `brainstorm` to widen the option space, `architect` for an independent +read-only architecture consultation, `architecture-review` for a primary-led +codebase sweep, `intent-check` to validate task interpretation, and +`decision-map` when the effort is too large for one session. + +### Large-context work + +Use `knowledge-compile` when multiple sources must become a durable cited +dossier. Use `long-context` when a managed large-context route is needed. The +input remains bounded and source-specific; long-context transport does not +grant governance or mutation authority. + +## Host and package support + +| Surface | Public package evidence | User expectation | +| --- | --- | --- | +| Claude Code | Claude-compatible plugin manifest and marketplace metadata. | Native package install and `/agent-collab:*` skills. Claude model participation remains async-only. | +| Codex CLI/app | Codex-native manifest and generated Codex marketplace. | Native package install and the same skill namespace. Start a new task after install/update. | +| Antigravity | Dynamic host policy and async target model; no separate package. | Use only through a compatible package host and observed async readiness. | +| OpenCode and ZCode | Dynamic host/model policy and managed OpenCode routes; no separate package. | A compatible host/plugin surface is required. OpenCode is a transport; the selected model supplies family lineage. | +| Custom host | Explicit primary identity fields and the closed package contract. | If the host cannot load the package safely, it is unsupported; do not recreate provider-specific shims. | + +## Availability rules + +A capability is usable only when all applicable gates pass: + +- the unified package is installed and selected; +- no active retired package blocks migration; +- primary identity is complete enough for the requested authority; +- the requested family is eligible and independent where required; +- the manifest advertises the exact route/action contract; +- the native boundary and provider-free readiness checks pass; and +- provider authentication, quota, and request execution succeed. + +Failing one gate produces a typed result such as `unavailable`, +`same_family_blocked`, `unknown_family`, or a runtime error category. Do not +turn that result into a raw-provider fallback or broader authority. + +For installation and recovery, continue to +[Lifecycle and operations](lifecycle-and-operations.md). diff --git a/docs/architecture/governance-and-authority.md b/docs/architecture/governance-and-authority.md new file mode 100644 index 0000000..5598b5e --- /dev/null +++ b/docs/architecture/governance-and-authority.md @@ -0,0 +1,142 @@ +# Governance and authority + +< [Architecture handbook index](README.md) + +`agent-collab` separates authorship, independent review, execution authority, +and landing authority. This matters because a model is least reliable at +finding the blind spots shared by its own family, and because a successful +tool call is not evidence that the caller should receive broader permissions. + +## Independence model + +For governance-grade review, the public policy requires a complete, +trustworthy primary identity and known artifact-author lineage. It excludes +both of these families from eligible reviewer selection: + +1. the active primary's model family; and +2. the reviewed artifact author's model family. + +If either family is unknown, governance fails closed. Non-governance work may +continue only where the contract permits it and carries an independence +warning. OpenCode is a host/runtime surface, not a model family; the selected +model's lineage supplies family provenance. + +```mermaid +flowchart LR + Artifact["Artifact plus author lineage"] --> Eligibility["Eligibility policy"] + Primary["Active primary lineage"] --> Eligibility + Eligibility --> Exclude["Exclude primary and author families"] + Exclude --> Reviewer["Eligible independent reviewer"] + Reviewer --> Evidence["Review artifact or governance verdict"] + Evidence --> PrimaryGate["Primary integration and repository gates"] +``` + +The diagram does not make reviewer output self-authenticating. Repository +automation validates declared evidence form; the primary, reviewers, and +operator remain responsible for its substance. + +## Authority classes + +The current repository policy uses closed route/action pairs with explicit +authorities: + +| Authority | Meaning | Examples in the current public contract | +| --- | --- | --- | +| **read-only** | May inspect bounded input and return analysis, review, plans, or context. | Gemini advisory/governance/long-context, Codex advisory/governance, OpenCode plan, Grok architecture/governance/huge-context. | +| **output-only** | May work in a private temporary workspace and return a patch or code artifact for the primary to inspect and apply. | OpenCode build and Composer code generation. | +| **unavailable** | The contract name is recognized but no hardened backend currently satisfies it. | Codex build in this repository generation. | +| **primary-executed** | The active primary follows the skill locally; no independent managed route is implied. | Self-executed engineering-process skills and primary-only visual guidance where typed media transport is absent. | +| **async readiness** | Reports whether a host-owned async target is currently addressable. | Explicit Claude or Antigravity target/session readiness. The public coordinator never sends. | + +No failure converts one row to another. In particular: + +- an advisory route cannot become a worker because another worker is + unavailable; +- output-only code cannot write the caller's checkout; +- a governance call cannot accept an unknown primary or artifact family; +- an explicit target is not silently replaced by a different provider; and +- a successful result does not gain merge, deployment, release, or policy + authority. + +## Role boundaries + +| Role | Owns | Must not own | +| --- | --- | --- | +| User/operator | Objective, hard constraints, reserved paths, release/activation policy, and final human decisions. | Routine implementation detail that policy already delegates safely. | +| Primary | Intent interpretation, architecture synthesis, integration, tests, conflict resolution, and in-scope landing decisions. | Independent review of its own family or authority beyond the user and repository contract. | +| Reviewer | Counter-arguments, defects, risks, and an evidence-bound verdict. | Editing the reviewed branch, merging, or silently changing scope. | +| Worker | A bounded research or implementation artifact under a declared authority. | Architecture/governance decisions, secret handling, merge/deploy, or caller-workspace write access unless explicitly provided by a future contract. | +| Repository automation | Deterministic checks for trace form, tests, generated state, security, and release consistency. | Judgment that a review was genuine or a change is desirable. | + +## Repository change tiers + +The self-contained public contribution contract defines three tiers: + +- **Tier 1:** documentation, comments, or cosmetic metadata with no executable, + policy, security, packaging, or release effect. A reasoned `N/A` independent + cross-check is permitted. +- **Tier 2:** user-visible behavior, skills, tests, ordinary CI, dependencies, + or compatible policy changes. Independent cross-family review is required. +- **Tier 3:** routing authority, family independence, provenance, sandboxing, + authentication, signing, runtime verification, release supply chain, or + governance gates. Independent cross-family review is required, and + operator-reserved paths require operator merge. + +The authoritative definitions and PR fields live in +[`docs/public-governance.md`](../public-governance.md). + +## Compliance trace: what it proves + +Every pull request records one compliance trace with eight required fields. +Local and CI checks validate its shape, tier rules, recognized cross-check +state, and reserved-path handling. A Tier 2 or Tier 3 pull request is not +merge-eligible on a bare `N/A`; it requires a converged `PROCEED` record. + +The trace proves that required evidence was recorded in the expected form. It +does **not** cryptographically prove that quoted review prose came from the +claimed reviewer. This is an intentional, documented residual boundary: + +- coordinator policy enforces family independence when it selects a managed + route; +- repository automation validates trace form and presence; and +- the primary, independent reviewer, and operator validate substance and exact + head before merge. + +## Merge and release authority + +Current repository settings require a pull request, signed commits, linear +history, required status checks, and resolved review threads; squash is the +allowed merge method. Administrative identities retain a pull-request bypass +capability at the hosting layer, so “no admin bypass” is a governance rule that +must be observed and audited, not a claim that the platform makes bypass +impossible. + +Before merge: + +1. review the exact head, not an earlier commit; +2. run the local compliance check against the pull request; +3. require all current status checks to pass; +4. resolve every actionable review thread; +5. honor CODEOWNERS and operator-reserved decisions; and +6. merge normally without an administrative bypass. + +Release authority remains separate from merge authority. A merged version and +fragment are staged inputs until the signed-tag and release workflow completes +and its evidence is verified. + +## Why these controls matter + +- **Different failure modes:** independent model families are more likely to + expose correlated assumptions than another instance of the author's family. +- **Least authority:** a route receives only the permission its work requires, + reducing the cost of a hallucination or prompt-injection failure. +- **Honest evidence:** typed unavailable and unknown-family results preserve + uncertainty instead of inventing success. +- **Separation of duties:** authoring, reviewing, integrating, merging, and + releasing remain distinct accountable acts. +- **Recoverability:** safe mode and retained verified state stop execution + without reviving retired packages or bypassing migration checks. + +For operational application of these rules, continue to +[Lifecycle and operations](lifecycle-and-operations.md). For the public PR +contract, read [`docs/public-governance.md`](../public-governance.md). diff --git a/docs/architecture/lifecycle-and-operations.md b/docs/architecture/lifecycle-and-operations.md new file mode 100644 index 0000000..8cb59f7 --- /dev/null +++ b/docs/architecture/lifecycle-and-operations.md @@ -0,0 +1,253 @@ +# Lifecycle and operations + +< [Architecture handbook index](README.md) + +This guide covers the public user lifecycle. It uses portable placeholders and +host-supported plugin commands; it does not expose operator-specific paths or +private provider invocation details. + +## Before installing + +Confirm these boundaries: + +- The repository is source-available under PolyForm Strict. Installation does + not grant redistribution, derivative-work, or commercial-use rights. +- The package currently ships native host manifests for Claude Code and Codex. + Other hosts need a compatible plugin surface; do not recreate a retired + host- or provider-specific shim. +- Managed native execution currently targets the platform described by the + selected release manifest. Skills and migration can still be present when a + native route is unavailable. +- Supported provider CLIs and authentication remain external prerequisites. + Install and authenticate them only through vendor-supported interfaces. + +## Install + +### Claude Code + +From Claude Code: + +```text +/plugin marketplace add sumitake/agent-collab +/plugin install agent-collab@agent-collab +``` + +Start a new session, then run: + +```text +/agent-collab:migration-doctor +``` + +### Codex CLI/app + +From a terminal with Codex installed: + +```text +codex plugin marketplace add sumitake/agent-collab +codex plugin add agent-collab@agent-collab +``` + +Start a new Codex task, then invoke the `agent-collab:migration-doctor` skill. +The repository tests pin `codex plugin add`; `codex plugin install` is not the +current command. + +### Other hosts + +Use the same single package only if the host has a compatible, supported +plugin manager. If it cannot load the package and preserve the closed request +boundary, treat it as unsupported. Do not copy skills into a provider-specific +package or rebuild a raw provider route. + +## Verify + +Installation, selection, and readiness are separate checks. + +1. **Package inventory:** confirm the host reports + `agent-collab@agent-collab` and the expected version. +2. **Fresh load:** start a new session/task; a running session can retain the + previously loaded plugin. +3. **Migration doctor:** remove every active or installed retired package it + reports, then run the doctor again. +4. **Runtime status:** invoke `agent-runtime-status` for a provider-free typed + snapshot. A listed route is not proof of readiness. +5. **Bounded smoke test:** invoke one low-risk read-only workflow, such as a + second opinion on a short draft, and verify the returned family is eligible + and independent. + +For an activation package, the closed management client can report status +without invoking a provider: + +```text +python3 "/runtime_setup.py" status +python3 "/runtime_setup.py" broker-status +``` + +Use the exact installed plugin root supplied by the host or migration doctor. +Do not search for provider executables, substitute a binary, or add path/model +overrides. Policy-only packages return typed unavailable for native lifecycle +operations. + +## Use + +Invoke the skills in normal language or by their host command. Examples: + +```text +/agent-collab:second-opinion Review this architecture decision. +/agent-collab:code-review Review the current diff against the task. +/agent-collab:qa-verify Verify the completed work against these acceptance criteria. +/agent-collab:delegate Split this read-only research list with an independent reviewer. +/agent-collab:agent-runtime-status +``` + +The primary should always: + +- provide bounded context and an explicit expected output; +- treat delegated output as untrusted until reviewed; +- preserve the returned typed status and provenance; +- run local tests before claiming completion; and +- keep merge, deployment, secret, and destructive decisions within the user's + and repository's authority boundaries. + +## Update + +### Claude Code + +Refresh the marketplace, update the package, then restart Claude Code: + +```text +claude plugin marketplace update agent-collab +claude plugin update agent-collab@agent-collab +``` + +After restart, verify the reported version and re-run +`/agent-collab:migration-doctor`. Reloading an already-running session is not a +substitute for applying a pending package version. + +### Codex CLI/app + +Refresh the configured Git marketplace and start a new task: + +```text +codex plugin marketplace upgrade agent-collab +codex plugin list --json +``` + +Read only the `agent-collab@agent-collab` version from local inventory; avoid +publishing the full output because host inventories can include local paths. If +the refreshed snapshot is not installed, use the current remove/add commands: + +```text +codex plugin remove agent-collab@agent-collab --json +codex plugin add agent-collab@agent-collab --json +``` + +Then start a new task and re-run migration doctor and runtime status. + +### Native lifecycle during package update + +Package refresh, import, readiness, and route invocation do not silently +install or mutate native lifecycle state. An activation update uses the closed +candidate/proof/commit lifecycle implemented by the package. A candidate is +not a normal routing target, and a previous verified lane is retained until the +new lane is committed and separately drained. + +General users should follow the selected release's management output rather +than reconstructing lifecycle commands or paths. A failed update must leave the +previous verified state selected or return a typed lifecycle error. + +## Troubleshoot + +| Symptom or status | Meaning | Safe response | +| --- | --- | --- | +| Skill is missing | The package may not be installed, enabled, or loaded in this session. | Check host plugin inventory, then start a new session/task. | +| `duplicate_blocked` or migration conflict | A retired package remains active or installed. | Run migration doctor, apply only its host-specific removal actions, and run it again. | +| `unavailable` | The route, runtime, provider prerequisite, or observed readiness is not currently usable. | Run runtime status and migration doctor; check supported vendor authentication separately. Do not use a raw-provider fallback. | +| `same_family_blocked` | The requested reviewer/worker is not independent from the primary or artifact author. | Select an eligible different family or treat the review as non-independent. | +| `unknown_family` | Current identity or artifact lineage cannot establish governance independence. | Correct the supported host identity signals; do not guess from a model nickname or installation path. | +| `config_error` | Request fields, host identity, or route/action pairing violate the closed schema. | Use the installed skill/package reference; remove unsupported fields rather than widening the schema. | +| `auth_error` or `quota_error` | The managed provider prerequisite failed after routing. | Use the provider's supported login/account interface or wait for quota. Keep the same authority. | +| Output-only worker made no caller-worktree changes | Expected behavior. | Review the returned artifact and apply it through the trusted primary if appropriate. | +| Governance call refuses partial identity | Expected fail-closed behavior. | Establish all required current-session identity fields or use a non-governance workflow with its warning. | +| Safe mode keeps native routes unavailable | Execution is intentionally disabled. | Finish migration and verification, unset safe mode, restart, and re-check readiness. | +| Version in a running session is stale | The host loaded an earlier package snapshot. | Finish the marketplace/package update and start a genuinely new session/task. | + +Preserve typed errors. Do not infer failure from response prose, retry a +terminal cleanup/teardown error, or substitute a different provider behind an +explicit target. + +## Safe mode and rollback + +The normal operational rollback is policy-only safe mode: + +1. Set `AGENT_COLLAB_SAFE_MODE=1` in the active host environment. +2. Restart the host. +3. Confirm native model routes return typed unavailable. +4. Run migration and package checks while execution is disabled. +5. Unset safe mode and restart only after the selected state is verified. + +Safe mode does not reinstall an older or retired package. It preserves the +public policy boundary while stopping model execution. + +If an activation installation has one complete prior verified broker record, +the closed management client also exposes: + +```text +python3 "/runtime_setup.py" rollback-broker +``` + +That action selects only the verified prior record. It is typed unavailable +when no valid rollback target exists. It is not a general package-version pin, +and it accepts no caller-selected path, socket, provider, model, or binary. + +Published release rollback is a release-governance decision. Do not delete and +reuse a published version, detach a shared marketplace clone, or reinstall a +retired package. Prefer a signed revocation where required and a higher patch +release. + +## Remove + +Remove active lifecycle state before removing an activation package, because +the package contains the only supported management client: + +```text +python3 "/runtime_setup.py" uninstall-broker +``` + +The command is idempotent when no broker is installed. It removes the exact +active job, socket, configuration, and mutable state while intentionally +retaining immutable version records used for audit/rollback evidence. + +Then remove the package. + +Claude Code: + +```text +claude plugin uninstall -s user -y agent-collab@agent-collab +``` + +Codex: + +```text +codex plugin remove agent-collab@agent-collab --json +``` + +If the `agent-collab` marketplace is no longer needed, remove it through that +host's marketplace command. Start a new session/task and confirm the skills are +absent. Package removal does not authorize manual deletion of unknown host +paths or credential state. + +## Legacy migration + +Retired standalone packages map into the unified package: + +- `codex-tools →` managed Codex backend in `agent-collab`; +- `glm-worker →` managed OpenCode backend in `agent-collab`; and +- host-specific collaboration packages → dynamic host profiles in + `agent-collab`. + +The exhaustive namespace mapping and cleanup rules live in +[`docs/migration-from-legacy-packages.md`](../migration-from-legacy-packages.md). +Treat names in that document as historical/migration evidence, not active +installation instructions. + +For evidence-plane distinctions, read [Status and evidence](status-and-evidence.md). diff --git a/docs/architecture/repository-and-release.md b/docs/architecture/repository-and-release.md new file mode 100644 index 0000000..a8651d2 --- /dev/null +++ b/docs/architecture/repository-and-release.md @@ -0,0 +1,163 @@ +# Repository and release architecture + +< [Architecture handbook index](README.md) + +This repository publishes one package, `plugins/agent-collab`. It is the public +source of truth for skills, policy, client behavior, migration, governance, and +release-safety checks. The native producer is a separate private trust domain; +contributors do not need access to it. + +## Repository map + +| Path | Status | Responsibility | Edit rule | +| --- | --- | --- | --- | +| `skill-specs/` | current | Editable source for collaboration skills. | Edit here; do not hand-edit generated copies. | +| `plugins/agent-collab/skills/` | generated/current | Host-readable installed skill contracts. | Regenerate with `scripts/build_skills.py`. | +| `plugins/agent-collab/` public Python modules | current | Coordinator, identity/authority policy, migration, runtime verification/management, and signing policy. | Keep the public module inventory closed. | +| `plugins/agent-collab/.claude-plugin/` and `.codex-plugin/` | current | Host manifests for the same name and version. | Update together. | +| `.claude-plugin/` and `.agents/plugins/` | generated/current | Claude-compatible and Codex marketplace views. | Regenerate with `scripts/build_marketplace.py`. | +| `plugins/agent-collab/runtime-manifest.json` | current contract | Closed runtime artifact and route metadata. | Generated/reviewed release input; never use it to infer host activation. | +| `plugins/agent-collab/runtime/` | repository-only when present | Final manifest-listed native bundle. | Only final reviewed signed artifacts may enter. No native source. | +| `docs/architecture/` | current | Public architecture handbook. | Update with boundary or lifecycle changes. | +| `docs/design/` | mixed | Design-of-record and historical review evidence. | Consult the design index and source/tests before treating it as current. | +| `docs/public-governance.md` | current/normative | Contribution and merge contract. | Keep prose and automation aligned. | +| `docs/migration-from-legacy-packages.md` | current | Retirement, cleanup, safe mode, and package migration. | Do not revive retired install surfaces. | +| `changelog.d/` | staged | Per-change release-note fragments. | Commit one unique fragment; do not compile `CHANGELOG.md` on feature branches. | +| `CHANGELOG.md` | generated | Release-time compilation of fragments. | Updated only by the release flow. | +| `scripts/` | current | Build, validation, compliance, archive, evidence, and release tools. | Preserve fail-closed behavior and tests. | +| `tests/` | current | Public behavior, security, distribution, and regression contracts. | Update with every changed contract. | +| `.github/workflows/` | current | CI, security, governance, dependency, and release automation. | Full commit-SHA pins and least-privilege workflow tokens. | + +## Source and generated flow + +```mermaid +flowchart LR + Specs["skill-specs/"] --> SkillBuild["build_skills.py"] + SkillBuild --> Skills["plugins/agent-collab/skills/"] + + Manifest["package manifests"] --> MarketBuild["build_marketplace.py"] + Fragment["marketplace fragment"] --> MarketBuild + Base["marketplace base"] --> MarketBuild + MarketBuild --> ClaudeMarket[".claude-plugin/marketplace.json"] + MarketBuild --> CodexMarket[".agents/plugins/marketplace.json"] + + Change["user-visible change"] --> ChangelogFragment["changelog.d/ fragment"] + ChangelogFragment --> ReleaseCut["governed release cut"] + ReleaseCut --> Changelog["generated CHANGELOG.md"] +``` + +Generated files are checked for freshness in CI. A version change is one +logical update across both host manifests, marketplace metadata, generated +skill versions, package/root README version markers, and the changelog +fragment. + +## Public/private source boundary + +The public repository owns: + +- request and result policy; +- model-family and authority decisions; +- skills and generated host-facing documentation; +- runtime client, manifest schema, migration, and management contracts; +- artifact verification and signing-policy anchors; +- tests, CI, contribution governance, and release checks; and +- final distributable legal evidence. + +The private producer owns: + +- native provider implementation source; +- build credentials and signing keys; +- private build/sign infrastructure; and +- any secret-bearing provider integration material. + +The only permitted crossing is a final signed standalone bundle, its closed +manifest metadata, and required license evidence. Public pull-request CI uses +GitHub-hosted runners without private build/sign credentials. + +## Release modes + +### Policy-only + +A policy-only release has an empty runtime manifest and no native runtime tree +in the archive. Skills, migration, and public policy can install, while all +native model routes remain typed unavailable. The release flow proves the +absence rather than pretending activation evidence exists. + +### Activation + +An activation release contains exactly one supported standalone bundle and a +schema-3/contract-3 manifest in this repository generation. Release checks +bind the bundle, manifest, route matrix, platform, architecture, minimum +operating system, file inventory, digests, signing profile, hardened runtime, +secure timestamp, notarization, legal notices, and source commit. + +Activation evidence establishes the package artifact. Host installation and +readiness remain later evidence planes. + +## Change lifecycle + +```mermaid +flowchart LR + Need["Scoped change"] --> Source["Owning source and tests"] + Source --> Generated["Regenerated package views"] + Generated --> Fragment["Unique changelog fragment"] + Fragment --> Local["Local validation"] + Local --> Review["Independent exact-head review"] + Review --> PR["Governed pull request"] + PR --> Main["Merged source baseline"] + Main --> Tag["Signed annotated tag"] + Tag --> Release["Verified release assets and evidence"] + Release --> Install["Host install/update"] + Install --> Ready["Provider-free readiness"] +``` + +Each arrow needs its own evidence. A merged pull request does not create a tag; +a tag does not create a release; a release does not update a host; installation +does not prove readiness. + +## Validation layers + +Run the repository-required commands from `AGENTS.md`. The principal layers +are: + +1. **Generation:** skill and marketplace outputs match their sources. +2. **Unit/regression:** repository and script test roots pass on the supported + Python matrix. +3. **Distribution:** exactly one public package, correct manifests, no retired + package trees, and deterministic archives/evidence. +4. **Release consistency:** versions, README markers, marketplaces, manifests, + changelog inputs, and tag rules agree. +5. **Public-export safety:** active tree and locally reachable history contain + no provider executor source, raw invocation recipes, credentials, private + paths, retired trees, or unreviewed artifacts. +6. **Security:** dependency-free secret scan, Gitleaks, CodeQL + `security-extended`, GitHub secret scanning/push protection, and pinned + third-party Actions. +7. **Governance:** compliance-trace schema, tier rules, CODEOWNERS, required + checks, signed commits, and resolved review threads. + +## History-scan scope + +The public-export history check scans refs available in the local clone. A +clone that retains obsolete refs can fail even when a disposable full clone of +the canonical remote is clean. A clean comparison proves only the recorded +remote snapshot; it does not clear a different clone or prior exposure. + +If a publication candidate, canonical fetched ref, credential pattern, or +provenance question remains unsafe, stop publication and follow +[`SECURITY.md`](../../SECURITY.md). Scanner output can itself contain sensitive +paths and object identifiers and must not be pasted into a public issue. + +## Contributor path + +1. Read `AGENTS.md` and [`docs/public-governance.md`](../public-governance.md). +2. Work from a current topic branch or isolated worktree. +3. Edit authoritative sources, regenerate outputs, and add one unique fragment. +4. Run focused checks and the required full suites. +5. Record the PR compliance trace and independent review required by the tier. +6. Resolve review threads and merge normally after all required checks pass. +7. Treat release/tag work as a separate governed lifecycle. + +The package reference documents the low-level coordinator schema. The +architecture handbook should link to that reference rather than duplicate its +field-by-field protocol. diff --git a/docs/architecture/status-and-evidence.md b/docs/architecture/status-and-evidence.md new file mode 100644 index 0000000..9ab6548 --- /dev/null +++ b/docs/architecture/status-and-evidence.md @@ -0,0 +1,80 @@ +# Status and evidence + +< [Architecture handbook index](README.md) + +This page prevents five different facts from being collapsed into one word: +repository version, signed tag, GitHub release, installed package, and active +runtime. Each has a different evidence source. + +## Evidence planes + +| Plane | What it can prove | What it cannot prove | +| --- | --- | --- | +| Repository source | Current files, manifests, generated skills, tests, and repository-only artifacts at a named commit. | That a package was published, installed, selected, or usable on a host. | +| Signed tag | A signed annotated reference and the exact commit it identifies. | That a GitHub release exists, its assets are correct, or a host installed it. | +| GitHub release | Published release metadata and attached evidence for one tag. | That every marketplace or host has updated, or that a route is ready. | +| Package installation | The package/version selected by one host's plugin manager. | That a native route passed readiness or that another host has the same version. | +| Runtime readiness | Provider-free evidence that the selected package and managed boundary are callable for the reported contracts. | A guarantee that provider authentication, quota, or a future request will succeed. | +| Invocation result | The typed outcome of one bounded request. | General availability, permission to retry with wider authority, or merge approval. | + +## Authoring snapshot + +This handbook was authored against the following public evidence on +2026-08-05: + +| Observation | Status | Interpretation | +| --- | --- | --- | +| `origin/main` began at commit `465c70e` with package version 4.9.0. This documentation change advances the source package to 4.9.1. | current | The handbook describes the public repository contract that will exist when this change merges. | +| The repository contains one unified package, generated host marketplaces, a populated activation manifest, and the manifest-listed Darwin arm64 bundle. | repository-only | The source tree contains activation material; this alone does not prove an installation or active host. | +| The latest GitHub release record observed during authoring was v4.5.1. | historical release observation | It describes the public release list at that point in time, not the newer repository tree. | +| A signed annotated v4.6.0 tag existed without a corresponding GitHub release record. | historical tag observation | Tag existence and release publication are separate lifecycle events. | +| Changelog fragments after the generated `CHANGELOG.md` baseline remain in `changelog.d/`. | staged | Fragments are release inputs. They are not compiled on feature branches. | +| Current host installation and route readiness | unclaimed | This repository documentation intentionally makes no operator-host claim. Inspect the target host. | +| Provider-specific and host-specific predecessor packages | retired | Migration and regression tests block their return as active packages or rollback targets. | + +The observed release list is time-sensitive. Re-check it before making a new +release claim. Do not turn this dated row into a permanent “latest version” +badge. + +## Source-priority rule + +Use the narrowest evidence that answers the question: + +1. For the current public repository contract, inspect merged source, + manifests, generated outputs, and focused tests. +2. For a published release, inspect the signed tag, release record, assets, and + release evidence together. +3. For an installed package, inspect that host's plugin inventory after a new + session starts. +4. For native-route readiness, use the provider-free migration/readiness + surfaces from the selected package. +5. For a proposal or historical rationale, use its design or review record only + after labeling it proposed or historical. + +## Common category errors + +- **“It is in the manifest, so it is active.”** The manifest advertises a + package contract. Host selection and readiness are additional evidence. +- **“The version is on `main`, so it is released.”** Repository state is not a + GitHub release or installed-host observation. +- **“The tag exists, so release assets exist.”** Tags and GitHub releases are + separate objects. +- **“The skill is installed, so its provider is available.”** Skills remain + discoverable when the corresponding route returns typed unavailable. +- **“Safe mode means the old package is restored.”** Safe mode disables model + execution; retired packages remain retired. +- **“A green compliance trace proves the quoted review was genuine.”** The + public gate validates evidence form. Human and independent-agent review still + establish substance. + +## Updating the snapshot + +When source, release, or installation state changes: + +1. Record the exact evidence plane and date. +2. Update only the row that the new evidence proves. +3. Preserve older facts as historical when they remain useful. +4. Do not promote repository-only behavior to installed/active without a host + observation. +5. Re-run the link, generated-source, release-consistency, and sanitization + checks described in [Repository and release architecture](repository-and-release.md). diff --git a/docs/architecture/system-context.md b/docs/architecture/system-context.md new file mode 100644 index 0000000..42b887c --- /dev/null +++ b/docs/architecture/system-context.md @@ -0,0 +1,147 @@ +# System context + +< [Architecture handbook index](README.md) + +`agent-collab` is a source-available plugin that helps a trusted primary AI +agent work with other model families through governed collaboration workflows. +It supplies reusable skills, identity and independence policy, closed managed +routes, migration checks, and release-safety tooling in one package. + +The project treats model output as untrusted-but-useful evidence. The primary +still interprets the user's goal, integrates any result, runs verification, and +owns the landing decision. + +A useful mental model is a guarded handoff desk, not a group chat. The primary +brings a bounded job; policy checks who is eligible to take it and which tools +that role may use; the result comes back to the primary for judgment. The +handoff transfers work, never ownership of the user's objective or permission +to land the result. + +## What the project is + +- A single plugin package for supported host plugin systems. +- A library of collaboration skills for review, planning, assurance, + delegation, knowledge work, orchestration, and domain expertise. +- A public policy boundary that resolves primary and artifact lineage, excludes + ineligible families, and seals route authority. +- A verified client for an optional co-packaged native runtime. +- A migration and safe-mode boundary for retiring older package generations. +- A public contribution, CI, and release contract that can be applied without + access to the private native producer. + +## What the project is not + +- It is not a general-purpose “AI swarm” that grants every agent equivalent + authority. +- It is not a raw wrapper around provider command-line tools. +- It does not publish provider executor source, provider credentials, raw + invocation recipes, downloaders, or post-install execution hooks. +- It is not a collection of host- or provider-specific plugins. +- It does not make every listed skill or route usable on every host. +- It does not let a reviewer, worker, or successful model response merge, + deploy, change governance, or expand its own permissions. +- It is source-available under PolyForm Strict; it is not an open-source grant. + +## System view + +```mermaid +flowchart LR + User["User"] --> Host["Supported AI host"] + Host --> Primary["Trusted primary"] + Primary --> Skill["agent-collab skill or workflow"] + + Skill --> Local["Primary-executed playbook"] + Skill --> Coord["Public coordinator and host policy"] + Skill --> Async["Host-owned async coordination readiness"] + + Coord --> Identity["Primary and artifact lineage"] + Identity --> Policy["Family independence and sealed authority"] + Policy --> Client["Verified runtime client"] + Client --> Runtime["Manifest-selected signed runtime"] + Runtime --> Role["Managed provider role"] + Role --> Result["Typed result and evidence"] + Result --> Primary + + Local --> Primary + Async --> Primary + + Producer["Private native producer"] -. "final signed bundle and closed manifest" .-> Client + Repo["Public repository"] --> Skill + Repo --> Coord + Repo --> Client + Repo --> Governance["Public review, CI, and release gates"] + Governance --> Primary +``` + +The dotted producer edge is intentionally narrow. Contributors can review and +change the public policy, skills, client, schemas, tests, and release checks +without seeing private implementation or signing credentials. Only a final +bundle and the metadata needed to verify it may cross into the public package. + +## Actors and authority + +| Actor or boundary | Responsibility | Authority not granted | +| --- | --- | --- | +| User | Sets the objective, constraints, and any reserved decisions. | No requirement to understand provider transport or package internals. | +| Supported host | Loads the plugin and exposes its skills in the host's normal interaction model. | Does not redefine model family or route authority. | +| Trusted primary | Interprets intent, selects a workflow, reviews output, applies changes, tests, and decides what to land within user authority. | Cannot turn same-family output into independent governance evidence. | +| Skill | Encodes one public workflow and its triggers, evidence needs, and stop conditions. | Does not prove the underlying managed route is active. | +| Public coordinator and policy | Resolve current identity, family eligibility, route/action pairing, and typed preflight results. | No raw provider, binary, credential, or arbitrary tool selection. | +| Managed reviewer | Returns bounded read-only critique or governance evidence. | No source mutation, merge, deployment, or self-approval. | +| Managed worker | Returns bounded output under its declared authority. | No hidden promotion from output-only to caller-workspace mutation. | +| Async target | Participates through a host-owned, explicitly addressed handoff after readiness is observed. | The public coordinator does not send messages or create a synchronous Claude route. | +| Native runtime | Executes the manifest-selected managed contract and returns typed output. | Cannot advertise contracts absent from the closed manifest. | +| Repository governance | Requires trace, review, CI, ownership, and release evidence. | Does not prove that quoted review prose is genuine or replace implementation tests. | +| Operator | Retains reserved merge, release, activation, security, and recovery authority defined by policy. | Is not silently bypassed by agent consensus or green CI. | + +## Public package boundary + +The installable package contains: + +- Claude-compatible and Codex-native manifests for the same package/version; +- generated skills built from the editable `skill-specs/` source; +- coordinator, host policy, migration doctor, runtime client/setup, bundle + verification, and signing-policy modules; +- the closed runtime and output schemas; +- package legal and third-party notices; and +- for an activation source tree or release, the manifest-listed native bundle. + +The package deliberately excludes provider backend source, provider-specific +plugin trees, an MCP server tree, downloader code, and private build/sign +configuration. Tests enforce the public module inventory and retirement +boundary. + +## Data and control flow + +1. The primary invokes a skill or follows a primary-executed playbook. +2. For a managed route, the public coordinator observes current identity and + validates the bounded request. +3. Policy excludes the active primary family and, when applicable, the + artifact-author family from independent review or worker selection. +4. The request receives one declared authority. Fallback cannot widen it. +5. The client validates the manifest and native bundle before the managed + runtime receives a request. +6. The runtime returns one typed result under the same contract. +7. The trusted primary evaluates the result, applies nothing automatically, + and runs task-appropriate verification. +8. Pull-request, merge, release, and operator gates remain separate decisions. + +## Threat and trust limit + +The public runtime boundary narrows artifact substitution, route confusion, +authority promotion, unsafe package state, and uncontrolled provider +invocation. It does not claim isolation from arbitrary malicious code already +running as the same operating-system user. A canonical user home is not a +deny-all-read confidentiality boundary; the implementation uses explicit +same-UID read trust while containing writes, execution/lifecycle state, +provider-state access, and cleanup. + +A blocked access attempt inside an established boundary is containment success, +not a failure. A structural containment failure means the boundary could not be +established or there is positive evidence of an escaped write or protected-state +change. Authentication, protocol/output, timeout, provider, teardown, and +cleanup failures remain distinct. Direct CLI invocation is not a normal +fallback for a managed route. + +Continue with [Capabilities and workflows](capabilities-and-workflows.md) or +[Governance and authority](governance-and-authority.md). diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100644 index 0000000..548f259 --- /dev/null +++ b/docs/design/README.md @@ -0,0 +1,40 @@ +# Design and review evidence + +This directory retains design artifacts and adversarial review records. These +files explain why current release-safety code has its shape, but they are not a +substitute for merged source, tests, package manifests, or the public +[architecture handbook](../architecture/README.md). + +## How to use this directory + +- **Design of record** means current source explicitly cites the document for a + defined contract. Read only the cited section/version and verify it against + code and tests. +- **Superseded design** preserves earlier reasoning. Later sections within the + same file may override earlier sections. +- **Historical review** records objections and verdicts from a past design + cycle. A review verdict does not describe current implementation by itself. + +## Registry + +| Document | Classification | Current use | +| --- | --- | --- | +| [`release-cut-pipeline-v2-saga-design.md`](release-cut-pipeline-v2-saga-design.md) | mixed design-of-record and superseded draft | `scripts/release_tag_contract.py` cites the converged v3 release-saga architecture. The filename and opening v2 status are historical layers; inspect the cited v3 section and current tests. | +| [`pr4-cut-release-activation-design.md`](pr4-cut-release-activation-design.md) | mixed design-of-record and superseded versions | Current tag-contract source cites V3/V9. Earlier V0–V10 text remains historical where later sections conflict. | +| [`reconciliation-contract-correction.md`](reconciliation-contract-correction.md) | historical design intervention | Records the stop-and-redesign tripwire that preceded the broader release saga. It is not the current standalone release contract. | +| [`reviews/reconciliation-plan-adversarial-review-1.md`](reviews/reconciliation-plan-adversarial-review-1.md) | historical review | First adversarial review of the reconciliation plan. | +| [`reviews/pipeline-v2-adversarial-review-2.md`](reviews/pipeline-v2-adversarial-review-2.md) | historical review | Second review round for the release pipeline design. | +| [`reviews/pipeline-v3-adversarial-review-3.md`](reviews/pipeline-v3-adversarial-review-3.md) | historical review | Third review round and remaining objections at that snapshot. | + +## Precedence + +For current behavior, use this order: + +1. merged source and focused tests; +2. public manifests, schemas, and release evidence; +3. normative governance and security documents; +4. explicitly cited design-of-record sections; and +5. historical designs and review records for rationale only. + +When adding a design or review file, update this registry and state whether it +is proposed, current design-of-record evidence, superseded, or historical. diff --git a/docs/public-governance.md b/docs/public-governance.md index 206d40b..d64d749 100644 --- a/docs/public-governance.md +++ b/docs/public-governance.md @@ -72,9 +72,9 @@ GitHub-hosted runners and receives no private build/sign credentials. Policy-only releases contain an empty runtime manifest. An activation release may import only a final signed and notarized standalone bundle, its closed -schema-2/contract-3 manifest, per-member verification metadata, and required -third-party license evidence. Public contributors never build or inspect the -private implementation. +schema-3/contract-3 manifest in the current repository generation, per-member +verification metadata, and required third-party license evidence. Public +contributors never build or inspect the private implementation. Run the gates in `README.md`, including: diff --git a/plugins/agent-collab/.claude-plugin/plugin.json b/plugins/agent-collab/.claude-plugin/plugin.json index 8f4011c..b7e2786 100644 --- a/plugins/agent-collab/.claude-plugin/plugin.json +++ b/plugins/agent-collab/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-collab", - "version": "4.9.0", - "description": "Unified dynamic-host collaboration package with centralized skills, migration preflight, and a verified plugin-relative native runtime boundary. The signed runtime artifact is intentionally absent until the private build/sign integration completes.", + "version": "4.9.1", + "description": "Unified dynamic-host collaboration package with centralized skills, migration preflight, and a verified plugin-relative native runtime boundary. Native route availability is established at runtime and never inferred from package metadata alone.", "author": { "name": "John Osumi" }, diff --git a/plugins/agent-collab/.codex-plugin/plugin.json b/plugins/agent-collab/.codex-plugin/plugin.json index 12c0a0c..b03c0fd 100644 --- a/plugins/agent-collab/.codex-plugin/plugin.json +++ b/plugins/agent-collab/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-collab", - "version": "4.9.0", - "description": "Unified dynamic-host collaboration package with centralized skills, migration preflight, and a verified plugin-relative native runtime boundary. The signed runtime artifact is intentionally absent until the private build/sign integration completes.", + "version": "4.9.1", + "description": "Unified dynamic-host collaboration package with centralized skills, migration preflight, and a verified plugin-relative native runtime boundary. Native route availability is established at runtime and never inferred from package metadata alone.", "author": { "name": "John Osumi" }, diff --git a/plugins/agent-collab/README.md b/plugins/agent-collab/README.md index 5f9aeb2..e8d6fea 100644 --- a/plugins/agent-collab/README.md +++ b/plugins/agent-collab/README.md @@ -4,10 +4,12 @@ installable half of the governed multi-agent engineering model described in the [repository README](../../README.md) — cross-family review independence, verifiable compliance evidence, and operator final-say, delivered as one -package for every supported host. This document is the package's technical -reference; the repository README carries the purpose and governance narrative. +package for every supported host. This document is the package's low-level +technical reference. General users should start with the public +[architecture handbook](../../docs/architecture/README.md) and +[lifecycle guide](../../docs/architecture/lifecycle-and-operations.md). -Current: **4.9.0** +Current: **4.9.1** It resolves `primary_id`, `primary_family`, `active_model`, `host_runtime`, and `session_identifier` from the current host or explicit configuration. On a @@ -78,7 +80,7 @@ one macOS `LC_BUILD_VERSION` with minimum macOS 14.0 instead of trusting those manifest labels. The broker transport and provider protocol are both version 2. The package carries both `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`; both -identify this same 4.9.0 package. +identify this same 4.9.1 package. Codex, Gemini, OpenCode, Grok, and Composer are broker-only contracts. Their sealed requests cross a mode-`0600`, digest-bound per-user launchd Unix socket; launchd starts the exact @@ -193,13 +195,10 @@ exactly - dual set membership without equality fails closed, as do mixed, hybrid, unknown, or non-string values. Governance readiness recognizes either exact mode as capability-only; readiness never authorizes execution. -This 4.5.4 source tree retains the rebuilt darwin-arm64 activation artifact -from final workspace `1.0.823` commit -`d08b6382710d6d5910d64cf011bcac873a2e1c03`. Its manifest pins the complete -standalone bundle at SHA-256 -`2cea10cff2030d0238661667cf8d1b83cf9885dc6f4a03b0db4365e891b04f47`; -the bundle is Developer-ID signed and Apple-notarized under submission -`c6d29dec-5351-467d-883e-0b862734567d`. Native **Gemini +This 4.9.1 source tree contains a repository-only darwin-arm64 activation +artifact. The committed manifest pins its exact standalone bundle membership, +identity, and verification contract. Repository presence is not host readiness: +native **Gemini advisory/governance/long-context**, **Codex advisory/governance**, **OpenCode plan/build**, and **Grok 4.5 read-only architecture consultation, governance review, huge-context ingestion, and output-only code/patch @@ -627,11 +626,12 @@ spawn, while treating the operator account and selected plugin cache as trusted. The manifest cannot choose its own signer. `signing_policy.py` pins the -operator-owned Developer ID Team ID in reviewed policy source, and runtime plus +approved Developer ID team in reviewed public policy source, and runtime plus release verification require the manifest and `codesign` output to match that -anchor. The anchor is intentionally empty in this source revision because no -valid Developer ID identity is installed on the build host; native activation -and release fail closed until the operator-owned Team ID is configured. +anchor. The anchor is configured in this source revision. Its presence does not +prove host installation or readiness; activation and release still fail closed +unless the complete bundle, manifest, signature, timestamp, notarization, and +release evidence agree. The full old namespace mapping and clean-history public-export requirement are documented in diff --git a/plugins/agent-collab/skills/agent-readiness/SKILL.md b/plugins/agent-collab/skills/agent-readiness/SKILL.md index 06accf1..8b21db2 100644 --- a/plugins/agent-collab/skills/agent-readiness/SKILL.md +++ b/plugins/agent-collab/skills/agent-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: agent-readiness -version: 4.9.0 +version: 4.9.1 description: Evaluate whether an agent, model, CLI, plugin, or role is ready for a proposed responsibility. Use when the user says "agent readiness," "is this agent ready," "can Codex be primary," "can Grok handle this role," "promote this agent," "evaluate this worker," "review model readiness," or "/agent-collab:agent-readiness." Also offer this proactively before assigning a new primary, reviewer, worker, delegate, headless, release, or merge-related role to Claude, Codex, Antigravity/Gemini, Grok, or a future agent. --- diff --git a/plugins/agent-collab/skills/agent-runtime-status/SKILL.md b/plugins/agent-collab/skills/agent-runtime-status/SKILL.md index 925de24..984dd58 100644 --- a/plugins/agent-collab/skills/agent-runtime-status/SKILL.md +++ b/plugins/agent-collab/skills/agent-runtime-status/SKILL.md @@ -1,6 +1,6 @@ --- name: agent-runtime-status -version: 4.9.0 +version: 4.9.1 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/ai-writing-auditor/SKILL.md b/plugins/agent-collab/skills/ai-writing-auditor/SKILL.md index 263fa43..c8fb865 100644 --- a/plugins/agent-collab/skills/ai-writing-auditor/SKILL.md +++ b/plugins/agent-collab/skills/ai-writing-auditor/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-writing-auditor -version: 4.9.0 +version: 4.9.1 description: Audits prose for the tells of machine-generated writing and rewrites it to read as if a careful human wrote it, without softening the actual content. Use when the user says "de-AI this text", "audit this writing for AI patterns", "make this read human", or "/agent-collab:ai-writing-auditor." Also offer this proactively when a piece of customer-facing or published prose is dense with the stock phrasing and mechanical structure typical of unedited model output. --- diff --git a/plugins/agent-collab/skills/architect/SKILL.md b/plugins/agent-collab/skills/architect/SKILL.md index b7daf67..09e134d 100644 --- a/plugins/agent-collab/skills/architect/SKILL.md +++ b/plugins/agent-collab/skills/architect/SKILL.md @@ -1,6 +1,6 @@ --- name: architect -version: 4.9.0 +version: 4.9.1 description: Request read-only architecture consultation for codebase analysis, system design, implementation planning, decomposition, or long-horizon coding strategy. Use when the user says "ask the architect," "have Grok design this," "architecture consultation," "plan this implementation," "decompose this build," "analyze the system design," or "/agent-collab:architect." Also offer this proactively before a substantial multi-system or long-horizon implementation where an independent architecture pass can reduce rework. This role never edits files, runs shell commands or tests, mutates a worktree, opens PRs, merges, or deploys. --- diff --git a/plugins/agent-collab/skills/architecture-review/SKILL.md b/plugins/agent-collab/skills/architecture-review/SKILL.md index 4107fd3..32f8493 100644 --- a/plugins/agent-collab/skills/architecture-review/SKILL.md +++ b/plugins/agent-collab/skills/architecture-review/SKILL.md @@ -1,6 +1,6 @@ --- name: architecture-review -version: 4.9.0 +version: 4.9.1 description: Self-executed sweep of a codebase for module-deepening opportunities — shallow interfaces, scattered locality, untestable seams — presented as a visual report the user picks a candidate from, then explored interactively. Unlike `architect` (routed consultation) and `code-review` (diff review), this skill is run by the active primary on the whole codebase. Use when the user says "architecture review," "find deepening opportunities," "where is this codebase getting muddy," "improve the architecture," or "/agent-collab:architecture-review." Also offer this proactively when repeated friction in a working session traces to shallow modules — bouncing between many files to follow one concept, or tests that cannot reach behavior through the current interfaces. --- diff --git a/plugins/agent-collab/skills/autonomy-readiness/SKILL.md b/plugins/agent-collab/skills/autonomy-readiness/SKILL.md index 6499c63..fcbf3c4 100644 --- a/plugins/agent-collab/skills/autonomy-readiness/SKILL.md +++ b/plugins/agent-collab/skills/autonomy-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: autonomy-readiness -version: 4.9.0 +version: 4.9.1 description: Evaluate whether an autonomous, always-on, scheduled, headless, or self-evolving workflow is ready to run safely. Use when the user says "autonomy readiness," "activation gate review," "is this workflow ready to run autonomously," "go/no-go autonomy," "always-on readiness," "headless operation review," or "/agent-collab:autonomy-readiness." Also offer this proactively before enabling background agents, recurring automations, auto-merge/self-evolution, external actions, unattended host runs, or any workflow that can continue without a human watching. --- diff --git a/plugins/agent-collab/skills/brainstorm/SKILL.md b/plugins/agent-collab/skills/brainstorm/SKILL.md index 878f438..fa6b041 100644 --- a/plugins/agent-collab/skills/brainstorm/SKILL.md +++ b/plugins/agent-collab/skills/brainstorm/SKILL.md @@ -1,6 +1,6 @@ --- name: brainstorm -version: 4.9.0 +version: 4.9.1 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/chain-configurator/SKILL.md b/plugins/agent-collab/skills/chain-configurator/SKILL.md index 8aaf0d5..9ecff77 100644 --- a/plugins/agent-collab/skills/chain-configurator/SKILL.md +++ b/plugins/agent-collab/skills/chain-configurator/SKILL.md @@ -1,6 +1,6 @@ --- name: chain-configurator -version: 4.9.0 +version: 4.9.1 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/chain/SKILL.md b/plugins/agent-collab/skills/chain/SKILL.md index 3ac52f0..c98666d 100644 --- a/plugins/agent-collab/skills/chain/SKILL.md +++ b/plugins/agent-collab/skills/chain/SKILL.md @@ -1,6 +1,6 @@ --- name: chain -version: 4.9.0 +version: 4.9.1 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/code-review/SKILL.md b/plugins/agent-collab/skills/code-review/SKILL.md index ce444a1..2dab973 100644 --- a/plugins/agent-collab/skills/code-review/SKILL.md +++ b/plugins/agent-collab/skills/code-review/SKILL.md @@ -1,6 +1,6 @@ --- name: code-review -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/compose-skills/SKILL.md b/plugins/agent-collab/skills/compose-skills/SKILL.md index f388ef6..3972722 100644 --- a/plugins/agent-collab/skills/compose-skills/SKILL.md +++ b/plugins/agent-collab/skills/compose-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: compose-skills -version: 4.9.0 +version: 4.9.1 description: Select a bounded, token-aware combination of collaboration skills or task lenses before execution. Use when the user says "compose skills," "which skills should I use," "use skill composition," "select a recipe," "combine these skills," or "/agent-collab:compose-skills." Also offer this proactively when a task plausibly needs multiple lenses, reviewers, or agents and would benefit from progressive disclosure, explicit fan-out limits, and a smallest-useful-skill plan before routing or loading full skill bodies. --- diff --git a/plugins/agent-collab/skills/data-engineer/SKILL.md b/plugins/agent-collab/skills/data-engineer/SKILL.md index 1258b4a..461a8b4 100644 --- a/plugins/agent-collab/skills/data-engineer/SKILL.md +++ b/plugins/agent-collab/skills/data-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: data-engineer -version: 4.9.0 +version: 4.9.1 description: Builds and hardens the pipelines and warehouse structures that move data from source systems to the people and systems that consume it. Use when the user says "build the ETL pipeline", "design the dbt models", "orchestrate this pipeline", or "design the warehouse schema", or "/agent-collab:data-engineer." Also offer this proactively when a pipeline lacks idempotency, has no data-quality checks, or moves data through undocumented schema contracts. --- diff --git a/plugins/agent-collab/skills/debate/SKILL.md b/plugins/agent-collab/skills/debate/SKILL.md index 6cc0807..22c1e86 100644 --- a/plugins/agent-collab/skills/debate/SKILL.md +++ b/plugins/agent-collab/skills/debate/SKILL.md @@ -1,6 +1,6 @@ --- name: debate -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/decision-map/SKILL.md b/plugins/agent-collab/skills/decision-map/SKILL.md index fdd094b..fbaf8c1 100644 --- a/plugins/agent-collab/skills/decision-map/SKILL.md +++ b/plugins/agent-collab/skills/decision-map/SKILL.md @@ -1,6 +1,6 @@ --- name: decision-map -version: 4.9.0 +version: 4.9.1 description: Plan an effort too large for one session as a shared map of decision tickets on the repo's issue tracker, then resolve them one per session until the way to the destination is clear. Use when the user says "decision map," "chart this effort," "map out this project," "break this fog into tickets," "work the map," or "/agent-collab:decision-map." Also offer this proactively when a request is a loose multi-session idea whose route is not yet visible — where the open questions outnumber the known steps and a single planning pass would either stall or guess. --- diff --git a/plugins/agent-collab/skills/delegate/SKILL.md b/plugins/agent-collab/skills/delegate/SKILL.md index cbd4883..50d4763 100644 --- a/plugins/agent-collab/skills/delegate/SKILL.md +++ b/plugins/agent-collab/skills/delegate/SKILL.md @@ -1,6 +1,6 @@ --- name: delegate -version: 4.9.0 +version: 4.9.1 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/dev-delegate/SKILL.md b/plugins/agent-collab/skills/dev-delegate/SKILL.md index 86c0ab4..67122b2 100644 --- a/plugins/agent-collab/skills/dev-delegate/SKILL.md +++ b/plugins/agent-collab/skills/dev-delegate/SKILL.md @@ -1,6 +1,6 @@ --- name: dev-delegate -version: 4.9.0 +version: 4.9.1 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/elixir-engineer/SKILL.md b/plugins/agent-collab/skills/elixir-engineer/SKILL.md index c92114f..688858d 100644 --- a/plugins/agent-collab/skills/elixir-engineer/SKILL.md +++ b/plugins/agent-collab/skills/elixir-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: elixir-engineer -version: 4.9.0 +version: 4.9.1 description: Senior Elixir and OTP engineer for fault-tolerant, concurrent, and Phoenix-based systems. Use when the user says "review this supervision tree", "why did this GenServer crash", "help me design this OTP process architecture", or "/agent-collab:elixir-engineer." Also offer this proactively when a change adds a new process, alters a restart strategy, or touches a Phoenix channel or LiveView boundary. --- diff --git a/plugins/agent-collab/skills/eval-engineer/SKILL.md b/plugins/agent-collab/skills/eval-engineer/SKILL.md index d5fffed..d9c79ba 100644 --- a/plugins/agent-collab/skills/eval-engineer/SKILL.md +++ b/plugins/agent-collab/skills/eval-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: eval-engineer -version: 4.9.0 +version: 4.9.1 description: Designs evaluation suites and scoring methods that measure whether an AI-backed workflow is actually good enough to ship. Use when the user says "design evals for this", "build an eval suite", "how should we measure this workflow", or "/agent-collab:eval-engineer." Also offer this proactively when a project ships a prompt, retrieval pipeline, or agent workflow with no structured way to tell whether a change made it better or worse. --- diff --git a/plugins/agent-collab/skills/go-engineer/SKILL.md b/plugins/agent-collab/skills/go-engineer/SKILL.md index 0f5f37b..71843f8 100644 --- a/plugins/agent-collab/skills/go-engineer/SKILL.md +++ b/plugins/agent-collab/skills/go-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: go-engineer -version: 4.9.0 +version: 4.9.1 description: Senior Go engineer for concurrent, service-oriented, and cloud-native code. Use when the user says "review this Go service for concurrency bugs", "help me design this Go interface", "why is this goroutine leaking", or "/agent-collab:go-engineer." Also offer this proactively when a change adds a goroutine, channel, or context-cancellation path without an obvious termination guarantee. --- diff --git a/plugins/agent-collab/skills/governance-review/SKILL.md b/plugins/agent-collab/skills/governance-review/SKILL.md index d5c3183..741d9e4 100644 --- a/plugins/agent-collab/skills/governance-review/SKILL.md +++ b/plugins/agent-collab/skills/governance-review/SKILL.md @@ -1,6 +1,6 @@ --- name: governance-review -version: 4.9.0 +version: 4.9.1 description: Use when the operator says "governance review," "high-stakes review," "tiebreaker," or "second opinion." Also offer this proactively when reviewer-family independence must be enforced. --- diff --git a/plugins/agent-collab/skills/hallucination-investigator/SKILL.md b/plugins/agent-collab/skills/hallucination-investigator/SKILL.md index 4a1847f..d920d36 100644 --- a/plugins/agent-collab/skills/hallucination-investigator/SKILL.md +++ b/plugins/agent-collab/skills/hallucination-investigator/SKILL.md @@ -1,6 +1,6 @@ --- name: hallucination-investigator -version: 4.9.0 +version: 4.9.1 description: Traces a specific wrong or fabricated AI output back to its root cause in context, retrieval, prompting, or tool use, and recommends the most targeted fix. Use when the user says "why is it hallucinating", "investigate this fabrication", "trace this wrong answer", or "/agent-collab:hallucination-investigator." Also offer this proactively when a factuality failure has been reported but no one has yet reconstructed why the system produced that specific wrong answer. --- diff --git a/plugins/agent-collab/skills/incident-responder/SKILL.md b/plugins/agent-collab/skills/incident-responder/SKILL.md index 4fdf8d6..c1a81eb 100644 --- a/plugins/agent-collab/skills/incident-responder/SKILL.md +++ b/plugins/agent-collab/skills/incident-responder/SKILL.md @@ -1,6 +1,6 @@ --- name: incident-responder -version: 4.9.0 +version: 4.9.1 description: Leads live incident response — triage, containment, evidence-driven root-cause analysis, and postmortem writeups for active outages or breaches. Use when the user says "we have an incident", "production is down", or "run the postmortem for this outage", or "/agent-collab:incident-responder." Also offer this proactively when the user is trying to write the incident timeline or communicate status while a service disruption is still unresolved. --- diff --git a/plugins/agent-collab/skills/intent-check/SKILL.md b/plugins/agent-collab/skills/intent-check/SKILL.md index 8122d47..e46c239 100644 --- a/plugins/agent-collab/skills/intent-check/SKILL.md +++ b/plugins/agent-collab/skills/intent-check/SKILL.md @@ -1,6 +1,6 @@ --- name: intent-check -version: 4.9.0 +version: 4.9.1 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/knowledge-compile/SKILL.md b/plugins/agent-collab/skills/knowledge-compile/SKILL.md index 774f2a7..9a0965a 100644 --- a/plugins/agent-collab/skills/knowledge-compile/SKILL.md +++ b/plugins/agent-collab/skills/knowledge-compile/SKILL.md @@ -1,6 +1,6 @@ --- name: knowledge-compile -version: 4.9.0 +version: 4.9.1 description: Compile multiple sources into a durable, cited knowledge dossier without mixing claims, assumptions, and decisions. Use when the user says "compile knowledge," "build a dossier," "create a knowledge base," "synthesize these sources," "preserve research context," "make this reviewable later," or "/agent-collab:knowledge-compile." Also offer this proactively when a task spans several repos, PRs, papers, articles, logs, agent messages, or drafts and future agents need source-separated context for independent review. --- diff --git a/plugins/agent-collab/skills/kubernetes-specialist/SKILL.md b/plugins/agent-collab/skills/kubernetes-specialist/SKILL.md index 796fcb2..d9d559b 100644 --- a/plugins/agent-collab/skills/kubernetes-specialist/SKILL.md +++ b/plugins/agent-collab/skills/kubernetes-specialist/SKILL.md @@ -1,6 +1,6 @@ --- name: kubernetes-specialist -version: 4.9.0 +version: 4.9.1 description: Designs, hardens, and troubleshoots Kubernetes clusters and the workloads running on them. Use when the user says "review this Kubernetes manifest", "why is my pod crash-looping", or "help me design a multi-tenant cluster", or "/agent-collab:kubernetes-specialist." Also offer this proactively when a change touches Deployment/StatefulSet/DaemonSet specs, RBAC bindings, network policies, or persistent volume claims. --- diff --git a/plugins/agent-collab/skills/llm-architect/SKILL.md b/plugins/agent-collab/skills/llm-architect/SKILL.md index b5991fa..c55c44c 100644 --- a/plugins/agent-collab/skills/llm-architect/SKILL.md +++ b/plugins/agent-collab/skills/llm-architect/SKILL.md @@ -1,6 +1,6 @@ --- name: llm-architect -version: 4.9.0 +version: 4.9.1 description: Designs the structural shape of an LLM-powered system — how context is assembled, how tools and retrieval are wired in, and how output flows to the caller. Use when the user says "design the RAG pipeline", "plan the agent architecture", or "help me structure the prompt pipeline", or "/agent-collab:llm-architect." Also offer this proactively when a project is wiring multiple prompts, tools, and retrieval steps together without a clear contract between them. --- diff --git a/plugins/agent-collab/skills/logic-check/SKILL.md b/plugins/agent-collab/skills/logic-check/SKILL.md index 8ac8d78..2c858ff 100644 --- a/plugins/agent-collab/skills/logic-check/SKILL.md +++ b/plugins/agent-collab/skills/logic-check/SKILL.md @@ -1,6 +1,6 @@ --- name: logic-check -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: xhigh diff --git a/plugins/agent-collab/skills/long-context/SKILL.md b/plugins/agent-collab/skills/long-context/SKILL.md index 42f1101..169f647 100644 --- a/plugins/agent-collab/skills/long-context/SKILL.md +++ b/plugins/agent-collab/skills/long-context/SKILL.md @@ -1,6 +1,6 @@ --- name: long-context -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/merge-resolve/SKILL.md b/plugins/agent-collab/skills/merge-resolve/SKILL.md index eac102e..12db80e 100644 --- a/plugins/agent-collab/skills/merge-resolve/SKILL.md +++ b/plugins/agent-collab/skills/merge-resolve/SKILL.md @@ -1,6 +1,6 @@ --- name: merge-resolve -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/migration-doctor/SKILL.md b/plugins/agent-collab/skills/migration-doctor/SKILL.md index 60421c6..e90db28 100644 --- a/plugins/agent-collab/skills/migration-doctor/SKILL.md +++ b/plugins/agent-collab/skills/migration-doctor/SKILL.md @@ -1,6 +1,6 @@ --- name: migration-doctor -version: 4.9.0 +version: 4.9.1 description: Use when the user says "migration doctor," "check old collaboration plugins," "verify agent-collab migration," or "/agent-collab:migration-doctor." Also offer this proactively after installing or updating agent-collab, when provider routing is blocked, or when a retired package may still be selected from an installed plugin or cache. --- diff --git a/plugins/agent-collab/skills/mlops-engineer/SKILL.md b/plugins/agent-collab/skills/mlops-engineer/SKILL.md index 1e07815..2118b1a 100644 --- a/plugins/agent-collab/skills/mlops-engineer/SKILL.md +++ b/plugins/agent-collab/skills/mlops-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: mlops-engineer -version: 4.9.0 +version: 4.9.1 description: Designs and hardens the infrastructure that carries models from training through production serving. Use when the user says "set up a model registry", "build the training pipeline", "deploy this model to production", or "/agent-collab:mlops-engineer." Also offer this proactively when a project trains or serves models but has no versioned artifacts, no promotion gate, or no monitoring for prediction quality. --- diff --git a/plugins/agent-collab/skills/orchestrate/SKILL.md b/plugins/agent-collab/skills/orchestrate/SKILL.md index 7b6a660..8d3c777 100644 --- a/plugins/agent-collab/skills/orchestrate/SKILL.md +++ b/plugins/agent-collab/skills/orchestrate/SKILL.md @@ -1,6 +1,6 @@ --- name: orchestrate -version: 4.9.0 +version: 4.9.1 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/postgres-engineer/SKILL.md b/plugins/agent-collab/skills/postgres-engineer/SKILL.md index 67ab145..ce7dd83 100644 --- a/plugins/agent-collab/skills/postgres-engineer/SKILL.md +++ b/plugins/agent-collab/skills/postgres-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: postgres-engineer -version: 4.9.0 +version: 4.9.1 description: Administers and hardens PostgreSQL at the engine level — configuration, replication, vacuum behavior, and locking under real workloads. Use when the user says "tune postgres for this workload", "design a vacuum strategy", "set up replication", or "fix our connection pooling", or "/agent-collab:postgres-engineer." Also offer this proactively when a PostgreSQL deployment shows replication lag, bloat, connection exhaustion, or a failover plan that has never been tested. --- diff --git a/plugins/agent-collab/skills/prompt-regression-tester/SKILL.md b/plugins/agent-collab/skills/prompt-regression-tester/SKILL.md index ede78b3..044b1ce 100644 --- a/plugins/agent-collab/skills/prompt-regression-tester/SKILL.md +++ b/plugins/agent-collab/skills/prompt-regression-tester/SKILL.md @@ -1,6 +1,6 @@ --- name: prompt-regression-tester -version: 4.9.0 +version: 4.9.1 description: Builds and runs comparison suites that catch behavioral drift when a prompt, model, or workflow configuration changes. Use when the user says "did the prompt change regress anything", "compare these prompt versions", "regression-test this prompt change", or "/agent-collab:prompt-regression-tester." Also offer this proactively when someone is about to swap a prompt, model, or tool wiring in a live workflow without a way to check whether existing behavior held. --- diff --git a/plugins/agent-collab/skills/prototype/SKILL.md b/plugins/agent-collab/skills/prototype/SKILL.md index a408855..d1d74ca 100644 --- a/plugins/agent-collab/skills/prototype/SKILL.md +++ b/plugins/agent-collab/skills/prototype/SKILL.md @@ -1,6 +1,6 @@ --- name: prototype -version: 4.9.0 +version: 4.9.1 description: Build a throwaway prototype that answers one design question — an interactive terminal app to pressure-test a state model or logic shape, or several radically different UI variants on one route. Use when the user says "prototype this," "sanity-check this state model," "show me a few options for this page," "mock up some variations," or "/agent-collab:prototype." Also offer this proactively when a design conversation is circling a question that a runnable artifact would settle in minutes — how a state machine handles an awkward case, or which of several layouts actually works with real data. --- diff --git a/plugins/agent-collab/skills/qa-verify/SKILL.md b/plugins/agent-collab/skills/qa-verify/SKILL.md index b16f389..2aec30f 100644 --- a/plugins/agent-collab/skills/qa-verify/SKILL.md +++ b/plugins/agent-collab/skills/qa-verify/SKILL.md @@ -1,6 +1,6 @@ --- name: qa-verify -version: 4.9.0 +version: 4.9.1 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/red-team/SKILL.md b/plugins/agent-collab/skills/red-team/SKILL.md index b5e7940..0c9c43a 100644 --- a/plugins/agent-collab/skills/red-team/SKILL.md +++ b/plugins/agent-collab/skills/red-team/SKILL.md @@ -1,6 +1,6 @@ --- name: red-team -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/route/SKILL.md b/plugins/agent-collab/skills/route/SKILL.md index 92b5a90..8e49bdd 100644 --- a/plugins/agent-collab/skills/route/SKILL.md +++ b/plugins/agent-collab/skills/route/SKILL.md @@ -1,6 +1,6 @@ --- name: route -version: 4.9.0 +version: 4.9.1 description: Use when the operator says "ask Codex," "target=gemini," "target=grok," "target=composer," or explicitly names a managed backend. Also offer this proactively when routing needs dynamic primary-family exclusion. --- diff --git a/plugins/agent-collab/skills/rust-engineer/SKILL.md b/plugins/agent-collab/skills/rust-engineer/SKILL.md index 0be824e..b343e1a 100644 --- a/plugins/agent-collab/skills/rust-engineer/SKILL.md +++ b/plugins/agent-collab/skills/rust-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: rust-engineer -version: 4.9.0 +version: 4.9.1 description: Senior Rust engineer for ownership-heavy, performance-sensitive, and systems-level code. Use when the user says "review this Rust code for soundness", "help me fix this borrow checker error", "optimize this Rust hot path", or "/agent-collab:rust-engineer." Also offer this proactively when a diff introduces unsafe blocks, changes lifetime bounds, or touches an async task's cancellation path. --- diff --git a/plugins/agent-collab/skills/second-opinion/SKILL.md b/plugins/agent-collab/skills/second-opinion/SKILL.md index 5c14cc8..ddc10ab 100644 --- a/plugins/agent-collab/skills/second-opinion/SKILL.md +++ b/plugins/agent-collab/skills/second-opinion/SKILL.md @@ -1,6 +1,6 @@ --- name: second-opinion -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/simulate-user/SKILL.md b/plugins/agent-collab/skills/simulate-user/SKILL.md index 7d57fff..f639a31 100644 --- a/plugins/agent-collab/skills/simulate-user/SKILL.md +++ b/plugins/agent-collab/skills/simulate-user/SKILL.md @@ -1,6 +1,6 @@ --- name: simulate-user -version: 4.9.0 +version: 4.9.1 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/sql-engineer/SKILL.md b/plugins/agent-collab/skills/sql-engineer/SKILL.md index b47dadb..bf80064 100644 --- a/plugins/agent-collab/skills/sql-engineer/SKILL.md +++ b/plugins/agent-collab/skills/sql-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: sql-engineer -version: 4.9.0 +version: 4.9.1 description: Senior SQL specialist for query design, query optimization, and schema-aware performance work across relational databases. Use when the user says "optimize this SQL query", "explain this query plan", "design these indexes", or "/agent-collab:sql-engineer." Also offer this proactively when a diff adds a new query against a large table, changes a join or aggregation, or introduces a schema change that could affect an existing access pattern. --- diff --git a/plugins/agent-collab/skills/sre-engineer/SKILL.md b/plugins/agent-collab/skills/sre-engineer/SKILL.md index 58026ee..7793a16 100644 --- a/plugins/agent-collab/skills/sre-engineer/SKILL.md +++ b/plugins/agent-collab/skills/sre-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: sre-engineer -version: 4.9.0 +version: 4.9.1 description: Builds and improves system reliability through SLO design, error-budget policy, toil reduction, and resilience architecture. Use when the user says "help me define SLOs for this service", "what's our error budget burn rate", or "reduce the toil in this on-call rotation", or "/agent-collab:sre-engineer." Also offer this proactively when a reliability review, capacity plan, or alert-quality audit is warranted ahead of a launch or growth milestone. --- diff --git a/plugins/agent-collab/skills/start-inbox-monitor/SKILL.md b/plugins/agent-collab/skills/start-inbox-monitor/SKILL.md index 8392775..15a7064 100644 --- a/plugins/agent-collab/skills/start-inbox-monitor/SKILL.md +++ b/plugins/agent-collab/skills/start-inbox-monitor/SKILL.md @@ -1,6 +1,6 @@ --- name: start-inbox-monitor -version: 4.9.0 +version: 4.9.1 description: Use when the user says "start the inbox monitor", "keep monitoring agent messages", or "/agent-collab:start-inbox-monitor", or when an active cross-agent thread needs durable session-scoped inbox monitoring. Select the native Codex, Claude, or Antigravity lifecycle instead of inventing a universal polling loop. --- diff --git a/plugins/agent-collab/skills/teamwork/SKILL.md b/plugins/agent-collab/skills/teamwork/SKILL.md index 940762c..7fd7e45 100644 --- a/plugins/agent-collab/skills/teamwork/SKILL.md +++ b/plugins/agent-collab/skills/teamwork/SKILL.md @@ -1,6 +1,6 @@ --- name: teamwork -version: 4.9.0 +version: 4.9.1 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/terraform-engineer/SKILL.md b/plugins/agent-collab/skills/terraform-engineer/SKILL.md index f0fd2ff..1752042 100644 --- a/plugins/agent-collab/skills/terraform-engineer/SKILL.md +++ b/plugins/agent-collab/skills/terraform-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: terraform-engineer -version: 4.9.0 +version: 4.9.1 description: Designs, refactors, and reviews Terraform infrastructure-as-code across cloud providers, with a focus on module contracts, state safety, and reviewable plans. Use when the user says "review this Terraform plan", "help me design a reusable module", or "why did this apply want to replace my resource", or "/agent-collab:terraform-engineer." Also offer this proactively when a change touches module interfaces, state backend configuration, or resource lifecycle blocks. --- diff --git a/plugins/agent-collab/skills/ui-to-code/SKILL.md b/plugins/agent-collab/skills/ui-to-code/SKILL.md index b6dfd46..0a15ec5 100644 --- a/plugins/agent-collab/skills/ui-to-code/SKILL.md +++ b/plugins/agent-collab/skills/ui-to-code/SKILL.md @@ -1,6 +1,6 @@ --- name: ui-to-code -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/untrusted-audit/SKILL.md b/plugins/agent-collab/skills/untrusted-audit/SKILL.md index caad5d8..eb12a4a 100644 --- a/plugins/agent-collab/skills/untrusted-audit/SKILL.md +++ b/plugins/agent-collab/skills/untrusted-audit/SKILL.md @@ -1,6 +1,6 @@ --- name: untrusted-audit -version: 4.9.0 +version: 4.9.1 description: Audit an external or untrusted source before using it in code, skills, plugins, workflows, prompts, or operations. Use when the user says "audit this untrusted source," "can we use this repo," "review this gist," "prompt injection audit," "is this plugin safe," "evaluate this methodology," or "/agent-collab:untrusted-audit." Also offer this proactively when a task would incorporate third-party instructions, code, scripts, hooks, generated skills, package manifests, install steps, or auto-updated methodology into the workspace or agent environment. --- diff --git a/plugins/agent-collab/skills/visual-review/SKILL.md b/plugins/agent-collab/skills/visual-review/SKILL.md index 6eaa430..10bc562 100644 --- a/plugins/agent-collab/skills/visual-review/SKILL.md +++ b/plugins/agent-collab/skills/visual-review/SKILL.md @@ -1,6 +1,6 @@ --- name: visual-review -version: 4.9.0 +version: 4.9.1 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/worker/SKILL.md b/plugins/agent-collab/skills/worker/SKILL.md index d79ea56..5b2bcc5 100644 --- a/plugins/agent-collab/skills/worker/SKILL.md +++ b/plugins/agent-collab/skills/worker/SKILL.md @@ -1,6 +1,6 @@ --- name: worker -version: 4.9.0 +version: 4.9.1 description: Use when the operator says "delegate this implementation," "use Gemini for this corpus," "ask Codex to build," or "use Composer for codegen." Also offer this proactively when a bounded non-governance task benefits from a managed worker. --- diff --git a/scripts/skill-build-config.json b/scripts/skill-build-config.json index f0f6c6e..6cb4779 100644 --- a/scripts/skill-build-config.json +++ b/scripts/skill-build-config.json @@ -20,7 +20,7 @@ "tier_flash_resolves_to_claude": "an asynchronous Anthropic inbox review; never a synchronous invocation", "tier_pro_resolves_to_gemini": "an eligible managed Google-family reviewer at high effort", "tier_flash_resolves_to_gemini": "an eligible managed Google-family reviewer at low effort", - "skill_version": "4.9.0", + "skill_version": "4.9.1", "agent_runtime_status_defaults_block": "defaults:\n tier: Fast\n effort: low\n", "merge_resolve_defaults_block": "defaults:\n tier: Advanced\n effort: high\n", "merge_resolve_call_params": "`effort='high'` in every eligible advisory row and no `tier` request field",