Skip to content

Repository Structure

Agents and skills assume this structure in every project that uses the toolbox:

Overview

.
├── .opencode/
│   ├── agents/
│   ├── skills/
│   ├── commands/
├── docs/
│   ├── project/        # board.md, inbox.md, epics.md
│   ├── work/           # W-NNN-<slug>.md, archive.md
│   ├── specs/
│   │   ├── 001-<spec-name>/
│   │   │   ├── spec-001-<spec-name>.md
│   │   │   ├── task-001-<task-name>.md
│   │   │   ├── task-002-<task-name>.md
│   │   │   ├── ...
│   │   ├── 002-<spec-name>/
├── AGENTS.md
├── CONTEXT.md

.opencode

Contains the configuration and structure for agents, skills, and commands within the repository.

├── .opencode/
│   ├── agents/
│   ├── skills/
│   ├── commands/

docs

Contains the project docs: the board (project/), work items (work/), and specifications (specs/).

AGENTS.md

Contains the global instructions for agents working in the repository. It is loaded through the instructions setting in the OpenCode config.

CONTEXT.md

Contains the context and environment information relevant to the repository, including global settings and configurations.

Project conventions

The toolbox is stack-agnostic. Every project that uses it describes its own conventions in AGENTS.md, and agents read them first:

  • Layout: source directories. The defaults here are packages/* (libraries) and apps/* (applications).
  • Commands: how to install, check, test, build, and run an app.
  • Stack: test framework, linter, docs tool, and any reference material (for example reference/).
  • Concept doc: the project's vision, if there is one.

Where a skill or agent names a path or tool, treat it as the default and let AGENTS.md override it.