workways: Scaffolding Agentic Workflows Into Your Repo

Every time I started a new project with an AI coding agent, I rebuilt the same scaffolding. A way to run e2e suites in parallel without the simulators trampling each other. A way to attach screenshots to a PR description. A way to let the agent drive my actual logged-in browser instead of a flagged automation one. The patterns were solid, but they lived as copy-paste folklore in my head and in four or five private repos.

workways is those patterns, packaged. It's a collection of clusters, small focused bundles of skills, scripts, and methods, that you scaffold into a repo with one command. Battle-tested in real Claude Code projects, then pulled out so you can drop them into your own.

Scaffold, don't depend

The core decision is in the name of the command: npx workways add. It does not install a library you import at runtime. It copies files into your repo (bash scripts, Markdown methods, .claude/ skills) and then gets out of the way.

npx workways list                  # see available clusters
npx workways add rn-e2e            # copy one cluster into cwd
npx workways add --all             # copy everything

Flags: --dest <dir>, --force, --dry-run.

It ships as files, not a dependency, for a reason. Half of this is bash and Markdown, which has to live in your repo anyway, and the other half, the Node and Playwright pieces, you're going to want to customize. A runtime dependency you can't edit is the wrong shape for "automation glue specific to your project." Owning the files makes both the editing and the reading natural. Your agent sees the skill the moment it lands, and when it doesn't quite fit, you change it.

The clusters

Each cluster solves one problem I actually hit. Most ship a ready-to-use .claude/ skill or a CLAUDE.md-linkable method, so the agent picks up the capability immediately.

rn-e2e: parallel Appium on iOS

The big one. Running multiple React Native e2e suites at once means fighting over global resources: the simulator, the Metro port, Xcode's DerivedData. This cluster gives each worktree its own. A UDID-keyed sim lock auto-discovers and boots a free simulator; a port-keyed Metro lock allocates a free bundler port; with-derived-data.sh redirects each build into a per-worktree directory so concurrent expo run:ios builds don't corrupt each other. It ships a wdio + Mocha harness with per-spec webm recording, and a docs/proof/ writeup showing two worktrees, two sims, two Metros, the same spec green on both at once.

pr-screenshots

An end-to-end pipeline for embedding screenshots and videos in private-repo PR descriptions, where the usual drag-and-drop upload trick doesn't work headlessly. A screenshot helper names captures by branch and route; a Playwright wrapper borrows your Chrome session, uploads to GitHub's user-attachments, and rewrites the PR body in place.

browser-attach

Drive your real, logged-in Chrome over CDP instead of letting an automation MCP spawn its own browser. The automation fingerprint (navigator.webdriver, the "controlled by automated test software" banner) comes from the --enable-automation launch switch, not the CDP connection. Attach to a human-launched Chrome and it looks like an ordinary browser. The cluster ships a skill with lazy-loaded per-site subskills, and is honest in the docs about what it does and doesn't defeat: it beats the flag, not Akamai, Cloudflare, Turnstile, or Google sign-in.

serveoptions

Make a UX decision by seeing it. Generate N meaningfully distinct variations of a feature, drop a dev-only selector pill that cycles them via a ?option=N param, and serve locally so you pick the winner in the browser. After you choose, the selector and losing options are stripped, leaving only the chosen implementation.

method, zsh-keybindings

The smaller ones. method drops a shipping methodology (atomic PRs, ephemeral worktrees, a manual-QA gate, the PR-screenshot rule) as a docs/methods/ bundle you link from your CLAUDE.md. zsh-keybindings fixes Option+Left / Option+Right word-jumping in zsh so you stop getting ;3C;3D garbage in your prompt.

Why this shape works for agents

An AI coding agent is great at applying a known pattern and bad at rediscovering one from scratch every session. Putting the pattern in the repo, as a skill the agent loads or a method it reads, turns "figure out how to run parallel e2e" into "follow the procedure that's already here." The agent stops improvising the boring, error-prone parts and spends its budget on your actual problem.

That's the whole bet behind workways: the reusable half of agentic work is glue, and glue belongs in your repo where you and your agent can both see and edit it.

npx workways list

It's MIT licensed. Take what's useful, change the rest.