DEV Community: crimson206

One Repo, One Package: Where the Review Trail Lives

crimson206 — Wed, 07 Oct 2026 12:19:45 +0000

In our first post on MWD we described the rule we build with: one repo = one package. Packages depend on each other only through published, versioned releases. At the end we admitted a cost: a change that spans several packages turns into several releases, and keeping versions aligned takes real care.

A reader replied with a good question:

I'd keep the package release and downstream version bump in the same review trail, so the interface change stays visible.

This post is our answer. We agree the change has to stay visible. We disagree that it needs one shared review trail.

Where the review trail lives

When a change in package A forces a change in package B, two decisions are made, in two places:

A decides what changed and why, and releases it under a version tag.
B decides which version of A to take and why, and pins it.

Both decisions belong in the commit history of the repository that made them. A's commit says what the interface change is. B's commit says "took A 0.1.1 because of X." The pinned version number is the link between them: from B you can find the exact release of A, and from A's tag you can find the commit that explains it.

So the histories stay separate, and each repository keeps a complete record of its own reasons, but the information isn't cut off. You follow the version number from one history to the other.

To make this concrete, we'll use a small example workspace, acme, built for this post. It has five repositories: a shared core package, a worker package that runs tasks and is deployed to production, a cli app, a dashboard app, and a worker-deploy project. The names, commits and versions are made up; the tool output further down is real, run against that workspace.

The change: core gets an optional task priority. Here's how it moves through the repositories:

core: feat(core): optional task priority (low|normal|high, default normal), then chore: release v1.3.0 and tag v1.3.0. What the new field is and how it's validated.
worker: chore(deps): @acme/core lower bound ^1.3.0 (task priority), feat(worker): run high-priority tasks first, then lock @acme/core 1.3.0 and its own release, v0.5.0.
cli: chore(deps): apply @acme/core 1.3.0, feat(cli): acme submit --priority <low|normal|high>, then v0.4.0.
worker-deploy: chore(deps): pin @acme/worker 0.5.0 (high-priority tasks run first) (more on this one below).

Why not one review space per change instead? Because the boundary isn't clear. A change in core touches the worker and the cli; the worker takes core directly and is deployed by yet another project; the dashboard depends on core too but doesn't need the new field yet. If every dependency edge gets a review space, you have to decide where each one starts and ends, and the number of spaces grows with the number of edges, not the number of packages. We would rather keep one rule that scales: every repository explains itself, and versions connect them.

What goes wrong if you do it naively

The rule alone doesn't make any of this easy. If you follow one repo = one package and change nothing else, you hit four problems quickly:

The story scatters. One change produces commits in four or five repositories. Each history is fine on its own, but nobody sees the whole sequence.
You don't know who is affected. When core changes, which packages depend on it, and which of them need a new release?
Versions drift. Some packages pin the new version and others still ask for the old range. It isn't always a bug, but you have to look.
Local, installed and deployed copies disagree. The code in your working tree, the version installed on your machine and the version running in production can all be different, and nothing tells you.

None of these are reasons to give up the rule. They are reasons to make the connections visible. Here are the tools we use for that. The output below is real, run against the example workspace from the change above; its root path is shortened to ~/acme.

Keeping the hierarchy: nested repos, two views

Splitting into many repositories doesn't mean giving up structure. A workspace still nests: a packages/ folder for libraries, a projects/ folder for apps, and each entry is its own Git repository. The gitdot names from the first post carry the same structure into the remote: packages/core on disk is acme/taskq.packages.core on the Git host.

git-nested, which we introduced last time as a live view of changes across nested repositories, can show the workspace from either side. By folder, with each repository's remote:

And by repository name, splitting each gitdot name on its dots:

The web view shows the same thing side by side: the repositories by local path on the left, and by remote URL on the right.

The same hierarchy comes out of both the folders and the repository names. Neither depends on the other: clone by name and you can rebuild the folders; look at a folder and you know the repository's name. One repo = one package splits the code, not the structure. (The (1) on dashboard is one uncommitted file; we'll come back to it.)

