Forem: Adrien Cossa

Installing OpenClaw the Easy Way

Adrien Cossa — Mon, 16 Mar 2026 16:34:05 +0000

I started installing OpenClaw manually — reading through the docs, figuring out each step, hitting the usual walls. It was taking too long, so I stopped and decided to try a different approach. So instead of repeating the process, I wrote a skill for it: a set of instructions and references that lets an AI coding agent handle the whole thing. This is the skill-driven development approach I described in a previous post — let the agent do the work, fix the skill when it gets something wrong, repeat until it gets it right.

The result is a skill that handles the full installation and configuration of OpenClaw on a VPS. You tell your agent "set up OpenClaw on my server" and it walks through everything: provisioning, hardening, messaging channels, backups. The skill encodes the gotchas so you don't have to hit them yourself.

What you get

With the skill loaded, setting up OpenClaw goes roughly like this:

"Set up OpenClaw on my new Hetzner server"

The agent asks a few questions — SSH access details, which messaging channels you want, which model providers you have API keys for — then works through the phases in order. It handles:

Server provisioning — SSH setup, initial access
OS hardening — UFW firewall, Fail2Ban, SSH lockdown
Disk encryption — LUKS full-disk or encrypted block storage volumes
Runtime installation — Node.js, Python, build tools
OpenClaw installation — clone, configure, systemd service
Model configuration — API keys (Anthropic, OpenAI, etc.) or local Ollama
Messaging channels — Signal, Telegram, WhatsApp, Discord, and others
Multi-agent routing — different agents for different contacts
Remote access — Cloudflare Tunnel, Tailscale, or Caddy reverse proxy
Docker sandboxing — container isolation with proper firewall rules
Backups — local snapshots, GitHub push, cloud provider images
Social media integration — optional, third-party schedulers
Ongoing maintenance — updates, log rotation, health checks

At each step, the agent adapts to your choices. Pick Telegram instead of Signal? The Signal-specific build steps get skipped. Want Tailscale instead of Cloudflare Tunnel? Different config, different verification. The skill describes the trade-offs; the agent presents them and moves on.

Without the skill, an agent can still attempt all of this — the information exists in OpenClaw's docs and platform-specific guides. But it takes hours of trial and error, and several of the issues below are genuinely hard to figure out from scratch.

Issues the skill handles for you

These are the problems that came up during the SDD loop — things the agent got wrong, that I fixed in the skill, and that you won't have to deal with.

Docker bypasses UFW

This one is not well-known. When Docker publishes a port, it writes its own iptables rules that bypass UFW entirely. Your firewall says "deny all incoming," but Docker's containers are wide open anyway.

The skill includes explicit DOCKER-USER chain rules that block all inbound connections to containers unless they come from loopback (127.0.0.1) or your Tailscale CGNAT range (100.64.0.0/10). Without this, any container you run is exposed to the internet regardless of your UFW config.

Signal on ARM64 has no pre-built binary

If you're running on an ARM64 VPS (Hetzner CAX series, for example), signal-cli's libsignal JNI binding doesn't have a pre-built binary. You have to clone the signal-cli repo and build libsignal from Rust source yourself. This requires openjdk-25-jre-headless, build-essential, cmake, libclang-dev, protobuf-compiler, and rustc — a dependency chain that takes a while to sort out.

The skill documents the exact build steps and dependencies. Without it, the agent installs signal-cli, it silently fails at runtime, and you spend a while figuring out why.

Secrets end up in config files

Left to its own devices, the agent will store API keys in environment files or config files because it's the fastest path. The skill enforces storing all secrets in pass (the standard Unix password manager) and reading them at runtime. No API keys in plain text, ever.

Services "started" but not actually running

A common agent failure: it runs systemctl start openclaw, gets no error, and declares the phase complete. But the service might have crashed immediately after starting, or it might be listening on the wrong port, or a dependency might be missing.

The skill marks verification as (Non-Negotiable) — the agent must confirm each service actually responds via HTTP before moving on. This single rule prevented most of the false-completion issues during the SDD loop.

Disk encryption on a cloud VPS

LUKS full-disk encryption on a cloud VPS isn't straightforward. You need to boot into rescue mode, set up cryptsetup, and install dropbear-initramfs so you can unlock the disk remotely after every reboot. The skill documents this path but also offers a simpler alternative: Hetzner encrypted block storage volumes for sensitive data only, which avoids the rescue-boot complexity for most use cases.

Remote access done wrong

Exposing ports directly to the internet is the default instinct, but it's the wrong one. The skill requires one of three approaches: Cloudflare Tunnel (outbound-only, Zero Trust), Tailscale Serve (private mesh), or Caddy reverse proxy with password auth. Each has documented trade-offs. The agent asks which one you prefer and configures it accordingly.

How the skill is structured

The main SKILL.md file is around 160 lines and covers the decision flow and ordering constraints. Detailed procedures live in reference files that the agent pulls in as needed:

Reference	What it covers
Security hardening	SSH config, UFW rules, Fail2Ban jails, Docker iptables bypass
Local models	Ollama installation, model selection by RAM, GPU passthrough
Messaging channels	Per-channel setup (Signal ARM64 build, WhatsApp QR pairing, Telegram BotFather)
Multi-agent routing	Contact-to-agent bindings, DM access policies, agent personalities
Remote access	Cloudflare Tunnel vs Tailscale vs Caddy — trade-offs and setup
Social media	Third-party schedulers, risk considerations
Backups	Local snapshots, GitHub push with deploy key, cloud provider images

