mcaf-architecture-overview

This skill acts as the primary maintainer for the architecture documentation suite, specifically focusing on docs/Architecture/Overview.md. It provides a structured mechanism to define the global map of a software project, ensuring that system boundaries, core modules, and interface contracts remain synchronized with the actual codebase. By enforcing the use of Mermaid diagrams, the agent creates visual representations of system architecture that are both human-readable and machine-navigable. It is specifically designed to prevent 'architecture drift' by requiring that every diagram element refers to real components or file paths, avoiding placeholders or abstract speculation. This skill is critical for teams undergoing onboarding, significant refactoring, or when defining new boundaries in complex systems. It adheres to the MCAF (Model-Context-Architecture-Framework) standards, ensuring that architecture decisions are linked to ADRs and features without cluttering the overview with behavioral logic or implementation details.

• Automatically generates or updates docs/Architecture/Overview.md based on existing folder structures and namespaces.

• Visualizes module boundaries, dependency directions, and key interface contracts using standardized Mermaid diagrams.

• Provides a 'start here' navigation point for developers and agents by linking every diagram element to its corresponding source code or documentation.

• Maintains strict architectural integrity by enforcing dependency rules (allowed vs. forbidden calls) and identifying cross-cutting concerns.

• Facilitates onboarding by summarizing system responsibilities and high-level interaction patterns in under one minute of reading time.

• The agent expects existing folder structures to represent domain boundaries (e.g., Docs/Architecture/, Docs/ADR/).

• Always verify current architectural state before proposing changes to ensure no invented components or 'AI slop' are introduced.

• Use this skill to keep documentation stable; update it only when structural boundaries or major interaction patterns change.

• Maintain focus on structural maps rather than behavioral flows; defer behavior-specific documentation to docs/Features/.

• Ensure each diagram remains readable; if a system grows too complex, trigger a split by boundary to maintain clarity.