Prerequisites

CLI	Purpose
git	Version control
gh	GitHub CLI — repo creation, auth, API calls
rsync	Template-owned file sync during update.wb
python3	Manifest rendering

Optional but recommended:

• ai-ralph — installed automatically by init.wb / join.wb on first run per machine.
• devin or claude CLI — drives the interview agent. Devin by default, Claude as fallback.

Install

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

install.zsh symlinks the workbench commands into ~/.local/bin/ and appends aliases to ~/.zshrc:

Command	Alias Variants	Purpose
init.wb	init.wb.dev, init.wb.cly	Create new workbench
join.wb	join.wb.dev, join.wb.cly	Join existing workbench
wb.upgrade	wb.upgrade.dev, wb.upgrade.cly	Pull template updates (replaces update.wb)
update.wb	(deprecated)	Old name for wb.upgrade; still works, prints a nag
orgs.wb	(none)	Manage GitHub org list
devkit.upgrade	(none)	Pull a newer ai-devkit release and reinstall
ralph.upgrade	(none)	Pull a newer ai-ralph release and reinstall
devkit doctor	(none)	Show version state for all three tools; offers --fix

The .dev variants force the Devin agent, .cly variants force Claude.

Ensure ~/.local/bin is on PATH:

export PATH="$HOME/.local/bin:$PATH"   # add to ~/.zshrc if missing
source ~/.zshrc

One-time bootstrap (existing clones)

If you cloned ai-devkit before the versioning release, run the bootstrap step once so the new aliases (devkit.upgrade, ralph.upgrade, wb.upgrade, devkit doctor) become available:

cd ~/Projects/Tools-Utilities/ai-devkit
git pull
./install.zsh
exec zsh

install.zsh is idempotent: re-running it will not duplicate alias lines or DEVKIT_CLONE exports. After exec zsh, the new commands are on PATH and the first run of any tool will perform a one-time version-check banner. See Versioning + upgrades for details.

First Workbench

mkdir -p ~/work && cd ~/work
init.wb

init.wb runs preflight (CLI checks, gh account confirmation, org picker, ai-ralph install if needed), then interviews you for:

• workspace label (kebab-case)
• Jira epic IDs
• code repos to register (name / url / role / stack)
• design references (optional)
• MCP servers to enable (Atlassian / Figma / none)

Then it creates ${ORG}/wb-<label>, clones registered code repos into repos/, renders project.conf + EPIC-PIPELINE.md, writes CODEOWNERS, runs ralph-enable inside the workbench, commits, pushes.

Output:

── Workbench initialized ────────────────────────────
  Label:      example
  Repo:       https://github.com/<org>/wb-example
  Path:       ~/work/wb-example
  ...
── Share with your counterpart ──────────────────────
  join.wb https://github.com/<org>/wb-example

After init: explore context/

After init.wb finishes, your new workbench has a context/ directory with one CONTEXT.md per registered source repo, plus an aggregate context/README.md index.

These files are devkit-generated domain summaries — they help agents (and you) understand each repo at a glance without grepping the source. Open them with your editor or skim the index:

cat context/README.md
cat context/<repo>/CONTEXT.md

A scan can fail (no HEAD in source, LLM crash, lock contention, etc.) — failed scans leave a stub with status: scan-failed in the frontmatter. Re-run with wb.rescan <repo> (or wb.rescan --all). See Repo Context Scan for the full feature reference.

Joining Someone Else’s Workbench

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

Preflight runs, you get appended to CODEOWNERS, any extra repos you bring get registered into project.conf.

Next Steps

• Commands — full CLI reference
• Versioning + upgrades: devkit.upgrade, ralph.upgrade, wb.upgrade, devkit doctor
• Repo Context Scan — auto-built per-repo CONTEXT.md and wb.rescan recovery
• Orgs — machine-local GitHub org list
• ai-workbench docs — what lives inside the workbench template
• ai-ralph README — autonomous loop engines