Dev On Leash
diogeneshfg/dev-on-leash
Harness verificado para dev assistido por IA com gates arquiteturais
Ver no GitHubHarness de desenvolvimento orientado por verificação que transforma planos em Markdown em workflows machine-checked com gates arquiteturais, agentes de revisão e execução paralela. Funciona como plugin Claude Code portável ou executa via scripts Python puros em CI/pre-commit sem dependência do Claude.
Instalação
npx convez-ai diogeneshfg/dev-on-leash1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Aplicar disciplina machine-checked em planos de desenvolvimento em Markdown
- Enforçar arquitetura de projeto com mechanical gates (import-linter, dependency-cruiser)
- Executar tarefas em paralelo com scheduler inteligente e checklist verificado
Veredito

Ferramenta robusta para equipes que precisam de rigor em desenvolvimento assistido — oferece verificação machine-checked, gates arquiteturais e integração CI/pre-commit. Curva de aprendizado exigente, mas retorno alto para projetos complexos com equipes distribuídas.
README
A tradução para o português deste README ainda está na fila.
dev-on-leash
A verify-gated task harness for AI-assisted development, packaged as a portable Claude Code plugin.
dev-on-leash turns a Markdown plan into a machine-checked workflow: a
harness task declares a verify command, its checkbox is ticked only when
that command passes, and every ticked harness task can be independently
re-verified so a hand-flipped checkbox cannot survive CI or a pre-commit hook.
It ships a
parallel-execution scheduler, a doc-freshness check, an auto-appended
changelog, custom review agents, a bootstrap skill that scaffolds the
whole setup into any project, and an architecture leash that turns a
prose architecture description into mechanical gates and a project-local
reviewer agent.
What's in the box
- Harness scripts (
scripts/harness/) —validate_plan,run_task,cycle_done,plan_schedule(parallel scheduler),check_freshness, baseline/regression tooling,validate_architecture/compile_architecture(architecture-leash). CI-executable, no Claude Code required. - Skills (
skills/) —bootstrap-dev-leash(interviews a project and generates a tailoredCLAUDE.md+AGENTS.md),execute-plan-task, andcompose-architecture-leash(declares an architecture and compiles it to gates + reviewer agent). - Agents (
agents/) —plan-reviewer,tdd-evidence-checker,isolation-reviewer,verification-gate,architecture-extractor. - Templates (
templates/) —CLAUDE.md/AGENTS.mdskeletons,task-schema,plan-template,settings.json,architecture-reviewer.md.tmpl. - Init scripts (
scripts/init.*) — copy the project-agnostic layer into a target repo without an interview.
Install
/plugin marketplace add diogeneshfg/dev-on-leash
/plugin install dev-on-leash@dev-on-leash
/bootstrap-dev-leash # interview + generate CLAUDE.md / AGENTS.md
How it works
A plan is a Markdown file with ## Task N headings. Augment any task with
a task-meta block — id, touches, depends, verify — to make it
machine-verified. task-meta is an augmentation, not a separate plan format;
tasks without one are human-run and ignored by the harness. The harness then
drives the loop:
validate_plan.py <plan>— checks the task-meta schema, dependency graph, and write-collisions; warns about task headings with notask-meta.plan_schedule.py <plan>— shows which tasks can run in parallel.run_task.py <plan> <id>— runs the task'sverifycommand and ticks its checkbox only if it exits 0. A failing verify leaves the box unticked.cycle_done.py --plan <plan>— once every task is checked off, runs the project's.harness/gatescommands and appends aCHANGELOG.mdentry.
The harness is plain Python operating on Markdown — no Claude Code required to run it, and no dependency on any other plugin.
Architecture leash
Once a project is bootstrapped, run /compose-architecture-leash to put its
architecture under the same machine-checked discipline as the rest of the
harness. The skill interviews the user in prose, dispatches the
architecture-extractor subagent to convert that prose into a structured
.harness/architecture.yaml, and compiles the YAML into enforcement
artifacts:
- Mechanical gates in
.harness/gates: dependency-direction contracts for Python (import-linter) and JS/TS (dependency-cruiser), plus a generic Python check script per forbidden-imports rule. - A project-local reviewer agent at
agents/architecture-reviewer.md, rendered fromtemplates/architecture-reviewer.md.tmplwith the declared layers, edges, and judgment rules baked in.
Re-runnable in three modes — add, revise, re-describe — so the
spec grows with the project. Every gate line carries # arch-leash:<id>
so the compiler can prune cleanly when a rule is removed.
dev-on-leash dogfoods this on itself: see .harness/architecture.yaml,
the generated .harness/checks/, and scripts/dogfood_architecture.py
(which plants a deliberate import requests in the harness layer and
asserts the gate rejects it).
Session leash
Concurrent Claude Code sessions on the same repo would otherwise share
one working tree and clobber each other's WIP. The session leash
detects this at SessionStart, blocks writes in the non-elected
session via a PreToolUse gate, and routes that session into its own
sibling git worktree via the /leash-session-new skill — auto-invoked
by the blocked agent. The worktree is cleaned up by
/leash-session-end and a conservative sweep in cycle_done that only
touches worktrees whose branch is merged, clean, and whose PID is dead.
Lockfiles live in .harness/sessions/<pid>.json (gitignored). PID
liveness is checked via ctypes on Windows and os.kill(pid, 0) on
POSIX. The two-phase write at SessionStart deterministically elects
the lowest-PID live session as primary, so the design needs no OS
lock.
dev-on-leash dogfoods this on itself: see scripts/dogfood_session.py,
which plants a peer lockfile, runs the hook, asserts the gate denies
an Edit, drives the resolution path, and asserts the gate unblocks
once the worktree is in place.
Parallel work with worktrees (opt-in)
Branch discipline is mandatory — every change on a new <type>/<slug> branch
off main. Worktrees make running several of those branches at once
comfortable, without the stash-dance.
- Bootstrap offers to standardize a
.worktrees/layout and adds.worktrees/to.gitignoreunder the# dev-on-leashheading. /leash-start-workstarts a change in its own worktree:git worktree add .worktrees/<slug> -b <type>/<slug> main. It delegates the mechanism toEnterWorktree/superpowers:using-git-worktreeswhen present.cycle_done.pyprints an advisory reminder togit worktree removeonce a<type>/<slug>branch is merged (it never removes feature worktrees for you).
This is distinct from the session leash, which reactively creates a sibling worktree only when two Claude Code sessions collide on the same repo.
Trust model
Be precise about what the harness enforces and what it only assists:
- Enforced. A harness task's checkbox is ticked only by
run_task.pyafter itsverifycommand exits 0.recheck_plan.pyre-runs theverifyof every ticked harness task — run it in CI (see templates/ci-snippet.md) and/or as the opt-in pre-commit hook, and a checkbox flipped by hand without the work done is rejected. A task heading with notask-metablock is human-run and not machine-checked. Session leash: while a second session is inpending-worktreeorpending-resolution, thePreToolUsegate deniesEdit,Write, andMultiEdit. - By convention only.
touchesis self-reported: the harness does not yet check that a task modified only its declared files, so the parallel-safety ofplan_schedule.pydepends ontouchesbeing accurate. Verifying it without false positives needs its own design — tracked as a follow-up. Session leash:Bashis intentionally outside the gate matcher (so/leash-session-newcan rungit worktree add); a determined session could write to the primary checkout via>redirects. Same posture astouches. - Escape hatch.
cycle_done.py --force -m <reason>closes a cycle past failing gates and appends an audit line to.harness/exceptions.log. It bypassescycle_done's own gate check only — it does not disablerecheck_planrunning in CI or the pre-commit hook. Session leash has no per-session bypass in v1: a user who really needs two sessions on the primary checkout must remove theSessionStart/PreToolUseentries from.claude/settings.json, which is a visible git change.
Validate the harness
python scripts/smoke_e2e.py
Builds a throwaway repo and drives the whole loop end to end in ~5s. Runs in CI on every push.