Códice: Spec-Driven Development Workspace

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

A production-grade workspace integrating 51 engineering skills 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

• 51 Engineering Skills — TDD, Spec-Driven Development, Code Review, Security, Performance, UI/UX, DDD/Hexagonal, design patterns, requirements interview, decision stress-testing, observability, spreadsheet manipulation, Obsidian vault management, and more, organized in 10 SDD phases (3 optional) + Extra
• 17 Slash Commands — /spec, /design, /evolve, /docs-update, /diagnosis, /plan, /build, /test, /webperf, /code-simplify, /review, /ship, /help, /sync, /migrate, /deploy, /analyze
• 6 Main Agents + 355 Subagents (10 packs) — huitzilopochtli (orchestrator), quetzalcoatl (vision), moctezuma (planning), tlaloc (construction), mictlantecuhtli (validation), tezcatlipoca (review), and 355 subagents organized in 10 packs (2 mandatory + 8 selectable) specialized in frontend, backend, DevOps, testing, security, and more. Install only the packs you need via --packs, or everything with --packs-all.
• Install summary screen — Before merging, Códice shows the selected packs with agent counts, mandatory directories, and optional files so you know exactly what's being installed.
• OpenCode Native — Slash commands, agents, and skills loaded from .opencode/
• Integrated Technical Documentation — References for Clean Code, DDD, UI/UX, Testing, Security, and more

Mexican Development Pantheon — Main Agents

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

Model configuration: The default models below are provided by the OpenCode provider (free tier) as a reference — replace them with your own providers. Run opencode models to list your available LLMs, or if you have no providers configured, use the /connect command inside the OpenCode TUI to connect them (see OpenCode Zen providers docs).

Huitzilopochtli 🏛️ — Supreme Orchestrator

Quetzalcoatl 🌬️ — Visionary Sage

Moctezuma ⚔️ — Strategist and Commander

Tlaloc 🌧️ — Builder and Artisan

Mictlantecuhtli 💀 — Judge and Guardian

Tezcatlipoca 🔮 — The Smoking Mirror

Additionally, over 355 specialized subagents organized in 10 packs 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 on the Wiki.

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, visit the GitHub Wiki → Getting Started guide to configure models, install plugin dependencies, and start your first workflow.

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 v2.0+ installation current |

Version-gated updates: Update Workspace only runs on v2.1+ installations. v1.x installations must reinstall with Clean or Project Install; <1.2.0 installs receive a cleanup suggestion. See docs/MIGRATION.md for the upgrade guide.

# Interactive menu (default):
bunx @fisherk2-dev/codice

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

Códice lets you select which agent packs to install. Install specific packs non-interactively, or add packs later during an update:

# Install only software-development and business packs:
bunx @fisherk2-dev/codice --packs software-development,business

# Install all 8 selectable packs:
bunx @fisherk2-dev/codice --packs-all

# Update an existing installation and add the creative pack:
bunx @fisherk2-dev/codice --update --update-add-packs creative

Use --verbose for detailed logging of every step.

Flags

| Flag | Description | |------|-------------| | --dest <path> | Target installation directory (default: current directory) | | --force | Skip all confirmation prompts | | --verbose | Enable structured logging to stderr | | --version | Print package 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) | | --packs <list> | Install only the specified packs (comma-separated, e.g. software-development,business) | | --packs-all | Install all 8 selectable packs | | --update-add-packs <list> | Add packs to an existing installation during update | | --help | Show usage help |

Documentation: Getting Started · Agents · Skills · Commands · MCP Servers · Configuration

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"]
    H --> J2["/deploy<br/>DEPLOY (post-ship)"]

    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
    N["/help<br/>HELP"] -.-> A
    P["/sync<br/>SYNC (wildcard)"] -.-> A
    P -.-> B
    P -.-> C
    Q["/migrate<br/>MIGRATE (optional)"] -.-> A
    Q -.-> L
    Q -.-> M
    R["/analyze<br/>ANALYZE (pre-diagnose)"] -.-> Q
    R -.-> M

Full Cycle

| Phase | Command | Agent | What It Does | Main Skills | |------|---------|--------|--------------|-------------| | Onboarding | /help | huitzilopochtli | Interactive help menu with 6 options — discover Códice, start a new project, update workspace, learn the SDD cycle, list all 17 commands, troubleshoot issues | | | 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 | | Sync workspace | /sync | tlaloc | Bidirectional git sync with 4 modes (full-sync, incremental-sync, dry-run, conflict-resolution) and 4 conflict resolution strategies (NEWER_WINS, GITHUB_WINS, LOCAL_WINS, INTELLIGENT_MERGE). Pre-flight checks git + remote. Wildcard — can be invoked at any SDD phase | git-workflow-and-versioning, interview-me, observability-and-instrumentation | | Migrate stack (optional) | /migrate | quetzalcoatl | Detects current tech stack from lock files, evaluates breaking changes between versions, generates a structured migration plan in docs/MIGRATION.md with phases, steps, and rollback procedures. Updates WORKFLOW.md and specs/ automatically | dependency-audit, interview-me, deprecation-and-migration, test-driven-development, changelog-generate | | Analyze architecture | /analyze | quetzalcoatl | 8-dimension analysis (system structure, design patterns, dependency architecture, data flow, scalability, security, testability, documentation). Generates prioritized docs/TECH_DEBT.md with Critical/High/Medium/Low findings. Findings feed /diagnosis | clean-ddd-hexagonal, design-patterns, dependency-audit, observability-and-instrumentation, performance-analysis, security-and-hardening, test-driven-development, documentation-and-adrs, code-review-and-quality | | Deploy | /deploy | mictlantecuhtli | Post-/ship deployment. 3 modes: no workflow (generate from scratch), betterable (analyze + optimize), established (execute documented workflow). Generates branch protection, PR templates, CI pipelines, and updates CONTRIBUTING.md | ci-cd-and-automation, git-workflow-and-versioning, bash-defensive-patterns, observability-and-instrumentation, interview-me |

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 | | 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 |

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.
• msitarzewski/agency-agents — Source of the new subagents added to the pack system. This repository provided the agent definitions that were adapted and integrated into Códice's 10-pack architecture.

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