opencode-metis 0.1.0

package/opencode/skill/codebase-navigation/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: codebase-navigation
+description: "Navigate, search, and understand project structures for onboarding, locating implementations, tracing dependencies, and architecture analysis."
+license: MIT
+compatibility: opencode
+metadata:
+  category: analysis
+  version: "1.0"
+---
+
+# Codebase Navigation
+
+Roleplay as a codebase navigation specialist providing systematic patterns for navigating and understanding codebases efficiently.
+
+CodebaseNavigation {
+  Activation {
+    - Onboarding to a new codebase - Understanding project structure and conventions
+    - Locating specific implementations - Finding where functionality lives
+    - Tracing dependencies - Understanding how components connect
+    - Architecture analysis - Mapping system structure and boundaries
+    - Finding usage patterns - Discovering how APIs or functions are used
+    - Investigating issues - Tracing code paths for debugging
+  }
+
+  Constraints {
+    1. Start broad, then narrow down
+    2. Use glob for file discovery - faster than grep
+    3. Use grep for content search - supports regex and context
+    4. Narrow scope - search in specific directories when possible
+    5. Never search entire node_modules/vendor directories
+    6. Never assume structure without verifying
+    7. Never skip reading project documentation (README, CLAUDE.md)
+  }
+
+  QuickStructureAnalysis {
+    Step1_ProjectLayout {
+      ```bash
+      # Understand top-level structure
+      ls -la
+
+      # Find configuration files (reveals tech stack)
+      ls -la *.json *.yaml *.yml *.toml 2>/dev/null
+
+      # Check for documentation
+      ls -la README* CLAUDE.md docs/ 2>/dev/null
+      ```
+    }
+
+    Step2_SourceOrganization {
+      ```
+      # Find source directories
+      glob: **/src/**/*.{ts,js,py,go,rs,java}
+
+      # Find test directories
+      glob: **/{test,tests,__tests__,spec}/**/*
+
+      # Find entry points
+      glob: **/index.{ts,js,py} | **/main.{ts,js,py,go,rs}
+      ```
+    }
+
+    Step3_ConfigurationDiscovery {
+      ```
+      # Package/dependency files
+      glob: **/package.json | **/requirements.txt | **/go.mod | **/Cargo.toml
+
+      # Build configuration
+      glob: **/{tsconfig,vite.config,webpack.config,jest.config}.*
+
+      # Environment/deployment
+      glob: **/{.env*,docker-compose*,Dockerfile}
+      ```
+    }
+  }
+
+  DeepSearchStrategies {
+    FindingImplementations {
+      When locating where something is implemented:
+      
+      ```
+      # Find function/class definitions
+      grep: (function|class|interface|type)\s+TargetName
+
+      # Find exports
+      grep: export\s+(default\s+)?(function|class|const)\s+TargetName
+
+      # Find specific patterns (adjust for language)
+      grep: def target_name  # Python
+      grep: func TargetName  # Go
+      grep: fn target_name   # Rust
+      ```
+    }
+
+    TracingUsage {
+      When finding where something is used:
+      
+      ```
+      # Find imports of a module
+      grep: import.*from\s+['"].*target-module
+
+      # Find function calls
+      grep: targetFunction\(
+
+      # Find references (broad search)
+      grep: TargetName
+      ```
+    }
+
+    ArchitectureMapping {
+      When understanding system structure:
+      
+      ```
+      # Find all route definitions
+      grep: (app\.(get|post|put|delete)|router\.)
+
+      # Find database models/schemas
+      grep: (Schema|Model|Entity|Table)\s*\(
+      glob: **/{models,entities,schemas}/**/*
+
+      # Find service boundaries
+      glob: **/{services,controllers,handlers}/**/*
+      grep: (class|interface)\s+\w+Service
+      ```
+    }
+  }
+
+  ExplorationPatternsByGoal {
+    UnderstandEntryPoints {
+      ```
+      # Web application routes
+      grep: (Route|path|endpoint)
+      glob: **/routes/**/* | **/*router*
+
+      # CLI commands
+      grep: (command|program\.)
+      glob: **/cli/**/* | **/commands/**/*
+
+      # Event handlers
+      grep: (on|handle|subscribe)\s*\(
+      ```
+    }
+
+    FindConfiguration {
+      ```
+      # Environment variables
+      grep: (process\.env|os\.environ|env\.)
+
+      # Feature flags
+      grep: (feature|flag|toggle)
+
+      # Constants/config objects
+      grep: (const|let)\s+(CONFIG|config|settings)
+      glob: **/{config,constants}/**/*
+      ```
+    }
+
+    UnderstandDataFlow {
+      ```
+      # Database queries
+      grep: (SELECT|INSERT|UPDATE|DELETE|find|create|update)
+      grep: (prisma|sequelize|typeorm|mongoose)\.
+
+      # API calls
+      grep: (fetch|axios|http\.|request\()
+
+      # State management
+      grep: (useState|useReducer|createStore|createSlice)
+      ```
+    }
+  }
+
+  BestPractices {
+    SearchEfficiently {
+      1. Start with glob for file discovery - faster than grep for locating files
+      2. Use grep for content search - supports regex and context
+      3. Narrow scope - search in specific directories when possible
+      4. Check output modes - use `files_with_matches` for discovery, `content` for analysis
+    }
+
+    BuildMentalModels {
+      1. Map the layers - presentation, business logic, data access
+      2. Identify patterns - repository, service, controller, etc.
+      3. Note conventions - naming, file organization, code style
+      4. Document boundaries - where modules connect and separate
+    }
+
+    AvoidCommonPitfalls {
+      - Do not search entire node_modules/vendor directories
+      - Do not assume structure without verifying
+      - Do not skip reading project documentation (README, CLAUDE.md)
+      - Do not grep for common words without filtering (use glob filters)
+    }
+  }
+
+  OutputFormat {
+    After exploration, summarize findings:
+    
+    ```
+    ## Codebase Overview
+
+    **Tech Stack:** [Languages, frameworks, tools]
+    **Architecture:** [Monolith, microservices, modular, etc.]
+    **Entry Points:** [Main files, routes, handlers]
+
+    ## Key Directories
+
+    - `src/` - [Purpose]
+    - `lib/` - [Purpose]
+    - `tests/` - [Purpose]
+
+    ## Conventions Observed
+
+    - Naming: [Pattern]
+    - File organization: [Pattern]
+    - Testing: [Pattern]
+
+    ## Dependencies
+
+    - [Key dependency]: [Purpose]
+    - [Key dependency]: [Purpose]
+    ```
+  }
+}
+
+## References
+
+- [Exploration Patterns Examples](examples/exploration-patterns.md) - Detailed practical examples

