AGENTS.md — Project contract

Entry point for any agent. First session: if .atlas/state.json does not exist or its status is pending, read and run .atlas/BOOTSTRAP.md before any other action. If the user says "configure this project", "run the initial setup" or any equivalent, this is what must be executed.

The source of truth for behavior is openspec/specs/ and adr/.

Index

Summary

• Project: {{PROJECT_NAME}}
• Description: {{ONE_LINE_DESCRIPTION}}
• Stack: {{STACK_SUMMARY}}
• Domain: {{DOMAIN_SUMMARY}}
• Base package: {{PACKAGE_BASE}}
• Documentation language: {{LANGUAGE_USER}}
• Skills and prompts language: {{LANGUAGE_AGENT}}

Architecture

{{ARCHITECTURE_SUMMARY}}

Boundaries and dependency direction: {{ARCHITECTURE_NOTES}}

• No agent imposes an architecture different from the one declared here.
• Durable decisions are recorded in adr/ and are immutable once accepted.
• If an implementation contradicts a current ADR, the agent stops and asks.

Commands

QA environment: {{QA_ENVIRONMENT}}

Multi-stack: these commands belong to the default stack (first row of § Stacks); each engineer-<stack> uses its row.

Stacks

A stack = profile + path + commands + packs. Each stack generates engineer-<stack> (even with one). Add later: crear-perfil.mjs → state.stacks + this table → renderizar-adaptadores.mjs.

{{STACKS_TABLE}}

Structure

{{PROJECT_STRUCTURE}}

Each change lives in openspec/changes/<change>/ and is worked on in its branch or worktree.

Do Not Touch Rules

{{DO_NOT_TOUCH}}

In addition:

• openspec/specs/ and adr/ are not modified from implementation.
• Secrets, credentials and real data are never committed.
• External dependencies are not added without justification in design.md or an approved ADR.

Preferences

Invariant: archive and sync always require explicit approval, whatever the preference.

Roles

Adapters are generated by renderizar-adaptadores.mjs from .atlas/agents/ + AGENTS.md. Each stack generates engineer-<stack>; without stacks, engineer.md is generated and removed on setup. Codex has no subagents: roles are emulated with this file and the role announcement. Cursor uses .cursor/agents/ with model: inherit; it has no per-role write permissions, so the reviewer's read-only contract is enforced by its prompt (it must still write its report). Supported hosts: OpenCode, Claude Code, Codex and Cursor.

Optional roles (only if the bootstrap activates them; see state.optional_agents): mentor (agnostic teaching of the project's concepts and patterns, code explanation and learning material) and business-strategist (business model, value proposition, segments, pricing and channels in docs/business/). They are not part of the delivery cycle: they are invoked when needed.

Workflow

explore → propose → apply → QA → review → close
         (proposal → specs → design → adr → tasks)

Exception — bootstrap: the initial setup (.atlas/BOOTSTRAP.md) runs on its own branch (chore/bootstrap), not in a change worktree. One commit per phase and the user merges.

Isolation: every change is written on its own branch, never on the base branch. The default is a worktree; a simple feature branch in the main checkout requires an explicit human request, a clean working tree, aligned submodule branches and a record in the change. See using-git-worktrees and git-workflow.

Stacks: state.stacks is the source; each stack generates engineer-<stack> and packs are activated per stack.

Gates

The analyst orchestrates by default and stops at:

1. Approval of each OpenSpec artifact.
2. Start of implementation (can be resumed in another session).
3. Start of QA (consumes an environment).
4. Pull request creation.
5. Archive approval and merge (always the user).

In manual mode, the user invokes each phase; the analyst checks that no gate is skipped.

Close

1. Design → code consistency.
2. doc-writer updates technical and functional documentation and returns a summary.
3. The analyst validates documentation consistency.
4. The PR is created; the user reviews once.
5. User approves archive; run archive + sync and commit in the same PR.
6. User confirms and merges.
7. Cleanup (branch + worktree).

Golden rules

• Branch isolation: no commit and no change artifact is written on the base branch; isolate every change (worktree by default, human-requested feature branch as exception). The pre-commit guard blocks any commit on the base branch.
• Incremental commits: one logical change = one commit (see conventional-commits).
• Role byline in agent commits: By <role>. at the end of the body.
• Code comments: reference ADRs (adr/NNNN-...) or functional documentation, never openspec/ specs, roadmaps or other projects. If no ADR anchors the decision, the comment is self-contained: decision and reason.
• Quality: 0 lint violations in the touched files (pre-existing ones are fixed); CRAP ≤ {{CRAP_THRESHOLD}} per method.
• Quality gates are signals, not targets: metrics are not manipulated; lines are not deleted, methods are not split without cohesion, trivial tests are not added, the threshold is not raised and files with logic are not excluded to pass a gate.
• No finding is closed silently: it is fixed or documented and the user is consulted.
• Context discipline: targeted searches; avoid massive sweeps (grep -r, ls -R, find + cat). If the project has an index or graph, use it.
• Do not invent libraries, APIs or behavior: verify with Context7 or ask.
• Test data: if created via direct SQL, it respects business invariants and is declared.
• Role announcement: 🎩 Ahora soy <rol> / 🎩 I am now <role>, in the user's language (language.user), when changing roles.
• Never advance without explicit user approval at each gate.

Skill Registry

Triggers can be expressed in any language; each skill declares trigger examples in its description (body and description in English, language.agent). 17 core + optional packs; pack skills are registered when the pack is activated.

Pack skills (.atlas/packs/) only exist when the pack is activated.

Extending

• Agent procedure (skills, agents, stacks, profiles, packs, minimize): .atlas/docs/en/extending.md. Follow it when the user asks.
• Project-specific context: docs/project-context.md.

Placeholders

The prompts in .atlas/agents/ use project placeholders; this table gives them their values. The full contract — closed list, profile and project layers, and the three states — is in .atlas/PLACEHOLDERS.md. A placeholder that is not in the contract does not exist and cannot be used.

N/A means "it exists but does not apply": the agent skips the step and declares it; it never runs N/A. If the stack does not use a concept (mutation, health…), the value is N/A — the placeholder is never left unresolved.

Document map

Pending

{{TBD_ITEMS}}