fixes for tempaltes

Author: KSemenenko

docs/templates/ADR-Template.md

@@ -1,5 +1,7 @@
 # ADR-XXXX: Title
 
+> TEMPLATE ONLY — remove this note and replace all placeholder text before saving as a real ADR under `docs/ADR/`.
+
 Status: Proposed | Accepted | Implemented | Rejected | Superseded  
 Date: YYYY-MM-DD  
 Related Features: `docs/Features/...` (recommended)  
@@ -46,11 +48,11 @@ Key points:
 
 ---
 
-## Diagram (Mandatory)
+## Diagram
+
+This section is mandatory.
 
 ```mermaid
-%% Show the boundaries/modules that change, and how they interact.
-%% Prefer 1 clear diagram over many noisy ones.
 ```
 
 ---
@@ -108,7 +110,9 @@ Key points:
 
 ---
 
-## Verification (Mandatory: describe how to test this decision)
+## Verification
+
+This section is mandatory: describe how to prove the decision (tests + commands).
 
 ### Objectives
 
@@ -127,7 +131,7 @@ Key points:
 - build: (paste from `AGENTS.md`)
 - test: (paste from `AGENTS.md`)
 - format: (paste from `AGENTS.md`)
-- coverage: (paste from `AGENTS.md` if separate)
+- coverage: (paste from `AGENTS.md`; delete if none)
 
 ### New or changed tests
 

docs/templates/AGENTS.md

@@ -93,6 +93,10 @@ If no new rule is detected → do not update the file.
 
 - All docs live in `docs/` (or `.wiki/`)
 - Global architecture entry point: `docs/Architecture/Overview.md` (read first)
+- When creating docs from `docs/templates/*`:
+  - copy the template, then remove every `TEMPLATE ONLY` note
+  - replace all placeholder text (`TODO:`, `...`, “FeatureName”, “ADR-XXXX”, etc.)
+  - real docs must not contain template instructions or placeholder scaffolding
 - Update feature docs when behaviour changes
 - Update ADRs when architecture changes
 - Diagrams are mandatory in docs:

docs/templates/Architecture-Template.md

@@ -1,9 +1,10 @@
-# Architecture Overview (Template)
+# Architecture Overview
 
-> Save this as: `docs/Architecture/Overview.md`  
-> Goal: in ~5 minutes, understand **what exists**, **where it lives**, and **how modules interact**.
+> TEMPLATE ONLY — remove this note and replace all placeholder text before saving as a real `docs/Architecture/Overview.md`.
 
-## 1) TL;DR (fill this, keep it short)
+Goal: in ~5 minutes, understand **what exists**, **where it lives**, and **how modules interact**.
+
+## Summary (keep it short)
 
 - **System:**  
 - **Where is the code:**  
@@ -12,20 +13,16 @@
 
 ## 2) Module map (Mermaid)
 
+> TEMPLATE ONLY — model modules + boundaries (not every class/file). Add dependencies only if they exist. Remove this note in the real doc.
+
 ```mermaid
 flowchart LR
-  %% Model MODULES + BOUNDARIES, not every class/file.
-  %% Replace nodes with your real modules (or services) and label arrows.
-
   EP[Entry Points]
   A[Module A]
   B[Module B]
 
   EP --> A
   A --> B
-  %% Add dependencies only if they exist:
-  %% A --> D[(Data Store)]
-  %% A --> X[External Service]
 ```
 
 ## 3) Modules (catalog)

docs/templates/Feature-Template.md

@@ -1,5 +1,7 @@
 # Feature: FeatureName
 
+> TEMPLATE ONLY — remove this note and replace all placeholder text before saving as a real feature doc under `docs/Features/`.
+
 Links:  
 Architecture: `docs/Architecture/Overview.md`  
 Modules:  
@@ -78,12 +80,13 @@ Short description of the business problem and value.
 ## Diagrams
 
 ```mermaid
-%% Mermaid diagram for the main flow (modules + interactions).
 ```
 
 ---
 
-## Verification (Mandatory: describe how to test)
+## Verification
+
+This section is mandatory: describe how to test (scenarios + commands).
 
 ### Test environment
 
@@ -126,7 +129,9 @@ Short description of the business problem and value.
 - Unit tests:  
 - Static analysis:  
 
-### Non-functional checks (delete section if not applicable)
+### Non-functional checks
+
+Include this section only if it applies to this feature; otherwise remove it.
 
 - Performance / load (tool, threshold, command):  
 - Security / privacy (threats to verify):  

skills/mcaf-adr-writing/SKILL.md

@@ -28,6 +28,7 @@ Before writing, make the ADR executable (no placeholders, no hand-waving):
    - what changes (and what does not)
    - what module(s) are affected
 2. Start from `docs/templates/ADR-Template.md`.
+   - Remove every `TEMPLATE ONLY` note and replace placeholder text before treating it as a real ADR.
 3. Write the ADR as a decision record:
    - **Context**: constraints + why this is needed now
    - **Decision**: a short, direct statement

skills/mcaf-architecture-overview/SKILL.md

@@ -25,6 +25,7 @@ This doc is the **global map**: boundaries, modules, and dependency rules.
 ## Workflow
 
 1. Open `docs/Architecture/Overview.md` if it exists; otherwise start from `docs/templates/Architecture-Template.md`.
+   - Remove every `TEMPLATE ONLY` note and replace placeholder text before treating it as a real doc.
 2. Identify the **real** top-level boundaries:
    - entry points (HTTP/API, CLI, UI, jobs, events)
    - modules/layers (group by folders/namespaces, not individual files)

skills/mcaf-feature-spec/SKILL.md

@@ -26,6 +26,7 @@ Write a spec that can be implemented and verified **without guessing**:
 
 1. Start from `docs/Architecture/Overview.md` to pick the affected module(s).
 2. Create/update the feature doc using `docs/templates/Feature-Template.md`.
+   - Remove every `TEMPLATE ONLY` note and replace placeholder text before treating it as a real spec.
 3. Define behaviour precisely:
    - purpose and scope (in/out)
    - business rules (numbered, testable)