DEV Community: Dhrupo Nil

Dev OS v2: gates, a learning loop, and agents that check agents

Dhrupo Nil — Sun, 01 Nov 2026 14:21:40 +0000

In v1 I treated ~/.claude as an operating system around the model: a kernel (one rulebook), a scheduler (lanes), interrupts (hooks), a package manager (pinned skills). I asked you to run the starter kit for a week and tell me what broke.

I ran it too, every day. 213 commits later, this is the v2 release, and its main change fits on one line:

A rule the agent reads is a request. A rule something runs is a gate.

Both commenters on v1 had said the same thing. Here is what that changed, in order of how much it helped. The gates, hooks, agents and tests below ship in the kit (135 checks, bash tests/run.sh); the rest is how I run my own setup. The kit works with any agent that reads AGENTS.md (Codex, Cursor, Copilot), not only Claude Code.

1. One rulebook, every agent

The kernel is the same: one CLAUDE.md whose first section says it overrides every skill, plugin and repo file. What's new is that AGENTS.md is a symlink to it.

ln -s ~/.claude/CLAUDE.md ~/.codex/AGENTS.md   # Codex reads ~/.codex/AGENTS.md, then one per folder, root → cwd

I checked how each tool loads it on 2026-11-01:

Codex concatenates AGENTS.md files up to 32 KiB by default. A long global rulebook steals room from repo rules. Mine is capped at 136 lines by a test.
Claude Code reads AGENTS.md only in a repo with no CLAUDE.md, so CLAUDE.md stays the source.
@lessons.md imports are Claude-only. Through the link, Codex gets the rulebook but not its imports.

2. Gates beat reminders

A test gate in plain git. v1's pre-commit hook only guarded ~/.claude itself. v2 installs one per project:

echo 'npm test' > .dev-os-test && ~/.claude/bin/gate-install

The hook it writes (condensed from bin/gate-install):

TOP=$(git rev-parse --show-toplevel)
unset GIT_INDEX_FILE GIT_DIR GIT_WORK_TREE GIT_PREFIX
CMD=$(cat "$TOP/.dev-os-test" 2>/dev/null)
if ! printf '%s' "$CMD" | grep -q '[^[:space:]]'; then
  echo "dev-os test gate: .dev-os-test is missing or empty; commit refused" >&2; exit 1
fi
(cd "$TOP" && bash -o pipefail -c "$CMD") || { echo "dev-os test gate: commit refused" >&2; exit 1; }

Every line there is a bug I hit:

pipefail: npm test | tail -5 exits with tail's 0, so a red suite commits.
Empty means refuse: a missing or empty test command fails loudly instead of passing quietly.
unset GIT_INDEX_FILE: git runs pre-commit with a temporary index during commit -a. A test suite that runs git add in a temp repo writes into your commit and breaks it with "Error building trees".
No global hooks: the installer refuses when a global core.hooksPath would turn one repo's gate into every repo's gate.

Permissions the agent can't talk past. permissions.ask rules still prompt under --dangerously-skip-permissions, and compound commands are split before matching:

"permissions": { "ask": ["Bash(git push:*)", "Bash(gh pr create:*)"] }

One catch: rules match the command text, so git -C . push slips past Bash(git push:*). I add Bash(git -C * push *) in my own settings. Keep branch protection on the remote as the backstop.

A Stop hook for the cheap way out. v1's Stop hook sent the agent back when source changed with no test. v2 adds one more case: a weakened test. That means fewer assertions, a new .skip/.only, or a deleted test file.

ASSERT = re.compile(r"\bassert\w*\s*\(|\bexpect\s*\(|->assert\w*\(|\$this->assert|^[-+]\s*assert(_\w+)?\s")
SKIP   = re.compile(r"markTestSkipped|markTestIncomplete|->skip\(|\.(skip|only|fixme)\s*\(|\bx(it|describe|test)\s*\(")
if removed_asserts > added_asserts or any(SKIP.search(l) for l in added):
    weakened.append(path)        # → {"decision": "block", "reason": "TEST WEAKENED: …"}

Codex hooks use the same Stop → {"decision":"block"} shape.

3. It learns by itself

In v1, "add a line to lessons.md" depended on me remembering to do it. Now the setup logs its own mistakes:

prompt starts "no, …" / "I said …"   ─┐
stop-check or test gate blocks       ─┼─▶ state/learn-<session>.jsonl
                                       │
Stop: learn.sh → any entry newer than the last `reflect`? → block once: "run reflect"

reflect routes each mistake to the lowest layer that would have caught it: first a test or hook, then one line in the skill that owns the job, and only last a line in lessons.md. lessons.md has a 60-line budget. When it fills up, meditate audits the rules for stale, duplicate and contradicting lines, and deletes nothing without my yes. 59 of the 213 commits are Lesson: commits, and many of them removed a lesson by turning it into a check.

The loop gets tested like everything else. A cold review caught the correction detector flagging "No tests exist for the parser yet" as a correction. Now no counts only when followed by punctuation, and only the first line of a prompt is read.

4. Agents check agents

One agent reviewing its own diff is a student grading their own exam. The kit ships two read-only agent shapes:

scout: one angle per scout (callers, tests, history, config). Each returns file:line facts and what it couldn't check.
review-lens: Skeptic always, Architect at 50+ changed lines, Minimalist at 200+. Then one verifier per finding that starts from "false positive".

Two skills run them. pre-merge-review is relay step 7 on your own branch: lenses sized by the diff, a verifier per finding, one saved report. post-pr-review is for someone else's PR: each finding must reproduce on both the base and the PR branch before it goes in a draft, and nothing is posted without a yes. /code-review stays the per-slice check inside build-check, and it never posts on other people's PRs.

Every subagent brief has the same fields: goal, scope, what's known, what's been ruled out, the exact ask, the output format, what's out of scope. Parallel builders get one git worktree each, and only for plan slices that share no files.

How well does this work? On the v2 kit itself, which already passed all its own tests:

Pass	Found
`/code-review`	9 (6 fixed, 3 left with reasons)
3 lenses, each reproducing its findings in a temp dir	14 more
a cold reviewer that saw none of the above	4 more

Every behaviour fix got a red test first.

5. Prove it by running it

9. A bug or security claim counts only when reproduced by running it. No repro, no fix.

For bugs, the first job is a red-capable feedback loop, in the order from Matt Pocock's diagnosing-bugs: failing test → curl script → CLI snapshot diff → headless browser → replayed payload → harness → fuzz → git bisect run. Hypotheses come after.

I also break every gate on purpose before I trust it. That caught a test that passed before the code existed. My helper matched substrings, so rc=127 ("command not found") satisfied a check for rc=1.

6. Project memory: graph first

Rule 8: before grep, ask a code graph "who calls this, and what breaks if I change it?"

Tool	Used for
graphify `query` / `explain` / `path` / `merge-graphs`	Finding code, explaining a node, call paths, one graph across repos
code-review-graph `get_impact_radius_tool`	Who else a fix reaches (the no-regressions rule)
`get_review_context_tool`, `get_affected_flows_tool`	Review context; which E2E flows a diff touches

The scouts, review lenses and review-reply step all start there. The graph holds structure. What the project taught lives in lessons.md and in plan folders kept outside the repo.

7. Stay lean

