ankn
e08c484838
Six-step weekly workflow (research → sources → storyline → draft → quality → publication) supporting Claude, ChatGPT, Gemini, and Mistral in parallel for creative steps. Web search via Anthropic tool for news research. Episode index built from 34 existing KNIEPUNKT episodes for redundancy checks. Sessions persisted as JSON for mid-workflow resume. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
123 lines
6.7 KiB
Markdown
123 lines
6.7 KiB
Markdown
# 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
|
|
---
|