ma-agents 3.2.0 → 3.3.0

package/.roo/skills/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import sys
+import re
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+from pathlib import Path
+
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+
+    # Check SKILL.md exists
+    skill_md = skill_path / 'SKILL.md'
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    # Read and validate frontmatter
+    content = skill_md.read_text()
+    if not content.startswith('---'):
+        return False, "No YAML frontmatter found"
+
+    # Extract frontmatter
+    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+
+    frontmatter_text = match.group(1)
+
+    # Parse YAML frontmatter
+    if yaml is None:
+        # Fallback: basic key-value parsing if PyYAML not installed
+        frontmatter = {}
+        for line in frontmatter_text.strip().split('\n'):
+            if ':' in line:
+                key, _, value = line.partition(':')
+                frontmatter[key.strip()] = value.strip()
+    else:
+        try:
+            frontmatter = yaml.safe_load(frontmatter_text)
+            if not isinstance(frontmatter, dict):
+                return False, "Frontmatter must be a YAML dictionary"
+        except yaml.YAMLError as e:
+            return False, f"Invalid YAML in frontmatter: {e}"
+
+    # Define allowed properties
+    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
+
+    # Check for unexpected properties
+    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
+    if unexpected_keys:
+        return False, (
+            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
+            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
+        )
+
+    # Check required fields
+    if 'name' not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if 'description' not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    # Validate name
+    name = frontmatter.get('name', '')
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name = name.strip()
+    if name:
+        if not re.match(r'^[a-z0-9-]+$', name):
+            return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
+        if name.startswith('-') or name.endswith('-') or '--' in name:
+            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+        if len(name) > 64:
+            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
+
+    # Validate description
+    description = frontmatter.get('description', '')
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description = description.strip()
+    if description:
+        if '<' in description or '>' in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+        if len(description) > 1024:
+            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
+
+    # Validate compatibility if present
+    compatibility = frontmatter.get('compatibility', '')
+    if compatibility:
+        if not isinstance(compatibility, str):
+            return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
+        if len(compatibility) > 500:
+            return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."
+
+    return True, "Skill is valid!"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)

package/.roo/skills/story-status-lookup/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: story-status-lookup
+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.
+---
+# Story Status Lookup
+
+Look up the current status of a story to determine whether its code is **delivered** or **work-in-progress**.
+
+## Purpose
+
+Used by other skills (notably `auto-bug-detection`) to classify code before deciding whether to flag defects.
+Do not flag bugs in WIP code. Do flag bugs in delivered code.
+
+---
+
+## Backend Configuration
+
+Before performing a lookup, check the project context for the configured sprint management backend.
+
+**Where to look (in priority order):**
+1. `project-context.md` in the project root — look for a `sprint_management` field
+2. The root directives file (`CLAUDE.md`, `.cursor/rules`, or equivalent for the active agent)
+3. If neither defines a backend, **default to `file-system`**
+
+| `sprint_management` value | Backend |
+|---|---|
+| `file-system` or not set | Read `sprint-status.yaml` (see below) |
+| `jira` | *(Future — see Jira section below)* |
+
+---
+
+## File-System Backend
+
+**Status file:** `_bmad-output/implementation-artifacts/sprint-status.yaml`
+
+### Step 1 — Identify the story slug
+
+Derive the story slug from the available context, in this order of preference:
+
+1. The story file name currently in scope (e.g. `11-1-auto-bug-detection-skill.md` → slug is `11-1-auto-bug-detection-skill`)
+2. The git branch name — strip prefixes (`feature/`, `fix/`, `chore/`) and normalize: lowercase, replace spaces and underscores with hyphens, remove non-alphanumeric characters except hyphens
+3. Any explicit story reference in the current task description
+
+### Step 2 — Look up the slug
+
+Find the slug as a key under `development_status` in `sprint-status.yaml`.
+
+### Step 3 — Map status to delivered / WIP
+
+| Status value | Classification | Action |
+|---|---|---|
+| `done` | **Delivered** | Flag bugs |
+| `review` | **Delivered** | Flag bugs — dev work is complete, code is awaiting review |
+| `in-progress` | WIP | Do not flag |
+| `ready-for-dev` | WIP | Do not flag |
+| `backlog` | WIP | Do not flag |
+| `on-hold` | WIP | Do not flag |
+
+### Fallback rule
+
+If any of the following are true, **classify as WIP and do not flag**:
+- The story slug cannot be determined from context
+- The slug is not found in `sprint-status.yaml`
+- The status file does not exist
+
+Never guess or assume delivered status. When in doubt, WIP.
+
+---
+
+## Future: Jira Backend
+
+When `sprint_management: jira` is set in the project context, this extension point applies:
+
+- Jira base URL, project key, and credentials will be defined in the project context or environment config
+- Query the Jira issue status API for the relevant issue key
+- Map the Jira workflow status to delivered/WIP using a status mapping defined in the project context
+
+**This backend is not yet implemented.** When Jira support is added, update this skill with the lookup procedure and status mapping. The file-system backend remains the default fallback if Jira is unreachable.

