mosaicstack/stack
1
0
Fork 0
Code Issues 22 Pull Requests 7 Actions Packages Projects Releases 13 Wiki Activity

docs: add mission control and coordination resilience docs

Browse Source
This commit is contained in:
Jason Woltje
2026-05-07 13:20:02 -05:00
parent 755df9079e
commit 079c5597ff
6 changed files with 978 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/mission-control/BOARD.md Normal file
View File

@@ -0,0 +1,99 @@
# Mission Control Plane — Feature Board
> Discussion board for the combined PRD / mission / Kanban workflow.
> Use this to decide scope before implementation.
## Board Legend
- **Must-have** — required for the first usable version
- **Should-have** — strongly preferred, but can ship after the core path
- **Could-have** — valuable later if time permits
- **Won't-have** — explicitly deferred
---
## Feature Board
| Feature Card | Need | Priority | Decision / Notes |
| --- | --- | --- | --- |
| Canonical mission manifest | One durable root object for goal, PRD, board, session | Must-have | Mission manifest becomes the anchor for all downstream state |
| PRD generator integration | PRD should be generated from a feature idea and saved in docs | Must-have | Use Mosaic PRDy format and keep the file human-reviewable |
| Board atomization | Break PRD into assignable tasks with dependencies | Must-have | Each user story should map to one or more tasks |
| Short-cycle detector | Detect compaction churn and repeated tool loops | Must-have | Coordinator should track churn score per session |
| Handoff packet | Preserve actionable context across rotations | Must-have | Use a compact structured summary, not a raw transcript |
| Auto-resume workers | Let new sessions read mission + board on start | Should-have | Makes overnight autonomy realistic |
| Mission status view | Show current phase, blockers, and active session | Should-have | Expose through CLI first, dashboard later |
| Worktree root convention | Keep worktrees off `/tmp` and on the larger persistent drive | Should-have | Prefer `/src/<repo>-worktrees` for repo worktrees and long-lived agent work |
| Review gate | Prevent autonomous work from shipping unreviewed | Should-have | Use reviewer tasks before mission close |
| Rotation policy config | Configure thresholds per mission/profile | Could-have | Keep v1 simple, add tuning later |
| Goal decomposition suggestions | Suggest sub-goals from the PRD | Could-have | Good for planning, not necessary for core path |
| Cross-channel continuity | Continue a mission across CLI/gateway/remote channels | Could-have | Important later, not required for MVP |
| Automatic board sync | Mirror git docs into DB and back | Could-have | Nice-to-have after the file-first flow stabilizes |
| Fully autonomous closeout | Let mission finish without human intervention | Won't-have | Keep an operator-visible review step |
---
## Needs Discussion
### 1) Canonical source of truth
**Question:** Should the PRD, mission manifest, and board all live in git, or should one be the database source of truth?
**Proposed answer:** Keep the human-readable artifacts in git and sync the mission runtime state to the database.
### 2) Scope of automation
**Question:** Should the first version auto-create the board from the PRD, or require a human/orchestrator to approve the split?
**Proposed answer:** Auto-create a draft board, then let the orchestrator approve or adjust it.
### 3) Rotation triggers
**Question:** What should trigger a forced session rotation?
**Candidate signals:**
- repeated compaction
- repeated prompts for permission
- identical tool loops
- no new file/task state after several turns
- task blocked on a missing prerequisite
**Proposed answer:** Use a weighted churn score with a small hard cap on repeated compactions.
### 4) Handoff format
**Question:** What should the next session receive?
**Proposed answer:**
- Mission ID
- PRD path
- Active board task
- Completed work
- Blockers
- Next 3 actions
- Non-negotiable constraints
### 5) Operator control
**Question:** Should the operator be able to force a rotation or pause the mission?
**Proposed answer:** Yes. Human override should win.
---
## Draft Decisions
1. File-first artifacts, DB-backed runtime state.
2. PRD-first planning, board-second execution.
3. Auto-rotation on churn, but human override remains available.
4. Structured handoff packets required on every rotation.
5. Mission close requires a reviewer task.
---
## Open Questions
- What exact data fields belong in the mission manifest?
- Should rotation thresholds vary by agent profile?
- What is the minimum viable status surface for v1?
- Should the board support milestones in addition to tasks?

