mcaf skills

Author: KSemenenko

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

@@ -0,0 +1,100 @@
+---
+name: mcaf-adr-writing
+description: "Create or update an ADR under `docs/ADR/` for architectural decisions, dependency changes, data-model changes, or cross-cutting policy shifts. Use when the user asks to write, update, or document an ADR, record a design decision, capture architecture trade-offs, or justify a repo-wide technical policy."
+compatibility: "Requires repository write access; produces Markdown ADRs with Mermaid diagrams."
+---
+
+# MCAF: ADR Writing
+
+## Trigger On
+
+- a dependency, boundary, platform, contract, or data model is changing
+- a design decision has meaningful trade-offs that should be recorded
+- a repo-wide engineering policy needs a durable rationale
+
+## Value
+
+- produce a concrete project delta: code, docs, config, tests, CI, or review artifact
+- reduce ambiguity through explicit planning, verification, and final validation skills
+- leave reusable project context so future tasks are faster and safer
+
+## Do Not Use For
+
+- feature-level behaviour details without an architecture decision
+- generic architecture overview content
+
+## Inputs
+
+- `docs/Architecture.md`
+- related feature docs
+- the nearest `AGENTS.md`
+- current constraints, options, and risks
+
+## Quick Start
+
+1. Read the nearest `AGENTS.md` and confirm scope and constraints.
+2. Run this skill's `Workflow` through the `Ralph Loop` until outcomes are acceptable.
+3. Return the `Required Result Format` with concrete artifacts and verification evidence.
+
+## Workflow
+
+1. Start from the concrete decision that must be made now.
+2. If the ADR is missing, scaffold it from `references/adr-template.md`.
+3. Record:
+   - context and problem
+   - chosen decision
+   - alternatives considered
+   - trade-offs and consequences
+   - implementation plan
+4. Add diagrams only when they remove ambiguity.
+5. Link the ADR to affected feature docs and `docs/Architecture.md`.
+
+## Deliver
+
+- `docs/ADR/ADR-XXXX-short-title.md`
+- linked updates to architecture docs when the decision changes boundaries
+
+## Validate
+
+- the decision and rejected alternatives are explicit
+- trade-offs are concrete, not hand-wavy
+- implementation impact is clear
+- a future engineer can understand why this path was chosen
+
+## Ralph Loop
+
+Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.
+
+1. Plan first (mandatory):
+   - analyze current state
+   - define target outcome, constraints, and risks
+   - write a detailed execution plan
+   - list final validation skills to run at the end, with order and reason
+2. Execute one planned step and produce a concrete delta.
+3. Review the result and capture findings with actionable next fixes.
+4. Apply fixes in small batches and rerun the relevant checks or review steps.
+5. Update the plan after each iteration.
+6. Repeat until outcomes are acceptable or only explicit exceptions remain.
+7. If a dependency is missing, bootstrap it or return `status: not_applicable` with explicit reason and fallback path.
+
+### Required Result Format
+
+- `status`: `complete` | `clean` | `improved` | `configured` | `not_applicable` | `blocked`
+- `plan`: concise plan and current iteration step
+- `actions_taken`: concrete changes made
+- `validation_skills`: final skills run, or skipped with reasons
+- `verification`: commands, checks, or review evidence summary
+- `remaining`: top unresolved items or `none`
+
+For setup-only requests with no execution, return `status: configured` and exact next commands.
+
+## Load References
+
+- start with `references/adr-template.md`
+- use `references/ADR-FORMATS.md` only for numbering or formatting conventions
+
+## Example Requests
+
+- "Write an ADR for moving to event-driven notifications."
+- "Document why we are adding PostgreSQL instead of keeping SQLite."
+- "Capture the policy decision behind local project AGENTS files."

.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.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 / test environment 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.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:
+````