WADE — Workflow for AI-Driven Engineering

AI tools write the code. WADE handles everything else.

Every Wade does the dirty work so the heroes don't have to.

Branches, worktrees, context loading, model selection, PR creation — all the workflow friction that surrounds AI coding sessions. WADE eliminates it. Works with Claude Code, Copilot, Gemini, Codex, and more. Run wade init once per project, then just point it at a GitHub (more to come!) issue number.

See It in Action

Starting work on Issue #42:

Without WADE:

git fetch origin && git checkout main && git pull
git checkout -b feat/issue-42-user-auth
# paste issue title + description into AI chat
# explain your branching rules, test locations, linters to run...

With WADE:

wade 42

WADE fetches the issue, detects whether it's been planned, and starts the right session automatically — planning if no plan exists yet, implementation if it does. Creates an isolated git worktree, launches your AI tool with the full issue loaded — title, description, labels, and all your project conventions — and Skills guide the AI from first commit to open PR without you touching git again.

Finishing work and opening the PR:

Without WADE:

git checkout main && git pull
git checkout feat/issue-42-user-auth
git merge main          # resolve conflicts yourself, if any
git push
gh pr create --title "User Auth (#42)" --body "..."   # write description manually
# don't forget to link the issue, clean up the branch...

With WADE (the AI handles all of this):

wade implementation-session done

The AI merges the latest main into the branch, resolves any conflicts, writes the PR description from what it built, and marks it ready for review — you get a clean, already-integrated diff with no noise for your reviewer.

Working on multiple issues at once:

wade implement-batch 42 43 44   # three worktrees, three AI sessions, zero stashing

Why WADE

Installation

One-line install script (installs uv automatically if missing):

curl -LsSf https://raw.githubusercontent.com/ivanviragine/wade/main/install.sh | sh

Or, if you already have uv or pipx:

uv tool install wade-cli    # recommended
pipx install wade-cli

Requires gh CLI (authenticated) and at least one supported AI coding tool.

gh auth login    # if not already authenticated

Quick Start

Initialize WADE in your project (once):

wade init

Then start working:

# Plan a feature — AI creates GitHub issues and draft PRs
wade plan

# Start working — WADE detects plan state and picks the right session automatically
wade 42

Commands

Short aliases: wade p (plan), wade i <N> (implement), wade r <N> (review pr-comments).

Most workflow commands accept --ai <tool>, --model <model>, --effort <level>, and --yolo to override configured defaults. implement also supports --detach (new terminal tab) and --cd (print worktree path only).

Supported AI Tools

Adapters, model/effort resolution, and per-tool config (allowlists, hooks) are powered by crossby, WADE's AI-tool-integration dependency.

Task Providers

WADE can pull tasks from three backends — pick one when you run wade init:

PRs always flow through GitHub regardless of choice — wade fetch-reviews,
the auto-poll loop, and review-thread resolution work identically across
providers.

Markdown provider

Useful when you want issues versioned alongside the code, with no external
service. Each issue is one ## heading in the file:

# Wade Issues

## #47239185 Add login feature

<!-- wade
state: open
labels: feature, complexity:medium
-->

Description body here. Sub-headings, code blocks, anything markdown.

• The file is resolved against the main worktree, so every linked
  worktree reads/writes the same physical file. No textual merge conflicts
  on ISSUES.md.

• IDs are random 8-digit decimal so two parallel wade implement sessions
  in different worktrees can't collide. They stay numeric so existing
  #NN checklist refs in tracking-issue bodies still work.

• Configure via .wade.yml:

  provider:
    name: markdown
    settings:
      path: ISSUES.md      # relative to repo root, or absolute
      auto_commit: false   # if true, close_task auto-commits the change
  

• After a PR merges, provider.close_task flips the section's state to
  closed in ISSUES.md. By default the file is left modified in your
  working tree — commit it yourself. Set auto_commit: true to have
  wade commit the change with a chore: close #N message; failures
  (not a git repo, hook rejection, signing required) are logged and
  swallowed so the close itself never blocks.

• Tracking issues with - [ ] #N checklist bodies work the same as with
  GitHub Issues — markdown's find_parent_issue scans every section's
  body for child refs.

Agent Skills

wade init installs Skills that teach your AI agent the workflow — issue format, planning rules, implementation session rules, and dependency analysis. Skills, the AGENTS.md workflow pointer, and any tool-specific configuration are set up automatically for every supported tool. Nothing to configure manually.

Worktree Hooks

Configure automated setup when worktrees are created via wade implement or wade implement-batch. Add a hooks section to .wade.yml:

hooks:
  post_worktree_create: scripts/setup-worktree.sh
  copy_to_worktree:
    - .env
    - .env.example

post_worktree_create — A setup script to run after each worktree is created. Use it to install dependencies, run builds, or prepare the environment so worktrees are ready to use immediately.

copy_to_worktree — Files to copy from the project root into the worktree before running the hook. Useful for secrets and config files (e.g., .env) that are gitignored and wouldn't otherwise be present in a new worktree.

See templates/setup-worktree.sh.example for a starter script.

Shell Integration

To make wade cd <N> actually change your directory (instead of just printing the path), add this to your shell profile:

eval "$(wade shell-init)"

Tab completion:

wade --install-completion bash   # or zsh / fish

Upgrading

wade update

Detects your install method (uv tool, pipx, Homebrew) and upgrades automatically, then refreshes all managed project files.

Contributing

See CONTRIBUTING.md.

License

MIT