agent-guides AGENTS.md

AGENTS — root guidance

Dynamic guidance loading

The loaded guidance set is project-specific and may change per task. Do not assume the statically listed files are complete; first discover optional guidance under the target project's .agent/ directory.

Discover and load guidance in this order:

1. .agent/*.md — project baseline files, when present
2. .agent/rules/*.md — all project rules
3. .agent/skills/*/SKILL.md — only the skill matching the current task
4. .agent/workflows/*.md — only the workflow matching the triggered command
5. .agent/prompts/*.md — only when explicitly requested or referenced by loaded guidance

Prefer relative paths in references inside markdown files.

---

General Development Practices

Cross-cutting practices that apply to every project regardless of area.

Git Workflow

• Use feature branches with task IDs in branch names (e.g., feat/TASK-123-add-auth).
• Commit messages include context: what changed, why, and any relevant ticket reference.
• No direct commits to main or protected branches — all changes via reviewed PRs.

Makefile Conventions

• Use Makefile for common development tasks accessible to all contributors.
• Include a help target listing available commands with descriptions.
• Standard targets: install, dev, test, lint, fmt, clean, build.

Docker Compose

• Use docker-compose for local multi-service development.
• Configure health checks for all dependent services before marking ready.
• Drive configuration via environment variables; no hardcoded values.

Linting and Formatting

• Configure language-appropriate linters for every project.
• Enforce standards via pre-commit hooks — CI is a safety net, not the primary check.
• Apply consistent formatting across all files on every commit.

SDLC Methodology

• Follow phases in order: Requirements → Design → Implementation → Verification → Deployment → Maintenance.
• Document requirements before implementation — "we'll figure it out" is not a requirement.
• Conduct design reviews for any change with architectural, security, or data model impact.
• Before changing project logic, read the relevant design and behavior documents under docs/**.
• Run validation, tests, coverage, and CI-style checks through Makefile targets only.