50 lines
3.3 KiB
Markdown
50 lines
3.3 KiB
Markdown
# Agent Operating Protocol
|
|
|
|
This document outlines the mandatory protocol for all agents operating within the OSVauco repository.
|
|
|
|
## Evidence hierarchy
|
|
1. **Live platform/API state** is authoritative for runtime, IAM, build, deploy, traffic, and infrastructure state.
|
|
2. **Remote Git branch and immutable commit SHA** are authoritative for versioned repository artifacts.
|
|
3. **Local Git state** is authoritative for the current workstation checkout.
|
|
4. **`WORKING_STATE.md` and `DECISIONS.md`** communicate intended work, known status, and rationale, but do not override live verification.
|
|
5. **Chat, terminal scrollback, and agent memory** are non-authoritative context.
|
|
|
|
## Session startup protocol
|
|
Every agent must perform the following steps at the beginning of a new session:
|
|
|
|
1. Read `docs/WORKING_STATE.md` and `docs/DECISIONS.md`.
|
|
2. Run the approved read-only workspace status command: `bash scripts/workspace-status.sh`.
|
|
3. State the current branch, local SHA, remote SHA, any dirty files, the current objective, verified facts, blockers, and propose one single next action based on this information.
|
|
4. Wait for explicit approval from the operator before taking any action that modifies files or infrastructure.
|
|
|
|
## Change protocol
|
|
Every agent must adhere to the following protocol when making changes:
|
|
|
|
1. Identify the smallest possible set of files affected by the proposed change.
|
|
2. Present a concrete proposed diff or an exact, detailed plan of the changes to be made.
|
|
3. After receiving approval, execute the change.
|
|
4. Run focused, relevant tests to verify the change. Do not run unrelated tests.
|
|
5. Report the exact test commands used and their pass/fail results.
|
|
6. Commit changes in small, coherent, logical units.
|
|
7. Push commits to the remote repository only after explicit approval or as part of a pre-approved workflow.
|
|
8. Deploy changes only through the canonical, approved deployment flow and only after receiving explicit approval for the deployment itself.
|
|
|
|
## Completion protocol
|
|
Upon completing a task, every agent must:
|
|
|
|
1. State the exact files that were created or changed.
|
|
2. State the exact tests that were run and their results.
|
|
3. State what was *not* changed to provide clarity on the scope of the work.
|
|
4. Update `docs/WORKING_STATE.md` if the `Current objective`, `Current deployment state`, `Current blockers`, or `Next single action` have changed as a result of the work.
|
|
5. Never claim infrastructure state (e.g., "deployed") without performing a live, read-only verification command and showing the result. An agent must distinguish committed, pushed, build-created, build-succeeded, revision-created, traffic-shifted, and live-verified states.
|
|
|
|
## Hard-stop protocol
|
|
An agent must stop all work and ask the operator for direction when any of the following conditions are met:
|
|
|
|
- Required configuration, source code, identity, or a target branch is unknown or ambiguous.
|
|
- A proposed command would create, modify, or deploy infrastructure unexpectedly.
|
|
- A test failure occurs that is unrelated to the approved task.
|
|
- A proposed change would expand permissions, firewall rules, or security scope.
|
|
- It is suspected that an existing system or component may already solve the problem at hand.
|
|
- The requested action conflicts with the current objective or rules listed in `docs/WORKING_STATE.md` or `docs/DECISIONS.md`.
|