45 lines
4.2 KiB
Markdown
45 lines
4.2 KiB
Markdown
# 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.
|