ma-agents 2.20.2 → 2.21.0

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

@@ -0,0 +1,241 @@
+{
+  "manifestVersion": "1.1.0",
+  "agent": "opencode",
+  "agents": [
+    "opencode"
+  ],
+  "scope": "project",
+  "skills": {
+    "ai-audit-trail": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:19.149Z",
+      "updatedAt": "2026-03-23T12:19:19.149Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "auto-bug-detection": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:19.319Z",
+      "updatedAt": "2026-03-23T12:19:19.319Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "cmake-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:19.584Z",
+      "updatedAt": "2026-03-23T12:19:19.584Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "code-documentation": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:20.028Z",
+      "updatedAt": "2026-03-23T12:19:20.028Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "code-review": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:20.260Z",
+      "updatedAt": "2026-03-23T12:19:20.260Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "commit-message": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:20.490Z",
+      "updatedAt": "2026-03-23T12:19:20.490Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:20.829Z",
+      "updatedAt": "2026-03-23T12:19:20.829Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-concurrency-safety": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:21.100Z",
+      "updatedAt": "2026-03-23T12:19:21.100Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-const-correctness": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:21.369Z",
+      "updatedAt": "2026-03-23T12:19:21.369Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-memory-handling": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:21.542Z",
+      "updatedAt": "2026-03-23T12:19:21.542Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-modern-composition": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:21.854Z",
+      "updatedAt": "2026-03-23T12:19:21.854Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "cpp-robust-interfaces": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:22.369Z",
+      "updatedAt": "2026-03-23T12:19:22.369Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "create-hardened-docker-skill": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:22.631Z",
+      "updatedAt": "2026-03-23T12:19:22.631Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "csharp-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:22.901Z",
+      "updatedAt": "2026-03-23T12:19:22.901Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "docker-hardening-verification": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:23.173Z",
+      "updatedAt": "2026-03-23T12:19:23.173Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "docker-image-signing": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:23.700Z",
+      "updatedAt": "2026-03-23T12:19:23.700Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "document-revision-history": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:23.854Z",
+      "updatedAt": "2026-03-23T12:19:23.854Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "git-workflow-skill": {
+      "version": "2.1.0",
+      "installedAt": "2026-03-23T12:19:24.284Z",
+      "updatedAt": "2026-03-23T12:19:24.284Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "js-ts-dependency-mgmt": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:24.578Z",
+      "updatedAt": "2026-03-23T12:19:24.578Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "js-ts-security-skill": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:24.843Z",
+      "updatedAt": "2026-03-23T12:19:24.843Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "logging-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:25.185Z",
+      "updatedAt": "2026-03-23T12:19:25.185Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "open-presentation": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:25.380Z",
+      "updatedAt": "2026-03-23T12:19:25.380Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "opentelemetry-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:25.652Z",
+      "updatedAt": "2026-03-23T12:19:25.652Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "python-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:25.865Z",
+      "updatedAt": "2026-03-23T12:19:25.865Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "python-dependency-mgmt": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:26.189Z",
+      "updatedAt": "2026-03-23T12:19:26.189Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "python-security-skill": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:26.439Z",
+      "updatedAt": "2026-03-23T12:19:26.439Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "self-signed-cert": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:26.597Z",
+      "updatedAt": "2026-03-23T12:19:26.597Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "skill-creator": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:26.879Z",
+      "updatedAt": "2026-03-23T12:19:26.879Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "story-status-lookup": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:27.066Z",
+      "updatedAt": "2026-03-23T12:19:27.066Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "test-accompanied-development": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:27.198Z",
+      "updatedAt": "2026-03-23T12:19:27.198Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "test-generator": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:27.401Z",
+      "updatedAt": "2026-03-23T12:19:27.401Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "vercel-react-best-practices": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:27.536Z",
+      "updatedAt": "2026-03-23T12:19:27.536Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    },
+    "verify-hardened-docker-skill": {
+      "version": "1.0.0",
+      "installedAt": "2026-03-23T12:19:27.724Z",
+      "updatedAt": "2026-03-23T12:19:27.724Z",
+      "installerVersion": "2.20.3",
+      "agentVersion": "1.0.0"
+    }
+  }
+}

package/.opencode/skills/MANIFEST.yaml

