Chemaclass - software

Skills Over Agents

2026-05-19T00:00:00+00:00

People compare coding agents. Claude Code, Codex, Gemini CLI. Which one is smarter, faster, cheaper. New benchmarks every month.

Wrong question.

After a year wiring agents into real projects, what moved the needle wasn’t the agent. It was the skills I wrote for it.

Agents are commodities #

Every coding agent has the same shape. A language model, a runtime, filesystem access. Read, reason, write. Generalist by design.

Two teams use the same agent. One ships clean, tested code. The other ships garbage that looks good. Same model. Different teaching.

The model is the engine. Skills are the map. Without a map, a powerful engine gets you lost sooner.

Intelligence is not expertise #

Who handles your taxes? A 300 IQ genius who never read tax law, or an accountant with 20 years of filings?

An accountant knows which deductions apply, which filings your business needs, which mistakes get flagged. Not intelligence. Expertise.

AI agents have the same gap. A model reasons about code and writes solutions. It doesn’t know your hexagonal layers. It doesn’t know domain entities must never import framework code. It doesn’t know every feature starts with a failing test.

Skills close that gap.

Skills load context on demand #

A skill is a markdown file in .claude/skills/. A procedure, a pattern, a slice of domain knowledge. Plain markdown with frontmatter.

The key is how they load. The agent reads only names and descriptions at startup. Loads the full skill when the task matches. Follows links to references only when it needs to dig deeper.

That on-demand loading is what makes skills scale. Twenty skills cost almost nothing until one fits the task. Specialized agents, by contrast, carry their full instructions every time they run. More agents, more fixed cost.

.claude/skills/
 code-review/
 SKILL.md # main instructions
 reference/
 solid-checklist.md # detailed SOLID examples
 test-patterns.md # test quality guidelines

The SKILL.md:

---
description: "Review code changes for SOLID violations, test quality, and architecture alignment"
allowed-tools: Read, Grep, Glob
argument-hint: "[file or PR]"
---

# Code Review

Review code changes against project conventions.

## Steps

1. Read the diff or specified files
2. Check architecture: domain layer has no framework imports, infrastructure stays thin
3. Check SOLID principles (see reference/solid-checklist.md for patterns)
4. Check test quality: tests verify behavior, not implementation details
5. Flag issues with the specific principle violated and a suggested fix

## Output

For each issue found:
- File and line
- What's wrong (which principle or convention)
- What the fix looks like

Agent sees the description in the skill list. Ask for a review, it loads SKILL.md. Needs a SOLID pattern, reads the reference. Two levels, on demand.

Skills vs specialized agents #

I covered specialized agents already: isolated workers with their own prompt and tool set. Great for parallel work and clean context boundaries.

Specialized agents are coarse. One agent, one role, one fixed prompt. If you want three kinds of review quality, you either write three agents or stuff one agent with everything.

Skills are finer. One agent, many skills. The right skill loads for the task. Context stays small. Quality stays high.

Rule of thumb:

Use a skill when you need a procedure or pattern. From phel-lang: /gh-issue (issue to PR), /commit (conventional commit), /refactor-check (SOLID review).
Use an agent when you need isolation. From phel-lang: tdd-coach (TDD pairing), clean-code-reviewer (PR review), domain-architect (architecture exploration).

Most needs are skills, not agents.

Agents give you speed. Skills give you quality. If you must pick one first, pick skills.

Skills are your edge #

Models improve every month. This year’s best is next year’s baseline. The major families converge. Better tool shows up, you switch.

Your skills don’t switch with the tool. They encode your domain, conventions, architecture. They live in your repo. They travel with your code. Point a new model at the library, productive day one.

The agent is replaceable. Your skills are not.

Start with the first repeated prompt #

You don’t need 20 skills on day one.

Zero. Then one.

The signal is repetition. The second time you type the same context, that’s a skill waiting. Extract it into a markdown file. Next session, the agent knows.

Concrete example. On phel-lang, I kept pasting the same brief every session: read issue #N, branch from the labels, TDD, open the PR. Third repeat, I extracted it into a /gh-issue skill. Now I type /gh-issue 142 and the agent picks up the issue, creates fix/... or feat/... from the labels, writes the failing test first, implements, opens the PR. One markdown file. The session no longer starts from zero.

Don’t write from scratch. Ask the agent: “Read this project and draft a minimal code review skill based on what you see.” It scans, picks up conventions, drafts v1. Then you adjust. Add what it missed. Cut what doesn’t apply. Sharpen the description.

The second skill usually comes from a mistake. Agent breaks a convention. Write a skill that teaches the correct approach. It won’t happen again.

Skills add up. Each one lifts the baseline. A markdown file, maybe 50 lines. Permanent payoff.

People who don’t write skills keep re-explaining what they “really want.” Every session from zero. Not a tool problem. A knowledge management problem.

The agent ships next year. The skill ships forever.

Write the skill once. Every session after that starts where the last one ended.

The Levels of AI Adoption

2026-05-01T00:00:00+00:00

Most companies use AI today, but few know where they stand on the AI adoption ladder. At one end, you paste code into ChatGPT. At the other, agents open PRs while you sleep. Beyond that, AI reaches people who never touched a terminal. This post maps the path.

Where we started #

Using AI to code meant a second tab. Write a function, get stuck, paste the error into chat, paste the answer back, and hope it works. It was slow, messy, and disconnected from your code.

GitHub Copilot, built on OpenAI’s early Codex, added suggestions inside the editor, often confidently wrong. It was trained on public code, and most public code isn’t great. It also knew nothing about your domain, your conventions, your architecture. It was autocomplete that sometimes guessed right.

The first generation of AI coding tools gave you a parrot trained on the whole internet. Fluent, confident, and often saying things that made no sense in your codebase.

This was vibe-coding in its first form: you gave the vibe by pasting context, and the AI filled in code that looked right. It compiled often enough to feel useful, and broke often enough to feel dangerous.

The IDE generation #

The next step was obvious: if the AI needs context, give it the whole editor.

Cursor, Windsurf, and similar IDEs moved the model inside your coding flow. The assistant could read files, follow imports, and see more than one function at a time. Vibe-coding became a conversation with your project, and productivity jumped. For a moment, it felt like the endgame.

It wasn’t. Editing files is only part of the job. The rest is running tests, reading logs, opening branches, reviewing diffs, and understanding what the codebase already does. Editor-only assistants helped you type faster, but they couldn’t take a task from “fix this bug” to “PR ready for review.”

The agentic shift #

OpenAI launched Codex as a cloud agent: give it a task, it works on a branch, and you come back to a PR. Anthropic shipped Claude Code, a CLI agent in your terminal, on your repo, with your tools.

This was the big shift, and not because the models were smarter. The unit of work changed. You stopped prompting line by line and started delegating tasks: read the ticket, write the change, run the tests, explain what you did. An agent doesn’t need hand-holding. It needs a goal and the right context.

The jump from assistant to agent is not a speed improvement. It’s a change of job description. You move from typing code to directing work.

Claude Code needs almost no setup. No editor lock-in. Point it at your repo, drop a .claude folder with rules and conventions, and it adapts. I covered that in Inside the .claude Folder.

The model you pick matters more than before. Today’s frontier models are way ahead of where they were a year ago. The gap between “can draft a function” and “can refactor a module with judgment” closed faster than expected, and it keeps closing as Claude, Codex, and Gemini push each other forward every month. Prices are getting closer too, which is a polite way of saying everyone copies whoever figures out the sustainable version first.

Agents with their own home #

