convez.ai
SkillAutomaçãoAvançado
diogeneshfg

Dev On Leash

diogeneshfg/dev-on-leash

Harness verificado para dev assistido por IA com gates arquiteturais

Ver no GitHub
InicialPluginScore · de 0 a 100

Harness 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-leash

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
v0.6.0
Issues abertas
0
Contribuidores
1

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 tailored CLAUDE.md + AGENTS.md), execute-plan-task, and compose-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.md skeletons, 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:

  1. validate_plan.py <plan> — checks the task-meta schema, dependency graph, and write-collisions; warns about task headings with no task-meta.
  2. plan_schedule.py <plan> — shows which tasks can run in parallel.
  3. run_task.py <plan> <id> — runs the task's verify command and ticks its checkbox only if it exits 0. A failing verify leaves the box unticked.
  4. cycle_done.py --plan <plan> — once every task is checked off, runs the project's .harness/gates commands and appends a CHANGELOG.md entry.

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 from templates/architecture-reviewer.md.tmpl with 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 .gitignore under the # dev-on-leash heading.
  • /leash-start-work starts a change in its own worktree: git worktree add .worktrees/<slug> -b <type>/<slug> main. It delegates the mechanism to EnterWorktree / superpowers:using-git-worktrees when present.
  • cycle_done.py prints an advisory reminder to git worktree remove once 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.py after its verify command exits 0. recheck_plan.py re-runs the verify of 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 no task-meta block is human-run and not machine-checked. Session leash: while a second session is in pending-worktree or pending-resolution, the PreToolUse gate denies Edit, Write, and MultiEdit.
  • By convention only. touches is self-reported: the harness does not yet check that a task modified only its declared files, so the parallel-safety of plan_schedule.py depends on touches being accurate. Verifying it without false positives needs its own design — tracked as a follow-up. Session leash: Bash is intentionally outside the gate matcher (so /leash-session-new can run git worktree add); a determined session could write to the primary checkout via > redirects. Same posture as touches.
  • Escape hatch. cycle_done.py --force -m <reason> closes a cycle past failing gates and appends an audit line to .harness/exceptions.log. It bypasses cycle_done's own gate check only — it does not disable recheck_plan running 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 the SessionStart / PreToolUse entries 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.

Ver o original no GitHub

Bom para

Relacionados