Skip to content

AGENTS.md

Latest commit

 

History

History
140 lines (90 loc) · 9.63 KB

AGENTS.md

File metadata and controls

140 lines (90 loc) · 9.63 KB

Agent instructions — IPTV Tunerr

Instructions for AI agents and maintainers. This repo is IPTV Tunerr (IPTV→Plex bridge); it also uses the agentic template workflow (memory-bank, verify, docs). Main app: cmd/iptv-tunerr. Navigation: memory-bank/repo_map.md.

Tool-compat: Tools that look for agents.md can use agents.md, which points here. Commands are authoritative in memory-bank/commands.yml; CI runs scripts/verify (no drift).

Communication style

These interaction rules are standard for all model interfaces used with this repo, including Hermes, Codex CLI, Claude CLI, Kilo CLI, OpenCode, Cursor, and similar agents:

  • Never praise questions or validate premises before answers.
  • If the user is wrong, say so immediately and directly.
  • Do not capitulate under pushback unless new evidence or a stronger argument is provided.
  • Do not anchor on numbers or estimates provided by the user. Generate an independent assessment first, then compare.
  • Use explicit confidence levels when making claims, recommendations, or estimates: high, moderate, low, or unknown.
  • Do not add disclaimers.
  • Do not give ethics lectures unless explicitly asked.
  • Do not use "it is important to consider" style hedges.
  • Surface negative conclusions and bad news directly.
  • Optimize for accuracy, not approval.
  • If you do not know, say so. Never fabricate.

Commands (authoritative)

Do not guess commands. Use memory-bank/commands.yml (machine-readable). CI runs scripts/verify, which runs scripts/verify-steps.sh if present (format → lint → test → build or whatever the project defines).

If scripts/verify-steps.sh is missing, verify exits success so the template stays green until you add your own checks. Update memory-bank/commands.yml when you add or change verification steps.

Memory bank (required)

Maintain a /memory-bank/ directory and use it. It is the single source of truth for project state that should persist across sessions and handoffs.

Files to keep updated

File Purpose
memory-bank/current_task.md What is being worked on right now: goal, scope, and next steps. Update at session start and when focus changes so the next agent (or you later) knows where things left off.
memory-bank/known_issues.md Known bugs, limitations, and design tradeoffs. Add when you discover or fix something non-obvious so others don't re-fight the same battles.
memory-bank/recurring_loops.md Critical: Recurring agentic loops, bugfix loops, and hard-to-solve problems that keep coming back. Document them here with: what keeps happening, why it's tricky, and what actually works. Future agents should read this first to avoid repeating the same mistakes and to get early warnings about fragile areas.
memory-bank/opportunities.md Lightweight backlog for security/perf/reliability/maintainability/operability discoveries. File out-of-scope improvements here; raise to user in summary.
docs/explanations/project-backlog.md Open work index: links LTV/LP epics, opportunities, known_issues, docs-gaps, and features § limits — single orientation page (details stay in those sources).
memory-bank/task_history.md Append-only log of completed tasks (summary, verification, opportunities filed).
memory-bank/repo_map.md Navigation: main entrypoints, key modules, hot paths, no-go zones. Check before wandering.
memory-bank/commands.yml Machine-readable verification commands; scripts/verify runs scripts/verify-steps.sh (which should align with this file).
memory-bank/code_quality.md Code and doc quality: "done" includes doc updates when behavior changes; docs as code.
memory-bank/work_breakdown.md Multi-PR epics only: WBS + story list + PR plan. Use when >1 PR or scope warrants it; see guardrail below.

Doc layout (Diátaxis): docs/index.md (tutorials, how-to, reference, explanations, adr, runbooks). New docs: frontmatter + See also; see docs/_meta/linking.md.

How to use the memory bank

  • At session start: Read current_task.md, known_issues.md, recurring_loops.md, and repo_map.md (navigation) before making changes.
  • When taking on work: Set or update current_task.md (goal, scope, next step).
  • When hitting a recurring or painful issue: Add or update recurring_loops.md with the pattern and the resolution (or "still open").
  • When discovering a limitation or bug: Add to known_issues.md with enough context to reproduce or work around.

Phrase entries so that another agent can act on them: concise, actionable, and with "why" where it helps.

