Skip to content

Add contributor and agent guidance documentation#33

Merged
shenanigansd merged 2 commits into
mainfrom
claude/adoring-euler-9FUGH
May 31, 2026
Merged

Add contributor and agent guidance documentation#33
shenanigansd merged 2 commits into
mainfrom
claude/adoring-euler-9FUGH

Conversation

@shenanigansd
Copy link
Copy Markdown
Member

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, the apply_action single 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

  • All documentation emphasizes the core architectural principle: engine has no HTTP knowledge; API is the only HTTP layer. This boundary is highlighted repeatedly across all guides.
  • The apply_action function in engine/rules.py is established as "the one door" through which all state changes must pass.
  • Clear separation of concerns: rules and cards spec live in the meta repo; this repo is the engine and API implementation.
  • Specific tool versions and configurations are documented (Python 3.14+, uv >= 0.11.8, Litestar 3 from git main, ruff with line-length = 120 and select = ["ALL"], mypy --strict).
  • Issue templates and PR template guide contributors toward the right repository for different types of changes.

https://claude.ai/code/session_013SBs3pqpzAqQWuaExZfEzc

claude added 2 commits May 31, 2026 18:18
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
@shenanigansd shenanigansd merged commit ff966ac into main May 31, 2026
12 checks passed
@shenanigansd shenanigansd deleted the claude/adoring-euler-9FUGH branch May 31, 2026 18:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants