Design Decisions¶
This document explains the "why" behind key architectural choices in Seer Agent Engine. Understanding these decisions helps you extend the system thoughtfully.
Why Plugin Architecture?¶
The Problem¶
Early agent implementations were monolithic:
agents/
├── seo-agent.md # 2000+ lines
├── analytics-agent.md # 1500+ lines
└── operations-agent.md # 1000+ lines
Issues:
- Token bloat: Full agent loaded every time, even for simple tasks
- No reuse: Similar patterns duplicated across agents
- Hard to maintain: Changes required understanding entire agent
- No versioning: Breaking changes affected everyone immediately
The Solution¶
Plugin architecture with separation of concerns:
plugins/
├── core-dependencies/ # Shared foundation
└── divisions/
└── seo/
├── commands/ # Specific workflows
└── skills/ # Behavioral patterns
Benefits:
- Modular loading: Only load what's needed
- Reusable standards: Write once, use everywhere
- Clear boundaries: Each piece has one job
- Independent versioning: Update parts without breaking whole
Why Not Just Use Commands?¶
Commands alone lack behavioral consistency. Without skills:
- Each command defines its own writing style
- No shared quality standards
- Inconsistent output across workflows
Skills provide the "how you think" layer that commands build on.
Why core-dependencies is Required¶
The Problem¶
Without a shared foundation:
seo-plugin/
├── hooks/user-prompt.sh # Activation logic
├── skills/writing-standards/ # Duplicate
└── skills/quality-standards/ # Duplicate
analytics-plugin/
├── hooks/user-prompt.sh # Same logic, different file
├── skills/writing-standards/ # Duplicate
└── skills/quality-standards/ # Duplicate
Every plugin reinvents:
- Skill activation hooks
- Writing standards
- Quality gates
- Diagnostic tools
The Solution¶
One required operating layer:
core-dependencies/ # Install once
├── hooks/ # All activation logic
├── skills/
│ ├── writing-standards/ # Single source
│ └── quality-standards/ # Single source
└── commands/
└── core-doctor.md # Diagnostics
seo-plugin/ # Thin, domain-only
├── skills/seo-methods/ # Domain-specific
└── commands/ # Workflows
Benefits:
- DRY: Standards defined once
- Consistent activation: Same hooks everywhere
- Easier updates: Change core, all plugins benefit
- Smaller plugins: Division plugins stay focused
Why Not Optional?¶
Making core-dependencies optional would:
- Allow inconsistent skill activation
- Duplicate shared standards
- Create compatibility issues between plugins
- Increase maintenance burden
Required dependency ensures ecosystem consistency.
Why Skills Auto-Activate¶
The Problem¶
Manual skill invocation is error-prone:
User: Write a content audit report
Agent: [Produces output without writing standards]
User: Use writing-standards skill
Agent: [Now applies standards]
Users must remember which skills exist and when to apply them.
The Solution¶
Context-driven activation via hooks:
User prompt arrives
↓
UserPromptSubmit hook fires
↓
Scan for matching keywords/patterns
↓
Inject: "Consider using writing-standards"
↓
Agent loads relevant skills
Benefits:
- Lower cognitive load: Users focus on task, not tools
- Consistent quality: Standards applied automatically
- Discoverability: Users learn skills exist through activation
Why "Suggest" Not "Require"?¶
Skills use enforcement: "suggest" by default because:
- Agent can assess if skill truly applies
- Edge cases exist where skill shouldn't apply
- Flexibility allows creative problem-solving
Critical standards can use enforcement: "require" when necessary.
Why Progressive Disclosure¶
The Problem¶
Large skill files waste tokens:
SKILL.md (2000 lines)
├── Quick reference
├── Detailed methodology
├── Edge cases
├── Examples
└── Historical context
Agent loads everything even for simple questions.
The Solution¶
Layered content with on-demand loading:
skills/seo-methods/
├── SKILL.md # < 500 lines (always loaded)
└── resources/
├── data-analysis.md # Loaded when needed
├── strategy.md # Loaded when needed
└── examples/ # Loaded when needed
SKILL.md contains:
- Core principles (always relevant)
- Quick reference (commonly needed)
- Pointers to resources (for deep dives)
Resources contain:
- Detailed methodologies
- Extended examples
- Edge case handling
Benefits:
- Token efficiency: Base cost is low
- Depth when needed: Full detail available
- Faster responses: Less to process initially
Why One Command = One Deliverable¶
The Problem¶
"God commands" that do everything:
Issues:
- Complex invocation:
/seo-toolkit --mode=audit --depth=full - Hard to document
- Difficult to maintain
- Unclear what each mode does
The Solution¶
Focused commands with clear outputs:
/content-audit → Audit report
/content-outline → Content blueprint
/search-landscape → SERP analysis
Benefits:
- Discoverable: Name describes what it does
- Predictable: Same input → same output type
- Maintainable: Change one without affecting others
- Junior-friendly: No flags to remember
What About Flexibility?¶
Commands can accept parameters:
But the core output (audit report) stays consistent.
Why Graceful Degradation¶
The Problem¶
Hard dependencies break workflows:
Users can't complete work when infrastructure is unavailable.
The Solution¶
Commands handle missing dependencies:
/content-audit
BigQuery unavailable. Please provide ranking data:
- Paste CSV from Search Console, or
- Enter keywords and positions manually
[Workflow continues with manual input]
Benefits:
- Resilient: Work continues despite failures
- Flexible: Works in environments without full MCP setup
- Educational: Users understand what data is needed
Implementation Pattern¶
## Data Collection
1. **Try** BigQuery for ranking data
2. **If unavailable**: Ask user for CSV paste
3. **If no CSV**: Ask for manual keyword list
4. **Continue** with whatever data is available
Why Dual Platform Support¶
The Problem¶
Vendor lock-in limits adoption:
- OpenCode users can't use Claude Code plugins
- Claude Code users can't use OpenCode configs
- Different teams use different tools
The Solution¶
Standard formats that work on both:
| Feature | Format | Works On |
|---|---|---|
| Skills | YAML frontmatter + Markdown | Both |
| Commands | YAML frontmatter + Markdown | Both |
| Manifests | JSON (plugin.json) | Both |
Benefits:
- Team flexibility: Use preferred tool
- Future-proof: Not tied to one platform
- Wider adoption: More users can contribute
Platform-Specific Features¶
Some features are platform-specific:
.opencode/config.json- OpenCode provider settings.claude/- Claude Code local settings
These are additive, not required.
Why Centralized Standards¶
The Problem¶
Distributed standards drift:
seo/skills/writing-tone.md # Version A
analytics/skills/writing.md # Version B (different)
operations/skills/style.md # Version C (also different)
Over time:
- Teams develop different voices
- Updates don't propagate
- Inconsistent client experience
The Solution¶
Single source in core-dependencies:
Division plugins reference, don't duplicate:
Benefits:
- Consistency: One voice across all outputs
- Easy updates: Change once, applies everywhere
- Clear ownership: Standards team owns core
What Can Divisions Customize?¶
Divisions add domain-specific methods, not replace shared standards:
Summary¶
| Decision | Why |
|---|---|
| Plugin architecture | Modularity, reuse, maintainability |
| Required core-dependencies | Consistency, DRY, ecosystem health |
| Auto-activating skills | Lower cognitive load, consistent quality |
| Progressive disclosure | Token efficiency, depth when needed |
| One command = one deliverable | Discoverability, predictability |
| Graceful degradation | Resilience, flexibility |
| Dual platform support | Team flexibility, future-proofing |
| Centralized standards | Consistency, easy updates |
Related¶
Explanation¶
- Architecture - Technical structure
- Understanding Skills - Skill concepts
Reference¶
- Skill Reference - Available skills
- Command Reference - Available commands
How-To¶
- Plugin Authoring - Building plugins