godding

godding is a verb: take something bigger or murkier than it needs to be and leave it smaller and clearer for the next person. Swarm is the engine that does the godding here.

🌳 evergreen tended 2026-05-15 home ideology methodology

flowchart LR
  o[orient] --> p[predict]
  p --> a[act]
  a --> c[compare]
  c --> z[compress]
  z -.handoff.-> o

Read next

• Human's guide — the 2-min version
• Map — where everything sits
• godding essays — ideology underneath the engineering
• How to swarm — apply the methodology
• Learn & teach — the swarm wants to learn from you
• Vote — agree / skip / disagree on any page

Started as 134 lines of markdown on 2026-02-25. Hundreds of self-directed sessions later, ~1k lessons + 60+ carded human-readable pages.

live: https://dafdaf1234444.github.io/godding/ license: MIT

A self-directed, multi-session AI swarm built on git as shared memory. No central controller. Each session orients on the saved state, does a unit of work, compresses what it learned, and hands off to the next. State persists in plain markdown + git, so knowledge compounds instead of resetting.

Scale: 716+ sessions · 1,700+ lessons · 369 principles · 21 beliefs · 57 domains · 275+ tools · 31 commit guards. Commit format: [S<N>] what: why.

State snapshot: S716 · 2026-06-03 — figures track the live corpus; trajectory and falsifiable projections in scaling timelines.

---

The problem

Most AI sessions start from zero. You re-explain context, re-set constraints, re-decide priorities. The session ends. Next session: reset. Knowledge doesn't compound — it evaporates.

The fix

Two ideas, both structural:

Predict before acting. The gap between expectation and outcome is where learning lives. Wrong predictions produce more knowledge than confirmations (sessions that expected the wrong thing rated 39.8 percentage points higher quality, across 849 measured sessions).

If a rule matters, make it code. Voluntary protocols written in docs decay to ~3% adoption. The same rules enforced by pre-commit hooks hold at ~90%.

What is godding?

godding is a verb: take something bigger, murkier, or more gated than it needs to be, and leave it smaller and clearer for the next person. Full ideology: docs/godding/.

What is swarm?

swarm is the engine. A team of AI sessions reads what the last session wrote, decides what to work on, acts, records what it learned, and hands off. No central controller — the repo is the shared memory. Protocol: SWARM.md. Started as 134 lines of markdown on 2026-02-25.

---

System map

0 · The big picture — how everything connects

flowchart TD
  human["Human (Can)<br/>types a verb"] -->|steers| claude["Claude Code<br/>orchestrator · owns commits"]
  claude -->|spawns| workers["Worker models<br/>Gemini · ChatGPT · Kimi · Codex"]
  claude -->|runs| tools["Tools · 260+<br/>orient · dispatch · compress · validate"]
  workers -->|read / write| state[("Shared git state<br/>beliefs · tasks · memory · domains · docs")]
  tools -->|read / write| state
  state -->|build| site["MkDocs site<br/>published docs"]
  state -->|commit + push| github["GitHub<br/>CI + next session reads"]
  github -.next session.-> claude

The loop is a cycle: every "handoff" feeds the next session's "orient." Coordination has no hidden channel — if it isn't in a committed file, it didn't happen. That is what lets independent sessions and agents cooperate without a server.

1 · The core loop — what one session actually runs

flowchart LR
  o[Orient] --> p[Predict]
  p --> a[Act]
  a --> d[Diff]
  d --> z[Compress]
  z --> h[Hand off]
  h -.next session.-> o

Phase	Tool(s) run	What it does
Orient	orient.py	Synthesizes current state: due maintenance, priorities, headline signals. The "where am I?" pass.
	task_order.py	Turns orient output into a scored, ordered task list (COMMIT > DUE > CLOSE > DISPATCH > PERIODIC).
	question_gen.py	Generates 6 inquiry frames (frontiers, belief health, compression, zombies, gaps, signals).
	dispatch_optimizer.py	Routes the chosen work to the right domain / worker model; surfaces cross-domain seams.
Predict	claim.py provisional-claim --verb	Declares the verb + states an expectation before acting (so the diff is honest). Also prevents two concurrent sessions racing.
Act	the verb's own tool (e.g. forage.py, scope.py, vault.py)	Does the unit of work: write a page, run an experiment, fix a gap.
Diff	manual + orient signals	Compares actual vs expected; records confirm / large / null / positive / negative outcome.
Compress	compress.py / compact.py / sharpen.py / harvest.py	Writes a lesson (max 20 lines) only if one earned itself; merges duplicate lessons; extracts principles.
Handoff	sync_state.py	Synchronizes shared state files.
	validate_beliefs.py	Checks self-model integrity (never-remove atoms still present, etc.).
	cell_blueprint.py save	Snapshots state for child spawns.
	safe_commit.py + git push	Atomic, concurrent-safe commit ([S<N>] what: why), then push.

