docs(agent): add repository agent harness and dev-tool preflight#185
docs(agent): add repository agent harness and dev-tool preflight#185liamnwhite1 wants to merge 2 commits into
Conversation
Add a repository-level agent harness so future coding agents and contributors can orient themselves, validate their environment, and make architecture-respecting changes from a fresh clone. Added: - Add root ARCHITECTURE.md with verified repository structure, runtime model, core concepts, control flow, dependency boundaries, extension points, validation commands, docs architecture, external dependencies, and known gaps. - Add root AGENTS.md as the compact agent entrypoint with setup commands, repository map, architecture rules, testing guidance, documentation rules, and handoff checklist. - Add docs/testing.md to document pytest markers, default tests, external-app tests, CI expectations, and skipped-check reporting. - Add docs/documentation.md to document MkDocs, generated API docs, agent harness maintenance, and documentation update rules. - Add docs/decisions/ with an index and lightweight ADR template. - Add scripts/check_docs_harness.py to verify required harness files, required headings, AGENTS.md links, and the AGENTS.md -> ARCHITECTURE.md relationship. - Add scripts/check_dev_tools.py to verify fresh-clone development readiness, including Python version, uv availability, writable caches, uv lock state, project Python, and dev tools available through uv run. Changed: - Wire the docs harness check into pre-commit and CI. - Update docs navigation for testing, documentation, changelog, and decisions. - Update README development links to point to the new architecture, agent, and testing docs. - Update developer setup docs to run the dev-tool preflight before and after syncing dev dependencies. - Fix the documented external-app pytest command from `uv run pytest --apps` to `uv run pytest -m apps`. Rationale: - Make repository knowledge the system of record for future agents and maintainers. - Avoid relying on local shell state, hidden setup assumptions, or chat history. - Give agents a deterministic first command for detecting missing tools, unwritable caches, unsynced dev dependencies, and docs-generation Python parity issues. - Keep AGENTS.md short while linking to deeper, focused documentation. Validation: - python scripts/check_dev_tools.py - uv run --frozen --no-sync python scripts/check_docs_harness.py - uv run --frozen --no-sync ruff check scripts/check_dev_tools.py scripts/check_docs_harness.py - uv run --frozen --no-sync ruff format --check scripts/check_dev_tools.py scripts/check_docs_harness.py - uv run --frozen --no-sync scripts/group_docs.py - uv run --frozen --no-sync mkdocs build --strict - uv run --frozen --no-sync pytest - uv run --frozen --no-sync pre-commit run --files <changed files> - git diff --check
gknapp1
left a comment
gknapp1
left a comment
There was a problem hiding this comment.
A bit hard to quantify effectiveness here, but I tested out the agent harness this seems to be reducing the context size compared to what I had previously seen (~50k tokens for a broadly scoped planning prompt instead of of ~100k). And documentation is useful, even outside of agentic coding applications.
My main concern is the decisions template. In having an agent plan changes, including assessing if a decision document was needed, it seems to either prefer writing a decision document over updating architecture.md (creating a documentation mismatch) or updating both (unncessary duplication). Is there any strong benefit to having the lengthier decision document over making sure that architecture.md stays up to date and maybe includes some short rationale for decisions in key places?
| ## Reporting Skipped Or Unavailable Checks | ||
|
|
||
| When handing off work, include: | ||
|
|
||
| - the exact command run; | ||
| - whether it passed or failed; | ||
| - the reason if it could not run, such as missing external executable, unavailable | ||
| optional extra, container dependency, or network restriction. | ||
|
|
||
| Do not replace a missing external-app test with a default pytest run and call the | ||
| external behavior covered. Say what was covered and what remains unverified. |
There was a problem hiding this comment.
Since this is agent-only instructions, this would better in an AGENTS.md within tests?
There was a problem hiding this comment.
If "pragmatic" and "gpt-5.5" are the only settings we are enforcing in config.toml, why include a .codex directory in Myna? These configurations are outside of Myna's scope. AGENTS.md can be moved to the repo root and then be portable for different model providers.
There was a problem hiding this comment.
I see the use of enforcing that AGENTS.md must link the ARCHITECTURE.md document. But the required headings seem overly prescriptive and add bloat that has to be maintained. Does the heading check solve a particular issue?
2 participants
Summary
Adds a repository-specific agent and documentation harness for Myna so maintainers, contributors, and coding agents can orient themselves from a fresh clone and validate the local development environment before making changes.
Related issues
Details
This is a documentation and maintenance change. It addresses generic
.codexguidance by adding a Myna-specific repository harness.The implementation adds:
.codex/AGENTS.mdas the compact coding-agent entrypoint with setup, commands, testing guidance, architecture rules, documentation rules, PR guidance, security notes, and handoff checklist.ARCHITECTURE.mdas the detailed repository map covering runtime model, workflow concepts, control flow, dependency boundaries, extension points, validation, docs architecture, external systems, and known gaps.docs/testing.mdfor pytest markers, default tests, external-application checks, CI expectations, and skipped-check reporting.docs/documentation.mdfor MkDocs/LazyDocs maintenance, generated API docs, docs update rules, and agent harness maintenance.docs/decisions/with an index and lightweight ADR template.scripts/check_dev_tools.pyfor fresh-clone/dev-shell preflight checks.scripts/check_docs_harness.pyfor required harness headings and.codex/AGENTS.mdlink validation.The docs harness check is wired into pre-commit and main CI. README, developer guide, getting started docs, and docs navigation were updated to point at the new surfaces. The documented external-app pytest command was also corrected to
uv run pytest -m apps.Impact
No Myna runtime behavior, CLI behavior, public workflow input format, database behavior, or simulation output behavior is changed.
Risk level: Low. The change is limited to documentation, standalone maintenance scripts, and CI/pre-commit harness validation.
Testing strategy
Environment used while drafting:
uv-managed development environment1e952cbValidation:
python scripts/check_dev_tools.pyuv run --frozen --no-sync python scripts/check_docs_harness.pyuv run --frozen --no-sync ruff check scripts/check_dev_tools.py scripts/check_docs_harness.pyuv run --frozen --no-sync ruff format --check scripts/check_dev_tools.py scripts/check_docs_harness.pyuv run --frozen --no-sync scripts/group_docs.pyuv run --frozen --no-sync mkdocs build --strictuv run --frozen --no-sync pytestuv run --frozen --no-sync pre-commit run --files <changed files>git diff --checkpython3 scripts/check_docs_harness.pyExternal application tests were not rerun because this PR is limited to documentation, repository maintenance scripts, and harness validation.