package/.roo/skills/test-accompanied-development/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: Test-Accompanied Development
+description: Enforces writing unit tests for every new public method created by the agent.
+---
+# Test-Accompanied Development (TAD)
+
+Enforce a "Test-Alongside" policy where every public method is accompanied by a corresponding unit test.
+
+## Purpose
+
+To ensure high code quality and maintainability by mandating that all public interfaces are verified by automated tests at the moment of creation.
+
+## Policy
+
+**Every new public method/function you write MUST be accompanied by at least one unit test.**
+
+## When to Use
+
+- Use this skill **every time** you are about to write a new public method or function.
+- This skill should be active during the coding phase of any feature or bug fix.
+
+## Instructions
+
+1.  **Identify Public Exports**: When preparing to write a new class, module, or function, identify which methods will be public/exported.
+2.  **Plan the Test**: Before or immediately after writing the method signature, plan the corresponding test cases (Happy Path, Edge Cases, Error Cases).
+3.  **Write the Method**: Implement the public method.
+4.  **Write the Tests**: Immediately write the unit tests for the method. 
+    - Refer to the `test-generator` skill for best practices on how to structure these tests (AAA pattern, Mocking, etc.).
+    - Ensure tests are placed in the appropriate test directory of the project.
+5.  **Verify**: Run the tests to ensure they pass before considering the method "done".
+
+## Rules
+
+- **No Public Method without Tests**: Do not consider a public method complete until its corresponding test file exists and passes.
+- **Refer to Test Generator**: Use the `test-generator` skill as the standard for test quality and structure.
+- **Traceability**: Mention the test file location when adding the public method.
+
+## Example Workflow
+
+### TypeScript (Jest)
+1.  **Agent**: "I am adding a `calculateTotal` method to the `InvoiceService`. I will also create `InvoiceService.test.ts` to verify it."
+2.  **Agent**: [Writes `calculateTotal` in `InvoiceService.ts`]
+3.  **Agent**: [Writes tests in `InvoiceService.test.ts` using `test-generator` patterns]
+4.  **Agent**: "Method and tests are complete. Running tests now..."
+
+### Python (Pytest)
+1.  **Agent**: "I am adding a `validate_user` function to `auth.py`. I will also create `tests/test_auth.py` to verify it."
+2.  **Agent**: [Writes `validate_user` in `auth.py`]
+3.  **Agent**: [Writes tests in `tests/test_auth.py` using `test-generator` patterns]
+4.  **Agent**: "Implementation and tests are ready. Running `pytest`."

package/.roo/skills/test-generator/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: Test Generator
+description: Generates comprehensive unit and integration tests
+---
+# Test Generator
+
+Generate comprehensive unit and integration tests for code.
+
+## Process
+
+1. **Analyze**: Understand code purpose, paths, dependencies, edge cases
+2. **Framework**: Determine or ask for testing framework
+3. **Generate**: Create test cases covering:
+   - Happy path (normal behavior)
+   - Edge cases (boundaries, empty/null inputs)
+   - Error cases (invalid inputs, exceptions)
+   - Integration scenarios (if applicable)
+
+## Test Structure (AAA Pattern)
+
+```
+- Arrange: Setup test data
+- Act: Execute code
+- Assert: Verify results
+```
+
+## Coverage Goals
+
+- 80%+ code coverage
+- All public methods
+- All conditional branches
+- Positive and negative cases
+
+## Best Practices
+
+- One assertion per test
+- Independent tests
+- Descriptive test names
+- Mock external dependencies
+- Clear assertion messages
+
+## Example Output
+
+```javascript
+describe('ComponentName', () => {
+  test('should [behavior] when [condition]', () => {
+    // Arrange
+    const input = setupTestData();
+
+    // Act
+    const result = functionUnderTest(input);
+
+    // Assert
+    expect(result).toEqual(expectedOutput);
+  });
+
+  test('should handle edge case', () => {
+    // ...
+  });
+
+  test('should throw on invalid input', () => {
+    expect(() => fn(invalid)).toThrow();
+  });
+});
+```

