stack/docs/plans/2026-10-04_foundation-direction.md

Foundation direction: build the system, then measure it (2026-10-04)

Status: Sage proposed it and Jason ratified it on 2026-10-04 (lead decisions 43 and 44). It supersedes the north star and the goal order on the 2026-09-27 goals page (docs/plans/2026-09-27_goals-review.md). That page's 2026-10-04 section has the details.

Why this page exists

On 2026-10-04 Jason rejected the KPI line of work, verbatim:

Let's put some intelligence behind the question of the KPIs. Reduction of necessary human interaction is good. But:

• Reduced in what way?
• What automations do the agents handle without interaction?
• How do the agents know where to steer?
• How do we establish the north star with clear direction?
• Who makes the decisions about conflicts?

We are chasing the reduction of human interactions without building the system properly to keep the direction true.

The brain dump in the same message, verbatim:

Mosaic Stack must provide separation of duties for agents. Project Manager, CEO, CFO, CTO, CMO, CIO, COO, etc. must all be declarable and have strict adherence to protocol.

The stack must:

• provide the ability to mint credentials
• provide credentials
• declare variables per system, business, workspace/project, agent
• enable inter-agent communications
• enable agent-level, proactive decision making
• enable surfacing of outstanding decisions
• track open tasks in a project management platform (Vikunja) with agentic capability to fully manage the tasks, dates, assignments, and all aspects of the system. Perhaps just annex the Vikunja code INTO Mosaic Stack??
• reduce the human interaction by intelligently handling things that don't need the human to make a decision
• use PRDY to establish the PRD and north star
• adapt to the needs of the user to provide options when appropriate, and avoid the presentation of interruptions where not needed
• provide a meta-harness for Claude, Codex, Pi, and other providers with the skills, system prompt, hooks, etc. to establish the system

If we are able to focus on the establishment of the system, establish the controls, tools, skills, system prompts, etc., we will necessarily address the KPIs over time. Then we can isolate an area of deficiency and optimize.

I don't have a functional system yet for Mosaic Stack. We have been able to surface some level of interaction within the system, but not yet providing a full webUI for interaction. Actually, I don't have a cli for interaction either. Therefore, we should be focused on establishing the basal systems, interface, messaging, cli/tui, webui, task management, profiles, and build upon those foundations. Without a system to measure, we can't iterate and improve.

Sage agrees. The ledger brief (2026-10-04_ledger-kpi-guideposts.md, row 32) tries to sort Jason's chat messages by hand into "decision" and "overhead". It has to work that way because the system has no decision object to count. That's a missing piece of the system, not a missing metric.

The five questions

1. Reduced in what way?

Jason's messages fall into three kinds.

• Decisions only he can make: direction, money, authority, outward communication, taste. These stay. They should cost less: batched, each with a recommendation, answerable in one word, and never asked twice.
• Admin the system should do: launching seats, relaying between them, finding a credential, asking for status, correcting drift, and asking "did you actually start?". These go to zero by building the missing parts, not by asking agents to try harder.
• Interruptions that aren't decisions: questions an agent could have settled under policy. These go to zero by declaring, per role, what it may decide.

Fewer messages follows from those three. It isn't the target.

2. Which automations run without Jason?

That depends on the decision's class and on the role that holds it. It's declared in policy, not left to each agent's judgment.

Class	Examples	Who decides
Routine	naming, approach, tests, docs, retries	the agent doing the work
Within a role, reversible	assigning and scheduling tasks, reviews, pushing reviewed work to the working branch	the role holder; logged
Across roles	two roles want opposite things, or one role's work blocks another's	the arbiter role named for that business
Gated	spend, minting credentials, outward communication, merge to main, deploy, policy or role changes, the PRD	the human

This table is prose in AGENTS.md today. It has to become data in each role's file under roles/, so a harness hook can enforce it and the decision inbox can sort by it.

3. How do agents know where to steer?

A chain every piece of work must sit in: PRD (objective, non-goals, success measures) → goals → milestones → tasks. A task names the PRD requirement or goal it serves, and a task with no parent can't be created. That check fails closed. An agent choosing work reads up the chain.

Today the chain is loose. The goals page leads to queue rows, and rows lead to briefs. No row cites a requirement id, because no PRD exists.

4. How is the north star set?

With PRDY. In v1 it's a package (v1/packages/prdy, about 1,500 lines of TypeScript, 20 tests) plus a skill (v1/skills/mosaic-prdy). It holds:

• a guided interview that asks a few questions with lettered options;
• section templates (problem, scope and non-goals, requirements, acceptance criteria, risks, milestones, success measures);
• a lifecycle of draft → review → approved → archived;
• successor versions on conflict, so an approved PRD is never edited in place.

The north star of a business or project is its approved PRD's objective, non-goals and success measures. Only the human approves a PRD.

Mosaic Stack needs no code to start this. Sage can run the PRDY interview with Jason by hand, using v1's template, and write the first PRD for Mosaic Stack itself. The port to code comes later, once the shape is proven.

5. Who decides conflicts?

Each business declares an order. A conflict inside one role's domain goes to that role's holder. A conflict between domains goes to the named arbiter (CEO for business questions, PM for delivery order, CTO for technical ones). Anything in the gated class, or anything that would change the PRD, goes to the human. Escalation happens as a decision object in the inbox, never as a chat message.

For Mosaic Stack today: Sage by Jason's ruling of 2026-09-26, then Jason. When two of Jason's own rulings conflict, Sage puts both to him side by side and doesn't pick one.

What exists against the brain dump

