Welcome to the OpenCode Framework. This guide explains how to use the framework to achieve a high-velocity, AI-assisted development workflow.
The framework is not just a set of scripts; it is a principled system designed to take you from ideation to execution at the fastest responsible speed, without sacrificing safety or maintainability.
The most pressing limitation of modern LLMs is context saturation. When you work on a single project for a long time, the model can lose track of important details, leading to hallucinations or drift.
This framework solves this problem by enforcing core principles:
- The important things should be made explicit: We keep track of everything important in Markdown files. Ideas are committed to
.knowledge/plans/, research is summarized in.knowledge/notes/, and all changes are logged in.knowledge/log/. This physical "long-term memory" prevents the agent from forgetting context. - Resist the urge to guess: We favor explicit commands over implicit actions. If you want the model to make a plan, you use the
/plancommand, which invokes a carefully crafted workflow rather than relying on the agent's default behavior. - Evidence-based: Every claim cites specific sources and findings are actionable.
The most critical phase of any project occurs before you write a single line of code. This phase uses read-only commands to gather information safely.
Your tool for deep domain exploration.
- How it works: Gathers documentation and synthesizes it into
.knowledge/notes/reports.
Your primary tool for forensic, scientific investigation.
- How it works: When a bug is detected, the
/debugcommand implements a principled approach to problem-solving using the specializeddebuggersubagent. It moves through four distinct phases: Context Analysis, Hypothesis Formulation, Isolated Testing on a temporary branch (debug/hyp-*), and finally a Synthesis of the findings into a Root Cause Analysis (RCA) report. - Why it works: It forces the agent to identify the root cause before attempting a fix, preventing "guess-and-check" coding that can lead to regressions.
Once you have gathered discovery artifacts, you must synthesize them into an actionable strategy.
Your tool for internal strategy and architectural design.
- How it works: The
planagent conducts a thorough analysis of your codebase. After clarifying the goal with you interactively, it produces a comprehensive Markdown plan in the.knowledge/plans/directory. - Crucial Rule: The
/plancommand never executes the code. It maps the territory and provides a step-by-step execution roadmap for you to approve first.
Your tool for rapid project orientation.
- How it works: Provides a high-signal overview of the repository's architecture, standards, and current state.
- Why it works: It ensures that you (and the agent) are always aligned with the project's unique conventions before starting a session.
Once you have a solid strategy in .knowledge/plans/, you can move into execution. These commands eliminate the friction of context-switching between your IDE and terminal.
Your gateway to GitHub.
- How it works: Interfaces with the GitHub CLI to analyze open issues and recommend what to tackle next based on strategic impact.
Your tool for project initialization.
- How it works: Scaffolds new components or entire projects using modern, standard tooling (TS, Python, Rust, etc.) and integrates the framework's standards and
makefilefrom the start.
Your tool for isolated execution environments.
- How it works: Sets up a Docker-based sandbox for running commands in isolation. Useful for testing potentially destructive operations or running untrusted code.
- Why it works: Provides safety guarantees by isolating execution from the host system.
Your task management tool.
- How it works: Manages project tasks via the
todowritetool. Use it to track work items, set priorities, and mark completion. - Why it works: Keeps a structured task list visible to both user and agent, ensuring nothing falls through the cracks.
Your tool for validation-aware commits with grouped changes.
- How it works: Analyzes your
git diffand logically groups modifications into cohesive units. Proposes a series of atomic, Conventional Commits for your approval. - Workflow:
- Validation: Runs
make testto ensure tests pass - Staging: Shows files to commit and asks for confirmation
- Commit: Creates Conventional Commit with optional issue linking
- Logging: Updates
.knowledge/log/{date}.yamlwith entry
- Validation: Runs
- Why it works: Ensures tests pass before commit, groups changes logically, and maintains audit trail
Automates the deployment process.
- How it works: Verifies workspace integrity (clean git tree, passing tests via
make), analyzes commit history to propose the next version bump, drafts aCHANGELOG.mdentry, and publishes the final tag to GitHub. - Why it works: Automates the tedious release process while enforcing quality gates
The framework uses OpenCode with specialized agents that handle different cognitive workloads:
analyze: Research, investigation, and auditsdesign: Architecture and system designplan: Strategy and planningbuild: Implementation with TCR disciplinerelease: Publishing and versioning
investigator: Codebase analysisscout: Web researchtester: Hypothesis validationdrafter: Content creationcritic: Prose reviewgeneral: General-purpose coding taskslit-commands: Literate command processing
A complete, principled development cycle follows the Discovery -> Plan -> Execute lifecycle.
Before acting, you must gather context. For example, if you are integrating a new authentication library, you start by researching the technical requirements.
- Use
/researchto gather documentation and synthesize it into.knowledge/notes/auth-library-deep-dive.md. - Use
/auditto audit the codebase or existing documents.
Once you understand the requirements, you trigger the /plan command.
- The
planagent analyzes the codebase and generates.knowledge/plans/implement-auth.md, mapping out the specific architectural changes and testing strategy.
The approved plan is linked to a task. You trigger the execution:
- Pre-flight: The agent verifies the tree is clean on
main. - Isolation: A feature branch is created.
- Loop (Red-Green-Verify):
The
/buildcommand breaks the plan into granular steps:- Write a failing test based on the step.
- Implement the minimal logic to pass.
- Verify with
make test. If successful, commit the step. - If it fails, revert the step and report the failure.
- The loop repeats for every granular step defined in the plan.
After all steps pass, the agent presents the final work. Upon your approval, it merges back to main and cleans up the feature branch.
Finally, update the technical documentation as needed and use /release to publish the new version.
When a bug is detected, the /debug command ensures a scientific resolution:
- Analyze Context: The agent gathers all relevant logs and context. ...
- Formulate Hypothesis: The agent proposes a root cause hypothesis (e.g., "The auth token is not being correctly passed to the header").
- Isolate & Test: The agent creates a temporary branch to implement a minimal reproduction script or logging.
- RCA Synthesis: Once confirmed, the agent generates a Root Cause Analysis (RCA) report. This report is used as the basis for the subsequent
/buildto implement the fix.
The framework's most powerful feature is its automated audit trail. This is enforced by a timestamp-based pre-commit hook that ensures your code never gets ahead of your documentation.
Every code change should be documented in .knowledge/log/YYYY-MM-DD.yaml. If you modify a file at 10:00 AM, you should have a journal entry with a timestamp of 10:00 AM or later before you can commit.
To simplify this, use the /note command:
opencode /note "Brief description of your work"This adds an entry to the daily journal with a precise timestamp.
Beyond code, this framework excels at generating high-quality technical content through a principled, multi-stage pipeline.
Your primary tool for long-form technical writing.
- How it works: The
/draftcommand follows a structured workflow: Context Gathering (from.knowledge/notes/or.knowledge/plans/), Title & Metadata Selection, Outline Creation (aligned with the Style Guide), Initialization of the file, Section-by-Section Drafting, and finally, a Conclusion with next steps. - Why it works: It forces structural integrity and prevents the "AI-ish" monotone by building the document incrementally based on project-specific research.
Your tool for bug fixes with regression prevention.
- How it works: Uses
/debugto find root cause, then applies TCR discipline to implement the fix with a regression test. - Why it works: It separates investigation from implementation, ensuring fixes are grounded in understanding.
This framework is not a "one-size-fits-all" solution; it is a starting point. Every command and subagent is a living document meant to be tweaked to suit your unique mental model.