Source of truth: SWARM.md (canonical protocol) · beliefs/CORE.md (operating rules).

2 · The agents — who does the work

flowchart TD
  claude["Claude Code<br/>orchestrator · commits · beliefs · kill-switch"]
  claude --> gemini["Gemini · gy<br/>long-context synthesis"]
  claude --> chatgpt["ChatGPT · cgy<br/>adversarial checks"]
  claude --> kimi["Kimi K2 · ky<br/>long research chains"]
  claude --> codex["Codex · cy<br/>code generation"]
  claude --> summoned["Summoned agents<br/>persistent priors"]

Model	Alias	Strength / when it is dispatched
Claude Code	—	Orchestration, coordination, HIGH-stakes commits, belief updates, kill-switch. Never delegates this authority.
Gemini	gy	Long-context synthesis (1M ctx), cross-domain reads, visual tasks.
ChatGPT	cgy	Adversarial checks, falsification, external perspective, second opinions.
Kimi K2	ky	Long research chains, web-inaccessible tasks, thinking-heavy analysis.
Codex	cy	Code generation, multi-file edits, agentic coding tasks.
Summoned agents	—	Persistent named sub-agents in summoned/ (e.g. SLEEP-ARCHITECT, VOID-PROSPECTOR) — divergent "priors" a future session can re-invoke. Created via summon.py.

Dispatch pattern: orient.py --coord → pick tasks → spawn workers by alias → monitor via swarm-watch. Heterogeneous agents converge faster than identical ones.

3 · Shared git state — the substrate every session reads & writes

• beliefs/ — who the swarm is (changes rarely; the constitution)
• CORE.md — operating rules [NEVER-REMOVE atom] · PHILOSOPHY.md — 21 identity claims, each with an evidence label · DEPS.md — 21 formal beliefs (B-IDs) · INVARIANTS.md — atoms that cannot be deleted · CHALLENGES.md — contradictions to resolve
• tasks/ — what to do next (changes every session; the work queue)
• NEXT.md — handoff targets · SWARM-LANES.md — active work lanes (who · domain · intent · expect) · SIGNALS.md — inter-session messages · FRONTIER.md — open research questions · KILL-SWITCH.md — emergency stop
• memory/ — what the swarm knows (append-mostly; the long-term store)
• INDEX.md — rollup counts · lessons/ — 1,677 lessons (L-NNN), max 20 lines each, with evidence · PRINCIPLES.md — 369 principles (P-NNN), each harvested from ≥3 lessons · SESSION-LOG.md — full history · THEMES.md — theme buckets
• domains/ — 57 specialist areas, each its own lane (ai, brain, physics, economy, governance, security, music, philosophy, …)
• docs/ — human-facing docs (COMMANDS.md, PAPER.md, GLOSSARY.md, investigations/, diagrams/, …)
• site_src/ — staging for the MkDocs build (gitignored; rebuilt each run)

4 · Knowledge shape — the hierarchy and the wavefront

The 5-layer chain (scope.py walks it; act at the thinnest layer first). A belief with no downstream lesson is an orphan; a topic with lessons but no belief grounding is "half a move."

flowchart LR
  belief["Belief<br/>why"] --> principle["Principle<br/>rule"] --> lesson["Lesson<br/>datum"] --> frontier["Frontier<br/>open question"] --> page["Page<br/>explainer"]

The wavefront (wavefront.py; the swarm expands outward like a ripple — explored ⊂ frontier ⊂ dark). Rule: when dispatch scores are close, prefer frontier over dark.

flowchart LR
  explored["Explored<br/>well-visited · good signal"] -->|expand outward| frontier["Frontier<br/>expand these first"]
  frontier -->|no adjacency yet| dark["Dark<br/>unexplored"]
  frontier -->|dead branches| pruned["Pruned<br/>cut + archived, not lost"]

5 · The verbs — how Can steers the swarm

A verb = "what kind of move." Two strategies coexist on purpose:

• Isolated — one verb, one mode. Sharp and predictable.
• Combined — two or more verbs fused; reaches operating points neither isolated verb would (read left-to-right: each verb gates the next).
• Dreamy — proposed future verbs, "claimed by use" — the first session to actually run one graduates it into the live vocabulary.

Isolated (selected):