package/opencode/skill/codebase-navigation/examples/exploration-patterns.md

@@ -0,0 +1,263 @@
+# Exploration Patterns Examples
+
+Practical examples demonstrating codebase exploration strategies for common scenarios.
+
+## Example 1: Onboarding to a New Project
+
+### Context
+
+You have been assigned to work on an unfamiliar codebase. You need to understand its structure, tech stack, and conventions before making changes.
+
+### Pattern
+
+```bash
+# Step 1: Read existing documentation first
+read: README.md
+read: CLAUDE.md (if exists)
+
+# Step 2: Identify tech stack from config files
+glob: package.json | requirements.txt | go.mod | Cargo.toml
+
+# Step 3: Map source structure
+glob: **/src/**/*.{ts,js,py,go}
+
+# Step 4: Find entry points
+glob: **/index.{ts,js} | **/main.{ts,js,py,go}
+
+# Step 5: Locate tests to understand expected behaviors
+glob: **/*.test.{ts,js} | **/*.spec.{ts,js} | **/test_*.py
+```
+
+### Explanation
+
+1. **Documentation first** - README and CLAUDE.md often contain project-specific conventions and commands
+2. **Config files reveal stack** - package.json shows Node.js, go.mod shows Go, etc.
+3. **Source mapping** - understand directory organization
+4. **Entry points** - find where execution begins
+5. **Tests as documentation** - tests reveal expected behaviors and usage patterns
+
+### Variations
+
+- For monorepos: Start with `glob: **/package.json` to find all packages
+- For microservices: Look for `glob: **/Dockerfile` to identify service boundaries
+- For legacy code: Check `glob: **/*.sql` for database schema clues
+
+### Anti-Patterns
+
+- Skipping documentation and assuming structure
+- Searching entire repo including node_modules/vendor
+- Making changes before understanding conventions
+
+---
+
+## Example 2: Finding Where a Feature is Implemented
+
+### Context
+
+You need to modify user authentication but do not know where the code lives.
+
+### Pattern
+
+```
+# Step 1: Search for obvious terms
+grep: (auth|login|authenticate)
+  glob: **/*.{ts,js,py}
+  output_mode: files_with_matches
+
+# Step 2: Find route definitions
+grep: (login|signin|auth).*route
+  glob: **/routes/**/*
+
+# Step 3: Locate service/handler
+grep: (AuthService|AuthHandler|authenticate)
+  output_mode: content
+  -C: 3
+
+# Step 4: Trace imports to find related files
+grep: import.*from.*auth
+  output_mode: files_with_matches
+```
+
+### Explanation
+
+1. **Broad search first** - Find all files mentioning authentication
+2. **Route definitions** - Locate API entry points
+3. **Service layer** - Find business logic implementations
+4. **Import tracing** - Discover related modules and dependencies
+
+### Variations
+
+- For frontend: `grep: (useAuth|AuthContext|AuthProvider)`
+- For database: `grep: (users|sessions).*table|schema`
+- For middleware: `grep: (middleware|interceptor).*auth`
+
+### Anti-Patterns
+
+- Searching for single common word like "user" (too many results)
+- Not narrowing scope after initial discovery
+- Ignoring test files (they often show usage patterns)
+
+---
+
+## Example 3: Understanding Data Flow
+
+### Context
+
+You need to understand how data moves from API request to database and back.
+
+### Pattern
+
+```
+# Step 1: Find API routes/handlers
+grep: (app\.(get|post)|router\.(get|post)|@(Get|Post))
+  glob: **/routes/**/* | **/controllers/**/*
+  output_mode: content
+  -C: 5
+
+# Step 2: Find service layer calls
+grep: (Service|Repository)\.(create|find|update|delete)
+  output_mode: content
+  -C: 3
+
+# Step 3: Find database operations
+grep: (prisma|sequelize|mongoose|typeorm)\.\w+\.(find|create|update)
+  output_mode: content
+
+# Step 4: Find data transformations
+grep: (map|transform|serialize|dto)
+  glob: **/{dto,mapper,transformer}/**/*
+```
+
+### Explanation
+
+1. **Start at API boundary** - Where requests enter the system
+2. **Follow to services** - Business logic layer
+3. **Track to database** - Data persistence layer
+4. **Find transformations** - How data changes between layers
+
+### Variations
+
+- For event-driven: `grep: (emit|publish|subscribe|on\()`
+- For GraphQL: `grep: (Query|Mutation|Resolver)`
+- For message queues: `grep: (queue|broker|consume|produce)`
+
+### Anti-Patterns
+
+- Starting from database and working up (harder to follow)
+- Ignoring middleware transformations
+- Missing async/await patterns that indicate I/O boundaries
+
+---
+
+## Example 4: Mapping Architecture Boundaries
+
+### Context
+
+You need to understand the high-level architecture to plan a refactoring effort.
+
+### Pattern
+
+```
+# Step 1: Find module/package boundaries
+glob: **/package.json | **/go.mod | **/__init__.py
+  (for monorepos: shows internal packages)
+
+# Step 2: Identify layers
+glob: **/{controllers,handlers,routes}/**/*
+glob: **/{services,usecases,domain}/**/*
+glob: **/{repositories,dal,data}/**/*
+
+# Step 3: Find external integrations
+grep: (axios|fetch|http\.|request\()
+  output_mode: files_with_matches
+glob: **/{clients,integrations,adapters}/**/*
+
+# Step 4: Map cross-cutting concerns
+glob: **/{middleware,interceptors,guards}/**/*
+grep: (logger|cache|metric|trace)
+```
+
+### Explanation
+
+1. **Package boundaries** - Physical separation of concerns
+2. **Architectural layers** - Presentation, business, data
+3. **External boundaries** - Where system meets outside world
+4. **Cross-cutting** - Shared functionality across layers
+
+### Variations
+
+- For microservices: Look for `glob: **/Dockerfile` and service definitions
+- For modular monolith: Check for internal API contracts
+- For plugin architecture: `grep: (plugin|extension|addon)`
+
+### Anti-Patterns
+
+- Assuming standard layer names (every project is different)
+- Missing hidden dependencies through global state
+- Not checking for circular dependencies
+
+---
+
+## Example 5: Investigating a Bug
+
+### Context
+
+Users report an error message: "Invalid token format". You need to find where this error originates.
+
+### Pattern
+
+```
+# Step 1: Search for exact error message
+grep: Invalid token format
+  output_mode: content
+  -C: 10
+
+# Step 2: Find related error handling
+grep: (throw|raise|Error).*token
+  output_mode: content
+  -C: 5
+
+# Step 3: Trace the code path
+# (after finding file, search for function callers)
+grep: validateToken|parseToken
+  output_mode: files_with_matches
+
+# Step 4: Check test files for expected behavior
+grep: Invalid token
+  glob: **/*.test.{ts,js} | **/test_*.py
+  output_mode: content
+```
+
+### Explanation
+
+1. **Exact match first** - Find the error source directly
+2. **Related errors** - Understand error handling context
+3. **Caller analysis** - Who invokes this code
+4. **Test context** - What is the expected behavior
+
+### Variations
+
+- For stack traces: Search for function names in the trace
+- For database errors: Check migration files and schema definitions
+- For runtime errors: Look for environment variable usage
+
+### Anti-Patterns
+
+- Guessing the source without searching
+- Not checking test files for expected behavior
+- Fixing symptom without understanding root cause
+
+---
+
+## Quick Reference: Search Strategy by Goal
+
+| Goal | Primary Tool | Pattern |
+|------|--------------|---------|
+| Find file by name | glob | `**/target-name*` |
+| Find file by content | grep | `pattern` with `files_with_matches` |
+| Understand function | grep | Function name with `-C: 10` for context |
+| Find all usages | grep | Call pattern with `files_with_matches` |
+| Map directory structure | glob | `**/src/**/*` |
+| Find configuration | glob | `**/*.{json,yaml,toml,env}` |
+| Trace dependencies | grep | Import/require patterns |
+| Find tests | glob | `**/*.test.* | **/*.spec.* | **/test_*` |

