I set up my repo to compound before writing any application code. Here's why and how.

When I started the public repo for Knot Forget, I spent a session on scaffolding before writing a single line of application code. Not just hygiene — a README, some labels, a branch ruleset — but a structure that would make every subsequent session faster than the last. This is how I set that up, and why the order matters.

Compound engineering

Compound engineering is a workflow developed and open-sourced by Every Inc. The premise is that 80% of leverage is in planning and review, 20% in execution — and that each cycle should make the next one cheaper, not harder.

The loop has four phases:

1. Plan — brainstorm requirements, write a right-sized spec before touching code
2. Work — execute the plan
3. Review — catch issues, calibrate judgment
4. Compound — document what was learned so the next session starts ahead

The first three are what most teams already do under various names. The fourth is the one that usually doesn't happen consistently, because there's no designated home for it. When Compound is skipped, the loop resets: the next session rediscovers the same constraints from scratch.

Every Inc ships this as a set of Claude Code and Codex skills (/ce-brainstorm, /ce-plan, /ce-work, /ce-code-review, /ce-compound). But the structure is independent of any tooling — it belongs in the repo itself.

Making the loop physical in docs/

The loop maps onto three directories:

docs/brainstorms/ holds exploratory notes before a plan is written. docs/plans/ holds the implementation plan once scope is clear. The PR carries Work and Review — ephemeral by design, already preserved in git history. docs/solutions/ is where solved problems get documented after the fact: a specific API constraint, a non-obvious decision, a bug worth remembering.

Two practices make docs/solutions/ useful rather than just populated:

• YAML frontmatter tags (module, tags, problem_type) so searches — human or agent — can find entries by problem type rather than by filename
• A pointer in CLAUDE.md to docs/solutions/ so any collaborator or agent starting a session knows to look there before starting work

Without both, the directory exists but isn't reachable from the natural starting points of a session.

How I ran the four phases on the scaffold itself

Plan

I opened with /ce-brainstorm. I already had a rough list of what to scaffold — labels, issue template, PR template, branch ruleset, CLAUDE.md — so the session was about closing scope rather than exploring it. Several things were cut or deferred: a CONTRIBUTING.md, separate bug/feature templates, CI. Two less obvious decisions: the PR template inherits acceptance criteria from the linked issue rather than duplicating them, and CLAUDE.md covers code workflow only.

/ce-plan then produced a six-unit implementation plan. It had to resolve one bootstrap paradox upfront: the branch naming convention requires an issue number, but the issue template doesn't exist until the scaffold is done. The plan documented the sequence explicitly so I didn't have to re-derive it mid-session.

Work

Everything in this scaffold was scripts, templates, YAML, and documentation. I delegated execution to Codex, added the docs/ files (brainstorm + plan) as a checkpoint commit, and opened PR #2.

Review

The review happened through dialogue during the PR window — no formal tool needed for content with no domain logic. It caught four issues before or immediately after merge. The full list is in PR #2 and PR #4 on GitHub.

Compound

Before opening PR #4, I ran /ce-compound to capture three non-obvious GitHub API gotchas in docs/solutions/best-practices/github-repo-setup-gh-api-gotchas.md. Then I added a pointer to docs/solutions/ in CLAUDE.md — the wiring that makes the document findable from the start of any future session, whether I'm opening it or an agent is.

The repo had no application code at that point. The loop had already fired once.

Why I did this before writing any code

Setting this up after the project is underway means the first weeks of learnings go undocumented. I could backfill, but I won't — there's always something more pressing. The setup cost is the same on day one or month three. The documentation debt is not.

More concretely: scaffolding is real work, and real work produces learnings. Because the compound-loop structure was already in place during the scaffold, the scaffolding work itself fed the loop. Three non-obvious API constraints are now documented. A bootstrap paradox is written down so it doesn't have to be re-derived. The next session — mine or anyone else's — starts a step ahead.

The three directories cost nothing to create. The only constraint is the discipline to use them at the right moment — after a problem is solved, not in a separate documentation session. Set the shape early, and every cycle from the first one contributes to it.

Building Knot Forget in public · Threads