Verb	Tool	What the move does
swarm	the whole protocol	Run one full session: orient→…→handoff.
god / godding	judgment, no tool	Pure simplification. Output is LESS than input — fewer files/words/concepts, same or greater meaning.
harvest	harvest.py	Extract a PRINCIPLE candidate from N lessons that share one shape.
ritualize	ritualize.py	Turn a one-off pattern into a recurring task in periodics.json.
seance	seance.py --session N	Replay a past session's decisions; ask "what was NOT tested under that label?"
eye / eyeing	eye.py	Read the corpus as a fresh reader; emit a ranked [H\|M\|L] punch-list. Reports only, never fixes.
look	screenshot.sh + vision	Capture the live screen; report what looks wrong. The "see" step for rendered output.
forage	arxiv_search.py + HF MCP	Go OUTSIDE the corpus (arXiv/HF/Scholar), bring research home under references/, land it in a page.
architect	architect.py	Survey a domain's knowledge readiness (0–100); emit a pre-flight project brief.
wavefront	wavefront.py	Map/expand the EXPLORED→FRONTIER→DARK circle; rank expansion targets; prune dead branches.
prune	prune.py	Delete a lesson ONLY if Sharpe ≤ bar AND nothing cites it. (GC by quality + dependency.)
sharpen	sharpen.py	BOOST under-labeled lessons / KILL ones marked SUPERSEDED.
compress	compress.py	Merge adjacent same-domain lessons (Jaccard ≥ 0.25) into one denser lesson.
housekeep	housekeep.py	Run ALL maintenance in one pass: GC + taxonomy + language + memory-index + evaporation rate.
scope	scope.py	Walk the 5-layer chain for a concept; report the thinnest (highest-priority) layer.
vault	vault.py	Polarity ladder (OPT/PESS to depth 3) to reach a hypothesis neither pole hits.
timeline	belief_timeline.py	Trace a belief's git history + challenge count → an evidence-age credibility score.

Combined (selected):

Verb	What the fusion adds
swarmgod	protocol + simplification bias (the default combo).
swarmcombo	protocol while hunting an isomorphism between lanes.
swarmgodforage	protocol + forage + simplify into ONE page.
swarmgodritual	protocol + ritualize bias (notice → register → cite).
swarmgodprune	protocol + GC bias ("prune before you add").
swarmgodhousekeep	protocol + clean-first bias (housekeep at start).
swarmgodscope	protocol + scope-first bias (act at thinnest layer).
swarmgodvaultdream	vault a concept, then dream from the frame-break.
swarmgodsummonmultiagent	N agents each dream a moonshot prior at a frontier.

…and ~20 more combined stacks — full list + claim history in docs/COMMANDS.md.

Dreamy (unbound future — claimed by first use): dream · dreamvault · oracle · summon · commune · witness · ascend · fork · dreamforge. The first session to run one writes the lesson that graduates it.

6 · The toolbox — 260+ tools, by job

Category	Representative tools	What this category is for
Protocol spine	orient · task_order · question_gen · dispatch_optimizer	The tools the loop always runs to know what to do.
Verb tools	forage · scope · vault · harvest · combo · eye · seance · architect · prune	One tool per steering verb (see section 5).
Compression	compress · compact · sharpen · harvest	Keep the corpus dense: merge lessons, extract principles.
Coordination	claim · open_lane · close_lane · swarm_signal · swarm_peer · safe_commit	Concurrency-safe work assignment + messaging between sessions/agents.
Self-model / audit	validate_beliefs · consistency_check · contract_check · dogma_finder	Guard integrity: catch contradictions, circular reasoning, format violations.
Knowledge mgmt	knowledge_state · lesson_combiner · genesis_extract	Aggregate/merge the corpus; build minimal "daughter" bundles.
Analysis / science	market_predict · bayes_meta · scaling_model · science_quality	Domain modeling + measuring the swarm's own scientific quality.
Site / publish	build_site_src.sh · validate_card_links · audit_pages	Build the MkDocs site and block pushes that would orphan a page.
Git / safety	check.sh · install-hooks · pre-commit/commit-msg/pre-push hooks · guards/	Validation harness + the git hooks that enforce rules as CODE (30+ modular guards).
Continuous run	autoswarm.sh	Loop sessions unattended.
Shared utilities	swarm_io · swarm_parse · swarm_cache	One source of truth for repo-root, git calls, parsing, caching — enforced by guards/27.

7 · Safety & CI — rules become code, not just docs

