docs(agent): add repository agent harness and dev-tool preflight#185
Merged
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
1 task
gknapp1
reviewed
Jun 1, 2026
gknapp1
reviewed
Jun 2, 2026
gknapp1
left a comment
gknapp1
left a comment
Collaborator
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?
gknapp1
reviewed
Jun 3, 2026
gknapp1
reviewed
Jun 3, 2026
- remove Codex-specific scope from repo - focus agent instructions through repo documentation and architecture map
Collaborator
|
@liamnwhite1, I pushed changes that address my comments. Thoughts? |
- Shortened AGENTS.md into a routing-focused entrypoint (~1900 tokens -> ~1400 tokens) - Relaxed scripts/check_docs_harness.py to check key structure, required links, link validity, and compactness. - Updated scripts/check_dev_tools.py with shell-neutral PATH/cache guidance. - Updated docs in ARCHITECTURE.md, docs/developer_guide.md, and docs/documentation.md. - AI contribution: human-led and edited, gpt-5.5 feature implmentation drafting
- documentation should not be an issue tracker, leave that to GitHub site - updates header name in doc harness check
gknapp1
approved these changes
Jun 19, 2026
gknapp1
left a comment
gknapp1
left a comment
Collaborator
There was a problem hiding this comment.
Overall, think this is a useful addition to the documentation. I've added my changes and made some corrections, so this is good to go for now.
We can iterate if the agent-specific instructions need tweaking or if some aspects of the docs become routinely stale.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.