This guide accompanies the product contract, revision 3 and development agreement, revision 2, approved together on 29 September 2026. The guide maintains evolving role groupings, specializations, reading paths and practices. It can change within delegated work, but cannot waive, amend or grant authority under either agreement.
The role map is a working arrangement, not live assignments or proof of qualified native activation. Exact assignments, plans, decisions and evidence belong in Sidecat; progress reports changing facts.
Current role map
A Sidecat Role is reusable responsibility. A Sidecat Actor has a durable identity independent of its assignments and may hold several roles; several actors may hold one role. Role packaging can change with workload and organizational needs while preserving the development agreement's accountability coverage and independent input/review.
The following component and product-wide groupings are working starting points. They are not an exhaustive roster or a requirement for permanent model processes. Name actual owners, exact role revisions and selected scope on the current assignment; do not infer live assignments from these tables.
Component roles
| Sidecat role | Primary responsibility | Boundary it must protect |
|---|---|---|
| Node and bus | Registry, local dispatch, supervision, event/subscription contracts and bounded delivery | Does not absorb domain records or run domain-specific SQL. A new app uses registration instead of daemon surgery. |
| Federation | Peer identity/addressing, remote calls, delivery/recovery and independent administration | A remote call retains its operation meaning and authority; connectivity does not confer access. |
Authorization and resources (sidecat-auth) |
AAuth integration, policy/approval decisions, delegation, budget reservation and reconciliation | Resources have a named authority/accounting owner. No invented authority or spend during a partition. Consume the standalone AAuth library through its public interface. |
AAuth Go (aauth-go) |
Independently maintain the general Go implementation: refresh specification references, assess conformance, guide and implement justified updates | Keep the library useful outside Sidecat. Sidecat-specific policy, branding and integration remain outside its repository. |
| Execution | Prepared environments, commands, adapters, outputs, cancellation and unknown-effect reconciliation | Orchestration asks for execution; the executor reports what actually happened. No duplicate consequential effect after a lost reply. |
| Orchestration | Typed routines/subroutines, durable workflow state and replaceable harness execution | Procedure semantics survive agent/daemon replacement. It does not own Work's meaning or infer success from fluent text. |
| Content and records | Note/content revisions, names, blob references, source links and retrieval | Exact historical content and access are explicit. Does not become the universal business-object or workflow database. |
| Work and planning | Work definitions, Plan occurrences, contextual backlog/board/facet use and multi-project continuity | Work is reusable; occurrence completion stays contextual. Multiple projects do not become competing copies of one work description. |
| Organization | Organizational structure, purpose, principles, portfolios and working context | A statement, adopted policy and effective grant are distinguishable. Domain facts do not themselves grant authority. |
| Roles and actors | Reusable role definitions, named actors, role assignments and activation requirements, composed with existing identity/assignment/execution owners | An actor persists across runs; its selected model is not its business identity. Do not duplicate task queues, credentials or run storage. |
| Messaging | Collective rooms/direct messages, threads, structured references, catch-up and attention | Durable conversation remains useful through turnover, backlog and scope changes. No Work creation merely to send a message. |
| Lisp and composition | Language profile, resident sessions, retained methods and partial execution | One documented language meaning. Interpreters/helpers do not multiply silently or bypass operation authority. |
| Marketplace and packages | Public and self-operated internal marketplace publishing, access, discovery, inspection, distribution and package lifecycle; common vocabulary/shape discovery | Go/Lisp/workflow/role/resource and mixed packages extend ordinary interfaces. Installing roles assigns no actors, grants no permissions and launches no workers. Semantics aid authors without importing domains into core; split stewardship when sustained work warrants it. |
Sidecat UI (sidecatui) |
Open-source operator client: goals/work/roles, conversation, decisions and honest resource visibility | Consume shared Sidecat records and authority. No private competing work state or approvals inferred from chat. Qualify keyboard use, narrow terminals and lead-unavailable operation. |
| Clients and connectors | CLI/MCP projections and external-service adapters | Shared meanings, clear help, structured references and usable errors. Connector-specific behavior remains behind its declared interface. |
An actor holding a component role maintains its contract, local tests and documentation as well as features. A concern outside the assignment goes to its owner or product management. Expanding a component's private ownership requires boundary review, even when its current role groupings change.
Product-wide roles
| Sidecat role | Accountability | Required contribution |
|---|---|---|
| Product manager | Product purpose, scope, acceptance and coverage across component boundaries | Trace each selected outcome to product purpose, applicable requirements and real use; identify missing ownership, duplicate features, orphan work and software-only assumptions; maintain a concise whole-product readiness view. Propose changes to required scope to the operator. |
| Scrum lead / delivery manager | A coherent sprint, dependencies, capacity and visible progress | Gather independent input, select ready assignments with owners, coordinate integration and resolve blockers. Keep new ideas in refinement until deliberately selected. Do not silently change the target or redirect every actor mid-sprint. |
| Systems integration reviewer | Common contracts and the behavior of parts together | Review boundary changes, shared-library growth, database ownership and multi-node composition. Require a focused consumer proof for changed shared contracts. It does not become the author of all components. |
| Call surface and agent usability | Prevent recurring task-discovery, prerequisite, sequencing and recovery failures across applications | Use the call-surface role guidance, relevant existing decisions and installed task evidence. Large official, third-party and local catalogs are expected; assess usability, not their size. |
| QA lead | Quality of the installed product and the evidence for it | Design exploratory, adversarial, concurrency, recovery and unfamiliar-user trials; assess every affected help/man/example path, documentation, code readability and unnecessary tests. Distinguish observed results from participant claims. |
| Release engineer | Exact candidate, packaging, distribution and controlled activation | Produce/reproduce the selected artifact, check evidence matches it, verify installer/publication/rollback, and publish its actual capabilities and limits. Does not decide product scope or waive QA findings alone. |
These roles cover the development agreement's required product, delivery, integration, QA and release functions. One actor can hold several roles, but the implementer cannot be the only reviewer of a consequential change or the only observer qualifying the installed result. The development agreement determines the required coverage and independence; this table describes one way to organize it.
Specializations and working arrangements
A team can group roles, divide a broad role into narrower responsibilities or use subroles for a selected workload. For example, a clients and connectors role might use a specialist for one connector, or QA might distinguish recovery and newcomer trials. These are organizational choices, not a required role-inheritance system. Each selected role states its own scope, obligations, outputs and escalation; shared obligations are referenced explicitly and grants remain separately authorized.
Record the actors holding each selected responsibility and the component and review boundaries before work relies on the arrangement. A refinement of role packaging cannot drop accountability, replace independent input with one lead's answer or make several actors unknowingly edit the same working tree. Qualified execution implementations can change without changing the role's identity.
Product purpose and source-backed views
Version 1 design follow-up requested on 29 September 2026, developing V1-01, V1-02, V1-03, V1-10 and V1-14. The product contract requires product/project context and source references; detailed object and operation contracts still need design and consumer review. These are proposed boundaries, not installed Product/Principle operations or a new approved wire schema.
Purpose, north stars, goals, principles and working guidance are existing core product concerns, not a new optional feature family. The existing call/object surface informs their replacement. A focused check on 29 September found:
| Existing capability | Observed basis | Carry-forward question |
|---|---|---|
| Organization baseline | Installed create/current operations expose direction, principles, constraints, operator statement and separate agent interpretation. | Preserve these meanings and original-versus-interpreted distinctions through the new owner/content boundaries. |
| Working guidance and references | Existing revisioned guidance and named references retain text, purpose, source, status and reader scope. | Reuse exact content and access behavior; remove duplicate authoritative text paths. |
| Project context | Existing Project metadata, Work links, planning and progress records. | Separate durable product scope from project effort without losing existing coordination functionality. |
| Profile, Goal, Practice and Contribution | In-progress local organization-package source and behavior-test definitions; not present in the selected live catalog or qualified by this inspection. | Review with the current owner before designing overlapping objects; carry useful outcomes forward and qualify the installed replacement. |
The existing Gen5 coverage analysis and modularization plan already require this capability mapping. For each selected area, compare intended, implemented and verified behavior; name the new owner and choose reuse, extraction, revision, rebuild or retirement with reasons and acceptance evidence. Search beyond operation names. Do not silently drop a capability because it is absent from a fresh node, and do not preserve a call merely because it exists. The proposed distinctions below must be checked against that source and current owners before implementation.
| Concept | Proposed responsibility |
|---|---|
| Product | Lasting purpose, intended users, scope and desired outcomes, with references to applicable principles and product commitments. Products need not be software. |
| Project | A coordinated effort toward an outcome, linked to the products or organizational goals it serves. Several projects can serve a product; a project can serve several products. |
| Principle | A revisioned statement with rationale and content references. Explicit scoped adoption connects it to an organization, product or project. A principle does not itself become policy, permission or an execution gate. |
| Work and Plan | Reusable Work describes the task/outcome; Plan occurrences carry assignments, sequence, dates and judgments. They refer to relevant product/project context instead of copying it. |
The open-source Sidecat product and a commercial offering can share referenced principles while having different scope and delivery commitments. Organizational structure and policies remain separate from product/project meaning. Resolve applicability and conflicts explicitly; membership or a reference alone does not create automatic inheritance, priority or permission. Component/database grouping is still an implementation decision under the common app contract.
Local definitions, packages and task surfaces
Apply the product contract's fundamentals when choosing how to expose a capability. A user's "north star" can be a named, typed entry under product context, with meaning and applicability defined locally or by a package. It need not become another mandatory core object/verb. Supported owners provide record creation, revisions, queries and relations; domain operations and routines remain discoverable and usable through the common surfaces.
Start with the relevant existing capability, then decide whether to reuse a definition, extend a supported shape, compose a routine or add Go behavior. Workload, invariants and total development cost guide that choice. Go applications can own substantial domain logic; infrequently changed definitions and composition can live in Lisp/data. A technical rule against Lisp owning storage must not silently exclude package-defined persistent records through a storage owner's interfaces. Affected owners review the exact extension contract before implementation relies on it.
A publishing routine can be selected for a project, prepare artifacts and call Git or other effect owners. Its definition, inputs, authority and continuation are inspectable. Hiding required checks in CLI-only wrappers would defeat this design. Package-specific procedures, editorial policies and styles remain optional choices.
The captured discussion uses Boxlab/FPRD as an adopter example: local practices become reusable packages; records can produce a working directory or publication, and selected return mappings can ingest outside work. Its detailed record shapes and procedures remain proposals. The contract's bounded extension qualification does not require shipping the complete research lab, an automatic bidirectional synchronizer or an air-gapped execution product. The full file/Git return journey remains a candidate package trial under that proposal, not a new mandatory Version 1 acceptance path.
Published views and working context
Build toward readable pages and bounded agent context drawn from the same authorized records. A publication view selects exact object/content revisions and maps fields and relationships to displayed headings, text and links. Namespaced labels can serve as anchors without appearing in ordinary prose. Human and agent views can differ; derived summaries and omissions remain identifiable.
Deterministic QA compares the actual presented text and structure with the selected sources: missing/duplicate records, incorrect grouping, changed text and broken references are observable failures. A retained snapshot can be correct even when a newer revision exists. A stamp or matching printed digest alone is insufficient. Unavailable source material produces an explicit inability to verify. Access rules still apply, and publication selects public material rather than exposing a store. For execution, distinguish available records, delivered context and observed effects; a saved packet does not prove understanding or compliance. The current purpose page renders one Markdown source; that representation does not qualify these native features.
Evidence-linked justification
Where a selected policy/workflow requires justification, retain the proposed action, the agent's declared justification and exact supporting references before dispatch. A Work description can lead through its originating Message to the user's exact Note revision. Preserve the difference between original instruction and interpretation; a valid source link alone is not approval for the proposed action.
Evidence coverage is separate from source accuracy. Resolve the applicable recorded instructions, policies, amendments and known conflicts from the work/resource context, not solely from evidence picked by the applicant. Review can request further context; no claim that every relevant fact or hidden model motive is known. Changes to action, artifact or applicable authority require the selected workflow's reassessment. This is configurable assurance, not a mandatory historical audit on ordinary operations.
Qualification should demonstrate a linked product/project/principle, source-backed publication with a deliberately detected mismatch, context delivery with exact source references, and a selected justification review that finds an applicable contradictory instruction despite accurate supporting citations. Fix the evidence and allow an ordinary justified action; stronger assurance remains optional. Preserve these as owned refinement work for later selection; do not redirect the active application qualification cycle merely to implement this discussion.
Development tools and packages
Choose an internal utility or a prepared user task
Use the simplest maintainable home for the actual caller and task. Maintained Node, Python, shell and Go utilities are useful for development and testing; they can call Sidecat where needed. Moving ad-hoc coordination from Python to Node does not itself fix procedure discovery, targeting or call sequencing.
Ordinary users, including agents using smaller models, should receive a prepared task, its data and exact references. They should not reconstruct owners, IDs, request keys and call sequences to do ordinary work. Writing reviewed methods, routines or extensions is author work. Choose a clear task interface and usable recovery; this guidance does not require every tool to be written in Lisp or integrated into the Sidecat runtime.
Packages and usage documentation
sidecat-development-utils should ship as a Sidecat package. Following the
Debian-inspired package model, packages can deliver end-user, development and
testing tools, documentation, resources and mixed content. A package need not
be an application, register on the bus or require full runtime integration.
Declare its contents and dependencies, with instructions for the actual caller.
Version and distribute maintained utilities rather than repeatedly creating
equivalent coordination glue.
Usage documentation and how-to instructions must be discoverable in Sidecat, including for tools that operate only on files, repositories or external services. Keep a named, source-linked reference to the maintained documentation; do not maintain a second manual body for native readers.
Current implementation gap and the agt example
As of 1 October 2026, the portable package format lacks plain-file/resource delivery and installation of a reusable REPL library. This is an implementation gap against V1-07, not a new accepted requirement or proof that these packages already install.
agt should likewise be independently versioned and distributed, preserving
local configuration and login state. The current development installation is
a Bash launcher at ~/.local/bin/agt; its canonical source pointer and package
delivery remain unestablished. This example identifies packaging work, without
requiring a launcher rewrite or changes to active sessions.
Sidecat UI development direction
sidecatui is the new open-source operator-client project and product name.
Start from its required user tasks and selectively port useful Rust terminal
interface code and supporting functionality. Review each dependency and test its
public behavior; do not carry over an entire command surface or compatibility
structure solely because it already exists. A gateway still needed by the client
must be replaced, extracted or deliberately retained before its old implementation
is retired. This is a planned development cycle, not a claim that the new project
has been created or qualified.
The client uses shared Sidecat state for work, messages, roles and decisions. Its marketplace view shows package source and distribution visibility separately from experimental/testing/stable track. Bundled, organization-internal and connected marketplaces are possible source examples, not fixed organization role types. An internal package can be stable; a public package can be experimental. Inspect content/dependencies and access before installation, then distinguish installation, admission, activation and separately authorized role assignment. Start the client in an early selected development cycle. Build its operator-facing views alongside their owning application interfaces, then exercise both on the same installed candidate during QA. Use the client for internal work before cutover. The first useful view can open a project or an isolated test workspace: show its purpose, recent work, active assignments, current tests and observed results. Keep it open during a test to inspect the changes Sidecat actually records. Show the selected environment, source candidate and freshness, including stale/error states. This makes the client a consumer test of the shared interfaces, not a private summary maintained by the lead. Early priorities are operator orientation, communication without a working lead, authorized responses and visibility into model/service availability, reported API credits and prepaid allowance. Use ordinary Sidecat calls for usage and availability: include observation and reset times where supplied, preserve actual worker/model and task attribution, and keep provider-reported allowance, token counters and cost estimates separate. Show observed, estimated, stale and unknown usage explicitly. A missing provider field is not zero, and a reported cost need not be an invoice amount. Detailed analytics, alternate-plan comparison and screen arrangements belong in the evolving roadmap. The initial implementation is a Rust terminal interface; the contract specifies its useful outcomes rather than a particular screen layout.
Summary-first presentation
Prefer an existing title or summary field when the object already provides one. For free-form notes and messages, use a short, understandable first line or opening paragraph followed by details and structured references. Think of a useful commit subject followed by its explanation. This is a writing and presentation convention, not a new universal parser or object schema.
Sidecat UI can show the summary first and let an operator expand the full content. An agent can obtain the structured details and references through the same owning application. Refusals, uncertainty, blockers and requests for decisions must remain visible in the concise view. Preserve the original content; do not maintain competing human and agent bodies just to achieve a different layout. Test whether the summary helps an unfamiliar operator understand what happened and what needs their attention.
Design for the available terminal width and height. Put status and the next action before supporting detail; keep uncertainty visible. Test narrow terminals and keyboard access with real content. Richer reports can use a web view of the same sources. The terminal client does not need to display every detail on one screen.
Start with the assignment
Before a development cycle, identify:
| Reference | What it tells the actor |
|---|---|
| Product/development revisions and digests | Which jointly approved agreements govern the work |
| Actor and selected role-assignment references | Who is responsible and which role revisions apply |
| Work/Plan and current shared state | The outcome, owner, candidate, workspace, budget, stop conditions and next decision |
| Requirement IDs and applicable design rules | What this outcome must satisfy and the boundaries it must preserve |
| Current development checkpoint | Which evidence and accountable roles are needed before proceeding |
| Component contract and actual consumers | The public behavior other applications rely on |
An actor can read a relevant section, an exact captured excerpt, or a prepared context packet. A packet states the source agreement digests and included section anchors, requirement IDs and named table rows. A handoff preserves those references and names any still-needed material. An excerpt is never described as a whole agreement when it is only a selection.
The common reading set
Every selected cycle needs the following information. It can be supplied as bounded excerpts; unrelated components and historical research need not be loaded.
- Product purpose, selected requirements and design decisions.
- Product roles/actors/runs, selected role definitions, assignment scope and effective authority.
- Development accountability, applicable cycle and checkpoint, including independent input, review and installed observation.
- Relevant development risks, context/amendment rules and used component/dependency contracts.
- For capacity, release, publication or cutover, product shipping/scale constraints and development cutover qualification.
These readings include the 25,000-agent target, initial 500-caller qualification, explicit lower-scope decision, and distinct internal-catfood/preview/full-release claims when relevant. Select the necessary paragraphs, not the whole history.
The assigning owner selects applicable material and checks the selection for missing obligations. An actor reports a material gap when its assignment cannot be checked from what was supplied. This is targeted orientation, not a requirement to summarize every section or repeatedly load the full document.
Reading by role
These paths can evolve as the role map changes. They are starting points. An assignment that crosses a boundary also needs the affected component's contract and its consumer's requirements.
| Sidecat Role | Read in addition to the common set | Decision it contributes |
|---|---|---|
| Product manager | Full product requirements, design and shipping/scope; development accountability, risks and cutover rules; selected role definition | Does the outcome serve the product, cover its requirements and preserve the agreed scope? |
| Scrum lead / delivery manager | Development cycle and checkpoints; participating component roles; current assignments, capacity, dependencies and continuation | Is one coherent outcome ready with owners, review coverage, budget and stop conditions? |
| Systems integration reviewer | Product interface, ownership, storage, federation and composition rules; development dependency decisions; affected component contracts and consumer evidence | Can independently developed parts rely on the change without hidden coupling or conflicting meaning? |
| Component maintainer | Its component-role row and requirement IDs; used dependency contracts; development surface/testing discipline and checkpoints | What must this component own, expose, test and remove? |
| QA lead | Development surface/testing discipline, assessment checks, independence, risks and current acceptance; product shipping/scale when relevant; affected docs | What does the installed candidate prove, what failed and what remains unqualified? |
| Release engineer | Product installation/distribution/execution requirements and shipping/scale; development release/publication checkpoints; artifact/configuration, installer/recovery/rollback and cutover | Is the artifact reproducible and qualified for this destination and scope? |
| Roles and actors maintainer | V1-10 and product native lifecycle/context; development assignment context and launch/cutover qualification; Work/Plan, Messaging, orchestration, execution and auth contracts | Are roles reusable, actors addressable offline and actual runs attributable without duplicate identity or queues? |
| Marketplace and packages maintainer | V1-07 and package lifecycle; public/internal hosting/access, Go/Lisp/workflow/role content; dependency decisions and independent author/consumer trials | Can authors deliver and organizations operate their own marketplace without implicit actor assignment, trust or authority? |
| Sidecat UI maintainer | V1-16 and operator outcomes; Work/Plan, Messaging, roles/actors, auth/resource interfaces; development internal-client QA | Can an operator understand and direct work when the lead is absent, using shared work and authority? |
The current groupings are in this guide's component roles and product-wide roles tables. The development agreement's accountability coverage and development checkpoints remain mandatory regardless of the grouping. The current manual role kit is preparation for native role assignment and activation. Its files and credential profiles do not establish that the native actor lifecycle is implemented.
Apply the cycle
| At this point | Read/check | Leave in Sidecat |
|---|---|---|
| Select an outcome | Product purpose, relevant requirement rows, role input, current evidence and capacity | Outcome, selected Work/Plan, owners, independent review coverage, budget and stop conditions |
| Approve implementation readiness | Concrete component calls, object ownership, failure behavior, consumers and reuse/rebuild reason | Reviewed spec/plan and any shared-contract disposition |
| Integrate | Exact source, appropriate failing/passing behavior evidence, independent review, docs and removal decisions | Findings and their disposition; exact integrated candidate |
| Build and install | The integrated source, packaging and supported configuration | An exact usable candidate for independent testing |
| Qualify an installed candidate | Functional, failure/recovery, concurrency, unfamiliar-user and documentation evidence | Scoped QA decision with observations and limits |
| Publish or cut over | Product acceptance, valid QA decision, authority/destination, installer and recovery plan | Release/activation decision and the exact artifact |
| Review the cycle | Delivered and undelivered outcomes, evidence, cost and coverage gaps | Disposition of unfinished work and a deliberate next outcome |
These are views of the development agreement's firm checkpoints. They do not turn guidance into an executable workflow. Until the selected procedure is implemented and qualified in Sidecat orchestration, the lead records how its decisions were applied and discloses the checks that remain manual.
Testing the delivered build
Prepare QA charters during development. Run release QA and unfamiliar-user trials after the candidate is built, installed and usable, before release. Test the artifact and shipped documentation. Developer tests and source review provide earlier evidence; they do not replace this stage. A repair produces a new candidate and repeats the affected installed checks.
Choosing reliability work
When recovery, consistency, audit or other reliability work consumes a substantial part of a cycle, reconsider its scope and timing. Name the real user task, the required behavior, and any extra guarantee we chose. Compare a simpler sufficient design and a shared mechanism where several applications need the same behavior. Existing code placement is a revisable choice.
Assess internal development use, short external trials and production qualification separately. Invest where the benefit justifies the cost; defer work that is unnecessary for the selected use, with its limit stated clearly. Hold only the scope that depends on it. Small, useful repairs need a proportionate decision; this review should not become another costly process.
Surface and documentation pass
At planning, select the public operations and user tasks affected by the slice. At integration, check the shared contract and the relevant projections below. The development surface/testing checks set the obligation; this table is the working checklist.
| Surface | Check |
|---|---|
| argv / CLI | Discovery, help, inputs, readable and structured results, errors and next steps |
| MCP | Descriptions and schemas, discovery, invocation, structured results and recovery information |
| Sidecat Lisp | Operation inspection, composition, typed values and consistent effect/continuation semantics |
| Native client / bus | The same operation contract and applicable event/subscription behavior |
| Sidecat UI | The relevant operator task, selected project/environment, fresh/stale state and useful error recovery |
| Documentation | Affected man pages, examples, user and author guides, README, llms.txt and web instructions |
Prefer one operation descriptor with generated projections to manually maintained copies. A new app should not require editing core routing or several independent command implementations. During each release cycle, exercise every supported call surface and the available UI paths on the installed candidate, using common acceptance scenarios with surface-specific discovery and recovery checks. Record any missing projection or outdated explanation. Declare unaffected surfaces explicitly when the relationship is not obvious; do not summon every reviewer or repeat the whole product suite for a private implementation change.
Revision and capture
The accepted product contract is architecture/version-1-contract.md, revision 3.
The accepted development agreement is architecture/version-1-development.md,
revision 2. Both were approved on 29 September 2026. This evolving guide is
architecture/version-1-reading-guide.md.
Captures identify each applicable agreement's exact digest, headings, requirement IDs, named accountability/checkpoint rows and selected role revisions. They may name the guide revision used for selection; filenames alone do not pin an agreement.
An active assignment retains its selected agreement/role revisions until authorized amendment. Revised reading paths cannot replace them silently; pinning does not preserve expired or revoked authority. Adoption identifies each accepted successor explicitly.
Accepted source digests:
- Product:
sha256:5f60dcb981a0cabce8f3b33f2c4d1138a27d7dbd03b0fea7a3b29279bae043b7. - Development:
sha256:2f712bd83fb40459fe5a5a819893e61855e794cf82a7cbde6e17800687760537.