klod68/gen-copilot-instructions

---

name: gen-copilot-instructions description: "Bootstrap a copilot-instructions.md for any repository by discovering the project structure, validating every command, and embedding universal architectural principles. Use this for foreign repos or non-.NET projects. For your own .NET solutions, use New-CopilotContext.ps1 instead. Invoke when the user says: create copilot instructions, bootstrap instructions file, add copilot-instructions.md, generate agent instructions for this repo, set up AI coding guidelines. Domain: DevOps, AI Context. Level: Intermediate."

Generate a .github/copilot-instructions.md for this repository.

The output combines project-specific operational guidance (discovered from the repository) with universal architectural principles (defined below and always included verbatim). Both parts are required — do not omit either.

Success criteria: After reading the generated file, an agent should be able to:

1. Understand what the project does in 30 seconds
2. Build successfully on first attempt
3. Run tests without debugging command issues
4. Know where to make changes without searching the codebase
5. Generate code that satisfies all architectural rules without being told per-task

---

Phase 1 — Project Discovery

Step 1: Read documentation first (priority order)

• [ ] README.md — purpose, setup, build commands
• [ ] CONTRIBUTING.md — workflow, validation steps
• [ ] docs/ — architecture, conventions
• [ ] CHANGELOG.md — recent major changes

Step 2: Identify the build system

Locate and extract exact commands from whichever applies:

• *.csproj / *.sln — .NET
• package.json — Node.js
• requirements.txt / pyproject.toml — Python
• pom.xml / build.gradle — Java/Kotlin
• Cargo.toml — Rust
• go.mod — Go
• Gemfile — Ruby
• Makefile / scripts/ / build/ / tools/

Step 3: Extract CI/CD commands

Read the exact commands the pipeline runs — these are the ground truth for what "passing" means:

