execute-code

name	execute-code
description	Use `execute-code` to get "Technical Design" when you must design technical tasks, implement features or refactor code.

Technical Design

Architectural Overview

OpenCode plugin that injects agents, commands, tools, and generated skills. Runtime merges repo config with user config, enforces sandbox/external-directory policies, and manages lifecycle jobs under .agents/jobs/.

Technology Choices

• TypeScript: Strong typing for SDK hooks, tools, and config merging.
• @opencode-ai SDK/plugin: Native integration point for agents, commands, and tool APIs.
• JSONC config: User/project overrides without losing comments.
• Markdown skills: Bundled from src/skills/*/SKILL.md into generated skill paths.

Key Data Models

• AgentConfig (src/agents/index.ts): Agent prompt, permissions, model tier, and sandbox policy.
• Autocode config (src/config.ts): Tier map, external directory rules, sandbox sync settings.
• Job lifecycle state (src/utils/jobs.ts): concepts → drafts → assist/executing/facilitate/review → shelved.
• ManagedSkillDefinition (src/skills/index.ts): Bundled skill frontmatter + body.

Key API Endpoints

• /job-concepts (src/commands/index.ts): Save concept markdown.
• /job-design (src/commands/index.ts): Read concept, create plan.
• /job-draft (src/commands/index.ts): Save plan to draft folder.
• /job-execute-assist (src/commands/index.ts): Start assisted execution session.
• /job-execute-auto (src/commands/index.ts): Start autonomous execution session.
• /job-review-commit (src/commands/index.ts): Check criteria, shelve accepted work.
• /job-shelve (src/commands/index.ts): Close job without acceptance.

Error Handling

• Tool error JSON (src/utils/tools.ts): Normalized failedAction, error, instruction payloads.
• Retry/abort escalation (src/utils/tools.ts): Same failure retries up to 5, then abort.
• Config parse errors (src/config.ts): Malformed JSONC throws with file path.
• Session/tool failures (src/tools/*): Abort or retry based on tool-specific instruction text.

Security Design

Auth is delegated to OpenCode session/client context. Security control is mostly permission policy: agents default-deny, then selectively allow task/tool access, external directories, and sandbox tools. applyExternalDirectoryPolicy() and applySandboxPlatformPolicy() remove unsafe access when platform support is missing. No secrets are stored in repo config; use ${ENV_VAR} placeholders.

External Integrations

• OpenCode client/session APIs (src/tools, src/utils/jobs.ts): Session create/update/prompt and job orchestration — SDK
• Filesystem (src/config.ts, src/utils/jobs.ts, src/skills/index.ts): Reads local/project/global config and job files — Node fs
• Sandbox runtime (src/tools/autocode_sandbox_*, src/agents/index.ts): Creates/cleans sandboxes and gates unsupported platforms — local process

Directory Structure

• Agents (src/agents/): Primary prompts, rules, and agent definitions.
• Commands (src/commands/): Programmatic command templates.
• Tools (src/tools/): OpenCode tool implementations and tests.
• Utils (src/utils/): Shared config, job, sandbox, and error helpers.
• Skills sources (src/skills/): Bundled generated-skill Markdown.
• Job storage (.agents/jobs/): Concepts, drafts, execution, review, and shelving artifacts.

Special Files

• src/skills/index.ts: Bundles managed skills into generated config path.
• src/config.ts: Loads global/local .opencode/autocode.jsonc overrides.
• src/plugin.ts: Final merge hook for agents, commands, tools, and skills.
• src/agents/prompts/execute_code.ts: Canonical execution prompt for code-writing sessions.

Known Risks & Anti-Patterns

• Overlapping policy sources: User config and plugin defaults both shape permissions.
• Dynamic job path resolution: File layout assumptions can break cross-worktree flows.
• Generated skill overwrite: ensureGeneratedSkills() clears stale generated skill dirs each load.
• Platform-gated sandbox tools: Unsupported hosts disable sandbox execution paths.

---

IMPORTANT: Update .agents/skills/execute-code/SKILL.md whenever architecture, APIs, data models, security, or integrations change.