Sinaris Product Architecture

Sinaris turns AI coding from one-off chat into a trackable, resumable, collaborative delivery workflow.

The product is built around an AI-native boundary: Sinaris provides durable facts, structured tools, runtime state, and safety invariants; the coding agent uses SKILLs to decide how to ask, design, execute, verify, continue, or stop.

1. Design Philosophy

Sinaris is not an agent that tries to own every workflow decision. It is a local-first control layer for AI coding work.

Layer	Owns	Should not own
Product code	Resource identity, state transitions, ownership checks, phase gates, event persistence, Hub projections, CLI/API contracts	Business prose, implementation judgment, task-by-task reasoning, hidden orchestration loops
SKILLs	Workflow policy, one-question loops, Apply behavior, TDD and verification discipline, drift handling, continuation decisions	Database invariants, concurrency, authorization, durable state
Human	Product intent, final decisions, trade-off acceptance, release confidence	Reconstructing state from chat history or manually synchronizing Agent sessions

This boundary keeps Sinaris professional and adaptable:

• product code remains stable, testable, and focused on correctness;
• Agent behavior can evolve through generated SKILL assets without hard-coding every policy branch;
• humans can review the rules agents follow because they are written down;
• a misbehaving agent cannot bypass ownership, readiness, or persistence rules because those remain code invariants.

2. Architecture Overview

The important point is not the technology stack. The important point is ownership:

• Markdown stores reviewable project facts.
• SQLite stores runtime state and indexes.
• CLI/API services are the only path for state transitions.
• Hub displays and invokes application services; it does not duplicate domain rules.
• SKILLs tell the agent how to use the tools.

3. Information Surfaces

Surface	Audience	Owns	Examples
Workspace markdown	Humans and agents	Durable business facts and design prose	.sinaris/context/*.md, proposals, milestones, phase designs, Apply work packets
SQLite workspace database	Sinaris and Hub	Runtime state, indexes, ownership, dispatches, events, evaluator state	tasks, task logs, sessions, AgentEvent, phase and milestone records
CLI protocol	Agents, hooks, scripts, Hub backend	Discoverable command surface and structured output	--format json, meta schema, error and success envelopes
Generated workspace assets	Host agents	Workflow instructions and host integration	.cursor/commands/sx-*.md, .cursor/skills/sinaris-*/SKILL.md, hooks, host instructions
Workspace registry	Hub and CLI	Known workspaces and asset upgrade status	display name, root path, installed tool version, available tool version

Two constraints follow from this model:

1. Editing Markdown must not secretly change runtime state. The agent writes facts, then registers them through CLI commands.
2. Runtime state must not be inferred from chat transcripts. Transcripts are useful context, but the product contract is structured state and structured events.

4. Workflow Model

Sinaris has two entry paths and one shared execution loop:

• Guide is for a new project or unclear direction. It establishes project goals, users, value, scope, decisions, open questions, and the initial milestone roadmap.
• Proposal is for a concrete new demand in an existing project. It shapes one change at a time and decides whether it creates or updates project context.
• Design converts confirmed direction into a phase design and ready tasks. Apply must not invent missing design decisions.
• Apply claims and executes one task at a time with ownership, context, evidence, and verification.
• Evaluator checks whether important user journeys and release confidence still hold.

The product does not collapse these flows into a single prompt. The separate entry points are part of the architecture because the decision quality needed for a new product is different from the decision quality needed for one new requirement in an existing product.

5. Stage Contracts

Guide

• Agent-driven through the generated /sx-guide command and Guide SKILL.
• Produces project context markdown and publishes it through sinaris guide publish.
• Guide publish synchronizes context without resetting unrelated runtime state.
• Done when the user confirms the project basis and no blocking open question remains.

Proposal

• Agent-driven through the generated /sx-proposal command and Proposal SKILL.
• Discussion is deferred until the user confirms the Final Proposal Summary.
• The agent allocates a proposal path, writes proposal markdown, checks it, and publishes it.
• The proposal state machine is Draft, Designed, Applied, Rejected.
• ContextAction describes whether the demand creates a milestone, updates one, updates the project, records a decision, or requires multiple context changes.

