Orchestrator/shared/AI-Orchestrator/AGENTS.md

AGENTS.md

---

Coding rules

1. Read SPEC.md first and treat it as source of truth ("the spec"). If SPEC.md does not exist, stop and ask.
2. Follow the user prompt exactly; do not omit explicitly requested steps.
3. Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused:

• Scope: Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.
• Documentation: Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.
• Defensive coding: Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs).
• Abstractions: Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task.
• Custom coding: Don't reinvent the wheel, use the functions the framework provides you with. If you think that using framework is not possible, consult the relevant online or MCP docs to make sure. If you still cannot find a solution within the framework, stop and ask.

4. Do not hard-code values or create solutions that only work for specific test inputs; implement the actual logic that solves the problem generally.
5. The resulting code must be robust, maintainable, and extendable.
6. The resulting code must not contradict the spec.
7. Before writing code, post a short and concise "Plan + spec mapping" summary and ask for approval to proceed. Do not implement until you receive the go-ahead.
8. Documentation Rules:

• filenames are always capitalized.
• describes the current state only. Do not include change/history phrasing.
• must always be coherent end-to-end never have stale or conflicting info.

9. Always use repo virtual environment (unless there is none).

---

Testing policy

• Property-based tests (hypothesis) for all domain logic — required.
• Property test files use _properties suffix: test_<module>_properties.py
• Run full suite: pytest
• Run specific: pytest tests/test_<module>.py
• Type check: mypy src/
• Lint: ruff check .

---

Base branch rule

BASE_BRANCH = the branch that new work branches are created from and PRs target.

Default:

• If the user did not explicitly specify a base/target branch, set:
  • BASE_BRANCH=$(git branch --show-current) (from the user's main checkout at session start)

Override:

• If the user explicitly specifies a base/target branch in the prompt, use that as BASE_BRANCH.

Remote base ref:

• If origin/$BASE_BRANCH exists, use that as BASE_REF, else use $BASE_BRANCH:
  • git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH" && BASE_REF="origin/$BASE_BRANCH" || BASE_REF="$BASE_BRANCH"

---

Before work

1. Determine base branch (unless user specified it explicitly):

• BASE_BRANCH=$(git branch --show-current)

2. Fetch latest refs:

• git fetch origin --prune

3. Update base branch (fast-forward only) if it has an origin/ tracking ref:

• git switch "$BASE_BRANCH"
• if git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH"; then git pull --ff-only origin "$BASE_BRANCH"; fi
• If the pull fails for any reason, stop and ask.

4. Read SPEC.md + README.md once per session. Re-read only if changed/unsure:

• git log -1 --oneline -- SPEC.md README.md

5. If deviating from SPEC.md: stop and ask.
6. Create a new local work branch (once per session) from BASE_BRANCH. ALWAYS push to the branch you created.

• git switch -c "agent/<topic>-YYYYMMDD-<shortid>"

Tests

• Run tests if the prompt requests or SPEC.md requires them; run all requested tests.
• If any cannot be run: stop and ask.

After work

1. Make sure you did not miss requested tests.
2. If you are addressing a remote github issue with

• "to-do" checklist: for each item, make sure your implementation is fully complete and:
  • if yes, check it off
  • if not, finish implementation and recheck.
• "acceptance" checklist: for each item, make the acceptance criterion is completely fulfilled and:
  • if yes, check it off
  • if not, implement missing code and recheck.

3. Update all relevant documentation appropriately.
4. Before making a commit: Stop and ask user to /review → Review uncommited changes.
5. Commit only after user confirms code review passed.
6. Open a PR or use already opened PR

• use your created branch.
• Target BASE_BRANCH.
• PR text requirements:
  • commands in backticks
  • real newlines (ANSI-C quoting/heredoc)
  • if addressing a remote github issue, reference it so that github can close automatically after merging.

7. Only after PR is merged:

• switch back to base branch and sync it
  • git switch "$BASE_BRANCH"
  • git fetch origin --prune
  • if git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH"; then git reset --hard "origin/$BASE_BRANCH"; fi
  • If the reset fails, stop and ask.
• delete the local merged work branch

---

Required completion checklist (final response)

• Base/target branch used correctly (BASE_BRANCH)
• all Coding rules followed
• All requested tests run (commands + results), or blocked → asked
• Documentation updated appropriately: list updated files
• PR opened (summary + command log) targeting BASE_BRANCH
• After merge (if applicable): base branch synced; merged branch deleted

---