Architecture Overview

A dispatch trajectory — every command, redaction, and cost, captured in-repo.

Stet's design is captured in 17 Architecture Decision Records (MADR format) and 3 specifications. Eight ADRs are accepted (the core product); nine are proposed (the expansion themes, captured during active ideation and not yet locked). This page is a themed index — read the Concepts & Glossary first if the vocabulary is new.

1. Accepted core

The eight decisions that define the product.

• ADR-0001 — Target platform & UI framework · accepted — macOS 26 + Apple silicon only; SwiftUI-first with native Liquid Glass.
• ADR-0002 — Viewer-first application posture · accepted — a code viewer and direction surface, not an editor; inbox-first, document-less.
• ADR-0003 — Pluggable container runtime · accepted — local sandboxes behind one abstraction: Apple container and Docker, both first-class.
• ADR-0004 — Pluggable agent harness adapter · accepted — OpenHands, Crush, and Pi behind one protocol; bring-your-own OpenAI-compatible model.
• ADR-0005 — Declarative YAML markup-verb workflows · accepted — emoji/comment verbs bind to YAML workflow definitions run by a lightweight local executor.
• ADR-0006 — Feedback review & brief compilation · accepted — markup accumulates, then Submit compiles it into one coherent brief → one PR.
• ADR-0007 — Forge integration & authentication · accepted — GitHub + Gitea via OAuth, tokens in Keychain, local git via SwiftGit2.
• ADR-0008 — AI-authored PR narration · accepted — every AI-authored PR must emit a structured guided walkthrough (Tour mode).

2. Running-artifact review (proposed)

Review the running product, not only its source.

• ADR-0009 — Live web-target markup · proposed — an embedded browser on the sandbox's dev server; mark up the live web UI as you use it.
• ADR-0010 — Desktop screenshot-to-narrative · proposed — a vision model reads a screenshot of a native app and maps regions back to source.

3. The project learns over time (proposed)

• ADR-0011 — Trajectories as versioned artifacts · proposed — commit each dispatch's full trajectory in-repo, as the branch's final commit, reviewable like a file.
• ADR-0012 — Skill distillation flywheel · proposed — distill reusable skills from trajectories + feedback + outcomes, committed back and injected into future dispatches.

4. Making it social (proposed)

• ADR-0013 — Collaboration & the social layer · proposed — the forge as social backbone; an embedded Dolt store for rich markup, threads, and votes.
• ADR-0014 — Agentic social voting · proposed — humans and agents vote on hunks/skills/trajectories; humans decide, agents advise.

5. Versioned config topology (proposed)

• ADR-0015 — The .stet topology & tiered primitives · proposed — three versioned levels (user/org/project) for Agents, Skills, and Verbs; precedence + pins.
• ADR-0016 — Agents as a first-class primitive · proposed — a named, configured actor (harness + model + persona + skills + verbs + guardrails), distinct from the harness.
• ADR-0017 — Composable, importable configs · proposed — YAML configs; a .stet can import other .stet repos, with GPG-signed-ref trust.

Specifications

Each capability is a paired artifact — spec.md (requirements) and design.md (rationale).

• SPEC-0001 — App Foundation — the native shell: sign-in, the PR/file inbox, and the reading canvas (implements ADR-0001, 0002, 0007).
• SPEC-0002 — Feedback Review — the core loop: markup verbs, submit → brief, and Tour mode (implements ADR-0002, 0005, 0006, 0008).
• SPEC-0003 — Agent Dispatch — the engine: container runtime, harness adapter, workflow executor, and PR creation (implements ADR-0003, 0004, 0005).