Milestone

• A milestone is a project resource, not Guide's private state.
• Proposal-derived milestones are registered through milestone commands instead of rerunning Guide.
• Republished Guide context must not delete proposal-derived resources or reset progress.

Design

• Agent-driven through the generated /sx-design command and Design SKILL.
• Produces phase design markdown and registers it through phase save.
• The design sufficiency gate covers goals, non-goals, acceptance criteria, scope impact, ownership, state and data flow, trade-offs, testing strategy, and Apply readiness.
• Proposal-linked designs must pass the proposal gate and must target the expected milestone.

Apply

• Agent-driven through the generated /sx-apply command and Apply SKILL.
• Works on one task at a time.
• task next, task claim, and explicit task claim --task share the same readiness and current-phase checks.
• task complete and task fail require the owning session when the task is owned.
• Completion and failure messages must carry useful evidence, especially Criteria: and Risk: when context snapshots are active.
• If the agent finds a product or design gap, it requests a decision or returns to Guide, Proposal, or Design instead of guessing.

6. AgentEvent As Structured Agent Input

Sinaris uses AgentEvent as the structured event vocabulary for agent-facing handoffs.

Current event types include:

Event type	Purpose
task.assignment_requested	A task was assigned or launched for a target session.
task.continuation_requested	A paused or in-progress task should continue.
task.decision_resumed	A user decision is available for a task waiting on input.
queue.auto_claim_available	Claimable work is available for an auto-claim-enabled agent.
session.resume_context	Resume context is available for a recorded session.
user.message_received	A user message was queued for an agent session.

An AgentEvent records the schema version, event id, source, workspace root, target session, optional task reference, optional dispatch id, user payload, and structured facts. AgentEventPromptRenderer renders this into a JSON block for the agent, so the handoff is machine-readable and auditable.

This is the AI-native version of a notification: the product states facts, not a hidden workflow script. The SKILL decides what to do with the event.

7. Activation And Continuation

Sinaris supports activation without turning product code into a workflow orchestrator.

There are two activation paths:

• Dispatch delivery: manual assignment, decision resume, or user message creates a queued message for a known session. Activation resumes that recorded session and delivers the structured event payload.
• Auto-claim wake-up: when an offline, auto-claim-enabled session has claimable work, Sinaris records queue.auto_claim_available and resumes the session with that fact.

Activation must respect these boundaries:

• do not create a replacement session when the contract is to resume a recorded session;
• do not wake busy agents;
• do not encode Apply's full decision tree into product code;
• let the Apply SKILL decide whether to claim, continue, pause, or stop after reading the event and queue status.

8. Hub Projection

The Hub is the human runtime view over Sinaris state.

It shows:

• Plans: Guide context, proposals, milestones, phases, and readiness.
• Board: claimable work, ownership, task status, parent/child structure, and dispatch state.
• Activity: session events, task logs, structured AgentEvent items, and optional transcript references.
• Agents: runtime state, aliases, current task, queued messages, auto-claim setting, resume capability, and transcript detail.
• Evaluator: user journeys, run lifecycle, delivery gate status, evidence, and human review.
• Workspaces: known workspace list, current workspace, and asset upgrade state.

Hub endpoints are workspace-scoped. Legacy non-workspace routes return a gone response that points to /api/workspaces/{workspaceId}/.... This keeps the UI aligned with the selected workspace and avoids accidental cross-workspace operations.

9. Workspace Assets And Tool Versioning

Generated assets are part of the product contract because they teach host agents how to use Sinaris.

Asset maintenance follows simple rules:

• sinaris init installs managed hooks, commands, SKILLs, and host instructions.
• sinaris init --force is the explicit destructive path for regenerating managed assets.
• Regular commands may detect that assets need maintenance, but they do not repair or overwrite assets.
• Hub workspace switching shows whether the workspace is current, missing assets, modified, unsupported, or has an upgrade available.
• Upgrade detection follows the Sinaris CLI tool version. Public versions are normalized without build metadata, so the Hub does not show long +sha strings or compare two builds of the same semantic version as different product versions.