package/opencode/skill/coding-conventions/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: coding-conventions
+description: "Apply consistent security, performance, and accessibility standards across all recommendations and code reviews."
+license: MIT
+compatibility: opencode
+metadata:
+  category: analysis
+  version: "1.0"
+---
+
+# Coding Conventions
+
+Roleplay as a cross-cutting standards enforcer providing consistent security, performance, and quality standards across all agent recommendations.
+
+CodingConventions {
+  Activation {
+    - Reviewing code for security vulnerabilities
+    - Validating performance characteristics of implementations
+    - Ensuring accessibility compliance in UI components
+    - Designing error handling strategies
+    - Auditing existing systems for quality gaps
+  }
+
+  Constraints {
+    1. Apply security checks before performance optimization
+    2. Make accessibility a default, not an afterthought
+    3. Use checklists during code review, not just at the end
+    4. Document exceptions to standards with rationale
+    5. Automate checks where possible (linting, testing)
+  }
+
+  CoreDomains {
+    Security {
+      Covers common vulnerability prevention aligned with OWASP Top 10.
+      Apply these checks to any code that handles user input, authentication,
+      data storage, or external communications.
+
+      See: [security-checklist.md](checklists/security-checklist.md)
+    }
+
+    Performance {
+      Covers optimization patterns for frontend, backend, and database operations.
+      Apply these checks when performance is a concern or during code review.
+
+      See: [performance-checklist.md](checklists/performance-checklist.md)
+    }
+
+    Accessibility {
+      Covers WCAG 2.1 Level AA compliance.
+      Apply these checks to all user-facing components to ensure inclusive design.
+
+      See: [accessibility-checklist.md](checklists/accessibility-checklist.md)
+    }
+  }
+
+  ErrorHandlingPatterns {
+    All agents should recommend these error handling approaches.
+
+    ErrorClassification {
+      Distinguish between operational and programmer errors:
+
+      | Type | Examples | Response |
+      |------|----------|----------|
+      | **Operational** | Network failures, invalid input, timeouts, rate limits | Handle gracefully, log appropriately, provide user feedback, implement recovery |
+      | **Programmer** | Type errors, null access, failed assertions | Fail fast, log full context, alert developers - do NOT attempt recovery |
+    }
+
+    Pattern1_FailFastAtBoundaries {
+      Validate inputs at system boundaries and fail immediately with clear error messages.
+      Do not allow invalid data to propagate through the system.
+
+      ```javascript
+      // At API boundary
+      function handleRequest(input) {
+        const validation = validateInput(input);
+        if (!validation.valid) {
+          throw new ValidationError(validation.errors);
+        }
+        // Process validated input
+      }
+      ```
+    }
+
+    Pattern2_SpecificErrorTypes {
+      Create domain-specific error types that carry context about what failed and why.
+      Generic errors lose valuable debugging information.
+
+      ```javascript
+      class PaymentDeclinedError extends Error {
+        constructor(reason, transactionId) {
+          super(`Payment declined: ${reason}`);
+          this.reason = reason;
+          this.transactionId = transactionId;
+        }
+      }
+      ```
+    }
+
+    Pattern3_UserSafeMessages {
+      Never expose internal error details to users.
+      Log full context internally, present sanitized messages externally.
+
+      ```javascript
+      try {
+        await processPayment(order);
+      } catch (error) {
+        logger.error('Payment failed', {
+          error,
+          orderId: order.id,
+          userId: user.id
+        });
+        throw new UserFacingError('Payment could not be processed. Please try again.');
+      }
+      ```
+    }
+
+    Pattern4_GracefulDegradation {
+      When non-critical operations fail, degrade gracefully rather than failing entirely.
+      Define what is critical vs. optional.
+
+      ```javascript
+      async function loadDashboard() {
+        const [userData, analytics, recommendations] = await Promise.allSettled([
+          fetchUserData(),      // Critical - fail if missing
+          fetchAnalytics(),     // Optional - show placeholder
+          fetchRecommendations() // Optional - hide section
+        ]);
+
+        if (userData.status === 'rejected') {
+          throw new Error('Cannot load dashboard');
+        }
+
+        return {
+          user: userData.value,
+          analytics: analytics.value ?? null,
+          recommendations: recommendations.value ?? []
+        };
+      }
+      ```
+    }
+
+    Pattern5_RetryWithBackoff {
+      For transient failures (network, rate limits), implement exponential backoff
+      with maximum attempts.
+
+      ```javascript
+      async function fetchWithRetry(url, maxAttempts = 3) {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+          try {
+            return await fetch(url);
+          } catch (error) {
+            if (attempt === maxAttempts) throw error;
+            await sleep(Math.pow(2, attempt) * 100); // 200ms, 400ms, 800ms
+          }
+        }
+      }
+      ```
+    }
+
+    LoggingLevels {
+      | Level | Use For |
+      |-------|---------|
+      | ERROR | Operational errors requiring attention |
+      | WARN | Recoverable issues, degraded performance |
+      | INFO | Significant state changes, request lifecycle |
+      | DEBUG | Detailed flow for troubleshooting |
+
+      Log: Correlation IDs, user context (sanitized), operation attempted, error type, duration.
+      Never log: Passwords, tokens, secrets, credit card numbers, PII.
+    }
+  }
+}
+
+## References
+
+- [security-checklist.md](checklists/security-checklist.md) - OWASP-aligned security checks
+- [performance-checklist.md](checklists/performance-checklist.md) - Performance optimization checklist
+- [accessibility-checklist.md](checklists/accessibility-checklist.md) - WCAG 2.1 AA compliance checklist