Overview

This repository demonstrates a governed workflow operating model rather than a one-off automation demo. Operator intent is separated from execution. Every run is classified, bounded, and logged before it becomes part of an operational workflow.

Governed workflow control

Actions are classified before side effects are accepted.

Access boundaries

Writes are constrained to governed repository zones and protected surfaces are denied.

Auditability

Runs and approvals are recorded in append-only JSONL logs for later review.

Controls Matrix

Control How it works Governance value
Policy engine Classifies actions as `ALLOW`, `REQUIRE_APPROVAL`, or `DENY`. Makes execution rules explicit and reviewable.
Approval routing Creates durable approval records for high-risk actions. Introduces human control for consequential exceptions.
Access control Restricts writes to `vault/` and `data/` and blocks protected control surfaces. Prevents uncontrolled workspace mutation.
Audit logging Appends run and approval events to structured JSONL logs. Supports traceability and operational review.
Secret screening Checks log content for credential-like patterns before recording. Reduces accidental disclosure in audit data.
Skill contracts Documents each capability’s purpose, inputs, outputs, and constraints. Keeps the execution surface bounded and inspectable.

Execution Flow

intake
  -> skill lookup
  -> policy check
  -> execution
  -> output validation
  -> audit write
  -> handoff or follow-up

The supported runtime surface is the packaged implementation under src/agentic_os/. The repository keeps code, policy, documentation, sample skills, and audit artifacts in one governed workspace.

Operational Visibility

Operational state is inspectable directly from repository artifacts.

`data/runs.jsonl`

Execution history with hashed inputs, output paths, status, and timestamps.

`data/approvals.jsonl`

Approval lifecycle records across pending, approved, denied, and expired states.

`vault/`

Governed memory structure for raw notes, promoted references, active outputs, and dated handoffs.

{
  "run_id": "RUN-20260520-123456",
  "skill": "research_digest",
  "inputs_hash": "a8f5b2c9d1e4",
  "outputs": ["vault/wiki/digest_sample_note_2026-05-20.md"],
  "status": "success",
  "timestamp": "2026-05-20T16:28:00.764Z"
}

Skill Surface

morning_brief

Creates a dated briefing from recent daily artifacts.

vault_cleanup

Promotes structured raw notes into curated reference material.

research_digest

Converts an input note into a structured digest in the wiki tier.

continuation_brief

Creates a handoff document for the next working session.

policy_simulator

Evaluates proposed actions against active policy without executing them.

Getting Started

chmod +x install.sh
./install.sh
agentic-os list
agentic-os run morning_brief
agentic-os approvals list --status pending
execution-simulator
operator@control-plane %

Roadmap

Version Status Scope
v0.1 Completed Governed local execution, append-only audit records, skill registry, and bounded writes.
v0.2 In progress Approval lifecycle management and rerun behavior for gated actions.
v0.3 Planned Static operational dashboard for runs, approvals, and policy distributions.
v0.4 Planned Optional governed adapters for external tool surfaces.