commands

Author: KSemenenko

docs/templates/ADR-Template.md

@@ -16,6 +16,19 @@ Rules:
 
 ---
 
+## Implementation plan (step-by-step)
+
+> TEMPLATE ONLY — replace these checkboxes with real implementation steps for this ADR and keep them updated while implementing.
+
+- [ ] Analyze current state (facts)
+- [ ] Plan the change (steps, files/modules, tests, docs)
+- [ ] Implement the change (smallest safe increments)
+- [ ] Add/update automated tests (happy + negative + edge; protect invariants)
+- [ ] Run verification commands (build/test/format/analyze/coverage) and record results
+- [ ] Update docs (ADR/Features/Architecture overview) and close the checklist
+
+---
+
 ## Context
 
 - Current situation (what exists today).
@@ -52,6 +65,8 @@ Key points:
 
 This section is mandatory.
 
+> TEMPLATE ONLY — Mermaid often breaks with fancy syntax. Keep it simple and make sure it renders in the repo.
+
 ```mermaid
 ```
 

docs/templates/AGENTS.md

@@ -79,11 +79,26 @@ If no new rule is detected → do not update the file.
   - confirm the Mermaid module/boundary diagram exists (if missing → create/update it first)
   - identify the impacted boundary/module(s) and entry points
   - follow the links to the relevant ADR(s) and Feature doc(s) (do not read everything)
-- Read assignment, then inspect only the relevant docs/code before planning
-- Write multi-step plan before implementation
+- Scope first (prevent context overload):
+  - use `docs/Architecture/Overview.md` → “Scoping (read first)”
+  - write **in scope / out of scope** (what will change and what must not change)
+  - if you cannot identify scope from the architecture map → stop and fix the map (or ask one clarifying question)
+- Analyze first (no coding yet):
+  - what exists today (facts only)
+  - what must change / must not change
+  - unknowns and risks (what must be clarified)
+- Create a written plan before implementation:
+  - for architecture/decision work: keep the plan as `## Implementation plan (step-by-step)` in the ADR
+  - for behaviour work: keep the plan as `## Implementation plan (step-by-step)` in the Feature doc
+  - update the plan while executing (tick items / update statuses as work is completed)
 - Implement code and tests together
 - If `build` is separate from `test`, run `build` before `test`
-- Run tests in layers: new → related suite → broader regressions
+- Verification timing (optimize time + tokens):
+  - do not run `test`/`coverage` “just because” before you wrote/changed code or tests (exception: reproducing a bug / confirming baseline)
+  - while iterating, run the smallest meaningful scope (new/changed tests first)
+  - run broader suites only when you have something real to verify (avoid re-running the same command without changes)
+  - run coverage once per change (it is heavier than tests)
+- Run tests in layers: new/changed → related suite → broader regressions
 - After tests pass: run format
 - After format: run build (final check)
 - Summarize changes and test results before marking complete
@@ -103,6 +118,10 @@ If no new rule is detected → do not update the file.
   - `docs/Architecture/Overview.md`: at least one Mermaid module/boundary map
   - `docs/Features/*`: at least one Mermaid diagram for the main flow
   - `docs/ADR/*`: at least one Mermaid diagram for the decision
+- Mermaid hygiene (Mermaid often breaks if you freestyle it):
+  - diagrams must render in repo Markdown preview (broken Mermaid is treated as broken documentation)
+  - prefer simple Mermaid syntax (`flowchart` / `sequenceDiagram`) and short ASCII-only IDs
+  - if a diagram doesn’t render, simplify it until it does (no “close enough”)
 
 ### Testing (ALL TASKS)
 
@@ -116,6 +135,7 @@ If no new rule is detected → do not update the file.
 - Never delete or weaken a test to make it pass
 - Each test verifies a real flow or scenario, not just calls a function — tests without meaningful assertions are forbidden
 - Check code coverage to see which functionality is actually tested; coverage is for finding gaps, not a number to chase
+- Flaky tests are failures: fix the test or the underlying behaviour, don’t “retry until green”
 
 ### Autonomy
 