This progressive disclosure keeps context usage reasonable. The full Signal ARM64 build instructions only get loaded if you're actually setting up Signal on ARM64.

Limitations

The skill isn't tied to a specific setup. It asks what you're working with — VPS or local machine, which OS, which architecture, which provider — and adapts accordingly. It can fetch current VPS pricing (Hetzner CAX series, DigitalOcean, etc.) so you can compare options before committing. If you want to run OpenClaw on a spare laptop instead of a cloud server, it adjusts the flow — no VPS provisioning, different networking, local Ollama instead of cloud API keys.

That said, my own setup (Hetzner ARM64, Ubuntu 24.04) is the only tested path so far. Other combinations should work but may have gaps in the gotcha coverage.

The skill is also a snapshot as of early 2026. OpenClaw is actively developed. Signal might ship ARM64 binaries eventually. Docker might fix the UFW bypass. Treat specific version numbers with appropriate skepticism.

And while the skill handles the setup, it doesn't replace understanding what's running on your server. If something breaks outside the skill's playbook, you'll need basic comfort with SSH, firewalls, and systemd to debug it.

Getting it

npx skills add https://github.com/souliane/skills --skill ac-openclaw -g -y

It works with any AI agent that can read files and run commands.

OpenClaw | MIT License

Skill-Driven Development: Transferring your Craft to AI Agents

Adrien Cossa — Fri, 13 Mar 2026 16:40:28 +0000

