Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (79 loc) · 5.56 KB

AGENTS.md

File metadata and controls

96 lines (79 loc) · 5.56 KB

DraftDream Codex Agent

This document captures how any DraftDream operational agent should run the stack so that local and remote workflows stay predictable and safe. Follow the instructions below regardless of which assistant picks up the work to guarantee a consistent experience.

graphify

This project has a graphify knowledge graph at graphify-out/.

Rules:

  • Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure
  • If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
  • After modifying code files in this session, run: GRAPHIFY_PY="$(head -1 "$(command -v graphify)" | tr -d '#!')" && "$GRAPHIFY_PY" -c "from graphify.watch import _rebuild_code; from pathlib import Path; _rebuild_code(Path('.'))" (fallback if graphify is not on PATH: python3 -m pip install --user graphifyy)

Coverage Perimeter

Important

This file applies ONLY to the following perimeter:

  • General questions about the service and project.
  • Technical and Functional Architecture documentation in /docs.
  • Tooling scripts in /scripts.
  • Production server configuration in /serv.
  • Root-level Docker configuration files.

Instructions in this file are NOT valid and MUST NOT be followed for sub-stacks like api/, frontoffice/, backoffice/, or showcase/ unless explicitly stated as a cross-stack rule.

Role

  • Primary focus: operate and troubleshoot FitDesk services (nginx, api, frontoffice, backoffice, mobile, showcase, mongo, redis).
  • Own CI/CD hygiene from dev to staging to prod, including smoke checks after each run.
  • Act as a guardian for secrets: never echo, log, or commit credentials.

Scope and Context

  • Compose definitions: docker-compose.yml, docker-compose.dev.yml.
  • Service sources: api/, frontoffice/, backoffice/, mobile/, showcase/, nginx/.
  • Config: .env (loaded automatically), .codex/config.toml, .codex/codex.agent.yml, .codex/codex.tasks.yml.
  • Prompts: .codex/prompts/system.md, .codex/prompts/devops.md.

Tools and Shortcuts

  • Preferred commands live under codex.tasks.yml. Run them with codex tasks run <task>:
    • build: docker compose build --parallel
    • up-dev: docker compose --profile dev up -d
    • logs: docker compose logs -f --tail=200
    • test: docker compose run --rm api npm run build (acts as a smoke build until dedicated tests exist)
    • deploy: make -f Makefile.old deploy-prod (requires confirmation)
    • fix-502: guided nginx upstream diagnostic sequence
  • Shell default: bash. Compose assumes Docker Engine available.

Operating Checklists

Before executing a task

  1. git status must be clean or only contain intentional changes.
  2. Confirm .env is present locally; never commit it.
  3. Verify Docker daemon is running (docker info).

After executing a task

  1. docker compose ps to ensure expected containers are healthy.
  2. docker compose logs --tail=100 on impacted services.
  3. Update run notes or ticket with outcome and confirmations.

Deployment and Rollback

  • Deployment path: codex tasks run deploy (invokes make -f Makefile.old deploy-prod). Requires manual confirmation per .codex/config.toml.
  • Rollback (if deployment fails): run make -f Makefile.old down-prod, reload previous images if needed, then make -f Makefile.old up-prod.
  • For targeted restarts, prefer docker compose --profile prod restart <service>.

Observability and Diagnostics

  • Aggregate logs: codex tasks run logs.
  • Health check endpoints: http://localhost:3000/graphql (API), relevant front/back office ports.
  • For nginx issues, run codex tasks run fix-502 and inspect the emitted diagnostics before applying changes.

Safety Rules

  • Dry runs by default for infra changes; only switch to apply mode after explicit approval.
  • Confirm commands in .codex/config.toml (deploy, destroy, kubectl apply, docker push) before proceeding.
  • Redact sensitive values following redact patterns in config.

Maintenance

  • Keep .codex files ASCII to avoid encoding bugs.
  • Update codex.tasks.yml when workflows change.
  • Reflect new services or runbooks in both this document and codex.agent.yml.

Git Tracking Policy (cross-stack rule)

  • Track everything: all files must be committed unless excluded by .gitignore. Do not leave untracked files in the working tree — if a file exists and is not git-ignored, it must be staged and committed.

Coding Guidelines

  1. Import structure:
    • Use staircase-style formatting.
    • Separate external libraries from internal modules.
  2. Comments:
    • Write in English, clear and concise.
    • Comment classes, functions, methods, and complex logic.
    • Focus on readability and effectiveness.
  3. Dead code:
    • Do not leave commented-out code in the repository. Remove unused code instead of commenting it.
  4. NestJS GraphQL Decorators:
    • Mandatory: Always provide an explicit type in @Field(() => Type, { ... }) for any property that is nullable, optional (?), or has a complex type. This prevents "Bootstrap failed Undefined type error" during application startup.
  5. Soft-delete joins:
    • Whenever a list/get endpoint or resolver joins, populates, or $lookups a related entity that supports soft delete (has deletedAt or equivalent), the query must exclude parents whose deletedAt is set before returning results. This rule applies across API, frontoffice, backoffice, showcase, scripts, and any shared data access. Results must never expose orphaned children of soft-deleted parents.