Skip to content

feat: add AGENTS.md to project#1530

Open
ttuffin wants to merge 1 commit intomainfrom
feat/add_agentsmd
Open

feat: add AGENTS.md to project#1530
ttuffin wants to merge 1 commit intomainfrom
feat/add_agentsmd

Conversation

@ttuffin
Copy link
Copy Markdown
Contributor

@ttuffin ttuffin commented Apr 16, 2026

Adding AGENTS.md for project level instructions for AI agents.

Summary by CodeRabbit

  • Documentation

    • Added a comprehensive onboarding guide with required reading, project purpose, architecture overview, setup and local build/test workflows, lint/format commands, CI/security guidance, configuration conventions, and debugging tips.
  • Chores

    • Standardized contributor guidance, repository navigation, test execution patterns (including local and containerized pytest workflows), service startup steps, and workflow conventions to streamline onboarding and reduce setup friction.

@ttuffin ttuffin requested a review from a team as a code owner April 16, 2026 11:57
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 16, 2026

📝 Walkthrough

Walkthrough

Adds a new top-level AGENTS.md onboarding and contributor guide that documents required reading, project purpose and stack, local build/test workflows (task/docker/pytest), lint/CI guidance, configuration conventions, architecture patterns, and development/PR workflows.

Changes

Cohort / File(s) Summary
Documentation
AGENTS.md
New repository-wide onboarding and contributor guide: required reading order, EDA Server overview and core stack, companion repos, step-by-step local setup and test workflows (task commands, Docker minimal services, migrations/seed data, superuser, task run:api), pytest usage and @pytest.mark.multithreaded behavior, lint/format commands, CI/GitHub Actions security guidance, dynaconf EDA_ config conventions, API/docs routes, high-level architecture/service flow, git/PR patterns, common gotchas, and debugging pointers.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Description check ❓ Inconclusive The description is minimal but explicitly states the purpose. However, it lacks details on why the change is needed, testing approach, and how it addresses the overall project goals. Expand the description to explain why AI agent instructions are needed, what problems this solves, and any relevant context or issue references.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title 'feat: add AGENTS.md to project' clearly summarizes the main change—adding a new AGENTS.md documentation file to the repository.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/add_agentsmd

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Around line 51-52: The docs currently publish fixed credentials
("admin/testpass") in the create:superuser task which is a security risk; update
the AGENTS.md entry for task create:superuser to remove the literal
admin/testpass, instruct contributors to set their own password (or show an
env-var example like ADMIN_PASSWORD=...) and clearly mark the example as
local-only/development use; reference the task name create:superuser and the
removed literal admin/testpass so the maintainer replaces that specific example
with a placeholder or env-based guidance.
- Around line 210-217: Update AGENTS.md to remove or correct the erroneous
requirements referring to `.github/pull_request_template.md`, JIRA-prefixed PR
titles, and mandatory AI co-author attribution, or add the missing governance
artifacts so the file is accurate; specifically, either (A) change the lines
that mention `.github/pull_request_template.md`, the "PR titles SHOULD be
prefixed with JIRA number" rule, and the "PR descriptions MUST include agent
co-author attribution" text to match the canonical docs in
`docs/contributing.md` (tests, Python 3.11 compatibility, passing CI), or (B)
create and add the referenced `.github/pull_request_template.md` and any
documented policy files so AGENTS.md correctly points to existing templates and
policies. Ensure the updated AGENTS.md clearly references the canonical
contributing rules and remove conflicting mandatory language if the
templates/policies are not added.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c7678aa7-6030-43d1-b105-3fdc9f697c72

📥 Commits

Reviewing files that changed from the base of the PR and between 51a73bf and fd15d43.

📒 Files selected for processing (1)
  • AGENTS.md

Comment thread AGENTS.md
Comment thread AGENTS.md Outdated
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Apr 16, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.93%. Comparing base (344ba2b) to head (13d6e85).

@@           Coverage Diff           @@
##             main    #1530   +/-   ##
=======================================
  Coverage   91.93%   91.93%           
=======================================
  Files         239      239           
  Lines       10810    10810           
=======================================
  Hits         9938     9938           
  Misses        872      872           
Flag Coverage Δ
unit-int-tests-3.11 91.93% <ø> (ø)
unit-int-tests-3.12 91.93% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ttuffin ttuffin force-pushed the feat/add_agentsmd branch from fd15d43 to 2aff5ed Compare April 16, 2026 12:36
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♻️ Duplicate comments (2)
AGENTS.md (2)