docs/templates/Architecture-Template.md

@@ -11,6 +11,15 @@ Goal: in ~5 minutes, understand **what exists**, **where it lives**, and **how m
 - **Entry points:**  
 - **Dependencies:**  
 
+## Scoping (read first)
+
+- **In scope:** …
+- **Out of scope:** …
+- Pick impacted module(s) from the diagram + modules table.
+- Pick entry point(s): API / UI / CLI / job / event.
+- Read only: linked ADR/Feature doc(s) → entry-point file(s) → minimum dependencies.
+- Stop if scope can’t be mapped to this doc → update this doc (or ask 1 clarifying question).
+
 ## 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.

docs/templates/Feature-Template.md

@@ -9,6 +9,19 @@ ADRs: `docs/ADR/...`
 
 ---
 
+## Implementation plan (step-by-step)
+
+> TEMPLATE ONLY — replace these checkboxes with real implementation steps for this feature and keep them updated while implementing.
+
+- [ ] Analyze current behaviour (facts)
+- [ ] Finalize spec (rules/flows/diagram/verification)
+- [ ] Implement the feature (smallest safe increments)
+- [ ] Add/update automated tests for each scenario (happy + negative + edge)
+- [ ] Run verification commands (build/test/format/analyze/coverage) and record results
+- [ ] Update docs (Feature/ADRs/Architecture overview) and close the checklist
+
+---
+
 ## Purpose
 
 Short description of the business problem and value.
@@ -79,6 +92,8 @@ Short description of the business problem and value.
 
 ## Diagrams
 
+> TEMPLATE ONLY — Mermaid often breaks with fancy syntax. Keep it simple and make sure it renders in the repo.
+
 ```mermaid
 ```
 

skills/mcaf-adr-writing/SKILL.md

@@ -27,6 +27,7 @@ Before writing, make the ADR executable (no placeholders, no hand-waving):
 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`.
    - Remove every `TEMPLATE ONLY` note and replace placeholder text before treating it as a real ADR.
 3. Write the ADR as a decision record:
@@ -36,6 +37,7 @@ Before writing, make the ADR executable (no placeholders, no hand-waving):
    - **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”

skills/mcaf-feature-spec/SKILL.md

@@ -27,6 +27,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.
+   - follow `AGENTS.md` scoping rules (do not scan the whole repo; use the architecture map to stay focused)
 3. Define behaviour precisely:
    - purpose and scope (in/out)
    - business rules (numbered, testable)

skills/mcaf-testing/SKILL.md

@@ -22,9 +22,10 @@ compatibility: Requires the repository’s build/test tooling; uses commands fro
    - `docs/Features/*` for user/system flows and business rules
    - `docs/ADR/*` for architectural decisions and invariants that must remain true
    - if the docs are missing/contradict, fix the docs first (or write a minimal spec + test plan in the task/PR)
-3. Build first (always):
-   - run the `build` command from `AGENTS.md`
-   - fix build breaks before writing tests
+   - follow `AGENTS.md` scoping rules (Architecture map → relevant docs → relevant module code; avoid repo-wide scanning)
+3. Follow `AGENTS.md` verification timing (optimize time + tokens):
+   - run tests/coverage only when you have a reason (changed code/tests, bug reproduction, baseline confirmation)
+   - start with the smallest scope (new/changed tests), then expand to required suites
 4. Define the scenarios you must prove (map them back to docs):
    - **positive** (happy path)
    - **negative** (validation/forbidden/unauthorized/error paths)
@@ -62,8 +63,4 @@ compatibility: Requires the repository’s build/test tooling; uses commands fro
 
 ## Guardrails
 
-- Never delete or weaken a test to make it pass.
-- No mocks for internal systems in integration tests (DB/queues/caches should be real test instances/containers).
-- Tests must be meaningful: a test without assertions is not a test.
-- Coverage is for finding gaps, not a number to chase.
-- Flaky tests are failures: fix the test or the underlying behaviour, don’t “retry until green”.
+- All test discipline and prohibitions come from `AGENTS.md`. Do not contradict it in this skill.