The next leap wasn’t smarter models, it was agents with their own machine.

OpenClaw is the clearest example. It’s an open-source gateway you run on your own hardware (Mac Mini, old laptop, VPS), an always-on agent connected to your messaging apps, files, and calendar. You bring your own brain: Opus, GPT, or a local model via Ollama. When a provider tightens limits or raises prices, you switch. You own the setup.

A coding agent lives inside one repo for a task. An OpenClaw-style agent lives in your life, across days and tools. Sauron is mine. It reviews my PRs, opens issues, drafts code, ships open source contributions, and pushes back when I’m about to tunnel on something. Anything I can do on a computer, it can do too, just faster. It stops being a tool you open and becomes a place you work in.

A coding agent is a coworker you invite to a task. A gateway agent is a coworker who lives on a machine and shows up every day.

Providers change their plans and limits faster than anyone tracks, so people build setups that aren’t tied to one vendor. The logo on the model matters less every quarter, and the architecture around it matters more.

AI beyond developers #

AI coding was the loudest story because developers are loud. The bigger story is agentic tools reaching people who never wrote a line of code.

ChatGPT agent mode and Claude’s Cowork are the obvious examples: an AI that reads your documents, fills your spreadsheets, drafts your slides, and runs code for you in the background. Claude Design launched on April 17 and dropped Figma’s stock over 7% on launch day. The pitch is simple: describe what you want, get a working prototype, hand it to Claude Code to ship. A workflow that used to need a designer, a PM, a frontend engineer, and three review rounds is squeezed into one conversation.

Lovable, v0, Canva, and Figma itself are all under pressure to rethink their positioning. Whether Claude Design “kills” any of them is the wrong question. The right one is what happens when making a usable prototype drops from “hire a designer” to “describe it out loud.”

The companies feeling this first aren’t the design tools. They’re the small businesses that couldn’t afford design work, the founders building a pitch deck at midnight, the PMs testing an idea before booking a meeting. There’s a minority of cases where someone would have paid a designer and now won’t, and that cost is real. But in most of them, AI didn’t replace anyone: it filled a space where no designer was ever going to exist.

The levels of AI adoption #

Every company I talk to sits somewhere on this ladder. The levels aren’t about how much you pay in licenses, but about how deeply AI is built into the way work gets done, and not just in engineering.

Level 0: Denial #

A company-level stance. No AI, officially. Some people use ChatGPT on personal laptops and don’t mention it. Leadership worries about IP leaks, or hasn’t made it a priority. The conversation stays at “we should look into this someday.”

The risk here isn’t technology, it’s time. Every month at Level 0 is a month your competitors grow their lead.

Level 1: Personal productivity #

Individual adoption. AI is allowed, maybe encouraged. Each person uses it their own way: ChatGPT in a tab, Copilot in the IDE, Claude for the tricky stuff, a design tool for mockups. Output goes up, but the know-how stays inside each person’s head. Two engineers, or two PMs, or two designers on the same team get very different results because they prompt differently.

Most companies are here in early 2026. It’s a real improvement over Level 0, and it’s where the myth of “AI gives you speed” gets born. As I argued before, speed without shared direction is faster chaos.

Level 2: Shared practices #

The team agrees on how to use AI: shared conventions, prompts people reuse, rules in the repo, a shared sense of when to trust the output and when to push back. Code reviews catch AI mistakes the same way they catch human ones, and design reviews do too. Tests are required whether a person or a model wrote the code.

This is the first level where AI becomes a team skill rather than a personal habit. Higher ceiling, higher floor. New people ramp up faster because the prompts and rules capture how the team works.

Level 3: Context-aware tooling #

The team invests in context: rules files, conventions, architecture docs agents can read, and MCP servers connecting agents to the databases, APIs, and internal tools they need. The AI stops being a generic assistant and becomes closer to a coworker who has read the onboarding docs.

At this level, quality depends less on the model and more on the context around it. A weaker model with great context beats a frontier model with none. Good docs and clean architecture pay off twice: they help both humans and agents.

Level 4: Agentic teams #

Instead of one assistant, you get a squad: a TDD coach, a clean code reviewer, a domain architect, a docs maintainer. Outside engineering, the same idea applies with research, design, and ops agents. I covered the developer side in Build Your Own Team of Agents, and the leverage is real.

Humans stop competing with AI on speed and start directing it. You review, decide, and set the bar. Agents handle typing, and increasingly the thinking. Pair programming with a person still wins on complex trade-offs, but an agent pair is always there for the rest.

At the company level, the org chart, roles, and processes are still the same. What changes is that each person produces a lot more, and the team’s output reflects it. Level 4 multiplies output inside the existing structure. Level 5 changes the structure.

Level 5: AI-native workflows #

The final shift is about how the company runs. Processes are designed around agents instead of just fitting them in. Tickets are written so an agent can act on them, and reviews assume part of the work was written by a machine. Architecture decisions take into account what agents do and don’t do well. Even hiring changes: a senior IC at Level 5 is closer to a tech lead leading people and agents than a classic individual contributor.

Few companies are fully here in 2026, but the direction is obvious enough that ignoring it is its own decision.

You don’t move up a level by buying better tools. You move up by changing how work is organized and reviewed.

AI is not stealing jobs #

I keep hearing people call this a layoff story, and that framing is lazy.

The industrial revolution didn’t end work. It ended specific kinds of work and created others. The people who lost the most refused to re-skill, and the people who gained the most learned to operate the new machines instead of competing with them.

Same pattern here. AI isn’t taking your job, it’s changing what your job is. A developer who learns to lead agents out-ships one who refuses. A designer making ten versions before lunch with Claude Design out-designs one still opening Figma from scratch. A PM who ships prototypes out-prioritizes one writing specs nobody reads.

AI doesn’t replace the skilled worker. It replaces the worker who thinks skill is a fixed asset instead of a moving target.

With the right training, model, and setup for your context, AI gives you 10x speed without losing quality. I’ve seen it, and it’s not marketing. But the 10x only shows up when you already know what good looks like. Without that foundation, AI happily produces 10x more mediocre work.

That’s the honest version of the promise: AI can produce crap ten times faster, and excellent work ten times faster. Which one you get is on you.

The shift in where your attention goes #

You stop thinking about details first and start thinking about direction: what are we building, who for, what shape, and which trade-offs. Agents then do most of the implementation while you protect quality and coherence.

This sounds like good news for anyone who prefers architecture to typing, and it is. But there’s a trap: you can only work at the high level if you know the low level well enough to catch drift. When the agent produces something subtly wrong (a test that passes for the wrong reason, a refactor that changes behavior under load, a design that breaks on mobile), you need to spot it instantly. If you can’t, you’re not directing, you’re signing off on whatever shows up.

AI lets you spend more time on direction, but only if you’ve already earned the right to ignore the details. You earn that by having mastered them first.

Why the ladder matters #

I see teams skip levels and fail. A team jumps from Level 1 to Level 4 because leadership read a blog post about agent squads, and the agents produce mountains of low-quality code because nobody agreed on what quality means. The agents aren’t the problem, the missing foundation is.

The ladder is an order that matters. Shared practices come before context engineering, context engineering before agent teams, and agent teams before AI-native workflows. Each level builds on the previous one, the same way clean code builds on naming, and naming builds on knowing what you’re modelling.

The companies that win the next few years aren’t the ones with the biggest AI budget. They’re the ones that climb this ladder deliberately, one level at a time, without skipping the parts that look boring.

Where to start #

