Agent Startup Guide

Mission

The Repository Operating System (ROS) makes research, engineering, decisions, and handoffs durable without relying on conversation history or tribal knowledge.

Start Here

1. Read the governance index.
2. Identify the task's scope and operating mode.
3. Locate the applicable canonical domain records; inspect the repository and user changes before editing.
4. State or record material unknowns, constraints, assumptions, and risks.
5. Use the smallest process that preserves correctness, traceability, and continuity.
6. Execute, validate, update affected records, and leave a handoff.

Detailed rules are in the Agent Operating Manual. Research packages follow the REP Specification; engineering follows the Engineering Standards.

Authority

Apply, in descending order: explicit user instruction; applicable safety, legal, and platform constraints; canonical governance; accepted domain REPs and theory; accepted architecture and decision records; current implementation; local convention; agent preference. A higher authority cannot authorize a violation of an applicable safety or legal constraint. When same-level sources conflict, prefer the narrower and newer accepted record and document the resolution; escalate if the outcome materially changes the authorized goal.

Core Rules

• Never fabricate evidence, file reads, approvals, commands, test results, or certainty.
• Preserve user work. Inspect before modifying; do not destroy or irreversibly migrate without authorization.
• Make reasonable, reversible, in-scope decisions. Escalate high-impact irreversible, security/privacy-sensitive, legally ambiguous, or materially out-of-scope decisions.
• Research by testing hypotheses against confirming and falsifying evidence. Engineering by establishing a baseline, defining acceptance criteria, making the smallest robust change, and testing in proportion to risk.
• Important claims cite EV-, HY-, and TH- records when those records exist. Material decisions use DF-, which canonically means Decision Record.
• Do not silently change canonical policy. Propose or record the change, its evidence, consequences, version, and migration path.
• Do not claim a test passed unless it ran and passed. Name skipped or unavailable checks and their implications.
• Not every edit needs a REP. Use the artifact threshold in the Agent Operating Manual.

Handoff

For substantial work, record: objective; work completed; files changed; decisions and assumptions; tests run and results; evidence added; unresolved questions; risks; and next recommended action. A capable successor must be able to continue without the originating conversation.

Work Protocol

Before meaningful mutation, identify the external work item and run ./ros work begin ID. Inspect ./ros work context ID for allowed actions and required evidence, perform the bounded work, gather configured evidence, request a legal transition with work complete, then run ./ros registry build and ./ros validate. Use work block --reason and work resume rather than hand-editing context. Use ./ros status when resuming unfamiliar work. Meaningful committed changes require machine-readable attribution; see docs/work-protocol.md.

AI Engineering Repository Instructions

In addition to ROS governance, agents working in this repository must:

1. Read CURRENT-STATE.md before making material changes.
2. Read the relevant canonical artifact in content/, docs/, ai-prompts/, or templates/ before editing related files.
3. Preserve provenance when moving, merging, archiving, or superseding content.
4. Update CURRENT-STATE.md, ROADMAP.md, and CHANGELOG.md when repository state materially changes.
5. Record significant import, merge, and canonicalization decisions under docs/repository/ when they affect repository structure.
6. Validate actual paths, references, and command results before claiming completion.
7. Prefer small, reversible changes over broad speculative rewrites.

The import audit for the current repository state lives in docs/repository/imports/2026-07-22-input-documents-import/.