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

Check	Evidence
Application agents and teams are deliberately registered, with stable IDs	Source declarations, app/main.py, app/config.yaml
Framework-owned components stay in Agno	OSManager(...), CompanyConfig(...), installed framework source
Shared resources and Studio capabilities match documentation	app/registry.py, db/, AgentOS registration
Configuration names, defaults and prerequisites agree	Environment reads, example.env, README, Compose, deployment scripts
Documented commands and file paths work	Scripts, skills, CLI help and installed signatures
Skills remain discoverable and their routing is coherent	Frontmatter, relative links, .claude/skills, CLAUDE.md
Eval targets, tool names and CLI examples exist	evals/cases.py, evals/__main__.py, installed Agno eval APIs
Sandbox documentation matches execution and persistence requirements	app/sandbox.py, agents/engineers.py, Dockerfile, README
MCP claims match the exposed interface and authentication behavior	app/interfaces.py, app/main.py, scripts/mcp_check.sh

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 declares agentos-maintenance: Company Manager reviews releases and the codebase every day at 09:00 UTC, proposes up to three Backlog Tasks and has automatic acceptance disabled. Verify the declaration against saved schedule state; do not infer successful execution from its presence. Before removing or renaming a component in an existing deployment, inspect saved schedules and Studio references read-only when access is available. Source absence does not establish that a saved record is absent. 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 engineer 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 eval-and-improve, and an explicitly requested deployment to deploy-platform.