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.

org · siteversatile.shpersonal side project (organisation, mostly private repositories)Shape an organisation, not one repositorySite Next.js 16 static export, Bun forms serverWay of working a center harness plus satellite harnessesVisibility site and some engines public; harnesses privateversatile.sh

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).

PartWhat it is
EnginesIndependent repositories with neutral cores, each with a record home
Company siteStatic export of Next.js 16, Tailwind CSS 4 and TypeScript, with connector and skill directories and forms
Center harnessHow the team works: router, workflow docs, skills, agents, commands, hooks, tools
Satellite harnessesEngineering 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.

Harness bootstrapsh
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.

Company sitesh
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
VariableUsed byEffect
DATA_DIRsite serverWhere the forms database is stored
CATALOG_DIRsite tasksCatalog checkout read by mise run catalog and mise run skills
VERSATILE_CONFORMANCE=offbin/syncSkips the conformance summary line

Architecture

rulesstudycenterdeploymedia
The center harness is the hub; each satellite is its own repository, joined to it and never copied into it.

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.

text
          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)
HarnessHolds
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-harnessEngineering knowledge base (premises, rules, patterns, standards, lints, design, decisions, architecture, research index) and the record home of each project
hosting-harnessInfrastructure and each app's deploy configuration
research-harnessThe research engine: method, studies, state, a generated research home
media repositoriesThe canonical copy of every image, video, logo and design source
A project repositoryThe 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

recordfixguardproofok?
A recurring problem goes round fix, proof, owner confirmation, guard and record, and the guard keeps it from returning.

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.

  1. 1Recognise the className the problem as a class, such as raw colour values in components. Check the open issues and the lint catalog first.
  2. 2Fix the root causeThe smallest change that removes the cause, not a patch on the symptom.
  3. 3CertifyA failing-first test or a before and after, plus a sweep for other instances of the class.
  4. 4Ask for confirmationOne line to the owner. The certification belongs to the agent, the confirmation to the owner.
  5. 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.
  6. 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

checklistnotemain
The turnstile only turns once the session knowledge note is in the box; then the branch reaches main.

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.

  1. 1Branchgit fetch, then a worktree on a feature branch from origin/main. Commits are granular, one concern each, each building.
  2. 2Validate locallyThe repository's one check command. CI workflows are manual and gate nothing, so the evidence in the pull request is the proof.
  3. 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.
  4. 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.
  5. 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.

  1. 1IntakeThe owner answers the questions before any work starts, recorded with the date.
  2. 2RecoverWhat is already closed for the topic, with its date and commit.
  3. 3CharterDecision, unit of analysis, judging rule, proof levels, floors, scope, seats and budget. The owner releases it.
  4. 4Frame attackA red team objects to the question and premises before any answer exists.
  5. 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.
  6. 6RoundsProposals, objections, decisions, audit and spikes, released in tranches. The owner decides after each tranche.
  7. 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/.

PremiseMeaning for a design
Public tomorrowEvery project repository is written as if public tomorrow
Neutral coreA core names no product, customer, vendor or sibling project
Private recordsRecords are private and live in one place
One artifact, every deploymentOne artifact serves every deployment
Secrets are referencesA secret is a reference everywhere except the store and the process that needs it
No customer dataNo customer, employer or personal data anywhere
Local validationNo remote job gates a pull request
Pull requests onlyWork reaches main only through a pull request
Evidence before doneNothing is done without evidence
Records change with the codeSame unit of work, same pull request flow
Small team with AIThe team learns once
Every harness its own repositoryThe 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.

GateChecks
Editor and formatFormatting and fast lint while typing
Pre-commitFormat and AST-only lint of staged files, fixed and re-staged
Pre-push and checkLinters on packages changed since the merge base; the full check on demand
Knowledge gateThe session checklist is recorded before gh pr create
ReviewStandards and spec axes, via /review or /pre-pr
Merge gateThe merged commit is the one the validation stamped; only where a repository has one
Lint catalogA confirmed recurring mistake becomes one shared lint every project enables
New-repository bootstrapDependabot, Semgrep, lefthook, LICENSE, SECURITY.md, README standard, go-lint for Go
Organisation conformancebin/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.

TierEvidenceGood for
SBehaviour observed in the running system: screenshots, real command output, real request and responseUI, end-to-end behaviour, deploys
AA test that failed before the change and passes after itBugs, races, rules
BTargeted tests, type check, lint and build all greenRefactors, internal changes
CI read the code and it should workNothing: it is not evidence
ChangeMinimum evidence
FeatureA, plus S when it has a user interface
Bug fixA: the failing-first test
RefactorB, behaviour tests unchanged and green
Configuration or deployS: observed in the running system
Visual changeS: screenshots at desktop and phone widths
Performance claimS 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

DecisionChosenRejectedWhy
Shape of the toolingOne center harness plus satellites as submodulesOne monorepo; copied contentEach concern has its own history and truth; the center links, never copies
DeliveryPull request, merge commit, local validationDirect push; squash; remote CI gateMain stays clean and each merge reverts as one unit; a remote job that never runs gates nothing
LearningGuard after owner confirmation, registered onceMemory only; per-repository copiesProse is broken again; copies disagree
Knowledge homeRecords in a private satelliteADRs and runbooks in product reposA product repository must be publishable tomorrow
ResearchA chartered study with an independent judge and auditorA single pass by one agentA single pass is a draft, never a result
ProofOne S, A, B, C scalePer-document scalesEverything is comparable
Check commandOne mise run check per repositoryMakefiles and ad hoc scriptsTwo 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 organisation
  • versatile-harness/premises/00-INDEX.mdIndex of the standing premises
  • versatile-harness/rules/00-INDEX.mdEngineering rules index
  • versatile-harness/lints/00-INDEX.mdThe lint catalog
  • research-harness/docs/methodology.mdStudy rules, stages and proof levels
  • versatile.sh/lib/leads.tsSite lead validation
  • versatile.sh/DESIGN.mdSite design rules