Imported from ecaraujo/mba-ia-greenfield-project (AGENTS.md). Install upstream with npx skills add ecaraujo/mba-ia-greenfield-project. Copyright stays with the author.

AGENTS.md

Project Overview

StreamTube is a YouTube-like video sharing platform. The repository is a monorepo with:

• nestjs-project/: NestJS 11 backend API and background workers.
• next-frontend/: Next.js frontend. Video UI is outside Phase 03 scope.
• docs/: architecture, technical decisions, phase plans, and progress.

Read docs/project-plan.md for product scope and CLAUDE.md for the complete existing project guidance. This file is the Codex entry point and has the same authority as the root CLAUDE.md.

Architecture

• NestJS API owns business rules, authentication, database writes, upload orchestration, and queue publication.
• PostgreSQL stores users, channels, videos, tokens, and later social data.
• S3-compatible object storage stores source videos and thumbnails. Local development uses MinIO.
• A dedicated FFmpeg worker consumes video-processing jobs from the queue.
• Services running in Docker must address each other by Compose service name, never localhost or 127.0.0.1.

Required Planning Workflow

For phases, follow the repository pipeline in order:

1. research -> docs/decisions/technical-decisions-<phase>.md
2. plan-context -> context.md
3. plan-validate -> validation.md
4. plan-resolve -> resolved decisions/context plus library-refs.md
5. Repeat validate/resolve until validation status is clean.
6. plan-build -> executable plan with SIs, Technical Specifications, dependency map, and deliverables.
7. implement -> code and progress.md, one SI at a time.

Codex-compatible wrappers for the canonical repository skills live in .agents/skills/. The original .claude/skills/ files remain the single source of workflow instructions. Do not implement a phase before its validation.md is clean.

Working Principles

• Preserve clear module and service responsibilities. Extract ownership into the proper domain immediately.
• Use strict TypeScript and explicit contracts at external boundaries.
• Follow repository patterns in auth/, users/, and channels/ rather than rewriting established infrastructure.
• Use migrations; never enable TypeORM synchronize for application schema changes.
• Keep documentation traceable to a requirement, decision, plan SI, or implemented behavior.
• Before using a new or uncertain library API, inspect the installed version and consult Context7 or official primary documentation for that version.

Definition of Done

A change is complete only when all of these pass in the relevant project container:

1. Relevant unit, integration, and e2e tests.
2. Full test suite.
3. npx tsc --noEmit with exit code 0.
4. npm run lint.

Git Flow

• Never commit directly to main.
• Feature branches originate from dev and merge back to dev.
• Use short, descriptive commits focused on why the change exists.
• Preserve unrelated user changes and avoid destructive Git commands.

Testing Conventions

• *.spec.ts: unit tests; no real database or external I/O.
• *.integration-spec.ts: real database, repository, queue, or storage contracts.
• *.e2e-spec.ts: full HTTP contract through Supertest under nestjs-project/test/.
• Run database-sharing suites serially with --runInBand.

Codex Foundation

• Project instructions: AGENTS.md and nested AGENTS.md files.
• Skills: .agents/skills/ wrappers pointing to canonical .claude/skills/ instructions.
• Read-only workflow agents: .codex/agents/ wrappers pointing to canonical .claude/agents/ instructions.
• MCP: .codex/config.toml configures Context7 and PostgreSQL for trusted local Codex sessions.