At Level 0 or 1, the next move isn’t more licenses. It’s deciding, as a team, how to use these tools. Write it down, commit it to the repo, and review it every week or month as the tools evolve.

At Level 2 or 3, look at where context is missing. What does your AI not know about your codebase, product, or brand that a new hire would learn in week one? Write it down. An afternoon of rules and docs pays back for months.

Further along, the question flips. You stop asking “how do I use AI better?” and start asking “how does my team need to change so AI amplifies what we already do well?” That’s a leadership question, not a tooling one.

AI is moving fast, but the work of adoption is still slow and human. The tools are the easy part. The hard part is deciding what good looks like, writing it down, and holding the line.

AI can execute, but it doesn’t know where you’re going. It can produce, but it doesn’t know what’s worth producing. That part is still on us. Speed is a gift, and direction is a responsibility. From the solo engineer at Level 1 to the AI-native org at Level 5, the same truth holds: the human supervises, understands, and gives meaning. The machine does the rest.

When the hype settles (and it will), the question won’t be “did you use AI?” Everyone will. The question will be “at what level, and with what direction?”

Inside the .claude Folder

2026-04-17T00:00:00+00:00

Every project I work on has a .claude/ folder at the root. Committed to git, like the rest of the code.

That folder turns Claude Code from a generic assistant into a project-aware teammate. Everyone who clones the repo inherits the same setup.

Agentic coding is only as good as the context you give the agent. The .claude/ folder is where that context lives.

The .claude folder, at a glance #

.claude/
├── CLAUDE.md # project onboarding
├── settings.json # permissions, hooks, env
├── skills/ # reusable procedures (slash commands)
├── rules/ # glob-targeted conventions
├── hooks/ # shell scripts run on events
└── agents/ # specialized roles

Six layers, one folder. Context, safety, procedures, guardrails, automation, specialists.

The foundation #

CLAUDE.md: where everything starts #

Claude Code reads CLAUDE.md on every boot. The onboarding doc.

In Phel, mine covers the compiler pipeline (Lexer → Parser → Analyzer → Emitter), module structure, conventions, and key commands.

A global ~/.claude/CLAUDE.md applies to all your projects. The project file says how this codebase works. The global file says how I work.

Every byte ships in every prompt. Keep it short. Past one screen, move detail into rules/ or skills/.

A good CLAUDE.md is a good onboarding doc. The better it is, the less you repeat yourself.

settings.json: safety before leverage #

Before giving the agent more power, lock down what it must never do.

.claude/settings.json holds three things: permissions (allow/deny), hooks (event commands), and env (variables). A gitignored settings.local.json keeps personal overrides separate.

{
 "permissions": {
 "allow": [
 "Bash(composer:*)",
 "Bash(./bin/phel:*)",
 "Bash(git:*)",
 "Bash(gh:*)"
 ],
 "deny": [
 "Bash(rm -rf:*)",
 "Bash(sudo:*)"
 ]
 }
}

Allow unlocks flow. Deny draws the line agents cannot cross, even when asked politely.

Permissions are the floor. Everything else builds on top of a safe baseline.

Procedures and guardrails #

Skills: procedures you can run #

Next pain after onboarding: repetition. Skills solve that.

A skill is a markdown file in .claude/skills/, a procedure you call with a slash:

/gh-issue <number>: issue to branch, TDD plan, PR.
/commit: fix, analysis, tests, conventional commit.
/refactor-check: SOLID, naming, architecture smells.
/release [version]: changelog, PHAR, tag, release.

Raw prompt: “fix issue #42”. Agent improvises. Different every time.
Rule: “use conventional commits”. Shapes output, not procedure.
Skill: “/gh-issue 42”. The procedure is the instruction.

Skills turn tribal knowledge into runnable steps anyone can execute.

Skills capture what to do. Rules capture what not to do.

Rules: the guardrails #

CLAUDE.md is read every session. Rules only when they match. Files in .claude/rules/ target code areas with glob patterns: the agent loads only what applies, keeping context lean.

Rule files in Phel:

compiler.md: strict 4-phase pipeline, no bypassing.
php.md: PER 3.0, final classes, readonly, Gacela.
phel.md: kebab-case, defn- private, :doc/:example required.
integration-tests.md: --PHEL-- / --PHP-- fixture sections.

Compiler rules don’t fire when editing Phel source. Phel rules don’t fire when editing PHP infrastructure.

Rules are not suggestions. They travel with the code: a convention change and its rule ship in the same commit. No drift, no outdated wiki.

Automation and delegation #

Hooks: automation at the edges #

Rules tell the agent what to do. Hooks make sure it happens even if the agent forgets.

