Sinaris Technical Design

This document describes the current implementation architecture of Sinaris. It is the technical companion to Product Architecture.

1. System Shape

Sinaris is a .NET CLI tool with an embedded local Hub. It stores project state per workspace, installs host-agent assets, exposes a machine-readable CLI protocol, and records structured agent events for handoffs.

2. Project Layout

Project	Responsibility
Sinaris.Domain	Domain models and simple domain invariants.
Sinaris.Application.Contracts	DTOs and application service contracts consumed by CLI and Hub.
Sinaris.Application	Use cases, workflow gates, orchestration between repositories, protocol-facing application logic.
Sinaris.Infrastructure	EF Core SQLite, repositories, migrations, transcript persistence adapters, filesystem-backed stores.
Sinaris.Cli.Protocol	Command declaration attributes, command registry, CLI result model, metadata contracts.
Sinaris.Cli.Generators	Source generator that turns attributed command classes into command registry metadata and adapter helpers.
Sinaris.Cli	CLI entry point, command handlers, Hub host, embedded assets, workspace asset management.
Sinaris.Architecture.Analyzers	Architecture diagnostics that prevent forbidden dependencies and unsafe data-access shortcuts.

3. Command Protocol

Sinaris commands are declared in attributed classes such as TaskCommands, AgentCommands, GuideCommands, ProposalCommands, MilestoneCommands, PhaseCommands, EvaluatorCommands, MetaCommands, RecoveryCommands, plus root commands init and hub.

The generator builds a framework-agnostic command registry. SystemCommandLineAdapter adapts that registry to System.CommandLine.

Design rules:

• command definitions live in one place;
• every command returns Task<CliCommandResult>;
• OutputFormat is the shared text|json vocabulary;
• command metadata is available at runtime through meta list and meta schema;
• CliToolInfo owns tool name, normalized public version, and build date.

JSON Contract

Agents and automation should use --format json.

Failure shape:

{
  "ok": false,
  "error": {
    "code": "validation",
    "message": "task id is required"
  }
}

State-changing success shape:

{
  "ok": true,
  "message": "Task completed.",
  "data": {
    "id": "task-id"
  }
}

Data commands can still return their natural JSON payload when the payload itself is the contract.

4. Persistence

Sinaris is local-first. Each workspace has a SQLite database stored under the user-level Sinaris workspace directory. The active workspace is resolved from the project root and passed through workspace-scoped services.

The database stores runtime state and indexes:

• project context projections;
• proposals, milestones, phases, and tasks;
• task logs and task dispatches;
• agent sessions and session events;
• structured AgentEvent records;
• evaluator journeys and runs;
• workspace registry entries and generated asset metadata.

Markdown files remain the human/agent-readable source for business prose. The database stores the registered resource state and indexes.

Schema Evolution

EF Core migrations own schema changes. Runtime code must not issue ad hoc raw SQL migrations before every CLI or API request. This avoids SQLite contention and keeps schema ownership auditable.

When initialization detects a database that cannot be migrated safely, destructive repair is an explicit init path with backup and user confirmation.

5. Workspace Registry And Asset Versioning

The workspace registry powers the Hub workspace switcher and asset status.

Tracked state includes:

• workspace id;
• root path and display name;
• initialization state;
• asset status;
• installed tool version;
• available tool version;
• last opened and last seen timestamps.

Upgrade detection follows the public Sinaris tool version, normalized without build metadata. This keeps UI messages short and avoids treating two builds of the same semantic version as distinct product upgrades.

The registry currently stores version metadata inside the existing asset metadata JSON rather than adding ad hoc schema changes outside migrations.

6. Workflow Services

Guide

Guide services validate and publish project context. They must preserve runtime state that does not belong to Guide, such as proposal-derived milestones and task progress.

Proposal

Proposal services manage deferred persistence, stage validation, context action, and prepare-design gating. Proposal state advances through commands and services, not by editing markdown.

Milestone And Phase

Milestone and phase services register authored markdown resources. Phase registration links the design to a milestone and optionally to a proposal. task batch then creates ready tasks under that phase.

Task Execution

Task services enforce:

• readiness before claim;
• current phase and context drift gates;
• ownership for complete/fail/release;
• one task per active agent session;
• parent/child structure and auto-complete behavior;
• evidence expectations when context snapshots are active.

task next, task claim, and explicit task claim --task must remain consistent. A specific-task claim cannot bypass the scheduler's eligibility rules.

Decisions

task decision-request pauses a task for user input. task decision-resume records the user's decision and dispatches a structured continuation event to the owning session.

This is preferable to failing the task when the correct next step is a product or design decision.

7. Agent Event Pipeline

