Metis Agent

{
  "model": "claude-opus-4-6",
  "variant": "max",
  "temperature": 0.3,
  "thinking": {
    "type": "enabled",
    "budgetTokens": 32000
  }
}

{
  "model": "gpt-5.2",
  "variant": "high",
  "temperature": 0.3,
  "reasoningEffort": "high"
}

{
  "model": "gemini-3.1-pro",
  "variant": "high",
  "temperature": 0.3
}

## Intent Classification
**Type**: [Refactoring | Build | Mid-sized | Collaborative | Architecture | Research]
**Confidence**: [High | Medium | Low]
**Rationale**: [Why this classification]

## Pre-Analysis Findings
[Results from explore/librarian agents if launched]
[Relevant codebase patterns discovered]

## Questions for User
1. [Most critical question first]
2. [Second priority]
3. [Third priority]

## Directives for Prometheus

### Core Directives
- MUST: [Required action]
- MUST: [Required action]
- MUST NOT: [Forbidden action]
- MUST NOT: [Forbidden action]
- PATTERN: Follow `[file:lines]`
- TOOL: Use `[specific tool]` for [purpose]

### QA/Acceptance Criteria Directives (MANDATORY)
- MUST: Write acceptance criteria as executable commands
- MUST: Include exact expected outputs
- MUST NOT: Create criteria requiring "user manually tests..."
- MUST NOT: Use placeholders without concrete examples

// User request
"Add user authentication to the API"

task(
  subagent_type="metis",
  description="Analyze authentication requirements",
  prompt="User requested: Add user authentication to the API. 
          Perform pre-planning analysis."
)

// Metis response:
"## Intent Classification
**Type**: Build from Scratch
**Confidence**: High
**Rationale**: New feature, no existing auth system mentioned

## Pre-Analysis Findings

Launched explore agent to find existing patterns:
- Found Express.js app in `src/server.ts`
- No existing auth middleware
- Current endpoints: `/api/users`, `/api/posts` (no protection)
- Uses PostgreSQL for data storage

## Questions for User

1. **Authentication method**: JWT tokens, sessions, or OAuth?
   - JWT is stateless and works well with APIs
   - Sessions require session storage (Redis)
   - OAuth delegates to third-party (Google, GitHub)

2. **What endpoints need protection?**
   - All `/api/*` routes?
   - Only specific routes (POST/PUT/DELETE)?
   - Public read, protected write?

3. **User registration flow**:
   - Email/password signup?
   - Email verification required?
   - Social login options?

4. **Password requirements**:
   - Minimum length, special characters?
   - Or follow existing company policy?

5. **Scope boundaries** (AI-slop prevention):
   - Add authentication ONLY, or also:
     * Authorization (roles/permissions)?
     * Password reset flow?
     * Rate limiting?
     * Refresh tokens?

## Identified Risks

- **Security misconfiguration**: JWT secrets, bcrypt rounds, token expiry
  - Mitigation: Use environment variables, follow OWASP guidelines

- **Backward compatibility**: Existing API clients may break
  - Mitigation: Define migration strategy (grace period with opt-in?)

- **Scope creep**: Auth often expands to roles, permissions, MFA
  - Mitigation: Define explicit exclusions upfront

## Directives for Prometheus

### Core Directives
- MUST: Follow Express middleware pattern from `src/server.ts:15-30`
- MUST: Store passwords with bcrypt (12 rounds minimum)
- MUST: Use environment variables for secrets (never hardcode)
- MUST NOT: Add authorization (roles/permissions) unless explicitly requested
- MUST NOT: Implement password reset flow unless explicitly requested
- MUST NOT: Add OAuth providers unless explicitly requested
- PATTERN: Follow error handling pattern from `src/middleware/error-handler.ts`

### QA/Acceptance Criteria Directives (MANDATORY)
- MUST: Write executable tests, not manual steps
- MUST: Use curl commands for API verification
- MUST: Include exact expected responses (JSON structure, status codes)
- MUST NOT: Require "user manually tests login page"
- MUST NOT: Use placeholders like "[your-token]" without concrete example

Example of GOOD acceptance criteria:
```bash
# Register new user
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"TestPass123!"}'
# Expected: {"success":true,"userId":1}

# Login
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"TestPass123!"}'
# Expected: {"token":"eyJhbGc...","expiresIn":3600}

# Access protected endpoint
curl http://localhost:3000/api/users \
  -H "Authorization: Bearer eyJhbGc..."
# Expected: [{"id":1,"email":"[email protected]"}]

### Example 2: Refactoring

```typescript
// User request
"Refactor the authentication service to use a cleaner structure"

task(
  subagent_type="metis",
  description="Analyze refactoring requirements",
  prompt="User requested: Refactor the authentication service. 
          Perform pre-planning analysis."
)

// Metis response:
"## Intent Classification
**Type**: Refactoring
**Confidence**: High
**Rationale**: Explicit refactor request, existing code modification

## Pre-Analysis Findings

