niksavis/basicly

A coding-agent harness. One catalog projected into every agent's config, a deterministic loop that runs on it, and git gates at commit time.
## What is basicly?
Most agent harnesses ship instructions and skills. basicly also ships the
workflow and the state — a deterministic development loop, the work
graph it derives progress from, and git gates that hold whether or not the model
read the guidance.
Four pillars:
01 Guidance — one versioned YAML catalog, projected into what each tool
natively reads: CLAUDE.md, AGENTS.md, .github/copilot-instructions.md,
skills, subagents, permissions. Edit one fragment and every target regenerates
consistently. Your overrides live in an overlay that upgrades never touch.
02 Gates — git hooks across pre-commit, commit-msg and pre-push, plus
agent hooks and a verify pipeline. Enforcement is at commit time, not only in
CI: a hook that refuses the commit is a different guarantee from a check that
fails the build afterwards.
03 The loop — one way to drive work, shipped as commands: intake, classify,
decompose, build, verify, validate, ship — driven the same way under Claude,
Codex or Copilot, and not the only way work gets done here. Work builds in an
isolated worktree; run one track at a time, or fan out parallel lanes behind a
serial merge queue.
04 The work graph — issues, dependencies, gate results, checkpoints and
evidence live in a tracked graph. The loop keeps no side-state: the phase a
track sits in is derived from that graph, so a session can crash, compact, or
hand over to a different agent family mid-track and the next command picks it
up by re-reading it.
The pillars are not a bundle of files. The loop, and every headless agent it
dispatches, reads the artifacts pillar 01 emits — so the config layer's output
is the orchestrator's contract. That is why the same track can start on one
agent and finish on another, and it is what a projector alone or an orchestrator
alone cannot offer.
## Quick start
### Install
basicly requires Python 3.14+ — for the CLI and for the projected hook
scripts that run inside your repo; older interpreters are not supported.
The default markdown gate also needs Node and a local markdownlint-cli2 package before
install. If your repository already locks the package, run npm ci. Otherwise, get the
repository owner's approval, then run npm install --save-dev markdownlint-cli2 and commit
the package files. Install and --dry-run refuse missing tools before writing files.
They do not add dependencies automatically. Before the first commit, select Markdown
inputs in your repository-owned .markdownlint-cli2 configuration. A style-only
.markdownlint.json configuration does not select inputs. Keep existing input and rule choices.
See markdown gate prerequisites
for an explicit scratch setup and the opt-out.
From inside a git repository, install the latest release on Linux, WSL or macOS:
sh
curl -fsSL https://niksavis.github.io/basicly/install.sh | sh
Windows (PowerShell):
powershell
irm https://niksavis.github.io/basicly/install.ps1 | iex
These permanent URLs serve scripts from the latest published release. They install uv
when needed and select Python 3.14 or later. They resolve a versioned release wheel before