I had two projects solving the same problem. I merged them and published to npm in a day

Geordano Polanco — Sat, 07 Feb 2026 20:06:41 +0000

I've been going back and forth on the same problem for months: how to manage the context rules you give AI coding tools. If you use Claude Code, you write a CLAUDE.md. If you use Cursor, a .cursor/rules. If you use Gemini CLI, a GEMINI.md. If you use all three — like I do — you have the same content in three different places, with three slightly different formats, and the certainty that at some point they'll get out of sync.

The problem is real. The solution took me longer to find than it should have.

Two projects, zero products

For weeks I was working on two things in parallel:

DevContext AI was a webapp. It had an MCP server, rule versioning, a Supabase database, auth, Vercel deploy. It was functional. It was deployed. It had an MVP. And nobody used it, starting with me, because it was too much for what I actually needed.

dev-workflows was a CLI. The idea was simpler: define rules in YAML, compile for each editor. But it only existed as documentation. Folders of docs, specs, architecture diagrams, documented decisions. Zero code.

One project with too much code and no focus. Another with too many documents and nothing executable. Both solving exactly the same thing.

Documentation paralysis

I have to be honest about something: I got stuck documenting. I had a VISION_GENERAL.md, an ARCHITECTURE.md, a ROADMAP.md, a DECISIONS.md, and a CLI_SPEC.md. Five documents for a CLI that didn't exist.

The documentation felt productive. I was "making progress." But I was really just putting off the moment of writing the first line of code. It's a trap I think more of us fall into than we'd like to admit.

The clarity came when I realized that if I couldn't explain what I was building in a paragraph, the problem wasn't lack of documentation — it was lack of clarity.

The merge

I decided to keep one. The CLI won for several reasons:

The underlying problem (duplicated rules across editors) is structural. It's not going away soon — each editor uses its own format.
A webapp competes with native editor features. A CLI complements them.
Validating a CLI is immediate: if it works on your project, it works. A webapp needs users, onboarding, retention.

The webapp doesn't get thrown away. The infrastructure (MCP, Supabase, versioning) becomes the future Pro tier. But that doesn't matter now. What matters now is having something that works and that someone can install.

I cut the five documents down to two: CLI_SPEC.md (the implementation contract) and DECISIONS.md (decision log). Everything else got deleted.

One day with Claude Code

This is where it gets interesting. With a clear spec, I handed the document to Claude Code and started building.

Sprint 1 — Core (morning)

I told it to scaffold the CLI: package.json, tsconfig, commander with commands registered as stubs. Done in minutes. Then the logic for devw init — tool detection, interactive prompts, .dwf/ structure generation. Worked on the first try.

Then devw compile — the heart of the product. A parser that reads the YAML files, three bridges (Claude, Cursor, Gemini) that translate to native format. Each bridge is one file. And devw doctor to validate everything is in order.

Sprint 2 — Blocks (noon)

Pre-baked block system: devw add typescript-strict installs strict TypeScript rules into your YAML files. Registry, installer, 6 content blocks, add/remove/list commands. 17 tests.

Sprint 3 — Ship (afternoon)

README, npm config, CI with GitHub Actions, changesets for automated releases. And the dogfooding: using dev-workflows on the dev-workflows repo itself.

The dogfooding was the most valuable part. I found three bugs the tests didn't catch:

devw compile was overwriting the entire CLAUDE.md — if you had manual content, you'd lose it. Fix:  markers that delimit the generated section.
devw init was adding all of .dwf/ to .gitignore — but .dwf/ contains your source rules, which you do want to version. Only .dwf/.cache/ should be ignored.
Invalid input in prompts crashed the CLI with a stack trace — instead of showing a friendly error and asking again.

Three bugs I found in 5 minutes of real usage. Three bugs that wouldn't have surfaced without using the product myself.

The result

By the end of the day I had a CLI published on npm with:

6 commands: init, compile, doctor, add, remove, list
3 bridges: Claude Code, Cursor, Gemini CLI
6 pre-baked rule blocks (TypeScript, React, Next.js, Tailwind, testing, Supabase)
54+ tests passing
Automated CI with GitHub Actions
Automated releases with changesets

npx dev-workflows init                    # creates .dwf/ with config and empty rule files
npx dev-workflows add typescript-strict   # installs a rule block
npx dev-workflows compile                 # generates CLAUDE.md, .cursor/rules, GEMINI.md

Define rules once in YAML, compile for each editor. Change a rule, recompile. Something's off, doctor tells you.

What I learned

Documentation before code is procrastination disguised as productivity. A concise spec is necessary. Five documents with vision, architecture, and a roadmap for something that doesn't exist yet is creative resistance.

A good spec is enough for AI to implement. I gave Claude Code the CLI_SPEC.md and it generated correct code on the first try in almost every case. The key isn't writing more documentation — it's writing the right documentation.

Dogfooding finds what tests don't. Tests verify what you thought could break. Using your own product reveals what you never even considered.

Ship first, polish later. The CLI has hardcoded values, the prompts could be better, and the block system is basic. None of that matters if nobody uses it. Publishing is the fastest way to find out if the product makes sense.

Current status and what's next

dev-workflows is at v0.1 — functional and I use it on my own projects, but it's an early version.

What's on my radar:

More bridges — Windsurf, Copilot, and other editors adopting context files
Remote block registry — so the community can contribute their own
Watch mode — auto-recompile on .dwf/ changes
Custom scopes — categories beyond the 5 built-in ones
Pro webapp — visual interface for teams, with versioning and sync

If you use multiple AI coding tools and you're tired of keeping duplicate rules across them, give it a try:

npx dev-workflows init

npm: npmjs.com/package/dev-workflows
GitHub: github.com/gpolanco/dev-workflows
License: MIT

If you find bugs or have ideas, open an issue. I'm building this in the open.

Requires Node.js >= 22.

DEV Community: Geordano Polanco