95
docs/mission-control/MISSION-MANIFEST.md Normal file
View File

@@ -0,0 +1,95 @@
# Mission Manifest — Mosaic Mission Control Plane
> Persistent document tracking scope, status, and handoff history for the combined PRD / mission / Kanban workflow.
## Mission
**ID:** mission-control-plane-20260506
**Statement:** Combine Mosaic PRDy, coord, and Kanban into one durable workflow so an agent can move from feature idea to PRD to mission to task board and keep working across session rotation, compaction, and restarts with minimal context loss.
**Phase:** planning — MC-01 complete, MC-02 next
**Current Milestone:** MC-02
**Progress:** 1 / 6 milestones
**Status:** active
**Last Updated:** 2026-05-06
**Parent Mission:** None — new mission
---
## Context
This mission exists because overnight autonomy breaks when the working session short-cycles. The system needs durable artifacts and a mechanical coordinator that can:
1. keep a canonical PRD,
2. atomize the PRD into board tasks,
3. track mission state separately from the chat session,
4. detect churn or compaction pressure,
5. rotate to a fresh session, and
6. re-enter from a structured handoff.
Operational convention: repo worktrees and long-lived working directories should use `/src/<repo>-worktrees` instead of `/tmp`.
Design references:
- `docs/mission-control/PRD.md` — product requirements
- `docs/mission-control/BOARD.md` — feature discussion board
- `docs/mission-control/TASKS.md` — atomized execution plan
---
## Success Criteria
- [ ] AC-1: A feature idea can be converted into a PRD, mission, and task board.
- [ ] AC-2: The coordinator can load a mission and its board from durable storage.
- [ ] AC-3: The coordinator can detect short-cycling and rotate sessions automatically.
- [ ] AC-4: A rotated session can resume from a handoff packet without manual re-prompting.
- [ ] AC-5: The board remains traceable back to the PRD user stories.
- [ ] AC-6: Operators can inspect mission state, task state, and latest handoff from one place.
- [ ] AC-7: The system can run overnight without losing the mission goal.
---
## Milestones
| # | ID | Name | Status | Branch | Started | Completed |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | MC-01 | PRD + mission schema foundation | in-progress | docs/mission-control-* | 2026-05-06 | — |
| 2 | MC-02 | Mission runtime model | not-started | — | — | — |
| 3 | MC-03 | Board atomization and task linkage | not-started | — | — | — |
| 4 | MC-04 | Short-cycle detector and rotation engine | not-started | — | — | — |
| 5 | MC-05 | Handoff generation and re-entry | not-started | — | — | — |
| 6 | MC-06 | Operator surface and E2E validation | not-started | — | — | — |
---
## Budget
| Milestone | Est. tokens | Parallelizable? |
| --- | --- | --- |
| MC-01 | 16K | No |
| MC-02 | 20K | No |
| MC-03 | 24K | Mostly after MC-01 |
| MC-04 | 20K | After MC-02 |
| MC-05 | 18K | After MC-04 |
| MC-06 | 26K | After MC-04/05 |
| **Total** | **~124K** | |
---
## Session History
| Session | Date | Runtime | Outcome |
| --- | --- | --- | --- |
| S1 | 2026-05-06 | hermes | PRD, board, task plan, mission manifest, and worktree convention drafted |
---
## Next Step
Kick off MC-02: implement the durable mission runtime model and wire the mission state into the coordinator.

200
docs/mission-control/PRD.md Normal file
View File

