ma-agents 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {

package/skills/README.md

@@ -302,6 +302,18 @@ Enforces target-based, property-oriented CMake patterns (CMake 3.0+ philosophy).
 
 ---
 
+### 14. Code Documentation Best Practices
+**Directory:** `code-documentation/`
+
+Enforces standardized file headers and method documentation across C++, C#, JS, and TS.
+
+**Key Features:**
+- ✅ **Standardized Headers**: Mandatory purpose, author, and version metadata.
+- ✅ **Language Standards**: Supporting Doxygen (C++), XML (C#), and JSDoc (JS/TS).
+- ✅ **Semantic Richness**: Mandates documenting `@param`, `@returns`, and `@throws`.
+
+---
+
 ## Requirements
 
 ### All Skills

package/skills/code-documentation/SKILL.md

@@ -0,0 +1,51 @@
+# Code Documentation Best Practices
+
+This skill enforces high-quality, standardized documentation for source code files and methods. It ensures consistent metadata and clear explanations of intent across different programming languages.
+
+## Policies
+
+### 1. Mandatory File Headers
+*   **Rule**: Every source file must begin with a standardized header block.
+*   **Contents**:
+    - **Purpose**: A brief description of what the file contains/solves.
+    - **Author/Project**: Project name or author information.
+    - **Metadata**: Date created/modified and version if applicable.
+
+### 2. Mandatory Method Documentation
+*   **Rule**: Every public or non-trivial internal function/method must have a documentation block immediately preceding it.
+*   **Standards**:
+    - **C++**: Use Doxygen style (`/** ... */`).
+    - **C#**: Use XML Documentation style (`/// <summary> ...`).
+    - **JS/TS**: Use JSDoc style (`/** ... */`).
+*   **Required Fields**:
+    - **Summary**: Concise description of what the method does.
+    - **Parameters**: Name and purpose of each argument.
+    - **Return Value**: Description of the output.
+    - **Exceptions/Errors**: Document significant error states or exceptions thrown.
+
+### 3. Focus on "Why" and "What"
+*   **Rule**: Do not document trivial code (e.g., `i++ // increment i`).
+*   **Action**: Document the **intent** and **usage constraints**. If the code is complex, explain the high-level logic rather than line-by-line mechanics.
+
+### 4. Semantic Linking
+*   **Rule**: Use language-specific linking features (e.g., `@see`, `{@link}`, `<see cref=.../>`) to refer to related types or methods.
+
+## Language Specifics
+
+| Language | Format | Key Tags |
+| :--- | :--- | :--- |
+| **C++** | Doxygen | `\brief`, `\param`, `\return`, `\throw` |
+| **C#** | XML Doc | `<summary>`, `<param>`, `<returns>`, `<exception>` |
+| **JS/TS** | JSDoc | `@description`, `@param`, `@returns`, `@throws` |
+
+---
+
+## Example (Generic Pattern)
+
+```text
+[File Header]
+[Imports]
+
+[Component Documentation]
+[Implementation]
+```

package/skills/code-documentation/examples/cpp.md

@@ -0,0 +1,29 @@
+# C++ Documentation (Doxygen Style)
+
+### File Header
+```cpp
+/**
+ * @file DataProcessor.hpp
+ * @brief Handles high-performance transformation of raw sensor data.
+ * @author Antigravity / ma-agents
+ * @date 2026-02-22
+ * @version 1.0.0
+ */
+```
+
+### Method Documentation
+```cpp
+/**
+ * @brief Calculates the moving average of a dataset.
+ * 
+ * This method uses a sliding window algorithm to smooth out volatility 
+ * in sensor inputs.
+ * 
+ * @param data A span of float values to process.
+ * @param windowSize The size of the averaging window (must be > 0).
+ * @return The calculated moving average as a float.
+ * @throw std::invalid_argument If data is empty or windowSize is invalid.
+ * @see SignalFilter
+ */
+float calculateMovingAverage(gsl::span<const float> data, size_t windowSize);
+```

package/skills/code-documentation/examples/csharp.md

@@ -0,0 +1,28 @@
+# C# Documentation (XML Style)
+
+### File Header
+```csharp
+/*
+ * File: AuthenticationService.cs
+ * Purpose: Manages user login, token validation, and multi-factor authentication.
+ * Author: Antigravity / ma-agents
+ * Date: 2026-02-22
+ */
+```
+
+### Method Documentation
+```csharp
+/// <summary>
+/// Validates a user's credentials against the secure identity store.
+/// </summary>
+/// <param name="username">The unique identifier for the user.</param>
+/// <param name="password">The plain-text password (will be hashed internally).</param>
+/// <returns>
+/// An <see cref="AuthResult"/> indicating success or failure with a details message.
+/// </returns>
+/// <exception cref="SecurityException">Thrown if the account is locked.</exception>
+public async Task<AuthResult> LoginAsync(string username, string password)
+{
+    // ...
+}
+```

package/skills/code-documentation/examples/javascript_typescript.md

@@ -0,0 +1,28 @@
+# JavaScript & TypeScript Documentation (JSDoc Style)
+
+### File Header
+```typescript
+/**
+ * @file api-client.ts
+ * @description Centralized HTTP client with automatic retry and error handling.
+ * @author Antigravity / ma-agents
+ * @version 1.2.0
+ */
+```
+
+### Method Documentation
+```typescript
+/**
+ * Fetches data from a specific endpoint with optional caching.
+ * 
+ * @template T The expected type of the response data.
+ * @param {string} url The target URL (must be absolute).
+ * @param {RequestOptions} [options] Optional configuration for headers and timeouts.
+ * @returns {Promise<T>} A promise that resolves to the parsed JSON response.
+ * @throws {NetworkError} If the server is unreachable.
+ * @throws {ValidationError} If the response schema does not match T.
+ */
+async function fetchData<T>(url: string, options?: RequestOptions): Promise<T> {
+  // ...
+}
+```

package/skills/code-documentation/skill.json

@@ -0,0 +1,23 @@
+{
+    "name": "Code Documentation Best Practices",
+    "description": "Standardize file headers and method documentation across C++, C#, JS, and TS.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "documentation",
+        "best-practices",
+        "cpp",
+        "csharp",
+        "javascript",
+        "typescript",
+        "doxygen",
+        "jsdoc"
+    ],
+    "applies_when": [
+        "creating or modifying source code files",
+        "defining new functions, methods, or classes",
+        "refactoring code logic",
+        "documenting APIs"
+    ],
+    "always_load": true
+}