AgentEvent is the structured handoff unit between Sinaris and agents.

Important components:

Component	Responsibility
AgentEvent	Domain record for schema version, event type, source, target session, task reference, dispatch id, user payload, and facts.
IAgentEventStore	Append and query structured events.
AgentEventDeliveryService	Record events and optionally enqueue rendered messages atomically.
AgentEventPromptRenderer	Convert events to JSON payloads embedded in an agent-readable message.
TaskContinuationDispatcher	Supersede active dispatches and deliver decision/continuation events.

The event pipeline makes handoffs auditable and avoids treating natural-language notifications as the product protocol.

8. Agent Activation

AgentActivationAppService decides whether a known session should be activated.

Activation checks runtime readiness:

• busy agents are skipped;
• agents without auto-activation capability are skipped;
• pending dispatch messages are delivered first;
• auto-claim wake-up only applies to offline sessions with auto-claim enabled and claimable work.

When activation happens, Sinaris builds a platform-specific resume command through the resume adapter. It resumes a recorded session; it does not create a replacement session for continuation paths.

The resume prompt contains structured facts. The SKILL decides how to act.

9. Session Detail, Activity, And Transcripts

AgentSessionDetailAppService builds the session timeline from three structured sources:

• session lifecycle events;
• AgentEvent records;
• task logs.

Transcript references are optional supporting context. They are displayed when available, but they are not the source of truth for product state.

This design lets the Hub explain what happened even when raw host transcripts are incomplete, unavailable, or contain events Sinaris does not recognize.

10. Hub Backend

sinaris hub hosts an embedded ASP.NET Core application bound to the local machine. The Hub serves static assets and workspace-scoped REST endpoints.

Endpoint rules:

• current APIs are scoped under /api/workspaces/{workspaceId}/...;
• legacy unscoped APIs return a gone response pointing to the workspace-scoped route;
• read endpoints open the selected workspace without repairing assets or running migrations as request side effects;
• mutation endpoints route through application services and return domain-level errors as HTTP responses.

Hub is a projection. It must not duplicate task readiness, assignment, phase gate, or asset upgrade logic in frontend JavaScript.

11. Generated Assets

sinaris init installs managed assets for supported host agents:

• hooks and wrapper scripts;
• Cursor command files such as /sx-guide, /sx-proposal, /sx-design, /sx-apply;
• Sinaris SKILL files;
• host instructions.

Assets include the Host Agent Mode Boundary so host-native planning modes do not take over Sinaris workflows.

Asset overwrite is explicit. Missing or outdated assets should lead users to sinaris init or sinaris init --force; normal CLI/API requests should not silently rewrite the workspace.

12. Evaluator

Evaluator models delivery confidence through user journeys and runs.

The technical contract includes:

• journey listing, validation, enable/disable, stale/current/retired lifecycle;
• run creation with scope and optional assigned agent;
• run detail, explanation, result submission, cancellation, abandonment, retry;
• human review confirm/reject flows.

Evaluator belongs after Design and Apply because implementation task completion is not the same as product readiness.

13. Error Handling And Safety

Design choices:

• use structured CLI error codes for agents and automation;
• avoid fail-open behavior for missing workflow prerequisites;
• require interactive confirmation for destructive init paths;
• keep database migration under EF Core migration ownership;
• keep host hook diagnostics separate from business state;
• enforce session ownership at task mutation boundaries;
• expose explicit queue and runtime state instead of guessing from transcripts.

14. Testing Strategy

Tests should match the architecture boundaries:

• unit tests for domain behavior, protocol formatting, services, projections, and parsers;
• subcutaneous tests for command/application handlers with fake process and filesystem boundaries;
• no tests that start real CLI processes, shell scripts, dashboard servers, external agent CLIs, or real HTTP listeners;
• file IO in tests should use injectable filesystem abstractions;
• asset tests should validate loader behavior and structured contracts, not broad brittle string assertions.

The goal is confidence in contracts and invariants, not snapshot-testing entire documents or UI text.

15. Packaging And Release

Sinaris is packaged as a .NET global tool:

<PackAsTool>true</PackAsTool>
<ToolCommandName>sinaris</ToolCommandName>
<PackageId>Sinaris.Cli</PackageId>

sinaris --version prints the normalized public version and build date. Production release is driven by Git tags that trigger CI publish.

16. Technical Principles

• Prefer structured protocol over prompt scraping.
• Prefer application services over UI-side business logic.
• Prefer SKILL policy over product-owned agent orchestration.
• Prefer explicit state transitions over inferred side effects.
• Prefer one authoritative service per capability.
• Prefer schema-owned migrations over request-time raw SQL.
• Prefer structured tests over brittle content matching.