Agent Context Guide

Map for AI coding agents working on Testosterone (testo-core, CLI testo): which note to read before touching what, so you don't have to scan the whole codebase. Adopting Testosterone in another project instead? Use the Setup Prompts.

Where to look

• Architecture & flow: System Diagram is the one-picture view. Before changing execution logic, runtime state or core modules, read Architecture Overview and Deep Dive - Execution Logic. Don't guess the lifecycle phases.
• CLI changes: before adding or changing a command, flag or exit code, read Command Reference and Troubleshooting and Error Codes. tests/contract/testo_core/test_cli_docs_drift.py fails if the reference documents a command that doesn't exist.
• CI and releases: CI-CD Pipeline Setup, QA Strategies § CI and streaming output, and the publishing guides (PyPI, Docker images, Artifactory).
• Pages demo: GitLab Pages Demo (covers GitHub Pages too).
• Reporting: QA Strategies § How results are logged and surfaced and the reporter section of Command Reference.
• E2E harness: E2E Harness Operations Guide.
• Docs vault, wiki and site: vault schema, Docs Vault and Wiki Sync and Docs Site. Images go under docs/assets/ and must be embedded from a note to reach Obsidian and the wiki. A new note gets a nav entry in mkdocs.yml to show in the site's menu.
• Getting started: Getting Started is tested by examples/getting-started/ in CI. A change to the commands or config it shows updates both.
• UI: the React frontend in frontend/ is the only UI; its API types are generated from FastAPI's OpenAPI schema.
• Delta semantics: Delta Comparison Policy.
• Design decisions: Specs & ADRs.
• Open debt and next steps: Technical Debt Tracker, Product Roadmap.
• History: dated plans, audits and phase checklists are in Archive. They describe the code as it was, not as it is.

Rules

The full conventions (frontmatter, ingest / query / lint, the log) are in the vault schema; python scripts/docs_vault.py lint checks them.

1. Read before writing. Check the relevant note above before refactoring core architecture or changing a CLI argument.
2. Keep docs in step. If you change a CLI command, execution state logic or infrastructure setup, update the matching note under docs/ in the same pull request. Bump the note's updated date.
3. Point, don't paste. If a note already explains something, link to it instead of repeating it.
4. Links. Use standard relative markdown links with spaces encoded as %20 (e.g. [Command Reference](../CLI%20Commands/Command%20Reference.md)), so they work on GitHub and in Obsidian. When you move or rename a note, update the links to it and Index in the same change.