# MCAF Adoption Alongside dotnet-skills

Use this reference when a repository wants to adopt the Managed Code Coding AI Framework and also uses the dotnet-skills catalog for `.NET` implementation work instead of keeping AI workflow rules scattered across chat threads, tribal knowledge, or ad hoc prompts.

## Canonical Sources

- Concepts: `https://mcaf.managed-code.com/`
- Tutorial: `https://mcaf.managed-code.com/tutorial`
- Skills catalog: `https://mcaf.managed-code.com/skills`
- Source repository: `https://github.com/managedcode/MCAF`

The concepts page defines the framework. The tutorial is the canonical bootstrap flow.

## What MCAF Adds To A Repository

From the official concepts and tutorial pages, the core MCAF shape is:

1. durable engineering context stays in the repository
2. agents work from `AGENTS.md`, repo docs, and installed skills
3. verification is enforced through tests and analyzers
4. guidance stays small, explicit, versioned, and repo-native

For repositories that also contain `.NET` code, the official tutorial makes one boundary explicit:

- install MCAF governance skills from the MCAF catalog
- install implementation-focused `dotnet-*` skills from `https://skills.managed-code.com/`

That means MCAF is the framework layer, while this repository remains the `.NET` execution layer.

The local `dotnet-skills` catalog now mirrors the net-new MCAF governance surfaces as installable `dotnet-mcaf-*` skills. Use the local mirrors first for the transferred surfaces, and fall back to the upstream MCAF catalog when a governance skill has not been mirrored here yet.

## Bootstrap Rules That Matter Alongside dotnet-skills

Use the tutorial as the single canonical install surface.

Required bootstrap artifacts:

- root `AGENTS.md` at the repo or solution root
- optional `CLAUDE.md` wrapper when the repo uses Claude Code
- local `dotnet-mcaf*` governance skills under the native agent skill directory
- `dotnet-*` implementation skills from this catalog when the repo contains `.NET` code

For multi-project solutions:

- keep one root `AGENTS.md`
- add one local `AGENTS.md` per project or module root when local rules differ
- local files may tighten root policy but must not silently weaken it

## Repo-Native Documentation Shape

The official MCAF concepts page recommends durable docs under:

- `docs/Architecture.md`
- `docs/Features/`
- `docs/ADR/`
- `docs/Testing/`
- `docs/Development/`
- `docs/Operations/`

For `.NET` teams, that means build and validation knowledge should not stay only in CI YAML or chat history. The repo should explicitly document:

- exact `dotnet build` commands
- exact `dotnet test` commands
- formatter and analyzer commands
- coverage commands and thresholds when used
- architecture and behavior that tests must prove

## Task Workflow Expectations

The official MCAF guidance expects non-trivial work to follow:

1. root-level `<slug>.brainstorm.md`
2. root-level `<slug>.plan.md`
3. implementation
4. validation against the repo-defined quality pass

Do not compress architecture choice, test strategy, and execution into one improvised edit cycle when the task is non-trivial.

## Verification Expectations

Official MCAF verification rules explicitly favor:

- TDD for new behavior and bug fixes
- user-visible or caller-visible scenario coverage
- integration and end-to-end checks when behavior crosses boundaries
- static analysis as part of done
- full relevant suites green before completion

For `.NET` repos this means “tests passed” is insufficient if the repo also requires:

- analyzers
- `dotnet format`
- coverage
- architecture tests
- security gates

## MCAF Skill Map That Usually Matters Alongside dotnet-skills

The local `managedcode/MCAF` catalog currently exposes 18 separate `mcaf-*` skills. In practice that means teams should route to a narrow governance skill, not cite "MCAF" generically.

Recommended split:

- use MCAF skills for governance, docs, planning, maintainability, testing policy, CI/CD policy, observability, security baseline, and delivery process
- use `dotnet-*` skills from this catalog for framework-specific implementation and validation

The most common `.NET` adoption map is in `references/skill-map.md`.

## Practical Routing For .NET Teams

