OpenCode Processing Skills - Agent Instructions

Project Overview

This is a meta-project for creating agents, skills, tools, and templates that standardize documentation and planning workflows for AI-assisted software development using OpenCode.

Project Structure

.
├── AGENTS.md              # This file - agent instructions
├── README.md              # Project overview (English)
├── config.yaml.example    # Model configuration template
├── skills/                # Reusable skill definitions
├── agents/                # Agent configurations
└── docs/                  # Project documentation

Core Entities

Workspace Entities

• Project: The entire workspace/repository
• Module: Self-contained part (service, container, frontend)
• File/Directory: Filesystem manifestation
• Symbol: Referenceable language element with meaning

Planning Entities

• Plan: Implementation plan for features (with DoD, tests, requirements)
• Phase: Subdivision when plan exceeds single-session capacity (defines scope: what and why)
• Implementation Plan: Per-phase technical approach, above code level (defines: how)
• Persistent Todo List: Items with status + changelog
• Session Handover: Context transfer for session continuity (created on demand, multiple per plan possible)

Documentation Entities

• Project Overview: High-level architecture, modules, references
• Module Documentation: Overview + inventories (directories/files + symbols) with explanations for each entry
• Feature Documentation: How features work, with implementation references

Architecture Principles

• Maintainer-owned main loop: The Maintainer owns the user conversation, decisions, scope, and final result. Subagents bound expensive context; durable artifacts and compact summaries carry context between sessions.
• File-based interface: Subagents write skill-/workflow-defined artifacts to the defined file structure (templates). The file structure IS the interface, not return values. Every subagent that produces artifacts writes them to disk; the primary agent receives only a short status summary.
• Skill-driven delegate: agents/delegate.md is the standard persona for normal delegation involving reasoning, synthesis, reviews, and skill-defined artifacts. Generated delegate-* variants are model aliases; loaded skills own expertise, write boundaries, and output contracts. Delegates hand separable evidence collection to the leaf retriever by default while retaining synthesis and artifact ownership.
• Workflow-owned writers: doc-explorer is the documentation-specialized Delegate, the canonical delegate handles skill-governed analysis/reviews and explicit artifacts, retriever is a disposable non-writing worker for straightforward evidence gathering, and implementer performs one gated work package while retaining ownership of any retriever-assisted changes.
• Bounded expensive sessions: Each phase implementation plan uses a fresh Delegate session in Maintainer-coordinated sequence, and each phase/work package uses a fresh Implementer for its BLUEPRINT -> EXECUTE pair. Post-digest Implementer reuse is narrowly allowed through review-fix for accepted defects of that same completed package, never a new phase/package or indefinite continuation. Implementation-plan batch review remains a separate deliberate reuse case; review-fix owns eligibility and one-pass closure for retained review/diagnosis evidence.
• Self-delegation for scale: When a subagent's workload would exceed comfortable context limits (e.g., documenting a project with many modules), it spawns additional instances of itself, each scoped to a smaller unit of work.
• Agent extension over commands: Skills extend the primary agent's behavior. Subagents handle expensive exploration.
• Stack-agnostic: No assumptions about language or framework
• Two-tier documentation: Overview with references + detail docs, deliberately curated to manage complexity
• Redundancy-free: Templates reference each other instead of duplicating content
• Session-resilient: Everything persisted, handover on demand
• Context-aware: Documents structured for partial loading (not everything into context at once)
• Policy-light: Routing rules are defaults, not self-imposed blockers; preserve valid context and avoid automatic review/fix loops
• Skill-owned scope authority: Detailed scope, completeness, underspecification, and configurable-value rules live in create-plan, author-and-verify-implementation-plan, and execute-work-package plus their bundled prompts/templates. Agent instructions route decisions and invoke the active skill rather than duplicating its rulebook; review skills retain their bounded review guidance.

Design Decisions

Key architectural decisions and their rationale. These explain WHY the framework works the way it does.

Why separate Phase (What/Why) from Implementation Plan (How)?

Phases define scope and acceptance criteria independent of technical approach. The implementation plan may be revised (e.g., "we chose a different library") without changing what the phase delivers. This separation also allows a plan reviewer to evaluate scope without needing to understand the technical details.

Why does the primary agent author plans, not doc-explorer?

Scope plans are conversation-anchored: requirements emerge from user dialogue, trade-offs are negotiated, and DoD is agreed upon. This context lives in the primary agent's conversation, so the Primary obtains user-owned decisions before create-plan writes artifacts. Grounded per-phase implementation plans are different: one fresh Delegate per phase follows author-and-verify-implementation-plan against gated scope and current code. Execution follows the separately gated execute-work-package authority. Documentation, by contrast, is codebase-anchored and belongs to Doc Explorer.

