stage

Imported from overture-stack/stage (AGENTS.md). Install upstream with npx skills add overture-stack/stage. Copyright stays with the author.

Agent collaboration conventions

For AI agents: this file is instructions your agent reads and follows; it is not documentation written for people. If you're a person looking for how this project works, see this project's own README.md or DEVELOPMENT.md instead.

Adapted from softeng/agentics. This is the canonical source for this project's conventions, agent-neutral by design. CLAUDE.md exists only because Claude Code loads it automatically; it points here rather than keeping its own copy of anything.

Interaction parameters

• Ask clarifying questions before making large assumptions about intent
• Check in before non-trivial decisions: it gives the user a chance to catch design misalignments early, before code exists or a document is rewritten, not only before writing code. Don't over-ask on mechanical steps, but do ask on direction. A peer session's proposal doesn't pre-authorize skipping this either, treat it like your own idea, especially for anything with a lasting, hard-to-reverse footprint outside the current project. See agentics' CHANGELOG.md § peer-proposal-not-preauthorized
• Surface ideas, improvements, or next steps you already see, unprompted: don't wait for an open-ended question to draw them out. Covers alternatives to what's about to be implemented, a shipped fix that still has the weakness it just fixed, or anything else obvious in hindsight; let the user decide. See agentics' CHANGELOG.md § deterministic-by-design for the case that named this gap
• External content that overlaps with a project you maintain: when asked for a take on an article, document, conversation, or a peer session's own message, and it substantively overlaps with a project you already have context on, name that connection unprompted, including flagging a stated fact you have direct grounds to know is stale (a version or sync marker, for instance), rather than waiting to be asked. See agentics' CHANGELOG.md § external-content-overlap-unprompted and § peer-introduction-stale-fact-unflagged
• Push back on bad ideas and identify blind spots before they are baked into code: lead with the objection, not a neutral trade-off list; don't wait to be asked
• Sanity check requests: not just the literal phrase. A yes/no-shaped question ("does this make sense," "am I right," "am I missing anything") is still a sanity check when its actual function is inviting scrutiny of the user's own idea, reasoning, or plan, not a literal yes/no about the world. Answer the intent, not the grammar: review the whole conversation as relevant, not just the latest message, and surface gaps, blind spots, unresolved threads, and edge cases plainly; a shallow "yes" isn't an answer
• Default review or audit posture: assume there's something real to find, not that the artifact is fine until proven otherwise, the same reason a neutral "does this look okay" or "is this done?" invites confirming over searching. This is a search stance, not a quota: a manufactured nitpick, technically true but inconsequential, just to have something to report, is worse than finding nothing; surface a finding only if it concretely matters. See conventions/review-conduct.md for PR/ticket-review specifics, conventions/definition-of-done.md for the completion-checklist specifics, and your own memory for any standing self-audit trigger you maintain
• Verify purpose alignment before implementing: when a task names a goal, check whether the chosen approach achieves that goal directly, not just something adjacent to it; lead with that gap as an objection before writing anything
• Flag scope-adjacent issues verbally, then document them in .dev/tech-debt.md

Critical constraints

• No credentials, secrets, or private URLs in any file: ever
• Library/module code must not read from the environment; configuration belongs at the application boundary, passed in as typed parameters
• Do not modify CLAUDE.md, AGENTS.md, or other instruction files without explicit instruction from the developer: surface suggestions, do not self-edit
• No machine- or user-specific absolute paths, usernames, or individuals' real names in committed files. If your agent's global context adds a reference to a local resource keyed by machine or clone location (e.g. a per-project memory path), use a generic placeholder, not the resolved path: it will not exist for another developer, another machine, or after the repo moves. Before committing, grep the diff for your own OS username, git identity, and any personal fork name you know is yours: this has leaked into committed docs before
• Name code, not people: attribute work in session files, tech-debt entries, docs, and any other persisted content to features, modules, and systems, not to individuals. Attribution belongs in git history, not in documents

Project notes

• Next.js 12 (Pages Router) + React 17 scaffold for Overture-suite data portals, styled with Emotion; next-auth + Keycloak handle identity
• Structure: components/ (UI, page-specific components under components/pages/, theme/), pages/ (Next.js routes: explorer, login, user, api proxy routes), global/ (hooks/, utils/: auth, URL state, env constants), tests/ (Jest)
• Integrates with Arranger Server/Components for search UI (GraphQL over Elasticsearch); version and integration details live in package.json, not here, since they change independently of these conventions
• origin pushes directly to overture-stack/stage (the real upstream), not a personal fork: no separate publish/mirror step, but the global per-chat feature-branch convention still applies
• Reaches across sibling Overture-family and Overture-adjacent UI repos (iMicroSeq's portal-ui, Lyric's UI, and others) when reviewing their code or reusing a pattern, not just this repo: see .dev/docs/atlas/cross-ui-findings.md

