klod68/gen-verbose-copilot-instructions

---

name: gen-verbose-copilot-instructions description: "Generate a comprehensive root instruction file for any repository by discovering the project structure, validating every command, and embedding universal architectural principles. Verbose variant with full output template. Invoke when the user says: generate verbose instructions, create comprehensive copilot instructions, bootstrap root instruction file, full instructions template, generate CLAUDE.md. Domain: DevOps, AI Context. Level: Intermediate."

Task: Generate a Root Instruction File for This Repository

Generate a root instruction file (e.g., .github/copilot-instructions.md or CLAUDE.md) that enables coding agents to work efficiently in this repository without extensive exploration. The output combines project-specific operational guidance (discovered from the repository) with universal architectural principles (defined in this prompt and always included verbatim).

---

Objectives

Primary Goals:

• Prevent PR rejections from build/test/validation failures
• Eliminate command trial-and-error
• Enforce architectural standards consistently across all contributors, human and AI

Success Criteria: An agent should be able to:

1. Understand what the project does in 30 seconds
2. Set up and build successfully on first attempt
3. Run tests without debugging command issues
4. Know where to make changes without grep/find searches
5. Generate code that satisfies all architectural rules without being told per-task

---

Constraints

• Format: Markdown, optimized for scanning
• Language: Imperative. "Do X", "Never Y", "Always Z". No passive voice, no paragraphs of explanation.
• Scope: Two parts — (1) project-specific discovery, (2) universal principles. Both are required.

---

Part 1: Project Discovery

Phase 1: Critical Path Discovery (Priority Order)

1. Documentation Files

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

