Strengthen vertical-slice and quality rules

Author: KSemenenko

README.md

@@ -25,8 +25,8 @@ The goal of MCAF:
 MCAF has three core elements:
 
 - **Context** — code, docs, `AGENTS.md`, and skills live with the repo.
-- **Verification** — tests and analyzers are the decision makers, not opinions.
-- **Instructions** — root and local `AGENTS.md` files define how agents work here.
+- **Verification** — integration tests and quality gates are the decision makers, not opinions.
+- **Instructions** — root and local `AGENTS.md` files define how agents work here and learn over time.
 
 These concepts define the framework (the "what" and "why").  
 `TUTORIAL.md` is the bootstrap procedure (the "how").  
@@ -113,15 +113,18 @@ The public skill catalog lives on the Skills page:
 
 Platform-specific bundles can stay small and still be explicit.
 `.NET` skills are maintained outside this repository in the [Managed Code Skills catalog](https://skills.managed-code.com/).
-Install the `.NET` skills you need from that catalog, then document the exact `dotnet build`, `dotnet test`, `dotnet format`, `analyze`, and coverage commands in the consuming repo’s `AGENTS.md`.
-For `.NET` code changes, the task is not done when tests are green if the repo also configured formatters, analyzers, coverage, architecture tests, or security gates.
+Install the `.NET` skills you need from that catalog, then document the exact `dotnet build`, `dotnet test`, `dotnet format`, `analyze`, `complexity`, coverage, and other quality-gate commands in the consuming repo’s `AGENTS.md`.
+For `.NET` code changes, the task is not done when tests are green if the repo also configured formatters, analyzers, complexity checks, coverage, architecture tests, or security gates.
 Agents should run the repo-defined post-change quality pass before completion, and any external `.NET` helper should still include a `Bootstrap When Missing` section so agents can detect, install, verify, and first-run the tool without guessing.
 
 ### 2.5 Context Rules
 
 - All durable engineering context lives in the repository.
 - The project has a current `docs/Architecture.md`.
 - Humans and agents start from the architecture map, not repo-wide scanning.
+- Vertical-slice architecture is mandatory by default.
+- Each feature lives in its own folder tree with the code, tests, contracts, docs, and other dependencies needed for that slice.
+- Feature slices stay as isolated as possible so task context stays narrow and the right files are easy to find.
 - `docs/Architecture.md` contains Mermaid diagrams for system/module boundaries, interfaces/contracts, and key types for the active area.
 - Feature docs under `docs/Features/` contain at least one Mermaid diagram for the main flow.
 - ADRs under `docs/ADR/` contain at least one Mermaid diagram for the decision and affected boundaries.
@@ -145,19 +148,23 @@ MCAF expects layered verification:
 The goal is not “one test per feature.”  
 The goal is enough automated evidence to trust the change.
 
+Integration tests are the backbone because they prove that a slice works through real boundaries, not just isolated units.
+
 ### 3.2 Verification Rules
 
 - Prefer TDD for new behaviour and bug fixes: start with a failing test, make it pass, then refactor.
 - New or changed behaviour is proven by new or updated automated tests.
 - Tests prove user-visible or caller-visible flows, not just isolated implementation detail.
 - Tests cover positive, negative, edge, and unexpected flows when the behaviour can fail in different ways.
 - Integration/API/UI coverage is preferred when the behaviour crosses boundaries.
+- Integration tests are the default primary proof for behaviour that spans more than one component inside a feature slice.
 - Internal and external systems are exercised through real containers, test instances, or sandbox environments in primary suites.
 - Mocks, fakes, stubs, and service doubles are forbidden in verification flows.
 - Changed production code should reach at least 80% line coverage and 70% branch coverage where supported; critical flows and public contracts should reach 90% line coverage.
 - Coverage must not regress below the pre-change baseline without an explicit exception, and coverage numbers do not replace scenario coverage.
 - Static analysis is part of done, not a cleanup task.
 - Failing tests or analyzers block completion.
+- Run every repo-defined quality gate that is available for the stack and change scope: formatters, linters, analyzers, complexity checks, architecture tests, security scans, mutation checks, coverage, and any other configured verification tools.
 - The task is not done until the full relevant test suite is green, not only the newly added or changed tests.
 
 ### 3.3 Verification Artifacts
@@ -210,13 +217,14 @@ Agents follow this order:
 
 Root `AGENTS.md` stays current with:
 
-- commands (`build`, `test`, `format`, `analyze`, `coverage` if used)
+- commands (`build`, `test`, `format`, `analyze`, `complexity`, `coverage`, and other quality gates if used)
 - global skills and when to use them
 - self-learning rules
 - non-trivial task workflow rules, including root-level `<slug>.brainstorm.md` and `<slug>.plan.md` usage
 - testing discipline
 - done criteria for tests, coverage, and quality gates
 - design and maintainability rules
+- vertical-slice architecture rules and allowed exceptions
 - exception policy
 - topology for local `AGENTS.md` files
 
@@ -254,13 +262,18 @@ Stable corrections, preferences, and recurring mistakes should become:
 - skill updates
 
 If the same mistake happens twice, the framework expects the rule to be made durable.
+Self-learning is a cornerstone of the framework, not an optional habit.
 
 ### 4.6 Hard Rules for Instructions
 
 - Every MCAF repo has a root `AGENTS.md`.
 - Multi-project solutions use local `AGENTS.md` files at project roots.
 - Agents read root and local `AGENTS.md` before editing code.
-- Non-trivial tasks start with a root-level `<slug>.brainstorm.md`, then move into a root-level `<slug>.plan.md`.
+- Vertical-slice architecture is mandatory unless an ADR or local exception rule says otherwise.
+- Each feature must live in its own isolated folder tree with its local code, tests, and supporting artifacts kept together.
+- Agents must prefer the smallest relevant feature slice over repo-wide scanning.
+- Only non-trivial tasks start with a root-level `<slug>.brainstorm.md`, then move into a root-level `<slug>.plan.md`.
+- Simple, short, or obvious tasks should skip the brainstorm and go straight to execution.
 - Brainstorms capture thinking, options, trade-offs, and the chosen direction before implementation starts.
 - Plans include ordered implementation steps, explicit test steps, testing methodology, and final validation commands.
 - Skills are preferred over improvised workflow when a skill matches the task.
@@ -274,6 +287,8 @@ MCAF coding rules exist to keep systems changeable and testable.
 
 - SOLID is mandatory.
 - SRP and cohesion are mandatory.
+- Vertical-slice architecture is mandatory at feature level.
+- Organize code so each feature owns its folder, subfolders, tests, and nearby dependencies as an isolated slice.
 - Prefer composition over inheritance unless inheritance is explicitly justified.
 - Boundaries must support realistic tests through public interfaces.
 - Hidden global state and side effects are design smells.
@@ -362,6 +377,7 @@ The brainstorm records:
 - the recommended direction that will become the plan
 
 Brainstorm first, think through the task, then convert the chosen direction into a working plan.
+Do not create a brainstorm for simple, short, or obvious work where the path is already clear.
 
 ### 7.3 Plan
 
@@ -397,7 +413,8 @@ Run verification in layers:
 2. related suite
 3. broader required regressions and the full relevant suite
 4. analyzers, formatters, and any configured architecture, security, mutation, or other quality gates
-5. coverage comparison against the pre-change baseline
+5. complexity checks and any other configured code-quality tools
+6. coverage comparison against the pre-change baseline
 
 ### 7.6 Update Durable Context and Close the Task
 
@@ -444,5 +461,7 @@ Adoption is complete when:
 - multi-project boundaries have local `AGENTS.md`
 - commands and docs reflect the real repo
 - non-trivial work is guided by root-level `<slug>.brainstorm.md`, `<slug>.plan.md`, and the Ralph Loop
+- simple work skips brainstorm overhead and goes straight to execution
+- vertical-slice architecture, integration tests, and self-learning are treated as core framework pillars
 - tool-specific skills document real bootstrap and install steps when the tool is missing
 - tests and analyzers are the real gates

TUTORIAL.md

@@ -114,13 +114,15 @@ For `.NET` repositories, keep these repo-native artifacts explicit in `AGENTS.md
 - `Directory.Build.props` or project files for bulk analyzer and runner settings
 - target `TFM` and explicit `LangVersion` only when the repo intentionally differs from the SDK default
 - whether the solution uses `VSTest` or `Microsoft.Testing.Platform`
-- the non-trivial task flow: `<slug>.brainstorm.md` first, then `<slug>.plan.md`, then implementation and validation
+- the decision rule for `brainstorm`: use `<slug>.brainstorm.md` only for non-trivial tasks, then `<slug>.plan.md`, then implementation and validation
+- vertical-slice architecture rules so each feature stays in its own isolated folder tree
+- self-learning rules so repeated corrections become durable repo guidance
 
 The intended `.NET` flow stays the same even though the bundle is external:
 
 - install the required skills from the external catalog
 - use the skills that fit the repo workflow and test framework
-- after code changes, run the repo-defined quality pass: format, build, analyze, tests, coverage, and any configured extra gates
+- after code changes, run the repo-defined quality pass: format, build, analyze, tests, complexity, coverage, and any configured extra gates
 
 ### 4.1 Current Skill Catalog (Generated)
 
@@ -236,6 +238,8 @@ Use a prompt like this:
 Analyze this solution and customize the root AGENTS.md.
 If this is a multi-project solution, create project-local AGENTS.md files in each project root.
 Then identify which MCAF skills apply to each project and document them in the local AGENTS files.
-For non-trivial tasks, require a root-level <slug>.brainstorm.md before <slug>.plan.md.
+For non-trivial tasks, require a root-level <slug>.brainstorm.md before <slug>.plan.md, but skip brainstorm for simple or obvious tasks.
+Make vertical-slice architecture mandatory so each feature stays in its own isolated folder tree with nearby tests and dependencies.
+Treat integration tests, self-learning, and full quality-gate execution as non-negotiable repo rules.
 Finally, update docs/Architecture.md so agents can scope work without repo-wide scanning.
 ```

docs/templates/AGENTS.md

@@ -112,7 +112,7 @@ If the stack is `.NET`, document skill-management rules explicitly:
 - Keep exactly one framework skill: `mcaf-dotnet-xunit` or `mcaf-dotnet-tunit` or `mcaf-dotnet-mstest`.
 - Add tool-specific `.NET` skills only when the repository actually uses those tools in CI or local verification.
 - Keep only `mcaf-*` skills in agent skill directories.
-- When upgrading skills, recheck `build`, `test`, `format`, `analyze`, and `coverage` commands against the repo toolchain.
+- When upgrading skills, recheck `build`, `test`, `format`, `analyze`, `complexity`, and `coverage` commands against the repo toolchain.
 
 ## Rules to Follow (Mandatory)
 
@@ -122,6 +122,7 @@ If the stack is `.NET`, document skill-management rules explicitly:
 - `test`: `...`
 - `format`: `...`
 - `analyze`: `...` (delete if not used)
+- `complexity`: `...` (delete if not used)
 - `coverage`: `...` (delete if not used)
 
 If the stack is `.NET`, also document:
@@ -160,6 +161,9 @@ Local `AGENTS.md` files may tighten these values, but they must not loosen them
 - Start from `docs/Architecture.md` and the nearest local `AGENTS.md`.
 - Treat `docs/Architecture.md` as the architecture map for every non-trivial task.
 - If the overview is missing, stale, or diagram-free, update it before implementation.
+- Use vertical slices as the default architecture rule.
+- Keep each feature in its own folder tree with its code, tests, contracts, docs, and supporting artifacts together.
+- Prefer the smallest relevant feature slice over repo-wide scanning so context stays narrow.
 - Define scope before coding:
   - in scope
   - out of scope
@@ -169,7 +173,9 @@ Local `AGENTS.md` files may tighten these values, but they must not loosen them
   - current state
   - required change
   - constraints and risks
+- Before starting a brainstorm, decide whether the task is actually non-trivial.
 - For non-trivial work, create a root-level `<slug>.brainstorm.md` file before making code or doc changes.
+- For simple, short, or obvious work, skip the brainstorm and go directly to execution.
 - Use `<slug>.brainstorm.md` to capture the problem framing, options, trade-offs, risks, open questions, and the recommended direction.
 - Think through the task in the brainstorm before committing to implementation details.
 - After the brainstorm direction is chosen, create a root-level `<slug>.plan.md` file.
@@ -208,6 +214,7 @@ Local `AGENTS.md` files may tighten these values, but they must not loosen them
   - broader required regressions
 - If `build` is separate from `test`, run `build` before `test`.
 - After tests pass, run `format`, then the final required verification commands.
+- Run every repo-defined quality gate that is available for the stack and change scope, including analyzers, linters, complexity checks, coverage, architecture checks, security checks, and any other configured tools.
 - The task is complete only when every planned checklist item is done and all relevant tests are green.
 - Summarize the change, risks, and verification before marking the task complete.
 
@@ -242,6 +249,7 @@ Local `AGENTS.md` files may tighten these values, but they must not loosen them
 - Tests should be as realistic as possible and exercise the system through real flows, contracts, and dependencies.
 - Tests must cover positive flows, negative flows, edge cases, and unexpected paths from multiple relevant angles when the behaviour can fail in different ways.
 - Prefer integration/API/UI tests over isolated unit tests when behaviour crosses boundaries.
+- Integration tests are the default primary proof for feature-slice behaviour that spans multiple components.
 - Do not use mocks, fakes, stubs, or service doubles in verification.
 - Exercise internal and external dependencies through real containers, test instances, or sandbox environments that match the real contract.
 - Flaky tests are failures. Fix the cause.
@@ -251,14 +259,16 @@ Local `AGENTS.md` files may tighten these values, but they must not loosen them
 - Coverage is for finding gaps, not gaming a number. Coverage numbers do not replace scenario coverage or user-flow verification.
 - The task is not done until the full relevant test suite is green, not only the newly added tests.
 - If the stack is `.NET`, document the active framework and runner model explicitly so agents do not mix VSTest and Microsoft.Testing.Platform assumptions.
-- If the stack is `.NET`, after changing production code run the repo-defined quality pass: format, build, analyze, focused tests, broader tests, coverage, and any configured extra gates such as architecture, security, or mutation checks.
+- If the stack is `.NET`, after changing production code run the repo-defined quality pass: format, build, analyze, focused tests, broader tests, complexity, coverage, and any configured extra gates such as architecture, security, or mutation checks.
 
 ### Code and Design
 
 - Everything in this solution MUST follow SOLID principles by default.
 - Every class, object, module, and service MUST have a clear single responsibility and explicit boundaries.
 - SOLID is mandatory.
 - SRP and strong cohesion are mandatory for files, types, and functions.
+- Vertical-slice architecture is mandatory unless a local rule or ADR documents an exception.
+- Each feature MUST live in its own isolated folder tree with all slice-local dependencies kept together.
 - Prefer composition over inheritance unless inheritance is explicitly justified.
 - Large files, types, functions, and deep nesting are design smells. Split them or document a justified exception under `exception_policy`.
 - Hardcoded values are forbidden.
@@ -274,6 +284,7 @@ Local `AGENTS.md` files may tighten these values, but they must not loosen them
 - Never weaken a test or analyzer without explicit justification.
 - Never introduce mocks, fakes, stubs, or service doubles to hide real behaviour in tests or local flows.
 - Never introduce a non-SOLID design unless the exception is explicitly documented under `exception_policy`.
+- Never spread one feature across unrelated folders when a vertical slice can keep it isolated.
 - Never force-push to `main`.
 - Never approve or merge on behalf of a human maintainer.