Explorer
Home Blog Contact Claude SDD

A Meta-Repo Workflow

Jan 3, 2026

Update: My Claude Plugin has been deprecated. I’ve moved on to using Codex inside of OpenCode for now, but I am sure that will change again. Most of the concepts here still apply. I am still working out of a top-level repo that contains all of my active projects as well as my Obsidian vault.

I’ve written about this a few times, but for a while now I have been working on my solution for working with LLM coding assistants. A way to direct them, keep them focused and on-task, prevent them from losing context, etc. See:

  1. I Tried Using AI to Make Me an AI App
  2. I Made an AI Coding Template (Sort of)
  3. Three Lessons from Building an AI Coding Toolkit

This is still something I am working on, but I am pivoting for a bit to experiment with something else.

My Claude Code Plugin really has two “core” ideas:

  1. Strict rules and workflows that the AI should follow while doing work, so that it works in the way you want it to and doesn’t just go off on rabbit holes and tangents.
  2. The work is represented in markdown files in the repo. Close to the code.

That second one is my take on Spec Driven Development. This makes it really easy for your LLM (in this case Claude Code) to parse and update the work in progress. That works well so far, but comes with some caveats.

  1. It’s difficult to coordinate with other developers like this. You have to deal with a potential merge conflict every time you want to make a change to a Spec or Task. Not ideal.
  2. You may have legitimate reasons for not including all of your project work history in the source of that project itself. Maybe this is an open source project but you don’t want all of that information available for anyone to see.
  3. It’s more difficult to get a bird’s-eye view of all of the different things you may be working on.

To try and solve some of these friction points, I am currently experimenting with working out of a top-level “Meta-Repo” (for lack of a better term).

On my PC, I currently have my directory structure set up something like this:

projects/
├── ideas/
│   └── [project]/
│       ├── README.md
│       ├── project-brief.md
│       ├── critique.md
│       ├── competitive-analysis.md
│       ├── features/
│       ├── specs/
│       │   └── SPEC-###-name.md
│       ├── issues/
│       │   └── ###-name/
│       │       ├── TASK.md
│       │       ├── PLAN.md
│       │       └── WORKLOG.md
│       ├── docs/
│       └── notes/
├── shared/
│   ├── docs/
│   │   ├── tech-stack-decisions.md
│   │   ├── pricing-philosophy.md
│   │   └── branching-strategy.md
│   └── templates/
├── spaces/
│   └── [project]/
│       ├── CLAUDE.md
│       ├── README.md
│       └── docs/
│           ├── architecture-overview.md
│           ├── data-model.md
│           └── adrs/
└── resources/
    ├── research/
    └── style-guide.md

Here is what each of those directories is for.

Directories

ideas/

This was actually the original purpose of the repository. I had been using this repo for a while as my brainstorming place for ideas and apps I hadn’t actually started building yet. A place for me to brainstorm with Claude Code and Gemini, pitch them ideas, ask for their feedback, sketch out project briefs, theorycraft monetization strategies, etc. Then I save the results of those discussions as markdown files. The kind of thing I was using Claude or Gemini in the web for, but in a way where the results of those discussions don’t feel so ephemeral. For a while it was an unstructured catch-all, but over time I have somewhat standardized the different files that go in there: project brief, competitive analysis, and a few other files that every idea should have, each following a semi-rigid template.

It’s now also where I track my project management and planning type of work. Specs, Tasks, etc.

resources/

This is where I store things that apply to more than one project. For example, I’ve defined a universal “style guide” for all of the things I am building, so there is a more cohesive look to them. My signature style, as it were. I’ve also been storing “research reports” in here. When I have Claude Ultrathink and research something, I have it save the results as a markdown file here so it’s easy to find and reference later.

shared/

This is for cross-project documentation. For example, I keep my unified tech stack decisions here (which framework for which type of app) and cross-cutting patterns like pricing philosophy that apply to multiple products. I might merge it with resources though, still playing around with it.

spaces/

This is my code. My in-progress side projects. Crucially, this directory is gitignored. That lets the meta-repo track high-level planning and ideas separately from the execution and version history of the individual code projects. Each project in it is its own git repository. I keep the ADRs and other related docs in it since those are the kind of thing that I think should be in the repo, even if it’s open source, since they would be useful to other developers who might contribute to the app.

Workflow

I launch my IDE and my LLM sessions in that root projects directory, not the directory for the individual projects themselves. I treat this directory essentially like a local, lightweight Jira and Confluence alternative. By working from here, I can better share information and context across the different things I am working on. For example, say you’re working on two different apps and they both use Clerk for authentication. By doing that work from the root directory, it’s easier for the LLM to take the lessons learned from implementing it in one app and apply them when you implement it in the other.

I’ve always been kind of able to do that with Claude Code. You can tell Claude Code to “Look up the Clerk implementation in ../my-other-app” and it can do so, but it’s a bit heavy-handed and brute force. Gemini and Codex, on the other hand, can’t seem to do that at all. For both of those, if I try to tell it to look at something outside of the “current project’s working directory,” it just won’t. I’ll get some kind of error like “File path must be within one of the workspace directories.” There are probably other ways to get around this limitation, but by launching the LLM in the parent directory, you just avoid that altogether.

I’ve taken a lot of inspiration from the Claude Code plugin I have been developing. I’m using mostly the same format around the Specs and Tasks, the same workflows and development loops, but I have moved those files into the ideas/ directory. This way they’re still local, still easy for the LLM to use, but they’re not “polluting” the source code of the actual projects themselves. I’m also using slightly tweaked versions of the commands and subagents from my plugin.

The root directory also has a CLAUDE.md that gives the LLM context about the whole workspace: what each project is, their status, and how to navigate the structure. Meta instructions, if you will.

I’m going to keep iterating on this. I’ve got some ideas on how to better capture “lessons learned” in a more standardized format. I also have some ideas on how to make this more collaborative with other human developers, but that’s a whole different project. It could also turn out that this isn’t really worth it at all, but stay tuned and I’ll let you know either way!