Códice: Spec-Driven Development Workspace

OpenCode Workspace for AI-assisted development with Spec-Driven Development methodology.

A production-grade workspace integrating 45 engineering skills + 1 meta-skill organized in 10 SDD cycle phases (3 optional) + Extra, slash commands, and specialized agents to accelerate AI-assisted development. Designed for teams and developers who want consistent quality in AI-assisted projects.

Features

• 45 Engineering Skills + 1 Meta-Skill — TDD, Spec-Driven Development, Code Review, Security, Performance, UI/UX, DDD/Hexagonal, design patterns, requirements interview, decision stress-testing, observability, spreadsheet manipulation, notebooks, and more, organized in 10 SDD phases (3 optional) + Extra
• 12 Slash Commands — /spec, /design, /evolve, /docs-update, /diagnosis, /plan, /build, /test, /webperf, /code-simplify, /review, /ship
• 6 Main Agents + 96+ Subagents — huitzilopochtli (orchestrator), quetzalcoatl (vision), moctezuma (planning), tlaloc (construction), mictlantecuhtli (validation), tezcatlipoca (review), and 96+ subagents specialized in frontend, backend, DevOps, testing, security, and more
• OpenCode Native — Slash commands, agents, and skills loaded from .opencode/
• Integrated Technical Documentation — References for Clean Code, DDD, UI/UX, Testing, Security, and more
• MIT License — Free for personal and commercial projects

Mexican Development Pantheon — Main Agents

Six primary agents orchestrate the SDD cycle, each with a specific role and permissions inspired by Mexican mythology:

Huitzilopochtli 🏛️ — Supreme Orchestrator

Quetzalcoatl 🌬️ — Visionary Sage

Moctezuma ⚔️ — Strategist and Commander

Tlaloc 🌧️ — Builder and Artisan

Mictlantecuhtli 💀 — Judge and Guardian

Tezcatlipoca 🔮 — The Smoking Mirror

Additionally, over 90 specialized subagents are available for specific tasks: code review, security audit, DB optimization, UI/UX design, debugging, and more. Invoked via task() from main agents or directly by the user. See the complete catalog.

Install / Update

Códice is a command-line tool that installs and updates this OpenCode workspace template atomically, safely, and intelligently.

Quick Install (Recommended)

Requires Bun installed on your system.

bunx @fisherk2-dev/codice

That's it. Bun downloads and runs the latest version automatically.

Note: If you encounter issues with bunx (e.g., no output, scoped package cache issues), use npx @fisherk2-dev/codice as a fallback — both commands work identically.

Tip: Use bunx --fresh @fisherk2-dev/codice to force download the latest version.

Next steps: After installation, follow the First Steps Before Opening OpenCode guide to configure models, install plugin dependencies, and start your first workflow.

Offline / Air-gapped Alternative

If you don't have Bun installed or prefer a standalone binary, download the compiled binary for your platform:

Linux (x64) / macOS (x64)

# Download the latest binary for your platform:
curl -L -o codice https://github.com/Fisherk2/codice-opencode/releases/latest/download/codice-linux
# macOS: replace `codice-linux` with `codice-macos`

# Make it executable:
chmod +x codice

# Run the installer:
./codice

Windows (x64)

# Download the latest binary:
curl -L -o codice.exe https://github.com/Fisherk2/codice-opencode/releases/latest/download/codice-windows.exe

# Run the installer:
.\codice.exe

Usage

Códice presents an interactive menu with three installation modes:

| Mode | Description | When to Use | |------|-------------|-------------| | Clean Install | Overwrites the destination with the complete template | Starting a fresh project | | Project Install | Selectively merges files using classification rules | Adopting the template into an existing project | | Update Workspace | Updates only Obligatorio + Estándar files after a version check | Keeping an existing installation current |

# Interactive menu (default) — via bunx or binary:
bunx @fisherk2-dev/codice     # via npm (requires Bun)
./codice                   # via compiled binary (standalone)

# Direct mode with flags:
bunx @fisherk2-dev/codice --dest ./my-project
./codice --force
./codice --version
codice --help

Flags

| Flag | Description | |------|-------------| | --dest <path> | Target installation directory (default: current directory) | | --force | Skip all confirmation prompts | | --verbose | Enable structured logging to stderr | | --version | Print binary version and exit | | --clean | Run Clean Install mode (skip interactive menu) | | --project | Run Project Install mode (skip interactive menu) | | --update | Run Update Workspace mode (skip interactive menu) | | --help | Show usage help |