• .github/workflows/*.yml
• azure-pipelines.yml
• .circleci/config.yml
• .gitlab-ci.yml
• Jenkinsfile

Step 4: Note configuration files

• .eslintrc*, .prettierrc*, tsconfig.json, .editorconfig
• Dockerfile, docker-compose.yml
• .nvmrc, .python-version, .ruby-version

Step 5: Map the project structure

• Root directory contents
• Main source directories (src/, lib/, app/)
• Test directories (test/, tests/, __tests__/, spec/)
• Main entry points (main.*, index.*, Program.*)

---

Phase 2 — Validate Every Command

Run each command before documenting it. Start from a clean state:

git clean -fdx

Mark each result:

| Symbol | Meaning | |---|---| | ✅ | Succeeds | | ❌ | Fails — document error + workaround | | ⚠️ | Gotcha / non-obvious prerequisite | | ⏱️ | Slow (>30 s) — note expected duration | | 🔄 | Order-dependent |

Test these scenarios (not edge cases — these are the common failure modes):

1. Fresh clone
2. After a code change
3. After switching branches
4. After pulling updates

---

Phase 3 — Check for Special Considerations

Document any of the following if present:

• [ ] Monorepo — multiple packages with separate build steps
• [ ] Generated code — must build before editing
• [ ] Database migrations or seed data
• [ ] Required environment variables (document names, never values)
• [ ] External services required at runtime (Docker, databases, message queues)
• [ ] Platform-specific requirements (macOS / Linux / Windows)
• [ ] Pre-commit hooks
• [ ] Code generation tools (protobuf, GraphQL, OpenAPI)

---

Phase 4 — Generate the File

Use the output template below. Translate the architectural principles to match the project's language and idioms. Do not omit, summarize, or move any principle section to a separate document.

Writing style:

• Imperative: "Run X", "Never Y", "Always Z" — no passive voice
• Exact commands with version numbers, not "run the tests"
• Bullets and code blocks — no prose paragraphs
• Document known failure modes and workarounds explicitly

---

Output Template

# `{ProjectName}` — Copilot Instructions

## What This Is
{One sentence. What does this project do and why does it exist?}

## Prerequisites
- {Runtime/SDK name} {exact version}
- {Tool} {exact version}
- ⚠️ {Any non-obvious prerequisite}

## Setup & Build
\`\`\`bash
# Setup
{command}

# Build
{command}

# Test
{command}

# Lint / Format
{command}
\`\`\`

| Command | Status | Notes |
|---|---|---|
| `{command}` | ✅ / ❌ / ⚠️ | {notes} |

## Project Structure
| Path | Purpose |
|---|---|
| `{path}` | {purpose} |

## Where to Make Changes
- {feature or behavior} → `{path}`
- {feature or behavior} → `{path}`

## Common Pitfalls
- ⚠️ {Pitfall}: {How to avoid}
- 🔄 {Order requirement}: {Why}

## CI Checks — Replicate Locally
\`\`\`bash
{exact commands CI runs}
\`\`\`

---

## Architectural Rules

### Class & Interface Design
- Depend on abstractions. Never depend on concrete implementations across module or library boundaries.
- A class has exactly one reason to change. If it has more, split it.
- Extend behavior by adding new implementations, not by modifying existing ones.
- Subtypes must be substitutable for their base type. Consumers never check the concrete type.
- Interfaces are small and role-focused. An interface with many unrelated methods must be split.
- Concrete classes are internal details. Public API surface is interfaces, abstract types, and stateless helpers.

### Dependency & Instantiation
- Never use `new ConcreteType()` to instantiate a type from another module or library. Use factories or DI.
- Dependencies enter via constructor injection as abstractions.
- DI registrations for external types use factory delegates, not hard-coded constructors.
- Each module/package exposes one registration entry point and manages its own internal wiring.

### Function Shape (CQS)
- **Commands** — return void/Task, use imperative verbs (`Save`, `Delete`, `Execute`). No data returned.
- **Queries** — return a result, use `Get`/`Find`/`Load`. No side effects.
- **Validators** — return bool, use `Is`/`Has`/`Can`. No side effects.
- A function that does two things must be split into two functions.

### Preconditions & Contracts
- Every public function validates all inputs at entry. Violations throw immediately with a clear error.
- Assert postconditions when the result contract is non-obvious.

### Async & Concurrency
- All I/O is async. Never block a thread waiting for async results (no `.Result`, `.Wait()`).
- Do not capture sync context in library code (`ConfigureAwait(false)` or equivalent).
- Always accept and propagate cancellation tokens. Never substitute an empty token for a provided one.
- Never fire-and-forget (`async void` or unmanaged background tasks).

### Nullability & Absence
- Null must be explicit in all type signatures.
- Never return null for a collection. Return empty.
- Nullable suppression requires an inline comment.

### Error Handling
- Contract violations (programming errors): propagate immediately, do not catch.
- Infrastructure failures: catch at the boundary, enrich, wrap in a domain exception, propagate once.
- Never swallow exceptions silently.
- Use result types for expected domain outcomes; use exceptions for broken contracts. Never mix in the same return path.
- Wrap all infrastructure exceptions before they cross the public API. Preserve the original as inner cause.

### Observability
- Every significant operation emits: a trace span, a duration metric, and a structured log on failure.
- Use structured logging with templates. No string interpolation in log messages.
- Never include sensitive data in traces, metrics, or logs.

### Versioning
- MAJOR: any breaking API change. MINOR: new backward-compatible feature. PATCH: bug fix only.
- Deprecate before removing. Deprecated members survive at least one MINOR release.
- Every release has a CHANGELOG entry.

### Testing
- Unit tests mock all dependencies via abstractions.
- Name tests: `MethodOrUnit_Condition_ExpectedOutcome`.
- Every public method: one happy-path test + one test per guard clause.
- Integration tests use on-demand provisioned infrastructure. Never shared state.
- Integration tests run in a separate suite from unit tests.

### Common Anti-Patterns — Reject in Code Review

| Anti-Pattern | Fix |
|---|---|
| `new ConcreteType()` across module boundaries | Factory or DI |
| `switch`/`if-else` branching on type | Polymorphism |
| `is`/`instanceof` check on base type | Redesign |
| Empty `catch {}` | Re-throw, wrap, or log |
| Async without cancellation token | Add cancellation parameter |
| Blocking on async (`.Result`, `.Wait()`) | Await properly |
| Returning `null` for collection | Return empty collection |
| Command that returns data | Split into command + query |
| Interface with many unrelated methods | Split by role |
| Public concrete non-abstract class | Make `internal` or `abstract` |

---

## Instructions for AI Agents

Trust these instructions. Search the codebase only when:
1. These instructions are incomplete for the specific task.
2. You need the concrete signature of an existing internal method.

When generating code, verify it satisfies every rule in **Architectural Rules** before
emitting. If a user request conflicts with a rule, flag the conflict and propose a
compliant alternative.

---

Final Checklist Before Emitting

• [ ] All documented commands tested and verified working
• [ ] Prerequisites include exact version numbers
• [ ] Build → Test → Lint sequence documented
• [ ] CI checks documented with local replication commands
• [ ] Common errors and workarounds included
• [ ] Project structure explains where to make changes
• [ ] Architectural Rules section is present and complete
• [ ] Anti-patterns table is present
• [ ] Formatted for scanning (bullets, code blocks, headers — no prose paragraphs)
• [ ] "Instructions for AI Agents" section is present