This product contract and the development agreement, revision 3 incorporate the UI amendment authorized on 2 October 2026. They retain the agreements approved together on 29 September 2026 and define minimum commitments, not claims that capabilities are implemented or qualified. The guide maintains evolving role arrangements and reading paths; it cannot waive either agreement. Live work and evidence belong in Sidecat; progress reports implementation and qualification separately.
What we are building
Sidecat is a programmable, federated working environment for people and agents. It preserves organizational intent and authority, shares work and reusable methods, coordinates execution, and lets people inspect and challenge outcomes. A fresh agent must join useful work without a private briefing from its predecessor.
Independent application development must be practical: an author needs its component, the common contract and neighbors' public interfaces, rather than the whole private database or months of conversation. This is a reliability requirement, not a line-count or process-count target. Research, operations, planning and other domains use the same foundation; software development is an internal proving ground. The open-source system remains independently useful, with company and open-source publication estates separate. The ratified vision remains the product direction.
The existing code, documentation, decisions, experiments and unfinished work are substantial design inputs to this rearchitecture. This contract states minimum commitments and design boundaries; it is not an exhaustive inventory of that work. Absence from the contract does not authorize discarding a capability or idea. Account for relevant existing work through the component capability analysis, including explicit reuse, revision, replacement, retirement or unassessed status.
Agent task usability is a primary reason for this rearchitecture. Previous Sidecat generations failed on confusing or overlapping calls and prerequisites or sequences agents could not discover and complete, including after ground-up rewrites. Application boundaries, explicit dependencies and reusable composition must help callers do real work. Large catalogs are expected; total application or operation count alone is neither a defect nor an acceptance measure.
Fundamentals and user-facing composition
Users work with meaningful domain operations and reusable tasks. They must not learn the system's storage and coordination plumbing to perform each task, or require a new core command whenever they introduce a concept. Applications and packages build on these capabilities; this is not a fixed list of services.
| Building block | What it provides |
|---|---|
| Content and references | Revisioned Notes, names, blobs and owner-qualified references, reusable across records and communications. |
| Owned records and relationships | Create, read, revise and query typed records and relationships through an owning application's public interface. Packages can declare supported domain shapes and indexes without adding domain SQL or handlers to the daemon. |
| Semantic definitions | Namespaces, vocabulary, fields, facets, shapes and explicit mappings. Meaning is identified independently of a display label; a package can specialize a concept without creating another core verb. |
| Organizational scope and governance | Organizations, departments, workspaces and product/project context select applicable guidance, requirements, procedures and resource policies. Their owners connect declared rules to enforcement; a label, role or principle alone grants no authority. |
| Procedures and task entry points | Typed Lisp methods, reusable routines, partial composition and durable workflows expose useful tasks over application operations. Discovery shows the selected definition, required inputs, dependencies and recovery. |
| Runtime and effect capabilities | Resident Go applications provide substantial domain behavior, efficient storage, scheduling and external effects through the shared bus. Authority is checked by the responsible owner when the effect occurs. |
The organization/product context contract supports named, typed context entries; it does not freeze an exhaustive vocabulary into the core. A user may define "north star" as a product-development principle, for example, with declared meaning, fields and applicability. Display names do not establish semantic equivalence across namespaces; mappings must be declared. Scoped adoption can inherit shared entries and extend them locally; effective context exposes origins, selected revisions, refinements and explicit override decisions. Guidance, required consideration, deterministic checks and judgment criteria remain distinguishable. Nothing forces every user to adopt one taxonomy. Adoption declares whether it follows updates or pins revisions; active runs keep their selected inputs until explicit amendment. Structured checks do not establish that arbitrary prose is consistent or that a judgment is correct.
Users can register local semantic definitions and routines through the same supported interfaces before distributing a package. Marketplace publication is not a prerequisite for useful local work. A chosen name cannot erase required record semantics, including the Work/Plan distinction.
Go/Lisp placement follows workload, invariants and development cost. Infrequently changed definitions and reusable composition are good Lisp/package candidates; high read/write rates can favor purpose-built Go behavior. Package-defined records still use their owner's transaction, access and recovery guarantees. No universal database, new interpreter or Lisp evaluation on every record read is required.
Publishing as a composed task
A publishing entry point can select a user- or project-configured procedure: prepare content, generate files, perform selected checks, then call Git or other effect owners. A routine may use Go operations and Lisp composition; its selected revision and required inputs are inspectable and retained for continuation. Starting the procedure does not grant its steps additional authority. Retries and unknown effects retain the responsible owner's recovery semantics. An optimized Go implementation is valid when it preserves the same declared task contract. Ordinary authorized calls remain available outside workflows.
Registered operations and routines project through the common CLI, MCP and Lisp interfaces. Useful domain names are allowed; a bespoke top-level command or MCP tool for every operation is not required. Preparation and reusable methods reduce repeated decisions and hidden prerequisite sequences. Required publishing checks belong to the selected policy/procedure, not to an undocumented client wrapper.
Version 1 requirements
Each outcome has an owner, acceptance scenario and evidence against a named installed candidate. Missing requirements remain visible across sprint/model changes.
| ID | Required result | Acceptance must demonstrate |
|---|---|---|
| V1-01 | Organizational context | A fresh agent finds purpose, values, principles, structure, products/projects, commitments and relevant work. Named context entries support user/package-defined vocabulary, scoped adoption, inheritance and extension, with effective context exposing sources and selected revisions. Company, department and workspace scopes coexist without imposing one organizational method; guidance and enforced conditions remain distinct. |
| V1-02 | Identity, authority and resources | AAuth-based authority, using the independently maintained aauth-go library, supports scoped delegation, missions, conditional/expiring approval, revocation and resource allocation. A mediated remote effect checks effective authority. Independent nodes cannot spend the same reserved allowance twice. |
| V1-03 | Records and source references | Versioned text, names, blobs, original requests, decisions and typed references can be reused without copying their bodies. A permitted reader can follow a Work description to the exact originating content; an unauthorized reader cannot gain access through that link. |
| V1-04 | Work and planning | Reusable Work definitions are distinct from scheduled/assigned occurrences. Agents can refine, plan and coordinate work across projects/products/departments; returning agents see what is pending and why. Backlogs, boards and facets have explicit contextual owners. |
| V1-05 | Collective messaging | Direct and shared-room communication supports threads, structured attachments, bounded catch-up, meaningful attention state and offline return. Work discussions remain discoverable when their original participants disappear. An agent need not ingest the full message log. |
| V1-06 | Lisp and composition | A full documented Sidecat Lisp environment supports interactive composition, retained sessions/results, reusable methods and controlled partial execution. A fresh agent can inspect and continue a composed task after restart. One language meaning applies across call surfaces. |
| V1-07 | Marketplace and packages | Authors publish and distribute exact-version packages; users discover, inspect, install, admit, activate and replace them through ordinary Sidecat interfaces. Packages can contain Go applications, Sidecat Lisp methods, routines/workflows, one or more roles, supporting guidance and resources, including mixed bundles with declared content and dependencies. Experimental/testing/stable tracks and replacement handle pending work explicitly. An organization can operate its own internal marketplace with hosting, publishing, access, discovery and distribution, without proprietary hosting. A role package can be published and installed, then its roles assigned through separately authorized bindings; installation alone assigns no actors, grants no permissions and launches no workers. |
| V1-08 | Semantic definitions and discovery | Authors discover and declare namespaced object/operation/facet meanings, fields, shapes, relationships and explicit mappings. Local definitions and installed packages create, revise, query and relate useful persistent domain records through supported owners without changing the daemon or clients. Discovery identifies meanings, owners, dependencies and callable contracts. No universal object store or ontology engine is required. |
| V1-09 | Executable procedures | Typed routines compose operations and subroutines, including discoverable task entry points such as a configured publishing procedure. Durable workflows retain selected revisions, values, checkpoints, waits, decisions, cancellation/retry state and next eligible actions across harness replacement and restart. Prose guidance is identifiable as guidance. |
| V1-10 | Managed agent work | Reusable Sidecat roles remain independent of model/harness. A Sidecat Actor can adopt one or more roles, receive messages and assignments while offline, and activate on demand. Several actors can perform one role. Adapters preserve actual execution attribution, delivered context, finish reasons, partial output, resource use and uncertainty. Selection and routing vary by task without changing workflow semantics. |
| V1-11 | Controlled execution | Local and prepared remote nodes run permitted commands, model work and connector effects, with deduplicated submission, cancellation, results and actionable unknown outcomes. A remote executor needs no model login or interactive CLI session. |
| V1-12 | Shared bus and federation | Applications register typed operations/events. Addressed calls, durable events, transient notifications, subscriptions and bindings have distinct contracts. Independently administered nodes can cooperate through explicit ownership, permission and recovery; no global database or total event order is assumed. |
| V1-13 | Feedback and improvement | A correction or finding identifies what it concerns, retains its source, gets an explicit disposition, and can be connected to a later change and outcome. Cost/time by task category and alternatives can be compared using actual observations. |
| V1-14 | Usable interfaces and integrations | CLI, MCP and Lisp expose coherent tasks and results. Supported Linux/macOS installations, help, man pages and examples work from published instructions. At least one real issue-tracker synchronization demonstrates explicit field ownership, duplicate suppression and conflict handling. Human review can be presented through local or hosted interfaces. |
| V1-15 | Operational durability and scale | Restart/logout survival, backup/recovery, bounded queues, retention, contention and resource use are tested. Multi-node concurrency, hot writers, slow subscribers and absent agents are included. Supported limits are published with measured hardware/workloads, not inferred from goroutine counts or small tests. |
| V1-16 | Sidecat UI (sidecatui) |
The open-source operator client shows goals, current and pending work, roles and responsible actors; supports direct and shared-room conversation; and presents requests and decisions under Sidecat authorization. An operator can reach other actors when the lead is unavailable. Model/service use and available capacity are available through ordinary Sidecat calls, with observation/reset times where available and explicit distinctions between reported limits, token counters, estimates, stale data and unavailable information. Actual worker/model and task attribution are retained where observable. The UI uses these shared records and interfaces. |
Agreed design decisions
| Decision | Rule |
|---|---|
| Fundamentals and extensibility | Apply the building blocks through public owner interfaces. Packages may define vocabulary, supported record shapes and procedures. Core scope/authority and record guarantees remain stable while domain language and task composition can vary. No core command per domain concept. |
| Work and Plan | Work owns reusable purpose/question/outcome and a description reference, without universal closure, schedule or assignee. A Plan occurrence owns assignment, sequence, dates, progress and completion judgment, pinning the Work revision it judges. |
| Note and Message | Note is revisioned authored text. Message is a communication event with sender, destinations, context/thread and exact content reference. Message and Work use the same content owner's retrieval/access contract. Text input is a convenience, never a second Message-owned body/access path. Batching/co-location cannot change these semantics. |
| Records and databases | Stateful owners normally have separate SQLite databases and local transactions; stateless apps need none. Related types may share an explicit owner when their invariants require it. Other owners never read private tables or depend on migrations. No universal application database or central schema ladder. |
| Node and application runtime | Use Go and resident execution. Logical apps can share a host; isolation follows trust, failure or workload needs. No process per micro-app invocation or requirement to compile every app into sidecatd. Client languages are delegated; a Rust client is compatible. Node/bus infrastructure does not absorb domain records or domain SQL. |
| Lisp and composition | Keep and qualify the useful general interpreter unless a named requirement defeats it. Retained methods/packages and registered task routines remain central. Go owners can support package-defined data/behavior while retaining storage and effect guarantees. One language meaning and operation authority apply across surfaces; helpers do not silently multiply interpreters. |
| Marketplace and packages | Apply V1-07 through the package lifecycle for public delivery and self-operated internal marketplaces, including mixed Go/Lisp/workflow/role/resource packages. Discovery, installation, admission and activation are distinct; track labels grant neither trust nor authority. |
| Roles and actors | Apply V1-10 through the native meanings and lifecycle: reusable roles, durable actors and many-to-many scoped assignments. Identity persists without roles. Assigning or installing a role grants no permission and launches no worker. |
| Sidecat UI | The V1-16 client is optional to install, with the required operator outcomes. It consumes shared records, calls and authority, with no competing work state or private approval path. Required full-release support does not make it a headless-node prerequisite. |
| Bus and federation | One transport-independent operation meaning and explicit owner-qualified references. Calls, events and bindings compose owners. Durable events accompany the owning change with declared retry/acknowledgement/gap behavior. Bounded queues/fan-out; no hidden distributed transaction, global database or total event order. |
| Authority and custody | Check identity and effective permission at actual effects. Resources have named authority/accounting owners; partitions permit neither invented authority nor double spend. Stronger preservation, reviews and gates are configurable. Ordinary startup, messaging and work require no compulsory historical audit chain. |
| Workflows | Sidecat orchestration owns executable, versioned procedure state; planning owns Work/Plan meaning and execution reports actual effects. Completion depends on inputs/effects/results, not prose or a worker claim. Harnesses are replaceable; ordinary calls remain available outside workflows. |
| Call surface | One typed operation projects consistent inputs, results, errors, authority and recovery into argv/CLI, MCP, Lisp and the native client interface. Use clear domain nouns and consistent verbs. Occurrence completion replaces ambiguous universal work finish. Discovery is compact/relevant and the whole catalog inspectable. Generic entry points need no command/tool/screen per operation. |
| Reuse and replacement | Retain, revise, combine or remove existing calls/components against requirements, demonstrated tasks and total cost. No old implementation is entitled to survive; no new one replaces a working piece merely because it is new. Existing names are not compatibility obligations. |
| Existing data | Preserve useful unfinished work by export and checked repopulation, with an archive and controlled cutover. No backward-data migration or pre-release call compatibility is required. Upgrade support is separately designed for released versions. |
Roles, actors and runs
| Term | Native meaning |
|---|---|
| Sidecat Role | Reusable, versioned purpose, responsibility/scope, knowledge, capabilities, methods, outputs, review obligations and escalation. References policies/contracts instead of copying competing truth into prompts. Can be packaged; identity encodes no vendor, model, harness, account or process. |
| Sidecat Actor | Durable named organizational participant with stable identity and message/assignment address. Holds zero or more role assignments; people or agents can operate it. Existing identity is reused without re-enrollment and survives role changes/endings and offline periods. |
| Role assignment | Authorized actor-to-exact-role-revision binding, scoped to organization/component, with resource and activation references. Changes do not silently transfer claims or amend active runs. Several actors can hold a role; an actor can hold several roles. |
| Actor run | One activation for bounded work under selected assignments. Records actor, exact role/input revisions, requested selection and actual worker/model/harness, runtime principal/effective grants, delivered context, execution history, outputs and resource use where observable. Later activations can change implementation. |
| Agent | Executing model-and-harness worker, including subagents, working for an actor. Provider identifiers/session handles are adapter facts. A worker needs a separate actor only for its own durable responsibility, address and assignments. |
| Execution implementation | Versioned harness/model or deterministic executor configuration, tools, environment and account/resource route; separate from actor and role identity. |
| Runtime principal | Actual authenticated identity for concrete operations, with current effective grants. It can be the actor's own or a delegated principal; retain that relationship. Role instructions, registration and self-description confer no authority. |
Registration, role assignment and activation are separate. A message reaches the actor's stable address while offline; it does not itself create Work, grant permission or launch a run. Explicit interaction or selected workflows can request those actions. Replies identify actor and actual run/worker where applicable. Ephemeral subagents retain actual attribution without mandatory permanent registration.
Planning can address a role or actor. The Plan/workflow chooses eligible holders, required participants and claim rules; role assignment does not broadcast one task to every holder. Orchestration checks authority/resources and requests execution; completion/review returns to the workflow. Crashes and absent leads do not erase assignments or messages. Workflows govern retry, reassignment and unknown effects; reassignment names successors and existing-claim dispositions. Bus wakes are not the only retained ready-work record. Reuse identity, assignment and execution owners; no duplicate queue, credential store, run storage, mandatory daemon or new central lifecycle tables are implied. Reusing identity does not preserve the old schema.
Each activation selects assignments and bounded work without automatically unioning grants. Its context contains exact role/contract/input revisions, requirements, assignment/outcome, source/workspace, component/dependency contracts, actual tools and authority, mode, outputs/evidence, budget/timebox, escalation and continuation. Resolve task-linked history selectively. Bound the packet to runtime capacity; required constraints cannot be silently truncated. Available information and delivered context remain distinguishable under the retention policy. Confirm the assignment and report material mismatches at launch. On interruption, retain candidate, observations, unfinished actions and next steps; prevent unaware shared-tree edits.
Roles can require task capabilities. The execution registry separates technical/authority eligibility, observed suitability and cost/latency preferences. Unknown suitability stays explicit; provider tiers or self-descriptions do not qualify a worker. Evaluate required tools, context capacity and task capabilities on representative tasks. Bounded supervised trials can admit new implementations with technical support and authority.
Marketplace and packages
- Deliver and operate. Authors publish/distribute exact-version packages; consumers discover, inspect, install, admit, activate and replace them. Organizations can host and control access to their own internal marketplace, including publishing, discovery and distribution, without proprietary hosting.
- Compose package contents. Declare content and dependencies for Go apps, Lisp methods, routines/workflows, semantic definitions and supported record shapes, one or more roles, guidance, templates, checks, resources or mixed bundles.
- Keep distinctions clear. Experimental/testing/stable tracks do not confer trust or authority. Source and audience are separate from track: internal packages can be stable, and public packages experimental.
- Control activation. Replacement explicitly handles selected revisions and pending work. Installing roles does not assign actors, grant permission or start workers; authorized role assignment follows separately. These capabilities do not prescribe another service or universal wire schema.
- Declare views and file mappings. Packages may combine Sidecat records and Git-managed artifacts in generated publications or working material. Such routines declare source references and whether files are generated views or editable inputs. Preparation and return procedures use the same owner interfaces; this does not require a universal synchronizer or automatic interpretation of arbitrary files.
- Qualify extension by use. One independent package-author/consumer journey starts with a locally named concept and relationship, creates/queries records, applies scoped context and composes a useful task without core edits. Package and distribute that extension, then have an unfamiliar consumer discover and use it through the common interfaces. The particular domain, vocabulary and visual design are not required core behavior.
Sidecat UI
The required operator outcomes are V1-16. Package inspection exposes source and
distribution visibility independently of release track. Deliver a working sidecatui to the operator early in Version 1 development, before cutover.
Each sprint provides a runnable, tested operator build, keeps relevant views/actions aligned with delivered capabilities, and uses it for independent QA and operator review before release. The client uses shared calls/events for goals, work, actors, conversation and authorized decisions.
Usage/capacity collection works through ordinary Sidecat calls independently of the UI.
Observations do not grant authority or replace budget accounting; account information
follows the owning application's access rules. Actual execution and task attribution
must be distinguished from requested configuration.
Operator information offers understandable summaries and accessible detail. Presentations for people and agents can differ without changing facts, references or authority. Concise views expose refusals, uncertainty, blockers and outstanding decisions; no competing audience-specific content bodies. The guide refines summary-first writing. Advanced forecasting and alternate-plan comparison can be selected later.
Shipping, capacity and extensions
Full Version 1 requires all sixteen outcomes and the development agreement's applicable
release checks. Internal catfooding, preview and full release are separate decisions;
earlier builds disclose missing capability/qualification. Dates or effort do not lower scope.
sidecatui's bounded capabilities are required for full release; installation remains
optional on headless nodes. Native-role cutover qualification is specified in the
development agreement and does not wait for a complete full-release client.
The target remains roughly 25,000 concurrent agents across application groups. Qualification starts with a defined 500-caller multi-node workload, then department and organization workloads. This is a sequence, not a single-writer/machine promise. Publish actual hardware, workloads, supported limits and the remaining target gap; a lower launch scope needs an explicit product decision.
Compatible extra applications/features are allowed with deliberate selection, owner, consumer, acceptance and budget. Identify applicable contract obligations and added behavior's acceptance; absence from this table alone needs no amendment. Additions cannot silently displace selected work or weaken outcomes, release scope or firm checks. Such changes and incompatible shared-contract changes require affected-owner decisions and operator involvement where product authority is required. Record dated successors, never silently rewrite accepted agreements. The guide cannot amend either agreement.
Keep documented existing Work behavior until the installed successor provides occurrence completion. Retire the old completion path in that same cutover; do not remove the only working path first or declare old Work records to be Plans. This is controlled internal export/repopulation, not a commitment to retain two public models.
Document history
2 October 2026 — product revision 4: Joshua Gay authorized early UI delivery and every-sprint UI builds and testing, with development revision 3. Prior product revision 3.
29 September 2026 — product revision 3 accepted with development revision 2. Approval record · Approved review text · Previous accepted agreement.