Complete Guide

From zero to first deploy. Understand how each piece of AI Workbench connects and how to use it in practice.

Complete Flow

Phase 1: Project Setup

Clone the Repository

git clone https://github.com/jdonini/ai-workbench.git
cd ai-workbench

Run the Setup Wizard

cd /your/existing/project
claude /path/to/ai-workbench/templates/setup-wizard.md

The wizard asks 12 questions about your project and automatically detects the stack. At the end, it generates the entire configuration structure.

Install Superpowers for Your Tool

Phase 0 installs superpowers, but the installation method depends on the tool:

Claude Code (official marketplace)
/plugin install superpowers@claude-plugins-official

Claude Code (obra marketplace)
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Codex
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

OpenCode
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

Install the Codex Plugin

The codex-plugin-cc allows using Codex inside Claude Code for reviews and task delegation:

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins

After installing, run /codex:setup to verify Codex is ready. If not logged in, run !codex login.

Phase 2: Tools

Claude Code — Orchestrator

Main tool that orchestrates the workflow. Uses CLAUDE.md as entrypoint and manages subagents.

/start-feature

Starts a new feature with brainstorm + planning

/debug-issue

Systematic debugging with hypotheses

Codex CLI — Review

Used as an automated reviewer. Runs subagents to verify code quality before commit.

/review-code

Delegates review to Codex

OpenCode — Executor

Alternative open-source executor. Supports OpenRouter as provider, allowing use of low-cost models.

opencode run

Runs tasks with configured model

Zed / VS Code — Editors

Alternative editors that read the same configuration generated by the wizard. Compatible with .claude/ and .opencode/.

Phase 3: SDD Workflow in Practice

Brainstorming

Before coding, describe the feature. The brainstorming skill should activate automatically:

I want to implement JWT authentication
with refresh tokens.

The brainstorming skill should explore:
- Functional and non-functional requirements
- Alternative approaches
- Risks and dependencies

Isolated Branch + Plan

After the design is approved, Superpowers should move into worktree creation and structured planning:

Expected flow after approval:
- using-git-worktrees
- writing-plans

Generated files:
- docs/spec/...-design.md
- docs/plan/...md

Execution + TDD

Implementation should happen task by task through the execution workflow, with TDD enforced during each step:

Recommended execution:
/subagent-driven-development

Alternative:
executing-plans

Inside each task:
1. RED: Write a failing test
2. GREEN: Minimal code to pass
3. REFACTOR: Improve without breaking tests

Review + Finish

Between tasks, Superpowers should run code review. At the end, finish the branch with the closing workflow:

Review skill:
requesting-code-review

Close-out command:
/finishing-a-development-branch

This verifies:
- Code quality
- Test coverage
- Plan compliance
- Merge / PR readiness

Merge

Clean commits, PR ready for human review:

git add -A
git commit -m "feat: feature description"
git push origin feature/feature-name

Maintenance

↻

Wizard Update

To update the project configuration, re-run the wizard. It detects the current state and updates only what's necessary:

claude /path/to/ai-workbench/templates/setup-wizard.md

Next Step

Now that you understand the complete flow, explore each tool in detail.

View Tools View Workflow