ma-agents 2.20.3 → 2.22.0

package/lib/templates/project-context.template.md

@@ -0,0 +1,47 @@
+# Project Context
+<!-- ma-agents-template-version: 1.0 -->
+<!-- Generated by ma-agents at install time — this is a living document -->
+<!--
+  EXPAND THIS FILE over time:
+  - After architecture phase: run /bmad-generate-project-context
+  - After each sprint:        run /project-context-expansion (post-retrospective companion)
+  - Manually:                 add conventions you notice agents getting wrong
+-->
+
+## AI Agent Mandatory Rules
+
+### Pre-Task (EVERY task, no exceptions)
+
+1. Read the MANIFEST.yaml for your platform:
+<!-- ma-agents:manifest-paths-start -->
+{{MANIFEST_PATHS_LIST}}
+<!-- ma-agents:manifest-paths-end -->
+2. Load ALL skills marked `always_load: true` completely before doing anything
+3. Select additional skills relevant to the specific task type
+
+### Git Workflow (ALL file-changing tasks)
+
+1. Create a fresh worktree: `git worktree add ../<project>-<branch> -b <branch>`
+2. ALL work happens inside that worktree — never in the main working tree
+3. Use conventional commits: `feat/fix/chore/docs/refactor`
+4. Open a PR to main — never commit directly to main, never auto-merge
+5. After human approval and merge: `git worktree remove ../<project>-<branch>`
+
+### Agent Mission Lifecycle
+
+1. **Pre-flight:** Read MANIFEST.yaml, load always_load skills, select task skills
+2. **Worktree:** `git worktree add` creates fresh, isolated working surface
+3. **Implementation:** Execute task within the worktree
+4. **Self-review:** Run `code-review` skill on own output before opening PR
+5. **PR:** Conventional commit + PR opened — clear title and description
+6. **Human review gate:** Await approval — do NOT auto-merge under any circumstance
+7. **Merge + cleanup:** After approval: merge, `git worktree remove`, delete branch
+8. **Post-mission:** Update story status to done, append session to AiAudit.md
+
+## Technology Stack
+<!-- TODO: Populated after architecture phase via /bmad-generate-project-context -->
+<!-- Run: /bmad-generate-project-context to auto-detect your stack -->
+
+## Project-Specific Rules
+<!-- TODO: Grows through retrospectives and manual additions -->
+<!-- Run: /bmad-retrospective after each sprint to surface new conventions -->

package/opencode.json