This keeps the mental model clear: when the tool version changes, generated workflow assets may need to be upgraded.

10. CLI Protocol

The CLI is a protocol surface, not just a human command runner.

Key protocol rules:

• Commands that produce structured data accept --format text|json.
• --format json is the stable contract for agents, hooks, Hub internals, and automation.
• Failures under JSON mode emit a structured error envelope with a stable error code.
• State-changing commands without a data payload emit a success envelope.
• sinaris meta list --format json exposes command discovery.
• sinaris meta schema exposes the nested command tree, options, arguments, enum values, and stdin payload shape.
• CliToolInfo is the single source for tool name, public version, and build date.

Agents should discover the protocol instead of scraping help text or hard-coding command surfaces.

11. Host Agent Mode Boundary

Sinaris workflows must not be silently converted into a host agent's native planning mode.

Generated command wrappers and SKILLs include a Host Agent Mode Boundary: while running a Sinaris workflow, the agent should not enter Cursor Plan mode, Copilot plan/build-plan mode, or any equivalent host planning mode that can later execute outside Sinaris gates.

The reason is architectural, not cosmetic. Sinaris needs Guide, Proposal, Design, Apply, and Evaluator to remain the workflow contract. A host-specific plan mode can capture the conversation and later execute it as a separate plan, bypassing Sinaris state, gates, task ownership, and evidence.

12. Current Implementation Map

Architecture element	Current implementation
CLI protocol and generated command registry	Sinaris.Cli.Protocol, SystemCommandLineAdapter, MetaCommands
Project context and Guide publish	GuideCommands, GuideCommandHandler, project context stores
Proposal state and design gate	ProposalCommands, ProposalGateService, PhaseDesignAppService
Milestone and phase resources	MilestoneCommands, PhaseCommands, phase and milestone application services
Task scheduling and ownership	TaskCommands, TaskCommandHandler, task application services, readiness gates
Decision pause and resume	task decision-request, task decision-resume, continuation dispatcher
Agent sessions and activation	AgentCommands, AgentActivationAppService, platform resume adapter
Structured agent events	AgentEvent, IAgentEventStore, AgentEventDeliveryService, AgentEventPromptRenderer
Session timeline and transcript detail	AgentSessionDetailAppService, transcript refs and providers
Hub projection	HubCommand, workspace-scoped Hub endpoint registrations, frontend assets
Workspace registry and asset status	WorkspaceAppService, WorkspaceRegistryStore, IWorkspaceToolVersionProvider
Evaluator	EvaluatorCommands, evaluator application services, Hub evaluator view
Init and destructive boundaries	InitCommandHandler, WorkspaceAssetManager, database initializer

13. Design Principles

• One capability has one owner. Do not spread the same rule across CLI handlers, Hub JavaScript, SKILL text, and repositories.
• Product code owns invariants. SKILLs own workflow judgment.
• Markdown stores facts and design prose; SQLite stores runtime state.
• Every state transition enters through application services.
• Agent-facing messages should be declarative and structured.
• Hub is a projection and operation surface, not a parallel domain model.
• Protocols should be discoverable at runtime.
• Missing or contradictory state should stop the flow or return to the correct earlier stage; do not hide it with defensive fallback behavior.
• Asset upgrades follow the public Sinaris tool version.
• Host agent modes must not bypass Sinaris workflow gates.

14. Follow-Ups

• Continue tightening Evaluator as the delivery confidence loop after Design and Apply.
• Expand explicit resource primitives for proposal context actions beyond milestone creation/update.
• Keep phase design lint focused on meaningful Apply readiness instead of brittle text matching.
• Evolve multi-agent retry, preemption, and attribution rules without turning product code into an agent policy engine.
• Keep transcript parsing as supplemental context; structured state and AgentEvent remain the product contract.