gistfile1.txt

Below is a **repo‑level structure** that makes GitHub Copilot automatically pick up the right guidance for each part of your monorepo (APIs with NestJS and UIs with Angular), using only what GitHub documents and supports today.

---

## What to create (folder & file layout)

```
your-monorepo/
├─ APIs/
│  └─ ... (NestJS apps & libs)
├─ UIs/
│  └─ ... (Angular apps & libs)
└─ .github/
   ├─ copilot-instructions.md                # repo‑wide rules (applies everywhere)
   ├─ instructions/                          # path‑specific rules (apply only to matched files)
   │  ├─ apis-nestjs.instructions.md
   │  ├─ apis-controllers.instructions.md
   │  ├─ apis-services.instructions.md
   │  ├─ apis-repositories.instructions.md
   │  ├─ uis-angular.instructions.md
   │  └─ tests.instructions.md
   └─ prompts/                               # optional, on‑demand task templates
      ├─ new-nest-controller.prompt.md
      └─ new-angular-component.prompt.md
```

**Why this works**

* Put a single **repo‑wide** file at `.github/copilot-instructions.md` for standards that apply everywhere. ([GitHub Docs][1])
* Add **path‑specific** instruction files in `.github/instructions/…`. Each one starts with YAML front‑matter that declares an `applyTo` glob (what folders/files it should govern). Copilot automatically merges the repo file + any path‑specific file(s) whose `applyTo` matches the file(s) it is working on. ([GitHub Docs][1])
* Path‑specific instructions are **supported in VS Code Copilot Chat** and by the **Copilot coding agent** (ideal for “agents pick it up automatically”). Other environments mainly honor the repo‑wide file. ([GitHub Docs][2])
* Note: instruction files **do not influence inline code completions** as you type; they apply to Chat, the coding agent, and (where enabled) reviews. ([Visual Studio Code][3])

---

## The minimum you need to author

### 1) Repo‑wide defaults — `.github/copilot-instructions.md`

Use this for cross‑cutting rules (TypeScript strictness, linting/formatting, commit message style, security posture, CI basics). Keep sentences short and imperative.

```markdown
# Monorepo Standards (applies to all folders)
- Use TypeScript, strict mode on. Prefer async/await.
- Enforce ESLint & Prettier before commit. Follow existing configs.
- Write unit tests for new code; include positive, negative, and edge cases.
- Favor pure functions; keep I/O at the edges.
- Reference architecture docs in /docs when relevant.
```

(Place this exact filename; GitHub looks for `.github/copilot-instructions.md` in the repo. ([GitHub Docs][1]))

---

### 2) Path‑specific rules (examples)

Each file lives in `.github/instructions/…` and begins with an `applyTo` header. Multiple patterns are comma‑separated.

> **Avoid conflicting guidance across files.** If two instruction files contradict each other and both match the same file, Copilot’s choice is **non‑deterministic**. Keep rules complementary. ([GitHub Docs][1])

#### a) APIs (NestJS) — broad folder guidance

`.github/instructions/apis-nestjs.instructions.md`

```markdown
---
applyTo: "APIs/**/src/**/*.ts,APIs/**/libs/**/*.ts"
---

# NestJS conventions (APIs/)
- Project shape: controllers → services → repositories; keep controllers thin.
- DTOs: use `class-validator` and `class-transformer`; validate all inputs.
- Errors: throw Nest `HttpException` (or subclasses) with meaningful messages; map domain errors to HTTP status codes.
- Logging: use Nest Logger in infra layers; never log secrets.
- Config: centralize in `config/`; validate with a schema.
- Testing: prefer isolated unit tests with Jest & TestingModule; mock external I/O.
```

#### b) Controllers only

`.github/instructions/apis-controllers.instructions.md`

```markdown
---
applyTo: "APIs/**/src/**/*.controller.ts"
---

# Controllers
- Keep route handlers ≤ ~30 lines; delegate to a service.
- Validate with DTOs; never accept `any`.
- Use explicit HTTP status decorators; document with Swagger decorators if present.
- Return domain DTOs, not ORM entities.
```

