# Working Agreements

> Always-on engineering contract for this project - language rules, security, architecture, package manager, timestamps, logging, and agent workflow, plus an index of the stack skills. Load at the start of any coding, review, or commit task; load the relevant stack skill on demand.

- Skill: `carlosferorduna/working-agreements` (Agent Skill)
- Install (CLI): `npx skillmds@latest add carlosferorduna/working-agreements`
- Raw SKILL.md: https://api.skillmd.com/api/skills/carlosferorduna/working-agreements/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: CarlosFerOrduna (https://skillmd.com/u/carlosferorduna)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/carlosferorduna/working-agreements

---


# Working Agreements

The always-on engineering contract. When the harness wrapper is installed
(Claude Code plugin or opencode plugin), this file is injected at the start of
every session (startup, `/clear`, and compaction); on a bare `~/.agents/skills`
install, load it with the `skill` tool or read it directly from disk. It stays
small on purpose: the details live in stack-specific skills that load on
demand.

This contract states the default rules for the repo(s) it governs. A project
layer (project-level skill or `AGENTS.md`) may tighten them; if a rule
conflicts with an explicit user instruction, the user instruction wins.

## Language

- Code in **English** with descriptive names: `getUserById`, not `getUsrById`.
- Make code **descriptive and readable on its own**: names carry intent, so a
  comment is the last resort, added only when the code cannot explain the
  **why** on its own.
- **JSDoc** always in **English**, regardless of the surrounding prose; it is
  API surface, not local note-taking.
- **Inline comments** in Spanish and only to explain **why**, never restate
  the **what** the code already says.
- README and docs in English.

## Security

- Never commit `.env` files; keep secrets out of git via `.gitignore` and
  provide `.env.example` as the template.
- Never operate on a database that is not the repo's local/Docker one. Dev or
  staging credentials visible in `.env` or config are read-only information:
  running migrations or writing to those environments is off limits, even when
  reachable.
- Never log: tokens, keys, passwords, decrypted config, or sensitive request
  bodies.
- Joi validation schemas are the source of truth for env vars, validation, and
  defaults; validate environment config at startup.
- Sensitive config may be encrypted at rest with AES-256-GCM (`CRYPT_KEY` as a
  base64 32-byte key). Never log decrypted values.

## Architecture

- The default assumption is a **microservices** architecture with explicit
  service boundaries; avoid unnecessary coupling. A project may override this
  layer.
- Prefer the smallest simple solution that satisfies the requirement. Reviews
  should push toward simplicity, not ceremony.

## Package manager

- Determine the package manager from the project **lockfile**, never from
  README or Dockerfiles.
- In a pnpm project never introduce `yarn.lock` or `package-lock.json`.

## Timestamps and logging

- All timestamps are UTC.
- Logs are written in English and never contain tokens, secrets, API keys,
  passwords, or decrypted configuration.

## Agent workflow

- Check `package.json` and the lockfile before assuming tooling is available.
- Run the project's lint command before committing.
- Verify tests according to the project's fork-specific test configuration.
- Run local build, lint, and unit tests as part of finishing an implementation;
  do not ask for permission first, just report the result.
- Keep shared values (enums, seeds, config) synchronized across their sources.
- At each natural commit point (a checkpoint reached or the requirement
  finished), pause and present the proposed commit message (following
  `commit-conventions`) with a summary of the changes; the user approves the
  message before anything is staged or committed. OpenCode and Claude Code
  expose this flow as `/commit` and `/push` commands; Zed as the `commit`
  skill.
- Never `git commit`, `git push`, or stage changes without that explicit
  approval; report the finished work and its state first.
- Synchronizing to external services (Postman sync, deploys, tickets) requires
  an explicit ask each time.
- Never self-arm autonomous background loops/wakeups; only run them when the
  user explicitly invokes the loop command.
- Never include `Co-Authored-By:` trailers in commit messages.

## Stack skills

Load the matching skill when the task touches its area (they are on-demand, so
they only cost context when triggered). Use the `skill` tool to load them; if
skills are not available in the current harness, read the `SKILL.md` files
directly from `~/.agents/skills/` or the plugin/marketplace skills directory
and apply them as if they were a direct project instruction:

- `commit-conventions` — Conventional Commits with a leading gitmoji.
- `commit` — the commit/push handshake: propose, present, and approve.
- `nestjs-code-style` — TypeScript / NestJS style, naming, types, repositories.
- `database` — versioned SQL migrations and ORM schema discipline.
- `typeorm` — TypeORM entity, relation, repository, query, and configuration conventions.
- `typeorm-mssql` — MSSQL-specific TypeORM conventions (identifiers, keys, filtered indexes).
- `typeorm-pg` — Postgres-specific TypeORM conventions (identifiers, keys, partial indexes).
- `testing-standards` — Jest, unit and integration test layout.
- `code-intelligence` — codebase search and graph navigation (ripgrep, ast-grep, graphify).

## Contract version

This contract is **v0.5.11**. When you need to know or report the version of the
standards in effect (for example, when collaborators on different installs
produce divergent commits), state it.