feat: portable AGENTS.md output (--agents, --all) + non-interactive --yes

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Least privilege: these jobs only read the repo and run tests.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run tests
+        run: npm test
+
+  smoke:
+    # Proves the headline claim — the CLI runs non-interactively and writes files.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 20
+      - run: npm install
+      - name: Smoke test the CLI in a sample project
+        run: |
+          mkdir -p /tmp/sample && cd /tmp/sample
+          echo '{"dependencies":{"next":"14.0.0","typescript":"5.0.0"}}' > package.json
+          node "$GITHUB_WORKSPACE/src/cli.js" --all --yes
+          test -f .cursor/rules/030-nextjs.mdc && echo "✅ .mdc generated" || (echo "❌ no .mdc" && exit 1)
+          test -f AGENTS.md && echo "✅ AGENTS.md generated" || (echo "❌ no AGENTS.md" && exit 1)
+          grep -q "cursor-compose:start" AGENTS.md && echo "✅ managed markers present" || (echo "❌ no markers" && exit 1)
+          ! grep -q "alwaysApply:" AGENTS.md && echo "✅ AGENTS.md is plain markdown" || (echo "❌ frontmatter leaked into AGENTS.md" && exit 1)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kabi10
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,54 +1,127 @@
+<div align="center">
+
 # cursor-compose
 
