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

Source: Dev.to

Managing Context Rules Across AI Coding Tools

The problem:
Every AI‑coding tool has its own way of defining context rules.

• Claude Code → CLAUDE.md
• Cursor → .cursor/rules
• Gemini CLI → GEMINI.md

When you use more than one tool, you end up with the same content in three places, each with a slightly different format, and you’re constantly fighting sync issues.

The Two Parallel Attempts

Both were trying to solve the same problem, but one had too much code and the other had too many docs.

The Documentation Trap

I ended up with five markdown files for a CLI that didn’t exist yet:

• VISION_GENERAL.md
• ARCHITECTURE.md
• ROADMAP.md
• DECISIONS.md
• CLI_SPEC.md

The docs felt productive, but they were just a way to postpone writing the first line of code.

Lesson: If you can’t explain the project in a single paragraph, the issue is lack of clarity, not lack of documentation.

Choosing a Path Forward

I kept one project – the CLI – for three reasons:

1. Structural problem: Duplicated rules across editors won’t disappear; each editor needs its own format.
2. Complementary nature: A CLI works with native editor features, whereas a webapp competes against them.
3. Immediate validation: If the CLI works on a real project, you know it works. A webapp needs onboarding and retention before you can tell.

The webapp’s infrastructure (MCP, Supabase, versioning) can become a future “Pro” tier, but right now the priority is a working, installable tool.

I trimmed the docs down to two essential files:

• CLI_SPEC.md – the implementation contract (the spec).
• DECISIONS.md – a decision log.

All other files were deleted.

Building the CLI with Claude Code

Sprint 1 – Core (morning)

1. Scaffold – asked Claude Code to generate:

   • package.json
   • tsconfig.json
   • A commander‑based CLI with stub commands

   Result: Done in minutes.

2. Implemented devw init – detects the project, runs interactive prompts, creates the .dwf/ folder structure.

3. Implemented devw compile – the heart of the product:

   • Parses the YAML rule files.
   • Three bridges (Claude, Cursor, Gemini) each translate to the native format.
   • Generates the appropriate context files.

4. Implemented devw doctor – validates that everything is in order.

Sprint 2 – Blocks (noon)

Added a pre‑baked block system:

• devw add typescript-strict – injects strict TypeScript rules into the YAML.
• Registry, installer, and 6 content blocks.
• Commands: add, remove, list.
• Tests: 17 passing.

Sprint 3 – Ship (afternoon)

• Added a README, npm publishing config, and CI with GitHub Actions.
• Integrated changesets for automated releases.
• Dogfooding: Ran dev‑workflows on its own repository.

Bugs discovered during dogfooding

These three bugs would never have surfaced from tests alone; real usage exposed them.

End‑of‑Day Result

• Published on npm (dev‑workflows).
• Commands (6): init, compile, doctor, add, remove, list.
• Bridges (3): Claude Code, Cursor, Gemini CLI.
• Pre‑baked rule blocks (6): TypeScript, React, Next.js, Tailwind, testing, Supabase.
• Tests: 54+ passing.
• CI: GitHub Actions.
• Releases: Automated via changesets.

Quick Usage

# Initialise a project
npx dev-workflows init

# Add a rule block (e.g., strict TypeScript)
npx dev-workflows add typescript-strict

# Generate the context files for each editor
npx dev-workflows compile

Define rules once in YAML → compile for each editor.
Change a rule, re‑run compile. If something’s off, devw doctor tells you.

Reflections

• Documentation before code can be procrastination in disguise.
• A concise spec is enough for AI to implement a functional product.
• Dogfooding uncovers issues that tests never anticipate.
• Ship first, polish later. Hard‑coded values, basic prompts, and a simple block system are fine as long as the tool is usable. Publishing early is the fastest way to validate the idea.

What’s Next?

• More bridges – Windsurf, Copilot, and other editors that use context files.
• Remote block registry – community‑contributed rule blocks.
• Watch mode – auto‑recompile on .dwf/ changes.
• Custom scopes – categories beyond the five built‑in ones.
• Pro webapp – visual UI for managing rules (future tier).

dev‑workflows is now at v0.1 – functional, used on my own projects, and ready for community feedback.

Dev‑Workflows

A team‑friendly interface for managing AI coding tools, with versioning and synchronization.
If you use multiple AI coding tools and are tired of keeping duplicate rules across them, give it a try:

npx dev-workflows init

Package

• npm:
• GitHub:
• License: MIT

If you find bugs or have ideas, please open an issue. This project is being built in the open.

Requires: Node.js ≥ 22.