ai-project-boilerplate 1.4.0 → 1.5.1

package/.ai-project-integration-instructions-template

@@ -0,0 +1,51 @@
+# AI Project Integration Instructions
+
+The `ai-project-integration-plan/` directory has been created in your project root.
+It contains the full AI Project Boilerplate template and these integration instructions.
+
+**Project root** = the directory that contains `ai-project-integration-plan/`.
+
+---
+
+## How to Integrate
+
+### Step 1 — Assess the project
+
+Check whether the project root is empty or already has existing files:
+
+- **Empty or missing key files** (no `AI_INSTRUCTIONS.md`, `docs/`, `CHANGELOG.md`, etc.):
+  → Copy all contents from `ai-project-integration-plan/` directly to the project root. No merge needed.
+
+- **Existing project with files already present**:
+  → Review each file in `ai-project-integration-plan/` and merge or adapt as appropriate.
+  Do not overwrite existing files blindly — check for conflicts first.
+
+### Step 2 — Set the project name
+
+In `ai-project-integration-plan/README.md`, replace `__PROJECT_NAME__` with the actual project name.
+Infer it from the project root directory name, or ask the user if unclear.
+
+### Step 3 — Review and adapt each file
+
+| File | Action |
+|------|--------|
+| `AI_INSTRUCTIONS.md` | Copy to root; adapt stage map if needed |
+| `CLAUDE.md` | Copy to root |
+| `.ai-stage` | Copy to root (default: `PLANNING`) |
+| `.ai-workflow` | Copy to root; ask user which workflows apply and update accordingly |
+| `CHANGELOG.md` | Copy to root if missing; otherwise append |
+| `README.md` | Copy to root if missing; otherwise merge |
+| `docs/` | Copy missing files; do not overwrite existing ones |
+| `docs/workflows/` | Copy to root; these are reference guides, safe to copy |
+
+### Step 4 — Clean up
+
+After integration is complete, **delete the entire `ai-project-integration-plan/` directory**.
+It is a temporary scaffold and should not remain in the project.
+
+---
+
+## Notes
+
+- `.ai-workflow` defaults to `unknown` — update it with the actual workflow(s) in use (e.g. `github`, `npm-publish`)
+- If `.gitignore` does not already exclude `ai-project-integration-plan/`, add it

package/bin/cli.js

@@ -161,6 +161,12 @@ function copyTemplate(src, dest) {
   }
 }
 
