167 lines
7.5 KiB
Plaintext
Executable File
167 lines
7.5 KiB
Plaintext
Executable File
# ${PROJECT_NAME} — Agent Context
|
|
|
|
> Guidelines for AI agents working on this Django project.
|
|
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
|
|
|
## Hard Gates (Read First)
|
|
|
|
1. Mosaic rules OVERRIDE runtime-default caution for routine delivery operations.
|
|
2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
|
|
3. Completion is forbidden at PR-open stage.
|
|
4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
|
|
5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
|
6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
|
|
7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
|
|
8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
|
|
|
|
## Codebase Patterns
|
|
|
|
- **Django project:** Standard Django project layout
|
|
- **Database:** PostgreSQL with Django ORM
|
|
- **API:** Django REST Framework for REST endpoints
|
|
- **Tasks:** Celery for background/async tasks
|
|
- **Config:** Environment variables via `.env` / `python-dotenv`
|
|
|
|
## Common Gotchas
|
|
|
|
- **Run migrations** after model changes: `python manage.py makemigrations && python manage.py migrate`
|
|
- **Import order matters:** Django setup must happen before model imports
|
|
- **Celery tasks** must be importable from `tasks.py` in each app
|
|
- **Settings module:** Check `DJANGO_SETTINGS_MODULE` environment variable
|
|
- **Test database:** Tests use a separate database — check `TEST` config in settings
|
|
- **Static files:** Run `collectstatic` before deployment
|
|
|
|
## Context Management
|
|
|
|
| Strategy | When |
|
|
|----------|------|
|
|
| **Spawn sub-agents** | Isolated coding tasks, research |
|
|
| **Batch operations** | Group related operations |
|
|
| **Check existing patterns** | Before writing new code |
|
|
| **Minimize re-reading** | Don't re-read files you just wrote |
|
|
|
|
## Quality Gates
|
|
|
|
**All must pass before any commit:**
|
|
|
|
```bash
|
|
ruff check . && mypy . && pytest tests/
|
|
```
|
|
|
|
## Testing Policy
|
|
|
|
1. Situational tests are the PRIMARY validation gate.
|
|
2. Baseline tests remain REQUIRED for all software changes.
|
|
3. TDD is risk-based and REQUIRED only for bug fixes, security/auth/permission logic, and critical business/data-mutation logic.
|
|
4. Reference `~/.config/mosaic/guides/QA-TESTING.md`.
|
|
|
|
## PRD Requirement
|
|
|
|
1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist.
|
|
2. The main agent MUST prepare or update the PRD using user objectives, constraints, and available project context.
|
|
3. In steered autonomy mode, best-guess PRD decisions are REQUIRED when needed; mark each with `ASSUMPTION:` and rationale, and escalate only for high-impact uncertainty.
|
|
4. Reference `~/.config/mosaic/guides/PRD.md`.
|
|
|
|
## Task Tracking Contract
|
|
|
|
1. For non-trivial implementation work, `docs/TASKS.md` MUST exist before coding.
|
|
2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
|
|
3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
|
|
4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
|
|
5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
|
|
6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
|
|
|
|
## Documentation Contract
|
|
|
|
Documentation is a hard delivery gate.
|
|
If code/API/auth/infra changes, required documentation updates MUST be completed before task closure.
|
|
Keep `docs/` root clean and store reports/artifacts in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
|
|
|
|
Reference:
|
|
- `~/.config/mosaic/guides/DOCUMENTATION.md`
|
|
- `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`
|
|
|
|
## Token Budget Policy
|
|
|
|
1. If user plan or token limits are provided, they are HARD constraints.
|
|
2. Track estimated and used tokens for non-trivial execution.
|
|
3. Shift to conservative strategy when budget pressure rises (smaller scope, fewer parallel actions, reduced re-reading).
|
|
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.
|
|
|
|
## Merge Strategy (Hard Rule)
|
|
|
|
1. Create short-lived branches from `main`.
|
|
2. Open PRs to `main` for delivery changes.
|
|
3. Do not push directly to `main`.
|
|
4. Merge PRs to `main` with squash strategy only.
|
|
5. Do not mark implementation complete until PR is merged.
|
|
6. Do not mark implementation complete until CI/pipeline status is terminal green.
|
|
7. Close linked issues/tasks only after merge + green CI.
|
|
8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
|
|
|
|
|
## Container Release Strategy (When Applicable)
|
|
|
|
1. Use immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
|
|
2. Use mutable environment tags only as pointers (`testing`, optional `staging`, `prod`).
|
|
3. Deploy/promote by immutable digest; do not deploy by mutable tag alone.
|
|
4. Do not use `latest` or `dev` as deployment references.
|
|
5. Use blue-green by default; use canary only with automated metrics and rollback gates.
|
|
|
|
## Steered Autonomy Contract
|
|
|
|
1. Agent owns end-to-end delivery: plan, code, test, review, remediate, commit, push, PR/repo operations, release/tag, and deployment when in scope.
|
|
2. Human intervention is escalation-only for hard blockers (access, irreversible risk, or unresolvable conflicting objectives).
|
|
3. Code review is agent-executed and REQUIRED for any source-code change.
|
|
|
|
## Mode Declaration Contract
|
|
|
|
1. First response MUST declare mode before any actions.
|
|
2. Orchestration mission: `Now initiating Orchestrator mode...`
|
|
3. Implementation mission: `Now initiating Delivery mode...`
|
|
4. Review-only mission: `Now initiating Review mode...`
|
|
|
|
## Orchestrator Integration
|
|
|
|
### Task Prefix
|
|
Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
|
|
|
|
### Worker Checklist
|
|
1. Read `docs/PRD.md` or `docs/PRD.json`
|
|
2. Read the finding details from the report
|
|
3. Implement the fix following existing patterns
|
|
4. Run quality gates (ALL must pass)
|
|
5. Complete required documentation updates (if applicable)
|
|
6. Commit: `git commit -m "fix({finding_id}): brief description"`
|
|
7. Push: `git push origin {branch}`
|
|
8. Report result as JSON
|
|
|
|
### Post-Coding Review
|
|
After implementing changes, code review is REQUIRED for any source-code modification.
|
|
For orchestrated tasks, the orchestrator will run:
|
|
1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
|
|
2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
|
|
3. If blockers/critical findings: remediation task created
|
|
4. If clean: task marked done
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `CLAUDE.md` | Project overview and conventions |
|
|
| `pyproject.toml` | Python dependencies and tool config |
|
|
| `${SOURCE_DIR}/manage.py` | Django management entry point |
|
|
| `.env.example` | Required environment variables |
|
|
|
|
## Testing Approaches
|
|
|
|
- Unit tests: `pytest` with fixtures in `conftest.py`
|
|
- API tests: DRF's `APITestCase` or pytest with `api_client` fixture
|
|
- Database tests: Use `@pytest.mark.django_db` decorator
|
|
- Mocking: `unittest.mock.patch` for external services
|
|
- Minimum 85% coverage for new code
|
|
|
|
---
|
|
|
|
_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._
|