better-dev

better-dev

Portable dev practices, packaged as skills - that run inside the coding agent you already use.

better-dev is a set of SKILL.md practices that make your existing agent - Claude Code, Codex, hermes, pi - do software development well, whether you're starting a project from scratch or working in an existing codebase. It's not an agent, framework, or provider layer. It adds one opinionated method and gets out of the way of everything else you've installed:

idea → scope it into an observable contract → isolate it → drive a loop to proven done → ship - and when you're missing a tool, go source it.

Status: built and self-verified (bd-package-check green), reimplemented from ~100 sources and audited against forge/devloop and loop-engineering. Not yet battle-tested in live multi-harness runs. Design notes: docs/PLAN.md · docs/DECISIONS.md.

Quick start - one paste

From inside the repo you want to set up, paste this into your agent. It installs better-dev once for your machine, then wires the repo:

Set up better-dev in this repo. Read https://raw.githubusercontent.com/yoelgal/better-dev/main/BOOTSTRAP.md
and follow it exactly: detect my coding agent, install better-dev globally for it if it isn't already, then
run /onboard to wire this repo. Ask me only if something is genuinely ambiguous.

Set up better-dev in this repo. It's a portable set of dev practices packaged as skills, in two layers: the
TOOL (skills + bd-* scripts + hooks) installs GLOBALLY once per machine and every repo shares it; a repo's
.better-dev/ holds that repo's DATA only.

1. Detect which coding agent I'm in (Claude Code ~/.claude, Codex ~/.codex, or other) - that decides the
   install command and the global skills directory.
2. Install the tool globally, once per machine. If it's already installed (a better-dev entry in the host's
   global skills dir, or an existing clone), run `git pull` in the clone and skip to step 3. Otherwise: on
   Claude Code install it as a plugin (add this repo as a marketplace, then install better-dev); on any host,
   `git clone https://github.com/yoelgal/better-dev ~/better-dev && ~/better-dev/install.sh`, which links the
   tool into the host's global skills dir. Update later with /update (a `git pull` in the clone underneath).
3. Run /onboard in this repo to wire it: create .better-dev/ for DATA only (rules.md, overrides.md,
   learnings.jsonl committed; ledger/ gitignored), create .better-dev/bin as a per-machine symlink to the
   global install's scripts so .better-dev/bin/bd-mem resolves here, and write a discovery block and a
   comms-style block into the entry file (CLAUDE.md / AGENTS.md).

Adapt to whatever conventions already exist; ask me only on genuine ambiguity.

Then your next message can just be "here's a bug…", "here's a feature…", or "let's build an app that…" - the wired repo carries an utterance-to-skill routing table, so you say what you want and the chain runs itself. Uninstall any time with /uninstall (or scripts/bd-uninstall): dry-run by default, removes only what better-dev installed, and never touches your .better-dev/ data unless you ask.

The method

Start a project from scratch, or land a feature or fix in an existing codebase - the work runs one spine: