Kniepunkt/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).

---

Documentation MCP policy

• We run ONE docs MCP server: docs (multi-library).

Library selection

• For any docs query call (everything except list_libraries), you MUST set library.
• If the prompt or repo context involves a specific product/project unambiguously, use that as library (e.g. library="haystack").
• If more than one library could plausibly match, call list_libraries and select the best match (do not invent/guess library ids).
• If the task spans multiple products, run separate docs calls per library and label results by library.

Version selection

• If the prompt or repo context involves a version or range (e.g. 2.25, 2.x), call find_version(library=..., targetVersion=...) and record the returned version.

• Use that resolved version for all subsequent calls for that library.

• If find_version cannot resolve unambiguously, stop and ask.

• If no version is mentioned, omit version (defaults to latest indexed for that library).

• We also run the github MCP server. Consult it always for code that is in public github instead of searching at the disk or cloning the repos locally.

---

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"

Notes:

• This supports long-lived feature integration branches and stacked PRs.
• The base branch may itself be another PR branch (for stacking); set BASE_BRANCH accordingly.

---

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 only 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

---