-Auto-detect your project's stack and generate Cursor project rules in one command. No cloning required.
+**Stop hand-writing AI coding rules. Detect your stack, generate them — for every tool.**
+
+One command scans your project, detects your frameworks, and writes a tailored rules file. Output a portable **`AGENTS.md`** (read by Cursor, Copilot, Codex & Claude Code) or Cursor's native `.cursor/rules/*.mdc` — from one source.
+
+[![npm version](https://img.shields.io/npm/v/cursor-compose.svg)](https://www.npmjs.com/package/cursor-compose)
+[![CI](https://github.com/Kabi10/cursor-rules/actions/workflows/ci.yml/badge.svg)](https://github.com/Kabi10/cursor-rules/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/node/v/cursor-compose.svg)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+</div>
+
+```bash
+npx cursor-compose --agents     # → AGENTS.md, works across every major AI editor
+```
+
+<!--
+  ⚠️ ADD A DEMO GIF HERE — the #1 thing that converts a visitor into a star.
+  Record with https://github.com/charmbracelet/vhs (scriptable) or asciinema + agg.
+  Show: run command → detected modules → toggle one → file written. Then update the path below.
+-->
+![demo](docs/demo.gif)
+
+---
+
+## Why
+
+Everyone is pasting the same recycled rules files between projects. They go stale, they don't match your actual stack, and every editor wants its own format.
+
+`cursor-compose` reads your **real dependencies** (`package.json`, `requirements.txt`, `pubspec.yaml`) and composes a rules file from modular, stack-specific building blocks — and writes it as the portable **`AGENTS.md`** standard so the same source works in Cursor, Copilot, Codex and Claude Code. Zero config to start.
+
+## Usage
 
 ```bash
-npx cursor-compose
+# In your project root:
+npx cursor-compose            # default → per-module .cursor/rules/*.mdc
+npx cursor-compose --agents   # → AGENTS.md (portable, cross-tool)
+npx cursor-compose --all      # → both .mdc and AGENTS.md, one pass
 ```
 
-Writes `.cursor/rules/project.mdc` — the current Cursor format. Legacy `.cursorrules` also supported.
+It will:
+1. **Scan** your project for dependency files.
+2. **Show** the modules it detected and let you toggle optional ones.
+3. **Write** your chosen output(s).
 
-## What it does
+No install, no config file required.
 
-1. Scans your project for `package.json`, `requirements.txt`, `pubspec.yaml`, etc.
-2. Shows which modules were detected, lets you toggle extras
-3. Writes a composed `.cursor/rules/project.mdc` to your project root
+### Flags
 
-## Detected stacks
+| Flag | Output |
+|---|---|
+| _(default)_ | per-module `.cursor/rules/*.mdc` (current Cursor format) |
+| `--agents` | `AGENTS.md` at repo root — portable across Cursor, Copilot, Codex, Claude Code |
+| `--all` | both `.mdc` and `AGENTS.md` in one pass |
+| `--legacy` | a single `.cursorrules` file |
+| `--yes`, `-y` | non-interactive: use detected modules, no prompts (great for CI/scripts) |
+| `-h`, `--help` | show help |
 
-| File found | Modules added |
-|-----------|--------------|
-| `next` in package.json | `nextjs` + `typescript` |
-| `typescript` in package.json | `typescript` |
-| `@supabase/supabase-js` | `supabase` |
-| `drizzle-orm` | `drizzle` |
-| `shadcn` / `@radix-ui` | `shadcn` |
-| `fastapi` in requirements.txt | `fastapi` |
-| `flutter:` in pubspec.yaml | `flutter` |
+### AGENTS.md is safe to hand-edit
 
-`core` is always included.
+The generated content lives between managed markers:
+
+```markdown
+<!-- cursor-compose:start -->
+# AGENTS.md
+...generated from your stack...
+<!-- cursor-compose:end -->
+
+## Your own notes (preserved on regenerate)
+```
+
+Re-running `--agents` only replaces the managed block — anything you add outside it is kept.
+
+## What it detects
+
+| Auto-detected | From |
+|---|---|
+| Next.js + TypeScript | `package.json` |
+| Supabase | `package.json` |
+| Drizzle ORM | `package.json` |
+| shadcn / Radix UI | `package.json` |
+| FastAPI | `requirements.txt` |
+| Flutter | `pubspec.yaml` |
+
+Core conventions always load by default.
 
 ## Optional modules
 
-Select these manually during init:
+Toggle these on during the interactive prompt:
 
-- `saas` — multi-tenancy, billing, feature flags
-- `ecommerce` — cart, checkout, inventory, payments
-- `claude-code` — CLAUDE.md conventions, memory system
-- `agentic` — agent loop patterns, tool use safety
+- **`saas`** — multi-tenancy, billing, auth patterns
+- **`ecommerce`** — cart, checkout, payment flows
+- **`claude-code`** — `CLAUDE.md` / documentation conventions
+- **`agentic`** — agent & tool-calling patterns
 
 ## Requirements
 
-Node.js 18+
+- Node.js 18+
+
+## Roadmap
+
+- [ ] **`cursor-compose check`** — CI command that fails the build when your committed rules drift from your actual dependencies.
+- [ ] More stacks (Django, Rails, SvelteKit, Expo).
 
-## Modular builder (advanced)
+Want a stack supported? [Open an issue](https://github.com/Kabi10/cursor-rules/issues) or send a PR — adding a module is just a markdown file (see [CONTRIBUTING.md](CONTRIBUTING.md)).
 
-If you prefer to compose rules with a script instead of `npx`, the original
-`build-rules.ps1` (Windows) and `build-rules.sh` (Unix) are still available after cloning.
+## How it works
+
+```
+src/
+  cli.js          # interactive prompt + orchestration + flags
+  detect.js       # reads dependency files → detected modules
+  compose.js      # assembles selected modules; writes .mdc / .cursorrules / AGENTS.md
+  frontmatter.js  # Cursor .mdc YAML frontmatter (not used for AGENTS.md)
+modules/          # one .md per framework — the rule building blocks
+patterns/         # reusable code-organization patterns
+```
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Adding a new module is just adding a `.md` file to `modules/`.
+New modules are welcome and easy — drop a markdown file in `modules/`. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

docs/demo.tape

@@ -0,0 +1,29 @@
+Output docs/demo.gif
+
+Set Shell bash
+Set FontSize 18
+Set Width 1100
+Set Height 680
+Set Theme "Dracula"
+Set TypingSpeed 55ms
+Set Padding 18
+
+Hide
+Type 'npx() { shift; node /workspaces/cursor-rules/src/cli.js "$@"; }'
+Enter
+Type "cd ~/ccdemo && rm -f AGENTS.md && clear"
+Enter
+Sleep 1s
+Show
+
+Sleep 1s
+Type "npx cursor-compose --agents"
+Sleep 700ms
+Enter
+Sleep 2800ms
+Enter
+Sleep 1800ms
+Type "head -16 AGENTS.md"
+Sleep 400ms
+Enter
+Sleep 3500ms

package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursor-compose",
-  "version": "1.1.0",
-  "description": "Auto-detect your stack and generate Cursor project rules (.cursor/rules/project.mdc). npx cursor-compose",
+  "version": "1.2.0",
+  "description": "Auto-detect your stack and generate AI editor rules — AGENTS.md (Cursor, Copilot, Codex, Claude Code) or Cursor .mdc. npx cursor-compose",
   "type": "module",
   "bin": {
     "cursor-compose": "src/cli.js"
@@ -11,7 +11,7 @@
     "modules/"
   ],
   "scripts": {
-    "test": "node --test tests/**/*.test.js"
+    "test": "node --test tests/*.test.js"
   },
   "dependencies": {
     "kleur": "^4.1.5",
@@ -24,8 +24,16 @@
     "cursor",
     "cursorrules",
     "cursor-ai",
+    "agents-md",
+    "agents.md",
+    "ai",
+    "llm",
+    "claude",
+    "copilot",
+    "codex",
     "developer-tools",
-    "cli"
+    "cli",
+    "npx"
   ],
   "license": "MIT",
   "homepage": "https://github.com/Kabi10/cursor-rules",