Every project has its own way of doing things — migration patterns, transaction handling, deployment quirks, that one PDF template workflow nobody wants to touch. I've been writing this stuff down as markdown files with helper scripts so my AI agent can follow along. I've taken to calling this skill-driven development (building on agent skills, a convention that started with Anthropic's Claude Code and has since been adopted by several other AI coding agents).

This post walks through some skills I've put together and shows the feedback loop that makes them worth maintaining.

What skills add over a README

A project README or an AGENTS.md can capture conventions. The skills I've been writing try to go a bit further:

Progressive disclosure — a slim main file loads first, with detailed references pulled in only when needed. This keeps the agent's context window focused.
Composability — skills declare dependencies and load together. A Django skill + a project overlay skill + a TDD skill compose into a complete workflow.
Scripts — skills can ship executable scripts alongside the instructions. A script the agent calls is more reliable than a 15-step procedure the agent interprets.
Self-improvement — when something goes wrong, the fix goes into the skill. Next session, the agent follows the updated instructions.

That last point is what makes it worth maintaining: every correction you make goes into the skill, and the agent doesn't make the same mistake twice.

The SDD loop

There's a useful parallel with Test-Driven Development:

	TDD	SDD
Write	Write the test first	Write the skill first
Run	Run the code	Let the agent produce the code
Evaluate	Test fails → fix the code	Output is wrong → fix the skill
Loop	Until green	Until the agent gets it right

In TDD, you iterate on code until the tests pass. Here, you iterate on skills until the agent's output is what you wanted. The skill isn't a one-shot handoff — you keep tweaking it as you find gaps.

In practice, the two aren't separate activities — skills encode TDD as part of the workflow. The implementation skill says "write a failing test first, then implement," and the agent does both. Nobody writes tests by hand and then separately invokes a skill; the skill is what makes the agent follow TDD.

When tests fail, it's worth asking whether the code is wrong or the skill is incomplete. Fix the skill, re-run. Over time it adds up — each fix prevents one class of mistake, and after enough sessions you've built up a decent set of guardrails just from things that went wrong.

If you use teatree (a set of lifecycle skills I put together for multi-repo development), this loop can be automated: t3-retro runs a retrospective after each session and writes fixes into the skill files. But it works just as well manually — whenever you correct the agent, you can put that correction in a skill so it sticks.

What a skill looks like

A skill is a markdown file (SKILL.md) with YAML frontmatter, often accompanied by scripts for the mechanical parts. Here's a simplified example of the markdown side:

---
name: ac-django
description: Django coding conventions and best practices.
requires: []
metadata:
  version: 0.2.0
---

# Django Conventions

## Models

### Fat Models Doctrine
- Business logic belongs in models, not views or serializers.
- Use model managers for complex queries.

### Migrations
- Always use `apps.get_model()` in data migrations — never import directly.
- Set `elidable=True` on data-only migrations.
- Include both `forwards` and `backwards` functions.

## Settings

### Storage Configuration (Non-Negotiable)
- Use `STORAGES` dict (Django 4.2+), not `DEFAULT_FILE_STORAGE`.
- The deprecated setting causes silent failures on deployment.

Rules marked (Non-Negotiable) are things I've learned the hard way. "Always verify services respond via HTTP before declaring running" sounds obvious, but without it, the agent will say "servers started" without checking whether anything actually came up.

These work with any agent that can read files — Claude Code, Codex, Cursor, whatever. The agent reads the skill and follows the instructions.

What's in the repo

I've put the generic ones in a public repository in case any of them are useful to others. Here are the ones I'd recommend looking at first.

`ac-reviewing-skills` — keep your skills in shape

This is probably the most broadly useful one. It does a deep audit of your skill files — architecture, content quality, script correctness, stale cross-references, duplicated guidance. I run it periodically and it consistently finds things I missed: rules that drifted between files, references pointing at renamed sections, scripts with missing error handling. If you maintain more than a handful of skills, it's worth running periodically.

`ac-django` — Django conventions that models already "know" but get wrong

The agent knows Django. It doesn't know how you use Django. This skill covers the mistakes I kept correcting: outdated migration patterns (apps.get_model() vs direct imports), unsafe transaction handling, the STORAGES dict vs deprecated DEFAULT_FILE_STORAGE, post_migrate signal timing for permission assignments. It's a reference, not a tutorial — it assumes the agent already understands the framework and just needs guardrails for the non-obvious parts.

ac-python is its companion for generic Python: style, typing, OOP patterns, testing conventions. Less opinionated, but useful as a baseline.

`ac-adopting-ruff` — structured linter migration

A step-by-step playbook for replacing black + isort + flake8 with ruff, one rule category per MR. It handles the things I got stuck on — conflicting formatter settings, rule equivalences between linters, the unfixable vs ignore distinction. Doing it in one big MR is painful; the skill breaks it into reviewable increments.

`ac-openclaw` — self-hosted AI assistant setup

An interactive guide to install OpenClaw on a VPS or local machine. Covers server provisioning, OS hardening, model configuration (BYOK or local Ollama), messaging channel integration (Signal, WhatsApp, Telegram, etc.), and secure remote access (Cloudflare Tunnel, Tailscale, or Caddy). It walks through every decision point — useful if you want a self-hosted personal AI assistant without piecing together a dozen tutorials.

Everything else

Skill	What it covers
`ac-python`	Generic Python: style, typing, OOP design, testing, tooling
`ac-editing-acroforms`	AcroForm PDF templates: widget geometry, content streams, font subsetting
`ac-auditing-repos`	Cross-repo infrastructure audit: harmonize pre-commit, linter, and editor configs
`ac-writing-blog-posts`	Article writing + social media promotion + dev.to publishing pipeline
`ac-generating-slides`	Markdown to presentation slides via Marp
`ac-scaffolding-skill-repos`	Scaffold new skill repos with correct config and structure

ac-editing-acroforms deserves a mention — it came out of editing PDF form templates by hand. The internals (annotation dictionaries, appearance stream generation, widget flags) are barely documented. The agent can't figure this out from training data alone, so the skill ships with Python scripts that handle the tricky bits.

This blog post was written with ac-writing-blog-posts, for what it's worth.

How to use them

Install with npx skills:

npx skills add https://github.com/souliane/skills --skill '*' -g -y

This installs all skills globally for your default agent. To install for multiple agents at once:

npx skills add https://github.com/souliane/skills --skill '*' -g -y \
  --agent claude-code codex cursor github-copilot

If you want the SDD feedback loop — where retrospective fixes land in files you can commit — clone the repo and symlink it into your agent's skills directory:

git clone git@github.com:souliane/skills.git ~/workspace/souliane/skills

# Example for Claude Code — adjust the target for your agent runtime
for skill in ~/workspace/souliane/skills/ac-*/; do
  ln -s "$skill" ~/.claude/skills/"$(basename "$skill")"
done

This points your agent at the live git checkout directly. When the agent (or you) updates a skill file, the change is immediately available in the next session and can be committed. Don't use npx skills add for this — it creates a managed copy that doesn't point back to your clone.

If you use teatree, its setup wizard can suggest these as companion skills for your project overlay — they're loaded automatically when you work in matching repos.

When it helps

Skills work best when:

You correct the agent for the same kind of mistake more than once
Your project has conventions that diverge from common patterns
You work across sessions and the agent keeps losing context
You use deterministic tools (PDF editors, linters, deployment scripts) where the agent needs exact steps
You want to share a recipe with others — a skill is a portable, self-contained package that anyone can install and use with their own agent

They're less useful for one-off tasks or when the model's defaults already match your preferences. But even something you only do once yourself might be worth writing as a skill if it's useful to someone else.

These skills reflect my own workflow — Django, Python, PDF templates, multi-repo infrastructure. They might not match yours at all. The most useful skills are probably ones you'd write yourself for your own project's conventions. These are just examples of what worked for me.

GitHub | MIT License

Introducing Teatree: Parallel Multi-Repo Development with AI Agents

Adrien Cossa — Thu, 12 Mar 2026 13:16:50 +0000

I'm a Customer Success Engineer at Oper Credits. My daily work involves a multi-repo project — backend, frontend, translations, configuration — and I use AI coding agents constantly. The friction isn't writing code; agents handle that well. It's everything surrounding it: following different conventions across codebases, coordinating changes across services, managing local environments that diverge from what's in git, and encoding the workflow patterns we could all benefit from.

The agent can figure out most of these things, but it struggles with the specifics — it loops on troubleshooting, tries approaches that don't match the project's actual setup, and burns tokens on trial and error. I started putting together teatree to write down that knowledge so the agent doesn't have to rediscover it every session. It's also a way to define and automate your personal workflow without adding friction with your team — build it on your own, then push for adoption once it works.

This post walks through the architecture, the design choices I landed on, and how the pieces fit together. It's long because there's a lot of ground to cover. If you just want the quick pitch, the README has that.

What it looks like
The problem
Skills as markdown and scripts
The lifecycle graph
Multi-repo worktree management
The overlay and extension system
Auto-loading hooks
The retrospective loop
Companion skills
Getting started
When it helps (and when it doesn't)

What it looks like

Tell your AI agent what you want. Teatree skills guide it through the entire lifecycle:

https://gitlab.com/org/repo/-/issues/1234

The agent fetches the ticket, creates synchronized worktrees, provisions isolated databases and ports, implements the feature with TDD, writes a test plan, runs E2E tests, self-reviews, then pushes and creates the merge request.

Fix PROJ-5678

The agent fetches the failed test report from CI, reproduces locally, fixes, pushes, and monitors the pipeline until green.

Review https://gitlab.com/org/repo/-/merge_requests/456

The agent fetches the ticket for context, inspects every commit individually, and posts draft review comments inline on the correct file and line.

Run the test plan for !789

The agent generates a test plan from the MR changes, runs E2E tests, and posts evidence screenshots on the MR.

Follow up on my open tickets

The agent batch-processes your assigned tickets, checks CI statuses, nudges stale MRs, and starts work on anything that's ready.

The problem

AI coding agents can do a lot — reason about architecture, run tests, create merge requests. But without your project's specific context, they spend tokens and time rediscovering things you already know. Your repo layout, your CI conventions, your team's practices, your local tooling — none of that is in training data.

The friction is especially pronounced with:

Multi-repo setups — creating branches across 3+ repos for a single ticket, provisioning isolated databases, allocating non-conflicting ports
Atypical local environments — personal tooling that differs from what's in git, dev configurations the team hasn't adopted yet
Operational workflows — self-reviewing before pushing, creating properly formatted merge requests, monitoring pipelines, running retrospectives

The agent can attempt all of these. But without explicit guidance, it either asks twenty questions or confidently does the wrong thing — and when something fails, it loops instead of applying the fix you already know.

I tried shell scripts and aliases first, sometimes Python scripts too. They worked for the happy path but couldn't handle edge cases — the database import that fails because VPN is down, the port conflict because another worktree is still running, the CI format check that rejects your MR title. A shell script can't say "if the test fails, check if it's a known flake — here are the patterns." An AI agent can.

So I started writing this stuff down — as markdown instructions with tested Python and shell scripts for the mechanical parts. The markdown gives the agent enough context to handle edge cases; the scripts handle deterministic operations where you don't want the agent improvising.

Skills as markdown and scripts

A teatree skill starts with a markdown file (SKILL.md) with YAML frontmatter, but the heavy lifting often happens in scripts that ship alongside it. Teatree currently has 15 Python executables, 9 library modules, and 3 shell scripts — backed by 26 test files. Here's a simplified example of the markdown side:

---
name: t3-code
description: Writing code with TDD methodology.
requires:
  - t3-workspace
metadata:
  version: 0.0.1
---

# Writing Code (TDD)

## Dependencies

- **t3-workspace** (required) — provides dev servers for live reload.

## Workflow

### 1. Plan First (Non-Negotiable)

Always make a plan before writing code. Never jump straight to coding.
- Identify scope: which files, modules, and repos are affected.
- Review existing patterns in the codebase before writing new code.

### 2. TDD Cycle

Write failing test → Implement → Green → Refactor

### 3. Follow Conventions

- Language/framework conventions from the project's convention skills.
- Repository-specific patterns take precedence over generic guidance.

A few things to note:

Skills contain both instructions and scripts. The markdown tells the agent when and why to do things. The Python scripts handle deterministic operations: worktree creation, port allocation, database provisioning, branch finalization. A script the agent calls is more robust than a 15-step procedure in a markdown file. Instructions for judgment calls, scripts for mechanical work.

Skills declare dependencies. The requires: field in the frontmatter tells the loading system which other skills need to be present. When t3-code is loaded, t3-workspace comes along automatically. This eliminates wasted round-trips where the agent reads a skill, sees "Load /t3-workspace now", and then has to make a second call.

Skills use progressive disclosure. Most SKILL.md files are 80–160 lines, with detailed procedures in references/ files that the agent reads on demand. This keeps the typical skill set well within a reasonable context budget.

Skills have rules marked (Non-Negotiable). These are things I've had to learn the hard way. "Always verify services respond via HTTP before declaring running" sounds obvious, but without it, the agent will say "servers started" without checking whether anything actually came up.

The lifecycle graph

Teatree organizes development into phases, each handled by a dedicated skill:

The flow is: ticket → code → test → review → ship → retro, with t3-workspace providing infrastructure to all phases and t3-debug available whenever something breaks.

Here's what each skill does:

Skill	Phase	What it handles
`t3-setup`	Bootstrapping	Interactive setup wizard, health checks, overlay scaffolding
`t3-workspace`	Infrastructure	multi-repo worktrees, port allocation, DB provisioning, env files, dev servers, cleanup
`t3-ticket`	Intake	Fetch the issue, extract acceptance criteria, detect affected repos, detect tenant/variant, create worktrees
`t3-code`	Implementation	Plan-first workflow, TDD cycle, convention enforcement, feature flag checks
`t3-test`	Verification	Test execution, CI interaction, E2E test plans, quality gates
`t3-debug`	Troubleshooting	Systematic 5-phase debugging protocol, user-hint-first investigation
`t3-review`	Code review	Self-review checklist, giving review, receiving feedback
`t3-ship`	Delivery	Commit formatting, branch finalization, MR creation, pipeline monitoring
`t3-review-request`	Notifications	Post MR links to review channels, check for duplicate requests
`t3-retro`	Improvement	Conversation audit, root cause analysis, skill updates, privacy scans
`t3-contribute`	Contribution	Push skill improvements to fork, open upstream issues
`t3-followup`	Batch ops	Process assigned tickets, check CI statuses, nudge stale MRs

The skills mirror how development actually works. Implementing a ticket touches intake, coding, testing, review, and delivery — often across multiple repos. Making the skills fully independent would mean duplicating knowledge across every one of them, which always diverges over time.

The follow-up dashboard

One skill worth highlighting is t3-followup. It runs your daily routine: batch-processing new tickets, checking CI statuses, advancing tickets through their lifecycle, and nudging reviewers about stale MRs.

As it works, it builds a persistent cache (followup.json) of all in-flight work — tickets, merge requests, pipeline statuses, review request states, and review comment tracking. From that cache, it generates an HTML dashboard:

The dashboard gives you a single view of everything that's in flight: ticket lifecycle status, pipeline results (color-coded pills), review request state, and tracked review comments. Everything is a clickable link — tickets, MRs, CI pipelines, Slack messages — so you can jump directly into any conversation.

The cache is a plain JSON file, so project overlays can inject extra fields (external tracker status, deployment state, tenant info) via the followup_enrich_data extension point. Stale tickets are purged automatically after their MRs have been merged for 14 days (configurable via T3_FOLLOWUP_PURGE_DAYS).

Multi-repo worktree management

This is where I started, and it's the feature I use most.

Suppose your project has three repos: acme-backend, acme-frontend, and acme-translations. You're about to work on ticket PROJ-1234. Running t3_ticket PROJ-1234 creates this structure:

Each ticket gets its own directory containing one git worktree per affected repo — lightweight checkouts that share the .git directory with the main clone but have their own branch and working tree. A shared .env.worktree file provides allocated ports, database name, and variant configuration.

After creating the worktrees, t3_setup provisions the environment:

Symlinks — .venv, node_modules, .python-version, and configurable shared directories are symlinked from the main repo (so you don't reinstall dependencies for every worktree)
Environment files — .env.worktree with unique ports, database URL, variant-specific overrides
Database — creates an isolated DB, imports from a snapshot or dump, runs migrations
direnv — auto-loads environment variables when you cd into the worktree
Frontend dependencies — installs if the lockfile changed

Then t3_start brings everything up: Docker services, migrations, backend server, frontend dev server. Each worktree is fully isolated — its own database, its own ports, its own services. You can have ticket 1234 and ticket 5678 running simultaneously without conflicts.

Why this matters

Without isolation, the most common failure is contamination between tickets. You're working on ticket A, make a database change, then switch to ticket B which expected the old schema — migrations fail, the frontend shows stale data, and you spend time figuring out what went wrong. Worktree isolation avoids this. Each ticket is a clean room.

The other benefit is parallelism. While waiting for CI on ticket A, start working on ticket B in a completely separate environment. No branch switching, no stashing, no "wait, which database am I pointing at?"

Multi-tenant awareness

If your project serves multiple tenants — each with their own configuration, feature flags, and sometimes database — teatree handles that too. The variant system (wt_detect_variant) auto-detects the target tenant from ticket labels, descriptions, or external trackers, then provisions tenant-specific databases, environment variables, and configuration. Feature flag checks during code review ensure changes are properly scoped per tenant.

The project overlay wires in your tenant-to-variant mapping; teatree handles the rest. This means "set up a worktree for ticket X" automatically produces an environment configured for the correct tenant — no manual env file editing, no guesswork about which tenant you're in.

Why `t3_ticket` instead of raw git commands

The convention is <ticket>/<repo>/ — a ticket directory containing worktrees. Raw git worktree add creates flat worktrees at whatever path you give it, which breaks the ticket-directory structure that every other tool expects. t3_ticket enforces the convention, handles branch naming (with your prefix), and creates worktrees across all affected repos in one call. The skill file marks this as (Non-Negotiable) because flat worktrees cause subtle breakage downstream.

The overlay and extension system

Teatree knows how to create worktrees, allocate ports, and orchestrate a development lifecycle. It doesn't know how to start your backend, import your database, or create your merge requests. That project-specific knowledge lives in a project overlay.

The three-layer architecture

When teatree needs to do something project-specific (start the backend, import a database, create an MR), it calls an extension point through a registry. The registry resolves the implementation using a 3-layer priority:

Priority	Layer	Source	Example
Highest	Project	Your overlay's `project_hooks.py`	`t3_start` that runs Docker + Django + Angular
Middle	Framework	Framework integration (e.g., Django)	`wt_post_db` that runs `manage.py migrate`
Lowest	Default	Teatree core fallback	Usually a no-op or "not configured" message

The registry itself is simple — 45 lines of Python:

_LAYERS = ("default", "framework", "project")
_LAYER_RANK = {layer: i for i, layer in enumerate(_LAYERS)}
_registry: dict[str, list[tuple[str, Callable]]] = {}

def register(point: str, fn: Callable, layer: str = "default") -> None:
    entries = _registry.setdefault(point, [])
    entries[:] = [(lyr, func) for lyr, func in entries if lyr != layer]
    entries.append((layer, fn))
    entries.sort(key=lambda x: _LAYER_RANK[x[0]])

def get(point: str) -> Callable | None:
    entries = _registry.get(point)
    if not entries:
        return None
    return entries[-1][1]  # highest priority = last entry

def call(point: str, *args, **kwargs):
    fn = get(point)
    if fn is None:
        raise KeyError(f"No handler registered for extension point {point!r}")
    return fn(*args, **kwargs)

Registering a handler at the "project" layer automatically overrides anything at "framework" or "default". The framework layer is there so teatree can ship framework integrations (Django is the first) that work out of the box but can still be overridden by project-specific needs.

What an overlay looks like

A project overlay is a directory with this structure:

acme-overlay/
├── SKILL.md                    # Skill description + loading order
├── scripts/
│   └── lib/
│       ├── bootstrap.sh        # Shell wrappers (sourced after teatree)
│       ├── shell_helpers.sh    # Env loading, variant detection
│       └── project_hooks.py    # Extension point overrides
├── hook-config/
│   ├── context-match.yml       # Patterns that trigger this overlay
│   └── reference-injections.yml # References to load per lifecycle phase
└── references/
    ├── prerequisites-and-setup.md
    ├── troubleshooting.md
    └── playbooks/
        └── README.md

The project_hooks.py file registers your overrides:

from lib.registry import register

def register_acme():
    def wt_env_extra(envfile):
        with open(envfile, "a") as f:
            f.write("ACME_API_KEY=dev-key\n")

    def wt_db_import(db_name, variant, main_repo):
        # Import from your team's shared dump
        from lib.db import db_restore
        db_restore(db_name, f"{main_repo}/dumps/{variant}_latest.sql")
        return True

    def wt_run_backend(*args):
        import subprocess
        subprocess.run(["python", "manage.py", "runserver", "0.0.0.0:8000"],
                      check=False)

    register("wt_env_extra", wt_env_extra, "project")
    register("wt_db_import", wt_db_import, "project")
    register("wt_run_backend", wt_run_backend, "project")

The teatree core scripts call registry.call("wt_run_backend"), and your project handler runs instead of the default "not configured" stub. You only override what you need — everything else falls through to the framework or default layer.

There are 25 extension points

They cover the full lifecycle:

Category	Extension Points
Workspace setup	`wt_symlinks`, `wt_env_extra`, `wt_services`, `wt_detect_variant`
Database	`wt_db_import`, `wt_post_db`, `wt_restore_ci_db`, `wt_reset_passwords`
Dev servers	`wt_run_backend`, `wt_run_frontend`, `wt_build_frontend`, `wt_start_session`
Testing	`wt_run_tests`, `wt_trigger_e2e`, `wt_quality_check`
Delivery	`wt_create_mr`, `wt_monitor_pipeline`, `wt_send_review_request`, `wt_fetch_failed_tests`, `wt_fetch_ci_errors`
Ticket management	`ticket_check_deployed`, `ticket_update_external_tracker`, `ticket_get_mrs`
Follow-up	`followup_enrich_data`, `followup_enrich_dashboard`

The /t3-setup wizard can scaffold an overlay for you. Tell it your repos, your backend framework, and your database, and it generates the skeleton with commented-out examples for each relevant extension point. From there, fill in the blanks — or ask your AI agent to fill them in if it already knows your codebase (e.g., after working in the repos for a while).

The sourcing chain

Shell functions are loaded in order:

# In .zshrc:
source ~/.teatree                                     # load config
source "$T3_REPO/scripts/lib/bootstrap.sh"            # teatree core functions
source "$T3_OVERLAY/scripts/lib/bootstrap.sh"         # project overlay overrides

The overlay's bootstrap has a guard — it checks that teatree was sourced first (_T3_SCRIPTS_DIR must be set). This prevents confusing errors from running the overlay standalone.

Inside Python scripts, the pattern is similar:

import lib.init
lib.init.init()                 # registers defaults + auto-detects framework
from lib.project_hooks import register_project
register_project()              # registers project overrides at 'project' layer
from lib.registry import call as ext
ext("wt_post_db", project_dir)  # calls highest-priority handler

Auto-loading hooks

Skills don't help if the agent doesn't load them. I got tired of manually telling it which skill to read, so I added a hook that suggests the right skills automatically based on what you're doing.

The mechanism is ensure-skills-loaded.sh, a hook that runs before every message (in Claude Code, this is a UserPromptSubmit hook; other agent platforms would use their own equivalent). It does three things:

1. Project context detection

The hook scans all skill directories for hook-config/context-match.yml files. If any pattern in the file matches the current working directory or the active-repo tracker, that skill is identified as the project overlay. This is how teatree knows you're working in a specific project without you having to say so.

# hook-config/context-match.yml
cwd_patterns:
  - "acme-backend"
  - "acme-frontend"

If your $PWD contains acme-backend, the hook knows you're in the acme project and will suggest loading the ac-acme overlay alongside whatever lifecycle skill you need.

2. Intent detection

The hook parses the prompt to figure out which lifecycle phase you're in. It checks for:

URL patterns — a GitLab issue URL triggers t3-ticket, a Sentry URL triggers t3-debug
Keyword patterns — "implement" triggers t3-code, "push" triggers t3-ship, "broken" triggers t3-debug
End-of-session phrases — "done", "all set", "that's it" triggers t3-retro (only if at least one other skill was loaded this session)
Bare imperative verbs — "Fix the login page" triggers t3-code

If nothing matches and you're in project context, it defaults to t3-code — because most prompts in a project directory are about coding.

3. Dependency resolution and suggestion

Once the hook knows which skill you need, it:

Parses the skill's requires: frontmatter to find dependencies
Checks which skills are already loaded (tracked in a session file)
Builds a suggestion list of skills that need loading
Adds companion skills (e.g., ac-django for backend work in a Django project)
Adds reference file injections from reference-injections.yml

The output looks like:

LOAD THESE SKILLS NOW: /t3-workspace, /t3-code, /ac-acme.
ACME references to read: references/prerequisites-and-setup.md

The agent sees this as a system message and loads the skills before doing anything else. The wording is intentionally forceful ("LOAD THESE SKILLS NOW") — softer phrasing ("Consider loading...") gets ignored by models.

Symlink health checks

The hook also runs a once-per-session health check on skills that you maintain (determined by an ownership config):

Verifies skill symlinks are actual symlinks (not stale copies)
Checks that the source is a real git repository (not a downloaded zip)
Validates that symlinks point into git repos (so retrospective commits work)

If anything is broken, it either auto-fixes (re-running the installer) or warns with a specific remediation.

The retrospective loop

After every non-trivial session, t3-retro runs a retrospective — a systematic audit of the conversation that produces concrete skill improvements and optionally contributes them upstream.

What the audit catches

The retrospective categorizes issues into specific types:

Category	What went wrong	Example
False completion	Claimed "done" without full verification	Said feature was complete but didn't run the test suite
Skill not loaded	A relevant skill existed but wasn't loaded	Worked in project context without the overlay
Playbook miss	A playbook covered the task but wasn't consulted	Didn't check the deployment playbook before pushing
Over-engineering	Did unnecessary work	Built a migration when admin config would have sufficed
Under-engineering	Missed required work	Updated the backend but forgot the frontend changes
Hook gap	Auto-loading should have triggered but didn't	Hook didn't detect intent from "fix the flaky test"
Stale guidance	Followed outdated instructions	Playbook referenced pre-refactoring patterns

For each issue, the retrospective determines the root cause and writes the fix directly into the skill system — a new guardrail, an updated playbook, a troubleshooting entry, a hook pattern.

Where improvements go

The retrospective respects a clear hierarchy:

Project overlay ($T3_OVERLAY) — receives project-specific improvements (troubleshooting, playbooks, guardrails). This is the default target when T3_CONTRIBUTE is false.
Core skills ($T3_REPO) — only modified when T3_CONTRIBUTE=true, and only for generic improvements (missing verification steps, hook gaps, stale core guidance)
Personal config (memory files, agent config like AGENTS.md) — for user preferences and environment-specific facts. Also serves as a fallback location when the overlay isn't maintained by the user.

The contribution model

When you enable T3_CONTRIBUTE=true:

The retrospective creates a local commit on the current branch in your fork. It never pushes automatically.
A privacy scan checks for emails, home directory paths, API keys, internal hostnames, and any terms in $T3_BANNED_TERMS.
When you're ready, /t3-contribute reviews what will be pushed, checks for fork divergence, and optionally opens an issue on the upstream repo.

The idea is that every user's failures make the system better for all users — but only through an explicit, reviewed contribution path. Nothing happens without your consent. The default is T3_CONTRIBUTE=false, which means the retrospective only improves your project overlay and personal config.

A concrete example

Suppose during a session, the agent set up a multi-repo worktree and claimed it was ready, but the backend server failed to start due to port conflicts with a previous worktree. The agent didn't verify that the infrastructure was actually running before declaring complete.

The retrospective would:

Audit: Identify this as "false completion" — claimed infrastructure ready without verification evidence
Root cause: The t3-workspace script runs through all setup steps but has no way for projects to define and verify health checks before the agent declares the worktree usable
Fix (core): Add a new extension point wt_health_check to t3-workspace that projects can implement
Fix (overlay): Implement wt_health_check in the project's project_hooks.py to curl the backend, check the frontend dev server, verify the database is accessible
Verify: Check that the skill file parses, the extension point is registered correctly, and the overlay hook runs without errors
Commit: If T3_CONTRIBUTE=true, commit the core extension point to the fork's teatree core skills; overlay changes go to the project overlay repo

Next time the agent sets up a worktree, t3-workspace runs the project's health checks before finishing — the core provides the mechanism, the project overlay provides the specifics. Both are enforced going forward.

It adds up

A single retrospective might fix one guardrail. After enough sessions, you've accumulated a lot of them — each one from a specific failure that actually happened.

Companion skills

Teatree handles the lifecycle — ticket intake, worktree management, TDD, review, delivery. It doesn't know about your programming language's conventions or your framework's best practices. That's what companion skills are for.

Companion skills are standalone skills that live in separate repos and are loaded alongside teatree when relevant. I maintain a few (souliane/skills) covering Django and Python conventions, but the best companion skill for your stack is one you find (or build) yourself. I wrote a separate post about skill-driven development and the skills I'm open-sourcing.

The project overlay's hook-config/context-match.yml wires companion skills to repo patterns:

companion_skills:
  ac-django:
    - "acme-backend"
  ac-python:
    - "acme-backend"

When the hook detects you're working in acme-backend, it suggests loading ac-django and ac-python alongside the lifecycle skill. You get framework conventions without cluttering the core lifecycle skills with language-specific details.

This separation matters. Django conventions change on a different cadence than worktree management. Keeping them in separate skills means you can update one without touching the other, and teams using Flask or Express aren't burdened with Django-specific guidance.

Companion skills vs framework layer

These are different things. The framework layer is teatree's built-in middle priority in the 3-layer extension point registry — it ships stock implementations for common frameworks (e.g., a Django integration that auto-registers manage.py migrate as the post-DB hook). Companion skills are external standalone skills that teach the agent coding conventions — they don't register extension points, they provide guidelines. The framework layer handles infrastructure (how to run migrations); companion skills handle conventions (how to write good Django code).

Getting started

Prerequisites

An AI coding agent (the auto-loading hooks currently target Claude Code, but the skills and scripts work with any agent that can read files and run commands)
Python 3.12+
uv (Python package manager)

Installation

Teatree requires a local git clone — it has shared infrastructure (scripts/, references/, integrations/) that lives outside the individual skill directories, so npx skills add alone isn't enough.

Fork the repo on GitHub (or just clone it directly if you don't plan to contribute back), then:

git clone git@github.com:YOUR_USERNAME/teatree.git ~/workspace/teatree
cd ~/workspace/teatree
./scripts/install_skills.sh

The install script creates symlinks from your agent's skills directory to the clone. Then open your agent and run /t3-setup — it handles config, shell integration, hooks, and optionally scaffolds a project overlay for your repos.

If you want the retrospective loop to write improvements back into skill files, set T3_CONTRIBUTE=true in ~/.teatree (created by /t3-setup). This requires a fork — the agent pushes to your fork, not to the upstream repo.

The setup wizard:

Checks prerequisites — verifies all required tools are installed, reports a summary table
Creates ~/.teatree — asks for workspace path, branch prefix, issue tracker, chat platform
Scaffolds a project overlay (optional) — ask it about your repos, framework, and database, and it generates the skeleton
Configures shell integration — adds sourcing lines to .zshrc or .bashrc
Installs skill symlinks — creates the symlink chain from the agent's skills directory to your clone
Configures hooks — sets up ensure-skills-loaded.sh and the statusline (Claude Code-specific; other agents would configure their own hooks)
Runs a smoke test — verifies hooks parse, statusline runs, Python imports work

After setup, restart your agent (or start a new conversation). Try: "start working on ticket PROJ-1234" — the hook should suggest /t3-ticket + /t3-workspace, and the agent will take it from there.

You can re-run /t3-setup at any time as a health check. It validates the existing installation, checks for broken symlinks, verifies hook wording, and reports what needs fixing.

The directory structure after setup

~/
├── .teatree                    # Config file (sourced by shell)
├── .local/share/teatree/       # Runtime data (ticket cache, dashboard, MR reminders, cache)
├── .claude/                    # Claude Code example (adapt paths for your agent)
│   ├── CLAUDE.md               # Agent instructions (skill-loading block)
│   ├── settings.json           # Hooks, statusline
│   └── skills/
│       ├── t3-ticket -> ~/workspace/teatree/t3-ticket
│       ├── t3-code -> ~/workspace/teatree/t3-code
│       ├── ...
│       └── ac-acme -> ~/workspace/acme-overlay
└── workspace/
    ├── teatree/                # Teatree clone (or fork)
    ├── acme-overlay/           # Project overlay
    ├── acme-backend/           # Main repo clone
    ├── acme-frontend/          # Main repo clone
    └── ac/                     # Ticket worktrees
        ├── 1234/
        │   ├── acme-backend/   # Worktree
        │   ├── acme-frontend/  # Worktree
        │   └── .env.worktree   # Shared env
        └── 5678/
            └── ...

The symlinks ensure that skill files always resolve to the live git clone. This is important for the retrospective — when the agent writes improvements to skill files, the changes land in a real git repository where they can be committed and pushed.

When it helps (and when it doesn't)

It helps most with: structured, repeatable processes that span multiple repos or require project-specific knowledge. Ticket intake, worktree setup, TDD cycles, code review, MR creation, CI debugging. The kind of work that eats hours but follows a pattern.

It helps less with: one-off creative decisions, highly ambiguous tasks, or projects simple enough that a single repo with npm start covers everything. If your development workflow is "edit a file and push," teatree is overkill.

The sweet spot is when you have enough friction that encoding it pays off through repetition. The project works for my workflow but hasn't been tested beyond that. If something doesn't click for your setup, open an issue or a PR. Or point your AI agent at the problem and let it fix things until it works for you — that's kind of the point.

A note on security

Teatree skills are prompt instructions — they control what your AI agent does. That makes the supply chain a security surface. The defaults are conservative: self-improvement is off (T3_CONTRIBUTE=false), pushing is disabled (T3_PUSH=false), and there is no auto-update mechanism. You opt in to each level of automation explicitly. If you use a fork from someone else, you're trusting that person's skill files as agent instructions — review changes before pulling.

Why "teatree"?

TEA's Extensible Architecture for work*tree* management. Also, teatree oil cuts through grime, which felt fitting.