Skip to content

Getting Started

Jump to bottom
Fisherk2 edited this page Aug 7, 2026 · 5 revisions

Getting Started

This guide walks you through installing the Códice workspace template and running your first SDD (Spec-Driven Development) cycle.

Prerequisites

Before installing Códice, you need OpenCode installed on your system. OpenCode is the AI-assisted development harness that Códice extends with agents, commands, and skills.

  • Install OpenCode — follow the official installation guide for your platform
  • Verify the installation by running opencode --version in your terminal

Códice is distributed via npm and executed with bunx @fisherk2-dev/codice. Bun is the recommended runtime.

Install the Workspace

Open a terminal in the project directory where you want to install the workspace, then run:

bunx @fisherk2-dev/codice

If you do not have Bun installed, use the npm equivalent:

npx @fisherk2-dev/codice

The installer launches an interactive menu with three options:

  1. Clean Install — Installs the complete workspace into an empty directory. All mandatory and standard files are copied. Optional files are presented as a checklist for you to choose from.
  2. Project Install — Merges the template into an existing project. Mandatory files overwrite existing ones. Standard files are copied only if they do not already exist. Optional files are presented as a checklist.
  3. Update Workspace — Updates an existing Códice workspace to the latest version. Only mandatory files are overwritten. Standard files are preserved if they exist. Optional files are never touched.

Clean and Project installs first show a pack selection wizard: choose which of the 8 agent packs to include (software-development is pre-selected by default; at least one pack is required). After confirming packs and optional files, the installer shows a summary — the selected packs with their agent counts, the always-included mandatory directories, and an estimate of total agents and files — before copying anything.

After you select a mode, the installer copies files, generates symlinks, and creates a .gitignore tailored for OpenCode development. No existing project files are modified without your consent.

Command-Line Flags

For non-interactive use (scripts, CI), the installer supports these flags:

Flag Description
--dest <path> Target directory (default: current directory)
--mode <mode> Skip the menu — clean, project, or update
--packs <ids> Comma-separated pack ids; skips the pack selection wizard
--packs-all Select all 8 agent packs non-interactively
--update-add-packs <ids> Update mode: add new packs to an existing installation
--force Skip confirmations and include all optional files
--verbose Show detailed logs of every operation
--version Print the installed version and exit
--help Show usage instructions

Example — clean install in a specific directory without interactive prompts:

bunx @fisherk2-dev/codice --dest ./my-project --mode clean --force

What Gets Installed

After installation, your project directory contains these new files and folders:

your-project/
├── opencode.json              # Main configuration (models, permissions, MCP servers)
├── AGENTS.md                  # Project-level agent instructions
├── SPEC.md                    # Central specification document
├── CONTRIBUTING.md            # Contribution guidelines
├── CHANGELOG.md               # Version history
├── docs/                      # Documentation templates
├── specs/                     # Modular specifications and ADRs
├── tasks/                     # Task breakdowns (created by /plan)
├── .opencode/
│   ├── plugins/               # SDD pipeline and orchestrator plugins
│   └── agents/ → agents/      # Symlink to agents directory
├── agents/                    # 6 primary + 4 writer agents + your selected pack subagents (~352 across 8 packs)
├── commands/                  # 12 SDD slash commands
└── skills/                    # 52 engineering skills

For a detailed breakdown of every file and directory, see Workspace Structure.

First Steps

Once the workspace is installed, open your project in OpenCode and follow these steps:

1. Run /help

Start by running the /help command to see all available slash commands and their descriptions. This gives you an overview of the entire SDD workflow at a glance.

2. Activate MCP Servers (Optional)

The template ships with 9 pre-configured MCP servers in opencode.json. Three are enabled by default: context7 (documentation queries), vercel-grep (GitHub code search), and gitmcp (GitHub repository docs). If your project needs browser debugging, spreadsheet manipulation, web scraping, or other capabilities:

  1. Check MCP Servers for per-server prerequisites
  2. Set "enabled": true for the server you need in opencode.json
  3. Restart OpenCode

Most projects only need the 3 default servers (already enabled). Activate others on demand to conserve context.

3. Run /spec to Define Your Project

The first SDD cycle phase is specification. Run:

/spec

This activates Quetzalcoatl (the Visionary Sage), who will:

  • Analyze your project state
  • Ask clarifying questions about your goals, users, and constraints
  • Generate a structured SPEC.md with objectives, commands, architecture, code style, testing strategy, and boundaries
  • Create supporting documentation (docs/ARCHITECTURE.md, docs/CODE_STYLE.md, etc.)
  • Create modular specs in specs/ and Architecture Decision Records in specs/adr/

The /spec command is for new projects or projects in the conception phase. If your project already has stable code and releases, use /evolve instead.

4. Run /plan to Break the Spec into Tasks

Once your specification is ready, run:

/plan

This activates Moctezuma (the Strategist), who will:

  • Analyze the dependency graph between components
  • Slice work into small, independent, verifiable tasks
  • Write each task with acceptance criteria and verification steps
  • Save the plan to tasks/plan.md and tasks/todo.md
  • Present the plan for your review before saving

5. Run /build to Implement

With a plan in place, run:

/build

This activates Tlaloc (the Builder), who works through each task incrementally using TDD (Test-Driven Development):

  • Pick the next pending task from the plan
  • Write a failing test (RED)
  • Implement the minimum code to pass (GREEN)
  • Run the full test suite to check for regressions
  • Commit and mark the task complete
  • Move to the next task

Continue the SDD Cycle

After building, continue through the remaining SDD phases:

Command Phase Agent Purpose
/test Validate Mictlantecuhtli Write tests, fix bugs using Prove-It pattern
/code-simplify Simplify Tlaloc Refactor code for clarity
/webperf Optimize Mictlantecuhtli Run web performance audits
/review Review Tezcatlipoca Five-axis code review
/ship Ship Mictlantecuhtli Pre-launch checklist and go/no-go decision

Each command suggests the next logical step when it finishes, guiding you through the full cycle without needing to consult documentation.

Next Steps

  • Configuration — Models, permissions, agents, and MCP settings
  • SDD Pipeline — How the orchestration plugin works
  • MCP Servers — Activate pre-configured servers and add new ones
  • Workspace Structure — Learn what each file and directory does
  • Commands — Detailed reference for all 12 slash commands
  • Agents — Understand each agent's role, permissions, and recommended models
  • Configuration — Configure models, agents, permissions, MCP, and more

For OpenCode-specific questions (agent configuration, permission model, MCP servers), refer to the official OpenCode documentation.

Clone this wiki locally