Project files

Initialization materializes a control plane into each linked repository. Most of it is meant to be committed: config, policy, specs, and promotion history are part of the project’s record.

<repo>/
├── .openloop/
│   ├── project.json          # per-project config (edit freely)
│   ├── policy.yaml           # scope & risk policy (edit freely)
│   ├── tasks.json            # task ledger, runtime-managed
│   ├── tasks.schema.json     # ledger JSON schema
│   ├── specs/                # generated task specs (plan mode)
│   ├── runs/                 # per-run summaries (markdown)
│   ├── promotions/           # promotion artifacts
│   ├── promotion-results/    # outcomes of applied promotions
│   ├── verifications/        # independent verifier verdicts
│   ├── approvals/            # human-approval packets
│   ├── worktrees/            # isolated run worktrees (opt-in)
│   └── backup/<timestamp>/   # pre-force-init backup
├── .pi/
│   ├── SYSTEM.md             # agent system prompt
│   └── APPEND_SYSTEM.md      # appended per-run instructions
└── .agents/
    └── skills/
        └── openloop/
            └── SKILL.md      # agent workflow instructions

Also: a fenced <!-- openloop:start --> … <!-- openloop:end --> section is merged into the repo-root AGENTS.md so any agent working in the repo knows the OpenLoop conventions.

What’s safe to edit

File	Guidance
project.json	Yours: the source of truth for project config.
policy.yaml	Yours; review it like code.
.pi/SYSTEM.md, SKILL.md, AGENTS.md section	Yours; tune how agents behave in this repo.
tasks.json	Prefer the task commands; hand-edit only for bulk surgery.
runs/, promotions/, …	Runtime-managed: read, don’t rewrite.

project init --force backs up the whole .openloop/ to .openloop/backup/<timestamp>/ before re-materializing templates.

Global state

~/.openloop/ (or $OPENLOOP_HOME) holds config.json, projects.json, and run/ (pid, state, log, events.jsonl). Logs rotate at 10 MB (3 kept); the event log at 10 MiB. See architecture.