Add contributor and agent guidance documentation#33
Merged
Conversation
Add human- and agent-facing contribution docs:
- CONTRIBUTING.md: setup, dev workflow, the CI-mirroring checks
(nox -s lints / nox -s tests), code style, architecture boundaries,
docs build, and private security reporting.
- AGENTS.md: canonical agent guidance — overview, commands, style
conventions, and the engine/api invariants (the one-door
apply_action, tagged-union schemas, no HTTP in the engine).
- .github/copilot-instructions.md: defers to AGENTS.md for general
context and adds a Copilot code-review focus list; kept under the
~4k-char code-review limit.
- .github/ISSUE_TEMPLATE/{bug_report,feature_request,config}.yml:
issue forms; config routes rules/cards questions to the meta repo.
- .github/PULL_REQUEST_TEMPLATE.md: contributor checklist.
Code of Conduct and Security policy are inherited org-wide from
letsbuilda/.github, so no repo-level copies are added.
https://claude.ai/code/session_013SBs3pqpzAqQWuaExZfEzc
Set `type: Bug` and `type: Feature` on the issue forms and drop the `bug`/`enhancement` labels, using GitHub's org-level issue types. https://claude.ai/code/session_013SBs3pqpzAqQWuaExZfEzc
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
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
This PR adds comprehensive documentation for contributors and AI coding agents working on mundane-backend. These new files establish clear guidelines for development workflow, code style, architecture boundaries, and project setup.
Key changes
CONTRIBUTING.md: A contributor-focused guide covering prerequisites, local setup, development workflow, checks to run before pushing, code style expectations, architecture boundaries to respect, testing practices, documentation updates, dependency management, and security reporting.AGENTS.md: A detailed guide for AI coding assistants (e.g., GitHub Copilot) with project overview, setup instructions, build/run/test commands, linting and formatting details, code style rules, architecture and layout, key invariants to preserve (engine/API separation, theapply_actionsingle door, tagged union actions), gotchas (Litestar 3 pre-release status, CI resolution strategy, GitHub Actions security), and a pointer to human-focused docs..github/copilot-instructions.md: Copilot-specific guidance emphasizing code review priorities (layering, the one door, illegal move handling, action schemas, types/docs, style, tests, dependencies, Litestar 3 status) and code generation best practices..github/ISSUE_TEMPLATE/bug_report.yml: Structured bug report template with fields for description, reproduction steps, expected behavior, environment, and logs; includes a note that rules and cards are in the meta repo..github/ISSUE_TEMPLATE/feature_request.yml: Structured feature request template with fields for problem/motivation, proposed solution, alternatives, and context; directs rules/card changes to the meta repo..github/ISSUE_TEMPLATE/config.yml: Issue template configuration disabling blank issues and providing contact links to the meta repo (for rules/cards) and documentation site..github/PULL_REQUEST_TEMPLATE.md: PR template with a summary section, related issues field, and a checklist covering linting, testing, docs, dependencies, and architecture boundaries.Notable implementation details
apply_actionfunction inengine/rules.pyis established as "the one door" through which all state changes must pass.uv>= 0.11.8, Litestar 3 from gitmain, ruff withline-length = 120andselect = ["ALL"],mypy --strict).https://claude.ai/code/session_013SBs3pqpzAqQWuaExZfEzc