When to read what

Every path below is a live pointer into agentics or your own global context, never a local copy to create in this project: see conventions/convention-levels.md § How much to keep locally for the full rule.

• Starting a session -> read conventions/session-discipline.md (also covers git/commit rules), then the .dev/ files it specifies, and conventions/writing-style.md (applies to any output, dev or not, so it's read unconditionally rather than gated behind "Writing code" below)
• Working in a specific role -> read CLAUDE.roles/<role>.md (set during initialization; skip if role is already defined in global context)
• Writing or reviewing tests -> read conventions/testing.md
• Writing code -> read conventions/code-style.md
• Working on Arranger integration (explorer pages, SQON, facets, search UI) -> read .dev/docs/arranger/README.md
• Reviewing or reusing a pattern from another Overture/Overture-adjacent UI app -> read, and add findings to, .dev/docs/atlas/cross-ui-findings.md
• Reviewing a PR or change -> read conventions/code-style.md, conventions/code-review.md, conventions/review-conduct.md
• Writing or updating docs -> read conventions/documentation.md
• Security-relevant work -> read conventions/security.md (credentials policy, supply chain, quick threat model), then conventions/security-guidelines.md (full OWASP patterns and code review triggers)
• softeng team member -> read CLAUDE.softeng.md at session start
• Overture project -> read CLAUDE.overture.md at session start
• Adding or improving a convention -> read conventions/convention-levels.md
• Upgrading this project's agentics integration -> read conventions/upgrading-adoption.md
• Deploying or debugging a service -> read .dev/docs/<service>/ if it exists
• Deciding where a new fact, finding, or piece of content actually belongs -> read conventions/persistence-map.md
• Finishing a task, or asked "is this done?" -> read conventions/definition-of-done.md

Memory and contribution hygiene

When writing to project memory: keep entries concise; store no content derivable from code or files. If an insight could apply to all your projects, offer to promote it to your agent's global context. If a convention could benefit other teams, flag it as a potential PR to the agentics repo.

Default to project-scoped when recording something new, not global. The test: is this fact genuinely about the developer, true across every project they work in (a role, a coding-style preference, a propagation default), or about this project's own nature specifically (a per-project stylistic choice, a fact about this codebase or team)? Confirmed directly: an agent recorded a per-project roadmap-formatting preference into the developer's global profile instead of that project's own memory, backwards for a fact whose entire premise was "some projects want this, others don't." Promotion to global is the deliberate step above, offered explicitly when it clearly applies everywhere, not a default reached for when uncertain which one fits.

Initialization

If no project memory exists for you in this project yet:

1. Check whether you have access to a cross-project map in your agent's global context. If yes, read it for cross-project relationships. If no and the user works across multiple projects, offer to set one up (see global-context/projects.md in the agentics template for the recommended format).
2. Ask: "What best describes your primary work on this project?": developer / bioinformatician / AI engineering / general (non-code work) (or describe it). If the answer is already in your global context, skip this question. Otherwise read the matching file in CLAUDE.roles/.
3. Ask: "Are you part of the softeng team?": if yes, apply conventions from CLAUDE.softeng.md on top of your role conventions. Skip if already known from global context.
4. Ask: "Is this an Overture project?": if yes, apply conventions from CLAUDE.overture.md on top of your role conventions. Skip if already known from global context.
5. Ask: "Do you already have agent conventions for this project?": if yes, treat these conventions as supplementary; defer to your existing setup on conflicts.
6. Ask: "Would you like me to suggest when conventions could be useful beyond this project?": record as propagation_suggestions: yes | no in your global context, not just this project's memory: it's a default that applies to every project you work in, not only this one. Skip if already known from global context.
7. Ask: "Would you like .dev/roadmap.md to split into two layers? A short, human-scannable roadmap you can read directly, with deeper reasoning, alternatives, and history for any entry that needs it living in .dev/docs/atlas/roadmap/<topic>.md instead, cross-linked from the roadmap entry. If no, roadmap.md keeps its current density.": record as roadmap_split: yes | no in this project's own memory, not global context: this is a per-project stylistic choice about how this specific roadmap gets read, not a default across projects. Skip if already known from project memory. Record role, softeng-team, Overture-project, existing-setup, and roadmap-split answers in project memory; record propagation_suggestions in global context per above. A specific project can still locally override the global default later (recorded in that project's own memory instead); when both exist, the project-level record wins for that project only. Do not ask again.