@@ -0,0 +1,8 @@
+{
+  "instructions": [
+    {
+      "_source": "ma-agents",
+      "text": "# AI Agent Skills - Planning Instruction\n\nYou have access to a library of skills in your skills directory. Before starting any task:\n\n1. Read the skill manifest at .opencode/skills/MANIFEST.yaml\n2. Based on the task description, select which skills are relevant\n3. Read only the selected skill files\n4. Then proceed with the task\n\nAlways load skills marked with always_load: true.\nDo not load skills that are not relevant to the current task."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "2.20.3",
+  "version": "2.22.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/yes-flag.test.js",
+    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js",
     "build:bmad-cache": "node scripts/build-bmad-cache.js"
   },
   "keywords": [

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

@@ -0,0 +1,165 @@
+# 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/skills/auto-bug-detection/skill.json

@@ -0,0 +1,8 @@
+{
+  "name": "auto-bug-detection",
+  "version": "1.0.0",
+  "description": "Instructs agents to identify and report defects in already-delivered code",
+  "category": "workflow",
+  "tags": ["bug-detection", "quality"],
+  "always_load": false
+}

package/skills/code-review/SKILL.md

@@ -18,6 +18,46 @@ Perform comprehensive code reviews following industry best practices.
 - Suggest refactoring opportunities
 - Assess test coverage and documentation
 
+## Bug Detection During Review
+
+When reviewing code, also evaluate **delivered code** (code whose associated story is marked done) for
+pre-existing defects — not just the changes under review.
+
+### Scope Distinction
+
+- **Review feedback** (style, suggestions, correctness of the diff) → applies to the **current story's changes**
+- **Bug reports** (defects in delivered code) → applies to **pre-existing code**, tracked independently
+
+Do NOT block the current story review because of pre-existing bugs. Log them separately and continue.
+
+### Detection During Review
+
+The `auto-bug-detection` skill (always_load: true) provides the full detection criteria. During code review,
+apply those criteria to the delivered code you encounter while reviewing the diff context.
+
+When you detect a bug in delivered code:
+
+1. **Label it clearly** with severity (critical / high / medium / low) and mark it as `[BUG]` — distinct from review findings
+2. **Do not conflate it** with the review outcome — a story can pass review even if pre-existing bugs are found nearby
+3. **Recommend the reviewer invoke `/create-bug-story`** to formally log the bug into the backlog
+
+### Bug Finding Format (within review output)
+
+```
+### [BUG] <short title>
+**Severity:** <critical|high|medium|low>
+**Category:** <logic-error|unhandled-edge-case|missing-error-handling|broken-contract|regression|security-vulnerability>
+**Affected Component:** <module or system area>
+**Affected Files:** <file:line>
+**Description:** <what the defect is — include expected vs actual behavior>
+**Action:** Run `/create-bug-story` to log this formally → it will be tracked independently of this review.
+```
+
+### Note on Skill Interaction
+
+The `auto-bug-detection` skill defines *what* to look for. This section defines *when* and *how* to
+surface bug findings during a structured code review session.
+
 ## Output Format
 
 ```

package/skills/cpp-best-practices/SKILL.md

@@ -0,0 +1,230 @@
+# C++ Best Practices
+
+This skill establishes baseline C++ coding standards applicable to modern C++ projects (C++17/20/23). It covers naming conventions, code organization, memory management, error handling, modern idioms, and build guidelines. Domain-specific topics are handled by dedicated sibling skills — this skill provides the umbrella foundation and cross-references those skills where relevant.
+
+---
+
+## 1. Naming Conventions
+
+### Rule: Use consistent case styles by identifier type.
+
+| Identifier | Convention | Example |
+|---|---|---|
+| Types (class, struct, enum, alias) | `PascalCase` | `UserAccount`, `ConnectionPool` |
+| Functions and methods | `camelCase` | `getUserName()`, `processData()` |
+| Variables (local, parameter) | `camelCase` | `userName`, `itemCount` |
+| Member variables (private) | `camelCase_` with trailing underscore | `name_`, `bufferSize_` |
+| Constants and enumerators | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` |
+| Macros | `UPPER_SNAKE_CASE` | `ASSERT_NOT_NULL`, `LOG_LEVEL` |
+| Namespaces | `lowercase_snake_case` | `network::http`, `core::utils` |
+| Template parameters | `PascalCase` | `template<typename ValueType>` |
+| Files | `snake_case.cpp` / `snake_case.h` | `user_account.cpp`, `connection_pool.h` |
+
+**Action:** Do not abbreviate unless the abbreviation is universally understood in the domain (e.g., `id`, `url`, `http`). Avoid single-letter names except for loop indices (`i`, `j`, `k`) and template parameters (`T`, `U`).
+
+---
+
+## 2. Code Organization
+
+### Rule: One primary type per header file; name the file after the type.
+
+**Action:**
+- Place class declarations in `.h` files; place definitions in `.cpp` files.
+- Use `#pragma once` at the top of every header (preferred over include guards in new code).
+- Group headers: project headers first, then third-party, then standard library — each group separated by a blank line.
+- Keep headers self-contained: every header must include what it needs to compile in isolation.
+
+### Rule: Use namespaces to model the logical module hierarchy.
+
+**Action:**
+- Prefer deeply nested namespaces over flat ones: `namespace myapp::network::http { ... }`.
+- Avoid `using namespace` in header files. Restrict `using namespace std;` to `.cpp` file scope if used at all.
+- Use `inline namespace` only for versioning public APIs (e.g., `inline namespace v2`).
+
+### Rule: Keep translation units small and focused.
+
+**Action:**
+- Limit headers to declarations and inline functions under ~20 lines.
+- Move non-trivial inline logic into `.inl` files included at the bottom of the header.
+- Use forward declarations in headers to reduce compilation dependencies.
+
+---
+
+## 3. Memory Management
+
+**Action:** Apply RAII (Resource Acquisition Is Initialization) for all resources. Never allocate resources without an owning object responsible for releasing them.
+
+Key policies:
+- Prefer stack allocation. Use heap allocation only when lifetime exceeds scope or size is dynamic.
+- Use `std::make_unique<T>()` for exclusive ownership; `std::make_shared<T>()` only when shared ownership is truly required.
+- Never use raw `new` or `delete` outside of a low-level container implementation.
+- Use standard containers (`std::vector`, `std::string`, `std::array`) instead of raw arrays and buffers.
+
+> For detailed memory management patterns, see the `cpp-memory-handling` skill if installed.
+> It covers RAII, smart pointer selection, Rule of Zero/Five, and ownership transfer patterns.
+
+---
+
+## 4. Modern C++ Idioms
+
+### C++17
+
+**Action:** Use these C++17 features where they improve clarity:
+
+- **Structured bindings**: `auto [key, value] = myMap.begin()->first;` — prefer over `first`/`second`.
+- **`std::optional<T>`**: Return optional values instead of `nullptr` sentinels or output parameters.
+- **`std::variant<T...>`**: Model sum types explicitly instead of void pointers or inheritance hierarchies.
+- **`if constexpr`**: Replace SFINAE with readable compile-time branching in templates.
+- **Fold expressions**: Simplify variadic template expansions: `(args + ... + 0)`.
+- **`std::filesystem`**: Use `std::filesystem::path` for all file path manipulation; never concatenate paths with string operations.
+- **Class template argument deduction (CTAD)**: Write `std::pair p{1, "hello"s}` instead of `std::make_pair`.
+
+### C++20
+
+**Action:** Adopt C++20 features when targeting C++20 or later:
+
+- **Concepts**: Constrain template parameters with `requires` clauses instead of relying on substitution failures.
+  ```cpp
+  template<std::integral T>
+  T clamp(T value, T lo, T hi);
+  ```
+- **Ranges**: Replace hand-written loops over containers with range adaptors (`std::views::filter`, `std::views::transform`, `std::ranges::sort`).
+- **`std::format`**: Replace `printf`/`sprintf`/`ostringstream` with `std::format("{} has {} items", name, count)`.
+- **Three-way comparison (`<=>`)**:  Define `operator<=>` to implement all comparison operators at once.
+- **Coroutines**: Use for asynchronous I/O and generator patterns; avoid raw `co_await` boilerplate — prefer a library abstraction (e.g., cppcoro, Asio).
+- **Modules**: New projects targeting C++20+ should plan for module adoption; existing headers remain valid but prefer named module interface units for new public APIs.
+
+### C++23
+
+**Action:** Use C++23 features when the toolchain supports them:
+
+- **`std::expected<T, E>`**: Return `expected<Result, ErrorCode>` from functions that can fail, eliminating exception-based control flow for expected failures.
+- **`std::print` / `std::println`**: Replace `std::cout` for formatted output.
+- **Deducing `this`**: Use explicit object parameter `this` to eliminate CRTP boilerplate and write recursive lambdas cleanly.
+- **`std::flat_map` / `std::flat_set`**: Prefer over `std::map`/`std::set` for small to medium sorted collections requiring cache-friendly iteration.
+
+---
+
+## 5. Const-Correctness
+
+### Rule: Make everything const by default; relax only when mutation is required.
+
+**Action:**
+- Declare local variables `const auto` unless reassignment is needed.
+- Mark member functions `const` whenever they do not modify observable state.
+- Use `constexpr` for values and functions computable at compile-time.
+- Pass large types by `const&`; pass cheap types (scalars, pointers, `string_view`) by value.
+- Never return `const` by value from a function — it prevents move semantics.
+
+> For detailed const-correctness policies, see the `cpp-const-correctness` skill if installed.
+
+---
+
+## 6. Error Handling
+
+### Rule: Choose an error-handling strategy per layer and apply it consistently.
+
+| Context | Preferred Mechanism |
+|---|---|
+| Programmer errors (precondition violations) | `assert()` or contracts (C++26); never exceptions |
+| Expected failures in library APIs | `std::expected<T, E>` (C++23) or error codes |
+| Exceptional conditions that prevent normal flow | Exceptions (`std::runtime_error` hierarchy) |
+| Async / coroutine code | Error channels in the coroutine framework |
+
+**Action:**
+- Mark functions that cannot throw `noexcept`. Destructors, move constructors, and swap functions MUST be `noexcept`.
+- Catch exceptions by `const&` only: `catch (const std::exception& e)`.
+- Never catch `...` (catch-all) except at top-level handlers or plugin boundaries.
+- Do not use exceptions for control flow or expected failure paths — use `std::optional` or `std::expected` instead.
+
+---
+
+## 7. Class Design
+
+### Rule: Follow the Rule of Zero.
+
+**Action:**
+- Design classes so that the compiler-generated special members (copy/move constructor, copy/move assignment, destructor) are correct by default.
+- Use RAII members (smart pointers, standard containers) to make this automatic.
+- If you must define any special member function, define all five (destructor, copy ctor, move ctor, copy assign, move assign) — the Rule of Five.
+
+### Rule: Prefer composition over inheritance for code reuse.
+
+**Action:**
+- Use `public` inheritance only to model true "is-a" relationships with polymorphic behavior.
+- Mark base class destructors `virtual` when the class is intended to be used polymorphically.
+- Mark overriding methods `override`; mark non-overridable methods `final`.
+- Prefer free functions over member functions for operations that do not require access to private state.
+- Mark factory functions and pure query methods with `[[nodiscard]]` (C++17) to turn silent result-discard into a compiler warning.
+
+> For detailed composition patterns and elimination of legacy C patterns, see the `cpp-modern-composition` skill if installed.
+> For interface design contracts and strong typing, see the `cpp-robust-interfaces` skill if installed.
+
+---
+
+## 8. Concurrency
+
+### Rule: Never share mutable state between threads without synchronization.
+
+**Action:**
+- Prefer task-based concurrency (`std::async`, thread pools) over raw `std::thread`. Always specify `std::launch::async` explicitly — `std::async` without a launch policy may run deferred (synchronously on the calling thread), which defeats the purpose of async execution.
+- Protect shared data with `std::mutex`; always use `std::lock_guard` or `std::unique_lock` — never call `lock()`/`unlock()` manually.
+- Declare data accessed from multiple threads as `std::atomic<T>` when appropriate (single-variable synchronization, counters, flags).
+- Avoid `volatile` for inter-thread communication; use `std::atomic` instead.
+
+> For detailed concurrency safety patterns, see the `cpp-concurrency-safety` skill if installed.
+
+---
+
+## 9. Build and Compilation Guidelines
+
+### Rule: Enable high-warning levels and treat warnings as errors.
+
+**Action:**
+- GCC/Clang: `-Wall -Wextra -Wpedantic -Wconversion -Wshadow -Werror`
+- MSVC: `/W4 /WX`
+- Do not disable warnings without an inline comment explaining the rationale.
+
+### Rule: Use sanitizers during development and CI.
+
+| Sanitizer | Flag (GCC/Clang) | Detects |
+|---|---|---|
+| AddressSanitizer | `-fsanitize=address` | Buffer overflows, use-after-free |
+| UndefinedBehaviorSanitizer | `-fsanitize=undefined` | UB (integer overflow, null deref) |
+| ThreadSanitizer | `-fsanitize=thread` | Data races |
+
+**Action:** Enable at least `-fsanitize=address,undefined` in Debug and CI builds. Do not ship sanitizer builds.
+
+### Rule: Set the C++ standard explicitly.
+
+**Action:** Always specify `-std=c++17` (or higher) explicitly. Do not rely on compiler defaults, which differ across vendors.
+
+> For CMake-specific build configuration patterns, see the `cmake-best-practices` skill if installed.
+> It covers target-based CMake, `target_compile_options`, and compiler flag propagation.
+
+---
+
+## 10. General Code Quality
+
+### Rule: Prefer clarity over cleverness.
+
+**Action:**
+- Write code for the next reader, not the compiler. Compilers optimize well; humans struggle with obfuscation.
+- Extract magic numbers into named `constexpr` constants.
+- Prefer algorithms from `<algorithm>` and `<numeric>` over hand-written loops.
+- Limit function length to what fits on one screen (~50 lines). If longer, extract named helper functions.
+- Avoid deep nesting (more than 3 levels). Use early-return and guard clauses to flatten control flow.
+
+### Rule: Use `auto` judiciously.
+
+**Action:**
+- Use `auto` when the type is verbose and already clear from context (e.g., iterators, lambda types, CTAD).
+- Do not use `auto` when the type communicates intent and is not immediately obvious from the right-hand side.
+- Always specify `auto&` or `const auto&` for range-for loops over containers of non-trivial types.
+
+---
+
+## Resources
+
+- [Naming and Organization Examples](examples/naming-and-organization.md)
+- [Modern C++ Idioms Examples](examples/modern-idioms.md)