Review and Improve

Review the requested scope against AGENTS.md and the actual implementation. When comparing with a branch or PR, record the base and head SHAs, and distinguish committed changes from local edits. A review-only request stays read-only. For a review-and-improve request, correct clear documentation and link errors within scope; report behavior changes separately unless the user has authorized their repair.

1. Establish the scope

Inspect the working tree before editing and preserve concurrent changes. Review the named files first. A repository-wide pass covers README.md, AGENTS.md, example.env, skills, app/, agents/, teams/, db/, evals/, scripts/, and build/deployment configuration. Include user-added workflows or other directories when present. Exclude environments, caches, generated files and Git internals from content scans. Do not print env-file values.

A running API is not required for the source review. Establish whether development uses Compose or the host API before attempting runtime checks; use the matching README commands. If a runtime is unavailable or belongs to another checkout, continue the source review and report the runtime verification gap.

2. Compare declarations, documentation and behavior

Do not register every file found under agents/ or invent manifest entries for internal components: determine whether it is an intended public component, a helper or framework-owned. OS Manager, its members and Company Manager are framework-owned; do not restore the old application-owned manager/builder/engineer stack. OS, Company and queue storage reuse get_postgres_db(); knowledge content adapters have distinct IDs.

app/company.py defines the daily agentos-maintenance review, disabled by default. To start it, enable it from the Company page in the AgentOS UI. Proposed Tasks are not automatically accepted. Check saved schedules and Studio references before renaming or removing components. Preserve historical sessions, notes and Company records.

3. Verify proportionately

Use static checks first:

source .venv/bin/activate
./scripts/validate.sh
git diff --check

For shell changes, run bash -n on the affected scripts. After authorized edits, format only as needed and inspect the resulting diff. Use disposable local fixtures to reproduce script failures when useful; keep the starter free of a bundled regression-test suite. CLI help and mock fixtures do not establish successful cloud deployment.

For an available local API, verify /health and the relevant component listing using its configured authentication. Confirm the process or container serves this checkout before drawing conclusions. Run scripts/mcp_check.sh in Compose mode, or MCP_CHECK_HOST=1 ./scripts/mcp_check.sh for the host API. The default MCP check proves initialization and required tool availability, not an agent answer.

Run model probes or evals only within the user's authorized scope and budget. Inspect available cases before selecting a tag; do not assume release or live cases exist. Even eval CLI help/list commands import knowledge storage and require PostgreSQL; inspect evals/cases.py directly when the database is unavailable. Evals use the application's database and persist sessions and results. Use explicitly owned fixtures for mutating cases; do not restore snapshot-diff cleanup or delete historical data. Do not smoke every coding agent automatically: those runs can execute code and modify workspaces. HTTP availability, direct execution, delegation and Company Task completion are separate checks.

4. Report

Lead with actionable findings: severity, file and line, triggering condition, observed or source-backed consequence, and recommended fix. Label inherited issues separately from regressions against the comparison base. Explain what was corrected and what remains. Give a sharing or merge recommendation limited to the reviewed scope.

Record verification in tmp/VERIFY.md when making changes, separating static, deterministic, model, container and hosted results. Report skipped checks and their limits; do not equate a passing linter or mock fixture with a healthy deployed platform.

Route agent behavior changes to extend-agent, missing eval coverage to create-evals, eval failures and agent hardening to improve, and an explicitly requested deployment to deploy-platform.