When the ask is:

- "set up repo rules, AGENTS, docs, and delivery workflow" -> start with `dotnet-mcaf`
- "implement or fix actual ASP.NET/Orleans/EF/Agent Framework code" -> route from `dotnet-mcaf` into the narrowest `dotnet-*` skill
- "tighten verification and CI rules" -> combine `dotnet-mcaf` with the appropriate testing or quality skill
- "choose which local MCAF mirror should own governance work" -> route through the grouped map in `references/skill-map.md`

# Current MCAF Skill Map

This map is sourced from the current local `managedcode/MCAF` catalog under `skills/`. Use it when a `.NET` repository wants MCAF but the task is specific enough that "use MCAF" is too vague to be useful.

## Governance And Delivery Flow

| MCAF skill | Use it for |
|---|---|
| `mcaf-solution-governance` | root and local `AGENTS.md`, rule precedence, topology, maintainability-limit placement, and solution-wide agent policy |
| `mcaf-agile-delivery` | backlog quality, planning flow, ceremonies, and turning delivery feedback into durable process changes |
| `mcaf-source-control` | branch naming, merge strategy, commit hygiene, release-policy guardrails, and secrets-in-git discipline |
| `mcaf-human-review-planning` | large AI-generated changes that need a practical human review sequence instead of a flat file-by-file read |

## Local Mirrors In This Catalog

The following net-new MCAF surfaces are now mirrored locally in `dotnet-skills`:

| Canonical MCAF skill | Local mirror in this catalog |
|---|---|
| `mcaf-agile-delivery` | `dotnet-mcaf-agile-delivery` |
| `mcaf-devex` | `dotnet-mcaf-devex` |
| `mcaf-documentation` | `dotnet-mcaf-documentation` |
| `mcaf-feature-spec` | `dotnet-mcaf-feature-spec` |
| `mcaf-human-review-planning` | `dotnet-mcaf-human-review-planning` |
| `mcaf-ml-ai-delivery` | `dotnet-mcaf-ml-ai-delivery` |
| `mcaf-nfr` | `dotnet-mcaf-nfr` |
| `mcaf-source-control` | `dotnet-mcaf-source-control` |
| `mcaf-ui-ux` | `dotnet-mcaf-ui-ux` |

## Docs And Architecture

| MCAF skill | Use it for |
|---|---|
| `mcaf-architecture-overview` | creating or updating `docs/Architecture.md` as the global system map |
| `mcaf-feature-spec` | feature behavior specs under `docs/Features/` |
| `mcaf-adr-writing` | ADRs under `docs/ADR/` for technical decisions and trade-offs |
| `mcaf-documentation` | durable engineering docs structure, navigation, source-of-truth placement, and writing quality |
| `mcaf-nfr` | explicit non-functional requirements such as reliability, accessibility, maintainability, scalability, and compliance |

## Quality, Testing, And Review

| MCAF skill | Use it for |
|---|---|
| `mcaf-testing` | repository-aligned automated tests, verification flows, and test strategy updates |
| `mcaf-code-review` | PR scope, review checklists, reviewer expectations, and merge hygiene |
| `mcaf-solid-maintainability` | SOLID, SRP, cohesion, splitting large files or classes, and maintainability-limit enforcement |
| `mcaf-security-baseline` | secure defaults, secrets handling, review checkpoints, and baseline security guardrails |
| `mcaf-observability` | logs, metrics, traces, diagnostics, alerts, and runtime visibility policy |

## Tooling, Ops, And Product Surfaces

| MCAF skill | Use it for |
|---|---|
| `mcaf-ci-cd` | CI/CD pipelines, quality gates, release flow, deployment stages, and rollback policy |
| `mcaf-devex` | onboarding, local inner loop, reproducible setup, and developer workflow quality |
| `mcaf-ui-ux` | design-system, accessibility, front-end technology selection, and design-to-dev collaboration |
| `mcaf-ml-ai-delivery` | ML or AI product delivery, experimentation, responsible-AI workflow, and model/inference delivery planning |

