OpenCode Capstone Project
Introduction: Building a Complete Project
Welcome to the final lesson of the Foundation course. Over the previous units, you have learned how to install OpenCode, manage sessions, configure the agent's behavior, and leverage its autonomous capabilities. Now it is time to combine everything into a realistic development workflow.
In this lesson, we will take an incomplete todo list application and transform it into polished, production-ready software. You will plan improvements, implement features, refactor messy code, add new modules, and write documentation — all through natural conversation with your AI assistant.
Setting Up Your Workspace
Before we begin coding, we need to ensure OpenCode starts in the correct directory. The agent is context-aware, meaning it automatically reads the file structure of whatever folder you launch it from. Starting in an empty directory means the agent knows nothing about your project. Starting inside your project folder gives it immediate access to your codebase.
Navigate to your project and launch OpenCode:
Once the interface loads, the agent can already see files like app.py, tasks.py, and config.py. You do not need to manually tell it about your project structure — it discovers this automatically.
Planning Before Building
When facing a complex task, rushing to write code often leads to poor decisions. Instead, we will start by switching to the Plan agent to create a strategy. The Plan agent analyzes your code and proposes solutions without modifying any files, giving you a chance to review the approach before committing to it.
Press Tab to switch from Build mode to Plan mode. You will see the status bar change to reflect this. Then ask the agent to review your codebase:
The agent reads your files and produces a structured implementation plan:
This plan becomes your roadmap. You can ask clarifying questions, request adjustments, or approve it as-is before moving forward.
Implementing the Plan
With a solid strategy in place, switch back to the Build agent by pressing Tab again. Because the agent remembers your entire conversation, you do not need to repeat the plan — simply tell it to proceed:
The agent executes the strategy across multiple files in a single turn:
Notice how the agent applied file handling with proper error recovery in app.py and added validation checks to tasks.py — all based on the plan you reviewed together. This Plan → Build workflow prevents the agent from making hasty decisions and ensures you maintain control over the direction of your project.
Targeting Specific Files
Sometimes you want to improve a single file without touching the rest of your project. The @ syntax lets you focus the agent's attention on exactly the file you care about. This is especially useful for refactoring, where you want to clean up code structure without changing functionality.
Let's say your tasks.py works correctly but has a long chain of repetitive if/elif statements for task priority handling. You can target it directly:
The agent focuses exclusively on this file:
By using @tasks.py, you ensured that app.py and config.py remained untouched. This targeted approach reduces risk and keeps your changes predictable.
Creating New Modules
OpenCode is not limited to editing existing files — it can create entirely new ones and integrate them with your codebase. Let's add a filtering system to easily search and display tasks by category or due date.
Rather than cramming this logic into an existing file, we will ask for a new module:
The agent creates the new file and updates your existing code to use it:
In a single request, the agent wrote a TaskFilter class with by_category() and by_due_date() methods, added the import statement to app.py, and modified the display logic to support filtered views. This demonstrates how complex, multi-file tasks can be handled through simple natural language requests.
Handling Errors Automatically
One of the most powerful aspects of agentic AI is self-correction. When code fails, you do not need to diagnose the problem yourself — the agent reads the error output and fixes it autonomously.
Suppose you ask the agent to run your application and something goes wrong:
Instead of manually debugging, simply ask for help:
The agent diagnosed the missing module, created the necessary file, and resolved the issue. This self-correction loop dramatically reduces debugging frustration and keeps you focused on building features rather than chasing errors.
Documentation and Testing
A project is not complete without clear documentation. Since the agent has read all your code and understands every feature you built together, it is perfectly positioned to write accurate documentation:
The agent generates comprehensive documentation and verifies the application:
The agent confirms your application runs properly and provides clear documentation for future users.
Wrapping Up and Moving Forward
When you are finished working, exit cleanly with /quit. You can return later with opencode --continue to pick up exactly where you left off.
You have now experienced the complete development workflow: planning with the Plan agent, implementing with the Build agent, targeting specific files with @ syntax, creating new modules, letting the agent self-correct errors, and generating documentation. This is the same process you will use on real projects — the only difference is scale.
In the practice exercises that follow, you will apply these skills independently to build a different application from scratch. By the end, you will be ready to collaborate with OpenCode on any project you can imagine.
Congratulations on completing Foundation - Getting Started with OpenCode! You now have the foundational skills to work effectively with AI-assisted development and are ready to tackle real-world projects with confidence.
