ai-devkit

Global CLI for engineers and QAs that provisions and maintains ai-workbench instances — self-contained bundles of repos, prompts, Figma refs, and MCP wiring that an AI agent (Devin or Claude) can drive end-to-end.

One machine-wide install. Three commands. No per-project setup.

---

Install

git clone https://github.com/amit-t/ai-devkit ~/Projects/Tools-Utilities/ai-devkit
cd ~/Projects/Tools-Utilities/ai-devkit
./install.zsh
source ~/.zshrc

The installer:

• symlinks init.wb, join.wb, update.wb into ~/.local/bin/
• registers zsh aliases (including .dev / .cly agent-forcing variants)
• warns if ~/.local/bin is not on your PATH

Run once per machine. After that, the commands are available from any directory.

---

Commands

Command	Role	Default agent	Force variants
init.wb	Initiator	Devin (falls back to Claude)	init.wb.dev, init.wb.cly
join.wb <workbench-url>	Joiner	Devin (falls back to Claude)	join.wb.dev, join.wb.cly
update.wb	Either	Devin (only if interactive conflict)	update.wb.dev, update.wb.cly
wb.rescan	Either	Devin (falls back to Claude)	--agent devin|claude override

All three core commands launch the configured agent with a role-specific prompt. The agent handles the interview, repo creation, templating, and git operations — the shell scripts are thin launchers.

• Auto-built repo context — init.wb and join.wb produce context/<repo>/CONTEXT.md per registered source repo, plus an aggregate context/README.md index. Source repos are never mutated (scans run in a throwaway git worktree sandbox). Failed scans degrade to a stub; refresh or repair with wb.rescan. See docs/repo-context-scan.md.

---

Quickstart

1. Initiator — start a new bundle

Typical use: a QA spinning up a workbench for a new epic.

mkdir ~/workbenches/wb-example && cd ~/workbenches/wb-example
init.wb

The agent will ask for: label, epics, repos, Figma refs, and MCPs. When it's done it creates a private GitHub repo, pushes the workbench, and hands you a share URL for collaborators.

2. Joiner — pick up an existing bundle

Typical use: a dev joining the QA's workbench.

cd ~/workbenches
join.wb https://github.com/<your-org>/wb-example

The agent clones the workbench, asks which additional repos you need for your work, appends them to project.conf, adds you to CODEOWNERS, commits, and pushes.

3. Updates — pull template changes safely

cd ~/workbenches/wb-example
update.wb

Pulls only template-owned files from ai-workbench. Your outputs, configs, and local state are never touched.

---

Requirements

• gh — authenticated against GitHub. HTTPS and SSH (including custom hostnames) both supported.
• git, rsync, python3, zsh — standard on macOS; install via your package manager on Linux.
• devin CLI (preferred) or claude CLI. Use .cly variants to force Claude when both are installed.

---

Layout

ai-devkit/
├── install.zsh              # one-shot installer
├── init-workbench/          # init.zsh  + init.prompt.md
├── join-workbench/          # join.zsh  + join.prompt.md
├── update-workbench/        # update.zsh + update.prompt.md (interactive only)
├── orgs-workbench/          # orgs.wb — manage the devkit org list
├── lib/                     # shared shell libraries (orgs.sh, …)
└── tests/                   # zsh regression tests (run via tests/run-all.zsh)

Each subdirectory pairs a short zsh launcher with the prompt that drives the agent. Update a prompt, and every user of that command picks up the change on their next run.

---

Tests

zsh tests/run-all.zsh

Covers the regressions Devin has flagged in past runs (e.g. orgs.wb PATH/symlink resolution, init.wb Step 3.10b .ralph/ rebuild). Add a new tests/test-*.zsh whenever a fix lands.

---

Versioning + upgrades

ai-devkit ships under semver. Every release bumps version.json (handled by release-please). To update your local clone:

devkit.upgrade            # interactive y/N
devkit.upgrade --yes      # unattended
devkit.upgrade --rollback # revert to prior version

To see status of all your tools (devkit, ralph, wb-template if inside a stamped wb):

devkit doctor
devkit doctor --fix       # upgrades all stale tools in dep order

See docs/versioning.md for the full system. First-time setup: ROLLOUT-VERSIONING.md.

---

Running on WSL2

WSL2 Ubuntu is a supported environment. Install the minimum prereqs:

sudo apt install -y zsh jq gh git curl

Clone repos under $HOME (not under /mnt/c/ or any other DrvFs mount). DrvFs paths are roughly 10x slower than the WSL2 ext4 filesystem and they break fsync semantics that ralph and git rely on. The devkit-doctor preflight will warn (check_wsl_mnt_path) if you run devkit doctor from a /mnt/ path.

The installer accepts a non-interactive mode (used by CI in .github/workflows/smoke-install.yml):

DEVKIT_NONINTERACTIVE=1 zsh install.zsh
# or
zsh install.zsh --yes

In non-interactive mode any prompt accepts the safe default (org slug falls back to $DEVKIT_DEFAULT_ORG or the current git remote owner, optional installs default to yes). Interactive TTY behaviour without the flag or env var is unchanged.

---

Related

Part of the ai-workbench ecosystem.