ma-agents 3.4.8 → 3.4.9

package/.opencode/skills/.ma-agents.json

@@ -8,114 +8,233 @@
   "skills": {
     "git-workflow-skill": {
       "version": "2.1.0",
-      "installedAt": "2026-04-02T10:55:34.181Z",
-      "updatedAt": "2026-04-02T10:55:34.181Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:12.696Z",
+      "updatedAt": "2026-04-05T18:09:29.627Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "js-ts-dependency-mgmt": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:38.637Z",
-      "updatedAt": "2026-04-02T10:55:38.637Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:30.300Z",
+      "updatedAt": "2026-04-05T18:09:35.734Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "js-ts-security-skill": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:40.623Z",
-      "updatedAt": "2026-04-02T10:55:40.623Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:31.521Z",
+      "updatedAt": "2026-04-05T18:09:37.126Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "logging-best-practices": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:41.631Z",
-      "updatedAt": "2026-04-02T10:55:41.631Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:34.518Z",
+      "updatedAt": "2026-04-05T18:09:48.622Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "open-presentation": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:42.829Z",
-      "updatedAt": "2026-04-02T10:55:42.829Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:36.318Z",
+      "updatedAt": "2026-04-05T18:09:53.125Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "opentelemetry-best-practices": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:44.088Z",
-      "updatedAt": "2026-04-02T10:55:44.088Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:39.513Z",
+      "updatedAt": "2026-04-05T18:07:39.513Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "python-best-practices": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:45.390Z",
-      "updatedAt": "2026-04-02T10:55:45.390Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:40.244Z",
+      "updatedAt": "2026-04-05T18:07:40.244Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "python-dependency-mgmt": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:46.375Z",
-      "updatedAt": "2026-04-02T10:55:46.375Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:41.778Z",
+      "updatedAt": "2026-04-05T18:07:41.778Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "python-security-skill": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:47.153Z",
-      "updatedAt": "2026-04-02T10:55:47.153Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:43.209Z",
+      "updatedAt": "2026-04-05T18:07:43.209Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "self-signed-cert": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:48.480Z",
-      "updatedAt": "2026-04-02T10:55:48.480Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:46.583Z",
+      "updatedAt": "2026-04-05T18:07:46.583Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "skill-creator": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:50.426Z",
-      "updatedAt": "2026-04-02T10:55:50.426Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:49.678Z",
+      "updatedAt": "2026-04-05T18:07:49.678Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "story-status-lookup": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:51.221Z",
-      "updatedAt": "2026-04-02T10:55:51.221Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:50.727Z",
+      "updatedAt": "2026-04-05T18:07:50.727Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "test-accompanied-development": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:51.997Z",
-      "updatedAt": "2026-04-02T10:55:51.997Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:53.179Z",
+      "updatedAt": "2026-04-05T18:07:53.179Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "test-generator": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:53.511Z",
-      "updatedAt": "2026-04-02T10:55:53.511Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:54.383Z",
+      "updatedAt": "2026-04-05T18:07:54.383Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "vercel-react-best-practices": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:54.376Z",
-      "updatedAt": "2026-04-02T10:55:54.376Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:07:58.007Z",
+      "updatedAt": "2026-04-05T18:07:58.007Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     },
     "verify-hardened-docker-skill": {
       "version": "1.0.0",
-      "installedAt": "2026-04-02T10:55:56.461Z",
-      "updatedAt": "2026-04-02T10:55:56.461Z",
-      "installerVersion": "3.4.7",
+      "installedAt": "2026-04-05T18:08:04.319Z",
+      "updatedAt": "2026-04-05T18:08:04.319Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "ai-audit-trail": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:39.503Z",
+      "updatedAt": "2026-04-05T18:08:39.503Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "auto-bug-detection": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:41.377Z",
+      "updatedAt": "2026-04-05T18:08:41.377Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "cmake-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:43.339Z",
+      "updatedAt": "2026-04-05T18:08:43.339Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "code-documentation": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:45.996Z",
+      "updatedAt": "2026-04-05T18:08:45.996Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "code-review": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:47.752Z",
+      "updatedAt": "2026-04-05T18:08:47.752Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "commit-message": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:50.322Z",
+      "updatedAt": "2026-04-05T18:08:50.322Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:51.509Z",
+      "updatedAt": "2026-04-05T18:08:51.509Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-concurrency-safety": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:56.571Z",
+      "updatedAt": "2026-04-05T18:08:56.571Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-const-correctness": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:57.540Z",
+      "updatedAt": "2026-04-05T18:08:57.540Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-memory-handling": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:08:59.690Z",
+      "updatedAt": "2026-04-05T18:08:59.690Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-modern-composition": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:09:03.289Z",
+      "updatedAt": "2026-04-05T18:09:03.289Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-robust-interfaces": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:09:05.913Z",
+      "updatedAt": "2026-04-05T18:09:05.913Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "create-hardened-docker-skill": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:09:07.044Z",
+      "updatedAt": "2026-04-05T18:09:07.044Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "csharp-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:09:09.984Z",
+      "updatedAt": "2026-04-05T18:09:09.984Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "docker-hardening-verification": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:09:13.601Z",
+      "updatedAt": "2026-04-05T18:09:13.601Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "docker-image-signing": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:09:21.890Z",
+      "updatedAt": "2026-04-05T18:09:21.890Z",
+      "installerVersion": "3.4.9",
+      "agentVersion": "1.0.0"
+    },
+    "document-revision-history": {
+      "version": "1.0.0",
+      "installedAt": "2026-04-05T18:09:25.478Z",
+      "updatedAt": "2026-04-05T18:09:25.478Z",
+      "installerVersion": "3.4.9",
       "agentVersion": "1.0.0"
     }
   }

package/.opencode/skills/MANIFEST.yaml

@@ -1,6 +1,134 @@
 # MANIFEST.yaml
 
 skills:
+  - id: ai-audit-trail
+    file: ai-audit-trail/SKILL.md
+    description: Tracks AI agent session activity, time spent, and token usage in a project-level AiAudit.md log file.
+    applies_when:
+      - starting a new agent task or workflow
+      - completing a document generation session
+      - finishing any multi-step agent workflow
+    always_load: true
+
+  - id: auto-bug-detection
+    file: auto-bug-detection/SKILL.md
+    description: Instructs agents to identify and report defects in already-delivered code
+
+  - id: cmake-best-practices
+    file: cmake-best-practices/SKILL.md
+    description: Enforce target-based, property-oriented CMake patterns (CMake 3.0+).
+    applies_when:
+      - creating or modifying CMakeLists.txt files
+      - managing C++ project dependencies via CMake
+      - defining C++ build configurations
+    always_load: true
+
+  - id: code-documentation
+    file: code-documentation/SKILL.md
+    description: Standardize file headers and method documentation across C++, C#, JS, TS, and Python.
+    applies_when:
+      - creating or modifying source code files
+      - defining new functions, methods, or classes
+      - refactoring code logic
+      - documenting APIs
+    always_load: true
+
+  - id: code-review
+    file: code-review/SKILL.md
+    description: Performs comprehensive code reviews with best practices
+
+  - id: commit-message
+    file: commit-message/SKILL.md
+    description: Generates conventional commit messages from code changes
+
+  - id: cpp-best-practices
+    file: cpp-best-practices/SKILL.md
+    description: Comprehensive C++ coding standards covering naming conventions, modern C++ idioms (C++17/20/23), error handling, and build guidelines. Cross-references domain-specific C++ skills for deep-dives.
+    applies_when:
+      - writing c++ code
+      - modifying c++ code
+      - creating new c++ files or classes
+      - reviewing c++ code style or conventions
+      - refactoring c++ code
+      - setting up a c++ project
+    always_load: true
+
+  - id: cpp-concurrency-safety
+    file: cpp-concurrency-safety/SKILL.md
+    description: Enforce safe multi-threading patterns using RAII locking and task-based parallelism (C++14+).
+    applies_when:
+      - working with C++ threads
+      - using C++ mutexes or locking primitives
+      - performing C++ asynchronous operations
+      - designing multi-threaded C++ systems
+
+  - id: cpp-const-correctness
+    file: cpp-const-correctness/SKILL.md
+    description: Enforce immutability-by-default and push logic to compile-time using constexpr (C++14+).
+    applies_when:
+      - declaring C++ variables
+      - defining C++ member functions
+      - performing C++ compile-time calculations
+      - optimizing C++ logic
+
+  - id: cpp-memory-handling
+    file: cpp-memory-handling/SKILL.md
+    description: Enforces Modern C++ practices (RAII, Smart Pointers) to prevent memory leaks, dangling pointers, and buffer overflows.
+    applies_when:
+      - writing c++ code
+      - modifying memory-intensive C++ logic
+      - debugging memory leaks in c++
+      - implementing new c++ classes
+
+  - id: cpp-modern-composition
+    file: cpp-modern-composition/SKILL.md
+    description: Replace legacy C patterns with STL, Ranges, and modern C++ abstractions (C++14+).
+    applies_when:
+      - writing C++ logic or algorithms
+      - performing C++ refactoring
+      - handling C++ data transformations
+      - working with C++ collections
+    always_load: true
+
+  - id: cpp-robust-interfaces
+    file: cpp-robust-interfaces/SKILL.md
+    description: Enforce contract-based design and strong typing in C++ interfaces (C++14+).
+    applies_when:
+      - creating or modifying C++ header files
+      - designing C++ function signatures
+      - defining C++ APIs or public interfaces
+
+  - id: create-hardened-docker-skill
+    file: create-hardened-docker-skill/SKILL.md
+    description: Creates production-ready hardened Docker configurations following CIS, OWASP, and NIST standards
+
+  - id: csharp-best-practices
+    file: csharp-best-practices/SKILL.md
+    description: Comprehensive C# coding standards covering modern C# (C# 10-12), async/await, LINQ, dependency injection basics, nullable reference types, and testing conventions.
+    applies_when:
+      - writing c# code
+      - creating new c# files or classes
+      - reviewing c# code style or conventions
+      - working with .net projects
+      - setting up a c# project
+    always_load: true
+
+  - id: docker-hardening-verification
+    file: docker-hardening-verification/SKILL.md
+    description: Audits Docker images for security best practices, least privilege, and OpenShift compliance.
+
+  - id: docker-image-signing
+    file: docker-image-signing/SKILL.md
+    description: Automates the signing of Docker images using certificates and Cosign/Notary.
+
+  - id: document-revision-history
+    file: document-revision-history/SKILL.md
+    description: Manages a revision history table at the beginning of generated documents, tracking changes per version.
+    applies_when:
+      - generating or updating planning documents
+      - creating specification or design documents
+      - modifying existing markdown documents that have a revision history table
+
   - id: git-workflow-skill
     file: git-workflow-skill/SKILL.md
     description: MANDATORY worktree-based workflow for ALL file-changing activities. Enforces isolated feature branches, conventional commits, and PR-based merging.

package/.opencode/skills/ai-audit-trail/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: AI Audit Trail
+description: Tracks AI agent session activity, time spent, and token usage in a project-level AiAudit.md log file.
+---
+# AI Audit Trail
+
+At the end of every significant agent session, append an entry to `{project_root}/AiAudit.md`. If the file does not exist, create it with a `# AI Audit Trail` header first.
+
+## Entry Format
+
+```markdown
+| Date | Task | Tokens (est.) |
+|------|------|---------------|
+| YYYY-MM-DD | Brief task description | In: ~X / Out: ~Y |
+```
+
+## Rules
+
+- **Append only** — never delete or modify previous entries
+- **One row per session** — combine multiple tasks in the same session into one entry
+- **Estimate tokens** — round to nearest thousand, prefix with `~`. Write `N/A` if unknown
+- Write the entry as the **last action** before presenting results to the user
+- Skip trivial interactions (single-question answers, quick lookups)

package/.opencode/skills/auto-bug-detection/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: auto-bug-detection
+description: Instructs agents to identify and report defects in already-delivered code
+---
+# Auto Bug Detection
+
+Proactively identify and report defects found in already-delivered code during all agent sessions.
+
+## Purpose
+
+When you encounter code that has already been delivered (story/task marked done), you must scan for defects
+and report them using the structured format below. Do not silently ignore bugs in delivered code.
+
+## Detection Scope
+
+### Delivered Code (MUST scan and report bugs)
+
+- Code whose associated story/task is marked **done** or **completed**, regardless of branch.
+- Committed code on `main` or release branches.
+- Committed code on feature branches whose **parent story is completed**.
+
+### Work-in-Progress (DO NOT flag as bugs)
+
+- Uncommitted changes in the working tree.
+- Committed code on a branch whose associated story is still **in-progress** or **not-started**.
+- `TODO` / `FIXME` markers in code added as part of the **current story under review**.
+- Incomplete implementations explicitly tied to an active story.
+
+### Ambiguous Boundary — Feature Branches
+
+Committed code on a feature branch where the story status is **unknown** must be treated as WIP.
+
+To resolve the status, use the `story-status-lookup` skill — it defines how to identify the story slug,
+which file to read, and how to map status values to delivered vs WIP. Follow its fallback rule:
+when status cannot be determined, **default to WIP and do NOT flag as a bug**.
+
+---
+
+## Detection Criteria
+
+Scan delivered code for the following categories of defects. Each category includes examples of what qualifies.
+
+### 1. Logic Errors
+
+Incorrect computational logic, wrong conditionals, or inverted boolean expressions that cause the code
+to produce incorrect results.
+
+**Examples:**
+- Using `>` instead of `>=` in a boundary check, silently excluding a valid edge value.
+- An accumulator initialized to `1` instead of `0`, skewing totals.
+- A loop that iterates one too many or one too few times (off-by-one error).
+
+### 2. Unhandled Edge Cases
+
+Inputs or states that the code does not handle, leading to incorrect behavior or crashes.
+
+**Examples:**
+- A function that accepts a list but does not handle an empty list, throwing an index error.
+- A parser that crashes on a valid but empty string input.
+- Division without a zero-check on the divisor.
+
+### 3. Missing Error Handling
+
+Absence of error handling for operations that can fail, causing unhandled exceptions or silent failures.
+
+**Examples:**
+- File I/O calls with no try/catch, crashing the process on a missing file.
+- Network requests with no timeout or error callback.
+- A database query whose rejection is swallowed without logging or recovery.
+
+### 4. Broken Contracts
+
+Code that violates the API contract it published: wrong return types, missing required fields in
+responses, or side effects not documented in the interface.
+
+**Examples:**
+- A function documented to return `string | null` but sometimes returns `undefined`.
+- A REST endpoint returning HTTP 200 for a failed operation instead of the correct 4xx/5xx code.
+- A class method mutating shared state that is not documented as a side effect.
+
+### 5. Regressions
+
+Previously working behavior that is now broken, typically introduced by a change in a related component.
+
+**Examples:**
+- A utility function refactored to accept a new parameter that broke all existing callers that pass no argument.
+- A config key renamed in one place but not updated in all consumers, causing silent runtime failures.
+- A test that was green before a dependency upgrade and now fails due to an incompatible API change.
+
+### 6. Security Vulnerabilities
+
+Code patterns that introduce exploitable security weaknesses in existing, delivered functionality.
+
+**Examples:**
+- User-supplied input passed directly into a shell command without sanitization (command injection).
+- Secrets or API keys hard-coded in source files committed to the repository.
+- SQL queries constructed via string concatenation with unsanitized user input (SQL injection).
+- Sensitive data (passwords, tokens) logged at INFO level in production code.
+
+---
+
+## Reporting Format
+
+When a defect is detected in delivered code, report it using this structured template:
+
+```
+## Bug Report
+
+**Title:** [Short, descriptive title]
+**Severity:** [critical | high | medium | low]
+**Category:** [logic-error | unhandled-edge-case | missing-error-handling | broken-contract | regression | security-vulnerability]
+**Affected Component:** [Module, file, or system area]
+
+**Reproduction Steps:**
+1. [Step 1]
+2. [Step 2]
+
+**Expected Behavior:**
+[What should happen]
+
+**Actual Behavior:**
+[What actually happens]
+
+**Affected Files:**
+- path/to/file.ext (line N)
+```
+
+**Severity Guidelines:**
+- `critical` — Data loss, security breach, or system crash in normal usage.
+- `high` — Core feature broken or serious security risk; blocks users.
+- `medium` — Feature partially broken or degraded; workaround exists.
+- `low` — Minor issue, cosmetic defect, or edge case with minimal user impact.
+
+---
+
+## What NOT to Flag
+
+Do **not** report the following as bugs:
+
+- **Work-in-progress code** — Uncommitted changes or code on a branch with an active story.
+- **TODO / FIXME comments** in code added as part of the **current story** being reviewed.
+- **Incomplete implementations** explicitly tied to an active or not-yet-started story.
+- **Style preferences** — Naming conventions, formatting, or architectural opinions not related to correctness.
+- **Speculative issues** — Theoretical attack scenarios or failure modes with no demonstrable code path in the current codebase (e.g., an attack vector that requires filesystem access the process can never obtain).
+
+---
+
+## Required Action on Detection
+
+The required action depends on severity:
+
+### critical or high severity
+
+**Immediately run `/create-bug-story`** without waiting for user confirmation. These defects represent
+broken core functionality or security risks that must not be left untracked. Inform the user as you act:
+
+> "I found a **[severity]** bug in delivered code — running `create-bug-story` now to ensure it is tracked."
+
+Do not ask permission. Do not proceed with other tasks until the bug story is created.
+
+### medium or low severity
+
+**Recommend** that the user create a formal bug story, but do not act without their confirmation:
+
+> "I found a **[severity]** bug in delivered code. Would you like me to run `create-bug-story` to log it
+> formally so it can be scheduled in the sprint?"
+
+If the user declines or does not respond, note the finding in your response and continue. The bug report
+remains visible in the conversation but is not written to a file.

package/.opencode/skills/cmake-best-practices/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: Modern CMake Best Practices
+description: Enforce target-based, property-oriented CMake patterns (CMake 3.0+).
+---
+# Modern CMake Best Practices (Target-Based Approach)
+
+This skill ensures that CMake definitions follow the "Modern CMake" philosophy (3.0+), focusing on targets and properties rather than global variables.
+
+## Policies
+
+### 1. Target-Centric Philosophy
+*   **Rule**: Treat targets as objects. Use `target_*` commands instead of global commands.
+*   **Action**: 
+    - **Forbidden**: `include_directories()`, `link_libraries()`, `add_definitions()`.
+    - **Mandatory**: `target_include_directories()`, `target_link_libraries()`, `target_compile_definitions()`.
+*   **Rationale**: Encapsulates requirements and prevents property leakage to unrelated targets.
+
+### 2. Visibility Hygiene (`PUBLIC`, `PRIVATE`, `INTERFACE`)
+*   **Rule**: Always specify the scope of target properties.
+*   **Action**:
+    - `PRIVATE`: Requirement only for building the target.
+    - `INTERFACE`: Requirement only for consumers of the target.
+    - `PUBLIC`: Requirement for both.
+*   **Rationale**: Ensures that internal dependencies (like a private logging library) don't bleed into the usage requirements of your high-level API.
+
+### 3. Feature-Based C++ Standards
+*   **Rule**: Do not manually set `CMAKE_CXX_STANDARD` or `-std=c++XX` flags.
+*   **Action**: Use `target_compile_features(my_target PUBLIC cxx_std_17)`.
+*   **Rationale**: Allows CMake to handle compiler-specific flags and ensures the compiler actually supports the requested features.
+
+### 4. No Global Variable Manipulation
+*   **Rule**: Ban direct modification of `CMAKE_CXX_FLAGS` or `CMAKE_EXE_LINKER_FLAGS`.
+*   **Action**: Use `target_compile_options()` for specific compiler warnings or flags.
+*   **Rationale**: Global flags make it impossible to have different settings for different targets in the same project.
+
+### 5. Namespaced Alias Targets
+*   **Rule**: Always provide an alias for library targets using a namespace.
+*   **Action**: `add_library(MyLib::MyLib ALIAS my_lib_target)`.
+*   **Rationale**: Makes exported targets look consistent with external dependencies (like those found via `find_package`).
+
+## Examples
+
+### Before (Legacy Procedural CMake)
+```cmake
+include_directories(${PROJECT_SOURCE_DIR}/include)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17 -Wall")
+add_library(mylib mylib.cpp)
+```
+
+### After (Modern Target-Based CMake)
+```cmake
+add_library(mylib mylib.cpp)
+
+target_compile_features(mylib PUBLIC cxx_std_17)
+target_compile_options(mylib PRIVATE -Wall)
+
+target_include_directories(mylib 
+    PUBLIC 
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+)
+
+add_library(MyProject::MyLib ALIAS mylib)
+```