git-nested went through this split itself. It used to be one repository; it is now core, server and ui packages plus a cli project, each in its own repository. The original repository became the cli project rather than being replaced, so its history carried over intact, and the new packages start with their own histories. The cli's commit says it is now assembled from them, and its dependencies name the versions it takes. That's the pattern of this post on a small scale: independent histories, connections kept.

Following one change across repos: cscan

cscan collects commits from every repository under a folder into one timeline. Here it is for the change above, the day core added task priority, grouped by repository (times in UTC):

Each line is still a commit in its own repository, with its own reason. cscan doesn't merge anything. It puts the separate histories next to each other so you can read the whole sequence: core added the feature and released, the worker raised its lower bound, then locked the new version and released, the cli followed, and the deploy project pinned the released worker.

Who is affected, and are versions aligned: mwd-deps

mwd-deps reads dependency declarations. sync-check looks at every local package in a folder and reports where packages ask for different versions of the same dependency:

This doubles as the answer to "who depends on core?": every package that declares it is listed, along with the range it asks for. Not every mismatch is a bug. ^1.2.0 still accepts 1.3.0, so the dashboard can still end up with the new version installed. But the list shows exactly where a decision was made and where it wasn't yet. Here the dashboard is the one that hasn't decided, and it's also the repository git-nested showed with uncommitted work: someone is in the middle of adding the priority column. When that lands, its commit should say which version of core it now needs, and why. mwd-deps also has dependents and impact commands that answer the same question from the package registry.

Local vs installed vs published: verscan

verscan walks a folder and compares, for each package, the version in the working tree, the version installed as a command on the machine, and the latest published version in the registry. Nothing in the example workspace is published, so there's nothing useful to show here, but on a real workspace it lists the packages where the three disagree: a release that was never published, a CLI that's installed globally at an older version, a --version flag that prints the wrong number.

Most of what it finds is expected, such as an app that's never meant to be published. The point is that the three versions are checked, not assumed.

A common mistake: deploying what wasn't released

The worker package is what runs in production. The tempting way to ship a change is to deploy straight from its working tree, then release. In the example workspace, that's how the previous worker release went:

The deploy commit comes 24 minutes before the v0.4.0 release. For those 24 minutes, production ran code that existed only in a local checkout. Even if the release that follows differs only in its version number, the rule is broken: the deployed worker has no published version to point to, so the trail from "what's running" back to "which release, and why" is missing. And nothing forces the release to match what was deployed.

The fix is structural, not a reminder. A separate deploy project, worker-deploy, doesn't contain the worker's code. It installs a published, exactly pinned version of @acme/worker and deploys only that. Upgrading the worker then means: release the package, bump the pin in the deploy project with a commit that says why, then deploy. That's the last line of the earlier timeline: pin @acme/worker 0.5.0 (high-priority tasks run first), after the worker's v0.5.0 release. The deploy project's history is the record of what ran in production, and each entry points to a release.

That's the same pattern as the rest of this post: the deployment becomes one more repository that writes down which version it took.

Wrapping up

One repo = one package means a cross-package change leaves several commits in several histories. We think that's fine, as long as each repository records its own reason and the version numbers connect them. A shared review space for every dependency would be hard to define and hard to keep up.

What we needed instead was to make the connections visible: the hierarchy (git-nested), the timeline across repositories (cscan), who depends on what (mwd-deps) and which versions are actually where (verscan). These tools don't change how the work is split. They let us read it as one story when we need to.

One Repo, One Package: How We Structure Code for AI Agents

crimson206 — Wed, 30 Sep 2026 08:41:44 +0000

Most development practices were designed around people: how teams split work, review each other's changes, and ship together. Now more and more of the code is written by AI agents, so we started from a different question. What structure makes an agent's work easy to scope, easy to check and easy to undo?

Our answer is a methodology we call MWD (Microwise Development). It has one core rule:

One repo = one package.

Every package lives in its own Git repository. Packages stay small and do one thing. They depend on each other only through published, versioned releases, never through local paths like file:../.

