first iteration

Author: KSemenenko

.codex/skills/mcaf-adr-writing/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: mcaf-adr-writing
+description: "Create or update an ADR (Architecture Decision Record) under `docs/ADR/` using `docs/templates/ADR-Template.md`: context, decision, alternatives, consequences, rollout, and verification. Use when changing architecture, boundaries, dependencies, data model, or cross-cutting patterns; ensure it is self-contained, has a Mermaid diagram, and defines testable invariants."
+compatibility: "Requires repository write access; produces Markdown docs with Mermaid diagrams."
+---
+
+# MCAF: ADR Writing
+
+## Outputs
+
+- `docs/ADR/ADR-XXXX-<short-title>.md` (create or update)
+- Update `docs/Architecture/Overview.md` when boundaries/interactions change
+
+## Decision Quality (anti-guesswork checklist)
+
+Before writing, make the ADR executable (no placeholders, no hand-waving):
+
+- **Decision**: one sentence. If you can’t write it, you don’t have a decision yet.
+- **Scope**: what changes / what does not + which module(s) are affected (match `docs/Architecture/Overview.md` names).
+- **No invented reality**: every component you mention exists in the repo today, or is explicitly part of this change (named + where it will live).
+- **Invariants**: write as **MUST / MUST NOT** statements and say how we prove each (test or static analysis).
+- **Verification**: use exact commands from `AGENTS.md` and link scenarios → test IDs.
+- **Stakeholders**: Product / Dev / DevOps / QA — what each role must know to execute safely.
+
+## Workflow
+
+1. Confirm the decision scope:
+   - what changes (and what does not)
+   - what module(s) are affected
+   - follow `AGENTS.md` scoping rules: Architecture map → linked ADR/Feature → entry points (do not scan everything)
+2. Start from `docs/templates/ADR-Template.md`.
+   - keep the ADR’s `## Implementation plan (step-by-step)` updated while executing
+3. Write the ADR as a decision record:
+   - **Context**: constraints + why this is needed now
+   - **Decision**: a short, direct statement
+   - **Diagram** (mandatory): include at least one Mermaid diagram for the decision (boundaries/modules/interactions)
+   - **Alternatives**: 1–3 realistic options with pros/cons
+   - **Consequences**: trade-offs, risks, mitigations
+4. Make it executable for the team:
+   - follow `AGENTS.md` Task Delivery rules (analysis → plan → execute → verify)
+   - include the invariants that must be proven by tests
+   - include verification commands copied from `AGENTS.md`
+   - include rollout/rollback and “how we know it’s safe”
+5. Make impacts explicit:
+   - code/modules affected
+   - data/config changes (including migration/rollback)
+   - backwards compatibility strategy
+6. Add verification that proves the decision:
+   - which tests must exist/change
+   - which suites must stay green
+7. If the decision changes boundaries, update `docs/Architecture/Overview.md` (diagram, modules table, dependency rules).
+
+## Guardrails
+
+- ADRs are self-contained: no hidden context, no “as discussed”.
+- ADRs justify *why*; feature docs describe *what the system does*.
+- If you can’t state the decision in 1–2 sentences, the ADR is not ready.

.codex/skills/mcaf-adr-writing/references/ADR-FORMATS.md