2. Build System — Identify and extract exact commands from:

   • [ ] package.json / package-lock.json (Node.js)
   • [ ] requirements.txt / pyproject.toml / setup.py (Python)
   • [ ] pom.xml / build.gradle (Java/Kotlin)
   • [ ] *.csproj / *.sln (C#/.NET)
   • [ ] Cargo.toml (Rust)
   • [ ] go.mod (Go)
   • [ ] Gemfile (Ruby)
   • [ ] Makefile / scripts in scripts/, build/, tools/

3. CI/CD & Validation — Extract the exact commands CI runs:

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

4. Configuration Files

   • [ ] .eslintrc*, .prettierrc*, tsconfig.json
   • [ ] .pylintrc, setup.cfg, pyproject.toml
   • [ ] .editorconfig
   • [ ] Dockerfile, docker-compose.yml
   • [ ] .nvmrc, .python-version, .ruby-version

5. Project Structure

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

Phase 2: Validate Every Command You Document

Run each command before documenting it:

git clean -fdx          # start from clean state
[run each command in order and confirm it succeeds]

Mark results as:

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

Test scenarios (focus on these, not edge cases):

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

Phase 3: Special Considerations

Check for and document if present:

• [ ] Monorepo (multiple packages with separate build steps)
• [ ] Generated code (must build before editing)
• [ ] Database migrations or seed data
• [ ] Required environment variables or secrets (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)

---

Part 2: Universal Architectural Principles

These sections are mandatory in every generated file, for every project, regardless of language or stack. Translate the rules below to match the project's language and idioms. Do not omit, summarize, or move them to a separate document.

Class & Interface Design

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

Dependency & Instantiation

• Never use new ConcreteType() to instantiate a type from another module or library. Use factories or dependency injection.
• High-level modules receive dependencies via constructor injection as abstractions. They never instantiate their own dependencies.
• When registering external types in a DI container, use factory delegates — not hard-coded constructors.
• A package or module is self-sufficient: it exposes a single registration entry point and manages its own internal wiring. Consumers provide configuration; they do not wire internals.

Function Shape (Command-Query Separation)

• Every function belongs to exactly one category:
  • Command — produces a side-effect, returns nothing (void/Task).
  • Query — retrieves data, produces no side-effect, returns a result.
  • Validator — evaluates a condition, produces no side-effect, returns bool.
• A function that both mutates state and returns data must be decomposed into two functions. Document inline if an atomic exception is unavoidable.
• Naming must telegraph category: commands use imperative verbs (Save, Delete, Execute); queries use Get, Find, Load; validators use Is, Has, Can.

Preconditions & Contracts

• Every public function opens with explicit precondition checks for all inputs. Violations fail immediately with a clear error. No silent defaults, no partial execution.
• Postconditions are asserted when the result contract is non-obvious.
• A function with no preconditions is suspicious — verify it truly accepts any input.

Async & Concurrency

• All I/O operations must be async. Never block a thread to wait for a result (no .Result, .Wait(), or equivalent blocking calls on async operations).
• Library code must not capture synchronization context. Always use the language-appropriate opt-out (e.g., ConfigureAwait(false) in C#).
• Every async public function accepts a cancellation token and propagates it to all internal async calls. Never substitute a default/empty token when one was provided by the caller.
• Never use async void (or equivalent fire-and-forget that loses exceptions). Fire-and-forget must be explicitly managed with structured concurrency.

Nullability & Absence

• Null must be explicit in all type signatures. A non-nullable type means the absence of a value is a contract violation; a nullable type means absence is a valid, handled outcome.
• Never return null for a collection type. Return an empty collection.
• Nullable suppression operators (e.g., ! in C#, ! assertion in TypeScript) require an inline comment explaining why.

Error Handling

• Classify errors into two categories:
  • Contract violations (programming errors): fail immediately, propagate without catching.
  • Infrastructure failures (transient or permanent I/O errors): catch at the boundary, enrich with context, wrap in a domain exception type, propagate once.
• Never swallow exceptions silently. Every catch block either re-throws, wraps, or logs at a severity that makes the failure visible.
• Do not catch the base Exception type except at a single top-level resilience boundary.
• Use result types (Result<T>, OperationResult, etc.) for expected domain-level outcomes (not found, validation failure). Use exceptions for broken contracts and infrastructure failures. Never mix both patterns in the same return path.
• Wrap infrastructure exceptions in a domain exception type before they cross the public API surface. Always preserve the original exception as the inner cause.

Observability

• Every significant operation emits:
  1. A trace span with the operation name and relevant context tags.
  2. A duration metric.
  3. A structured log entry on failure (error type, operation name, relevant identifiers).
• Use structured logging with message templates. Never use string interpolation to build log messages.
• Never include sensitive data (passwords, tokens, PII, connection strings) in traces, metrics, or log messages.
• Instrumentation must be compatible with the ecosystem's standard observability protocol (e.g., OpenTelemetry). Do not hard-code exporter choices inside library code.

Versioning & Breaking Changes

• Follow Semantic Versioning (MAJOR.MINOR.PATCH):
  • MAJOR: any breaking change to the public API (removing, renaming, or changing the signature of a public member; adding a required member to an interface).
  • MINOR: new backward-compatible functionality.
  • PATCH: backward-compatible bug fixes only.
• Deprecate before removing. Mark deprecated members with the language-appropriate deprecation annotation and a message pointing to the replacement. Deprecated members survive at least one MINOR release before removal triggers a MAJOR bump.
• Every release requires a CHANGELOG entry categorized as Breaking Changes, New Features, or Bug Fixes.

Testing

• Unit tests mock all external dependencies through abstractions. A class that cannot be unit-tested in isolation has a design violation — fix the design, not the test.
• Test naming: MethodOrUnit_Condition_ExpectedOutcome.
• Every public function requires at minimum: one happy-path test and one test per precondition violation.
• Integration tests run against real infrastructure provisioned on-demand (e.g., containers). They never depend on shared or persistent external state.
• Integration tests are isolated from unit test runs (separate suite, separate CI stage).
• Contract tests verify that every implementation of a shared interface satisfies the same behavioral specification.
• Coverage is a floor, not a target. Meaningful assertions matter more than line counts.

Common Anti-Patterns — Reject in Code Review

| Anti-Pattern | Rule Violated | Required Fix | |---|---|---| | new ConcreteType() across module boundaries | DIP | Use factory or DI | | switch/if-else branching on type | OCP | Replace with polymorphism | | is / instanceof / typeof checks on base types | LSP | Consumer must not inspect concrete type | | Empty catch {} block | Error Handling | Re-throw, wrap, or log | | Async method without cancellation token | Async Policy | Add CancellationToken parameter | | Blocking call on async operation (.Result, .Wait()) | Async Policy | Await properly | | Returning null for a collection | Nullability | Return empty collection | | Command method that returns data | CQS | Decompose into command + query | | Interface with 10+ unrelated methods | ISP | Split by role | | Public concrete class (non-abstract, non-helper) | Encapsulation | Make internal or abstract |

---

Output Structure

Use this template. Fill Part 1 sections from discovery. Include Part 2 sections verbatim (translated to the project's language/idioms).

# [Project Name] — Coding Agent Instructions

## Repository Overview

[2–4 sentences: what the project does, who uses it.]

**Tech Stack:**
- Language: [e.g., TypeScript 5.x, C# 12, Python 3.12]
- Framework: [e.g., Express, ASP.NET Core, FastAPI]
- Runtime: [e.g., Node.js 20.x, .NET 8, Python 3.12+]
- Project Type: [e.g., REST API, NuGet library, CLI tool]

---

## Setup & Build

### Prerequisites
- [Tool] [version]+ (check with `[command]`)

### First-Time Setup
```bash
[exact commands]

Expected time: [~X minutes]

Build

[exact command]

⚠️ [Any critical notes]

Common issues:

Running Tests

# Unit tests
[exact command]

# Integration tests (requires [prerequisite])
[exact command]

# Specific test
[exact command with example]

Expected time: [~X seconds/minutes]

Code Quality

# Lint
[exact command]

# Format
[exact command]

# Type check (if applicable)
[exact command]

Replicate CI Locally

[exact sequence CI runs]

All checks must pass before opening a PR.

---

Project Structure

[repo-root]/
├── [dir]/    - [purpose]
├── [dir]/    - [purpose]
└── [dir]/    - [purpose]

Key locations:

• Entry point: [path]
• Tests: [path]
• Configuration: [path]
• Build artifacts: [path] — generated, never edit directly

---

CI/CD & Validation

On Pull Request:

1. [workflow] — Runs: [what it does]
2. [workflow] — Runs: [what it does]

Pre-commit hooks: [what runs automatically, or "None"]

---

Architectural Rules — Enforce in All Generated Code

Class & Interface Design

• Depend on abstractions. Public API surface = interfaces, abstract types, stateless helpers. Concrete types are internal.
• One class, one reason to change. Split anything with mixed responsibilities.
• Extend by adding implementations, not by modifying existing code.
• Subtypes must be interchangeable with their base type. Never check the concrete type at runtime.
• Interfaces are small and role-focused. Split interfaces that serve more than one role.

Dependency & Instantiation

• Never instantiate types from another module with new. 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.
• Assert postconditions when the result contract is non-obvious.

Async & Concurrency

• All I/O is async. Never block a thread waiting for async results.
• Do not capture sync context in library code (use ConfigureAwait(false) or equivalent).
• Always accept and propagate cancellation tokens. Never substitute an empty token for a provided one.
• Never fire-and-forget (no 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 (containers). 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 — consumer must not inspect type | | 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 |

---

Common Pitfalls

[Populate from discovery — project-specific gotchas, ordering requirements, environment issues]

• ⚠️ [Pitfall]: [How to avoid]
• ⚠️ [Pitfall]: [How to avoid]

---

Quick Reference

# Setup
[command]

# Build
[command]

# Test
[command]

# Lint / Format
[command]

Key paths:

• Config: [path]
• Entry: [path]
• Tests: [path]

---

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.

---

## Writing Style Rules (Apply to All Generated Content)

**DO:**
- Imperative voice: "Run X", "Never Y", "Always Z"
- Exact commands: `` `dotnet test` `` not "run the tests"
- Version numbers: "Node.js 20.x" not "recent Node.js"
- Timing for slow operations: "~5 minutes"
- Highlight gotchas: "⚠️ Must build before testing"

**DON'T:**
- Passive voice: "Dependencies should be installed"
- Vague instructions: "Set up the environment"
- Assumed knowledge: "Configure as usual"
- Paragraphs: Use bullets and code blocks
- Omit error cases: Document known failure modes

---

## Edge Cases

**No build step:**
```markdown
## Setup & Build
No build step required. Files execute directly.

No tests:

## Testing
⚠️ No automated test suite. Manual validation: [describe steps]

Monorepo:

## Repository Structure
Monorepo. Packages:
- `packages/[name]/` — [purpose] — build with `[command]`
- `packages/[name]/` — [purpose] — build with `[command]`

Missing information: Document the gap explicitly rather than guessing.

⚠️ Build command not found in repository. Check with the team before proceeding.

---

Visual Indicators (Use Consistently)

• ✅ Working / Recommended
• ❌ Broken / Do not use
• ⚠️ Warning / Gotcha
• 🔧 Workaround needed
• ⏱️ Slow operation (>30 seconds)
• 🔄 Must run in specific order

---

Final Checklist Before Emitting Output

• [ ] All documented commands tested and verified working
• [ ] Prerequisites include version numbers
• [ ] Build → Test → Lint sequence documented
• [ ] CI checks documented with local replication command
• [ ] 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)
• [ ] Final "Instructions for AI Agents" section present