ai-project-boilerplate 1.3.3 → 1.5.0

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,65 @@ 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.`);
+    }
+  }
+
+  console.log(`\nNext: Ask your AI to read:`);
+  console.log(`  ai-project-integration-plan/.ai-project-integration-instructions`);
+  console.log(`\nYour AI will decide how to integrate the boilerplate into your project.`);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-boilerplate",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "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/template/.ai-workflow

@@ -0,0 +1 @@
+unknown

package/template/AI_INSTRUCTIONS.md

@@ -14,11 +14,39 @@ Read `.ai-stage` for the current stage value.
 ## Always-Available
 - `CHANGELOG.md` — append completed work after each session
 
+## Workflow
+`.ai-workflow` lists the active workflows for this project, one per line. Each entry maps to `docs/workflows/<name>.md`.
+
+Example `.ai-workflow`:
+```
+github
+npm-publish
+```
+
+**If `.ai-workflow` is missing or every line is `unknown`:**
+- Ask the user: *"Which workflows does this project use? (e.g. github, npm-publish, gitlab)"*
+- Write the answers to `.ai-workflow`, one per line
+- Do not proceed with any code management action until this is resolved
+
+**When to read workflow files:**
+- Do NOT read workflow files on session start or during normal coding
+- ONLY read when you are about to perform a code management action
+- Read only the workflow(s) relevant to the current action:
+
+| Action | Read this workflow |
+|--------|-------------------|
+| commit / push / PR / branch | the VCS workflow (e.g. `github`, `gitlab`) |
+| publish to a package registry | the publish workflow (e.g. `npm-publish`) |
+| release (tag + publish) | both VCS and publish workflows |
+
+If multiple workflows apply to the current action, read all of them.
+
 ## Instructions
 1. Read ONLY the file for the current stage above.
 2. Do not read other stage files unless explicitly asked.
 3. After completing work, append a summary to `CHANGELOG.md`.
 4. When the stage changes, update `.ai-stage` on the current branch.
+5. Before any code management action: check `.ai-workflow`, read the relevant `docs/workflows/*.md`, and follow it exactly.
 
 ## First-Time Setup (AI tools other than Claude Code)
 If your tool uses a dedicated instructions file (e.g. `.cursorrules` for Cursor,

package/template/docs/architecture.md

@@ -9,10 +9,12 @@
 ```
 
 ## Git Workflow
-- Every new feature or bug fix must be developed on a dedicated branch — never commit directly to `main`
+- **All changes to `main` must go through a PR — no exceptions, including version bumps and chores**
+- Every change must be developed on a dedicated branch — never commit directly to `main`
 - Branch naming:
   - `feature/<short-description>` — for new functionality
   - `fix/<short-description>` — for bug fixes
+  - `chore/<short-description>` — for version bumps, dependency updates, config changes
 ### PR Flow
 1. Create a feature or fix branch and push to remote
 2. Open a pull request targeting `main` (e.g. via `gh pr create` or your Git host's UI)

package/template/docs/workflows/github.md

@@ -0,0 +1,116 @@
+# GitHub Workflow
+
+## Branch Naming
+- **All changes to `main` must go through a PR — no exceptions**
+- Never commit directly to `main`
+- `feature/<short-description>` — new functionality
+- `fix/<short-description>` — bug fixes
+- `chore/<short-description>` — version bumps, config changes, dependency updates
+
+---
+
+## PR Flow
+
+```bash
+# 1. Create and switch to a branch
+git checkout -b feature/<short-description>
+
+# 2. Make changes, commit, and push
+git add <files>
+git commit -m "feat: describe the change"
+git push -u origin feature/<short-description>
+
+# 3. Create a pull request
+gh pr create \
+  --title "feat: describe the change" \
+  --body "$(cat <<'EOF'
+## Summary
+- <bullet points>
+
+## Test plan
+- [ ] <manual test steps>
+EOF
+)"
+
+# 4. Check CI status
+gh pr checks
+
+# 5. Merge and delete branch after approval
+gh pr merge --squash --delete-branch
+```
+
+---
+
+## Release Flow
+
+### Automated (Recommended)
+If a `scripts/release.sh` exists in the project:
+
+```bash
+# Bumps version via PR, tags commit, creates GitHub release
+./scripts/release.sh <patch|minor|major>
+
+# Then publish to registry if applicable (e.g. npm)
+npm publish
+```
+
+### Manual
+```bash
+# 1. Ensure you are on main with a clean working tree
+git checkout main && git pull origin main
+
+# 2. Bump version (no commit yet)
+npm version patch --no-git-tag-version   # or minor / major
+
+# 3. Create a release branch, commit, push, and open a PR
+git checkout -b release/v<version>
+git add package.json
+git commit -m "chore: bump version to <version>"
+git push -u origin release/v<version>
+
+gh pr create \
+  --title "chore: release v<version>" \
+  --body "Version bump to v<version>." \
+  --base main
+
+# 4. Merge the PR
+gh pr merge release/v<version> --squash --delete-branch
+
+# 5. Pull merged commit, tag it, and push the tag
+git checkout main && git pull origin main
+git tag v<version>
+git push origin v<version>
+
+# 6. Create a GitHub release
+gh release create v<version> \
+  --title "v<version>" \
+  --generate-notes
+
+# 7. Publish to registry if applicable
+npm publish
+```
+
+---
+
+## Quick Reference
+
+```bash
+# List open PRs
+gh pr list
+
+# View PR status and checks
+gh pr view
+gh pr checks
+
+# Merge current branch's PR
+gh pr merge --squash --delete-branch
+
+# List releases
+gh release list
+
+# View a release
+gh release view v<version>
+
+# Delete a release (e.g. to redo)
+gh release delete v<version>
+```

package/template/docs/workflows/npm-publish.md

@@ -0,0 +1,59 @@
+# npm Publish Workflow
+
+## Prerequisites
+- Logged in to npm: `npm whoami` (if not, run `npm login`)
+- `NODE_AUTH_TOKEN` set in CI environment for automated publishing
+
+## When to Use
+Read this file only when you are about to publish a new version to the npm registry.
+
+---
+
+## Publish Flow
+
+```bash
+# 1. Ensure you are on main with the correct version in package.json
+git checkout main && git pull origin main
+node -e "console.log(require('./package.json').version)"
+
+# 2. Dry-run to verify package contents
+npm publish --dry-run
+
+# 3. Publish with the default 'latest' tag
+npm publish
+
+# 4. Verify the published version
+npm view <package-name> version
+```
+
+### Publishing a Pre-release
+```bash
+# Publish under a dist-tag (e.g. beta, next) — does NOT affect 'latest'
+npm publish --tag beta
+
+# Verify
+npm view <package-name> dist-tags
+```
+
+---
+
+## Version Bump
+Version bumps must happen before publishing, via the VCS workflow (e.g. a PR merging a `release/vX.Y.Z` branch). Do not bump the version manually outside of that flow.
+
+---
+
+## Quick Reference
+
+```bash
+# Check who you are logged in as
+npm whoami
+
+# List all published versions
+npm view <package-name> versions --json
+
+# Deprecate a version
+npm deprecate <package-name>@<version> "<reason>"
+
+# Unpublish within 72 hours (use sparingly)
+npm unpublish <package-name>@<version>
+```

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.