package/.roo/skills/vercel-react-best-practices/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: Vercel React Best Practices
+description: Performance optimization framework for React and Next.js projects with 57 actionable rules across 8 categories
+---
+# Vercel React Best Practices
+
+A thorough performance optimization framework for React and Next.js projects. Contains 57 actionable rules organized into 8 categories, ranked by potential impact.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components
+- Implementing data fetching
+- Reviewing code for performance concerns
+- Refactoring existing applications
+- Reducing bundle sizes and load times
+
+## Rule Categories (Priority-Ordered)
+
+### 1. Eliminating Waterfalls (CRITICAL)
+Prefix: `async-`
+
+- Avoid sequential data fetching — use parallel requests (`Promise.all`, `Promise.allSettled`)
+- Prefetch data at the layout/page level rather than in deeply nested components
+- Use `loading.tsx` and `Suspense` boundaries to stream content progressively
+- Avoid `await` chains where requests don't depend on each other
+- Colocate data fetching with the component that uses the data, but fetch in parallel at the route level
+- Use React Server Components to move data fetching to the server and eliminate client-server waterfalls
+
+### 2. Bundle Size Optimization (CRITICAL)
+Prefix: `bundle-`
+
+- Prefer `next/dynamic` or `React.lazy` for heavy components not needed on initial load
+- Audit dependencies with `@next/bundle-analyzer` — remove or replace bloated packages
+- Use tree-shakeable libraries and import only what you need (`import { x } from 'lib'` not `import lib from 'lib'`)
+- Mark client components with `'use client'` only at the lowest necessary level
+- Avoid importing server-only code into client components
+- Use `next/image` instead of raw `<img>` tags for automatic optimization
+- Use `next/font` to self-host fonts and eliminate external font requests
+
+### 3. Server-Side Performance (HIGH)
+Prefix: `server-`
+
+- Default to React Server Components — only add `'use client'` when interactivity is needed
+- Use the `cache()` function to deduplicate identical requests within a single render
+- Leverage `unstable_cache` or `fetch` cache options for cross-request caching
+- Set proper `revalidate` values — avoid `revalidate: 0` unless data truly changes on every request
+- Use `generateStaticParams` for static generation of dynamic routes
+- Move database queries and API calls to Server Components or Route Handlers
+- Use streaming (`loading.tsx`, `Suspense`) to avoid blocking the entire page on slow data
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+Prefix: `client-`
+
+- Use SWR or React Query for client-side data fetching with caching, revalidation, and deduplication
+- Implement optimistic updates for mutations to improve perceived performance
+- Set appropriate `staleTime` and `cacheTime` to avoid unnecessary refetches
+- Use `prefetchQuery` or `preload` to start fetching before navigation
+- Avoid `useEffect` + `fetch` patterns — prefer dedicated data fetching libraries
+- Paginate or infinitely scroll large datasets instead of loading everything at once
+
+### 5. Re-render Optimization (MEDIUM)
+Prefix: `rerender-`
+
+- Lift state up only as far as necessary — keep state close to where it's used
+- Split contexts to avoid triggering unnecessary re-renders on unrelated state changes
+- Use `useMemo` and `useCallback` only for expensive computations or stable references passed to memoized children
+- Avoid creating new objects/arrays in render — extract them as constants or memoize them
+- Use `React.memo` for pure components that re-render often with the same props
+- Prefer `useRef` over `useState` for values that don't need to trigger re-renders
+- Avoid prop drilling — use composition (`children` prop) instead of deep prop chains
+
+### 6. Rendering Performance (MEDIUM)
+Prefix: `rendering-`
+
+- Virtualize long lists with `react-window` or `@tanstack/virtual`
+- Debounce rapid user inputs (search, resize, scroll handlers)
+- Use CSS for animations and transitions instead of JS-driven re-renders
+- Use `content-visibility: auto` for off-screen content
+- Avoid layout thrashing — batch DOM reads and writes
+- Use `will-change` sparingly and only on elements that will actually animate
+- Prefer `transform` and `opacity` for GPU-accelerated animations
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+Prefix: `js-`
+
+- Avoid blocking the main thread — use `requestIdleCallback` or Web Workers for heavy computation
+- Use `Map` and `Set` for frequent lookups instead of arrays
+- Minimize closures in hot paths
+- Prefer `for...of` or `Array.prototype` methods over manual loops for readability, but use manual loops in performance-critical sections
+- Avoid deep cloning — use structural sharing (Immer) or shallow copies where possible
+- Use `AbortController` to cancel stale requests and avoid race conditions
+
+### 8. Advanced Patterns (LOW)
+Prefix: `advanced-`
+
+- Use the `Offscreen` API (when stable) for pre-rendering hidden UI
+- Implement route-level code splitting with parallel route segments
+- Use Edge Runtime for latency-sensitive API routes
+- Implement partial prerendering (PPR) for hybrid static/dynamic pages
+- Use `Server Actions` for form mutations to avoid manual API routes
+- Profile with React DevTools Profiler and Chrome Performance tab before optimizing
+
+## General Principles
+
+- **Measure before optimizing** — use Lighthouse, Web Vitals, and React DevTools
+- **Higher-priority categories yield larger gains** — focus on waterfalls and bundle size first
+- **Don't prematurely optimize** — only apply lower-priority rules after addressing critical ones
+- **Test performance changes** — verify improvements with real metrics, not just intuition