agentleFS
Sign inStart free
oqtopus-teamoqtopus-team/qdash/AGENTS.md

qdash

AGENTS.md54 starsChanged 23 days agoApache-2.0View on GitHub

This file is the shared guide for coding agents working in this repository. It covers project-wide conventions only; keep it concise and update it when those conventions change. Package directories may add their own AGENTS.md with package-specific rules. QDash is a web platform for managing and monitoring qubit calibration workflows. Read docs/developer-guide/architecture.md and the more specific docs under docs/developer-guide/ before making broad changes. Do not manually edit generated files: When backend API schemas or routes change, run task generate from…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository4 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

36 rules. About 0 are common, 15 are distinctive, and 21 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 21

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Read docs/developer-guide/architecture.md and the more specific docs under docs/developer-guide/ before making broad changes.

    line 21
  2. Distinctive:

    Do not manually edit generated files:

    line 41
  3. Very specific:

    When backend API schemas or routes change, run task generate from the repository root to regenerate the OpenAPI document and TypeScript …

    line 48
  4. Distinctive:

    Run commands from the repository root unless a directory is specified.

    line 52
  5. Very specific:

    Start lightweight host-side stack: task dev-local

    line 63
  6. Very specific:

    Start full Docker Compose stack: task deploy-local

    line 64
  7. Very specific:

    Start API only: uvicorn src.qdash.api.main:app --reload

    line 65
  8. Very specific:

    Start UI dev server: task dev-ui or bun run dev in ui/

    line 66
  9. Very specific:

    Use focused tests during development.

    line 85
  10. Very specific:

    Use uv run ... for Python tooling when invoking commands directly.

    line 91
  11. Very specific:

    Avoid changing tools, scripts, or generated requirement exports unless the task is specifically about those areas.

    line 95
  12. Very specific:

    Use Bun in ui/.

    line 99
  13. Very specific:

    Use named exports for ordinary components, hooks, utilities, and contexts.

    line 101
  14. Very specific:

    Use imports from established aliases and locations, especially @/contexts/*, @/hooks/useUrlState or @/hooks/url-state, and @/lib/utils/*.

    line 102
  15. Very specific:

    Keep reusable primitives in ui/src/components/ui/, feature UI in ui/src/components/features/, charts in ui/src/components/charts/, and …

    line 103
  16. Very specific:

    Keep DaisyUI as the visual and theme foundation.

    line 104
  17. Distinctive:

    Do not treat Radix as a wholesale DaisyUI replacement.

    line 105
  18. Very specific:

    Use TanStack Query for server state and nuqs for URL query state when matching existing patterns.

    line 106
  19. Distinctive:

    Use Lucide React icons where an icon is appropriate.

    line 107
  20. Very specific:

    Follow docs/developer-guide/ui/guidelines.md and docs/developer-guide/ui/design-policy.md for implementation and visual design details.

    line 108
  21. Very specific:

    Follow docs/developer-guide/docs-guidelines.md and use the technical-docs skill (.agents/skills/technical-docs/SKILL.md) to write, verify …

    line 112
  22. Very specific:

    Use the document-changes skill (.agents/skills/document-changes/SKILL.md) to audit a branch, pull request, commit, or working-tree diff for …

    line 113
  23. Distinctive:

    Start docs with a direct context sentence.

    line 114
  24. Distinctive:

    Do not add manual tables of contents, summary sections, empty checklists, future-enhancement sections, or emoji.

    line 115
  25. Very specific:

    Do not restructure docs/task-knowledge/.

    line 117
  26. Very specific:

    Use Conventional Commits style: <type>(<scope>): <summary>.

    line 121
  27. Distinctive:

    Keep commit titles short, specific, English, no emoji, and no trailing period.

    line 124
  28. Very specific:

    Before every push, including updates to an existing PR, run task check from the repository root (nix develop -c task check on the host) and …

    line 127
  29. Distinctive:

    If the check fails or cannot run, resolve the failure before pushing.

    line 134
  30. Distinctive:

    Check git status --short before editing and do not revert unrelated user changes.

    line 140
  31. Distinctive:

    Prefer existing project patterns and local helper APIs over new abstractions.

    line 141
  32. Distinctive:

    Keep edits scoped to the requested area.

    line 142
  33. Distinctive:

    If changing API contracts, update tests and regenerate the client.

    line 143
  34. Distinctive:

    If changing UI behavior, add or adjust Vitest tests where practical and run the relevant UI checks.

    line 144
  35. Distinctive:

    If changing workflow or repository behavior, run the matching Python tests.

    line 145
  36. Distinctive:

    Keep personal model, provider, editor, and delegation preferences in user-level agent configuration, not in repository guidance.

    line 147

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

QDash Agent Guide

This file is the shared guide for coding agents working in this repository. It covers project-wide conventions only; keep it concise and update it when those conventions change. Package directories may add their own AGENTS.md with package-specific rules.

Project Overview

QDash is a web platform for managing and monitoring qubit calibration workflows.

Architecture

  • Frontend: ui/ uses Next.js, React, TypeScript, DaisyUI, TanStack Query, and Bun.
  • Backend API: src/qdash/api/ uses FastAPI with MongoDB/PostgreSQL-related services.
  • Pi extensions: packages/pi-qdash/ and packages/pi-qcaleval/ share a root Bun workspace with agent-runtime/ and clients/typescript/; install dependencies from the repository root. They remain independently published npm packages.
  • Workflow engine: src/qdash/workflow/ uses Prefect 3 and qubex.
  • Shared data/model code lives under src/qdash/common, src/qdash/datamodel, src/qdash/dbmodel, and repository/service modules.

Read docs/developer-guide/architecture.md and the more specific docs under docs/developer-guide/ before making broad changes.

High-Value References

  • Setup: docs/developer-guide/setup.md
  • Development flow and commits: docs/developer-guide/development-flow.md
  • API design: docs/developer-guide/api/design.md
  • API testing: docs/developer-guide/api/testing.md
  • UI guidelines: docs/developer-guide/ui/guidelines.md
  • UI architecture: docs/developer-guide/ui/architecture.md
  • UI testing: docs/developer-guide/ui/testing.md
  • UI design policy: docs/developer-guide/ui/design-policy.md
  • Workflow quickstart: docs/developer-guide/workflow/quickstart.md
  • Workflow architecture: docs/developer-guide/workflow/engine-architecture.md
  • Workflow testing: docs/developer-guide/workflow/testing.md
  • Documentation guidelines: docs/developer-guide/docs-guidelines.md
  • Database collections: docs/reference/database-structure.md

Generated Code

Do not manually edit generated files:

  • ui/src/client/
  • ui/src/schemas/
  • clients/typescript/src/generated/
  • docs/oas/openapi.json

When backend API schemas or routes change, run task generate from the repository root to regenerate the OpenAPI document and TypeScript clients.

Common Commands

Run commands from the repository root unless a directory is specified.

On the host, run task check as nix develop -c task check and create commits inside the Nix shell (for example nix develop -c git commit) so the leak scans and pre-commit hook use the Betterleaks release pinned by BETTERLEAKS_VERSION in .devcontainer/Dockerfile. Inside the DevContainer, run the commands directly. Any brief that delegates checks or commits must carry this requirement. If task check-betterleaks-version fails, fix the environment; do not bypass the hook or edit leak allowlists to silence findings from another release.

  • Show available tasks: task -l
  • Install host-side local dependencies: task dev-local-setup
  • Start lightweight host-side stack: task dev-local
  • Start full Docker Compose stack: task deploy-local
  • Start API only: uvicorn src.qdash.api.main:app --reload
  • Start UI dev server: task dev-ui or bun run dev in ui/
  • Generate API client: task generate
  • Python tests: task test
  • Fast Python test loop: task test-fast
  • API tests: task test-api
  • Workflow tests: task test-workflow
  • UI tests: task test-ui
  • Build the local TypeScript client: task build-client-ts (also runs before pi/runtime checks)
  • TypeScript client checks: task test-client-ts
  • Pi package tests and typecheck: task ci-pi-packages
  • Agent runtime tests and typecheck: task ci-agent-runtime
  • Python CI checks: task ci
  • Required before every push: task check (task check-all is an alias)
  • Python lint/format with fixes: task lint-python
  • UI lint/format with fixes: task lint-ui
  • UI production build: task build or task ci-ui-build
  • Docs dev server: task docs
  • Docs build: task build-docs

Use focused tests during development. Before every push, run the full task check regardless of change size, including documentation-only changes.

Python Conventions

  • Python supports >=3.11,<3.13.
  • Use uv run ... for Python tooling when invoking commands directly.
  • Ruff line length is 100. The project uses Ruff for linting and formatting.
  • Mypy is strict for application code. Keep types explicit when adding public helpers or cross-module interfaces.
  • Tests use pytest. Many tests are designed to run in memory without MongoDB.
  • Avoid changing tools, scripts, or generated requirement exports unless the task is specifically about those areas.

UI Conventions

  • Use Bun in ui/.
  • ui/src/app/ should contain routing-only App Router files. Keep page.tsx files thin and delegate substantial UI to *PageContent components.
  • Use named exports for ordinary components, hooks, utilities, and contexts. page.tsx and layout.tsx use default exports.
  • Use imports from established aliases and locations, especially @/contexts/*, @/hooks/useUrlState or @/hooks/url-state, and @/lib/utils/*.
  • Keep reusable primitives in ui/src/components/ui/, feature UI in ui/src/components/features/, charts in ui/src/components/charts/, and layout in ui/src/components/layout/.
  • Keep DaisyUI as the visual and theme foundation. Use the established Radix-based primitives in ui/src/components/ui/ for interactions that need robust focus management, keyboard navigation, portals, dismissal, or collision-aware positioning.
  • Do not treat Radix as a wholesale DaisyUI replacement. Prefer DaisyUI for buttons, cards, inputs, badges, tables, and semantic colors; add a headless primitive only when the interaction behavior requires it.
  • Use TanStack Query for server state and nuqs for URL query state when matching existing patterns.
  • Use Lucide React icons where an icon is appropriate.
  • Follow docs/developer-guide/ui/guidelines.md and docs/developer-guide/ui/design-policy.md for implementation and visual design details.

Documentation Conventions

  • Follow docs/developer-guide/docs-guidelines.md and use the technical-docs skill (.agents/skills/technical-docs/SKILL.md) to write, verify and review a page.
  • Use the document-changes skill (.agents/skills/document-changes/SKILL.md) to audit a branch, pull request, commit, or working-tree diff for documentation impact before making documentation fixes.
  • Start docs with a direct context sentence.
  • Do not add manual tables of contents, summary sections, empty checklists, future-enhancement sections, or emoji.
  • Link relevant docs inline instead of adding broad related-document lists.
  • Do not restructure docs/task-knowledge/; those files have a fixed template consumed by the copilot system.

Git And PR Conventions

  • Use Conventional Commits style: <type>(<scope>): <summary>.
  • Types: feat, fix, docs, style, refactor, test, ci, chore.
  • Scopes: use api, workflow, ui, docs, infra, or repo when clear.
  • Keep commit titles short, specific, English, no emoji, and no trailing period.
  • For PR text, follow .github/pull_request_template.md and .github/instructions/pull-request-description-instructions.md.
  • Branches usually start from develop; common prefixes are feature/, bugfix/, and hotfix/.
  • Before every push, including updates to an existing PR, run task check from the repository root (nix develop -c task check on the host) and require exit status 0. Focused tests, pre-commit hooks, and CI do not replace this gate. Follow the pre-push procedure.
  • Stage intended new files before checking so the leak scan includes them. Fetch the PR target and use LEAKS_BASE=origin/<target> when it is not develop.
  • Review any auto-fix changes from task check and include intended fixes in the commit. If you edit files afterward, rerun task check before pushing.
  • If the check fails or cannot run, resolve the failure before pushing. If blocked, report the failed command and reason; do not push or claim validation succeeded.
  • Record the command and result in the PR description and final handoff.

Agent Working Rules

  • Check git status --short before editing and do not revert unrelated user changes.
  • Prefer existing project patterns and local helper APIs over new abstractions.
  • Keep edits scoped to the requested area.
  • If changing API contracts, update tests and regenerate the client.
  • If changing UI behavior, add or adjust Vitest tests where practical and run the relevant UI checks.
  • If changing workflow or repository behavior, run the matching Python tests.
  • Mention any verification that could not be run and why.
  • Keep personal model, provider, editor, and delegation preferences in user-level agent configuration, not in repository guidance.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free