Why keep exploration and writing within workflow agents?

Earlier iterations had a separate code-analyzer (read-only analysis) and writer agents. This created problems: (1) code-analyzer could only return text, weakening the file-based interface; (2) extra delegation chains added indirection without value; (3) the primary spawning analyzers directly for large tasks could dump excessive analysis into the primary's context. The solution: the workflow agent that owns an artifact performs the necessary exploration and writes the artifact directly. For documentation scale, doc-explorer self-delegates per module; for review and implementation-plan artifacts, delegate-* writes the explicit output path defined by the skill.

Why one canonical delegate persona?

Task expertise changes more often than generic delegate behavior. Keeping exploration, review, remediation, and artifact contracts in skills avoids persona drift and permits an eligible review or analysis task_id to move to accepted remediation without collecting secured evidence again. Model variants copy the canonical persona and differ only in configured model/options, so capacity can change without duplicating workflow rules.

Why may defect fixes stay in the review or diagnosis session?

Already-secured evidence should not be collected again merely because review or analysis has ended. review-fix reuses correct and sufficient retained review/diagnosis context for explicitly accepted and Primary-instructed defect remediation; a review artifact is one source, not a prerequisite. Faulty, insufficient, or unavailable context instead requires a fresh session with a finding-source hint, never claimed inherited context. The skill owns routing and bounded closure, including the same-package Implementer exception. Remediation is not an independent review; new risk goes to the Primary for a re-review decision, never an automatic loop. Conversation-owned plan corrections remain with update-plan.

Why does doc-explorer self-delegate instead of the primary spawning per-module instances?

The primary agent should not need to know the internal module structure of a project. Doc-explorer discovers modules during exploration and decides how to partition the work. This keeps the primary's prompt simple ("document this project") and avoids leaking implementation details of the documentation process into the primary's context.

Why bundle templates in each skill directory?

OpenCode skills are self-contained units. A skill loaded into an agent session must have all its resources available without depending on external paths. Therefore, tpl-* files live alongside each skill as the operational (and canonical) templates. This avoids drift between a separate "human reference" template set and the templates agents actually follow.

Why no "implementation" skill?

The framework deliberately stops at the boundary between planning and coding. Implementation is the domain of the coding agent (OpenCode's primary capability). The resume-plan skill bootstraps context so the agent can implement effectively, but the actual coding workflow is left to the agent's native capabilities. An "implement-phase" skill would either be too generic to be useful or too prescriptive for the variety of possible implementations.

How is execution handled then?

Instead of a generic "implementation" skill that tries to plan-and-code, this framework uses:

• A dedicated execution protocol (execute-work-package) that is explicitly gated (step list -> primary approval -> execute -> digest)
• A dedicated execution-only subagent (implementer) that handles exactly one two-call work package and then retires after returning a compact digest, subject only to the bounded same-package review-fix exception

This keeps planning and execution responsibilities separated while still standardizing implementation as a repeatable workflow.

Target Project File Convention

When skills/agents create artifacts in a target project, they use this convention. Empty implementation and handover directories are created only when their artifacts are needed:

project-root/
├── AGENTS.md
├── docs/
│   ├── overview.md
│   ├── modules/<module-name>.md
│   ├── features/<feature-name>.md
│   └── handovers/session-YYYY-MM-DD.md  (standalone, without plan)
├── plans/
│   └── <plan-name>/
│       ├── plan.md
│       ├── phases/phase-N.md
│       ├── implementation/phase-N-impl.md
│       ├── reviews/
│       │   ├── plan-review.md
│       │   ├── impl-plan-review-phase-N.md
│       │   └── impl-review-phase-N.md
│       ├── todo.md
│       └── handovers/session-YYYY-MM-DD.md

Development Guidelines

• When creating skills or agents, ensure they follow the entity model above
• Templates should be modular - avoid redundancy by referencing shared sections
• Documentation must be updatable (not just generatable)
• Plans must support multi-session workflows with clear phase boundaries
• Always consider the context window limitation when designing artifacts
• Skills define WHAT to create and HOW - the file structure defines WHERE

File Conventions

• Templates use Markdown with YAML frontmatter where metadata is needed
• Plan files include a changelog section for tracking progress across sessions
• Todo lists are persisted as structured Markdown with checkbox syntax