@@ -0,0 +1,254 @@
+# 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.
+    applies_when:
+      - committing changes
+      - creating branches or PRs
+      - any code writing or modification task
+    always_load: true
+
+  - id: js-ts-dependency-mgmt
+    file: js-ts-dependency-mgmt/SKILL.md
+    description: Standardize package management and security across NPM, Yarn, and PNPM.
+    applies_when:
+      - managing JavaScript or TypeScript project dependencies
+      - configuring package.json, npmrc, or lockfiles
+      - updating NPM/Yarn/PNPM packages
+      - auditing JS/TS supply chain security
+    always_load: true
+
+  - id: js-ts-security-skill
+    file: js-ts-security-skill/SKILL.md
+    description: Verify security of JavaScript and TypeScript codebases against OWASP Top 10 2025 standards
+    applies_when:
+      - writing or reviewing security-critical code
+      - analyzing third-party dependencies
+      - performing security audits
+
+  - id: logging-best-practices
+    file: logging-best-practices/SKILL.md
+    description: Standardizes structured logging across Backend, Frontend, Realtime, and Algorithmic domains with mandatory exception handling.
+    applies_when:
+      - writing new service classes
+      - reviewing or modifying existing log statements
+      - adding error handling
+
+  - id: open-presentation
+    file: open-presentation/SKILL.md
+    description: Opens the BMAD-METHOD AI Development Training presentation from _bmad-output/methodology/
+    applies_when:
+      - user types /open-presentation
+      - user asks to open the methodology presentation or training slides
+
+  - id: opentelemetry-best-practices
+    file: opentelemetry-best-practices/SKILL.md
+    description: Standardizes distributed tracing, metrics, and semantic conventions for high-quality system observability.
+    applies_when:
+      - implementing api endpoints
+      - handling distributed requests
+      - optimizing performance
+      - adding monitoring
+
+  - id: python-best-practices
+    file: python-best-practices/SKILL.md
+    description: Comprehensive Python coding standards covering PEP 8 conventions, type hinting (3.10+), modern patterns (match/case, exception groups), async, and packaging best practices. Cross-references security-focused Python skills.
+    applies_when:
+      - writing python code
+      - modifying python code
+      - creating new python files or modules
+      - reviewing python code style or conventions
+      - refactoring python code
+      - setting up a python project
+
+  - id: python-dependency-mgmt
+    file: python-dependency-mgmt/SKILL.md
+    description: Standardize Python dependency handling using uv and pip (requirements.txt).
+    applies_when:
+      - managing Python project dependencies
+      - configuring Python build systems
+      - updating requirements.txt or uv.lock
+      - setting up Python development environments
+    always_load: true
+
+  - id: python-security-skill
+    file: python-security-skill/SKILL.md
+    description: Enforce secure Python coding standards following OWASP Top 10 2025.
+    applies_when:
+      - writing or reviewing Python code
+      - managing Python dependencies
+      - configuring Python application environments
+      - handling sensitive data in Python
+    always_load: true
+
+  - id: self-signed-cert
+    file: self-signed-cert/SKILL.md
+    description: Generates secure self-signed certificates and Root CAs using OpenSSL.
+
+  - id: skill-creator
+    file: skill-creator/SKILL.md
+    description: Guide for creating effective skills that extend Claude's capabilities with specialized knowledge, workflows, and tool integrations
+
+  - id: story-status-lookup
+    file: story-status-lookup/SKILL.md
+    description: Looks up the current status of a story to classify code as delivered or work-in-progress. Supports file-system backend now; Jira backend reserved for future configuration.
+    always_load: true
+
+  - id: test-accompanied-development
+    file: test-accompanied-development/SKILL.md
+    description: Enforces writing unit tests for every new public method created by the agent.
+    applies_when:
+      - writing or reviewing public APIs
+      - adding new public methods to a class
+      - code review tasks
+
+  - id: test-generator
+    file: test-generator/SKILL.md
+    description: Generates comprehensive unit and integration tests
+    applies_when:
+      - creating new code files
+      - adding complex logic
+      - refactoring existing code
+
+  - id: vercel-react-best-practices
+    file: vercel-react-best-practices/SKILL.md
+    description: Performance optimization framework for React and Next.js projects with 57 actionable rules across 8 categories
+    applies_when:
+      - working on React or Next.js components
+      - optimizing page performance
+      - reviewing frontend code architecture
+
+  - id: verify-hardened-docker-skill
+    file: verify-hardened-docker-skill/SKILL.md
+    description: Comprehensive security verification for Docker configurations against CIS, OWASP, and NIST standards
+

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.