@@ -0,0 +1,200 @@
# PRD: Mosaic Mission Control Plane
## Metadata
- **Owner:** Jason Woltje
- **Date:** 2026-05-06
- **Status:** draft
- **Framework:** Mosaic PRDy + coord + Kanban
- **Target Repo:** `git.mosaicstack.dev/mosaic/mosaic-stack`
- **Primary Modules:** `packages/prdy`, `packages/coord`, `packages/queue`, `apps/gateway`, `packages/brain`, `packages/cli`
---
## Problem Statement
Mosaic already has the ingredients for durable agent work: PRD generation (`prdy`), mission coordination (`coord`), and task execution boards (`Kanban` / `TASKS.md`). Today those systems can still drift apart:
- A PRD can exist without a mission record.
- A mission can exist without a machine-readable execution board.
- Agents can short-cycle or compact repeatedly without a durable handoff.
- The next session may know the goal, but not the exact next step.
The result is brittle overnight autonomy: work continues only as long as a single session remains healthy.
This feature unifies those layers into one durable workflow so a mission can survive session rotation, compaction, and restarts with minimal state loss.
---
## Goals
1. Create one canonical pipeline from idea → PRD → mission → board → execution.
2. Let `prdy` generate a PRD that is immediately usable as a mission input.
3. Let `coord` own mission state, handoffs, and session rotation.
4. Let the board hold atomized tasks with dependencies and assignees.
5. Let agents read the mission and board to learn the next action without extra prompting.
6. Detect short-cycling and rotate sessions before quality degrades.
7. Preserve useful context across handoffs with a structured summary packet.
8. Give operators a single place to see mission status, task state, and the current session.
---
## Non-Goals
1. Replacing the Mosaic agent runtime or gateway architecture.
2. Rewriting `prdy` or `coord` from scratch.
3. Turning the board into a general project-management system.
4. Building a full Gantt/charting product.
5. Removing human review or approval gates.
6. Allowing agents to create arbitrary mission state without schema.
---
## User Stories
### US-001: Create a mission from a feature idea
**Description:** As an orchestrator, I want to turn a feature idea into a PRD and mission so that agents can work from a durable spec instead of a chat transcript.
**Acceptance Criteria:**
- [ ] `prdy` can emit a PRD with goals, non-goals, and requirements.
- [ ] The PRD is linked to a mission ID.
- [ ] The mission manifest references the PRD path.
- [ ] The mission is readable by downstream agent sessions.
### US-002: Atomize work into a board
**Description:** As an orchestrator, I want to split a PRD into board tasks so that work can be assigned to specialists.
**Acceptance Criteria:**
- [ ] Each user story can become one or more tasks.
- [ ] Tasks have assignees, dependencies, and estimates.
- [ ] Tasks are machine-readable and durable.
- [ ] The board can be regenerated from the PRD without ambiguity.
### US-003: Rotate sessions without losing the mission
**Description:** As a coordinator, I want to restart or rotate a session when it short-cycles so that the mission continues with minimal loss.
**Acceptance Criteria:**
- [ ] The coordinator detects compaction pressure or repeated loops.
- [ ] The coordinator writes a handoff summary before rotation.
- [ ] A new session can resume from the handoff packet.
- [ ] The mission state remains intact across the rotation.
### US-004: Let workers read the next step automatically
**Description:** As a worker agent, I want to read the mission and board at startup so I can do the next useful thing without waiting for a human prompt.
**Acceptance Criteria:**
- [ ] Startup loads the active mission manifest.
- [ ] Startup loads the current board/task row.
- [ ] Startup exposes the next action clearly in the prompt.
- [ ] The agent can continue after compaction using the same mission context.
### US-005: Observe mission health from one place
**Description:** As an operator, I want a single view of mission health so that I can see progress, blocked tasks, and session churn.
**Acceptance Criteria:**
- [ ] Mission state shows current phase and progress.
- [ ] Board state shows task status by assignee.
- [ ] Short-cycle/rotation events are visible.
- [ ] Handoffs are inspectable.
---
## Functional Requirements
FR-1. The system must represent a mission as a durable object with an ID, goal, current phase, PRD path, board path, and active session ID.
FR-2. The system must represent a PRD as a markdown document with goals, user stories, functional requirements, non-goals, technical considerations, and success metrics.
FR-3. The system must represent execution work as a board of atomized tasks with status, assignee, dependency, and estimate fields.
FR-4. The coordinator must be able to derive a task board from a PRD.
FR-5. The coordinator must be able to write a handoff packet that includes goal, current state, completed work, blocked work, next steps, and constraints.
FR-6. The coordinator must detect short-cycling signals such as repeated compactions, repeated tool loops, repeated approval prompts, or no progress across several turns.
FR-7. The coordinator must rotate the session when the short-cycle threshold is exceeded.
FR-8. The coordinator must preserve mission continuity across session rotation.
FR-9. The worker session must read the mission state and board state at startup.
FR-10. The worker session must be able to resume from the last handoff summary without the operator rewriting the goal manually.
FR-11. The operator must be able to inspect the mission state, PRD, board, and latest handoff from one place.
FR-12. The mission system must keep a traceable link between PRD requirements and board tasks.
FR-13. The system must not allow a task to become active without a valid mission context.
FR-14. The system must keep durable history for rotation and handoff events.
---
## Board Discussion: Features and Needs
This is the feature discussion board that should drive the mission design.
| Card | Need | Why it matters | Proposed decision |
| --- | --- | --- | --- |
| Canonical mission record | One source of truth for goal/state | Prevents drift between chat, docs, and queue | Make mission manifest the durable root object |
| PRD → board derivation | Break feature ideas into executable work | Lets the plan be assigned and tracked | Keep PRD as the spec, generate board tasks from user stories |
| Session watchdog | Detect churn/short-cycling | Keeps overnight runs productive | Add short-cycle scoring and forced rotation |
| Structured handoff | Preserve context across session changes | Minimizes restart loss | Use a compact JSON/MD handoff packet |
| Worker auto-read | Let agents resume without human re-prompting | Reduces operator overhead | Load mission + board on session start |
| Status surface | Show progress and blockers clearly | Operators need confidence | Expose mission state via CLI and dashboard |
| Review gate | Keep quality high on autonomous work | Prevents silent regressions | Require review tasks before close |
| Recoverability | Resume after failure or restart | Mission should outlive a process | Persist session and handoff history |
---
## Design Considerations
1. The PRD should stay human-readable markdown, because the board and mission references need to be reviewable in git.
2. The board should be machine-readable enough for automation but still readable by humans.
3. The mission manifest should point to the PRD and board, not duplicate them.
4. Handoff packets should be compact and structured so they can be injected into a new session with minimal token cost.
5. The coordinator should prefer rotation over forced context growth once the session is near the compaction threshold.
6. Existing Mosaic commands should be extended, not replaced, wherever possible.
7. The same mission should be resumable across CLI, gateway, and remote channels.
---
## Technical Considerations
- Likely storage split:
- PRD/board/manifest in git-backed docs
- mission/session state in the Mosaic data layer
- runtime health in queue/session state
- Worktrees and long-lived agent working directories should live under `/src/<repo>-worktrees` rather than `/tmp` so they sit on the larger persistent drive and survive longer-running missions.
- The coordinator needs a stable session identity, even if the active session changes.
- Task dependencies must be enforced so workers do not start early.
- The handoff packet should include the top 3 immediate actions and the strongest constraints.
- Rotation triggers should be configurable per profile or per mission.
- The initial version can be file-first, with dashboard sync added later.
---
## Success Metrics
- A mission can rotate sessions without losing the active goal.
- A new session can resume from the latest handoff in under one turn.
- Board tasks remain aligned to PRD user stories.
- Short-cycling sessions are replaced before repeated compaction harms quality.
- Operators can find mission state without spelunking across multiple chat logs.
---
## Open Questions
1. What should the canonical mission ID format be?
2. Should the board live only in git, or also in the database?
3. Should rotation be automatic by default, or opt-in per mission?
4. What should the short-cycle threshold be initially?
5. Should handoffs be pure text, structured JSON, or both?
6. Which CLI command should be the primary mission entrypoint: `mosaic mission`, `mosaic coord`, or `mosaic prdy`?

