versatile.sh
A small organisation run as a side project: independent engines, a shared way of working with AI agents, and the harnesses that keep both honest.
Overview
versatile-sh is the organisation I run as a side project. It is built around one idea: independent engines. Each engine does one job (durable workflows, a test engine, a computer engine, a plugin protocol), keeps a neutral core that names no product, and can be used without the others.
The organisation is also a way of working. A small team works with AI agents, and the team learns once: what one person teaches an agent is turned into a shared rule, record or lint instead of living in one machine's memory.
This case describes that way of working in the public-safe sense: the structure, the flows and the gates. The harness repositories are private, so their paths are named but not linked. Engines appear by codename: nagare (durable workflow), hakoniwa (test engine), heya (computer engine), tsugite (plugin protocol).
| Part | What it is |
|---|---|
| Engines | Independent repositories with neutral cores, each with a record home |
| Company site | Static export of Next.js 16, Tailwind CSS 4 and TypeScript, with connector and skill directories and forms |
| Center harness | How the team works: router, workflow docs, skills, agents, commands, hooks, tools |
| Satellite harnesses | Engineering knowledge and project records, infrastructure config, research engine, media |
Getting started
A contributor clones the center harness and the satellites it needs side by side, then runs two tools. bin/sync brings everything up to date. bin/install links the skills, agents and commands into each checkout.
bin/sync # fast-forward clean checkouts on main; move read copies to each satellite's main
bin/install # link skills, agents, commands into each versatile-sh checkout
bin/install --with-hooks --with-timer # team hooks and a daily sync + harvest timer
bin/conformance # what each repository misses from the baseline- bin/install writes one symlink per skill, agent and command, listed in each project's .git/info/exclude so nothing is committed to a project.
- A project's own item with the same name wins over a linked one.
- bin/install creates a never-pushed local/ area for anything that is not part of the organisation, and builds a personal deny list from your other checkouts.
- bin/sync is idempotent: running it twice changes nothing the second time. It never stashes, resets or switches branches.
- --bump records the current main of each satellite as the submodule pointer, through a pull request.
The company site runs with mise, which installs Node.js, pnpm and Bun.
mise run install
mise run dev # pages on http://localhost:3000, without the forms API
mise run build # static export into out/
mise run preview # out/ plus the forms API| Variable | Used by | Effect |
|---|---|---|
| DATA_DIR | site server | Where the forms database is stored |
| CATALOG_DIR | site tasks | Catalog checkout read by mise run catalog and mise run skills |
| VERSATILE_CONFORMANCE=off | bin/sync | Skips the conformance summary line |
Architecture
The center harness is the one place that gathers everything. Every other harness is a satellite with its own repository, carried as a git submodule under harness/ in the center. Nothing is copied.
versatile-sh/.claude (center: how we work)
router, docs/work, skills, agents, commands, bin, hooks
|
+-------------------+--------------------+--------------------+
| | | |
versatile-harness hosting-harness research-harness <domain>-media
engineering rules infra + deploy method, studies, canonical images,
project records config per app generated home video, logos
|
+-- projects/<repo>/ profile, agents.md, adr/, roadmap, issues
project repositories: the product only (code, tests, README)| Harness | Holds |
|---|---|
| Center (.claude) | How we work: router, docs/work, skills, agents, commands, bin tools, hooks, the colleague guide. Never engineering rules or one project's facts |
| versatile-harness | Engineering knowledge base (premises, rules, patterns, standards, lints, design, decisions, architecture, research index) and the record home of each project |
| hosting-harness | Infrastructure and each app's deploy configuration |
| research-harness | The research engine: method, studies, state, a generated research home |
| media repositories | The canonical copy of every image, video, logo and design source |
| A project repository | The product only, written as if public tomorrow |
The truth of a satellite is its main on GitHub. The copy under harness/ is read-only and bin/sync keeps it at that main. A change is made in the sibling working copy, on a branch, through a pull request.
Everything that is not part of the organisation stays in local/ or in a person's own memory. The inverse holds too: anything about the organisation never has personal memory as its only home.
Learning loop
When a problem recurs or someone repeats a request, the response is a fixed protocol. Memory on one machine is not learning, and a rule only in prose will be broken again.
- 1Recognise the className the problem as a class, such as raw colour values in components. Check the open issues and the lint catalog first.
- 2Fix the root causeThe smallest change that removes the cause, not a patch on the symptom.
- 3CertifyA failing-first test or a before and after, plus a sweep for other instances of the class.
- 4Ask for confirmationOne line to the owner. The certification belongs to the agent, the confirmation to the owner.
- 5Codify the guardOnly after an explicit yes: a lint, check, test or ratchet, proved by reintroducing the mistake once, and registered in the lint catalog in the same unit of work.
- 6Record and shareA pull request in the shared home. Colleagues get it on their next pull.
If the owner does not answer, the fix and its regression test stay, the issue is marked fixed but not confirmed, and no class-wide guard is added. Separately, when a person does something better than the harness describes, it is recorded as a field practice under the file that owns the topic and replaces the rule text on its second confirmed case.
Pull request gate
In every versatile-sh repository work reaches main only through a pull request from a feature branch, merged with a merge commit after local validation. There is no direct push, and no force-push or history rewrite without the owner's explicit approval.
- 1Branchgit fetch, then a worktree on a feature branch from origin/main. Commits are granular, one concern each, each building.
- 2Validate locallyThe repository's one check command. CI workflows are manual and gate nothing, so the evidence in the pull request is the proof.
- 3Session knowledge checklistBefore opening the pull request, update what the session changed or learned: the project README and docs, the records in versatile-harness, any rule, pattern or lint that emerged, and the center harness if the way of working changed. Each goes through its own pull request.
- 4Record itbin/pr-ready stores the checklist answers for the branch. The hook on gh pr create holds the command until that record exists. It expires after a day.
- 5Merge and cleangh pr merge --merge --delete-branch, delete the local branch, remove the worktree, all in the same unit of work. The owner is told in the chat what was updated, with links.
The gate is symbolic and fails open. It satisfies itself only by doing the checklist, it does not apply to the harness repositories themselves, and it lets every other command through.
Research method
Real decisions run through one engine, the research harness. One study supports one owner decision, and a study that cannot name its decision does not start. Its method was rewritten from what earlier research did well and badly, and it is amended after every study.
- 1IntakeThe owner answers the questions before any work starts, recorded with the date.
- 2RecoverWhat is already closed for the topic, with its date and commit.
- 3CharterDecision, unit of analysis, judging rule, proof levels, floors, scope, seats and budget. The owner releases it.
- 4Frame attackA red team objects to the question and premises before any answer exists.
- 5Inventory and scoutA blind inventory built from the user outward and the code inward, then one macro table of candidates. The owner picks what to deepen.
- 6RoundsProposals, objections, decisions, audit and spikes, released in tranches. The owner decides after each tranche.
- 7Synthesis and closeA map or matrix, owner decisions with recommendations, deferred items with a trigger, a final audit by an auditor who is not the judge, and a retro that amends the method.
A narrow question one source settles is one-off research and skips the rounds. A choice inside a task gets a ten-line decision matrix in the pull request body, written before the candidates run.
Premises
A premise is a standing assumption every design starts from and does not re-argue in each task. Each one has its own small file in versatile-harness/premises/.
| Premise | Meaning for a design |
|---|---|
| Public tomorrow | Every project repository is written as if public tomorrow |
| Neutral core | A core names no product, customer, vendor or sibling project |
| Private records | Records are private and live in one place |
| One artifact, every deployment | One artifact serves every deployment |
| Secrets are references | A secret is a reference everywhere except the store and the process that needs it |
| No customer data | No customer, employer or personal data anywhere |
| Local validation | No remote job gates a pull request |
| Pull requests only | Work reaches main only through a pull request |
| Evidence before done | Nothing is done without evidence |
| Records change with the code | Same unit of work, same pull request flow |
| Small team with AI | The team learns once |
| Every harness its own repository | The center links satellites, never copies them |
A project repository holds the product only. No ADRs, runbooks, research, deploy config, hosts or internal process appear in its files, commits, pull request bodies or branch names. That is what makes the public-tomorrow premise testable.
Gates and lints
Every change climbs the same gates, cheapest first, all on the developer's machine. A gate checks one thing, has one config home, and calls the repository's one check command, mise run check, instead of re-implementing it.
| Gate | Checks |
|---|---|
| Editor and format | Formatting and fast lint while typing |
| Pre-commit | Format and AST-only lint of staged files, fixed and re-staged |
| Pre-push and check | Linters on packages changed since the merge base; the full check on demand |
| Knowledge gate | The session checklist is recorded before gh pr create |
| Review | Standards and spec axes, via /review or /pre-pr |
| Merge gate | The merged commit is the one the validation stamped; only where a repository has one |
| Lint catalog | A confirmed recurring mistake becomes one shared lint every project enables |
| New-repository bootstrap | Dependabot, Semgrep, lefthook, LICENSE, SECURITY.md, README standard, go-lint for Go |
| Organisation conformance | bin/conformance lists what each repository misses |
The lint catalog lists each lint once with the problem it prevents, where it is implemented and which projects enabled it. Examples include a neutrality gate for engine cores, a dependency edge table, a comments check, a clock seam, an environment-in-composition-root check, and a Semgrep gate that ratchets on the merge base. Go checks come from one shared kit, go-lint.
Dependabot pull requests are never left idle: each is reviewed and merged, fixed and merged, migrated, or planned in an issue with its version ignored.
Proof levels
A claim needs evidence someone else can reproduce, shown as before and after, with the baseline captured first. There is one scale, and every ADR, study or decision matrix cell uses positions on it.
| Tier | Evidence | Good for |
|---|---|---|
| S | Behaviour observed in the running system: screenshots, real command output, real request and response | UI, end-to-end behaviour, deploys |
| A | A test that failed before the change and passes after it | Bugs, races, rules |
| B | Targeted tests, type check, lint and build all green | Refactors, internal changes |
| C | I read the code and it should work | Nothing: it is not evidence |
| Change | Minimum evidence |
|---|---|
| Feature | A, plus S when it has a user interface |
| Bug fix | A: the failing-first test |
| Refactor | B, behaviour tests unchanged and green |
| Configuration or deploy | S: observed in the running system |
| Visual change | S: screenshots at desktop and phone widths |
| Performance claim | S or A with numbers, same conditions before and after |
In studies, the labels read, specified and run map onto this scale. A read claim is valid only as a fact about its source, with version and date. It is never proof that our change works.
Company site
The site is a static export of Next.js 16 with the App Router, Tailwind CSS 4 and TypeScript. One small Bun server hands out the export and stores the forms in SQLite, from the schema in migrations/.
- Pages for the company, plus /connectors and /skills directories built from two catalogs of plain files.
- Forms: waitlist, contact, and connector and skill submissions. Lead validation lives in lib/leads.ts.
- POST /api/leads applies a same-origin check, an 8 KB limit, a honeypot and a per-address rate limit.
- The server answers / with a Markdown mirror when the request asks for text/markdown; the site also ships llms.txt discovery routes.
- The site ships no deployment configuration. Design rules are in DESIGN.md.
Decisions
| Decision | Chosen | Rejected | Why |
|---|---|---|---|
| Shape of the tooling | One center harness plus satellites as submodules | One monorepo; copied content | Each concern has its own history and truth; the center links, never copies |
| Delivery | Pull request, merge commit, local validation | Direct push; squash; remote CI gate | Main stays clean and each merge reverts as one unit; a remote job that never runs gates nothing |
| Learning | Guard after owner confirmation, registered once | Memory only; per-repository copies | Prose is broken again; copies disagree |
| Knowledge home | Records in a private satellite | ADRs and runbooks in product repos | A product repository must be publishable tomorrow |
| Research | A chartered study with an independent judge and auditor | A single pass by one agent | A single pass is a draft, never a result |
| Proof | One S, A, B, C scale | Per-document scales | Everything is comparable |
| Check command | One mise run check per repository | Makefiles and ad hoc scripts | Two definitions of green drift |
- The merge gate exists only in some product repositories; elsewhere the evidence in the pull request is the gate.
- The knowledge gate is symbolic and fails open if its hook errors.
- The harnesses and several engines are private, so this case cannot link them.
- Some lints are listed with an implementation not yet verified; the conformance tool reports what each repository still misses.
Files
Harness paths are private and relative to each harness repository.
.claude/CLAUDE.mdCenter harness router: scope, non-negotiable rules, routing table.claude/docs/work/01-WORKFLOW.mdThe working loop, decision matrix, stop condition.claude/docs/work/03-EVIDENCE.mdProof tiers and before and after.claude/docs/work/04-LEARNING-LOOP.mdRecurring problem to guard to shared record.claude/docs/work/06-GIT-AND-PRS.mdGit rules and the session knowledge checklist.claude/docs/work/10-GATES.mdThe gate ladder.claude/bin/syncUpdates checkouts and satellite read copies.claude/bin/installLinks skills, agents, commands; hooks and timer.claude/bin/conformanceBaseline check across the organisationversatile-harness/premises/00-INDEX.mdIndex of the standing premisesversatile-harness/rules/00-INDEX.mdEngineering rules indexversatile-harness/lints/00-INDEX.mdThe lint catalogresearch-harness/docs/methodology.mdStudy rules, stages and proof levelsversatile.sh/lib/leads.tsSite lead validationversatile.sh/DESIGN.mdSite design rules