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

1. Place root AGENTS.md at the repository or solution root.
2. Add project-local AGENTS.md only when the solution has multiple projects with genuinely different local rules.
3. 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.
4. Route to the narrowest MCAF skill once the governance concern is clear:

| Concern | Skill | |---------|-------| | Delivery workflow and feedback loops | mcaf-agile-delivery | | Developer onboarding and local inner loop | mcaf-devex | | Durable docs structure and source-of-truth placement | mcaf-documentation | | Executable feature behaviour docs | mcaf-feature-spec | | Human review for large AI-generated drops | mcaf-human-review-planning | | ML/AI product delivery process | mcaf-ml-ai-delivery | | Explicit quality attributes and trade-offs | mcaf-nfr | | Branch, merge, and release hygiene | mcaf-source-control | | Design-system, accessibility, front-end direction | mcaf-ui-ux |

1. Scaffold repo-native documentation:

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

1. Encode the non-trivial task flow in AGENTS.md: <slug>.brainstorm.md then <slug>.plan.md then implementation and validation.
2. 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

Related skills