#### c) Services only

`.github/instructions/apis-services.instructions.md`

```markdown
---
applyTo: "APIs/**/src/**/*.service.ts"
---

# Services
- Business logic lives here; no HTTP or transport concerns.
- Inject repositories via constructor; no static access.
- Transactions: expose single method that wraps the unit of work.
- Errors: throw domain errors; let controllers translate to HTTP.
```

#### d) Repositories / data access

`.github/instructions/apis-repositories.instructions.md`

```markdown
---
applyTo: "APIs/**/src/**/*repository*.ts,APIs/**/src/**/repositories/**/*.ts,APIs/**/src/**/data/**/*.ts"
---

# Repositories
- Contain only persistence logic; no business rules.
- Return plain domain objects/DTOs, not raw driver records.
- Keep queries typed; encapsulate N+1 mitigations here.
```

#### e) UIs (Angular)

`.github/instructions/uis-angular.instructions.md`

```markdown
---
applyTo: "UIs/**/src/**/*.ts,UIs/**/src/**/*.html,UIs/**/src/**/*.scss"
---

# Angular conventions (UIs/)
- Prefer standalone components; keep components presentational; put logic in services.
- State: favor RxJS streams; avoid shared mutable state.
- Change detection: mark heavy trees OnPush (or performance-friendly equivalents).
- Templates: strict type checking on; no `any`.
- Routing: lazy-load feature areas; keep guards/resolvers lean.
- Accessibility: ARIA where needed; keyboard navigation for all interactive components.
```

#### f) Tests everywhere

`.github/instructions/tests.instructions.md`

```markdown
---
applyTo: "APIs/**/*.spec.ts,APIs/**/*.test.ts,UIs/**/*.spec.ts,UIs/**/*.test.ts"
---

# Unit test standards
- Structure: Arrange–Act–Assert; names describe behavior.
- Coverage: tests for happy path, edge cases, and failure modes.
- Mocks: use lightweight jest mocks; avoid mocking implementation details.
- For Nest: build a TestingModule; mock external providers.
- For Angular: use TestBed; prefer testing public API of components/services.
```

> **How the matching works:** When Copilot (Chat or the agent) is working on `APIs/orders/src/orders.controller.ts`, it will merge repo‑wide rules + `apis-nestjs` + `apis-controllers`. For `UIs/admin/src/app/users/users.component.ts`, it will merge repo‑wide + `uis-angular`. ([GitHub Docs][1])

---

## Optional: reusable, one‑click tasks (prompt files)

Prompt files are **on‑demand** templates (not automatic) you can run in Chat, great for standard scaffolds like “generate a NestJS controller + service + tests” or “add an Angular component with tests and routing.” Store them under `.github/prompts/*.prompt.md`. ([GitHub Docs][4])

Example — `.github/prompts/new-nest-controller.prompt.md`

```markdown
---
mode: 'agent'
description: 'Scaffold a NestJS resource (controller, service, DTOs, tests)'
---

Create a NestJS resource named ${input:name:resource name}. Follow our controller/service/repo patterns
and testing standards from the instructions files. Generate:
- `*.controller.ts` with REST endpoints (CRUD as applicable)
- `*.service.ts` with business logic
- DTOs with `class-validator`
- Jest unit tests for controller and service
```

In VS Code Chat you can run it with `/new-nest-controller` and Copilot will ask for inputs. ([GitHub Docs][4])

---

## (Optional) Agent charter

If you use the **Copilot coding agent**, you can add an `AGENTS.md` to describe how the agent should behave (e.g., how to run builds/tests for APIs vs UIs). The nearest `AGENTS.md` takes precedence when the agent works in that subtree (feature is experimental; support varies by client). ([GitHub Docs][1])

---

## Where this is supported (and expectations)

