@raindogs/contextmd 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# contextmd
+
+Generate and sync `CLAUDE.md` and `AGENTS.md` for any repo — one command, no API key needed.
+
+```bash
+npx contextmd
+```
+
+Your AI assistant finally knows your project.
+
+---
+
+## Why
+
+AI coding assistants are only as good as the context they receive. Claude Code, Cursor, Codex, and Windsurf all depend on `CLAUDE.md` and `AGENTS.md` to understand your project's architecture, conventions, and constraints — but no tooling exists to generate these files automatically.
+
+[Issue #6235](https://github.com/anthropics/claude-code/issues/6235) — "Support AGENTS.md" — is the single most-commented open issue on the claude-code repo (2,120+ comments, unresolved for 10+ months). Nobody has shipped the clean `npx contextmd` solution. Until now.
+
+---
+
+## What it does
+
+- Scans your repo (package.json, tsconfig, directory structure, git log)
+- Generates a **commit-quality** `CLAUDE.md` with all 6 required sections
+- Generates a compatible `AGENTS.md` (works with Codex, Cursor, Windsurf)
+- Infers conventions from your actual stack (Zustand → no Redux, Prisma → no raw SQL, etc.)
+- No API key. No internet connection. Zero ongoing cost.
+
+> **This repo's `CLAUDE.md` was generated with `npx contextmd` and has never been manually edited.**
+
+---
+
+## Usage
+
+```bash
+# Generate CLAUDE.md + AGENTS.md in current directory
+npx contextmd
+
+# Regenerate after making changes to the codebase
+npx contextmd sync
+
+# Audit quality of an existing CLAUDE.md (0-100 score)
+npx contextmd score
+
+# Also write .ruler/ files for ruler.js fan-out (27+ agent formats)
+npx contextmd --ruler
+```
+
+---
+
+## What gets generated
+
+`contextmd` produces the 6 sections that the [GitHub Blog analysis of 2,500+ repos](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) identifies as required for an effective context file:
+
+| Section | What it contains |
+|---|---|
+| **Commands** | Exact `dev`, `build`, `test`, `lint` invocations — including the single-test-file variant |
+| **Architecture** | Directory map with purpose of each key folder |
+| **Conventions** | Non-obvious team decisions inferred from your stack |
+| **Testing** | Runner, how to run a subset, coverage command |
+| **Git** | Commit format detected from recent history |
+| **Do NOT** | Explicit rejections of plausible alternatives the team has decided against |
+
+### Inference rules
+
+`contextmd` automatically derives conventions from your dependencies:
+
+| Dependency | Generated rule |
+|---|---|
+| `zustand` | Do not use Redux or Redux Toolkit |
+| `@tanstack/react-query` | Do not store server state in useState |
+| `prisma` | Do not write raw SQL — use Prisma ORM |
+| `drizzle-orm` | Do not write raw SQL — use Drizzle ORM |
+| `tailwindcss` | Do not use inline styles |
+| `@commitlint/cli` | Conventional commits format |
+| `next` + `app/` | Use Server Components by default |
+| tsconfig `paths` | Use the `@/` path alias |
+
+---
+
+## Ruler integration
+
+[ruler](https://github.com/intellectronica/ruler) distributes rules to 27+ agent formats (`.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`, etc.) — but it can't generate them.
+
+`contextmd` generates the source. `ruler` handles the fan-out:
+
+```bash
+npx contextmd --ruler   # writes .ruler/rules.md and .ruler/project.md
+ruler                   # distributes to all your agent configs
+```
+
+---
+
+## Quality score
+
+```bash
+npx contextmd score
+```
+
+Audits your `CLAUDE.md` against 5 commit-readiness tests (each worth 20 pts):
+
+1. Commands are executable (can be copy-pasted and run immediately)
+2. Architecture map matches actual directory structure
+3. Conventions section encodes at least one non-obvious team decision
+4. Do NOT section has at least one explicit rejection
+5. File is under 200 lines
+
+A low-signal `CLAUDE.md` performs **worse than no file at all** — Claude is instructed to treat it as optional context. The score tells you if yours is pulling its weight.
+
+---
+
+## Compared to alternatives
+
+| Tool | npx install | Static (no API) | CLAUDE.md + AGENTS.md | Auto-sync | Score |
+|---|---|---|---|---|---|
+| **contextmd** | ✓ | ✓ | ✓ | ✓ | ✓ |
+| ClaudeForge | ✗ (Claude Code plugin) | ✗ | partial | partial | ✓ |
+| agentseed | ✓ | partial | AGENTS.md only | ✗ | ✗ |
+| `claude /init` | built-in | ✗ | CLAUDE.md only | ✗ | ✗ |
+| claudemd-gen | ✓ | ✓ | CLAUDE.md only | ✗ | ✗ |
+
+---
+
+## Team sync (coming in v0.2)
+
+The paid [contextmd.dev](https://contextmd.dev) sync layer adds:
+
+- **Auto-sync on push** — GitHub Action that keeps context files current
+- **Drift alerts** — Slack/email when files fall out of sync with the codebase
+- **Multi-repo dashboard** — health status across all repos in an org
+- **Team config** — shared `contextmd.config.json` for consistent format
+
+Solo $9/mo · Team $19/mo · Studio $29/mo
+
+---
+
+## Contributing
+
+Issues, PRs, and feedback welcome.
+
+```bash
+git clone https://github.com/walidch/contextmd
+cd contextmd
+npm install
+npm run dev
+```
+
+---
+
+## License
+
+MIT

package/bin/contextmd.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../dist/index.js').catch(err => {
+  console.error('contextmd failed to start:', err.message)
+  process.exit(1)
+})

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }