18trees-Project-Bootstrap

What it is

18trees-Project-Bootstrap is a personally customized bootstrap for coding agents that support skills (Codex / Claude Code). It integrates a four-layer semantic map, a working discipline for sub-agents, and four proven upstream skill specs into one usable project initialization, installed non-invasively into a project you have been writing for a long time.

It addresses three things: the agent does not know what your project looks like, so it re-reads the code every time while you still have to talk in file paths and class names; you want to say “just change this part” but cannot say what that part corresponds to in the code; and after the change no one checks independently. Incidentally, many tools also stuff files into your repository, so skills directories and config files all become part of your commit history.

So it does three things in turn: it draws a four-layer semantic map of the project, and when you point at the map and say “change this”, the agent maps it to the implementation; it sets a discipline for collaboration — one branch per task, an automatically launched independent review, serialized queue-based merging; and it brings in good specs, taking interaction, coding, engineering, and visualization from four proven upstream skills rather than inventing another set. You describe only the goal; installation, understanding, modification, testing, independent review, and merging are all the agent’s job. The entry point is the target project’s agent chat — web-based chatbots cannot execute commands or read and write files, so they cannot use this project.

How it is structured

What gets installed into a target project falls into four blocks: a four-layer semantic map, a set of workflow rules, specs sourced from upstream, and a local toolchain that installs, validates, and cleanly removes them.

Semantic map. The project is projected into four layers — Product / Feature (User Flow) / Capability / System — and written as one project.manifest.json: nodes carry a stable NODE:X id, layer, name, semantic summary, and planned / implemented status; relationships come in four kinds — adjacent-layer contains, Feature ordering precedes, same-layer depends_on, and data_flow between capabilities and systems; each user flow lists its ordered Feature steps under a FLOW:X id. A JSON Schema plus additional checks enforce unique ids, legal layers, every node reachable from a Product, and every Feature present in at least one flow. File paths, class names, and evidence live only in metadata, so the layer humans read holds semantics alone. archify renders the map into a self-contained offline HTML whose first entry is the Product / Feature workflow; the source-of-truth chain runs one way only — Codebase → Semantic Project Manifest → HTML Project Map.

Workflow rules. The backbone is the Gateway Flow: main ← Merge Queue ← Review Gate ← Task Branch ← Coding Agent. Every task starts from latest main on a feat/, fix/, refactor/, or chore/ branch, and the coding agent is forbidden to modify, commit to, or push main directly. Once implementation and tests are done, a Review Subagent launches automatically and receives only five kinds of material — the original task and its acceptance goals, the semantic node and boundary, a diff bound to base / head, test results, and the specs — and it is read-only, outputting only PASS or REQUEST_CHANGES. The merge queue serializes in Ready order, re-validating each queue head against latest main; conflicts go back to the original coder to re-adapt and then through review again, because the reviewer never fixes code. Deployment has two modes, Local-first (the default) and Production-direct, and both must satisfy the project’s own Deployment Check before reaching production. What it delivers is a behavioral spec: branch protection, permissions, and CI / queue services have to be configured by you on the remote. This repository’s own four merge commits landed through exactly this process.

Spec sources. Interaction, coding, engineering, and visualization specs come from four proven upstream skills — i-have-adhd, ponytail, Stop That Shit, and archify — and the upstream text is never copied into the repository. The project deliberately adds no competing coding spec: no code style, no test spec, no directory conventions. Its main output is orchestrating the four into one set — where each one’s boundary lies, what standard the reviewer reviews against, what to do when an upstream is missing, and whose word wins on conflict — and freezing those conclusions into the initialization templates.

Toolchain. bootstrap.py exposes five entry points: init / map / validate / verify-install / deinit. init runs from a full source copy outside the project, while the copy installed into the target renders the map, validates, verifies the installation, and uninstalls. Local-only is the default: everything goes into .project-bootstrap/, the project root keeps only two thin entries (Codex’s AGENTS.override.md and Claude Code’s CLAUDE.local.md), tracked AGENTS.md / CLAUDE.md are never modified, and neither are the global Git config, the shared info/exclude, .gitignore, or the index — Git conditional configuration binds only to the workspace where the installation lives. Tracked / staged diff is unchanged before and after installing, and uninstalling previews its scope first, keeping your original rules and task changes. Only an explicit choice of Standard commits the specs along with the project. Running it needs Python 3.12+, Node.js 22+, Git, and archify; missing dependencies are prepared in a cache directory outside the project.

Design decisions worth noting

Humans speak at the map, not at the file tree. The map’s first entry is the Product / Feature workflow, not a file tree; the human mainly operates the top three layers while the agent finds the technical path. One manifest serves two readers: a browsable offline HTML for the human, and an index for the agent to locate the implementation.

Review is the default action, and self-review cannot substitute for it. Every development task automatically launches a reviewer in an independent, clean context that receives only five kinds of material, is read-only, and can only return PASS or REQUEST_CHANGES; when evidence is insufficient, REQUEST_CHANGES is the only option — writing “guessing approval is not allowed” into a protocol is more reliable than putting it in a prompt.

Merging is serialized, and an old PASS is not grounds for unconditional merging. The queue runs in Ready order rather than creation order, and each head re-checks against latest main; if the implementation changes again, the earlier PASS lapses. Conflicts are not handed to the reviewer to fix — they return to the original coder to re-adapt, retest, and re-review.

Specs come from upstream; no competing set is invented. When good proven specs already exist, use the ones that exist; what this project defines is the collaboration interface, not another coding spec.

Installation is non-invasive and reversible. By default Local-only confines the effect to the workspace where it was installed without touching global configuration or the project’s existing rules; uninstalling restores the original exclude bytes and the thin entries’ original content, and keeps your task changes.

What problems it solves

• You no longer need to read the code structure before issuing a command: requirements are stated in product and feature terms, and the agent locates where they land.
• “Only change this part” becomes an executable boundary: under the Strict Node Boundary the agent may not cross it, and must stop and explain when other nodes need to be involved, waiting for you to redefine.
• Every change passes through one independent review: review launches by default, in a clean context, read-only, and can only return REQUEST_CHANGES when evidence is insufficient.
• Merging is serialized in Ready order and re-validated against latest main; conflicts return to the original coder to re-adapt, retest, and re-queue.
• Installing does not disturb the existing project: tracked / staged diff is unchanged before and after, uninstalling can restore it, and committing the specs with the project requires explicitly choosing Standard.
• Interaction, coding, engineering, and visualization specs are all reused from four proven upstream skills instead of being reinvented.