A context budget test: rulebook plus skill descriptions, measured in bytes, against a baseline. It went from 59,287 to 46,927 while the setup grew.
Routing is tested: one rulebook sentence ("call the owner skill before any other tool") took my routing eval from 0-1 to 7-8 of 11 prompts.
Effort is a budget too: "effortLevel": "medium" by default, in every modelSettings entry as well, since a per-model value wins. High effort lives in skill frontmatter only where a wrong answer is expensive: grilling, writing and checking the plan, whole-plugin bug hunts. Hooks can read the effort level but not set it, so serious cases are handled by a rule: payment or refund, data loss, auth or a security finding mean the verifiers are spawned with effort: "high".
Smaller output: RTK trims git/gh/test output before the agent reads it. Compressed output can hide the one line you need, so "never report a result you couldn't see" is a rule.

The userland

Most of my 103 skills are other people's work: 39 are pinned to an upstream commit in skills.lock, with local edits in overlays that a sync script re-applies.

ponytail by Dietrich Gebert: the smallest-change ladder (YAGNI → reuse → stdlib → platform → installed dep → one line). It's rule 3 in the kit.
Matt Pocock's skills: tdd, grill-me, handoff, domain-modeling.
obra/superpowers: brainstorming and systematic-debugging.
Trail of Bits: fp-check, variant-analysis and differential-review, for security claims.
e2e-reviewer: catches E2E tests that pass while the feature is broken.

Skills use the Agent Skills format. Codex reads them from .agents/skills, and Claude Code from .claude/skills, so one folder with two symlinks serves both.

Upgrade or start

New: follow the kit's README "Start here". The core (rulebook, test gate, plan template) takes about 10 minutes, and the Claude Code layer is optional.
From v1: the README has an "Upgrading from v1" block. Nothing was renamed. Two hooks and two skills get replaced after a "Before v2" commit, so it's one git revert to undo.

Same ask as v1: run it for a week and tell me what broke. And what's the one rule your agent keeps breaking? I'll tell you which gate I'd put behind it.

Host up to 10 WordPress sites for free with Oracle Cloud and xCloud

Dhrupo Nil — Wed, 14 Oct 2026 04:50:18 +0000

I wanted a place to run a handful of WordPress sites (test sites, demos, a personal page) without paying for hosting every month. The combination that worked: a free Oracle Cloud server, managed through xCloud's free plan, so I never had to install the web server, PHP or SSL by hand.

This is the full walkthrough, including the parts that tripped me up: Oracle's "Out of capacity" error, a card hold that looked like a charge, and a firewall rule that silently did nothing.

Run WordPress sites on a free Oracle Cloud server, managed through xCloud's free plan.

Oracle Cloud Always Free gives you the server (the land).
xCloud free Self-Managed plan installs and manages the web server, PHP, database and SSL (the builder).
Only cost: a domain name (about $10–13/year), and only if you want your own address.

How it fits together

The cover image above shows the whole setup: a visitor's browser finds your server through DNS, passes Oracle's two firewalls, and reaches the Ubuntu server that xCloud manages.

The build, in short:

Create a free Oracle account and a network that allows web traffic (Parts 1–2).
Create one Ubuntu 24.04 server on that network (Part 3).
Log in, open the web ports inside the server, and add swap if it's the 1 GB one (Part 4).
Give xCloud root access with its key; xCloud installs the web server, PHP and database (Part 5).
Point a domain at the server (Part 6), then add sites from the xCloud dashboard (Part 7).

Running up to 10 sites

xCloud's free plan allows 1 server with up to 10 sites. All of them live on the same Oracle server and share its CPU and memory.

One domain is enough. Each site gets a free subdomain: example.dev, blog.example.dev, shop.example.dev, lab.example.dev, …
One DNS record covers all subdomains. A wildcard A record (* → server IP) points every subdomain at the server, so a new site needs no DNS change.
Each site is added the same way in xCloud (Part 7) and gets its own SSL certificate, database and WordPress install.
Testing without a domain: use xCloud's Demo Site option for a free temporary address, and switch to a real domain later.

How many sites the server can really carry:

Server	Realistic number of sites
ARM 2 OCPU / 12 GB	All 10, if they are ordinary WordPress sites with caching on
AMD Micro 1 GB (+2 GB swap)	3–5 quiet sites (tests, demos, personal pages). Not WooCommerce or real traffic

If you start on the 1 GB server and outgrow it, create the ARM server later and move the sites over with xCloud's site migration. The free xCloud plan covers only one server at a time.

Last checked: October 2026. Oracle and xCloud change their screens and limits, so a label may read slightly differently from this guide.

What you get

Item	Free allowance
xCloud Free plan	1 server, up to 10 sites
Oracle ARM server (`VM.Standard.A1.Flex`)	2 OCPU / 12 GB RAM total (halved from 4/24 in June 2026)
Oracle AMD server (`VM.Standard.E2.1.Micro`)	Up to 2 servers, 1 GB RAM each
Oracle disk	200 GB total, across all boot volumes
Oracle outbound traffic	10 TB per month

Which server?

ARM, 2 OCPU / 12 GB: comfortable for several WordPress sites. Often unavailable on free accounts (see Out of capacity).
AMD Micro, 1 GB: almost always available. Good for 1 small site or a handful of quiet test sites.

Before you start

