# PRD: Mosaic Stack

- Status: draft, version 0.1. Jason approves it, and once approved it is
  never edited in place. Changes after approval are a new version.
- Owner: Jason. Sage writes it from the PRDY interview.
- Template: PRDY "software" (`v1/packages/prdy/src/templates.ts`), filled
  by hand until PRDY is ported.
- Interview record: Sage's thread 1ef1e4f8. Round 1 was answered on
  2026-10-04 and is recorded as lead decision 45.

## Introduction

### Objective

Working north star, ratified as lead decision 44: "Jason declares
businesses, projects and roles. Agents in those roles carry the work end
to end under declared policy, and only gated decisions reach him."

### Context

See `docs/plans/2026-10-04_foundation-direction.md`. Agents can already do
real work here, but a person has to launch them, relay between them, hand
them credentials and correct them. There's no CLI or complete WebUI for
Jason, and no place where outstanding decisions collect.

## Users

Jason alone for now. The stack must be built so outside users can install
it later: an installer, no paths or names specific to Jason, and
configuration through the variable layers (round 1, answer D).

## Problem statement

In priority order (round 1):
1. **Admin falls on Jason.** He launches seats, relays between them,
   finds credentials and corrects them.
2. **Jason can't see what the agents are doing or what's waiting on
   him.**
3. **Agents drift from what the business needs.** Nothing ties a piece of
   work to a stated goal.

Credential sprawl wasn't picked as a top problem. The roles work and hard
limit C cover it.

## Scope and non-goals

### Hard limits

Every one of these is a gated decision, or simply not done (round 1,
"all five"):
- A. The stack never spends money without Jason.
- B. It never speaks externally as Jason without his approval.
- C. Agents never hold Jason's personal credentials. Each role gets its own.
- D. It is not a multi-tenant SaaS in v1.
- E. It doesn't replace Claude Code, Codex or Pi. It wraps them.

### Where it runs

Self-hosted first, on Jason's machines and homelab (round 1, "A first").
Cloud workers aren't ruled out later.

### In scope for v1

Slice 1 of the foundation direction:
- roles, variables and credentials per role;
- decision records and messages addressed by role;
- tasks in Vikunja through its API;
- the `mosaic` CLI, then the WebUI;
- the meta-harness.

### Out of scope for v1

To be set in round 2.

## Requirements

To be set in rounds 2 and 3. Each requirement gets a stable id
(`REQ-<area>-<n>`). Every task the stack creates must cite one.

## Acceptance criteria and success measures

v1 is done when Jason gives one-sentence requests in the CLI and Mosaic
Stack builds pieces of itself from them, five pieces in a row. For each
piece:
- only gated decisions reach Jason;
- every step leaves a trail in the CLI and the WebUI.

(Round 1, answer A.)

## Technical considerations

Ratified as lead decision 44:
- Vikunja is integrated through its API, never annexed. Mosaic Stack's
  own work uses a dedicated local instance. The installer offers an
  existing instance or the bundled one.
- Decisions and messages live in SQLite, in append-only tables. Run
  records stay as write-once files.
- People sign in through Pocket ID, wired in after slice 1. Agents use
  service tokens per role.

## Risks and open questions

To be set in round 3.

## Milestones

Slice 1 first, in the order on the foundation direction page. The
milestones get set once the requirements exist.