Mcaf

MCAF Adoption

Trigger On

• bootstrapping MCAF in a new or existing repository that also contains .NET work
• updating root or project-local AGENTS.md files to follow a durable repo workflow
• deciding which MCAF governance skills and implementation-focused catalog skills to install together
• organizing repo-native docs for architecture, features, ADRs, testing, development, and operations

Workflow

1. Start from the canonical bootstrap surface:

• tutorial: https://mcaf.managed-code.com/tutorial
• concepts: https://mcaf.managed-code.com/
• public MCAF skills: https://mcaf.managed-code.com/skills

2. Place root AGENTS.md at the repository or solution root. 3. Add project-local AGENTS.md only when the solution has multiple projects with genuinely different local rules. 4. Install MCAF governance skills (mcaf-*) for process areas and implementation-focused catalog skills for framework work. Check references/skill-map.md for overlap before adding duplicate surfaces. 5. Route to the narrowest MCAF skill once the governance concern is clear:

6. Scaffold repo-native documentation:

   docs/
   ├── Architecture.md
   ├── Features/
   ├── ADR/
   ├── Testing/
   ├── Development/
   └── Operations/

7. Encode the non-trivial task flow in AGENTS.md: <slug>.brainstorm.md then <slug>.plan.md then implementation and validation. 8. Treat verification as part of done: tests, analyzers, formatters, coverage, and any architecture or security gates the repo configured.

flowchart LR
  A["Adopt MCAF"] --> B["Root AGENTS.md"]
  B --> C{"Multi-project?"}
  C -->|Yes| D["Project-local AGENTS.md"]
  C -->|No| E["Root policy only"]
  B --> F["Install mcaf-* governance skills"]
  B --> G["Install implementation-focused skills"]
  D --> H["Document boundaries and commands"]
  E --> H
  F --> I["Repo-native docs scaffolds"]
  G --> J[".NET implementation guidance"]
  H --> K["Run full quality pass"]
  I --> K
  J --> K

Deliver

• repository-ready MCAF adoption with clear root and local AGENTS.md responsibilities
• correct split between mcaf-* governance and implementation-focused skills
• repo-native docs and verification expectations instead of chat-only instructions

Validate

• root AGENTS.md exists at the repository or solution root
• project-local AGENTS.md files exist only where genuinely needed
• repo documents exact build, test, format, analyze, and coverage commands
• durable docs exist for architecture and behavior, not only inline comments
• non-trivial work follows the brainstorm-to-plan flow before implementation
• the full quality pass is part of done, not only a narrow happy-path test run

References

• references/adoption.md - canonical MCAF entry points, bootstrap rules, and the local-mirror boundary between governance and implementation skills
• references/skill-map.md - MCAF catalog map with overlap-vs-new split for precise routing

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 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 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 mcaf* governance skills under the native agent skill directory
• implementation-focused 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 implementation-focused 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 mcaf
• "implement or fix actual ASP.NET/Orleans/EF/Agent Framework code" -> route from mcaf into the narrowest implementation-focused skill
• "tighten verification and CI rules" -> combine 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

Local Mirrors In This Catalog

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

Docs And Architecture

Quality, Testing, And Review

Tooling, Ops, And Product Surfaces

Practical .NET Routing

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

Then route:

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

After governance routing is clear, switch to the matching implementation-focused 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 implementation-focused skills

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:

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

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