aioengine 0.1.2 → 0.1.3

package/README.md

@@ -4,14 +4,35 @@ AI change control for developers using Claude Code, Cursor, Codex, Copilot, and
 
 aioengine helps you review AI-generated code before you trust it. It scans your repo for missing guardrails, checks changed files for risky edits, and flags when AI may have wandered outside the requested task.
 
+## Quick start
+
+Run aioengine in any JavaScript or TypeScript project:
+
+```bash
+npx aioengine check
+```
+
+Then set up AI coding guardrails:
+
+```bash
+npx aioengine init
+```
+
+After your AI coding tool makes changes, review them before committing:
+
+```bash
+npx aioengine scope "update landing page headline"
+npx aioengine review
+```
+
 ## Commands
 
 ```bash
-aioengine init
-aioengine check
-aioengine scope "add init command"
-aioengine review
-aioengine rules
+npx aioengine init
+npx aioengine check
+npx aioengine scope "add init command"
+npx aioengine review
+npx aioengine rules
 ```
 
 ## Why aioengine exists
@@ -43,7 +64,7 @@ CLAUDE.md
 Run:
 
 ```bash
-aioengine init
+npx aioengine init
 ```
 
 ## `aioengine check`
@@ -66,7 +87,7 @@ Checks for:
 Run:
 
 ```bash
-aioengine check
+npx aioengine check
 ```
 
 ## `aioengine scope`
@@ -76,10 +97,10 @@ Checks whether changed files match the task you gave your AI coding tool.
 Example:
 
 ```bash
-aioengine scope "update landing page headline"
+npx aioengine scope "update landing page headline"
 ```
 
-If the task sounds like a UI change but AI modified billing, database, env, dependency, or deployment files, aioengine will flag possible scope drift.
+If the task sounds like a UI change but AI modified billing, database, env, dependency, CLI, or deployment files, aioengine will flag possible scope drift.
 
 ## `aioengine review`
 
@@ -88,7 +109,7 @@ Reviews current uncommitted changes for risky files.
 Run:
 
 ```bash
-aioengine review
+npx aioengine review
 ```
 
 aioengine will flag changes to files that often deserve extra review, such as:
@@ -108,7 +129,7 @@ Generates starter AI coding rules for Claude Code and Cursor.
 Run:
 
 ```bash
-aioengine rules
+npx aioengine rules
 ```
 
 This creates or skips:
@@ -121,13 +142,13 @@ CLAUDE.md
 ## Example workflow
 
 ```bash
-aioengine init
-aioengine check
+npx aioengine init
+npx aioengine check
 
 # Ask Claude, Cursor, Codex, or another AI coding tool to make a change.
 
-aioengine scope "update landing page headline"
-aioengine review
+npx aioengine scope "update landing page headline"
+npx aioengine review
 ```
 
 ## Current status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aioengine",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "AI change control for developers using AI coding tools.",
   "main": "./src/index.js",
   "scripts": {

package/src/index.js

@@ -62,7 +62,6 @@ function runInit() {
 
   const aioengineDir = ".aioengine";
   const configPath = path.join(aioengineDir, "config.json");
-  const claudePath = "CLAUDE.md";
   const cursorDir = ".cursor/rules";
   const cursorPath = path.join(cursorDir, "aioengine.mdc");
 
@@ -92,12 +91,7 @@ function runInit() {
     skipped.push(configPath);
   }
 
-  if (!exists(claudePath, root)) {
-    fs.writeFileSync(path.join(root, claudePath), getClaudeRules());
-    created.push(claudePath);
-  } else {
-    skipped.push(claudePath);
-  }
+  createClaudeRulesSafely(root, created, skipped);
 
   if (!exists(cursorDir, root)) {
     fs.mkdirSync(path.join(root, cursorDir), { recursive: true });
@@ -113,6 +107,14 @@ function runInit() {
   printSection("Created", created, "green");
   printSection("Skipped", skipped, "yellow");
 
+  if (skipped.includes("CLAUDE.md already exists")) {
+    console.log(
+      `\n${pc.dim(
+        "aioengine did not modify your existing CLAUDE.md. Suggested Claude rules were saved to .aioengine/suggested-claude-rules.md if that file did not already exist."
+      )}`
+    );
+  }
+
   console.log(pc.bold("Next steps:"));
   console.log(`  1. Run ${pc.cyan("aioengine check")}`);
   console.log(`  2. Make or review AI-generated changes`);
@@ -382,19 +384,13 @@ function runRules() {
 
   const root = getProjectRoot();
 
-  const claudePath = "CLAUDE.md";
   const cursorDir = ".cursor/rules";
   const cursorPath = path.join(cursorDir, "aioengine.mdc");
 
   const created = [];
   const skipped = [];
 
-  if (!exists(claudePath, root)) {
-    fs.writeFileSync(path.join(root, claudePath), getClaudeRules());
-    created.push(claudePath);
-  } else {
-    skipped.push(claudePath);
-  }
+  createClaudeRulesSafely(root, created, skipped);
 
   if (!exists(cursorDir, root)) {
     fs.mkdirSync(path.join(root, cursorDir), { recursive: true });
@@ -410,6 +406,14 @@ function runRules() {
   printSection("Created", created, "green");
   printSection("Skipped", skipped, "yellow");
 
+  if (skipped.includes("CLAUDE.md already exists")) {
+    console.log(
+      `\n${pc.dim(
+        "aioengine did not modify your existing CLAUDE.md. Suggested Claude rules were saved to .aioengine/suggested-claude-rules.md if that file did not already exist."
+      )}`
+    );
+  }
+
   console.log(pc.bold("Next step:"));
   console.log(`  Run ${pc.cyan("aioengine check")} again.`);
 }
@@ -839,6 +843,37 @@ function getDefaultConfig() {
   };
 }
 
+function createClaudeRulesSafely(root, created, skipped) {
+  const claudePath = path.join(root, "CLAUDE.md");
+  const aioengineDir = path.join(root, ".aioengine");
+  const suggestedPath = path.join(
+    root,
+    ".aioengine",
+    "suggested-claude-rules.md"
+  );
+
+  if (!fs.existsSync(aioengineDir)) {
+    fs.mkdirSync(aioengineDir, { recursive: true });
+    created.push(".aioengine");
+  }
+
+  if (!fs.existsSync(claudePath)) {
+    fs.writeFileSync(claudePath, getClaudeRules(), "utf8");
+    created.push("CLAUDE.md");
+    return;
+  }
+
+  skipped.push("CLAUDE.md already exists");
+
+  if (!fs.existsSync(suggestedPath)) {
+    fs.writeFileSync(suggestedPath, getClaudeRules(), "utf8");
+    created.push(".aioengine/suggested-claude-rules.md");
+    return;
+  }
+
+  skipped.push(".aioengine/suggested-claude-rules.md already exists");
+}
+
 function getClaudeRules() {
   return `# AI Coding Rules