Need	Today	Gap
Declarable roles with protocol	roles/ has conductor-policy.json and researcher.json; agents/README.md lists seats	No schema for business roles (PM, CEO, CTO and the rest), no decision classes, no role lock
Mint credentials	none	Gitea can create tokens for bot users with an admin token; nothing in the stack does it
Provide credentials	scripts/gitea-api.sh reads a token file in place; auth.sh for pi	Per seat by hand; a launch doesn't set a role's credential
Variables per system, business, project, agent	one system config, ~/.config/mosaic-dev/config.json	No business, project or agent layers
Inter-agent messages	T3 messages addressed by thread id; the Discord connector (#1509)	No bus addressed by role; the thread id is the address
Proactive decisions	prose rules in AGENTS.md	Not data, not enforced
Surfacing outstanding decisions	the waiting-on-jason state in the queue; "Input needed:" lines	No decision object, no inbox
Task management	the queue (packages/queue): rows, owners, reviews, a log, a lock	Built for agents; no dates, no UI, nothing for Jason to work in; Vikunja not connected
PRD and north star	the ratified goals page	No PRD; PRDY exists only in v1
Options vs. no interruption	none	Depends on decision classes and the inbox
Meta-harness	adapters/pi, adapters/mock; Claude deferred (LAYERS L4)	No Claude or Codex adapter; skills, prompts and hooks aren't generated from roles
CLI or TUI	scripts/mosaic launch, seat task, queue; per-seat TUI launchers	No front door for Jason
WebUI	packages/webui (control board screen), CHAT-03 chat in review (row 5)	No tasks, decisions or conversation view in one place

Vikunja: integrate, don't annex

Recommendation: reach Vikunja through its REST API behind a task interface in Mosaic Stack, and keep the agent-side logic in the stack.

• Vikunja is Go with a Vue front end, under the AGPL-3.0. Annexing it means a Go codebase in a Node repository, every upstream release merged by hand, and AGPL terms on the combined work if Mosaic Stack is ever offered to others over a network.
• Its API has scoped tokens, which helps the credential plan: each role gets a token limited to what it does.
• v1 tried the other direction, a native kanban that would replace Vikunja (v1/docs/requirements/native-kanban-sot.md). Its canon review came back NO-GO with 8 blockers before any code shipped.
• Integration can be undone. A fork can't really.

The queue keeps doing what it does well, which is the agents' lock, review and audit log. Whether Vikunja becomes where tasks live and the queue mirrors it, or the reverse, is the first design question for that piece.

Proposed order

Building the layers one at a time, each finished before the next starts, risks the failure Jason named: machinery with no working system. Sage recommends one thin path through every layer first, then widening.

Slice 1, the first working system. Jason opens mosaic in a terminal and talks to the PM role. The PM files a task in the tracker, linked to a PRD requirement, and assigns it to a coder role. The stack launches that agent with the role's contract, variables and credential. The agent works. A gated question shows up in Jason's decision inbox in the CLI. He answers in one word. The task is reviewed and closed, and the CLI and the WebUI both show the trail. Every step is a logged event, so the measures come from data and not from hand tagging.

What slice 1 needs, in build order:

1. PRD for Mosaic Stack. A PRDY interview with Jason, run by hand. It replaces the goals page as the top of the chain.
2. Profiles, roles and variables. A role schema with decision classes and a lock; variable layers for system, business, project and agent; one business (Mosaic Stack) and four roles (PM, CTO, coder, reviewer).
3. Decision objects and messages. A decision record (who raised it, class, options, recommendation, who resolved it, when) and messages addressed by role. T3 and Discord become transports.
4. Tasks. The tracker interface with the Vikunja adapter, or the queue alone if Jason picks annexing and that becomes a later piece.
5. The mosaic CLI and TUI. One front door: talk to a role, see the inbox, tasks and agents.
6. WebUI. The same data through the console; CHAT-03 carries on as part of it.
7. Credentials per role. Provided at launch first. Minting stays gated and comes after slice 1.
8. Meta-harness. Generate the system prompt, skills and hooks for Pi from role and variables, then add Claude and Codex adapters.

After slice 1, each layer widens: more roles and businesses, minting, more harnesses, PRDY in code. Measures come last and pick one weak spot at a time, which is what Jason described.

What happens to work in flight

• Row 5, CHAT-03 I1: continues; it's WebUI work slice 1 uses.
• Row 32, ledger guideposts: park it. Only Jason can park.
• Row 7, the weekly ledger: keep the Monday run as a raw baseline. It costs a command, and no new ledger work.
• Goal 2, rows 11 and 13: the queue stays as the agents' lock and log. Row 11's second accepted brief can be the first slice brief.
• Goal 3, Gate E: unchanged.
• Goal 4, retiring the fleet: it needs a working system to move to, so it folds into slice 1. The relaunch idea (2026-10-04_project-relaunch-roles.md) becomes the roles piece.

Open questions

• Storage. The canon keeps config and run records in files. Tasks, messages and decisions at this scale may want a database. That's an invariant question for later, and it doesn't block the PRD interview.
• Which roles a business must declare, and which are optional.
• Whether Sage holds PM or CTO for Mosaic Stack once roles exist.

Rulings so far

Recorded in full as lead decision 43, 2026-10-04.

• Vikunja: integrate through its API. No code annexed.
• First roles: PM, CTO, coder and reviewer.
• Row 32: Sage advised parking it. That waits on Jason's word.
• Pocket ID: candidate for people's SSO. Agents still use service tokens per role.
• The direction itself isn't ratified yet. Sage put its choices to Jason as lettered questions.
• 2026-10-04, decision 44. Ratified:
  • The working north star sentence is on the goals page.
  • Slice 1 is goal 1.
  • Mosaic Stack builds itself on slice 1.
  • A CLI first.
  • A dedicated local Vikunja by default. The installer offers an existing instance or the bundled one.
  • Pocket ID after slice 1.
  • SQLite with append-only tables for decisions and messages.
  • Row 32 parked.