linearvoid/.github/AGENTS.md

AGENTS.md

Agents instructions for the linearvoid project.

General Guidelines

• Use the architecture documentation (arc42 template and ADRs in docs) as the source of truth for design decisions.
• Follow the project folder structure in the root README.
• Update documentation first before implementing changes to ensure traceability of decisions.

Task Management

• Plan any task in the .github/instructions/TODO.md file with clear steps and mark them as completed when done. Move completed sections to .github/instructions/DONE.md. Write entry in root CHANGELOG.md for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the TODO.md file.
• Before taking any action except for planning and writing TODO.md, always ask user for confirmation, accept go, ok, yes, next, or continue to proceed. If the user says no, stop, or cancel, abort the action and return to planning.

Required tracking files — update at every development step

These files must be kept current with every change. Do not let them drift.

File	Purpose	When to update
.github/instructions/TODO.md	Active implementation plan with checkboxes	Mark items done as they complete; add new items when scope expands
.github/instructions/BACKLOG.md	Deferred, manual, and operational tasks	Sync whenever TODO items complete or new gaps are identified
.github/instructions/DONE.md	Archive of completed TODO sections	Move completed sections here from TODO.md
.github/MEMORY.md	Session memory — what was done, when, and why	Append dated entry after each meaningful batch of changes
docs/DEVELOPMENT.md	Remaining task checklist organized by topic	Sync checkboxes with TODO.md after each implementation session
CHANGELOG.md	User-facing release notes	Add entry when a phase or significant feature completes
docs/STREAMING.md	Streaming pipeline contract	Update when playout, HLS, or caching behavior changes
docs/DEPLOYMENT.md	Deploy and infrastructure procedures	Update when pipeline, topology, or provisioning changes
docs/SETUP.md	Environment and onboarding guide	Update when prerequisites, .env, or setup steps change
docs/MONITORING.md	Observability reference	Update when metrics, alerts, or dashboards change
docs/API.md	API contract	Update when endpoints, status codes, or rate limits change
docs/SECURITY.md	Security posture	Update when auth, TLS, or rate limiting changes
docs/operations/*.md	Runbooks, checklists, how-to guides	Keep aligned with actual procedures and dashboard URLs

Security & Secrets Protection

• Never commit raw secrets or credentials to the repository.
• Never print or log raw secrets in terminal commands or output files.
• Use Gitea Actions Secrets for all production credentials and environment variables.
• Avoid hardcoding sensitive values in workflow files (.yml). Instead, reference them using ${{ secrets.SECRET_NAME }}.
• Do not use the GITEA_ prefix for custom secrets or environment variables in Gitea, as it is reserved internally and will be silently ignored or returned as empty. Use the CI_ prefix instead (e.g., CI_REGISTRY_USER, CI_REGISTRY_TOKEN).
• Keep .env gitignored and use .env.example as the template for local development.
• For CD deployments, generate the .env file dynamically on the runner using a secure step that populates values from Gitea Actions Secrets.