@@ -0,0 +1,269 @@
+# ADR Formats (templates)
+
+This file is for **copy/paste**. Pick one of the templates below and fill it with real repo facts.
+
+Rules (MCAF):
+
+- ADRs are self-contained (no “as discussed”).
+- At least one Mermaid diagram is mandatory.
+- ADRs define testable invariants + verification commands (not vibes).
+
+---
+
+## Template 1: MCAF ADR (full)
+
+Use this as the default template. Save as `docs/ADR/ADR-XXXX-title-in-kebab-case.md`.
+
+````md
+# ADR-XXXX: Title
+
+Status: Proposed | Accepted | Implemented | Rejected | Superseded
+Date: YYYY-MM-DD
+Related Features: `docs/Features/...` (recommended)
+Supersedes: `docs/ADR/ADR-....md` (delete if none)
+Superseded by: `docs/ADR/ADR-....md` (delete if none)
+
+Rules:
+
+- This ADR is **self-contained** — avoid “as discussed”; include all critical context and links.
+- At least **one Mermaid diagram is mandatory** (boundaries/modules/interactions for this decision).
+
+---
+
+## Context
+
+- Current situation (what exists today).
+- Constraints (tech/legal/time/org constraints that matter).
+- Problem statement (what is failing / what you must enable).
+- Goals (what success looks like).
+- Non-goals (what this ADR is not trying to solve).
+
+---
+
+## Stakeholders (who needs this to be clear)
+
+| Role | What they need to know | Questions this ADR must answer |
+| --- | --- | --- |
+| Product / Owner | User/business impact, scope, rollout risk | What changes for users? What’s out of scope? |
+| Engineering | Boundaries/modules, data/contract changes, edge cases | What do we change, where, and why? |
+| DevOps / SRE | Deployability, config, monitoring, rollback | How do we ship safely and observe it? |
+| QA | Test scenarios + environment assumptions | What must be proven by automated tests? |
+
+---
+
+## Decision
+
+- One sentence decision statement.
+
+Key points:
+
+- Key point 1
+- Key point 2
+
+---
+
+## Diagram (Mandatory)
+
+```mermaid
+%% Show the boundaries/modules that change, and how they interact.
+%% Prefer 1 clear diagram over many noisy ones.
+```
+
+---
+
+## Alternatives considered
+
+### Option A
+
+- Pros:
+- Cons:
+- Rejected because:
+
+### Option B
+
+- Pros:
+- Cons:
+- Rejected because:
+
+---
+
+## Consequences
+
+### Positive
+
+- Benefit
+
+### Negative / risks
+
+- Risk
+- Mitigation:
+
+---
+
+## Impact
+
+### Code
+
+- Affected modules / services:
+- New boundaries / responsibilities:
+- Feature flags / toggles (names, defaults, removal plan):
+
+### Data / configuration
+
+- Data model / schema changes:
+- Config changes (keys, defaults, secrets handling):
+- Backwards compatibility strategy:
+
+### Documentation
+
+- Feature docs to update:
+- Testing docs to update:
+- Architecture docs to update:
+- `docs/Architecture/Overview.md` updates (what must change):
+- Notes for `AGENTS.md` (new rules/patterns):
+
+---
+
+## Verification (Mandatory: describe how to test this decision)
+
+### Objectives
+
+- What behaviour / qualities must be proven.
+- Which invariants from this ADR must be encoded as tests (happy path + negative/forbidden + edge cases).
+- Link each objective/scenario to the specific automated test(s) that prove it.
+
+### Test environment
+
+- Environment (local compose / staging / prod-like):
+- Data and reset strategy (seed data, migrations, rollback plan):
+- External dependencies (real / sandbox / fake services required):
+
+### Test commands
+
+- build: (paste from `AGENTS.md`)
+- test: (paste from `AGENTS.md`)
+- format: (paste from `AGENTS.md`)
+- coverage: (paste from `AGENTS.md` if separate; otherwise delete)
+
+### New or changed tests
+
+| ID | Scenario | Level (Unit / Int / API / UI) | Expected result | Notes / Data |
+| --- | --- | --- | --- | --- |
+| TST-001 | Happy path / negative / edge | Integration | Observable outcome | Fixtures / seed data |
+
+### Regression and analysis
+
+- Regression suites to run (must stay green):
+- Static analysis (tools/configs that must pass):
+- Monitoring during rollout (logs/metrics/alerts to watch):
+
+---
+
+## Rollout and migration
+
+- Migration steps:
+- Backwards compatibility:
+- Rollback:
+
+---
+
+## References
+
+- Issues / tickets:
+- External docs / specs:
+- Related ADRs:
+
+---
+
+## Filing checklist
+
+- [ ] File saved under `docs/ADR/ADR-XXXX-title-in-kebab-case.md` (not in `docs/templates/`).
+- [ ] Status reflects real state (`Proposed`, `Accepted`, `Rejected`, `Superseded`).
+- [ ] Links to related features, tests, and ADRs are filled in.
+- [ ] Diagram section contains at least one Mermaid diagram.
+- [ ] `docs/Architecture/Overview.md` updated if module boundaries or interactions changed.
+````
+
+---
+
+## Template 2: Mini ADR (small, safe decision)
+
+Use this when the decision is real but the scope is contained (still needs a diagram + verification).
+
+````md
+# ADR-XXXX: Title
+
+Status: Proposed | Accepted | Implemented | Rejected | Superseded
+Date: YYYY-MM-DD
+Related Features: `docs/Features/...` (delete if none)
+
+## Decision
+
+- One sentence.
+
+## Why (context + constraints)
+
+- Why now:
+- Constraints:
+
+## Diagram (Mandatory)
+
+```mermaid
+%% Boundaries/modules that change + their interaction.
+```
+
+## Alternatives (at least one)
+
+- Alternative A (why not):
+
+## Consequences
+
+- Positive:
+- Negative / risks + mitigations:
+
+## Verification (Mandatory)
+
+- Invariants to test:
+- Tests to add/update:
+- Commands to run (from `AGENTS.md`):
+````
+
+---
+
+## Template 3: Options Matrix ADR (when choosing between 2–4 options)
+
+Use this when you need to evaluate trade-offs explicitly and keep the decision auditable.
+
+````md
+# ADR-XXXX: Title
+
+Status: Proposed | Accepted | Implemented | Rejected | Superseded
+Date: YYYY-MM-DD
+
+## Decision
+
+- One sentence.
+
+## Decision drivers (what matters)
+
+- Driver 1:
+- Driver 2:
+
+## Options
+
+| Option | Summary | Pros | Cons | Risk | Why/why not |
+| --- | --- | --- | --- | --- | --- |
+| A | | | | | |
+| B | | | | | |
+
+## Diagram (Mandatory)
+
+```mermaid
+%% Diagram the chosen option (and the most important alternative if helpful).
+```
+
+## Verification (Mandatory)
+
+- Invariants to protect:
+- Test plan:
+````

