opencode-processing-skills AGENTS.md

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. Only one package's BLUEPRINT -> EXECUTE pair reuses an Implementer session; it retires after the digest. Implementation-plan batch review remains a separate deliberate reuse case, and review-fix reuse remains conditional on retained reasoning value.
• 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.