# Repository Guidelines ## Project Structure & Architecture This is a Yarn workspace monorepo. Application code lives under `apps/`; shared package blueprints live under `packages/`; archived experiments live under `experiments/`. - `apps/backend`: NestJS backend with Prisma and GraphQL code-first support. - `apps/backend/src`: active Nest modules, controllers, services, GraphQL resolvers, and generated `schema.gql`. - `apps/backend/prisma`: Prisma schema and Prisma-related backend files. Keep Prisma models unchanged unless a task explicitly asks for data-model work. - `apps/backend/test`: Jest e2e tests. - `apps/frontend`: Angular app with Apollo Angular and GraphQL Code Generator output. - `apps/frontend/src/app/core/graphql/operations`: frontend `.graphql` operation documents. - `apps/frontend/src/app/core/graphql/generated/graphql.ts`: generated Angular Apollo types and services. - `packages/hello-world`: local workspace package blueprint for shared package structure. - `experiments/trpc`: archived tRPC experiment and generator work. Do not modify it unless a task explicitly targets the archive. The active application architecture is NestJS + Prisma + GraphQL code-first on the backend, and Angular + Apollo Angular + GraphQL Code Generator on the frontend. The old tRPC work is archived under `experiments/trpc` and is not active app wiring. ## Build, Test, and Development Commands Run commands from the repo root unless noted. For AI-operated work-producing commands, use the Runtime command wrapper as the canonical execution path so work registration and live visibility are not optional: - `node ai/runtime/dist/cli.js command run -- [args...]`: run a repository command with Runtime work-session registration, heartbeat, foreground child projection, terminal status, and parent restoration. Pure read-only inspection commands may be used directly while cfd-0036 hardens the guard policy, but build, test, validation, lifecycle, server, generated-code, and file-producing commands should run through the wrapper or a typed Runtime entrypoint with equivalent work-contract coverage. - `yarn install`: install workspace dependencies. - `yarn dev:backend`: run the Nest backend in watch mode. - `yarn dev:frontend`: serve Angular on `0.0.0.0:4220`. - `yarn codegen`: generate frontend GraphQL types/services from the backend schema and frontend operations. - `yarn build:backend`: compile the backend. - `yarn build:frontend`: build the Angular app. - `yarn build`: build packages, backend, and frontend. - `yarn lint`: run non-mutating lint checks. - `yarn lint:fix`: run lint fixes intentionally. - `yarn format:check`: run non-mutating formatting checks. - `yarn format`: apply formatting intentionally. - `yarn test:backend`: run backend unit tests. - `yarn workspace backend test:e2e`: run backend e2e tests. - `yarn test:frontend`: run frontend tests. - `yarn build:packages`: build local workspace packages. ## GraphQL Schema And Codegen The backend uses NestJS GraphQL code-first. `apps/backend/src/schema.gql` is generated by backend app startup/tests from GraphQL decorators and resolvers. The root `codegen.yml` reads that schema and frontend documents from `apps/frontend/src/app/core/graphql/operations/**/*.graphql`, then writes generated Angular Apollo code to `apps/frontend/src/app/core/graphql/generated/graphql.ts`. When changing GraphQL resolvers, object types, inputs, or operation documents, run: - `yarn workspace backend test:e2e` or another backend app initialization path to refresh `apps/backend/src/schema.gql`. - `yarn codegen` to refresh frontend generated GraphQL code. - The relevant backend/frontend build and test commands. ## Coding Style & Naming Conventions Use TypeScript throughout. Follow existing Nest and Angular naming patterns: backend files use `.module.ts`, `.service.ts`, `.controller.ts`, `.resolver.ts`, and `.spec.ts`; Angular specs use `.spec.ts`; GraphQL documents use `.graphql`. Prettier uses single quotes. Backend formatting also requires trailing commas; frontend formatting uses `printWidth: 100`. Use two-space indentation, keep imports ordered framework/external/local, and prefer explicit return types on public backend handlers and resolvers. ## Testing Guidelines Backend unit tests use Jest with `*.spec.ts` files under `apps/backend/src`. Backend e2e tests use `apps/backend/test/jest-e2e.json` and `*.e2e-spec.ts`. Frontend tests run through Angular/Vitest via `yarn test`. Add focused tests for service, resolver, controller, and component behavior changed by a PR. Run the relevant test command before submitting. ## Chunk-Based AI Workflow Migration work is handled in explicit chunks. Execute only the requested chunk, keep changes inside the stated scope, and avoid opportunistic cleanup. Before editing, inspect the current tree and identify files that must change. Do not change application source code, dependencies, schema, frontend UI, or archived experiments unless the chunk explicitly asks for it. Reusable AI workflow files live under `ai/`: - `ai/roles/orchestrator.md`: planning-only role. Do not edit code unless explicitly asked. - `ai/roles/requirements.md`: requirements role for turning product intent into approved acceptance criteria. - `ai/roles/requirements-intake.md`: intake role for turning rough ideas into user-centered requirements drafts. - `ai/roles/requirements-review.md`: review role for approving or blocking requirements before chunk planning. - `ai/roles/chunk-planner.md`: planning role for converting approved requirements into ordered implementation chunks. - `ai/roles/developer.md`: implementation role for a single assigned chunk. - `ai/roles/qa.md`: review and validation role. - `ai/tasks/requirements-template.md`: standard requirements capture template. - `ai/tasks/requirements-intake-template.md`: standard intake prompt/template. - `ai/tasks/requirements-review-template.md`: standard requirements review template. - `ai/tasks/chunk-plan-template.md`: standard approved-requirements-to-chunks template. - `ai/tasks/feature-template.md`: standard feature chunk template. - `ai/tasks/qa-review-template.md`: standard QA review template. - `ai/requirements/README.md`: requirements lifecycle workflow. - `ai/commands/validate.sh`: full validation script. - `ai/commands/new-chunk.sh`: create draft, backlog, or active chunks from a slug and optional piped prompt content. - `ai/commands/activate-chunk.sh`: move a draft or backlog chunk into `active` safely. - `ai/commands/complete-chunk.sh`: mark an active chunk completed and archive it safely. - `ai/commands/orchestrator-status.sh`: summarize active, backlog, latest completed chunks, and git status. - `ai/commands/orchestrator-next.sh`: print the recommended next orchestrator action from chunk state. - `ai/chunks/README.md`: persistent chunk lifecycle, naming, metadata, execution, and archive workflow. - `ai/standards/done.md`: definition of done for chunk completion. - `ai/standards/qa-gates.md`: QA gates for static validation, runtime smoke, integration, UX, cleanup, documentation, and regression review. - `ai/standards/iteration-policy.md`: retry limits, stop conditions, scope discipline, and validation discipline. - `ai/standards/orchestration-workflow.md`: reusable Orchestrator -> Developer -> QA loop workflow. - `ai/standards/requirements.md`: requirements file format and quality bar. - `ai/conventions/*.md`: default Angular, NestJS, GraphQL, and testing conventions. Chunk files use `chunk-XXX-kebab-case-name.md` with immutable zero-padded ids. Move chunks through `drafts`, `backlog`, `active`, and `completed`; preserve completed chunks as immutable history. Lifecycle authority follows the runtime SOP: AI may propose, runtime may enforce, validators may verify, and only canonical transition engines may mutate authority state. Developer records implementation evidence, QA records independent PASS/BLOCKED evidence, and Orchestrator coordinates transitions and approval boundaries. Manual lifecycle edits and legacy helpers are compatibility-only unless they wrap canonical transition or dispatcher tooling. For rough, large, or ambiguous product ideas, use the requirements workflow before implementation: Requirements Intake creates a draft, Requirements Review returns `PASS` or `BLOCKED`, Chunk Planner creates ordered chunks from approved requirements, and Orchestrator then runs Developer -> QA loops. Validation passing is required but is not enough by itself to mark a chunk complete. Behavior/UI/integration changes need applicable runtime smoke, cleanup, documentation updates, and QA or human approval according to `ai/standards/done.md`. After each chunk, run the commands requested by the chunk, then report: - What changed. - What was intentionally left untouched. - Commands run and whether they passed. - `git status`. - `git diff --stat`. If a command cannot run because of sandbox or environment restrictions, state the concrete failure and whether a permission rerun was needed. ## Commit & Pull Request Guidelines Recent history uses short imperative or status-style subjects, for example `Add files.` and `Refining template.` Keep subjects concise. Pull requests should include a summary, tests run, linked issues when applicable, and screenshots for visible frontend changes. Note Prisma schema, GraphQL schema, generated-code, or dependency changes explicitly. ## Security & Configuration Tips Do not commit secrets, local database credentials, or generated dependency folders. Keep environment-specific configuration outside source control, and document required variables when adding them.