Work breakdown (multi-PR only) — guardrail

  • One PR: Use only current_task.md (objective, success criteria, In/Out, plan, verification). No work breakdown.
  • More than one PR: You must create or update the work breakdown (memory-bank/work_breakdown.md or docs/epics/EPIC-*.md) and only work on items listed there. Every task/PR must reference a story ID. Park improvements in opportunities.md; don't hijack the epic.

When to create a work breakdown: Any of: will take >1 PR, touches >~5 modules/areas, multiple stakeholders/UX choices, non-trivial migration/rollout, meaningful security/perf implications. When to use which: PR-sized → current_task.md only; product scope → docs/product/PRD-template.md; multi-PR epic → work_breakdown.md or docs/epics/EPIC-*.md; story = row in that breakdown (or docs/stories/STORY-template.md for format).

Uncertainty policy (ask only when it matters)

Agents should not get bogged down asking permission. Ask questions only when:

  • requirements are ambiguous in a way that risks rework or wrong behavior
  • a change could break compatibility, security posture, or data integrity
  • the task would expand scope materially (new features, new deps, major refactor)
  • there are multiple plausible interpretations with different outcomes

If uncertain but not blocked:

  • make the safest reasonable assumption
  • document it in memory-bank/current_task.md under "Assumptions"
  • proceed and keep the diff small

For how to ask well: memory-bank/skills/asking.md. Security checklist before landing: memory-bank/skills/security.md. Dangerous ops (backup/rollback note required): memory-bank/skills/dangerous_ops.md. Quick repo orientation: memory-bank/skills/repo_orientation.md.

Continuous improvement (without scope creep)

While working, keep an eye out for:

  • security hazards (input validation, auth, secrets handling, injection paths)
  • performance wins (allocations, IO, hot paths, caching)
  • maintainability (clarity, duplication, brittle coupling)
  • operability (logs, metrics, error messages, debuggability)

Policy:

  • If it is a small, low-risk improvement that is clearly within scope, you may do it.
  • If it expands scope or carries meaningful risk, log it to memory-bank/opportunities.md and raise it to the user in your summary.

Scope guard (no drive-by refactors): If it isn't in In/Out, don't touch it — file it as an opportunity. Keeps improvement-hunting from becoming a refactor spree.

Definition of done: Done = green verification + task_history entry + docs updated if behavior changed + opportunities filed if discovered.

Recurring loops and hard problems (emphasis)

Some issues show up again and again: agents or humans fix something, then the same class of problem reappears elsewhere or after a refactor. Those belong in memory-bank/recurring_loops.md.

Examples of what to record there:

  • Agentic loops: e.g. "Agent repeatedly changes X to fix Y, which breaks Z; the real fix is W."
  • Bugfix loops: e.g. "Bug in component A keeps reappearing because B assumes C; document that B must never assume C."
  • Hard-to-solve / easy-to-regress: e.g. "Component A assumes B is immutable; changing B at runtime causes subtle bugs—document the invariant and add tests."

When you add an entry, include:

  1. What keeps happening (the recurring symptom or mistake).
  2. Why it's tricky (root cause or constraint).
  3. What works (concrete fix or rule to follow).
  4. Where it's documented (doc link or code path) if applicable.

The goal is to give future agents early warnings and concrete guidance so they don't re-enter the same loops.

Project overview (for context)

This repo is an agentic repo template for any language or stack: memory-bank workflow, single verify script, Diátaxis docs. Add your own code and define verification in scripts/verify-steps.sh and memory-bank/commands.yml.

After cloning from template: Run scripts/init-template; replace placeholders in README, CODEOWNERS, and docs. See TEMPLATE.md. The memory bank holds current state, known issues, and recurring loops. When behavior/config changes, update or add one doc and file gaps in opportunities.md; see memory-bank/code_quality.md.

Local Identity Privacy

Never include private local hostnames, local OS usernames, home-directory paths, or operator-specific machine names in commit messages, changelogs, release notes, public docs, or GitHub release text. Use generic wording such as "live validation host", "test host", "operator account", or "local checkout". CI can pass extra private denylist terms through the LOCAL_IDENTITY_DENYLIST secret; local-only terms can live in an untracked file such as .local/identity-denylist.txt and be passed with LOCAL_IDENTITY_DENYLIST_FILE.