opencode-sa-assistant

OpenCode plugin for AWS Solutions Architect assistance with multi-agent Guru system.

Overview

This plugin activates when you use the wadd keyword in your messages, transforming OpenCode into an AWS Solutions Architect assistant powered by 7 specialized agents:

4 Guru Agents (Philosophy & Wisdom):

• sa-bezos: Customer Obsession, Day 1, Working Backwards
• sa-vogels: Distributed Systems, Design for Failure
• sa-naval: Leverage, Asymmetric Outcomes
• sa-feynman: Simplification, First Principles

3 Specialist Agents (Execution):

• sa-explorer: Architecture analysis, diagram interpretation
• sa-researcher: AWS service information via MCP tools
• sa-reviewer: Well-Architected Framework reviews (6 pillars)

Orchestrator:

• sa-orchestrator: Master agent that coordinates Gurus and Specialists based on Guru_Mandate rules

Features

✨ WADD Mode Activation: Type wadd to activate SA mode
🧠 Multi-Agent System: 4 Gurus + 3 Specialists working together
📋 Guru_Mandate: Automatic expert consultation based on context
🏗️ Well-Architected Framework: All 6 pillars integrated
📚 AWS MCP Tools: Real-time AWS documentation access
🇰🇷 Bilingual: Korean prose + English technical terms

Agents

Guru Agents (Philosophy & Strategy)

| Agent | Core Principles | Use When | Avoid When | |-------|----------------|----------|------------| | sa-bezos | Customer Obsession, Day 1, Working Backwards | Customer value definition, Long-term vs short-term decisions, PR/FAQ writing | Pure technical implementation, Cost calculations | | sa-vogels | Everything Fails, Design for Failure, Loose Coupling | Distributed system design, Scalability/resilience patterns, Operational excellence | Business strategy, Cost ROI analysis | | sa-naval | Leverage, Asymmetric Outcomes, Compounding | Cost analysis, ROI, Leverage points identification, Complexity removal | Technical architecture details, Customer experience | | sa-feynman | Feynman Technique, First Principles, Simplicity | Complex concept simplification, Non-technical presentations, Learning materials | Detailed technical decisions, Cost analysis |

Specialist Agents (Execution)

| Agent | Role | Output | |-------|------|--------| | sa-explorer | Architecture analysis | Component discovery, Dependency mapping, As-Is documentation | | sa-researcher | AWS information gathering | Service info, Pricing, Best practices with evidence | | sa-reviewer | Well-Architected review | 6 Pillars evaluation, Risk summary, Prioritized recommendations |

Orchestrator

sa-orchestrator is the master agent that:

• Classifies user intent (Architecture Review, Service Selection, Cost Analysis, etc.)
• Invokes appropriate Gurus based on Guru_Mandate rules
• Delegates tasks to Specialists
• Enforces anti-patterns (no architecture decisions without Guru consultation)

Installation

Add the plugin to your opencode.json:

{
  "plugin": [
    "opencode-sa-assistant"
  ]
}

Usage

Basic Activation

In OpenCode, simply start your message with wadd:

wadd 이 Lambda 아키텍처를 리뷰해줘

The plugin will:

1. Detect the wadd keyword (case-insensitive, word boundary)
2. Activate SA mode (sets model to "max" variant)
3. Inject the SA Orchestrator system prompt
4. Consult appropriate Gurus based on Guru_Mandate rules

Guru_Mandate Rules

The orchestrator automatically consults Gurus based on context:

| Scenario | Gurus Consulted | |----------|-----------------| | Architecture design/review | vogels + bezos | | Cost decisions | naval + bezos | | Learning/explanation | feynman + relevant guru | | System design | vogels + naval | | Security/compliance | vogels + bezos | | Innovation | bezos + feynman |

Direct Agent Invocation

You can also directly request specific agents:

wadd bezos에게 고객 경험 관점에서 이 기능을 평가해달라고 해줘

Skills

The plugin includes 4 skill modules that are automatically installed to ~/.config/opencode/skills/:

• guru: Guru consultation patterns and philosophies
• mcp: AWS MCP tools reference (search_documentation, read_documentation)
• docx: AWS Blog-style document generation guidelines
• pptx: SA presentation templates

Skills are installed globally to ensure they are available before any plugin caching occurs. Use /skill guru or /skill mcp to load them.

Testing

# Run all tests
bun test

# Run specific test file
bun test src/__tests__/integration.test.ts

Test Coverage: 80 tests, 234 assertions, 100% pass rate

Development

Project Structure

packages/opencode-sa-assistant/
├── src/
│   ├── index.ts                     # Plugin entry point
│   ├── hooks/wadd-mode.ts           # WADD keyword detection
│   ├── agents/index.ts              # Agent/Skill installation
│   │   ├── prompts/
│   │   │   ├── orchestrator.ts          # SA Orchestrator
│   │   │   ├── gurus.ts                 # 4 Guru agents
│   │   │   └── specialists.ts           # 3 Specialist agents
│   │   ├── skills/
│   │   │   ├── guru/SKILL.md
│   │   │   ├── mcp/SKILL.md
│   │   │   ├── docx/SKILL.md
│   │   │   └── pptx/SKILL.md
│   │   └── __tests__/
│   │       └── *.test.ts                # 80 tests
├── package.json
├── tsconfig.json
└── bunfig.toml

Tech Stack

• Runtime: Bun
• Language: TypeScript
• Testing: Bun test
• Plugin SDK: @opencode-ai/plugin

Well-Architected Framework

The reviewer specialist covers all 6 pillars:

1. 운영 우수성 (Operational Excellence)
2. 보안 (Security)
3. 안정성 (Reliability)
4. 성능 효율성 (Performance Efficiency)
5. 비용 최적화 (Cost Optimization)
6. 지속 가능성 (Sustainability)

AWS MCP Integration

The plugin integrates with AWS Documentation MCP for real-time information:

• aws-docs_search_documentation: Search AWS documentation
• aws-docs_read_documentation: Fetch specific documentation pages
• aws-docs_recommend: Get related documentation

License

MIT

Author

Jisan Bang ([email protected])

Contributing

Contributions are welcome! Please ensure:

• All tests pass (bun test)
• TDD protocol followed (RED → GREEN → REFACTOR)
• Korean + English bilingual content preserved
• Conventional commit format used

Changelog

v0.2.7 (2026-02-06)

Phase 2 & 3 Improvements:

• Naval Guru: Added concrete AWS cost examples (RI vs On-Demand, Serverless crossover, IaC ROI)
• PPTX Skill: Implemented move slide operation in rearrange.py
• Orchestrator: Added cross-agent communication pattern for Guru conflict resolution
• MCP Skill: Added error handling documentation and aws-docs_recommend tool docs
• Explorer: Added confidence levels (🟢 HIGH / 🟡 MEDIUM / 🔴 LOW)
• Reviewer: Added Well-Architected Pillar tradeoff guide
• DOCX Skill: Added Header/Footer/ToC (Table of Contents) examples

v0.2.6 (2026-02-05)

• feat(docx-skill): Add diagram, code block, and table improvements
• feat(pptx-skill): Add missing scripts (inventory, replace, thumbnail, ooxml) and documentation
• Version bump for npm publish

v0.2.5 (2026-02-05)

• Fix: Skills now installed to global location (~/.config/opencode/skills/)
  • Resolves oh-my-opencode cache timing issue
  • Skills are now available via /skill command immediately
• Test coverage: 80 tests, 234 assertions

v0.2.4 (2026-02-05)

• Added skill installation to .opencode/skills/
• Skills: guru, mcp, docx, pptx

v0.2.3 (2026-02-05)

• Aligned wadd hook with oh-my-opencode pattern
• Added removeCodeBlocks() for keyword detection

v0.1.0 (2026-02-05)

• Initial release
• 7 agent types (4 Gurus + 3 Specialists)
• WADD mode activation
• Guru_Mandate consultation system
• Well-Architected Framework integration
• AWS MCP tools support