Why this matters when agents write the code

An AI coding session works inside a boundary, and the useful question is what that boundary contains.

In a large shared codebase, an agent asked to fix one module can see, and often touch, everything around it. The change you asked for comes back mixed with changes you didn't ask for. When something breaks, it is hard to say how far back you need to roll.

When the package is the repository, the boundary becomes concrete:

Scope. An agent working on a package opens that repository. What is in front of it is the package and the versions it depends on.
Parallelism. Two agents working on two packages are working in two repositories. They don't share a working tree, so they don't collide in one.
Rollback. A package has its own history and its own releases. If a release is bad, consumers go back to the previous version.

You can approximate some of this inside a monorepo with conventions and tooling. We chose the repository boundary because git, CI, permissions and releases already respect it.

The rule is simple, but following it creates two practical problems right away.

Problem one: a lot of repositories

If every package is a repository, you end up with many repositories: dozens at first, then more. A monorepo gives you structure for free, because folders nest. A flat list of repositories on a Git host doesn't.

We didn't want to give up the one-repo rule to get structure back, so we put the structure into the repository name instead. This is gitdot, a naming syntax that uses dots to express hierarchy:

gitlab.com/microwiseai/glpkg.cli
gitlab.com/microwiseai/glpkg.adapters.npm
gitlab.com/microwiseai/glpkg.adapters.pypi

gitdot reads those names as a tree: a glpkg group containing cli and an adapters group, which in turn holds npm and pypi. The hierarchy you would have expressed with folders in a monorepo now lives in the name, and so in the URL of every repository. It works on the Git hosts you already use, such as GitHub and GitLab. gitdot doesn't host anything itself; it's an organizing layer on top of the platform.

Here are our own glpkg repositories, first as GitLab lists them and then as gitdot shows the same repositories:

Before: GitLab shows a flat list.

glpkg > adapters (npm, pypi, go, nuget, generic) and packages" width="720" height="918">
After: gitdot turns the dotted names into a tree.

With the structure in the names, grouping, listing and cloning "everything under glpkg.adapters" become operations on names.

Problem two: a lot of packages to publish

The second problem follows from the first. If packages depend on each other only through published versions, every package has to be published, often and in large numbers. A fix to one small package means a new release, and then consumers install that release.

Where do all those releases go?

The obvious answer is the public registries: npm, PyPI and the others. That doesn't fit what we're doing. Many of these packages are small internal building blocks. They're useful to us, but they don't belong in a public index that other developers search. Publishing hundreds of them would add noise to a shared space. It would also tie our naming to whatever is still free there, and many good names and scopes were claimed long ago.

What we wanted was a registry of our own that we could publish to as often as we like, under names we choose, without touching the public registries.

