linearvoid/.github/instructions/AGENTS.md

AGENTS.md

Agents instructions for the linearvoid project.

General Guidelines

• Use the architecture documentation (arc42 template and ADRs) as the source of truth for design decisions.
• Follow the project folder structure defined in ADR-002 and reflected in the root README.
• Update documentation first before implementing changes to ensure traceability of decisions.
• Plan any task in the TODO.md file with clear steps and mark them as completed when done. Move completed sections to 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.

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.