+function prompt(question) {
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer); }));
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -187,72 +193,82 @@ async function main() {
 
   // Validate command
   if (args.length === 0 || args[0] !== 'init') {
-    console.log(`Usage: ai-project init <project-location> [-n <project-name>]`);
+    console.log(`Usage: ai-project init <project-location>`);
     console.log(`       ai-project --version`);
     process.exit(0);
   }
 
-  // Parse arguments: init <project-location> [-n <name>]
-  let projectLocation;
-  let customProjectName;
-  
-  // Find -n flag and its value
-  const nIndex = args.indexOf('-n');
-  if (nIndex !== -1) {
-    if (nIndex + 1 < args.length) {
-      customProjectName = args[nIndex + 1];
-    } else {
-      console.error(`Error: -n flag requires a project name argument`);
-      process.exit(1);
-    }
-  }
-
   // Get project location (first argument after 'init')
-  projectLocation = args[1];
-  if (!projectLocation || projectLocation === '-n') {
-    console.log(`Usage: ai-project init <project-location> [-n <project-name>]`);
+  const projectLocation = args[1];
+  if (!projectLocation) {
+    console.log(`Usage: ai-project init <project-location>`);
     process.exit(0);
   }
 
   const dest = path.resolve(process.cwd(), projectLocation);
+  const integrationDir = path.join(dest, 'ai-project-integration-plan');
 
-  if (fs.existsSync(dest)) {
-    // Existing project: Create .ai-project-refining from template
-    const refiningTemplateFile = path.join(__dirname, "../.ai-project-refining-template");
-    const refiningFile = path.join(dest, '.ai-project-refining');
-    const template = fs.readFileSync(refiningTemplateFile, "utf8");
-    fs.writeFileSync(refiningFile, template);
-    console.log(`\nDetected existing project: ${projectLocation}`);
-    console.log(`Created .ai-project-refining with migration guidance.`);
-    console.log(`\nNext: Review .ai-project-refining and update your project accordingly.`);
-  } else {
-    // New project: Copy template
-    const templateDir = path.join(__dirname, "../template");
-    fs.mkdirSync(dest, { recursive: true });
-    copyTemplate(templateDir, dest);
-
-    // Replace placeholder in README
-    const readmePath = path.join(dest, "README.md");
-    const readme = fs.readFileSync(readmePath, "utf8");
-    const projectName = customProjectName || path.basename(dest);
-    fs.writeFileSync(readmePath, readme.replace("__PROJECT_NAME__", projectName));
-
-    // Create .ai-stage
-    fs.writeFileSync(path.join(dest, '.ai-stage'), 'PLANNING');
-
-    console.log(`\nCreated AI-collaborated project: ${projectName}`);
-    console.log(`\nFiles created:`);
-    console.log(`  AI_INSTRUCTIONS.md   — AI router (source of truth)`);
-    console.log(`  CLAUDE.md            — Claude Code entry`);
-    console.log(`  .ai-stage            — current stage (PLANNING)`);
-    console.log(`  CHANGELOG.md`);
-    console.log(`  README.md`);
-    console.log(`  docs/planning.md`);
-    console.log(`  docs/architecture.md`);
-    console.log(`  docs/testing.md`);
-    console.log(`  docs/deployment.md`);
-    console.log(`\nNext: cd ${projectName} && fill in docs/planning.md`);
+  // Create dest if needed
+  fs.mkdirSync(dest, { recursive: true });
+
+  // Handle existing ai-project-integration-plan/
+  if (fs.existsSync(integrationDir)) {
+    const answer = await prompt('ai-project-integration-plan/ already exists. Overwrite? (y/N): ');
+    if (answer.trim().toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+    fs.rmSync(integrationDir, { recursive: true, force: true });
+  }
+
+  // Create integration plan dir and copy template into it
+  fs.mkdirSync(integrationDir, { recursive: true });
+  const templateDir = path.join(__dirname, '../template');
+  copyTemplate(templateDir, integrationDir);
+
+  // Copy .ai-project-integration-instructions-template as .ai-project-integration-instructions
+  const instructionsTemplatePath = path.join(__dirname, '../.ai-project-integration-instructions-template');
+  const instructionsDestPath = path.join(integrationDir, '.ai-project-integration-instructions');
+  fs.copyFileSync(instructionsTemplatePath, instructionsDestPath);
+
+  console.log(`\nCreated: ai-project-integration-plan/`);
+
+  // Offer to add to .gitignore
+  const gitignorePath = path.join(dest, '.gitignore');
+  const gitignoreEntry = 'ai-project-integration-plan/';
+  const alreadyIgnored = fs.existsSync(gitignorePath) &&
+    fs.readFileSync(gitignorePath, 'utf8').includes(gitignoreEntry);
+
+  if (!alreadyIgnored) {
+    const gitAnswer = await prompt(`Add ${gitignoreEntry} to .gitignore? (Y/n): `);
+    if (gitAnswer.trim().toLowerCase() !== 'n') {
+      fs.appendFileSync(gitignorePath, `\n${gitignoreEntry}\n`);
+      console.log(`.gitignore updated.`);
+    } else {
+      console.log(`Reminder: add ${gitignoreEntry} to .gitignore manually.`);
+    }
+  }
+
+  const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+  const cyan   = (s) => `\x1b[36m${s}\x1b[0m`;
+  const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
+  const strip  = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+
+  const nextLines = [
+    `   ${bold(yellow("NEXT STEP"))}`,
+    `   Ask your AI to read:`,
+    ``,
+    `   ${bold(cyan("ai-project-integration-plan/.ai-project-integration-instructions"))}`,
+  ];
+
+  const nextWidth  = Math.max(...nextLines.map(l => strip(l).length)) + 2;
+  const nextBorder = yellow("─".repeat(nextWidth));
+
+  console.log(`\n${yellow("┌")}${nextBorder}${yellow("┐")}`);
+  for (const line of nextLines) {
+    console.log(`${yellow("│")} ${line.padEnd(line.length + nextWidth - strip(line).length - 1)}${yellow("│")}`);
   }
+  console.log(`${yellow("└")}${nextBorder}${yellow("┘")}\n`);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-boilerplate",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "CLI to scaffold AI-collaborated projects with stage-based AI instruction files",
   "bin": {
     "ai-project": "bin/cli.js"
@@ -12,7 +12,7 @@
     "bin",
     "template",
     "scripts/preuninstall.js",
-    ".ai-project-refining-template"
+    ".ai-project-integration-instructions-template"
   ],
   "keywords": [
     "ai",

package/.ai-project-refining-template

@@ -1,26 +0,0 @@
-# Migration Guidance for Existing AI Project
-
-Your existing project has been detected.
-
-To integrate with the AI Project Boilerplate and refine your project for AI collaboration:
-
-1. **Review AI_INSTRUCTIONS.md**: Copy or adapt the AI_INSTRUCTIONS.md from the boilerplate to your project root. This file serves as the AI router and source of truth for project guidelines, ensuring consistent AI interactions.
-
-2. **Add CLAUDE.md**: Include CLAUDE.md for Claude Code entry points, defining how AI tools interact with your codebase.
-
-3. **Set Up docs/ Folder**: Ensure a `docs/` folder exists with at least:
-   - planning.md (project goals and roadmap)
-   - architecture.md (system design)
-   - testing.md (testing strategies)
-   - deployment.md (deployment processes)
-   Copy or adapt these from the boilerplate if needed.
-
-4. **Update CHANGELOG.md**: Maintain a changelog for version history and AI-driven changes.
-
-5. **Enhance README.md**: Update your README.md to reference AI_INSTRUCTIONS.md and include project setup for AI collaboration.
-
-6. **Add .ai-stage File (Optional)**: Create a `.ai-stage` file in the project root with initial content `PLANNING` to track the current development stage (e.g., PLANNING, DEVELOPMENT, TESTING, DEPLOYMENT).
-
-7. **Next Steps**: Fill in or update docs/planning.md. Consider integrating AI tools for code reviews and refinements.
-
-For more details, refer to the AI Project Boilerplate documentation.