Analyzed existing authentication service:
- `src/services/auth.ts` (450 lines, multiple responsibilities)
- Handles: token generation, password hashing, user validation, session management
- Tests exist: `src/services/auth.test.ts` (28 tests, all passing)

## Questions for User

1. **Behavior preservation** (CRITICAL for refactoring):
   - Must all 28 tests continue passing without modification?
   - Or can we update tests if behavior intentionally changes?

2. **Refactoring scope**:
   - Restructure `auth.ts` only?
   - Or also related files (middleware, routes)?

3. **What specific structure issues?**:
   - Too many responsibilities in one file?
   - Unclear function naming?
   - Hard to test?
   - Performance problems?

4. **Rollback strategy**:
   - Can we use feature flag to toggle old/new implementation?
   - Or is direct replacement acceptable?

## Identified Risks

- **Regression introduction**: Changing working code may break subtle behaviors
  - Mitigation: Run full test suite after EACH file change, not just at end

- **Adjacent code changes**: Refactor may require updating callers
  - Mitigation: Use `lsp_find_references` to map all usages first

- **Scope creep**: "Clean structure" may expand to adding new features
  - Mitigation: Define "Must NOT change behavior" directive

## Directives for Prometheus

### Core Directives
- MUST: Define pre-refactor verification (exact test command + expected output)
- MUST: Use `lsp_find_references` to map all usages of functions being moved
- MUST: Verify tests pass after EACH change, not just at the end
- MUST: Use `lsp_rename` for safe symbol renames across codebase
- MUST NOT: Change behavior while restructuring
- MUST NOT: Add new features during refactoring
- MUST NOT: Refactor adjacent code not explicitly in scope
- TOOL: Use `ast_grep_replace(dryRun=true)` to preview transformations

### Pre-Refactor Verification
```bash
bun test src/services/auth.test.ts
# Expected: All 28 tests pass

curl -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"ExistingPass123"}'
# Expected: Same response format as before refactoring

### Example 3: Architecture Decision

```typescript
// User request
"How should we structure the new microservices architecture?"

task(
  subagent_type="metis",
  description="Analyze architecture requirements",
  prompt="User asked: How should we structure the new microservices? 
          Perform pre-planning analysis."
)

// Metis response:
"## Intent Classification
**Type**: Architecture
**Confidence**: High
**Rationale**: System design decision with long-term implications

## Questions for User

1. **Why microservices?** (Verify need before proceeding)
   - What specific problem are you solving?
   - Current monolith issues: Performance? Team scaling? Deployment?
   - Microservices add complexity - is the tradeoff justified?

2. **Scale and constraints**:
   - Expected request volume? (current and 12-month projection)
   - Team size? (impacts coordination overhead)
   - Deployment environment? (K8s? AWS ECS? Serverless?)

3. **Service boundaries**:
   - Bounded contexts already identified?
   - Or need help defining service splits?

4. **Non-negotiable constraints**:
   - Technology stack requirements?
   - Security/compliance needs?
   - Budget limitations?

5. **Integration requirements**:
   - What existing systems must this integrate with?
   - API compatibility requirements?

## Directives for Prometheus

### Core Directives
- MUST: Consult Oracle agent before finalizing architecture plan
- MUST: Document architectural decisions with rationale
- MUST: Define "minimum viable architecture" (avoid over-engineering)
- MUST NOT: Over-engineer for hypothetical future requirements
- MUST NOT: Add unnecessary abstraction layers
- MUST NOT: Ignore existing patterns for "better" design
- MUST NOT: Introduce complexity without clear justification

### Oracle Consultation
```typescript
task(
  subagent_type="oracle",
  prompt="Architecture consultation:
  
  Request: Microservices architecture design
  Current state: [gathered context from user answers]
  
  Analyze:
  - Architecture options and tradeoffs
  - Service boundary recommendations
  - Long-term implications
  - Technical risks and mitigations
  
  Apply pragmatic minimalism: simplest solution that meets actual needs."
)

## Best Practices

<Check>**Always classify intent first** - Determines entire analysis strategy</Check>
<Check>**Use explore/librarian agents** - Gather context before asking questions</Check>
<Check>**Ask specific questions** - "Should this change UserService only, or also AuthService?"</Check>
<Check>**Flag AI-slop patterns** - Prevent over-engineering upfront</Check>
<Check>**Provide actionable directives** - Give Prometheus clear guidance</Check>
<Check>**Ensure executable QA** - No "user manually tests" criteria</Check>

<Warning>**Don't skip exploration** - For Build/Research intents, discover patterns first</Warning>
<Warning>**Don't ask generic questions** - "What's the scope?" is too vague</Warning>
<Warning>**Don't make assumptions** - Question unclear requirements</Warning>

## Configuration

Customize Metis in `oh-my-opencode.jsonc`:

```jsonc
{
  "agents": {
    "metis": {
      "model": "anthropic/claude-opus-4-6",
      "variant": "max",
      "temperature": 0.3,
      "thinking": {
        "type": "enabled",
        "budgetTokens": 32000
      },
      "prompt_append": "Additional analysis guidelines...",
      "disable": false
    }
  }
}