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

LayerPurposeFileAudit FindingsTrack issues through a status lifecyclefindings.jsonlContext PacksGive each agent run a compact starting contextcontext-packs/*.mdMission ControlOne-page health view for the humanmission-control/*.mdFlight RecorderReplay agent decisions after the factflight-recorder/*.jsonlDecision BriefsCompress human todos into 1-3 real decisionsembedded in Mission ControlExperience LogClassify learnings as rule/test/gate/prompt/docexperience-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):

ScriptPurposescripts/upsert_finding.pyCreate / update findings in .agent-os/findings.jsonl``scripts/compile_context_pack.pyGenerate context packs from workspace statescripts/mission_control.pyGenerate one-page health view

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

References#

FileContentreferences/schemas.mdJSON/Markdown schemas for all data filesreferences/workflows.mdDaily check, weekly review, and upgrade workflowsreferences/templates.mdCopy-paste templates for each file type