That's what glpkg does. It publishes packages to, and installs them from, a GitLab package registry that belongs to your group. From the developer's side (or the agent's side), it feels like any other package manager.

Here's a real example. git-nested is a small tool we built for this way of working. With one repo per package, a workspace fills up with Git repositories nested inside folders, and git-nested shows all of them as one tree in the browser, with each repository's uncommitted changes updating as files change. We publish it with glpkg to our group's registry, and because its repository (gitlab.com/microwiseai/mwd-tools.git-nested) is public, you can install it without a token. It's a command-line tool, so it goes in globally:

npm i -g @glpkg/cli
glpkg install @mwd-tools/git-nested --group microwiseai -g
git-nested --help

--group tells glpkg which group's registry to install from. glpkg takes care of the registry configuration and authentication, so installing one of our packages looks the same as installing a public one. It supports npm, PyPI, Go modules, NuGet and generic packages.

In our workflow the loop for a change is always the same: commit, publish a new version, install it where it's needed. Agents follow the same loop as people, with the same commands.

Why GitLab

We looked at the usual candidates. Publishing everything to the public npm registry defeated the purpose. GitHub Packages integrates well with GitHub, but it has no generic package type for arbitrary artifacts. A self-hosted registry like Verdaccio handles npm only, and it's one more server to run.

GitLab was the one product that gave us all of these together, on its free hosted tier:

private packages
several package formats plus a generic registry
Git hosting and CI in the same place

GitLab doesn't have the widest format coverage; dedicated artifact managers support more. For us, the combination mattered more. We'll go deeper into this comparison in a follow-up post.

Wrapping up

MWD starts from one rule, one repo = one package, because it gives an AI agent a clear boundary to work in and gives us a clean unit to review and roll back. The rest of the tooling exists to make that rule livable: gitdot keeps many repositories organized, and glpkg keeps many packages flowing.

gitdot, glpkg and git-nested aren't the only tools. Along the way we've built several others for working this way, such as linting and dependency checks, and we use them every day. Most of those are still internal. We hope to share more of them over time.

The rule has costs too. A change that spans several packages turns into several releases, and keeping versions aligned across repositories takes real care. We'll write about those trade-offs as well.

If you're working with AI agents on a codebase that keeps growing, we hope this gives you another way to think about where the boundaries go.

IST: Running AI Coding Sessions as a Team

crimson206 — Sat, 26 Sep 2026 11:27:54 +0000

Most of us use AI to write code the same way: one chat window, one agent, one task at a time. It is a good default — until the work outgrows a single conversation, and that one thread becomes the bottleneck.

IST takes a different approach. Instead of a single agent, it runs multiple sessions that coordinate like a team: a manager that plans and delegates, and workers that carry out tasks in parallel. The manager rarely touches the code itself. It decomposes the work, hands each piece to a worker, reviews what comes back, and keeps everything moving toward the goal.

Here is what that looks like when several sessions run at once:

A team, not a chatbot

A single agent is a capable individual contributor. But an individual has limits: one context window, one train of thought, one thing in flight. Scale the ambition — a migration across dozens of files, a feature that spans several services, a batch of independent tasks — and you feel those limits fast.

IST reframes the unit of work from a conversation into a team:

Sessions are independent agents, each with its own context and workspace. You start and manage them with a single command.
Messaging lets sessions talk to one another — a manager assigns a task, a worker reports back — so coordination is explicit rather than improvised.
Monitoring watches every session at once, surfacing the moment one needs a decision or finishes its work, so nothing stalls in silence.

On top of these primitives sits a simple pattern we call TDA (Top-Down Agent): the manager owns the plan and the delegation; workers own the execution. The manager stays at altitude — deciding what and who — while workers handle the how.

Why it matters

Parallelism is the obvious win: several workers can move on several fronts while the manager holds the thread. But the quieter benefit is separation of concerns. The manager is never buried in diffs, so it stays free to plan, sequence, and verify. Workers are never distracted by the big picture, so each one focuses on a single well-scoped task and returns a clean result. The structure itself makes the work more legible — and, in our experience, more correct.

Try it yourself

The best way to understand IST is to run it. Our getting-started guide takes you from zero to your first manager-and-worker setup in a few minutes:

→ Getting Started with IST

If you build something with it — or break something interesting — we would love to hear about it. Follow along as we build MicrowiseAI in the open.

Don't delegate too much to Claude Code.

crimson206 — Mon, 08 Sep 2025 23:06:41 +0000

Since Claude Code handles most things pretty well, I tend to just approve permission requests as they come in. But this makes it hard for both me and Claude Code to know if the code is actually on the right track. While it might be handling the small details fine, the overall flow could be a complete mess.

Even if I keep hitting "yes! yes!" in the moment, I need to completely reset the allow settings the next day.

From Google Maps to OpenStreetMap: A Journey of Trade-offs in Location Services

crimson206 — Fri, 05 Sep 2025 12:02:17 +0000

When building a location-based application, I needed to implement a feature that would allow users to click on a map and retrieve coordinates. What seemed like a straightforward requirement turned into an exploration of different mapping solutions and their inherent trade-offs.

The Google Maps Temptation

My initial instinct was to leverage Google Maps - it's familiar to users and provides excellent search functionality. On the web version, Google Maps generates URLs like this:

https://www.google.com/maps/place/N+Seoul+Tower/data=!3m1!4b1!4m6!3m5!1s0x357ca257a88e6aa9:0x5cf8577c2e7982a5!8m2!3d37.5511694!4d126.9882266!16zL20vMDJxcGYx?entry=ttu&g_ep=EgoyMDI1MDkwMi4wIKXMDSoASAFQAw%3D%3D

These URLs contain location data and place IDs that can be parsed for coordinates. However, on mobile devices, you can't directly access these URLs. Instead, the share function provides short links like:

https://naver.me/xZjKJ9SA

While these can be resolved through redirects to get the full URL, this introduces latency - an acceptable trade-off for the familiar Google Maps experience.

The Stability Problem

The real showstopper wasn't the user experience or performance concerns. It was stability. The URL structure I was parsing wasn't a JSON API response or official documentation - it was essentially reverse-engineering Google's internal URL format.

This approach had several red flags:

No guarantees about URL format consistency
Not an official API endpoint
Could break without notice
Not sustainable for a production service

Back to Basics: OpenStreetMap + Leaflet

Ultimately, I reverted to a more traditional approach using OpenStreetMap with Leaflet. While this solution has its limitations:

Cons:

Search functionality isn't as robust as Google Maps
Less polished UI compared to Google's interface

Pros:

Fast and responsive
Highly customizable
Stable and predictable APIs
Cost-effective

Building Resilient Systems

Even OpenStreetMap isn't bulletproof. That's why I implemented both solutions - the Google Maps workaround as a backup to the primary OpenStreetMap implementation. This redundancy ensures service continuity if either solution fails.

Key Takeaways

This experience reinforced several important principles:

Nothing is perfectly stable - Build redundancy into your system with multiple fallback options
Avoid dependencies on unofficial APIs - Reverse-engineering existing services may seem clever, but it's a maintenance nightmare
Purpose-built tools often win - Sometimes combining developer-focused tools to build custom components is more reliable than trying to hack existing consumer products

When building production systems, it's tempting to take shortcuts by leveraging popular services in unintended ways. However, the short-term gains often lead to long-term technical debt. Sometimes the boring, stable solution is the right choice.

What mapping solutions have you used in your projects? Have you faced similar trade-offs between familiarity and stability?

Standalone Python CLI Distribution Made Simple

crimson206 — Sun, 08 Jun 2025 18:33:22 +0000

Want to share your Python CLI tool with non-technical users? Let's make it simple - no Python installation required!

Why Standalone Binaries?

Traditional Python CLI tools depend on the Python environment present during installation. For more reliable service delivery, sometimes we need to distribute a standalone package with Python compiled into it.

Quick Solution

I've created a template repository that handles all the complexity for you:
python-standalone-binary

This template provides:

A simple example CLI implementation
Installation scripts
Release workflow
Cross-platform support (Linux, Windows, macOS)

With these tools, you can easily distribute standalone Python CLI binaries on GitHub using a simple installation command:

curl -fsSL https://raw.githubusercontent.com/{user}/{repo}/main/scripts/install.sh | bash

Try Our Example

Want to see it in action? Test our example CLI with these commands:

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/crimson206-templates/python-standalone-binary/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/crimson206-templates/python-standalone-binary/main/scripts/install.ps1 | iex

Running the CLI

Linux/macOS: Simply type example-cli in your terminal
Windows: The installer will show "Installed to: {path}"
- Example path: C:\path-to\example-cli.exe
- Run the shown path in PowerShell

Deploying Your Own CLI

The release action is configured to run automatically when version tags are pushed.

To deploy this example in your own repository:

Fork the repository:

   gh repo fork crimson206-templates/python-standalone-binary

Create a release:

   source scripts/tagging.sh v0.1.0

After the action completes successfully, test your deployment:

   # Linux/macOS
   curl -fsSL https://raw.githubusercontent.com/{user}/python-standalone-binary/main/scripts/install.sh | bash

Resources

Ready to make your Python CLI more accessible? Check out the template repository and start building!