Skip to content

opencode-integration-guide.md

Latest commit

 

History

History
240 lines (175 loc) · 8.41 KB

opencode-integration-guide.md

File metadata and controls

240 lines (175 loc) · 8.41 KB
Raw

AQE OpenCode Integration Guide

Version: 1.0.0 Last Updated: 2026-02-24 Status: Production-ready

Quick Start

1. Install AQE

npm install -g agentic-qe
# or use npx
npx agentic-qe init --wizard

2. Add MCP Server to OpenCode

Add the AQE MCP server to your opencode.json:

{
  "mcp": {
    "agentic-qe": {
      "type": "local",
      "command": "npx",
      "args": ["agentic-qe", "mcp"],
      "env": {
        "AQE_MEMORY_PATH": ".agentic-qe/memory.db",
        "AQE_V3_MODE": "true",
        "AQE_V3_HNSW_ENABLED": "true"
      }
    }
  }
}

For SSE transport (remote deployment):

{
  "mcp": {
    "agentic-qe-sse": {
      "type": "sse",
      "url": "http://localhost:3100/sse",
      "env": {
        "AQE_V3_MODE": "true"
      }
    }
  }
}

3. Copy Agent and Skill Configs

cp -r .opencode/agents/ ~/.opencode/agents/
cp -r .opencode/skills/ ~/.opencode/skills/
cp .opencode/permissions.yaml ~/.opencode/permissions.yaml

Configuration

MCP Server Options

Option Description Default
AQE_MEMORY_PATH Path to SQLite memory database .agentic-qe/memory.db
AQE_V3_MODE Enable v3 architecture true
AQE_V3_HNSW_ENABLED Enable HNSW vector search true
AQE_MAX_AGENTS Maximum concurrent agents 15
AQE_TOPOLOGY Swarm topology hierarchical

Plugin Hooks

AQE integrates with OpenCode's lifecycle through hooks:

  • SessionStart: Initializes learning patterns, loads memory
  • PostTask: Captures experience for dream cycle learning
  • SessionEnd: Persists session knowledge

Agent Selection

Agents are auto-selected based on task type. Override with explicit agent references in your prompts or use the model_route MCP tool for tier-aware routing.

Available Agents

Agent Description Model Tier
qe-test-architect AI-powered test generation with pattern recognition tier3-best
qe-tdd-specialist TDD Red-Green-Refactor workflow guidance tier2-good
qe-coverage-analyst O(log n) sublinear coverage gap detection tier2-good
qe-security-scanner SAST/DAST security vulnerability scanning tier3-best
qe-defect-predictor ML-powered defect prediction from code metrics tier3-best
qe-code-reviewer Context-driven code review with quality scoring tier2-good
qe-debugger Hypothesis-driven autonomous debugging tier3-best
qe-performance-engineer Performance testing and bottleneck analysis tier2-good
qe-api-tester API contract testing and endpoint validation tier2-good
qe-accessibility-auditor WCAG 2.1/2.2 accessibility testing tier2-good

Available Skills

Quality Engineering Core

Skill Description Tier
qe-test-design-techniques Boundary value, equivalence partitioning, pairwise tier2-good
qe-tdd-london-chicago London (mock-based) and Chicago (state-based) TDD tier2-good
qe-debug-loop Hypothesis-driven autonomous debugging loop tier3-best
qe-regression-testing Regression risk analysis and test selection tier2-good
qe-mutation-testing Mutation testing for test suite effectiveness tier3-best

Security & Compliance

Skill Description Tier
qe-security-testing OWASP Top 10 vulnerability testing tier3-best
qe-compliance-testing GDPR, HIPAA, SOC2 compliance checks tier1-any
qe-accessibility-testing WCAG automated accessibility audits tier2-good

Analysis & Reporting

Skill Description Tier
qe-code-review-quality Context-driven code review tier2-good
qe-risk-based-testing Risk-based test prioritization tier2-good
qe-performance-testing Load, stress, and endurance testing tier2-good
qe-exploratory-testing-advanced Charter-based exploratory testing tier2-good