Workflow

flowchart LR
    A["/spec<br/>DEFINE"] --> B["/plan<br/>PLAN"]
    B --> C["/build<br/>BUILD"]
    C --> D["/test<br/>VERIFY"]
    D --> E["/webperf<br/>WEBPERF (optional)"]
    E --> F["/code-simplify<br/>SIMPLIFY (recommended)"]
    F --> G["/review<br/>REVIEW"]
    G --> H["/ship<br/>SHIP"]
    H --> I["Go Live"]

    J["/evolve<br/>EVOLVE (mature project)"] -.-> A
    K["/design<br/>DESIGN (optional)"] -.-> A
    K -.-> C
    L["/docs-update<br/>DOCS"] -.-> A
    M["/diagnosis<br/>DIAGNOSE"] -.-> C

Full Cycle

| Phase | Command | Agent | What It Does | Main Skills | |------|---------|--------|--------------|-------------| | Design (optional) | /design | quetzalcoatl | Parallel fan-out: UX research, technical feasibility, accessibility. Merges into design specification in specs/design/ | ui-ux-design-pro, design-taste-frontend, frontend-ui-engineering | | Define (new) | /spec | quetzalcoatl | Detects project state (3 cases), clarifies requirements, generates docs (PRD, TRD, ARCHITECTURE, WORKFLOW) and synthesizes into SPEC.md | spec-driven-development, clean-ddd-hexagonal, architecture-diagrams, idea-refine, interview-me | | Evolve (mature) | /evolve | quetzalcoatl | Creates new specs or modifies existing ones for mature projects with version history. Redirects to /spec for new/immature projects | spec-driven-development, interview-me, idea-refine, doubt-driven-development, architecture-diagrams | | Sync documentation | /docs-update | quetzalcoatl | Pre-flight analyzes docs state, question-tool resolves contradictions, then synchronizes docs with current codebase | documentation-and-adrs, agent-md-refactor, architecture-diagrams | | Diagnose issues | /diagnosis | quetzalcoatl | Analyzes remote issues, executes diagnostic commands, documents root cause in docs/diagnosis/ with structured template | interview-me, debugging-and-error-recovery | | Plan | /plan | moctezuma | Analyzes dependencies, cuts vertically, writes tasks with acceptance criteria in tasks/plan.md and tasks/todo.md | planning-and-task-breakdown, clean-ddd-hexagonal, architecture-diagrams | | Build | /build | tlaloc | Takes next pending task, applies RED-GREEN-REFACTOR with TDD, runs full suite, commits | incremental-implementation, test-driven-development, solid, error-handling-patterns | | Verify | /test | mictlantecuhtli | TDD for features (test → implement → refactor). Prove-It for bugs (reproduce → fix → verify). Escalates to incident-response if incident | test-driven-development, error-handling-patterns, browser-testing-with-devtools | | Audit performance (optional) | /webperf | mictlantecuhtli | Delegates to web-performance-auditor to audit Core Web Vitals, GPU animations, layout shifts, CSS efficiency. Findings for /review | observability-and-instrumentation, browser-testing-with-devtools | | Simplify (recommended) | /code-simplify | tlaloc | Scans code for simplification opportunities (nesting, long functions, ternaries, dead code). Applies incrementally with tests | code-simplification, refactoring-patterns, solid | | Review | /review | tezcatlipoca | 5-axis audit: Correctness, Readability, Architecture, Security, Performance. Incorporates /webperf findings. Findings categorized Critical/Important/Suggestion | code-review-and-quality, solid, security-and-hardening, performance-optimization | | Ship | /ship | mictlantecuhtli | Parallel fan-out: code-reviewer, security-auditor, test-engineer, dependency-manager, ±accessibility-tester. Produces GO/NO-GO decision + rollback plan | shipping-and-launch, crafting-effective-readmes, architecture-diagrams, bash-defensive-patterns |

Workspace Structure