* **VS Code (Chat + coding agent):** Supports repo‑wide and path‑specific `*.instructions.md`. You can also generate the initial instructions file from VS Code’s Chat menu. **Note:** instruction files do **not** affect inline code completions. ([Visual Studio Code][3])
* **GitHub.com (Chat / coding agent / code review):** Repo‑wide instructions are used broadly; path‑specific instructions are supported for the **coding agent** and **code review** on GitHub.com. ([GitHub Docs][1])
* **Visual Studio:** Uses the repo‑wide `.github/copilot-instructions.md` (enable “Use instruction files” in settings). ([Microsoft Learn][5])
* **JetBrains:** Uses a repo‑wide `.github/copilot-instructions.md` (and can have a local global file); path‑specific support varies. ([GitHub Docs][1])

---

## How to verify it’s working

* In Copilot Chat, open a file under `APIs/…` and ask “summarize the controller conventions.” In the **References** for the reply you should see your `.github/copilot-instructions.md` and the matching `*.instructions.md`. ([GitHub Docs][1])
* For **code review** on GitHub, enable “Use custom instructions when reviewing pull requests” in **Repo → Settings → Copilot → Code review**. ([GitHub Docs][1])

---

## Optional: add richer background docs

If you want the agent/chat to **read broader documentation** (architecture, ADRs, UI design system, API style guide), keep those as Markdown in your repo and link to them from your instruction files. For larger, cross‑repo context you can organize it with **Copilot Spaces** (GitHub is replacing knowledge bases with Spaces). ([GitHub Docs][6])

---

## Copy‑paste templates (ready to drop in)

> Replace bullets with your real standards—these are just safe defaults.

**`.github/copilot-instructions.md`**

```markdown
# Global rules
- Use TypeScript everywhere; keep strict mode on.
- Follow ESLint and Prettier configs in the repo; fix before commit.
- Write unit tests for new code and for bug fixes.
- Keep functions small; prefer composition over inheritance.
- Never include secrets or PII in logs, tests, or docs.
```

**`.github/instructions/apis-controllers.instructions.md`**

```markdown
---
applyTo: "APIs/**/src/**/*.controller.ts"
---
# Controllers
- Only orchestrate; delegate to services.
- Input: DTO + validation; Output: DTO (no entities).
- Translate domain errors to HTTP codes consistently.
```

**`.github/instructions/uis-angular.instructions.md`**

```markdown
---
applyTo: "UIs/**/src/**/*.ts,UIs/**/src/**/*.html,UIs/**/src/**/*.scss"
---
# Angular UI
- Standalone components; keep them lean and presentational.
- Services hold logic & side-effects; use RxJS for state.
- Tests: prefer Angular TestBed for components; no DOM snapshots.
```

---

## Summary

1. Create **`.github/copilot-instructions.md`** for universal rules.
2. Add **path‑specific `*.instructions.md`** in `.github/instructions/` with `applyTo` globs that target **APIs/** (NestJS), **UIs/** (Angular), and your **test files**. Copilot will automatically use the right set based on the files it’s working on. ([GitHub Docs][1])
3. (Optional) Add **prompt files** in `.github/prompts/` for one‑click scaffolds. ([GitHub Docs][4])
4. Verify in Chat **References** and enable **Code review → Use custom instructions** on GitHub if desired. ([GitHub Docs][1])

If you want, tell me your exact NestJS/Angular rules (controller/service/repo patterns, testing stack, naming) and I’ll drop them into these files with the correct `applyTo` globs.

[1]: https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot "Adding repository custom instructions for GitHub Copilot - GitHub Docs"
[2]: https://docs.github.com/en/copilot/tutorials/customization-library/custom-instructions/your-first-custom-instructions "Your first custom instructions - GitHub Docs"
[3]: https://code.visualstudio.com/docs/copilot/customization/custom-instructions "Use custom instructions in VS Code"
[4]: https://docs.github.com/en/copilot/tutorials/customization-library/prompt-files/your-first-prompt-file "Your first prompt file - GitHub Docs"
[5]: https://learn.microsoft.com/en-us/visualstudio/ide/copilot-chat-context?view=vs-2022&utm_source=chatgpt.com "Customize chat responses - Visual Studio (Windows)"
[6]: https://docs.github.com/en/copilot/using-github-copilot/copilot-spaces/about-organizing-and-sharing-context-with-copilot-spaces "About GitHub Copilot Spaces - GitHub Docs"