.codex/skills/mcaf-architecture-overview/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: mcaf-architecture-overview
+description: "Create or update `docs/Architecture/Overview.md` (architecture diagrams): maintain Mermaid diagrams for system/modules, interfaces/contracts, and key classes/types; document dependency rules; link to ADRs/features. Use when onboarding, refactoring, or adding modules/boundaries."
+compatibility: "Requires repository write access; produces Markdown docs with Mermaid diagrams."
+---
+
+# MCAF: Architecture Overview
+
+## Output
+
+- `docs/Architecture/Overview.md` (create or update)
+
+## Architecture Thinking (keep it a map)
+
+This doc is the **global map**: boundaries, modules, and dependency rules.
+
+- Keep it lean and structural:
+  - modules/boundaries + responsibility + dependency direction
+  - Mermaid diagrams are the primary context:
+    - system/module map (blocks + dependency direction)
+    - interfaces/contracts map (how modules talk)
+    - key classes/types map (high-signal only; not exhaustive)
+- Treat it as the main “start here” card for humans and AI agents:
+  - diagram elements must use real names (no placeholders)
+  - every diagram element must have an explicit reference link (docs/code) so an agent can navigate without repo-wide scanning
+  - keep diagrams readable; if a diagram becomes “spaghetti”, split by boundary and link out
+- Keep behaviour out of the overview:
+  - feature flows live in `docs/Features/*`
+  - decision-specific diagrams/invariants live in `docs/ADR/*`
+- Anti-“AI slop” rule: never invent components/services/DBs — only document what exists (or what this change will explicitly add).
+
+## Workflow
+
+1. Open `docs/Architecture/Overview.md` if it exists; otherwise start from `docs/templates/Architecture-Template.md`.
+   - Ensure it contains a short `## Scoping (read first)` section (this is how we prevent “scan everything” behaviour).
+2. Identify the **real** top-level boundaries:
+   - entry points (HTTP/API, CLI, UI, jobs, events)
+   - modules/layers (group by folders/namespaces, not individual files)
+   - external dependencies (only those that actually exist)
+3. Fill the **Summary** so a new engineer can orient in ~1 minute.
+4. Maintain the Mermaid diagrams (the map people and agents start from):
+   - **system/module map**: keep it small (roughly 8–15 nodes), label arrows (calls/events/reads/writes)
+   - **interfaces/contracts map**: show ports/interfaces, APIs, events, queues, file formats (only what exists)
+   - **key classes/types map**: capture the main types that matter across modules (avoid inventories)
+   - don’t invent DB/queues/services/modules that aren’t present
+5. Fill the module index:
+   - one row per diagram node (not every internal module/class)
+   - responsibilities and “depends on” must be concrete
+   - prefer a short navigation list with links over big tables/inventories
+6. Write explicit dependency rules:
+   - what is allowed
+   - what is forbidden
+   - how integration happens (sync / async / shared lib)
+7. Add a short “Key decisions (ADRs)” section:
+   - link to the ADRs that define boundaries, dependencies, and major cross-cutting patterns
+   - keep it link-based (no detailed flows here)
+8. Link out to deeper docs:
+   - ADRs for key decisions
+   - Features for behaviour details
+   - Testing/Development for how to run and verify
+
+## Guardrails
+
+- Do not list every file/class. This is a **map**, not an inventory (key classes/types only).
+- Keep the document stable: update it when boundaries or interactions change.