API & Contract Testing

Skill Description Tier
qe-api-testing-patterns REST/GraphQL API test patterns tier2-good
qe-contract-testing Consumer-driven contract testing tier2-good
qe-chaos-engineering-resilience Chaos engineering resilience testing tier3-best

QCSD Workflow (Swarm)

Skill Phase Description
qcsd-ideation Ideation Quality criteria sessions with HTSM v6.3 and Risk Storming
qcsd-refinement Refinement SFDIPOT product factors and BDD scenario generation
qcsd-development Development TDD adherence, complexity analysis, coverage gaps
qcsd-cicd Verification Regression analysis, flaky detection, quality gates
qcsd-production Production DORA metrics, RCA, cross-phase feedback loops

Custom Composite Tools

AQE registers 40+ MCP tools. Key composite tools for common workflows:

Tool Description Use Case
task_orchestrate Multi-agent task orchestration Complex QE workflows spanning multiple domains
test_generate_enhanced AI-powered test generation Generate unit/integration/e2e tests with pattern recognition
coverage_analyze_sublinear O(log n) coverage analysis Fast coverage gap detection for large codebases
security_scan_comprehensive Combined SAST+DAST scanning Pre-deployment security validation
defect_predict ML defect prediction Identify high-risk code areas before they become bugs

Provider Compatibility

AQE uses a 3-tier model classification for graceful degradation:

  • tier1-any: Any model works (formatting, checklists, data management)
  • tier2-good: Needs decent reasoning (test generation, code review, coverage)
  • tier3-best: Needs advanced reasoning (security, mutation testing, QCSD swarms)

See Provider Capability Matrix for full provider-to-tier mapping.

Degradation Behavior

Behavior Description
warn Skill runs with a quality warning
block Skill is blocked (security-critical skills)
use-fallback Automatically falls back to a simpler skill

QCSD Workflow

The Quality Criteria-driven Software Development (QCSD) workflow runs as a 4-phase quality swarm:

  1. Ideation → Quality criteria analysis, risk storming, testability scoring
  2. Refinement → SFDIPOT product factors, BDD scenario generation, requirements validation
  3. Development → TDD adherence, complexity analysis, coverage gap detection, defect prediction
  4. Verification (CI/CD) → Regression analysis, flaky test detection, quality gates, deployment readiness
  5. Production → DORA metrics, root cause analysis, feedback loops to Ideation

Each phase consumes outputs from the previous phase via shared memory, creating a continuous quality feedback loop.

Troubleshooting

Cold Start Latency

The first MCP tool invocation may take 2-5 seconds as the server initializes memory, loads patterns, and sets up HNSW indexes.

Mitigation: Run npx agentic-qe mcp as a background process, or use the SessionStart hook to pre-warm.

Token Limit Exceeded

Large tool outputs (coverage reports, security scans) may exceed OpenCode's context budget.

Mitigation: AQE automatically compacts outputs to stay under 35k tokens. If you see truncated results, use memory_store to save the full report and memory_retrieve to fetch specific sections.

Provider Degradation

If your model provider doesn't meet the minimum tier for a skill, AQE will:

  1. Warn for most skills (reduced quality but functional)
  2. Block for security-critical skills
  3. Fallback to a simpler skill where configured

Check model_route tool to see tier recommendations for your current provider.

Memory Database Issues

If the memory database becomes corrupted:

# Backup first
cp .agentic-qe/memory.db .agentic-qe/memory.db.bak

# Remove stale WAL/SHM files
rm -f .agentic-qe/memory.db-wal .agentic-qe/memory.db-shm

# Verify integrity
sqlite3 .agentic-qe/memory.db "PRAGMA integrity_check;"

Connection Issues (SSE/WebSocket)

For remote MCP server connections:

# Test SSE endpoint
curl http://localhost:3100/sse

# Test WebSocket endpoint
wscat -c ws://localhost:3100/ws

Verify AQE_V3_MODE=true is set in the environment.