devops-platform-api/AGENTS.md

@RTK.md

Agent Instructions

This backend owns the DevOps platform API only. Do not edit sibling projects from this directory.

Hard Boundaries

• Write only inside devops-platform-api unless the user explicitly expands the scope.
• Do not write devops-platform-web.
• Do not write devops-platform-docs/devops-platform-implementation-tracker.md; the coordinating thread owns tracker updates.
• Do not revert unrelated user or worker changes.

Backend Standards

• Use NestJS modules and dependency injection for all business boundaries.
• Keep controllers thin. Validation, orchestration, and audit decisions belong in services.
• Use Prisma as the default data access layer. Business code must not create mysql2 pools or scatter handwritten SQL.
• If native SQL is unavoidable, place it in a Repository, parameterize it, document why Prisma is insufficient, and keep the method narrow.
• Keep external clients behind integration modules: Jenkins, Gitea, notification providers, and LLM.

Security Standards

• Never commit real credentials.
• Redact tokens, webhook URLs, cookies, authorization headers, private keys, and long opaque secret-like strings before logging, auditing, returning errors, or passing content to LLMs.
• Store future persisted secrets encrypted server-side only.
• Frontend must never receive Jenkins/Gitea/notification/LLM secret values.

Audit Standards

• Record actor, resource, action, before/after state summaries, request source, and parameter digests for deploy, cancel, retry, secret change, and agent invocation operations.
• Deploy run status transitions must be idempotent and concurrency-safe when database writes are enabled.

Agent Standards

• Agent features must be tied to DevOps workflows, not general chat.
• Agent calls are read-only unless a future product decision explicitly changes this.
• Save prompt version, purpose, operator, input digest, output digest, token estimate, and sanitized failure summary for every real invocation.