## Practical .NET Routing

Start with `dotnet-mcaf` when the ask is "adopt MCAF" or "make this repo follow MCAF".

Then route:

- repo bootstrap and root/local `AGENTS.md` work -> `dotnet-mcaf`
- delivery workflow -> `dotnet-mcaf-agile-delivery`
- developer onboarding and local loop -> `dotnet-mcaf-devex`
- docs bootstrap -> `dotnet-mcaf-documentation`
- feature behaviour docs -> `dotnet-mcaf-feature-spec`
- large generated-drop review sequencing -> `dotnet-mcaf-human-review-planning`
- ML or AI delivery policy -> `dotnet-mcaf-ml-ai-delivery`
- source-control policy -> `dotnet-mcaf-source-control`
- explicit quality attributes -> `dotnet-mcaf-nfr`
- UI/UX and accessibility direction -> `dotnet-mcaf-ui-ux`
- overlapping architecture, testing, CI, security, observability, and maintainability areas -> keep the boundary guidance below and route into the existing `dotnet-*` implementation skills as needed

After governance routing is clear, switch to the matching `dotnet-*` skill for real framework or code changes.

## Overlap Versus Net-New Surface

Some MCAF skills overlap conceptually with areas that already exist in `dotnet-skills`, but they operate at a different layer.

### Conceptual overlap with existing `dotnet-*` skills

| MCAF skill | Closest current `dotnet-skills` surface | Boundary |
|---|---|---|
| `mcaf-architecture-overview` | `dotnet-architecture` | MCAF defines repo architecture docs and decision shape; `dotnet-architecture` covers actual .NET solution structure and technical design |
| `mcaf-code-review` | `dotnet-code-review` | MCAF defines review process and merge hygiene; `dotnet-code-review` reviews .NET code changes for bugs and regressions |
| `mcaf-testing` | `dotnet-quality-ci`, test-framework skills such as `dotnet-xunit`, `dotnet-nunit`, `dotnet-mstest`, `dotnet-tunit` | MCAF defines verification policy; `dotnet-*` skills define concrete .NET test and CI implementation |
| `mcaf-ci-cd` | `dotnet-quality-ci`, `dotnet-project-setup` | MCAF defines release-flow and governance policy; `dotnet-*` skills wire concrete .NET pipeline commands and quality gates |
| `mcaf-solution-governance` | `dotnet-project-setup` | MCAF defines root/local `AGENTS.md`, rule precedence, and repo policy; `dotnet-project-setup` defines solution and project structure |
| `mcaf-solid-maintainability` | `dotnet-complexity`, analyzer skills | MCAF defines maintainability expectations; `dotnet-*` skills implement concrete metrics, analyzers, and refactoring mechanics |
| `mcaf-security-baseline` | `dotnet-codeql`, analyzer and platform security skills | MCAF defines baseline security process; `dotnet-*` skills cover concrete .NET tooling and framework-specific security work |
| `mcaf-observability` | platform/runtime skills such as `dotnet-aspnet-core`, `dotnet-worker-services`, `dotnet-aspire`, `dotnet-orleans` | MCAF defines telemetry policy; `dotnet-*` skills implement logging, tracing, metrics, and diagnostics per framework |

### Surfaces that are effectively new relative to this catalog

These MCAF skills did not have a close one-to-one equivalent in the original `dotnet-skills` catalog and are now mirrored locally as:

- `dotnet-mcaf-agile-delivery`
- `dotnet-mcaf-devex`
- `dotnet-mcaf-documentation`
- `dotnet-mcaf-feature-spec`
- `dotnet-mcaf-human-review-planning`
- `dotnet-mcaf-ml-ai-delivery`
- `dotnet-mcaf-nfr`
- `dotnet-mcaf-source-control`
- `dotnet-mcaf-ui-ux`

Treat those as genuinely additive. They extend repo workflow and delivery governance rather than duplicating .NET implementation guidance.