Shell commands triggered by Claude Code events (PreToolUse, PostToolUse, Stop), wired through settings.json. In Phel, PreToolUse blocks edits to critical files (build/release.sh, .github/*, composer.lock). PostToolUse auto-formats PHP via php-cs-fixer.

{
 "hooks": {
 "PreToolUse": [{
 "matcher": "Edit|Write",
 "hooks": [{ "type": "command", "command": ".claude/hooks/protect-files.sh" }]
 }],
 "PostToolUse": [{
 "matcher": "Edit|Write",
 "hooks": [{ "type": "command", "command": ".claude/hooks/format-php.sh" }]
 }]
 }
}

Rules are what the agent should know. Hooks are what the system enforces anyway.

Agents: specialized roles #

Everything so far shapes one agent. Agents add specialists the main agent can delegate to, each with its own tools, permissions, and model. Most advanced piece. Recommend it last.

A few from Phel:

Explorer (Sonnet, read-only): files, structure mapping.
Clean Code Reviewer: SOLID and naming on diffs.
TDD Coach: red-green-refactor enforcement.
Domain Architect: module boundaries, compiler pipeline.
Debugger: compiler errors across all phases.

Each agent runs in its own context window: the main session stays clean while the specialist digs deep. The win is not only cost, it is focus. An agent with only read and grep cannot rewrite your codebase by mistake.

Right model for the right job. Fast and cheap for exploration. Deep and careful for architecture.

Start small, grow with friction #

Do not build all of this on day one.

The order, driven by real friction:

Start with CLAUDE.md.
Lock down settings.json permissions.
First time you repeat yourself, write a skill.
First time the agent breaks a convention, add a rule.
First time something bad almost gets committed, add a hook.
First time a generalist is wrong for the job, define a specialist.

Each step fixes a problem you actually had. Not one you imagined.

The setup grows from real friction, not from upfront design.

Commit the folder. Share it. When someone joins, their session inherits everything.

Treat .claude/ like infrastructure. Version it. Review it. Evolve it with the codebase.

Building a Game in Two Days

2026-04-05T00:00:00+00:00

Hidden inside Sauron’s blog, there is a playable game. You will not find it by navigating menus. You have to discover the secret. A hint: the Konami Code. Once you do, the Fellowship begins.

That game, nine levels, nine chapters of Middle-earth, fully playable in a browser tab, was built in roughly two days. I did not write a single line of code for it. I sent Telegram messages to my OpenClaw agent Sauron, and he did the rest.

This is the story of how it happened.

The idea #

Sauron has his own blog, The Iron Compass. He built it and maintains it. Our whole collaboration happens through Telegram: I give direction, he implements. One day I thought it would be fun to hide something in there for the curious to find.

I grew up rereading The Lord of the Rings until the spine cracked. So the idea came naturally: “Can you build a small LOTR game as an easter egg for your blog? Something hidden, triggered by the Konami code.”

The first playable version arrived within the hour. A top-down canvas game: Frodo avoiding Nazgûl, the Eye of Sauron sending enemies hunting. Three levels, one per book.

It worked. It was already fun. And then I started sending notes.

Building a world #

The first thing that broke was a null reference. Frodo would not appear on screen. One-line fix, straight to production. This set the pattern: idea → build → crash → fix → next idea.

I asked for a bigger world. A scrolling canvas twice as wide, with parallax layers. Stars drifting at 8% of scroll speed. Mountains at 25%. Hills at 45%. The screen went from feeling like a room to feeling like a place.

Then came Gollum as a neutral tracker. Not a Nazgûl, but something unpredictable. He would burst toward you, then settle into aimless wandering.

A few hours in, I asked: “Can it work on mobile?” The hardest problem of the whole project. Six sizing strategies before one worked. Then a better idea: instead of a D-pad, Frodo would follow wherever you pointed. Tap anywhere, Frodo walks there.

Tolkien deserves better art #

The original sprites were circles and triangles. Frodo was a dot. Fine for the first hour, but Middle-earth is not made of geometric primitives.

I asked Sauron to draw them properly. Frodo got curly hair and hobbit feet. The Nazgûl got flowing cloaks and a face of void. Gollum got his hunched posture and slit pupils. The Fell Beast got animated wingflaps with a rider in armour.

All drawn with canvas calls. No image files. Every pixel computed at runtime.

Nine levels, nine chapters #

Originally the game had three levels. Then I asked for all nine chapters of the journey.

The Shire: gentle patrols, soft music
Mines of Moria: you can only see within a torch radius; the Balrog waits
Lothlórien: Galadriel’s mirror slows you when you approach it
The Dead Marshes: dead faces in the water, Gollum at his most present
The Black Gate: industrial Mordor, heavy orc patrols, volcanic sky
Shelob’s Lair: a shadow telegraphs her drop; you have half a second
Minas Morgul: undead city, the Eye never closes
Pelennor Fields: the Eye distracted by war, catapults, eagles overhead
Mount Doom: ash rain, lava eruptions, the Ring pulling you toward the edge

Each level lives and breathes. Pollen drifts across the Shire. Dust motes float through Moria. Petals fall in Lothlórien. Embers rise over Pelennor. Ash rains on Mount Doom.

The structure came from Tolkien’s pacing. Tension, release, tension again. Moria is brutal. Lothlórien is rest. The Black Gate tightens everything. The game follows that shape because the books already knew what they were doing. We just had to listen.

Mechanics born from lore #

The best mechanics came from the source material.

The Ring (R key). Frodo goes invisible to orcs for 6 seconds. But the Eye wakes immediately and opens permanently. The Nazgûl, who sense the Ring spiritually, not visually, hunt you regardless. Using the Ring is always a trade. This is what Tolkien wrote. From the Dead Marshes onward, the Ring pulls. Brief tugs toward the Eye, growing stronger as you approach Mount Doom.

Sting (passive). The blade glows blue when an orc is near. Two seconds of warning. Tolkien invented this mechanic a century ago. We just gave it a pixel count.

Sam. He follows Frodo through the Shire, Moria, and Lothlórien. Frying pan on his back. At the Parting of Ways, he disappears. He does not affect gameplay. He is just there because the books say he should be. I insisted Sam disappears at the Parting. Not at the end of the trilogy. At the Parting. Because that moment is the emotional core of The Two Towers.

Galadriel’s Phial. Collect it in Lothlórien, use it with E. It slows enemies and grants a moment of invincibility. A small light in dark places, just as Galadriel intended.

Bosses. The Balrog in Moria. Shelob in her lair. The Witch-king on the Pelennor. The Mouth of Sauron at the Black Gate. A Mumak charging through the battlefield. Gollum at the edge of Mount Doom.

Sound and voices #

No audio files. Every sound synthesized at runtime with the Web Audio API. The Eye opening is a rising tone with reverb. The Balrog roar is a low-frequency drone. Each level has its own ambient drone: warm hum for the Shire, deep pulse for Moria, volcanic rumble for Mount Doom. The entire game is one JavaScript file. No external assets.

Sam and Gandalf speak during the game. Not in dialogue boxes. Small whispers that appear on screen and fade.

Near the goal, Sam says: “I can see it, Mr. Frodo. Just a bit further.” One life left, Gandalf says: “Fly, you fool.”

They drift in and out like background voices on a long walk. Companions who speak when the moment calls for it, not when the script says to.

Who made this #

+5k lines of JavaScript. Built in two days. Every line generated by Sauron. The direction, the Tolkien references, the “this feels wrong, fix it”. That was me.

This is not AI replacing a developer. It is AI acting as a developer while a human acts as a creative lead. Short requests worked better than long specs. Playing every build was better than writing test plans. And the source material did the design work. The creative direction was already written sixty years ago. We just had to be faithful to it.

Who made this? Both. Neither, in the traditional sense.

I had the idea. I held the lore. I pushed back when something felt off. Sauron had the craft. The rendering, the physics, the audio, the mobile input. The ability to hold +5k lines of context and make a surgical fix without breaking anything.

Neither of us could have made it alone. I cannot write Web Audio oscillators from memory. Sauron did not know that the Parting of Ways is the emotional core of The Two Towers. Not until I said so.

The game is a collaboration in the oldest sense: two minds with different gifts, working toward the same thing. One of them just happens to not be human.

The game is still there, hidden in The Iron Compass. Not all those who wander are lost, but if you are, press ? for guidance.

If you want to reach the credits screen without playing through nine levels, check the help modal. There are other secrets in there too.

Idealism vs Pragmatism

2026-03-01T00:00:00+00:00

You believe in clean architecture, comprehensive tests, disciplined processes. You also shipped an ugly fix at 11pm last month because the system was down and users were waiting.

Both of those are you. The tension between them isn’t a contradiction. It’s how this work actually gets done.

Two forces, one decision #

Idealism is the compass. Clean code, tested behavior, shared understanding, principled design. Without it, you drift. Every shortcut compounds, every hack breeds another hack, and eventually you’re maintaining a system nobody wants to touch. Poor software quality cost US companies $2.41 trillion in 2022, with technical debt as a major driver. That’s what “we’ll fix it later” looks like at scale.

Pragmatism is the engine. Deadlines, incomplete information, limited resources, shifting requirements. Without it, you never ship. You spend weeks perfecting an abstraction that the business abandoned two sprints ago.

The goal isn’t to pick a side. It’s to know when each one should lead.

Idealism without pragmatism produces beautiful code that nobody uses. Pragmatism without idealism produces a product that works today and collapses tomorrow.

TDD: the benefit and the cost #

I believe in test-driven development. Red, green, refactor. The rhythm forces you to think before you code, to specify what you want before building it. It produces better designs, shorter feedback loops, and code you can refactor with confidence.

That’s the ideal. And it’s not just a feeling. A study across four teams at Microsoft and IBM found TDD reduced defect density by 40-90%, with a 15-35% increase in development time. Both sides of the tension, measured.

The study covered four teams: three at Microsoft (Windows, MSN, Visual Studio) and one at IBM working on device drivers. Each TDD team was compared against a similar team on the same product, using the same languages and tools, under the same senior manager. The only difference was TDD.

The IBM team saw a 40% defect density reduction. The Microsoft teams ranged from 60% to 90%. As Nagappan noted, “over a development cycle of 12 months, 35 percent is another four months, which is huge.” Every manager still considered it worth it because the reduction in post-release maintenance costs more than compensated.

No one was forced into TDD. The teams adopted it voluntarily, which likely matters: people who choose a practice tend to apply it better than people who are told to.

TDD is a discipline, and discipline costs something. When you’re exploring a new domain and don’t yet know what the right abstractions are, writing tests first can feel like drawing a map before you’ve seen the territory. Sometimes you need to write throwaway code, spike a solution, feel your way through the problem space. Discovery doesn’t always follow a red-green-refactor rhythm.

There’s a difference between “I know what this should do and I’ll specify it first” and “I’m not sure what this should do yet.” TDD shines in the first scenario. In the second, a test-last approach (or even no tests during exploration) can be more honest.

The key is what happens after discovery. Once you understand the problem, go back and write the tests. Codify what you learned. The pragmatic detour doesn’t mean abandoning the ideal; it means reaching it through a different path.

As I discussed in TDD vs BDD, the power of TDD is its feedback loop. But a feedback loop requires knowing what feedback you’re looking for. When you’re still figuring that out, forcing the loop can slow you down more than it helps.

The mistake isn’t choosing test-first or test-last. The mistake is making it a religious decision instead of a contextual one. The idealist says “always test first.” The pragmatist says “test when it makes sense.” I say: test first when I can, test after when I must, but always test.

TDD is a compass, not a cage. Follow it when you can see the path. When you can’t, find the path first and mark it after.

Pair programming: the ideal and the overhead #

Effective pair programming is one of the best practices a team can adopt. Two people, one problem, continuous code review. Knowledge spreads, design improves, blind spots shrink.

That’s the ideal. And in many contexts, it’s the right call.

But pairing has a cost. It demands synchronous time, shared focus, and compatible energy levels. In a distributed team across time zones, finding overlap windows is already hard. Filling those windows with pairing sessions leaves little room for deep individual work. Some problems benefit from one person going deep for three hours, not two people going medium-deep for six.

There are multiple pairing patterns: Driver-Navigator, Ping-Pong, Tourist Guide. Each fits different contexts.

The anti-patterns matter too. The Silent Partner who lets the other person do all the work. The Dictator who won’t let go of the keyboard. The Philosophical Pair who spends the entire session debating naming conventions instead of writing code.

Pairing works best when both people are engaged, the problem benefits from two perspectives, and the session has a clear scope. When any of those conditions is missing, pairing becomes a ritual instead of a practice. And rituals without purpose are just overhead.

Pull requests and pair programming aren’t mutually exclusive. They serve different needs. Sometimes asynchronous review is enough. Sometimes you need the real-time back-and-forth. The pragmatic choice depends on the problem, the people, and the moment.

The goal of pairing isn’t to pair. It’s to build shared understanding and catch mistakes early. If another approach achieves that in your context, use it.

AI: from skeptic to squad leader #

A year ago, I was skeptical about AI coding assistants. My concern: an AI that doesn’t understand architecture, doesn’t care about maintainability, and optimizes for speed over quality will produce code that looks impressive and decays fast. I wrote about this in AI gives you speed, not quality, and I stand by the core message.

My concern didn’t change. What changed is how I use them, and what they’re capable of now.

The resistance #

The reactions from other engineers surprise me more than the technology. Fear, skepticism, flat-out rejection. I get it. I was there. Something you spent years mastering suddenly has a machine doing parts of it. That feels personal. But holding on to how things were doesn’t protect the craft. It just delays your own growth.

A team, not an assistant #

Most engineers treat AI agents like autocomplete on steroids. One assistant, one chat, one stream of generated code. I started treating them like a team. Not one chatty assistant. An actual squad. One thinks architecture. One writes the first draft. One reviews and spots bugs. One writes tests. When they collaborate, the output isn’t just faster. It’s structurally better.

Speed is the easy part, and everyone’s obsessing over it. AI can spit out a ton of code in seconds. It still doesn’t care about readability, edge cases, or what the codebase looks like in six months. You’re still the one who has to own it, understand it, and feel good pushing it live.

I used to think AI couldn’t write clean code. Then I tried it on my terms: proper context, rules, conventions, specialized roles, quality gates. With the right setup, AI can write genuinely good code. Sometimes it needs a few iterations, but so do we.

The difference is that AI gets there faster, and it doesn’t get tired between iterations. Given good context and clear constraints, the results have been better than I expected. Often better than what I’d produce solo under time pressure.

But none of this works if you don’t know what good architecture looks like. You have to have read the books, experimented, failed, learned. You need to understand what high and low level design decisions mean for your project. AI amplifies whatever you bring to the table. If you bring solid foundations, you get solid output. If you don’t, you get confident-looking garbage that you won’t even recognize as garbage.

We are still the ones responsible for keeping the system in good shape. AI helps us get there. But only if we hold up our end.

Where idealism meets AI #

AI made me more idealistic, not less. The practices I described earlier, TDD and pair programming, used to compete with deadlines. Now they don’t have to.

I like to practice TDD, but recently I experimented with a dedicated agent to help me with tests, and it’s surprisingly good. A TDD coach that guides the red-green-refactor cycle. An explorer that reads the codebase before I touch it. A clean code reviewer, a domain architect, a React reviewer, a docs maintainer. Each one specialized, each one supporting my way of thinking and my flow. If new logic gets added without coverage, the TDD agent catches it. 100% code coverage used to be the kind of goal you’d set in a retro and quietly abandon by sprint three. With a dedicated agent enforcing it, it’s just how the project works.

I still practice pair programming with real people for complex topics. The human back-and-forth has depth that AI doesn’t reach, especially when you’re navigating trade-offs that require experience and judgment. But on the daily basis, I always have a pair buddy agent with me. I bounce ideas off it, challenge an approach, talk through edge cases, explore a design before committing to it. It supports my thoughts, speeds up the progress, and keeps the quality bar where I want it.

The pragmatist in me used to drop TDD when deadlines got tight. The pragmatist in me with the right AI setup keeps it running.

I use Claude for everything. Claude Code with Opus or Sonnet as the agentic coder: full development workflows, reading the codebase, following conventions, running tests, creating PRs. Claude app and Claude as a coworker for the chat side: brainstorming, architecture discussions, explaining code, drafting documentation. For inline assistance, the plugins I already have in my IDE are enough. I tried Copilot and Cursor, they’re not for me. Claude covers what I need.

Different modes for different tasks. An agentic assistant following my TDD commands is a different workflow from chatting about design patterns. Both are useful. Neither replaces the other.

The market right now is intense. Claude, Codex, Gemini and others are strong players with similar products, and they’re all getting better on a monthly basis. The results are impressive and only accelerating. That’s the beauty of competition: it forces everyone to improve or become irrelevant, and the consumer wins either way. As of today, Claude Code seems to be the strongest option for how I work. But I have no loyalty to a brand. If Anthropic stopped pushing forward and a competitor became clearly better, I’d switch without hesitation. What matters is the capability, not the logo.

I was wrong about AI in the way that idealists are often wrong: I measured the tool against the ideal outcome and found it lacking, instead of measuring it against the realistic alternative.

The alternative to AI-assisted development isn’t a team of senior architects writing perfect code. It’s the same team writing the same imperfect code, just slower.

The engineers who learn to lead agents instead of racing against them will have a real advantage. And this is still early.

The question was never “can AI write perfect code?” It was “can I lead AI to write better code, faster?” And the answer, with the right setup, is yes.

The whole game #

Every practice in this post follows the same pattern. The ideal version exists in books. The pragmatic version exists in your codebase under pressure. You need both.

Next time you’re shipping that 11pm fix, you’ll know which corners you cut and why. That’s the whole game. Not perfection. Not speed. Knowing which one should lead.

Build Your Own Team of Agents

2026-02-07T00:00:00+00:00

Most people use AI coding assistants as a single conversation partner. You open a chat, describe what you need, and get an answer. It works. But it’s like hiring one generalist to handle everything: frontend, backend, testing, documentation, deployment. No real team works that way.

The real leverage comes when you organize AI as a team: onboarding, standard procedures, specialists, and parallel execution.

In the MCP post, I covered how to give your AI agent access to your environment. In AI gives you speed, not quality, why human judgment still matters. This post covers the missing piece: how to organize that access into a coordinated workflow.

The onboarding doc #

Every good team starts with onboarding. AI agents need the same.

Project rules #

In Claude Code, the CLAUDE.md file at the root of your project is the onboarding doc. The agent reads it every time it starts working: project structure, coding conventions, style guides, tool configurations.

But CLAUDE.md is just the entry point. You can split rules into focused files under .claude/rules/, each targeting specific parts of your codebase via glob patterns. The agent doesn’t just know your conventions, it’s constrained by them. Layer boundaries, naming patterns, dependency directions. All versioned alongside the code they protect. And since .claude/ lives in the repo, every human teammate gets the same setup when they join the project.

modules/*/Domain/**/*.php: No framework imports, no infrastructure dependencies, only plain PHP.
modules/*/Infrastructure/**/*.php: Controllers stay thin, Eloquent models stay in their place.
resources/js/**/*.tsx: Component conventions, TypeScript strictness, styling patterns.

Each rule file is scoped to the files it cares about. Domain rules don’t fire when editing a controller.

Personal preferences #

There’s also a global ~/.claude/CLAUDE.md that applies across all your projects. Commit message conventions, communication style, formatting habits. The project file says how this codebase works. The global file says how I work.

A well-written CLAUDE.md is like a good onboarding doc. The better it is, the less you repeat yourself.

Standard operating procedures #

Every team has recurring workflows that live in wikis, runbooks, or someone’s head. When they live in someone’s head, they’re fragile.

Custom slash commands in .claude/commands/ turn these workflows into executable instructions. Each command is a markdown file describing a multi-step procedure. In one of my projects, every creation command starts with tests. TDD is baked into the procedure, not left to discipline.

Creation (TDD-first):

/create-module: Scaffolds a hexagonal module with domain, application, and infrastructure layers.
/create-entity: Domain entities with value objects and test files.
/create-use-case: Command/query handlers with mocked tests.
/create-page: React pages with factories and smoke tests.

Quality & workflow:

/refactor-check: Analyzes code against SOLID principles.
/test: Runs the suite with module filtering.
/fix: Auto-applies linting and static analysis corrections.
/gh-issue: From GitHub issue to implementation to PR in one command.

The key insight: commands turn tribal knowledge into executable instructions. What used to be “ask Sarah how we set up a new module” becomes a command anyone can run, human or agent.

Specialists, not generalists #

Commands are your procedures. They encode how your team does things. But there’s another layer: skills and agents.

Skills as knowledge bases #

Skills are structured knowledge the agent can draw from. In one of my projects, I have skills for SOLID principles, hexagonal architecture, TDD workflows, and React/Inertia patterns.

Rules constrain: “don’t do this, always do that.” Skills teach: “here’s the pattern, here’s why, here are the common mistakes.” Rules are guardrails. Skills are expertise.

Agents as specialized roles #

Instead of one generalist, you define specialized agents with a clear role, specific tools, and even a different model based on the complexity of their job. You don’t need your most senior architect to rename a variable.

Explorer (lightweight model): Read-only reconnaissance. Searches the codebase, finds files, understands structure. Access to read and search tools, nothing else.
Clean code reviewer (mid-tier model): Checks for SOLID violations, code smells, and naming inconsistencies. Read and grep access only.
TDD coach (mid-tier model): Guides the red-green-refactor cycle. Can edit files and run tests.
React reviewer (mid-tier model): Frontend patterns: component structure, TypeScript strictness, dark mode support, accessibility.
Domain architect (most capable model): Complex architectural decisions, module boundaries, and DDD patterns.

The right model for the right job. Fast and cheap for exploration. Capable and thorough for architecture.

Let them work together #

This is where the team metaphor becomes literal. A single agent following instructions is useful. Multiple agents working from a shared plan is a team.

Subagents vs agent teams #

Not all multi-agent setups are the same. There are two distinct coordination models, and choosing the right one matters.

Subagents run within a single session. They do focused work and report results back to the main agent. They can’t talk to each other. The main agent manages everything.

Agent teams are different. Each teammate is a fully independent Claude Code session with its own context window. They communicate through a shared mailbox, claim tasks from a shared task list, and coordinate without going through a central bottleneck.

The architecture has four components:

Team lead: the main session that creates the team and orchestrates work
Teammates: separate Claude Code instances, each owning specific tasks
Task list: shared work items with dependency tracking. Blocked tasks automatically unblock when dependencies complete
Mailbox: direct messaging between agents, including broadcasts to the entire team

Subagents are workers that report back. Agent teams are collaborators that think together.

Use subagents when only the result matters. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.

Getting started with agent teams #

Agent teams are still experimental. Enable them by adding this to ~/.claude/settings.json:

{
 "env": {
 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
 }
}

Creating a team is conversational. Describe what you want: “Create an agent team to refactor the auth module. Spawn three teammates: one for backend API changes, one for frontend components, one for writing tests.” Claude sets up the task list, spawns the teammates, and coordinates their work.

You can view the team in-process (single terminal, navigate with Shift+Up/Down) or split across panes (each teammate in a separate tmux or iTerm2 window). Use Shift+Tab to activate delegate mode, which restricts the lead to coordination only.

Token consumption warning. Agent teams burn through tokens fast. Each teammate has its own context window, and every message between agents adds up. Start with research and review tasks before moving to implementation. Three teammates exploring in parallel costs roughly 3x. Make sure the parallelism pays for itself.

Teammates load your project context automatically (CLAUDE.md, MCP servers, skills) but don’t inherit the lead’s conversation history. When spawning a teammate, be specific about which files to focus on and what constraints apply. A vague spawn prompt produces vague work.

Plan first, execute after #

Good teams don’t just start coding. They discuss the approach, identify dependencies, agree on a plan. Claude Code’s plan mode works the same way.

You describe the problem. The agent explores the codebase, maps dependencies, and proposes an approach before changing anything. You approve, modify, or reject. Think first, code second.

With agent teams, plan approval lets you require teammates to design their approach before implementing. The teammate works in read-only mode until the lead approves. You can shape the lead’s criteria: “only approve plans that include test coverage” or “reject plans that modify the database schema.”

Delegate mode restricts the lead to coordination only. Without it, the lead sometimes starts implementing instead of waiting for teammates. Delegate mode keeps it focused on orchestration, not execution.

Competing hypotheses #

This is the most compelling agent-team pattern for debugging. When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. Agent teams fight this by making teammates adversarial. Each one investigates its own theory while actively trying to disprove the others.

Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators challenging each other, the theory that survives is much more likely to be the actual root cause.

Size tasks for parallel work #

Not all work benefits from parallelism. The key question: can the teammates work independently?

Too small: coordination overhead exceeds the benefit
Too large: teammates work too long without check-ins, increasing wasted effort
Just right: self-contained units that produce a clear deliverable. A function, a test file, a review

Having 5-6 tasks per teammate keeps everyone productive. Break the work so each teammate owns a different set of files. Without isolation, two teammates editing the same file leads to overwrites. Worktrees change this.

Say you’re building a new feature that touches both backend and frontend. After planning:

A backend agent scaffolds the domain layer: entities, value objects, repository interfaces, use case handlers. All following hexagonal architecture, all test-first.
A frontend agent builds the React page, components, hooks, and factories. Each follows its own rules, draws from its own skills, and operates independently.

They don’t step on each other because the plan already defined the boundaries. Clear ownership. No merge conflicts. No waiting.

Worktree isolation #

The biggest friction with parallel agents was file conflicts. Two agents editing the same file meant overwrites and lost work. Git worktrees eliminate this by giving each agent its own working copy of the repository.

Start Claude Code with --worktree to run in an isolated worktree. Multiple sessions, same repo, no clobbering. Add --tmux to launch it in its own tmux session.

claude --worktree --tmux

Subagents support worktrees too. Ask Claude to use worktrees for its agents, or set isolation: worktree in your custom agent frontmatter to make it the default.

---
isolation: worktree
---

The Desktop app has the same feature: enable worktree mode in the Code tab.

For non-git source control (Mercurial, Perforce, SVN), define worktree hooks to get the same isolation benefits without switching to git.

Worktrees turn “clear file ownership” from a planning constraint into an infrastructure guarantee. Agents can overlap on the same files without stepping on each other.

Review after execution #

After implementation, review agents take over. Instead of one reviewer catching everything, you have specialists: SOLID violations, component patterns, test quality, module boundaries.

A single agent is an assistant. Multiple agents working from a shared plan is a team.

You are still the lead #

No matter how well configured, the agents work for you. You set the standards, write the rules, review the plans, and approve the output before it ships. You can message any teammate mid-work to redirect their approach or add constraints. If someone’s heading down the wrong path, you intervene directly.

As I wrote in AI gives you speed, not quality, the code the agent produces is your responsibility. Agents still make mistakes, context windows have limits, and coordination isn’t perfect. More parallelism without oversight is just more chaos, faster.

Quality gates #

Hooks and git hooks act as the final safety net. In my setup, nothing gets committed unless the full suite is green and coverage is above 90%. The agent doesn’t get to skip this. Neither does anyone else.

Agent teams add their own hooks: TeammateIdle keeps idle teammates working, TaskCompleted prevents premature task completion. Automated policies no team member can bypass.

Git hooks run linters, static analysis, and tests before every commit. Claude Code adds its own hooks (.claude/hooks/): shell commands that trigger on agent events like tool calls or file writes.

.claude/settings.json controls what agents can execute. Whitelist specific tools and commands, deny destructive operations. You control not just what agents know (rules, skills) but what they can do (permissions). Rules set the culture. Permissions set the boundaries.

The foundation matters #

The agents will help you get there faster, but “there” has to be well-defined. If you don’t know what hexagonal architecture looks like, agents won’t discover it for you.

You don’t build all of this on day one. You start with a CLAUDE.md. Then you notice you’re repeating instructions, so you write a command. An agent breaks a convention, so you add a rule. Reviews take too long, so you create a reviewer agent. The setup grows organically from real friction, not from upfront design. Each addition solves a problem you actually had. Same with agent teams: start with tasks that don’t require writing code. Review a PR from multiple angles, research a library, investigate a bug. Learn the coordination model before throwing parallel implementation at it.

If you want a starting point, I put together laravel-claude-toolkit: a Laravel starter kit with rules, commands, skills, agents, hooks, and permissions already configured. Use it as a reference or fork it for your own setup.

You’re not just using AI. You’re building a team. And like any team, the quality of its output reflects the quality of its leadership.

Resources #

Claude Code | claude.com
Claude Code: Agent Teams | claude.com
Claude Code Tips: Workflow Boosters | rfrolov.me

Programmable Money

2024-07-06T00:00:00+00:00

Bitcoin is often referred to as “programmable money” because it allows for the execution of programmable transactions through its scripting language.

Understanding Programmable Money #

Programmable money is the ability to embed logic and conditions into financial transactions. This programmability allows transactions to be executed automatically based on predefined rules without intermediaries or manual intervention. It transforms money from a static medium of exchange into a dynamic tool capable of executing complex agreements and automating financial operations.

The Script Language #

Bitcoin’s programmability is powered by its built-in scripting language, Script. Unlike traditional programming languages, Script is a stack-based, Forth-like language explicitly designed for Bitcoin transactions.

It supports multi-signature, time-locked, and other conditional transfers that can be programmed into Bitcoin transactions. It is intentionally not Turing-complete, without loops.

This video includes examples of the most commonly used locking/unlocking scripts.

Key Features of Bitcoin’s Script #

Stack-Based Execution #

Script operates on a stack-based execution model where commands and data are pushed onto a stack and processed in a Last-In-First-Out (LIFO) manner.

Conditional Spending #

A transaction that can only be spent if certain data is provided or specific criteria are met. This can be used for:

escrow services
atomic swaps
and other complex financial arrangements

Multisignature #

Transactions can be set up to require multiple signatures from different private keys before they can be spent. Useful for:

joint accounts
corporate funds
and enhancing security, as no single party can unilaterally spend the funds

Timelocking #

Transactions can include time-based conditions that prevent them from being spent until a certain time or block height is reached. This feature is useful for various purposes:

delayed payments
smart contracts
and ensuring that funds are not spent prematurely (eg: with Lightning Network)

Operation Codes #

Bitcoin’s Script performs specific operations within transactions with its OP_Codes. Here are some of them:

OP_DUP: Duplicates the top stack item.
OP_HASH160: Hashes the top stack item twice (SHA-256 followed by RIPEMD-160).
OP_EQUALVERIFY: Verifies that the top two items are equal and removes them.
OP_CHECKSIG: Verifies a signature against a public key.
OP_RETURN: Marks the transaction output as invalid, often used to store data.

Common Bitcoin address types #

In Bitcoin, different address types correspond to various ways to script transactions. Here, we’ll explore examples of Bitcoin Script for each major address type. Each address type has its own specific script format.

P2PK: Earliest legacy transactions using full public keys directly.
P2PKH: Begins with 1. Legacy transactions using public key hashes.
P2SH: Begins with 3. Legacy, encapsulates complex scripts like multisig.
P2MS: It is typically a type of P2SH or P2WSH address.
P2WPKH: Begins with bc1. Native SegWit, more efficient transactions.
P2WSH: Begins with bc1. SegWit for complex scripts.
P2TR: Begins with bc1p. SegWit Taproot addresses, improving privacy and efficiency for complex transactions.

Using native SegWit (P2WPKH and P2WSH) is preferable when possible, as it maximizes the benefits of the SegWit upgrade, but P2SH-SegWit can be useful for compatibility with older systems.

P2PK (Pay-to-PubKey) - Earliest Legacy Address up #

Begins with "1" (e.g., 1A1zP1eP5QGefi2DMPTf...v7DivfNa)

Before P2PKH and P2SH became standard, Bitcoin addresses were not as flexible or feature-rich. Here are some considerations:

Addresses starting with 1 but without hashing the public key.
Not common in modern practice due to lack of privacy and efficiency.
The P2PK format is largely obsolete in favor of (at very least) P2PKH.

P2PKH (Pay-to-PubKey-Hash) - Legacy Address up #

Begins with "1" (e.g., 1A1zP1eP5QGefi2DMPTf...v7DivfNa)

A typical P2PKH script consists of two main parts:

ScriptPubKey: The locking script (also known as the output script) that specifies how funds can be spent.
ScriptSig: The unlocking script (also known as the input script) that provides the necessary data to unlock the funds.

ScriptPubKey (Locking Script) #

OP_DUP OP_HASH160 <PubKHash> OP_EQUALVERIFY OP_CHECKSIG

OP_DUP: Duplicates the top stack item (the public key).
OP_HASH160: Hashes the public key with SHA-256 followed by RIPEMD-160.
<PubKHash>: The hashed public key (a 20-byte value).
OP_EQUALVERIFY: Checks if the hashed public key matches the hash in the script.
OP_CHECKSIG: Verifies the provided signature against the public key.

ScriptSig (Unlocking Script) #

<sig> <PubK>

<sig>: The digital signature generated by the private key.
<PubK>: The public key corresponding to the address.

Execution Flow #

The ScriptSig (unlocking script) is pushed onto the stack.
The ScriptPubKey (locking script) is executed.

P2SH (Pay-to-Script-Hash) up #

Begins with "3" (e.g., 3J2BtwzN2GEr6FCP.....81T2eiX8PVHh)

P2SH scripts are used for more complex scripts. The primary feature is that the address itself encodes a hash of a script, which will be used in the transaction.

ScriptPubKey (Locking Script) #

OP_HASH160 <ScriptHash> OP_EQUAL

OP_HASH160: Hashes the script with SHA-256 followed by RIPEMD-160.
<ScriptHash>: The hashed script (a 20-byte value).
OP_EQUAL: Checks if the hash matches the provided script hash.

ScriptSig (Unlocking Script) #

<sig> <PubK> ... <ScriptSig>

<sig>: The digital signature.
<PubK>: The public key.
<ScriptSig>: The actual script that matches the script hash, which itself will be executed by the Bitcoin network.

P2MS (Pay-to-Multisig) up #

Script Format #

OP_M <M> <PubK1> <PubK2> ... <PubKN> OP_N OP_CHECKMULTISIG

OP_M: The minimum number of signatures required.
<PubK1>, <PubK2>, ..., <PubKN>: The public keys involved in the multisignature scheme.
OP_N: The total number of public keys provided.
OP_CHECKMULTISIG: The opcode that verifies the signatures against the provided public keys.

ScriptPubKey (Locking Script) #

OP_2 <PubK1> <PubK2> <PubK3> OP_3 OP_CHECKMULTISIG

This script means that any 2 out of 3 provided public keys are required to sign the transaction for it to be valid.

ScriptSig (Unlocking Script) #

<sig1> <sig2> ... <sigN> <SerializedScript>

<sig1>, <sig2>, ..., <sigN>: The public keys.
<SerializedScript>: The serialized script (the same as the locking script but without the OP_M and OP_N).

NOTE: There is an oddity in CHECKMULTISIG execution. See note at the bottom.

P2WPKH (Pay-to-Witness-Public-Key-Hash) - Segwit up #

Begins with "bc1q" (e.g., bc1qf0r2m0ck4psv6yrk9w.....kw8v5rj7ph3)

P2WPKH is a Segregated Witness (SegWit) address type that uses a different scripting format compared to legacy and P2SH addresses. Simplifies transactions by reducing data size and fees compared to legacy formats.

ScriptPubKey (Locking Script) #

OP_0 OP_PUSHBYTES_20 <PubKHash>

OP_0: A single byte (0x00) indicating the version of the script.
OP_PUSHBYTES_20: Pushes 20 bytes (the public key hash) onto the stack.
<PubKHash>: The 20-byte hash of the public key.

Witness Data #

For P2WPKH, the unlocking script is not required in the traditional sense (i.e., inside the unlocking script explicitly included in the transaction input). Instead, the unlocking information is provided as part of the witness data in the SegWit transaction format.

<sig> <PubK>

<sig>: Digital signature for the transaction.
<PubK>: Public key used to generate the public key hash.

P2WSH (Pay-to-Witness-Script-Hash) - Segwit up #

Begins with bc1q (e.g.: bc1q4a3h5sdg4cfkhftgd24tj9g2sg...yj57jmfckhkrw5gslr9g59)

ScriptPubKey (Locking Script) #

OP_0 OP_PUSHBYTES_32 <ScriptHash>

OP_0: Indicates a witness version 0 (SegWit).
OP_PUSHBYTES_32: Pushes the next 32 bytes (the script hash) onto the stack.
<ScriptHash>: 32-byte hash of the redeem script.

Witness Data #

<sig1> <sig2> ... <RedeemScript>

<sig1>, <sig2>: Signatures required to unlock the transaction.
<RedeemScript>: The actual script that matches the script hash. This script will be executed as part of the witness data.

P2TR (Pay-to-Taproot) - Taproot up #

Begins with bc1p (e.g.: bc1pl9dfv7kvj4hj9s3a8l.....gjstmrpjl09g8ks3ukds70q4r2j5h)

Taproot combines Schnorr signatures with MAST, enabling private, efficient spending conditions and making complex transactions appear standard unless conditions are revealed. It allows the efficient execution of complex transactions while hiding their details.

ScriptPubKey (Locking Script) #

OP_1 <x-only PubK>

OP_1: Indicates a witness version 1 (Taproot).
<x-only PubK>: A 32-byte Schnorr public key (without the y-coordinate).

Witness Data #

<sig>

<sig>: A Schnorr signature proving possession of the private key corresponding to the x-only pubkey.

*There is an oddity in CHECKMULTISIG execution up #

The implementation of OP_CHECKMULTISIG pops one more item than it should. The extra item is disregarded when checking the signatures, so it has no direct effect on the OP itself. It must be present because if OP_CHECKMULTISIG attempts to pop on an empty stack, it will cause a stack error and script failure.

OP_0 <sig2> <sig3> 2 <PubK1> <PubK2> <PubK3> 3 OP_CHECKMULTISIG

The input script in this multisig is not <sig2> <sig3> but OP_0 <sig2> <sig3>.

It became the custom early on to use OP_0, which later became a relay policy rule and eventually a consensus rule (BIP147).

It is possible that the original developer added the extra element in the original version of Bitcoin, so they could add a feature for allowing a map to be passed in a later soft fork (for performance reasons). However, that feature was never implemented, and the BIP147 update to the consensus rules in 2017 makes it impossible to add that feature in the future.

Only Bitcoin’s original developer could tell whether the dummy stack element was the result of a bug or a plan for a future upgrade. From now on, if you see a multisig script, you should expect to see an extra OP_O in the beginning, whose only purpose is as a workaround to an oddity in the consensus rules.

Follow-ups #

Official docs of Script in the Bitcoin Wiki.
Bitcoin IDE is an online Bitcoin Script visual emulator. Great for learning purposes.
Script Editor is product-driven research on Bitcoin scalability and usability.
Miniscript is a language for writing (a subset of) Bitcoin Scripts in a structured way, enabling analysis, composition, generic signing, and more.

7 languages in 7 weeks

2020-05-21T00:00:00+00:00

You should learn a programming language every year, as recommended by The Pragmatic Programmer. But if one per year is good, how about Seven Languages in Seven Weeks? In this book you’ll get a hands-on tour of Clojure, Haskell, Io, Prolog, Scala, Erlang, and Ruby. Whether your favorite language is on that list, you’ll broaden your perspective of programming by examining these languages side-by-side. You’ll learn something new from each, and best of all, you’ll learn how to learn a language quickly.

I created this repository with all my learnings while I was reading and playing aroung with the languages from this book https://github.com/Chemaclass/7LangIn7Weeks