project-root/
├── AGENTS.md                   # Agent personas and orchestration
├── CHANGELOG.md                # Release history
├── CONTRIBUTING.md             # How to add agents and skills
├── Justfile                    # Task runner commands
├── LICENSE                     # MIT License
├── Makefile                    # Build targets
├── README.md                   # Project overview
├── SPEC.md                     # Project specification
├── opencode.json               # OpenCode configuration
├── skills-lock.json            # Skill dependency lockfile
├── requirements.txt            # Python dependencies
├── .env.example                # Environment variables template
│
├── agents/                     # 102+ agent personas (6 primary + 96+ subagents)
│   ├── huitzilopochtli.md      #   Supreme Orchestrator
│   ├── quetzalcoatl.md         #   Visionary Architect
│   ├── moctezuma.md            #   Strategic Commander
│   ├── tlaloc.md               #   Rain God Builder
│   ├── mictlantecuhtli.md      #   Underworld Judge
│   ├── tezcatlipoca.md         #   Smoking Mirror Critic
│   └── ... (96+ subagent files)
│
├── commands/                   # 12 slash commands for OpenCode
│   ├── build.md                #   BUILD
│   ├── code-simplify.md        #   SIMPLIFY (recommended pre-review)
│   ├── design.md               #   DESIGN (optional, UI/UX)
│   ├── diagnosis.md            #   DIAGNOSE (issue analysis)
│   ├── docs-update.md          #   DOCS (sync documentation)
│   ├── evolve.md               #   EVOLVE (mature projects)
│   ├── plan.md                 #   PLAN
│   ├── review.md               #   REVIEW
│   ├── ship.md                 #   SHIP
│   ├── spec.md                 #   DEFINE (new projects)
│   ├── test.md                 #   VERIFY
│   └── webperf.md              #   WEBPERF (optional, perf. audit)
│
├── .opencode/                  # OpenCode runtime config
│   ├── agents -> ../agents     #   Symlink to agents
│   ├── commands -> ../commands #   Symlink to commands
│   ├── skills -> ../skills     #   Symlink to skills
│   ├── plugins/                #   SDD pipeline plugin
│       ├── sdd-pipeline.ts     #     Pipeline state machine
│       └── sdd-workflow-test.md #   Workflow test specs
│
├── skills/                     # 46 skills (45 engineering + 1 meta-skill)
│   ├── using-agent-skills/     #   META: skill discovery
│   ├── idea-refine/            #   DEFINE / EVOLVE
│   ├── spec-driven-development/#   DEFINE / EVOLVE
│   ├── agent-md-refactor/      #   DEFINE (PRE-FLIGHT)
│   ├── env-setup/              #   DEFINE (PRE-FLIGHT)
│   ├── clean-ddd-hexagonal/    #   DEFINE / PLAN / BUILD
│   ├── design-patterns/        #   DEFINE / PLAN / REVIEW
│   ├── architecture-diagrams/  #   DEFINE / PLAN / SHIP
│   ├── ui-ux-design-pro/       #   DEFINE / BUILD
│   ├── interview-me/           #   DEFINE / EVOLVE (extract requirements)
│   ├── doubt-driven-development/ # EVOLVE / BUILD (stress-test decisions)
│   ├── planning-and-task-breakdown/ # PLAN
│   ├── incremental-implementation/  # BUILD
│   ├── test-driven-development/     # BUILD
│   ├── source-driven-development/   # BUILD
│   ├── context-engineering/         # BUILD
│   ├── frontend-ui-engineering/     # BUILD
│   ├── api-and-interface-design/    # BUILD
│   ├── api-spec-generation/         # BUILD
│   ├── docker-optimize/             # BUILD / SHIP
│   ├── db-migration/                # BUILD / SHIP
│   ├── solid/                       # BUILD / REVIEW
│   ├── clean-code/                  # BUILD / REVIEW
│   ├── error-handling-patterns/     # BUILD / VERIFY / REVIEW
│   ├── design-taste-frontend/       # BUILD / VERIFY / REVIEW
│   ├── bash-defensive-patterns/     # BUILD / SHIP
│   ├── observability-and-instrumentation/ # BUILD / VERIFY / SHIP
│   ├── browser-testing-with-devtools/ # VERIFY / WEBPERF
│   ├── debugging-and-error-recovery/  # VERIFY
│   ├── code-review-and-quality/       # REVIEW
│   ├── code-simplification/           # SIMPLIFY
│   ├── security-and-hardening/        # REVIEW
│   ├── dependency-audit/              # REVIEW
│   ├── performance-optimization/      # REVIEW
│   ├── performance-analysis/          # REVIEW
│   ├── refactoring-patterns/          # SIMPLIFY
│   ├── git-workflow-and-versioning/   # SHIP
│   ├── changelog-generate/            # SHIP
│   ├── ci-cd-and-automation/          # SHIP
│   ├── deprecation-and-migration/     # SHIP
│   ├── documentation-and-adrs/        # SHIP / EVOLVE
│   ├── shipping-and-launch/           # SHIP
│   ├── incident-response/             # SHIP / VERIFY
│   ├── crafting-effective-readmes/    # DEFINE / SHIP
│   ├── xlsx/                          # EXTRA
│   └── excel-analysis/                # EXTRA
│
├── references/                 # 59 technical reference files
│   ├── testing-patterns.md
│   ├── security-checklist.md
│   ├── performance-checklist.md
│   ├── accessibility-checklist.md
│   ├── clean-code.md
│   ├── code-smells.md
│   ├── design-patterns.md
│   ├── solid-principles.md
│   ├── error-handling.md
│   ├── tdd.md
│   ├── architecture.md
│   ├── DDD-STRATEGIC.md
│   ├── DDD-TACTICAL.md
│   ├── HEXAGONAL.md
│   ├── CQRS-EVENTS.md
│   ├── refactoring-smell-catalog.md
│   ├── component-patterns.md
│   ├── color-system.md
│   ├── typography.md
│   └── ... (59 files total — see references/ for the full list)
│
├── docs/                       # Project documentation
│   ├── APPFLOW.md              #   Application flow
│   ├── ARCHITECTURE.md         #   System architecture decisions
│   ├── CODE_STYLE.md           #   Coding conventions
│   ├── DESIGN.md               #   Design directions
│   ├── PRD.md                  #   Product requirements
│   ├── SCHEMA.md               #   Data schema
│   ├── TRD.md                  #   Technical requirements
│   ├── WORKFLOW.md             #   Implementation workflow
│   └── opencode/               #   OpenCode configuration guides
│       ├── USER_GUIDE.md       #     Complete Reference Guide
│       ├── 00-setup.md
│       ├── 01-agents.md
│       ├── 02-orchestration-patterns.md
│       ├── 03-agent-index.md
│       ├── 04-commands.md    #     Command creation guide
│       ├── 05-skills.md
│       ├── 06-mcp-servers.md
│       ├── 07-models.md
│       ├── 08-rules.md
│       ├── 09-tools-and-custom-tools.md
│       └── 10-permissions.md
│
├── specs/                      # Project specifications
│   ├── spec-xx.md              #   Feature specs
│   ├── adr/                    #   Architecture Decision Records
│   │   └── adr-xxx.md          #     Template
│   └── design/                 #   Design docs
│       ├── components.md
│       ├── style-guide.md
│       └── user-flow.md
│
├── scripts/                    # Helper scripts
│   ├── build.sh
│   ├── lint.sh
│   ├── setup.sh
│   └── test.sh
│
├── tasks/                      # Task tracking
│   ├── plan.md                 #   Current plan
│   └── todo.md                 #   Todo list
│
├── src/                        # Source code
└── tests/                      # Tests

