Agentic Development & Practices
Relevant source files
The following files were used as context for generating this wiki page:
Agentic Development & Practices in OpenWork refers to the framework and methodologies used to build, manage, and extend autonomous AI behaviors integrated with the OpenCode engine. The core philosophy is to treat the prompt as the primary workflow, utilizing local-first execution, least-privilege security, and transparent auditability to create a premium, "slick" experience for both technical power users and non-technical knowledge workers.
Sources: AGENTS.md:1-25, PRINCIPLES.md:1-20, PRODUCT.md:1-15
Core Development Philosophy
OpenWork development follows a "Self-building" and "Self-referential" approach, preferring prompts, skills, and composable primitives over bespoke hard-coded logic. The system is designed to be a thin UX layer on top of OpenCode’s native surfaces, such as folders, projects, and .opencode configurations.
Key Development Guidelines
- Purpose-first UI: Prioritize clarity and safety for non-technical users.
- Parity: Every UI action must map cleanly to OpenCode tools and server APIs.
- Self-referential: Maintain a gitignored mirror of OpenCode at
vendor/opencodefor architectural inspection. - Prompt-driven Workflows: Product logic should reside in prompts, rules, and skills rather than application code.
Sources: AGENTS.md:10-25, PRINCIPLES.md:15-25
Architecture and Extension Primitives
OpenWork leverages multiple OpenCode primitives to define agentic behavior. Choosing the right abstraction depends on the specific capability required.
| Primitive | Use Case | Description |
|---|---|---|
| Skills | Repeatable Patterns | Plain-English patterns that shape behavior; best for repeatability and legibility. |
| Plugins | Tooling & Scoping | Real tools in code with scoped permissions; safer than raw CLI. |
| MCP | Third-party Auth | Used for authenticated third-party flows (e.g., OAuth). |
| Agents | Multi-model Tasks | Used when tasks require execution by different models or specialized context. |
| Commands | Reusable Flows | / commands that trigger specific tools or templates. |
| Bash/CLI | Power Workflows | Highest risk; reserved for advanced users or internal prototyping. |
Sources: ARCHITECTURE.md:3-35, INFRASTRUCTURE.md:40-55
Runtime Configuration Flow
The following diagram illustrates how OpenWork initializes the OpenCode engine and manages workspace primitives.
The flow shows the distinction between Host and Client modes and how they both terminate in an event-driven SSE stream for UI updates.
Sources: ARCHITECTURE.md:40-70, PRODUCT.md:70-95
Skill Authoring and Triggers
Skills are the primary way to extend OpenWork with specialized knowledge. They are stored in .opencode/skills/<skill-name>/ and anchored by a SKILL.md file containing YAML frontmatter.
Trigger Mechanism
A critical component of a skill is its description, which acts as the trigger phrase selection mechanism. Claude uses this field to decide when to activate a skill.
- Requirement: Descriptions must include specific "triggers when" or "use when" phrases.
- Validation: Triggers should be longer than 50 characters and contain at least one quoted phrase to ensure specificity.
- Storage: Skills should be credential-safe and self-building, avoiding hard-coded secrets.
Sources: packages/app/src/app/data/skill-creator.md:5-40, packages/app/pr/skill-creator-triggers.md:35-55
Skill Metadata Structure
---
name: content-manager
description: |
Manages the publication pipeline for blog posts.
Triggers when user mentions:
- "content pipeline"
- "add to my content database"
- "schedule a post"
---
Sources: packages/app/src/app/data/skill-creator.md:40-50
Task Execution and Permissions
OpenWork maps every user outcome to an OpenCode Session. The lifecycle of a task run is fully auditable and requires explicit user intent for sensitive actions.
Permission Workflow
OpenWork enforces a "Default Deny" policy for anything outside authorized roots. Permissions are managed via SSE events and must be surfaced clearly to the user.
This diagram demonstrates the interception of permission requests by the UI before a tool call can proceed.
Sources: ARCHITECTURE.md:95-110, PRODUCT.md:120-135, packages/server/src/server.ts:470-490
Workspace Folder Authorization
OpenWork enforces safety through two layers:
- UI Authorization: Users explicitly select allowed folders via a native picker.
- Server Enforcement: The underlying OpenCode instance requests permission for specific file operations within those roots.
Sources: ARCHITECTURE.md:175-195, PRINCIPLES.md:10-15
Infrastructure and Sidecar Management
OpenWork acts as a lifecycle supervisor (Orchestrator) for the OpenCode engine. In Host mode, it manages the engine lifecycle, including starting the server on loopback (default 127.0.0.1:4096).
API and Lifecycle Endpoints
The OpenWork Server provides endpoints for managing the environment without direct filesystem manipulation for remote clients.
| Endpoint | Method | Purpose |
|---|---|---|
/workspace/:id/engine/reload | POST | Forces OpenCode to re-read config (skills/plugins/MCP). |
/workspace/:id/plugins | POST/GET | Adds or lists plugins in opencode.json. |
/workspace/:id/skills | POST/GET | Upserts or lists skills in the workspace folder. |
/approvals | GET/POST | Host-only endpoint for managing remote permission requests. |
/workspace/:id/audit | GET | Retrieves the history of prompts, plans, and tool calls. |
Sources: packages/server/src/server.ts:180-250, ARCHITECTURE.md:130-150, packages/app/pr/openwork-orchestrator.md:40-60
Conclusion
Agentic Development & Practices within OpenWork emphasize a modular, prompt-centric architecture. By strictly adhering to OpenCode primitives and enforcing local-first security through explicit permissions and auditable logs, OpenWork provides a robust environment for both creating and running complex agentic workflows. The focus remains on portability, slick UI performance (60fps), and a mobile-native experience that leverages a desktop host as a powerful sidecar engine.
Sources: AGENTS.md:5-15, INFRASTRUCTURE.md:10-35, PRODUCT.md:5-15