mosaicstack/stack
1
0
Fork 0
Code Issues 48 Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Fleet configuration control plane and operator documentation #758

New Issue
Open
opened 2026-07-14 18:59:16 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-07-14 18:59:16 +00:00
Owner
Copy Link

Objective

Make the existing Mosaic fleet system understandable and safely operable through one declarative, schema-validated configuration lifecycle. The roster is canonical input; generated agent environment files, systemd units, tmux sessions, and heartbeat state are derived/reconciled outputs.

Required agent classes

  • code — coder agent
  • review — code and security review
  • validator — PR review and final gate; codename Ultron
  • orchestrator — master orchestrator between interaction and fleet agents
  • team-leader — project lead receiving leased coder/review/validator capacity from orchestrator
  • enhancer — fleet-wide improvement monitor collaborating with orchestrator
  • interaction — human-machine interface; codename Tess

Required capabilities

  • Document the roster YAML/JSON schema, every field/default/constraint, generated-file boundary, role contracts, lifecycle, examples, migration, troubleshooting, and human/agent workflows.
  • Expose programmatic create, inspect, update, remove, start, stop, restart, status, validate, reconcile, and doctor operations through mosaic fleet where not already present.
  • Allow safe runtime/model/harness/effort/workdir/role changes without direct editing of generated environment files.
  • Validate duplicate names, unsupported classes/runtimes/models, incompatible options, missing role contracts, stale generated state, unmanaged sessions, systemd drift, and socket ambiguity.
  • Keep generated files explicitly non-authoritative and rebuildable from the canonical roster.
  • Preserve existing installations through schema versioning and migration.

Delivery gates

  • Update docs/PRD.md before implementation.
  • Track implementation in docs/TASKS.md.
  • Tests must cover schema, mutations, reconciliation, systemd/tmux status, migration, and documentation examples.
  • Independent code and security review required.
  • Squash merge to main, terminal-green CI, then close this issue.
## Objective Make the existing Mosaic fleet system understandable and safely operable through one declarative, schema-validated configuration lifecycle. The roster is canonical input; generated agent environment files, systemd units, tmux sessions, and heartbeat state are derived/reconciled outputs. ## Required agent classes - code — coder agent - review — code and security review - validator — PR review and final gate; codename Ultron - orchestrator — master orchestrator between interaction and fleet agents - team-leader — project lead receiving leased coder/review/validator capacity from orchestrator - enhancer — fleet-wide improvement monitor collaborating with orchestrator - interaction — human-machine interface; codename Tess ## Required capabilities - Document the roster YAML/JSON schema, every field/default/constraint, generated-file boundary, role contracts, lifecycle, examples, migration, troubleshooting, and human/agent workflows. - Expose programmatic create, inspect, update, remove, start, stop, restart, status, validate, reconcile, and doctor operations through mosaic fleet where not already present. - Allow safe runtime/model/harness/effort/workdir/role changes without direct editing of generated environment files. - Validate duplicate names, unsupported classes/runtimes/models, incompatible options, missing role contracts, stale generated state, unmanaged sessions, systemd drift, and socket ambiguity. - Keep generated files explicitly non-authoritative and rebuildable from the canonical roster. - Preserve existing installations through schema versioning and migration. ## Delivery gates - Update docs/PRD.md before implementation. - Track implementation in docs/TASKS.md. - Tests must cover schema, mutations, reconciliation, systemd/tmux status, migration, and documentation examples. - Independent code and security review required. - Squash merge to main, terminal-green CI, then close this issue.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#758
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?