flowchart TD
  commit([git commit]) --> msg{"commit-msg hook<br/>format ok?"}
  msg -->|no| reject["REJECT"]
  msg -->|yes| pre{"pre-commit · check.sh<br/>30+ guards"}
  pre -->|"mass deletion · mass-staging · .env"| fail["FAIL"]
  pre -->|pass| push([git push])
  push --> gate{"pre-push · site gate<br/>validate_card_links"}
  gate -->|orphan page| block["BLOCK"]
  gate -->|pass| ci["GitHub CI<br/>site · autoswarm-cron · swarm-check"]

Hard rules (structural): no force-push · no mass deletion (>20) · no mass-staging · .env never staged · commit format enforced · NEVER-REMOVE atoms = beliefs/CORE.md + tools/validate_beliefs.py.

8 · One session's life — and what it leaves behind

flowchart LR
  start(["Session N start"]) -->|"reads CORE + INDEX + tasks"| work["claim verb + expectation<br/>novel work, then maintenance"]
  work --> commit["commit + push<br/>what : why"]
  commit --> artifacts["artifacts in git<br/>lesson · principle · page · forage record"]
  artifacts --> next(["Session N+1 start"])
  next -.builds on all of it.-> compounding["compounding"]

Re-derive this map any time from: SWARM.md (loop) · docs/COMMANDS.md (verbs) · beliefs/CORE.md (rules) · memory/INDEX.md (counts) · tools/ (what each tool does). Full visual map: docs/MAP.md.

---

What it's proven

• Knowledge compounds — each compression layer filters noise; later sessions are measurably better than earlier ones.
• Concurrent coordination works — 10+ parallel AI sessions coordinate through git without destroying state.
• Self-directed exploration — an explore-vs-exploit algorithm picks which question to investigate next, producing +59% more lessons per investigation than random selection.
• Self-honesty is structural — every identity claim carries an evidence label; the system finds its own circular reasoning.

What it hasn't (and it knows)

• Overwhelmingly self-referential — most knowledge is about itself, not the external world.
• Zero instances of two independent swarms interacting.
• Every session still requires a human to press "go."
• Growing faster than it can compress — attention debt accumulating.

These aren't hidden — they're tracked as open frontiers with falsifiable criteria.

---

Try it

git clone https://github.com/dafdaf1234444/godding.git
cd godding
python3 tools/orient.py   # see current state and priorities

Then say swarm to any AI coding tool — Claude Code, Cursor, Codex, Gemini, Windsurf, Copilot. Each bridge file loads the protocol; the session reads state and self-directs from there.

Build your own

You don't need this repo to use the methodology:

1. Create a LESSONS.md in any repo — each AI session reads it first, writes what it learned after.
2. End every session with: Did / Expected / Actual / Next.
3. When you've written the same pattern three times, extract it as a one-line rule.
4. Wire important rules into pre-commit hooks so they can't be forgotten.

That's the loop. It compounds from session 1. For the full methodology — what breaks at session 30, how to scale to concurrent sessions, when lightweight isn't enough: docs/HOW-TO-SWARM.md.

Run locally

# bash / WSL / macOS / Linux
pip install -r requirements-docs.txt
bash tools/build_site_src.sh
mkdocs serve   # http://127.0.0.1:8000

# Windows PowerShell (5.1 or 7+) — note: no '&&', run line-by-line
pip install -r requirements-docs.txt
pwsh -NoProfile -File tools/build_site_src.ps1
mkdocs serve   # http://127.0.0.1:8000

Explore

State & protocol

Page	What it is
beliefs/CORE.md	Operating principles — what every session follows
beliefs/PHILOSOPHY.md	Identity claims, each with an evidence label
tasks/TODO.md	Top-level ordered task list, rated bad/medium/good
tasks/FRONTIER.md	Open research questions
docs/PAPER.md	Full methodology paper
docs/GENESIS.md	How 134 lines became this

Concepts & reference

Page	What it is
docs/godding/	The godding essays — noun, verb, four questions, engine
docs/investigations/	Long-running questions: stigmergy, brain, energy, bureaucracy, universe-as-compression, learnable skills
docs/MAP.md	Full visual map of the repo (entry points, layers, runtime, investigation graph)
docs/GLOSSARY.md	One-line definitions — also powers hover-tooltips on every site page
docs/PATTERNS.md	Pattern language for compressed-for-humans pages (Alexander × Maggie Appleton)
docs/COMPRESSIONS.md	Index of every compression scheme the repo uses
docs/HOW-TO-SWARM.md	Apply the methodology to your own repo
docs/ONBOARDING.md	Start your own swarm in 10 minutes — clone, extract DNA, run session 1

---

MIT