Agent OS

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 (\x3Cproject>/.agent-os/) that lets multiple agents share:

Directory Protocol

All Agent OS data lives under \x3Cproject-root>/.agent-os/:

.agent-os/
├── findings.jsonl                  # Audit finding registry
├── experience-log.jsonl            # Promoted learnings
├── context-packs/
│   └── YYYY-MM-DD-\x3Clabel>.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):

{
  "agent": "\x3Cname>",
  "domain": "\x3Cscope>",
  "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):

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

References