sumitake · sumitake · Aug 6, 2026 · Aug 6, 2026
@@ -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"
   }
 }
@@ -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"
   }
 }
@@ -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.
@@ -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.
@@ -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).