| name | adapter-development-devforge |
| description | Use when building new adapter types, modifying existing adapters, or implementing adapter-specific features like model selection, token tracking, and environment variables. Handles claude_local, codex_local, opencode_local, gemini_local, hermes_local.
|
Adapter Development - DevForge AI
Overview
Handles adapter development for the Paperclip codebase. Creates new adapter types, modifies existing adapters, implements adapter-specific features like model selection, token tracking, environment variable injection, and ensures adapters integrate with the heartbeat/wake lifecycle.
When to Use
- When adding a new adapter type to
BUILTIN_ADAPTER_TYPES
- When adapterConfig fields need to be added or modified
- When model selection in adapterConfig doesn't persist between runs
- When adapter environment variables need new fields (PAPERCLIP_WAKE_ACTOR_TYPE)
- When
isLocal checks in UI miss a new adapter type
- When adapter execute.ts needs model API changes
- Don't use when: It's an adapter runtime error (use fixer-devforge-bug-fixing)
Core Procedures
New Adapter Workflow
- Define Adapter Type - Add to
BUILTIN_ADAPTER_TYPES in server adapters module
- Create Adapter Package - Follow existing
*-local adapter pattern in packages/adapters/
- Implement execute.ts - Handle model API calls, token tracking, error handling
- Add Adapter Config Schema - Define adapterConfig fields (model, thinking, etc.)
- Integrate Heartbeat - Ensure adapter works with heartbeat/wake lifecycle
- Write Adapter Tests - Match existing
*-local-adapter-environment.test.ts pattern
- Update UI - Add adapter to adapter type selector, update
isLocal checks
Common Adapter Patterns
- All
_local adapters: set isLocal = true for instructions bundle access
- Adapter env vars: export
PAPERCLIP_* vars from execute.ts contextSnapshot
- Config persistence: ensure adapterConfig is saved to DB, not just env vars
Agent Assignment
Primary Agent: codesmith-devforge-backend-engineer
Company: DevForge AI
Role: Adapter Development Specialist
Reports To: codesmith-devforge-backend-engineer
Backup Agents: devcore-devforge-core-development, interface-devforge-api-integration
Success Metrics
- New adapter works with heartbeat/wake lifecycle
- Model selection persists across runs
- UI
isLocal checks include all local adapter types
- Adapter env vars properly exported
Error Handling
- Error: Adapter config resets between runs
Response: Check config persistence, ensure adapterConfig is saved to DB
- Error: UI misses adapter in isLocal check
Response: Add adapter type to isLocal disjunction or derive from suffix
Cross-Team Integration
Gigabrain Tags: devforge, adapter, model-selection, heartbeat, environment-variables
Related Skills: codesmith-devforge-backend-engineer, devcore-devforge-core-development, interface-devforge-api-integration
Last Updated: 2026-04-07
