# 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

| Section | Content |
|---|---|
| [Summary](#summary) | Project, stack, language |
| [Architecture](#architecture) | Declared stance and boundaries |
| [Commands](#commands) | Build, test, quality, environment |
| [Structure](#structure) | Where everything lives |
| [Do Not Touch Rules](#do-not-touch-rules) | What no agent modifies |
| [Preferences](#preferences) | OpenSpec commands, orchestration, quality |
| [Roles](#roles) | Available agents |
| [Workflow](#workflow) | Pipeline and gates |
| [Golden rules](#golden-rules) | Cross-cutting rules |
| [Skill Registry](#skill-registry) | Skills with path and trigger |
| [Stacks](#stacks) | Project stacks (single/multi) |
| [Extending](#extending) | How to extend skills, agents and packs |
| [Placeholders](#placeholders) | Values read by the prompts |
| [Document map](#document-map) | Where to find each thing |
| [Pending](#pending) | `TBD` from the bootstrap |

---

## 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

| Purpose | Command |
|---|---|
| Install dependencies | `{{INSTALL_COMMAND}}` |
| Build | `{{BUILD_COMMAND}}` |
| Run locally | `{{RUN_APP_COMMAND}}` |
| Tests | `{{TEST_COMMAND}}` |
| Lint (production) | `{{LINT_MAIN_COMMAND}}` |
| Lint (tests) | `{{LINT_TEST_COMMAND}}` |
| Static analysis | `{{STATIC_ANALYSIS_COMMAND}}` |
| Quality gate | `{{QUALITY_COMMAND}}` |
| Coverage | `{{COVERAGE_COMMAND}}` |
| Mutation | `{{MUTATION_COMMAND}}` |
| CRAP | `{{CRAP_COMMAND}}` |

**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

| Preference | Value | Possible values |
|---|---|---|
| OpenSpec commands | `{{OPENSPEC_COMMANDS_POLICY}}` | `user` (always the human), `agent` (always the agent, mutation with confirmation), `ask` (ask at the start of each session) |
| Orchestration | `{{ORCHESTRATION_POLICY}}` | `orchestrated` (default) or `manual` |
| CRAP threshold | `{{CRAP_THRESHOLD}}` | integer per method (default `6`) |
| Persistent memory | `{{MEMORY}}` | `engram`, another, or `none` |
| Documentation | Only the areas selected in `state.docs` | Root configurable (`state.docs.root`); English folder names; content in `language.user` |

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

---

## Roles

| Role | Canonical prompt | Purpose |
|---|---|---|
| `analyst` | `.atlas/agents/analyst.md` | Analysis and planning |
| `engineer` | `.atlas/agents/engineer.md` | Implementation with TDD; each stack generates `engineer-<stack>` |
| `reviewer` | `.atlas/agents/reviewer.md` | Code review (read-only) |
| `qa-analyst` | `.atlas/agents/qa-analyst.md` | Functional testing |
| `doc-writer` | `.atlas/agents/doc-writer.md` | Technical and functional documentation |

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.

**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

```text
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.

| Skill | Path | Trigger |
|---|---|---|
| `openspec-explore` | `.agents/skills/openspec-explore/` | Explore an idea before proposing |
| `openspec-propose` | `.agents/skills/openspec-propose/` | Plan a change |
| `openspec-apply-change` | `.agents/skills/openspec-apply-change/` | Implement the tasks |
| `openspec-archive-change` | `.agents/skills/openspec-archive-change/` | Archive a change |
| `openspec-sync-specs` | `.agents/skills/openspec-sync-specs/` | Sync specs |
| `openspec-workflow` | `.agents/skills/openspec-workflow/` | Full pipeline and gates |
| `grilling` | `.agents/skills/grilling/` | Stress-test a plan or design before building |
| `test-driven-development` | `.agents/skills/test-driven-development/` | Red → green → refactor |
| `implementation-standards` | `.agents/skills/implementation-standards/` | Engineering criteria: SOLID, Clean Code, refactors |
| `using-git-worktrees` | `.agents/skills/using-git-worktrees/` | Isolate the change |
| `git-workflow` | `.agents/skills/git-workflow/` | Branches, worktrees, PR, cleanup |
| `architectural-decision-records` | `.agents/skills/architectural-decision-records/` | Record a durable decision |
| `gherkin-specs` | `.agents/skills/gherkin-specs/` | Write scenarios |
| `conventional-commits` | `.agents/skills/conventional-commits/` | Every commit |
| `session-startup` | `.agents/skills/session-startup/` | Session start |
| `session-end` | `.agents/skills/session-end/` | Session close |
| `update-harness` | `.agents/skills/update-harness/` | Update the template/harness to a new version (any language) |

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`](.atlas/docs/en/extending.md). Follow it when the user asks.
- Project-specific context: [`docs/project-context.md`](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`](.atlas/PLACEHOLDERS.md). **A placeholder that is not in the contract
does not exist and cannot be used.**

| Placeholder | Value |
|---|---|
| `TEST_COMMAND` | {{TEST_COMMAND}} |
| `QUALITY_COMMAND` | {{QUALITY_COMMAND}} |
| `MUTATION_COMMAND` | {{MUTATION_COMMAND}} |
| `CRAP_COMMAND` | {{CRAP_COMMAND}} |
| `APP_PORT` | {{APP_PORT}} |
| `RUN_APP_COMMAND` | {{RUN_APP_COMMAND}} |
| `SERVICE_NAME` | {{SERVICE_NAME}} |
| `HEALTH_URL` | {{HEALTH_URL}} |
| `METRICS_PATH` | {{METRICS_PATH}} |

**`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

| For | Where |
|---|---|
| Behavior specifications | `openspec/specs/` |
| Active change | `openspec/changes/<change>/` |
| Architectural decisions | `adr/` |
| Functional documentation (Use Cases) | `docs/functional/` |
| Architecture and C4 | `docs/architecture/` |
| API contracts | `docs/api/` |
| Development guides | `docs/guides/` |
| Preliminary QA inventory | `openspec/changes/<change>/qa-scenarios.md` |
| QA reports | `openspec/changes/<change>/qa-report-*.md` |
| Review reports | `openspec/changes/<change>/reviewer-report-*.md` |
| Harness guides | `docs/README.md` (index) · `docs/harness/es/` · `docs/harness/en/` |
| Project-specific context | `docs/project-context.md` |
| ATLAS landing page | `docs/README.md` (the project has no root README; its own is generated from `.atlas/PROJECT-README.md`) |
| Optional packs | `.atlas/packs/README.md` (EN) |
| Harness scripts | `.atlas/scripts/` |
| Project state | `.atlas/state.json` (`stacks`, `packs`, `optional_agents`, `readme`) |

---

## Pending

{{TBD_ITEMS}}