51-52: ⚠️ Potential issue | 🟠 Major

Remove fixed default credentials from setup instructions.

The admin/testpass example normalizes weak credentials and can leak into shared environments. Replace it with “set your own password” (or env-var driven) guidance and mark it local/dev-only.

As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 51 - 52, The setup doc currently shows fixed default
credentials ("admin/testpass") for the task create:superuser example which is
insecure; update the AGENTS.md instructions for the task create:superuser entry
to remove any hard-coded username/password, instruct users to choose their own
strong password (or use an environment-variable-driven secret), and add a clear
note that this step is for local/dev-only and must not be used in production.
Ensure the example demonstrates a placeholder (e.g., <your-password> or
references an env var) rather than real credentials and call out that
credentials should be rotated and secured in real deployments.

207-215: ⚠️ Potential issue | 🟠 Major

Avoid hard-coding repository governance rules in AGENTS.md without canonical linkage.

“Always give agent co-author credit” plus mandatory PR title/description policy (including specific assistant wording) is likely to drift or conflict with canonical contribution policy. Prefer linking to docs/contributing.md as source of truth and making this section advisory unless those requirements are formally codified there.

As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 207 - 215, The AGENTS.md text currently hard-codes
mandatory PR title/description and co-author credit rules; change this to an
advisory note that defers to the canonical contribution policy by linking to
docs/contributing.md and remove the required phrasing. Specifically, replace the
"Always give agent co-author credit in commits" header and the "PR titles
SHOULD..." / "PR descriptions MUST include..." blocks with a short advisory
paragraph that (1) directs readers to docs/contributing.md for official
repository policy and (2) recommends including agent attribution without
mandating exact wording or JIRA prefix; ensure the new copy references the
existing "Pull Request Guidelines" section title so reviewers can locate it.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@AGENTS.md`:
- Around line 51-52: The setup doc currently shows fixed default credentials
("admin/testpass") for the task create:superuser example which is insecure;
update the AGENTS.md instructions for the task create:superuser entry to remove
any hard-coded username/password, instruct users to choose their own strong
password (or use an environment-variable-driven secret), and add a clear note
that this step is for local/dev-only and must not be used in production. Ensure
the example demonstrates a placeholder (e.g., <your-password> or references an
env var) rather than real credentials and call out that credentials should be
rotated and secured in real deployments.
- Around line 207-215: The AGENTS.md text currently hard-codes mandatory PR
title/description and co-author credit rules; change this to an advisory note
that defers to the canonical contribution policy by linking to
docs/contributing.md and remove the required phrasing. Specifically, replace the
"Always give agent co-author credit in commits" header and the "PR titles
SHOULD..." / "PR descriptions MUST include..." blocks with a short advisory
paragraph that (1) directs readers to docs/contributing.md for official
repository policy and (2) recommends including agent attribution without
mandating exact wording or JIRA prefix; ensure the new copy references the
existing "Pull Request Guidelines" section title so reviewers can locate it.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f25e43d3-d246-4432-915f-d5dcc3b5b249

📥 Commits

Reviewing files that changed from the base of the PR and between fd15d43 and 2aff5ed.

📒 Files selected for processing (1)
  • AGENTS.md

Comment thread AGENTS.md Outdated
Comment thread AGENTS.md Outdated
Comment thread AGENTS.md
@ttuffin ttuffin force-pushed the feat/add_agentsmd branch 2 times, most recently from c356201 to 1ed745b Compare April 17, 2026 13:58
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

♻️ Duplicate comments (2)
AGENTS.md (2)

51-52: ⚠️ Potential issue | 🟠 Major

Remove fixed default credentials from setup instructions.

Publishing admin/testpass is a security footgun in contributor docs. Replace it with “set your own password” guidance (or env-var placeholder) and mark it as local-development only.

Suggested doc update
-# Create admin superuser (admin/testpass)
-task create:superuser
+# Create admin superuser (local development only; choose your own credentials)
+task manage -- createsuperuser

As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 51 - 52, Remove the hard-coded example credentials
from the "task create:superuser" documentation entry and replace them with
guidance to set a custom password (or use an env-var placeholder) and a clear
note that the step is for local-development only; update the line containing
"Create admin superuser (admin/testpass)" and the "task create:superuser"
section to instruct contributors to choose their own secure password or
reference an environment variable (e.g., ADMIN_PASSWORD) and annotate that this
example must not be used in production.

210-215: ⚠️ Potential issue | 🟠 Major

PR policy requirements here should align with canonical contributor policy.

The mandatory JIRA-title format and required AI-attribution block can conflict with canonical contribution guidance and cause process ambiguity. Either relax this to project-canonical rules or explicitly reference where these requirements are officially enforced.

As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` around lines 210 - 215, The two mandatory rules in AGENTS.md
("**PR titles SHOULD be prefixed with JIRA number**" and "**PR descriptions MUST
include agent co-author attribution**") conflict with the project's canonical
contributor policy; update AGENTS.md to either relax these statements from
MUST/SHOULD to recommendations or explicitly reference and link to the canonical
contributor policy and where enforcement occurs (e.g., mention the governing
CONTRIBUTING.md or CODEOWNERS process); specifically edit the lines containing
the quoted policy text to replace absolute language with "Recommended" or add a
clear sentence pointing to the authoritative policy and enforcement mechanism so
readers know which rule is binding.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@AGENTS.md`:
- Line 52: The docs reference a non-existent Taskfile task "create:superuser";
replace that line to use the existing management-command entrypoint instead so
readers run the Django createsuperuser via the management-command task (e.g.,
invoke the management-command task with the "createsuperuser" argument). Update
the AGENTS.md occurrence of "task create:superuser" to call the
management-command task name used in Taskfile.dist.yaml and include the
createsuperuser argument so the command maps to the defined management-command
entrypoint.

---

Duplicate comments:
In `@AGENTS.md`:
- Around line 51-52: Remove the hard-coded example credentials from the "task
create:superuser" documentation entry and replace them with guidance to set a
custom password (or use an env-var placeholder) and a clear note that the step
is for local-development only; update the line containing "Create admin
superuser (admin/testpass)" and the "task create:superuser" section to instruct
contributors to choose their own secure password or reference an environment
variable (e.g., ADMIN_PASSWORD) and annotate that this example must not be used
in production.
- Around line 210-215: The two mandatory rules in AGENTS.md ("**PR titles SHOULD
be prefixed with JIRA number**" and "**PR descriptions MUST include agent
co-author attribution**") conflict with the project's canonical contributor
policy; update AGENTS.md to either relax these statements from MUST/SHOULD to
recommendations or explicitly reference and link to the canonical contributor
policy and where enforcement occurs (e.g., mention the governing CONTRIBUTING.md
or CODEOWNERS process); specifically edit the lines containing the quoted policy
text to replace absolute language with "Recommended" or add a clear sentence
pointing to the authoritative policy and enforcement mechanism so readers know
which rule is binding.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e703dbb2-3adf-4b69-975e-8de954aa0760

📥 Commits

Reviewing files that changed from the base of the PR and between 2aff5ed and c356201.

📒 Files selected for processing (1)
  • AGENTS.md

Comment thread AGENTS.md
Adding AGENTS.md for project level instructions for
AI agents.
@ttuffin ttuffin force-pushed the feat/add_agentsmd branch from 1ed745b to 13d6e85 Compare April 17, 2026 13:59
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♻️ Duplicate comments (1)
AGENTS.md (1)

52-52: ⚠️ Potential issue | 🟠 Major

task create:superuser is not a defined task.

This command will fail during setup. Use the Django management command through the manage task instead.

🔧 Corrected command
-task create:superuser
+task manage -- createsuperuser
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@AGENTS.md` at line 52, The task name "create:superuser" is invalid and will
fail; replace any invocation of the nonexistent task with the existing "manage"
task and call Django's management command (e.g., use the manage task to run
"createsuperuser" or an equivalent manage command), updating references from
"task create:superuser" to the manage task invocation that runs "python
manage.py createsuperuser" (or the project's manage wrapper) so setup uses the
correct management command.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@AGENTS.md`:
- Line 52: The task name "create:superuser" is invalid and will fail; replace
any invocation of the nonexistent task with the existing "manage" task and call
Django's management command (e.g., use the manage task to run "createsuperuser"
or an equivalent manage command), updating references from "task
create:superuser" to the manage task invocation that runs "python manage.py
createsuperuser" (or the project's manage wrapper) so setup uses the correct
management command.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cb26cd29-6c23-4228-8201-5dd381c28d7f

📥 Commits

Reviewing files that changed from the base of the PR and between c356201 and 13d6e85.

📒 Files selected for processing (1)
  • AGENTS.md

@sonarqubecloud
Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants