Agentic dco fix 3

.github/INSTRUCTION_AUTHORING.md

@@ -0,0 +1,133 @@
+---
+description: "Standards for creating and maintaining .instructions.md files"
+applyTo: "**/*.instructions.md"
+tags: ["authoring", "standards", "instructions", "documentation"]
+---
+
+# Instruction File Authoring Standards
+
+When creating or updating any Copilot instruction Markdown file (`.instructions.md`), follow these rules to keep guidance durable, easy to review, and maintainable.
+
+## Purpose
+
+Instruction files define scoped AI guidance for specific file types or code areas. They must be predictable and machine-readable.
+
+## General Authoring Rules
+
+- Prefer precise, testable directives over vague guidance.
+- Avoid overlapping or conflicting instructions across files.
+- Keep content reusable and not tied to one temporary task.
+- Use imperative language ("Use", "Prefer", "Do not", "Validate").
+- If a rule is scoped to a subset of files, use a path-specific `.instructions.md` file rather than adding it to the global file.
+- Do not restate general rules in multiple files unless required for clarity.
+- When unsure, produce fewer, clearer rules.
+
+## Required Format
+
+All `.instructions.md` files must begin with YAML frontmatter and follow this section order:
+
+```yaml
+---
+description: "Short, concrete summary of what the file governs"
+applyTo: "src/**/*.cs"
+tags: ["tag1", "tag2"]
+---
+
+# Purpose
+
+[One paragraph explaining why this guidance exists]
+
+## Scope
+
+[What files and scenarios this applies to]
+
+## Required Rules
+
+[MUST / MUST NOT directives, phrased imperatively]
+
+## Preferred Patterns
+
+[SHOULD directives, repeated patterns, best practices]
+
+## Validation
+
+[Concrete checks: build, test, lint, docs validation]
+
+## Examples
+
+[Optional: "Preferred" and "Avoid" patterns]
+```
+
+## Frontmatter Rules
+
+- `description` must be one sentence and concrete.
+- `applyTo` must use explicit glob patterns with the narrowest safe scope. Examples:
+  - `src/**/*.cs` — all C# files in source
+  - `tests/**/*.cs` — all test files
+  - `**/Program.cs` — program entry points
+- `applyTo` must **not** be `**` unless the file is intentionally repository-wide.
+- If multiple globs are needed, keep them explicit and readable, separated by semicolons or as separate lines.
+- `tags` should reflect the instruction's domain (e.g., `["validation", "dependency-injection", "testing"]`).
+
+## Content Rules
+
+- **Required rules** must be phrased as MUST / MUST NOT / SHOULD where possible.
+- **Validation section** must include concrete checks (build, test, lint, docs validation) when applicable.
+- **Examples** must show "preferred" and "avoid" patterns when useful.
+- Do not include secrets, tokens, or environment-specific sensitive values.
+- Keep sections short and scannable; each section should fit on one screen without scrolling.
+
+## Conflict Resolution
+
+When multiple instruction files might apply to the same file:
+
+- Repository-wide instructions define defaults.
+- Path-specific instruction files define narrower, stronger rules for matching files.
+- If a new file would conflict with an existing instruction file, revise the narrow file instead of creating duplicate policy.
+- Always document the relationship between overlapping instruction files in cross-references.
+
+## Cross-Referencing
+
+Link between instruction files using relative paths or workspace absolute paths:
+
+- Relative: `../other-instruction.md`
+- Absolute: `/.github/instructions/host-setup.instructions.md`
+- Always verify links work before committing.
+
+## Example Structure
+
+A well-formed instruction file:
+
+```yaml
+---
+description: "Controller conventions for CoreEx API hosts"
+applyTo: "**/Controllers/**/*.cs"
+tags: ["controllers", "api", "dependency-injection"]
+---
+
+# Purpose
+
+Controllers define HTTP endpoints for CoreEx API hosts. This guidance ensures consistent routing, dependency injection, and use of CoreEx WebApi helpers.
+
+## Scope
+
+Applies to all `Controllers/` directories in API projects (`.Api` projects).
+
+## Required Rules
+
+- MUST inherit from `WebApiControllerBase<TRequest, TResponse>` or `WebApiControllerBase`.
+- MUST use `[Route("api/v1/...")]` and follow REST conventions.
+- MUST NOT inject `IUnitOfWork` directly; receive it only through application service dependency.
+
+## Preferred Patterns
+
+- Prefer `PostAsync()`, `PutAsync()`, `PatchAsync()` from `WebApi` helpers over manual response building.
+- Prefer explicit dependency injection over service locator patterns.
+- Prefer PATCH with `application/merge-patch+json` for partial updates.
+
+## Validation
+
+- Build the project: `dotnet build`
+- Run tests: `dotnet test`
+- Check inheritance with: `grep "class.*Controller" Controllers/*.cs`
+```

.github/SKILL_AUTHORING.md

@@ -0,0 +1,152 @@
+---
+description: "Standards for creating and maintaining SKILL.md files"
+applyTo: "**/.github/skills/**/SKILL.md"
+tags: ["authoring", "standards", "skills", "documentation"]
+---
+
+# Skill File Authoring Standards
+
+When creating or updating any skill (SKILL.md file), follow this organization pattern to keep the main file lean and context-efficient.
+
+## Purpose
+
+Skill files guide AI agents through complex, multi-step tasks. They must be discoverable, brief, and provide clear pointers to detailed workflows rather than embedding all content inline.
+
+## Skill Directory Structure
+
+```
+skills/{skill-name}/
+  SKILL.md                    # Main entry point (lean, <300 lines)
+  references/
+    workflow.md               # Detailed step-by-step workflows
+    checklists.md            # Completion gates, validation criteria
+    patterns.md              # Code patterns, templates, conventions
+    troubleshooting.md       # Known issues and solutions
+  assets/
+    templates/               # Code templates, boilerplate files
+    examples/                # Real working examples from the repo
+```
+
+Each file serves one purpose. Keep files focused and scannable.
+
+## SKILL.md Content Rules
+
+The main SKILL.md must include:
+
+1. **YAML frontmatter** with `name`, `description`, `argument-hint`, `tags`
+2. **One-sentence purpose statement** — what the skill does and when to use it
+3. **"When to Use" section** — bullet points, not prose; concrete triggers
+4. **"When Not to Use" section** — prevents misuse and clarifies boundaries
+5. **Quick reference** — CLI commands, key steps, or summary table (if applicable)
+6. **Pointer to detailed workflows** — "For step-by-step guidance, see `references/workflow.md`"
+7. **Key References** — links to relevant instructions, samples, or external docs
+
+**Maximum: 300 lines** including frontmatter. If you exceed this, move content to `references/`.
+
+## references/ Subdirectory
+
+Detailed, procedural content lives in `references/`:
+
+- **workflow.md** — full step-by-step phases, sub-steps, decision trees; 100–200 lines
+- **checklists.md** — completion gates, validation steps, sign-off criteria; one page
+- **patterns.md** — recurring code patterns, naming conventions, architectural decisions; reference material
+- **troubleshooting.md** — known issues, debugging strategies, error messages and fixes; searchable format
+
+Each file stays focused on one concern. No file should exceed what is readable in one screen scroll without getting lost.
+
+## assets/ Subdirectory
+
+Reusable templates and examples:
+
+- **assets/templates/** — boilerplate code, project structures (copy-and-fill files)
+- **assets/examples/** — concrete working examples from the repo (links only, no duplicates)
+
+**Important**: Never maintain duplicate copies of sample code. Always link to the canonical source in `samples/` or other repository locations.
+
+## Cross-Referencing
+
+When skills reference each other, instructions, or samples:
+
+- **Relative paths**: `../other-skill/references/...` (for other skills)
+- **Absolute workspace paths**: `/.github/instructions/host-setup.instructions.md`, `/samples/src/Contoso.Products.Api/Program.cs`
+- Always verify links work before committing
+- Prefer workspace-relative links for durability
+
+## Frontmatter Requirements
+
+All SKILL.md files must include:
+
+```yaml
+---
+name: skill-id
+description: "Concise description of when and why to use this skill"
+argument-hint: "What user should provide, e.g. 'Optional: domain name and entities'"
+tags: ["tag1", "tag2", "tag3"]
+---
+```
+
+**Tag guidance**: Reflect the skill's domain and primary use cases. Examples:
+- `["scaffolding", "microservice", "code-generation"]`
+- `["orchestration", "cli", "distributed-apps"]`
+- `["retrofit", "integration", "messaging"]`
+
+## Lean SKILL.md Example
+
+```yaml
+---
+name: generate-domain
+description: "Scaffold a new CoreEx domain across all layers following framework conventions"
+argument-hint: "Domain name, entity fields, business rules (optional)"
+tags: ["scaffolding", "domain", "code-generation"]
+---
+
+# Generate Domain
+
+Guides you through creating a new CoreEx domain from scratch. Asks about entity shape, validation, messaging needs, and generates code tailored to your domain model.
+
+## When to Use
+
+- Creating a new bounded context or microservice
+- Entity has custom fields, business rules, or complex validation
+- You want the agent to reason about conventions and event naming
+- Scaffolding Products, Orders, Shopping, or similar sample domains
+
+## When Not to Use
+
+- Entity fits a standard template shape — use `/scaffold-domain-from-templates` instead
+- Domain already exists — use `/add-capability` to retrofit messaging/integration
+- You need just one file (a contract or service) — manually create it
+
+## Workflow Overview
+
+1. **Load Context** — examine existing domains and conventions
+2. **Gather Inputs** — domain name, entity fields, validation rules, events
+3. **Contracts** — define DTOs with source-generation markers
+4. **Application Services** — validation, unit-of-work patterns, event publishing
+5. **Infrastructure** — repositories, mappers, database access
+6. **API Host** — controllers, registration, middleware
+7. **Database** — migrations, schema, outbox tables
+8. **Tests** — integration and API test scaffolding
+
+For detailed step-by-step guidance, see [`references/workflow.md`](references/workflow.md).
+
+## Key References
+
+- [Application Services Instructions](/.github/instructions/application-services.instructions.md)
+- [Contracts Instructions](/.github/instructions/contracts.instructions.md)
+- [Host Setup Instructions](/.github/instructions/host-setup.instructions.md)
+- [Sample Domains](./samples/src/Contoso.Products/)
+- [Roslyn Source Generation](./docs/capabilities.md)
+```
+
+## Quality Gates
+
+Before completing a skill:
+
+- [ ] SKILL.md is <300 lines (excluding examples)
+- [ ] All `references/` files exist and are linked
+- [ ] All links (relative and absolute) are verified
+- [ ] YAML frontmatter is valid
+- [ ] No inline workflows or checklists in main SKILL.md
+- [ ] Cross-references to instructions are correct
+- [ ] Example links point to real, canonical code locations

.github/agents/coreex-expert.agent.md

@@ -0,0 +1,47 @@
+---
+name: CoreEx Expert
+description: "Use when you need to explain, understand, or decide how CoreEx works. Triggers: explain CoreEx, how does CoreEx, which pattern, which capability, which shape, plan a feature, review a design, compare samples, architecture guidance, coding patterns, layering, host setup, validation, repository conventions, eventing, outbox relay, subscriber design, sample-aligned decisions."
+tools: [read, search]
+user-invocable: true
+argument-hint: Ask for CoreEx pattern guidance, architecture decisions, or sample-aligned implementation advice.
+---
+You are the CoreEx Expert for this repository.
+
+Your mission:
+- Provide authoritative, repo-grounded guidance on CoreEx architecture, patterns, and practices.
+- Prefer CoreEx-native primitives and conventions over generic .NET advice.
+- Keep recommendations aligned with existing layering and sample implementations.
+
+Primary sources of truth:
+- .github/copilot-instructions.md
+- docs/agent-interaction-guide.md
+- docs/agent-prompt-recipes.md
+- .github/instructions/api-controllers.instructions.md
+- .github/instructions/application-services.instructions.md
+- .github/instructions/contracts.instructions.md
+- .github/instructions/repositories.instructions.md
+- .github/instructions/event-subscribers.instructions.md
+- .github/instructions/host-setup.instructions.md
+- .github/instructions/tests.instructions.md
+- .github/instructions/validators.instructions.md
+
+Operating rules:
+- Always inspect current code before recommending changes.
+- Give sample-backed guidance where possible.
+- Favor smallest safe change and preserve existing structure.
+- Separate explanation, plan, and implementation guidance clearly.
+- For mutable entities, call out ETag, changelog, validation, and idempotency implications where relevant.
+- For messaging, explicitly distinguish API-only, API plus relay, API plus subscribe, and orchestration shapes.
+
+Decision routing:
+- If request is greenfield domain scaffolding, advise using /generate-domain.
+- If request is deterministic template scaffolding, advise using /scaffold-domain-from-templates.
+- If request is retrofit capability on an existing domain, advise using /add-capability.
+- If request is repo mapping or onboarding documentation, advise using acquire-codebase-knowledge.
+
+Response format:
+1. Recommendation.
+2. Why this fits CoreEx.
+3. Evidence from repo files.
+4. Risks and tradeoffs.
+5. Minimal next steps.