Agent Os

Provides file-based protocols to enable audit trails, shared context, mission control, flight recording, and seamless handoff in multi-agent collaboration.

Make agent collaboration depend on auditable file protocols, not long chat logs.

When to Use

This skill activates when any of these triggers appear:

• Keywords: agent os, multi-agent collaboration, agent handoff, audit finding, mission control, context pack, flight recorder, promote learning
• Scenarios: You are working with multiple agents on the same workspace and need shared state, audit trails, or human decision compression
• Commands: Any of the 6 core commands listed below

What It Does

Agent OS provides a minimal file protocol (<project>/.agent-os/) that lets multiple agents share:

Layer	Purpose	File
Audit Findings	Track issues through a status lifecycle	findings.jsonl
Context Packs	Give each agent run a compact starting context	context-packs/*.md
Mission Control	One-page health view for the human	mission-control/*.md
Flight Recorder	Replay agent decisions after the fact	flight-recorder/*.jsonl
Decision Briefs	Compress human todos into 1-3 real decisions	embedded in Mission Control
Experience Log	Classify learnings as rule/test/gate/prompt/doc	experience-log.jsonl

Directory Protocol

All Agent OS data lives under <project-root>/.agent-os/:

text

.agent-os/
├── findings.jsonl                  # Audit finding registry
├── experience-log.jsonl            # Promoted learnings
├── context-packs/
│   └── YYYY-MM-DD-<label>.md      # Task-scoped context summaries
├── mission-control/
│   └── YYYY-MM-DD.md              # Daily one-page health view
└── flight-recorder/
    └── YYYY-MM-DD.jsonl            # Agent run records

Agents MUST NOT require other directories. This is the only protocol root.

Core Commands

1. compile context pack

Generate a compact context summary before an agent run.

Script: scripts/compile_context_pack.py

Reads workspace state (open findings, recent memory, repo status) and writes a context pack to .agent-os/context-packs/.

The primary agent should invoke this at session start or before handing off to another agent.

2. upsert finding

Create or update an audit finding in the registry.

Script: scripts/upsert_finding.py

Findings follow a status lifecycle: open → accepted → fixed → verified → closed. Alternate paths: deferred, false_positive.

3. summarize mission control

Generate a one-page project health view.

Script: scripts/mission_control.py

Aggregates open findings, active repos, stale items, and human decision items into a single Markdown file the human can scan in seconds.

4. record flight

Record an agent run's inputs, decisions, changes, and verification results.

MVP scope: Implemented as a workflow/template in references/templates.md. Script planned for v0.2.0.

5. compress decisions

Filter human-actionable items and compress them into 1-3 decision briefs.

MVP scope: Implemented as a workflow in references/workflows.md. Script planned for v0.2.0.

6. promote learning

Classify a learning as rule, test, gate, prompt, or doc.

MVP scope: Implemented as a workflow in references/workflows.md. Script planned for v0.2.0.

Agent Onboarding Protocol

A new agent joining the workspace MUST:

1. Read the latest context pack (.agent-os/context-packs/)
2. Query open findings (.agent-os/findings.jsonl where status is open)
3. Read the latest mission control (.agent-os/mission-control/)
4. After completing work, either update findings or append a flight record

Minimal onboarding declaration (optional, for agent registries):

json

{
  "agent": "<name>",
  "domain": "<scope>",
  "inputs": ["context-pack", "mission-control"],
  "outputs": ["handoff", "finding-update", "flight-record"]
}

Boundaries

Agent OS explicitly does NOT:

• Replace GitHub Issues or project trackers (it complements them)
• Build a web dashboard or database backend
• Require any specific agent framework or runtime
• Introduce real-time messaging between agents
• Increase the human's cognitive load

Scripts

Three scripts ship with v0.1.0 (Python 3.10+, zero external dependencies):

Script	Purpose
scripts/upsert_finding.py	Create / update findings in .agent-os/findings.jsonl
scripts/compile_context_pack.py	Generate context packs from workspace state
scripts/mission_control.py	Generate one-page health view

All scripts support --help and --dry-run.

References

File	Content
references/schemas.md	JSON/Markdown schemas for all data files
references/workflows.md	Daily check, weekly review, and upgrade workflows
references/templates.md	Copy-paste templates for each file type