113
docs/mission-control/TASKS.md Normal file
View File

@@ -0,0 +1,113 @@
# Tasks — Mosaic Mission Control Plane
> Single-writer: orchestrator only. Workers read but never modify.
>
> **Mission:** mission-control-plane-20260506
> **Schema:** `| id | status | description | issue | agent | branch | depends_on | estimate | notes |`
> **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa`
> **Agent values:** `codex` | `glm-5.1` | `haiku` | `sonnet` | `opus` | `—` (auto)
>
> Scope: this file decomposes the combined PRD / mission / board workflow into atomized tasks.
---
## Milestone 1 — PRD + mission schema foundation
Goal: create the durable doc structure and the minimal mission metadata needed to keep PRD, board, and mission aligned.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| MC-01-01 | not-started | Write `docs/mission-control/PRD.md` with goals, non-goals, functional requirements, and success metrics. | — | sonnet | docs/mission-control-prd | — | 5K | Human-readable PRD becomes the spec anchor. |
| MC-01-02 | not-started | Write `docs/mission-control/BOARD.md` as a decision board for scope, priority, and open questions. | — | haiku | docs/mission-control-board | MC-01-01 | 3K | Keeps discussion separate from the spec. |
| MC-01-03 | not-started | Write `docs/mission-control/MISSION-MANIFEST.md` linking PRD, board, tasks, and mission identity. | — | sonnet | docs/mission-control-manifest | MC-01-01, MC-01-02 | 4K | Durable mission root object. |
| MC-01-04 | not-started | Write `docs/mission-control/TASKS.md` with the atomized execution plan and dependency graph. | — | sonnet | docs/mission-control-tasks | MC-01-03 | 4K | Board-backed execution plan. |
**Milestone 1 estimate:** ~16K tokens
---
## Milestone 2 — Mission runtime model
Goal: make missions first-class runtime objects that can survive session restarts and compaction.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| MC-02-01 | not-started | Define mission schema in the data layer: mission ID, goal, phase, PRD path, board path, active session ID, last handoff, and churn score. | — | codex | feat/mission-control-schema | MC-01-03 | 6K | This is the durable root state. |
| MC-02-02 | not-started | Add mission read/write services to `packages/coord` so the coordinator can load and persist mission state. | — | codex | feat/mission-control-coord-store | MC-02-01 | 6K | Keep storage simple and explicit. |
| MC-02-03 | not-started | Add mission status reporting to `mosaic mission` and `mosaic coord status`. | — | codex | feat/mission-control-status-cli | MC-02-02 | 4K | Operators need one obvious status command. |
| MC-02-04 | not-started | Add tests for mission persistence and recovery after restart. | — | haiku | feat/mission-control-persistence-tests | MC-02-02 | 4K | Verify mission survives process churn. |
|| MC-02-05 | done | Add a worktree-root convention to the mission runtime notes and startup guidance so agents prefer `/src/<repo>-worktrees` over `/tmp`. | — | haiku | docs/mission-control-worktree-root | MC-01-03 | 3K | Keep long-lived work on the larger persistent drive. |
**Milestone 2 estimate:** ~20K tokens
---
## Milestone 3 — Board atomization and task linkage
Goal: derive assignable tasks from the PRD and keep them linked to mission state.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| MC-03-01 | not-started | Add a PRD-to-task decomposition rule set: every user story maps to one or more board tasks. | — | sonnet | feat/mission-control-decompose | MC-01-01 | 5K | Start simple and deterministic. |
| MC-03-02 | not-started | Implement board generation from the PRD in a machine-readable format. | — | codex | feat/mission-control-board-gen | MC-03-01 | 6K | Output should be usable by the coordinator. |
| MC-03-03 | not-started | Add dependency validation so tasks cannot start before parent tasks complete. | — | codex | feat/mission-control-deps | MC-03-02 | 5K | Enforces ordering. |
| MC-03-04 | not-started | Add review-task support so a mission cannot close without a reviewer step. | — | sonnet | feat/mission-control-review-gate | MC-03-03 | 4K | Preserves quality. |
| MC-03-05 | not-started | Add tests proving the board stays traceable back to the PRD user stories. | — | haiku | feat/mission-control-trace-tests | MC-03-02, MC-03-03 | 4K | Traceability is the point. |
**Milestone 3 estimate:** ~24K tokens
---
## Milestone 4 — Short-cycle detector and rotation engine
Goal: detect when a session is stuck and rotate to a fresh session before quality falls off.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| MC-04-01 | not-started | Define churn signals: repeated compaction, identical tool loops, repeated permission prompts, and no progress across several turns. | — | sonnet | feat/mission-control-churn-signals | MC-02-01 | 4K | Keep the rules explicit. |
| MC-04-02 | not-started | Implement churn scoring in the coordinator with configurable thresholds. | — | codex | feat/mission-control-churn-score | MC-04-01 | 6K | Weighted score makes tuning easier. |
| MC-04-03 | not-started | Implement automatic session rotation when churn crosses the threshold. | — | codex | feat/mission-control-rotate-session | MC-04-02 | 6K | The session is disposable; the mission is not. |
| MC-04-04 | not-started | Add tests for rotation triggers and for avoiding premature rotation. | — | haiku | feat/mission-control-rotation-tests | MC-04-03 | 4K | Prevent flapping. |
**Milestone 4 estimate:** ~20K tokens
---
## Milestone 5 — Handoff generation and re-entry
Goal: preserve the best context from the old session and inject it into the new session cleanly.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| MC-05-01 | not-started | Define the handoff packet schema: mission ID, session ID, completed work, blockers, next 3 actions, and constraints. | — | sonnet | feat/mission-control-handoff-schema | MC-02-01 | 4K | Keep it compact and structured. |
| MC-05-02 | not-started | Implement handoff packet writing during rotation. | — | codex | feat/mission-control-handoff-write | MC-05-01, MC-04-03 | 5K | Persist before the old session exits. |
| MC-05-03 | not-started | Implement handoff packet loading at session startup. | — | codex | feat/mission-control-handoff-load | MC-05-01, MC-04-03 | 5K | New session should know the next action. |
| MC-05-04 | not-started | Add tests proving a rotated session can continue the mission without manual re-prompting. | — | haiku | feat/mission-control-handoff-tests | MC-05-02, MC-05-03 | 4K | Resume quality is the key metric. |
**Milestone 5 estimate:** ~18K tokens
---
## Milestone 6 — Operator surface and E2E validation
Goal: expose the whole workflow through commands and verify it end-to-end.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| MC-06-01 | not-started | Add a CLI command to inspect the active mission, PRD path, board path, task statuses, and latest handoff. | — | codex | feat/mission-control-inspect-cli | MC-02-03, MC-05-03 | 5K | One place to inspect the whole stack. |
| MC-06-02 | not-started | Add a compact dashboard or TUI summary view for mission health. | — | codex | feat/mission-control-summary-ui | MC-06-01 | 6K | Nice to have, but not before the core works. |
| MC-06-03 | not-started | Build an E2E harness that simulates compaction / rotation and verifies the mission can continue. | — | sonnet | feat/mission-control-e2e-harness | MC-04-03, MC-05-03 | 8K | This is the proof that the design works. |
| MC-06-04 | not-started | Add final docs for operators explaining how PRD, mission, and board fit together. | — | haiku | feat/mission-control-ops-docs | MC-06-03 | 4K | Make it usable by humans. |
| MC-06-05 | not-started | Consolidate review findings and close the mission with a release note. | — | sonnet | chore/mission-control-close | MC-06-04 | 3K | Only after the E2E passes. |
**Milestone 6 estimate:** ~26K tokens
---
## Execution Notes
- `sonnet` is best for planning, decomposition, and the review-gate tasks.
- `codex` is best for schema, coordinator, and CLI implementation.
- `haiku` is best for validation, traceability checks, and docs.
- The first implementation pass should stay file-first and keep the runtime state thin.
- The mission should not close until the PRD, board, mission manifest, and E2E harness all agree.