Note: The .opencode/agents, .opencode/commands, and .opencode/skills directories are symlinks created automatically by the Códice installer after copying template files. This ensures compatibility with npm packaging (which strips symlinks from tarballs).

Troubleshooting

| Problem | Solution | |---------|----------| | bunx @fisherk2-dev/codice not found | Ensure Bun is installed: curl -fsSL https://bun.sh/install \| bash | | bunx shows no output or hangs | Try bunx @fisherk2-dev/codice@latest or use npx @fisherk2-dev/codice instead | | bunx uses a cached version | Run bunx --fresh @fisherk2-dev/codice | | Permission denied (binary) | Run chmod +x on the downloaded binary, or prepend sudo | | Binary not found after install | Ensure the binary is in your $PATH, or use ./codice | | GitHub API rate limited | Wait 1 hour, or proceed with the bundled local template (Códice continues without remote check) | | Installation interrupted (Ctrl+C) | Códice automatically rolls back any partial changes — your project is safe | | --dest path outside workspace | Códice rejects path traversal attempts with exit code 1 | | Symlinks not created | If .opencode/agents is missing after installation, re-run the installer. Symlinks are created during post-installation and require write permissions in the project directory |

License

MIT — See LICENSE for details.

Acknowledgments

This project would not exist without the work of:

• awesome-opencode — Source of inspiration for implementing new skills, the 90+ specialized agents, and OpenCode documentation.
• addyosmani/agent-skills — Base of this project. This repository is a fork of that work, which laid the foundations of the AI agent skill ecosystem.
• oh-my-opencode-slim — Direct inspiration for the multi-main-agent architecture and Mexican orchestration system design.

Thanks to their authors and contributors for their invaluable contribution to the community.