A credit or debit card (Oracle uses it for identity checks; Always Free resources are not billed).
An xCloud account: https://xcloud.host
A terminal with ssh (macOS/Linux built in; Windows: PowerShell or WSL).
Optional: an SSH key. Check with ls ~/.ssh/*.pub. If none exists, create one:

ssh-keygen -t ed25519

Part 1 — Create the Oracle Cloud account

Sign up at https://www.oracle.com/cloud/free/.
Choose your Home Region carefully. It can never be changed, and free servers only run there. Pick a region close to your visitors.
Finish card verification and wait for the account to be ready.

Part 2 — Create the network (VCN)

Create the network before the server. The inline network option in the server form has a bug that can lock the public IP off.

☰ menu → Networking → Virtual Cloud Networks.
On the left, under Compartment, choose your root compartment (your account name).
Click Start VCN Wizard (it may be under Actions).
Choose Create VCN with Internet Connectivity → Start VCN Wizard.
Fill in:

Field	Value
VCN name	`xcloud-vcn`
VCN IPv4 CIDR block	`10.0.0.0/16`
Public subnet CIDR	`10.0.0.0/24`
Private subnet CIDR	`10.0.1.0/24`

Next → Create. Wait until every line has a green tick, then View VCN.

Open web ports (80 and 443)

Port 22 (SSH) is already open. Add the web ports:

In the VCN, open Security Lists → Default Security List for xcloud-vcn.
Add Ingress Rules:

Field	Value
Source Type	CIDR
Source CIDR	`0.0.0.0/0`
IP Protocol	TCP
Source Port Range	(empty)
Destination Port Range	`80,443`
Description	`web`

Save. You should now see three TCP rules from 0.0.0.0/0: 22, 80, 443.

Part 3 — Create the server (instance)

☰ → Compute → Instances → Create instance.
Basic information
- Name: e.g. xcloud-server
- Placement: default availability domain
- Shape → Change shape (do this before the image):
  - ARM: Ampere → VM.Standard.A1.Flex, 2 OCPU, 12 GB
  - or AMD: Specialty and previous generation → VM.Standard.E2.1.Micro
- Image → Change image → Ubuntu → Canonical Ubuntu 24.04 (not "Minimal")
Security: leave as is.
Networking
- Existing VCN: xcloud-vcn
- Existing subnet: the public subnet
- Automatically assign public IPv4 address: on
- SSH keys: Paste public key (contents of your ~/.ssh/id_ed25519.pub), or Generate a key pair for me and click Download private key right away. You cannot download it later.
Storage
- Tick Specify a custom boot volume size
- Enter 100 GB (keep the total of all your boot volumes at 200 GB or less to stay free)
Create. Wait for Running, then copy the Public IP address.

Out of capacity

Out of capacity for shape VM.Standard.A1.Flex in availability domain AD-1 means free ARM machines in your region are all taken. Your settings are fine. Try, in order:

Another availability domain (if your region has more than one).
A smaller size: 1 OCPU / 6 GB.
Retry at a different time of day.
Use the AMD Micro shape instead (1 GB, nearly always available).
Upgrade to Pay As You Go (☰ → Billing & Cost Management → Upgrade and Manage Payment). Paid accounts get capacity much more easily and are not reclaimed when idle. You still pay $0 if you stay within the free allowance.

About the Pay As You Go card hold

Upgrading places a temporary hold of about US$100 on your card (shown in your local currency, e.g. ~S$138). It is a verification hold, not a charge:

Check Billing & Cost Management → Invoices: there should be none.
Check Cost Analysis: usage should be 0.
Your bank releases the hold on its own, usually within days, sometimes up to ~30 days.
If it shows as posted (not pending), or an invoice appears, contact Oracle support and your bank.

Set a $1 budget alert (do this on Pay As You Go)

☰ → Billing & Cost Management → Budgets → Create Budget → amount 1, alert at 1% of actual spend, your email. You'll hear about any real charge immediately.

Part 4 — Prepare the server

ssh -i ~/.ssh/id_ed25519 ubuntu@YOUR_SERVER_IP

If you used an Oracle-generated key:

chmod 600 ~/Downloads/ssh-key-XXXX.key
ssh -i ~/Downloads/ssh-key-XXXX.key ubuntu@YOUR_SERVER_IP

4.1 Add swap (1 GB AMD server only)

Gives the small server spare memory so it doesn't crash under load.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

free -h should show Swap: 2.0Gi.

4.2 Open ports 80 and 443 inside the server

Oracle's Ubuntu image has its own firewall that blocks web traffic, separate from the Security List in Part 2. Both must allow it.

First find the line number of the REJECT rule:

sudo iptables -L INPUT -n --line-numbers

Example output:

4    ACCEPT  ...  state NEW tcp dpt:22
5    REJECT  ...  reject-with icmp-host-prohibited

Insert the web rules at the REJECT line's number (here 5), so they sit above it. Rules placed below REJECT do nothing.

sudo iptables -I INPUT 5 -m state --state NEW -p tcp --dport 443 -j ACCEPT
sudo iptables -I INPUT 5 -m state --state NEW -p tcp --dport 80 -j ACCEPT
sudo netfilter-persistent save
sudo iptables -L INPUT -n --line-numbers

The list should now show 22, 80, 443 before REJECT.

Part 5 — Connect the server to xCloud

In xCloud: Servers → Add Server → Connect Your Existing Server (Any Provider).
Fill in the form:

Field	Value
Server Name	Any label, e.g. `oracle-free`
App Type	WordPress (optional)
Web Server	OpenLiteSpeed (built-in cache, good for small servers). NGINX also works on AMD. On ARM, use OpenLiteSpeed
IP Address	Your server's public IP
SSH Port	`22`
SSH Username	`root`
Database Server	Do not leave on None. Pick MariaDB or MySQL (on ARM, MySQL 8.4 is not supported)
Plan	Free
SSH Authentication	Public Key

xCloud shows a command that adds its key to the server. Copy it and run it on the server (in your ubuntu SSH session). It should print SSH key added successfully.

Oracle blocks direct root login with your key, but root login with an added key works. This command is what lets xCloud in as root.

Tick I have created a new server on my provider → Create.
Wait for provisioning to finish. On a 1 GB server this can take a while.

Part 6 — Get a domain (optional)

You can skip this and use xCloud's free Demo Site address for testing.

For real sites, one domain is enough for many sites, because subdomains are free:
example.dev, blog.example.dev, shop.example.dev, …

When buying:

Judge by the renewal price, not the first-year price.
Make sure WHOIS privacy is free.
Untick add-ons (email, "protection", site builders).
.dev and .app domains require HTTPS in every browser. That is fine with xCloud's free SSL, but a site won't load at all until its certificate is issued.

Point the domain to the server

At your registrar's (or Cloudflare's) DNS settings, add A records pointing to your server IP:

Name	Type	Value
`@`	A	`YOUR_SERVER_IP` (the main domain)
`*`	A	`YOUR_SERVER_IP` (every subdomain at once)

On Cloudflare, set these to DNS only (grey cloud) until xCloud has issued the SSL certificate. DNS changes can take a few minutes to an hour.

Part 7 — Add a site

Open the server in xCloud → Add Site.

Field	What to do
Select Options	Default
Site Title	Your site's name
Go Live / Demo Site	Go Live with your domain, or Demo Site for a free test address
Domain Name	e.g. `blog.example.dev` (Go Live only)
DNS Setup	Click Verify My DNS. Keep Use free SSL certificate issued & managed by xCloud
Multisite	Off
xSpeed Cache	On
Mail Delivery	Off for now
Site Backup	Off for now
Blueprints	Gutenberg Websites, or turn off for clean WordPress. The Elementor blueprint adds weight a small server doesn't need
More Advanced Settings	Set the WordPress admin username, password and email; keep the default PHP version

Click Next and wait. Repeat for each additional site with a different title and domain.

Small server tips: keep plugins few, keep caching on, don't run imports or backups on several sites at once. A 1 GB server suits quiet sites only; WooCommerce or real traffic needs the ARM server.

Troubleshooting

Problem	Likely cause and fix
`ssh` asks for a password or says Permission denied	Wrong key file or user. Use `ubuntu@`, and the private key matching the public key you gave Oracle
`Please login as the user "ubuntu" rather than "root"`	You tried `root@` directly. Log in as `ubuntu`
xCloud can't connect	The xCloud key command wasn't run, or was run on a different server. Rerun it in your SSH session
Site doesn't load on port 80/443	One of the two firewalls still blocks it: check the Security List (Part 2) and the iptables order (Part 4.2)
Verify My DNS fails	DNS not spread yet (wait and retry), wrong IP in the A record, or Cloudflare proxy (orange cloud) is on
Oracle reclaims an idle free server	Free accounts can lose a VM whose CPU, network and memory all stay under 20% for 7 days (a warning email comes first). Pay As You Go accounts are not reclaimed

Wrapping up

You now have a server you don't pay for, a dashboard that handles the web server, PHP, database and SSL, and room for up to 10 WordPress sites under one domain.

If you hit a step that looks different on your screen, or found a better way around Oracle's capacity problem, tell me in the comments.

How I set up Claude Code: one rulebook, a 12-step relay to use it daily

Dhrupo Nil — Wed, 07 Oct 2026 17:29:45 +0000

Claude Code used to feel like a brilliant teammate with no onboarding. Some days: tests first, small diff, asked before pushing. Other days: no tests, three "cleaned up" files, a PR opened on its own.

The model wasn't the problem. My setup was: a 20 KB CLAUDE.md that contradicted itself, dozens of copied skills fighting each other, and rules nothing enforced.

So I rebuilt ~/.claude like any other system. Here's how, step by step.

Short on time? Start here. Three things fix most of the chaos:

One rulebook that says it overrides everything else (Step 2).

Lanes, so Claude states the size of the job before acting (Step 3).

permissions.ask for git push and gh pr create, so nothing ships without your yes (Step 8).

📦 Everything below is in a starter kit you can copy in about 10 minutes: the rulebook template, the 3 hooks, the 4 relay skills and their tests. github.com/dhrupo/claude-code-dev-os

What we're building

~/.claude/
├── CLAUDE.md          # the one rulebook
├── lessons.md         # mistakes not to repeat (imported by CLAUDE.md)
├── settings.json      # hooks, permissions, plugins
├── skills/            # one folder per skill
├── skills.lock        # where each skill came from, pinned
├── overlays/          # my edits, re-applied after updates
├── hooks/             # enforcement scripts
└── tests/             # tests for the setup itself

The starter kit has everything here except skills.lock and overlays/. Those only matter once you start pinning skills from GitHub (Step 6).

Step 1: Make `~/.claude` a git repo

Every change becomes one commit, so any bad rule is one git revert away. ~/.claude also holds chat history and credentials, so use an allowlist .gitignore:

*
!.gitignore
!settings.json
!CLAUDE.md
!lessons.md
!skills.lock
!skills/**
!hooks/**
!overlays/**
!tests/**

cd ~/.claude && git init && git add -A && git commit -m "Baseline"

Keep it local. Never add a remote.

Step 2: Write ONE rulebook

Most of my "Claude ignores me" problems were really "Claude got conflicting instructions." The fix is one line at the top of ~/.claude/CLAUDE.md:

## 0. Precedence
This file overrides skills, plugins, slash commands and repo CLAUDE.md files.
Those may ADD project facts (test commands, code style). On conflict, this file wins.

Then the skeleton:

## 1. Defaults   — be concise; never push without asking; state what "done" means before building
## 2. Lanes      — 🟢 / 🟡 / 🔴
## 3. Relay      — the steps
## 4. Skill map  — one owner per job
## 5. Rules      — test first, smallest change, no regressions, no noise comments
@lessons.md

Keep it small. It loads every session. If you can't say what a line changes, delete it.

Step 3: Lanes

A typo shouldn't get the same process as a payment-flow change. Claude must put the lane on the first line of every reply:

- 🟢 question — answer only, no code.
- 🟡 small — one obvious file. 3-line plan in chat. Tests still required.
- 🔴 full — anything bigger. Full relay + written plan.
Ratchet up, never down: a 🟡 that grows must say so and switch to 🔴.

🔴 full · bug (refund sends the receipt twice) tells me in one glance whether Claude understood the size of the job.

Step 4: The relay

🔴 work goes through 12 steps. Each step has one owner skill, and some steps have a STOP where I decide:

#	Step	Owner
1	Grill: one question at a time, with a recommended answer → STOP	`grill-me`
2	Plan: one page + list of allowed files → STOP	`openspec-plan`
3	Check the plan: tests named? "won't change" listed?	`plan-check`
4	Build: failing test first, smallest fix	`tdd` + `ponytail`
5	Check the build: tests, E2E, lint, diff matches plan	`build-check`
6	Tidy: delete what isn't needed	`ponytail-review`
7	Deep review: bugs, security, performance, regressions	`pre-merge-review`
8	Fix findings → back to 4
9	Step back: read the whole diff cold	`step-back`
10	PR: asks before push, asks again before the PR	`commit-push-pr`
11	Wait for review → STOP
12	Handle review: verify every finding, don't trust it blindly	`receiving-code-review`

🟡 runs a light version (quick grill, then 3 → 4 → 5 → 9). 🟢 skips it all.

Four of the skills here are my own (openspec-plan, plan-check, build-check, step-back), and each is under 60 lines. All four are in the starter kit, where the plan skill is called plan. For example, here's plan-check in full:

---
name: plan-check
description: Use right after the plan is written, before any code. Gates the PLAN.
---
1. **Tests named** — the exact failing test(s) to write first.
2. **Must-not-change listed** — what behaviour is at risk and how we protect it.
3. **Smallest change** — no new dependency, no new public API, fewest files.
4. **No open questions.**
One line per check, pass/fail. Any fail → fix the plan, not the code.

You don't need my 12 steps. You need named steps, one owner each, and clear STOP points.

Step 5: Skills, one owner per job

Skills from different sources compete. I had three TDD skills and two brainstormers that each claimed to run first. So the rulebook has a routing table: one owner per job, and everyone else steps aside or gets called by the owner. I also turned off 6 design skills that overlapped (skillOverrides in settings.json).

Here's my whole shelf in one pass:

Plan: superpowers:brainstorming, grill-me, grill-with-docs, openspec-plan, plan-check, design-an-interface, improve-codebase-architecture, zoom-out, explain-this, source-driven-development, new-feature
Build: tdd (rigorous-coding-workflow defers to it), bug-fix (builds a fast pass/fail loop first), ponytail, ponytail-review, ponytail-audit, ponytail-debt, context-packaging, handoff
Review: build-check, pre-merge-review, security-auditor (read-only), security-repro, infection-gate, phpstan-gate, step-back. pr-review-toolkit and Codex give a second opinion only when asked
Ship: commit-push-pr, release-readiness, knowledge-capture, retro, daily-work, plus Addy Osmani's shipping-and-launch, ci-cd-and-automation, observability-and-instrumentation, performance-optimization, deprecation-and-migration
Understand code: graphify and the code-review-graph MCP. The rule is graph first, grep second
My stack: the WordPress agent skills (wp-plugin-development, wp-rest-api, wp-block-development, wp-playground, wp-phpstan, wp-plugin-directory-guidelines) and plugin-audit

The special ones get a few lines each:

🎨 UI/UX is a pipeline with gates. ui-ux-pro-max picks the direction (palette, type, patterns) → impeccable builds it well → break-ui feeds it worst-case data (80-character names, empty lists, emoji) → impeccable-audit + axe-a11y-audit must pass. Extras: review-animations, animation-vocabulary, mobile-native, and the Chrome DevTools MCP for live debugging.

✏️ Pencil: draw it before you code it. When I say "mock it up", pen-design uses the pen.dev CLI to make a .pen file and a PNG in ~/Documents/designs/<project>/<id>/. It never overwrites (design-v2, design-v3…) and logs each run. For a redesign, a screenshot of the current screen goes in as reference.png. Then the PNG becomes the target: the UI skills build to it, and build-check compares a screenshot of the result side by side. It never runs unless I ask.

🧪 E2E: "unit tests pass" ≠ "it works". Anything a user can click gets a Playwright test against the real site, red before the fix and green after. playwright-core writes it, playwright-auth-state handles logins, and playwright-cli / playwright-cli-runner are for exploring only. e2e-reviewer scans for tests that can pass while the feature is broken.

🔎 Research and scraping, on demand. agent-reach does web and social research. Its queries leave the machine, so nothing sensitive goes in, and social logins only happen when I ask. scrapling scrapes JS-heavy or bot-protected pages locally, and only when plain WebFetch fails.

🔐 Consent-gated. Some tools must never run by surprise. strix-local (a live pentest) only targets local or owned hosts and asks Attack <target> now? (y/n) every time. omniroute-session (routing through another model) runs only in a separate session, never machine-wide.

🏠 Product layer. For the two products I work on daily (Fluent Forms and Fluent Player), I add trace skills that walk one real flow end to end before a fix, such as trace-submission-flow, trace-payment-flow, trace-ui-api and trace-player-runtime-flow. There are 18 in total. I also add product wrappers around the generic owners: grill-change, ui-ux-skills, fluentform-pre-pr-review, fluentplayer-release-readiness and so on. Copy the pattern: a generic shelf, plus one trace skill for whichever flow of yours breaks most.

Step 6: Pin skills, keep your edits

You copy a skill from GitHub and tweak it. Then updating it wipes your tweak. My fix:

skills.lock records each skill's repo and pinned commit, plus a status: installed-upstream, installed-ondemand, consent-gated, or skip (with the reason, so future me doesn't reinstall it).
overlays/<name>.md holds my edits. For example, my ponytail overlay says "shrink the code, never the tests."
bin/sync-skills.sh fetches each skill at its pinned commit, copies it in, and appends the overlay. Running it twice changes nothing the second time.

{ "name": "tdd", "status": "installed-upstream",
  "repo": "https://github.com/mattpocock/skills", "ref": "6fd9479",
  "path": "skills/engineering/tdd", "overlay": "tdd" }

Step 7: Plans live outside the repo

Skills don't share memory, and long chats get compacted. So skills hand off through files. Every 🔴 change gets a folder in ~/Documents/openspec/<project>/changes/<id>/ (the starter kit uses the simpler ~/Documents/plans/<project>/<id>/):

proposal.md   # what's wrong · what changes · what WON'T change · how we'll know
tasks.md      # checkboxes, failing test named first
scope.txt     # the files this change may touch
evidence/     # test runs, screenshots, review reports

"What won't change" turns "don't break anything" into a promise you can test. Keeping the folder outside the repo means plans never land in a PR by accident.

Step 8: Hooks: rules ask, hooks enforce

The biggest lesson: a rule in CLAUDE.md is a request. A hook is a guarantee.

{
  "permissions": { "ask": ["Bash(git push:*)", "Bash(gh pr create:*)"] },
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/reminder.sh" }] }],
    "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "~/.claude/hooks/scope-guard.sh" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/stop-check.sh" }] }]
  }
}

permissions.ask: git push and gh pr create always prompt, even in auto mode. This is the simplest guard and the most important.
Reminder (UserPromptSubmit): whatever the hook prints is added to Claude's context, so one short paragraph re-anchors the rules on every prompt:

  #!/bin/bash
  echo "<rules>Rulebook: ~/.claude/CLAUDE.md. First line: lane. Test first. Smallest change. Ask before push.</rules>"

Scope guard (PostToolUse): after each edit, if the file isn't in the plan's scope.txt, it tells Claude to explain why and ask me. It warns, never blocks, because sometimes the extra file is correct. It just can't happen silently.
Stop check (Stop): when Claude finishes, it checks git status. If source changed but no test did, it returns {"decision": "block", "reason": "..."} and Claude has to keep working. It fires once per new problem, so it can't loop.

My rulebook lists which rules have a hook behind them. Then I know which rules are guaranteed and which are just hoped for.

The full scripts and their tests are in the starter kit.

Step 9: Test the setup

Hooks are code. A broken scope guard looks exactly like one with nothing to report. So ~/.claude/tests/ pipes fake hook input into each script and checks the output:

OUT=$(echo '{"tool_input":{"file_path":"src/Other.js"},"cwd":"'$REPO'"}' | ../hooks/scope-guard.sh)
echo "$OUT" | grep -q "UNPLANNED FILE" && echo ok || echo FAIL

I have 7 test files with 140 assertions, and I run them before every commit to ~/.claude. One more script tracks the context budget: the size of the rulebook plus all skill descriptions. That way bloat shows up as a number, not a feeling.

Step 10: Learn from review

When a reviewer catches a real bug I should have caught, I add one line to lessons.md: the general pattern, plus the check that catches it. The rulebook imports that file, and the review steps walk every lesson against the diff, so each miss turns into a check for later changes.

The same rule tells Claude not to trust review findings blindly. For each finding it checks the real code, then decides: challenge it with evidence, fix the root cause, list it as out of scope, or ask.

What I learned

One rulebook with precedence fixes most "Claude ignores me" problems.
One owner per job. Competing skills cause random behaviour.
Rules ask, hooks enforce. Put a hook behind whatever you can't afford to skip.
Warn more than you block. Strict hooks get disabled, and then they protect nothing.
STOP points where you decide (scope, plan, push, PR). Let everything in between run on its own.
Treat ~/.claude as code: git, small commits, tests.

Starter checklist

[ ] git init in ~/.claude with an allowlist .gitignore
[ ] One CLAUDE.md with a precedence clause
[ ] Lanes on the first line of every reply
[ ] Named relay steps, one owner skill each, clear STOP points
[ ] permissions.ask for push and PR
[ ] Hooks: reminder, scope guard, stop check, each with a test
[ ] lessons.md for every bug review caught

Start with the first three plus ask-before-push. That alone fixes most of the chaos. Or grab the whole thing from the starter kit and run bash tests/run.sh.

What does your setup look like? Tell me in the comments. 👇

I gave 8 AI agents an island and watched a society emerge — wars, gossip, grudges, and peace

Dhrupo Nil — Sun, 14 Jun 2026 07:30:50 +0000

Tiny Civilization: what happens when AI agents have to live together

I grew up on Age of Empires, Sid Meier's Civilization, and Rise of Nations. The thing that hooked me was never the graphics — it was the systems. You set a few rules in motion and a whole world spills out of them: economies, rivalries, alliances, betrayals.

Years later I watched OpenAI's hide-and-seek multi-agent video (writeup), where agents that were only rewarded for hiding and seeking invented tools and counter-strategies nobody coded — ramps, box-surfing, fort-building. Emergent behavior from simple pressure. That broke something open for me.

So I asked a smaller question: forget winning a game — what if AI agents just had to live in a society together? Would they behave like us? Hold grudges? Gossip? Make peace because they're tired of fighting?

That became Tiny Civilization — a browser sim where 2–8 agents with distinct personalities live on a small island, gathering, building, trading, stealing, gossiping, holding grudges, making peace, and remembering it all across lives.

👉 Live demo — runs keyless in "instinct mode," or plug in a key for LLM minds.

The whole thing — every line — was built with Claude Code, using the Fable model, right before Fable retired. It felt fitting to send a storytelling model off by having it build a world full of little stories.

The problem: pure-LLM agents are bankrupting and pure-utility agents are boring

The first design decision was the hardest. Two obvious options, both bad:

Call the LLM every tick. Every agent, every day, makes an API call. Beautiful, expressive — and it costs a fortune and crawls.
Pure utility AI (the classic RTS approach). Fast and free, but agents can't scheme, can't talk, can't surprise you. It's just min-maxing.

So I split the brain in two:

Layer	Decides	Cadence	Cost
LLM mind	Strategy (`gather`/`build`/`trade`/`befriend`/`aggress`/`reconcile`/`defend`), per-neighbor stances, an inner thought, and all dialogue	~every 15 sim-days	~150 calls / 1,000 days
Utility engine	Each day's concrete action — eat, sleep, gather, steal, attack, gift, trade, make peace	every tick	free, local

The LLM declares intent — "aggress against Kai, he raided my base" — and that biases the utility scores for the next two weeks. The body runs on instinct (hunger, energy, storms); the mind sets direction. This is the trick that makes it both affordable and alive.

Memory across lives — where it got strange

When a run ends, each agent's life is distilled into memory lines:

"you won with score 200"
"Maya destroyed your home"
"you and Kai made peace after a feud"
"this life hardened you — you trust less now"

Stored in localStorage, keyed by agent name, and injected into next run's prompts. Agents start referencing past lives in dialogue, pre-emptively paying reparations to remembered enemies, trusting remembered allies — sometimes to their own ruin.

How I actually built and balanced it

This is the part I'm proudest of, and it's pure childhood-strategy-game energy: you can't balance a society by vibes. So the workflow was:

A pure, deterministic simulation core — zero DOM, zero AI. The same runTick powers the browser, the tests, and a batch runner.
A seeded experiment runner. npm run experiment -- --runs 30 --days 1000 --seed 1 runs 30 reproducible lifetimes and spits out a win-rate/score table. Every balance change landed with a before/after table. (Example: a Hermit rebalance moved one agent from 0/30 wins to 9–11/30 without breaking the other archetypes.)
A 16-gate regression suite. The justification gate (no grievance → no violence), war burnout, reconciliation pricing, positive-sum trade, granary protection, homelessness-death, trait drift — each one locked behind a headless test so balance changes can't silently regress behavior.

Change a dial in constants.ts → run the experiment → read the table. That was the entire loop.

What emerged (none of this is scripted)

Running the same island over and over, with memory on, produced a coherent arc:

Massacres. Early on, the warrior just killed everyone. No deterrence existed.
Forever wars. I added a justification gate (violence needs a real grievance — theft, attack, trespass). That fixed unprovoked killing… but now wars never ended: 495 fruitless attacks across 1,500 days.
Diplomacy. Reconciliation + escalating reparations + war-weariness made endings inevitable. Attacks per 2,000-day run collapsed: 594 → 14 → 0.
The kleptocracy. With war capped, theft became the unpunished crime — 340 thefts/run. I fixed it the human way: granaries. Fortification, not punishment.
The golden age. A clean-slate run, no memories: zero attacks in 1,000 days, and the Warrior won by out-trading everyone (118 trades, 1 attack).
The fall. The very next run — now remembering that golden age — collapsed. Remembered trust lowered everyone's guard, which raised the payoff of betrayal. Scores dropped ~15%; every relationship ended negative. Peace between strangers turned out to be easier than peace between old friends with open tabs.

The recurring lesson: every time I patched one form of conflict, the agents found the next-cheapest one. Massacres → wars → theft → litigation. Exactly like us.

Stack

TypeScript, React, Zustand, Vite, Recharts. Default mind is z.ai GLM, but any OpenAI-compatible provider works per-agent — so you can literally pit Claude vs GLM vs Gemini in the same village and watch model-vs-model diplomacy. Keys never touch the browser (server-side proxy), and an adaptive-pacing controller learns each key's real rate ceiling.

Try it: https://multiagentciv.netlify.app/
Code: https://github.com/dhrupo/multi-agent-civilization

If you played the same strategy games I did, I think you'll feel right at home watching this thing run.

I translated my 7,000-line AI-coding handbook with 12 parallel AI agents

Dhrupo Nil — Sun, 07 Jun 2026 09:32:01 +0000

Last week I shipped a complete AI-coding handbook in Bangla — 79 terms decoded with everyday analogies, hands-on CLI guides, a 6-chapter story, and a 30-day practice path. The premise was the vocabulary wall: words like "token", "context window", and "harness" sound like spells until someone explains them plainly.

Turns out the vocabulary wall isn't a Bangla problem. It's a beginner problem.

So today the whole book exists in English:

🔗 https://github.com/dhrupo/dictionary-of-ai-coding-english

What's inside (the 60-second version)

📖 Part 1 — The words. 62 terms across 7 sections, each with a daily-life analogy instead of a textbook definition. A model is a calculator that never presses its own buttons. And Goldi 🐠 — a goldfish with a 3-second memory — keeps reminding you that models are stateless too.

🛠️ Part 2 — The tools. 7 hands-on guides: real CLI commands (Claude Code + Codex), AI-friendly folder structure (AGENTS.md, .claude/), bad-prompt → good-prompt rewrites, popular community skills (brainstorming, grill-me, TDD, handoff…), 17 extra terms (RAG, embeddings, temperature, hooks…), token economics, and safety — prompt injection explained with a postman analogy.

📜 Part 3 — The story. Nothing to install: Rafi, a 9th grader, builds his first portfolio site with an AI agent, makes every classic mistake (vague prompts, a hallucinated library, dragging a session deep into the dumb zone), and recovers using the tools from Part 2. You read over his shoulder.

🗓️ The 30-day path. One 5–15 minute mission a day. The first two weeks need nothing but a free AI chat. Plus a myth-busting FAQ, a 79-term index, and copy-paste templates/.

The fun part: the book translated itself the way it teaches you to work

Here's the meta-story. The handbook spends three chapters teaching subagents, handoff artifacts, and verification-before-completion. So when it came time to translate ~7,000 lines of Bangla markdown across 36 files… I used exactly that.

12 parallel AI agents, one session. Each agent got the same conventions block — character names (Goldi, Rafi), recurring section labels, file renames — plus its own slice of the book: three dictionary chapters here, the whole 6-chapter story to a single agent there (one translator = one consistent voice).

Three things made it work:

1. Deterministic rules beat agent judgment. The Bangla book's term headings were ### বাংলা-শব্দ (English Term). The convention: the English heading becomes exactly the parenthetical term. That one rule made every cross-file anchor predictable — agents working on different files in parallel could link into each other's not-yet-written chapters and have the slugs match.

2. A machine-verifiable gate, not vibes. The repo ships a tiny CI link checker (scripts/check-links.py) that validates every markdown link and anchor, GitHub slug quirks included. First run after the agents finished: 44 broken links. Leftover Bangla anchors, one agent guessing #esc-stop where another wrote ### ESC (stopping), a third doubling slugs like #-grill-me-grill-me. Twenty minutes of scripted fixes later: 36 files, every link alive. That checker now runs on every PR.

3. Verify, don't assume. The index agent didn't compute its 79 anchors — it read the actual translated files and extracted the real headings. Zero misses. Meanwhile an asset agent scanned every terminal-GIF source script for Bangla characters and found… none. The GIFs had been authored in English all along. The "re-render 26 GIFs" task evaporated because an agent checked instead of assuming.

If that workflow sounds useful, it's literally what Part 2 and Part 3 of the book teach — subagents, handoffs, verification — just pointed at itself.

It's a community thing

Everything is CC BY 4.0, in both languages, and the two editions cross-link. Issue forms for "I found a mistake" and "suggest a new word" are ready in both repos.

💙 Built on the shoulders of Matt Pocock's Dictionary of AI Coding — Parts 2 and 3 grew far beyond it, but the soul is his.

And the offer from the Bangla launch stands: if you speak another language, steal this structure. The deterministic-heading trick + a link checker means the next translation is mostly an afternoon of agent-wrangling. I'd genuinely love to see a Spanish, Hindi, or Vietnamese edition.

🔗 https://github.com/dhrupo/dictionary-of-ai-coding-english
🇧🇩 Prefer Bangla? https://github.com/dhrupo/dictionary-of-ai-coding-bangla

I built a complete AI-coding handbook in Bangla - words, tools, a story, and a 30-day path

Dhrupo Nil — Fri, 05 Jun 2026 17:14:15 +0000

A year of AI-coding discourse taught me one thing: the hardest part isn't the tools — it's the vocabulary wall. If English isn't your first language, "token", "context window", "hallucination", "harness" don't sound like concepts. They sound like spells. 🪄

Matt Pocock's brilliant Dictionary of AI Coding showed how teachable these words really are. So I adapted it into Bangla — and then kept going, way past where the original stops. Today it's a complete, free, open-source learning path:

🔗 https://github.com/dhrupo/dictionary-of-ai-coding-bangla

The four-stage arc: শব্দ → হাতিয়ার → গল্প → অভ্যাস

(words → tools → story → habit)

📖 Part 1 — The words. 62 terms across 7 sections, each with a daily-life analogy instead of a textbook definition. A model is a calculator that never presses its own buttons. Parameters are mixing-board knobs. And there's গোল্ডি (Goldie) — a goldfish with a 3-second memory who keeps reminding you that models are stateless too. 🐠

🛠️ Part 2 — The tools. This is where it goes beyond the original: 7 hands-on guides covering real CLI commands (Claude Code + Codex, mapped back to the concepts — /compact is just the Compaction button), AI-friendly folder structure (AGENTS.md, .claude/, who reads what and when), bad-prompt → good-prompt rewrites, the popular community skills (brainstorming, grill-me, TDD, handoff…), 17 extra terms (RAG, embeddings, temperature, hooks…), token economics, and safety (including prompt injection, explained with a postman analogy).

📜 Part 3 — The story. Instead of a tutorial you have to install things for, it's a 6-chapter read-along: রাফি, a 9th grader, builds his first portfolio site with an AI agent. He makes every classic mistake — vague prompts, trusting a hallucinated library, dragging a session deep into the dumb zone — and recovers using the tools from Part 2. Margin notes call back every concept at the exact moment it bites. The reader installs nothing.

🗓️ The 30-day path. Reading isn't owning. So the book ends with 30 daily missions (5–15 min each). The first two weeks need zero setup — just any free AI chat and open eyes ("ask the same question twice — did the answers match?"). Weeks 3–4 go hands-on, but every mission has a read-only alternative.

Plus: a myth-busting FAQ ("AI will eat my job", "you need a CS degree"), a 79-term alphabetical index, copy-paste templates/ (a starter AGENTS.md, a working /handoff command, a SKILL.md example), and 26 terminal GIFs — all reproducible from committed VHS scripts.

Things I learned building it

Analogies are load-bearing, not decoration. "Prefix cache" never landed until it became "the waiter remembers your usual order."
A story teaches sequencing in a way lists can't. You can document /compact vs /clear vs handoff perfectly and people still won't know when. Watching রাফি lose his color-scheme decision to a long session — that sticks.
Bengali text breaks your tooling in fun ways. grep couldn't match half my content (decomposed Unicode), GitHub slugs for emoji-prefixed headings start with a stray hyphen, and nested code fences need 4-backtick outers. The repo's link checker is a tiny Python script for a reason.
Beginners deserve the real thing. Simplified ≠ dumbed down. The dictionary keeps the exact English terms visible everywhere, so readers can walk into any English doc afterward and feel at home.

It's a community thing

Everything is CC BY 4.0. There are Bangla issue forms for "I want a new word" and "I found a mistake" — contributions of any size welcome, from a typo to a better analogy to a whole new section.

And if you speak another language: steal this structure. The vocabulary wall exists in every non-English-speaking dev community, and the fix is surprisingly fun to build. 💙

🔗 https://github.com/dhrupo/dictionary-of-ai-coding-bangla

Your AI Coding Agent Wastes 80% of Its Context. Fixed That with Graph Theory.

Dhrupo Nil — Mon, 25 May 2026 13:45:00 +0000

The problem nobody admits

When you give Claude Code, Cursor, or Codex a task like "fix the login validation bug", here's what they usually do:

Run grep -l login src/ → 17 files
Read all 17 files top-to-bottom (because context is "free")
Spend 80% of the model's context window on irrelevant imports, type aliases, and helper functions the bug doesn't touch
Generate a fix using whatever 20% of attention is left

This works. Sort of. But it's wasteful — and on big codebases, it's wrong: the agent runs out of context before it sees the actual buggy function.

The instinct is to throw a bigger model at it. Bigger context window, fancier RAG, vector embeddings. All of which trade real cost for diminishing returns.

There's a better answer that's been sitting in classical CS the whole time: treat the repo as a graph.

The idea, in one paragraph

Your codebase already is a graph. Functions call functions. Modules import modules. Classes extend classes. Pick a node (the symbol your task is about), and the structurally-closest neighborhood is almost certainly what an agent needs to see.

So I built mincut-context — an npm package that:

Parses your repo into a symbol graph (tree-sitter, supports TS/JS/Vue/Python/PHP)
Derives seed nodes from your task description (keyword IDF on symbol names + file paths)
Runs personalized PageRank with the seeds as the restart vector
Picks the minimum-cut subgraph that fits a token budget you choose

The output: a list of files + line ranges that an agent should look at. Nothing more, nothing less.

Show me the numbers

I built an evaluation suite into the repo itself. 28 hand-labeled tasks across 3 real codebases at a 4,000-token budget:

strategy	precision	recall	F1	token-efficiency
mincut	0.27	0.83	0.39	0.270
mincut + `--embed` (semantic)	0.27	0.83	0.39	0.270
grep keyword baseline	0.11	0.42	0.16	0.105
random selection (control)	0.01	0.04	0.01	0.009

Per-repo breakdown:

repo	tasks	mincut recall	grep recall	mincut F1	grep F1
mincut-context (self)	12	0.97	0.56	0.44	0.30
FluentForm (PHP+Vue+JS)	8	0.88	0.13	0.43	0.04
Fluent Player (TS/JSX)	8	0.63	0.56	0.31	0.13

mincut catches ~2× more of the correct files than grep, at ~2.5× better token efficiency. Reproducible with npm run eval. Add your own labeled tasks under eval/fixtures/ to score against your own codebase.

The math, briefly

Given a symbol graph $G = (V, E, w)$ where:

$V$ are code units (functions, classes, methods)
$E$ are dependency edges (imports, calls, references)
$w(v)$ is the token cost of including symbol $v$
$B$ is your token budget
$S \subseteq V$ are seed nodes derived from the task

Find $T \supseteq S$ with $\sum_{v \in T} w(v) \le B$ minimizing the boundary cut cost:

$$\text{cut}(T, V \setminus T) = \sum_{e \in E, \text{ crossing}} w(e)$$

In plain English: pick a connected, low-token region that has few "loose ends" pointing outside it. The inside of the cut is what the agent needs; the outside is safely ignorable.

The objective is submodular, so a greedy algorithm gives a $(1 - 1/e) \approx 0.63$ approximation guarantee. The full pseudocode is in the README; the implementation is ~200 lines in src/core/select.ts.

Three ways to use it

1. As an MCP server — recommended for agents

Drop this block into your Claude Code / Codex / Cursor settings:

{
  "mcpServers": {
    "mincut-context": {
      "command": "npx",
      "args": ["-y", "mincut-context", "mcp"]
    }
  }
}

Your agent now has six new tools: pack_context, expand_node, find_callers, find_callees, search_symbols, explain_selection. They operate on the cached graph from the most recent pack_context call — effectively free traversal after the first pack.

2. As a CLI

npm install -g mincut-context

mcx pack "fix the login validation bug" --budget 4000             # plain output
mcx pack "..." --format tree                                       # directory-grouped
mcx pack "..." --format json | jq                                  # pipe to anything
mcx pack "..." --interactive                                       # Ink TUI: vim keys + preview
mcx pack "..." --embed                                             # semantic seeding
mcx pack "..." --cache                                             # 5× warm-run speedup
mcx watch "..." --debounce 300                                     # re-pack on file change
mcx doctor                                                         # environment self-check

mcx doctor is my favorite — it tells you in 6 lines what's installed and what isn't:

3. As a library

import { pack } from 'mincut-context';

const result = await pack({
  task: 'fix the login validation bug',
  repo: process.cwd(),
  budget: 4000,
  cache: true,
  parallel: 4,
  chunk: { enabled: true, maxTokens: 400 },
});

for (const f of result.files) {
  console.log(f.path, f.score.toFixed(3), f.tokens, '·', f.reasons[0]);
}
// → src/auth/login.ts        0.541  612 · seed — matched directly by task
// → src/auth/session.ts      0.408  483 · attached (60%)

What I learned by building this

1. Embeddings are oversold for this problem

Adding semantic embeddings (--embed flag, via @xenova/transformers running locally) did not improve recall on any of my three eval task sets. Why? Because the labels were named honestly. When you label "stripe payment processor" → StripeProcessor.php, the keyword match catches it without help. Embeddings only earn their keep when your task vocabulary diverges from the code's — "centrality and ranking" → PageRank, that kind of gap.

I left --embed in because it doesn't hurt, and there are real users whose mental model doesn't match the code. But the marketing-friendly "AI-powered" framing for this stuff is mostly noise.

2. Greedy beats CELF for this objective

I implemented CELF (Cost-Effective Lazy Forward, Leskovec 2007) hoping for a free speedup over the naive greedy. It diverged — not just slower (8× slower on FluentForm) but wrong: it produced smaller, structurally weaker selections.

Why: our "no isolated nodes" acceptance rule (a candidate must have at least one edge into the current selection) breaks CELF's submodular-monotone assumption. A candidate's eligibility flips discontinuously when a node with an edge to it joins T. The lazy cache becomes unreliable.

I wrote the dead end up in eval/ALGORITHM-RESEARCH.md so nobody re-treads it. Honest negative results are worth shipping.

3. Sub-symbol chunking matters more than I expected

Big legacy codebases have huge functions. A 500-line function is one symbol in the graph, and if it gets selected, the whole thing eats your budget. So --chunk splits big functions at statement boundaries — each chunk becomes its own sub-symbol, individually selectable.

On FluentForm: indexing without chunking → 4,333 symbols. With --chunk → 4,878 symbols (+545 chunks). Same budget, much finer-grained selection. The greedy can pick just the relevant if/for/try block instead of all-or-nothing.

4. Test coverage of 88% isn't the whole story

The CI gates on 85% statements / 80% branches / 90% functions / 85% lines. But the genuinely-untestable files — worker scripts, lazy-loaded LSP clients — are excluded from the calc. Honest reporting means saying what is tested, not just the headline number.

The honest tradeoffs

Honest tradeoff	What we do
True optimal min-cut is NP-hard	Greedy submodular — `(1−1/e)` bound
Tree-sitter symbols are syntactic, not type-aware	`--lsp` refines TS/JS via typescript-language-server
Embedding model adds ~22 MB on first run	Opt-in behind `--embed` flag
LSP startup is slow (~1–5s)	Opt-in; cached after init
Cold start parses whole repo	`--cache` (5× speedup) + `--parallel n` (2.7× speedup)

What I'd build next if you asked

The roadmap that's not checked off yet:

Pyright / Intelephense LSP adapters — type-aware calls for Python and PHP (~1–2 days each on the existing LSP infrastructure)
Svelte / Rust / Go parsers — one file each on the parser template
Incremental neighborhood caching in the greedy — keep attach(v, T) cached and update only when a node with an edge to v is added. Expected 3–5× speedup on graphs with bounded degree.

Each is bounded effort and additive. The core is done.

Stop building, start using

The hardest lesson: a tool's value comes from someone actually using it on real work, not from feature count. mincut-context is at v1.7.0 — 261 tests, 88.6% coverage, CI green on Ubuntu + macOS × Node 18/20/22. There's no honest "but it's not ready" excuse left.

If you've watched an AI agent burn 80% of its 200k-token context on imports it doesn't care about, install it now and tell me what breaks:

npm install -g mincut-context

🔗 GitHub: github.com/dhrupo/mincut-context
📦 npm: npmjs.com/package/mincut-context
📊 Reproducible benchmarks: eval/CROSS-REPO-RESULTS.md

I'd love feedback — especially "your numbers don't replicate on my codebase" feedback. That's literally what the eval suite is for.

If you got value from this, ⭐ the repo or drop a comment about a tooling problem you're solving. mincut-context is open-source MIT; the eval suite welcomes new fixtures.

DEV Community: Dhrupo Nil

Dev OS v2: gates, a learning loop, and agents that check agents

1. One rulebook, every agent

2. Gates beat reminders

3. It learns by itself

4. Agents check agents

5. Prove it by running it

6. Project memory: graph first

7. Stay lean

The userland

Upgrade or start

Host up to 10 WordPress sites for free with Oracle Cloud and xCloud

How it fits together

Running up to 10 sites

What you get

Before you start

Part 1 — Create the Oracle Cloud account

Part 2 — Create the network (VCN)

Open web ports (80 and 443)

Part 3 — Create the server (instance)

Out of capacity

About the Pay As You Go card hold

Set a $1 budget alert (do this on Pay As You Go)

Part 4 — Prepare the server

4.1 Add swap (1 GB AMD server only)

4.2 Open ports 80 and 443 inside the server

Part 5 — Connect the server to xCloud

Part 6 — Get a domain (optional)

Point the domain to the server

Part 7 — Add a site

Troubleshooting

Wrapping up

How I set up Claude Code: one rulebook, a 12-step relay to use it daily

What we're building

Step 1: Make ~/.claude a git repo

Step 2: Write ONE rulebook

Step 3: Lanes

Step 4: The relay

Step 5: Skills, one owner per job

Step 6: Pin skills, keep your edits

Step 7: Plans live outside the repo

Step 8: Hooks: rules ask, hooks enforce

Step 9: Test the setup

Step 10: Learn from review

What I learned

Starter checklist

I gave 8 AI agents an island and watched a society emerge — wars, gossip, grudges, and peace

Tiny Civilization: what happens when AI agents have to live together

The problem: pure-LLM agents are bankrupting and pure-utility agents are boring

Memory across lives — where it got strange

How I actually built and balanced it

What emerged (none of this is scripted)

Stack

I translated my 7,000-line AI-coding handbook with 12 parallel AI agents

What's inside (the 60-second version)

The fun part: the book translated itself the way it teaches you to work

It's a community thing

I built a complete AI-coding handbook in Bangla - words, tools, a story, and a 30-day path

The four-stage arc: শব্দ → হাতিয়ার → গল্প → অভ্যাস

Things I learned building it

It's a community thing

Your AI Coding Agent Wastes 80% of Its Context. Fixed That with Graph Theory.

The problem nobody admits

The idea, in one paragraph

Show me the numbers

The math, briefly

Three ways to use it

1. As an MCP server — recommended for agents

2. As a CLI

3. As a library

What I learned by building this

1. Embeddings are oversold for this problem

2. Greedy beats CELF for this objective

3. Sub-symbol chunking matters more than I expected

4. Test coverage of 88% isn't the whole story

The honest tradeoffs

What I'd build next if you asked

Stop building, start using

Step 1: Make `~/.claude` a git repo