ai-project-boilerplate 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jayden Liang
+
+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.

package/README.md

@@ -0,0 +1,60 @@
+# ai-project-boilerplate
+
+CLI to scaffold AI-collaborated projects with stage-based AI instruction files.
+
+## Install
+
+```bash
+npm install -g ai-project-boilerplate
+```
+
+## Usage
+
+```bash
+ai-project <project-name>
+```
+
+Creates a new directory with the following structure:
+
+```
+<project-name>/
+  AI_INSTRUCTIONS.md   — AI router (source of truth for all AI tools)
+  CLAUDE.md            — Claude Code entry (@imports AI_INSTRUCTIONS.md)
+  .ai-stage            — current stage, tracked per branch
+  CHANGELOG.md
+  README.md
+  docs/
+    planning.md        — PLANNING stage
+    architecture.md    — CODING stage
+    testing.md         — TESTING stage
+    deployment.md      — DEPLOY stage
+```
+
+## How it works
+
+Each AI session, the AI reads only `AI_INSTRUCTIONS.md` + the one doc for the current stage.
+Stage is stored in `.ai-stage` (one line) so it travels with the branch and causes minimal merge conflicts.
+
+### Stages
+
+| Stage | Doc | Purpose |
+|-------|-----|---------|
+| PLANNING | `docs/planning.md` | Goals, requirements, decisions |
+| CODING | `docs/architecture.md` | Structure, conventions, commands |
+| TESTING | `docs/testing.md` | Test strategy, coverage rules |
+| DEPLOY | `docs/deployment.md` | Env vars, deploy steps, rollback |
+
+### Updating the stage
+
+```bash
+echo "CODING" > .ai-stage
+git add .ai-stage && git commit -m "chore: advance stage to CODING"
+```
+
+## Version check
+
+Every invocation checks npm for a newer version and prints an upgrade prompt if one exists.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+
+const REPO = "JaydenLiang/ai-project-boilerplate";
+const CURRENT_VERSION = require("../package.json").version;
+
+function fetchLatestVersion() {
+  return new Promise((resolve, reject) => {
+    const url = `https://registry.npmjs.org/ai-project-boilerplate/latest`;
+    https
+      .get(url, { headers: { "User-Agent": "ai-project-boilerplate-cli" } }, (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          try {
+            resolve(JSON.parse(data).version);
+          } catch {
+            resolve(null);
+          }
+        });
+      })
+      .on("error", () => resolve(null));
+  });
+}
+
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return 1;
+    if (pa[i] < pb[i]) return -1;
+  }
+  return 0;
+}
+
+async function checkForUpdate() {
+  const latest = await fetchLatestVersion();
+  if (latest && compareVersions(latest, CURRENT_VERSION) > 0) {
+    console.log(`\n  Update available: ${CURRENT_VERSION} → ${latest}`);
+    console.log(`  Run to update:    npm install -g ai-project-boilerplate\n`);
+    return true;
+  }
+  return false;
+}
+
+function copyTemplate(src, dest) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyTemplate(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const projectName = args[0];
+
+  // Always check for updates first
+  await checkForUpdate();
+
+  if (!projectName) {
+    console.log(`Usage: ai-project <project-name>`);
+    console.log(`       ai-project --version`);
+    process.exit(0);
+  }
+
+  if (projectName === "--version" || projectName === "-v") {
+    console.log(CURRENT_VERSION);
+    process.exit(0);
+  }
+
+  const dest = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(dest)) {
+    console.error(`Error: directory "${projectName}" already exists.`);
+    process.exit(1);
+  }
+
+  const templateDir = path.join(__dirname, "../template");
+  fs.mkdirSync(dest, { recursive: true });
+  copyTemplate(templateDir, dest);
+
+  // Replace placeholder project name in README
+  const readmePath = path.join(dest, "README.md");
+  const readme = fs.readFileSync(readmePath, "utf8");
+  fs.writeFileSync(readmePath, readme.replace("__PROJECT_NAME__", projectName));
+
+  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`);
+}
+
+main();

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "ai-project-boilerplate",
+  "version": "1.0.0",
+  "description": "CLI to scaffold AI-collaborated projects with stage-based AI instruction files",
+  "bin": {
+    "ai-project": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": ["ai", "boilerplate", "claude", "cursor", "copilot", "scaffold"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JaydenLiang/ai-project-boilerplate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JaydenLiang/ai-project-boilerplate/issues"
+  },
+  "homepage": "https://github.com/JaydenLiang/ai-project-boilerplate#readme",
+  "author": "JaydenLiang"
+}

package/template/.ai-stage

@@ -0,0 +1 @@
+PLANNING

package/template/AI_INSTRUCTIONS.md

@@ -0,0 +1,32 @@
+# AI Instructions — AI Router
+
+## Current Stage
+Read `.ai-stage` for the current stage value.
+
+## Stage → Document Map
+| Stage | Read This File | Purpose |
+|-------|---------------|---------|
+| PLANNING | `docs/planning.md` | Goals, requirements, decisions |
+| CODING | `docs/architecture.md` | Structure, conventions, commands |
+| TESTING | `docs/testing.md` | Test strategy, commands, coverage rules |
+| DEPLOY | `docs/deployment.md` | Env vars, deploy steps, rollback |
+
+## Always-Available
+- `CHANGELOG.md` — append completed work after each session
+
+## 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.
+
+## First-Time Setup (AI tools other than Claude Code)
+If your tool uses a dedicated instructions file (e.g. `.cursorrules` for Cursor,
+`.github/copilot-instructions.md` for Copilot, `.windsurfrules` for Windsurf),
+add the following line to that file so it points here:
+
+    @AI_INSTRUCTIONS.md
+
+or if `@import` is not supported, add:
+
+    See AI_INSTRUCTIONS.md for all instructions.

package/template/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+<!-- AI: append a new entry after each work session. Do not edit previous entries. -->
+<!-- Format: ## YYYY-MM-DD [Stage] — brief summary, then bullet points -->

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AI_INSTRUCTIONS.md

package/template/README.md

@@ -0,0 +1 @@
+# __PROJECT_NAME__

package/template/docs/architecture.md

@@ -0,0 +1,34 @@
+# Architecture
+
+## Stack
+<!-- Language, runtime, key dependencies -->
+
+## Directory Structure
+```
+/
+```
+
+## Key Conventions
+<!-- Naming, file organization, patterns to follow -->
+-
+
+## Commands
+```bash
+# Install
+# Build
+# Run
+# Lint
+```
+
+## Module Responsibilities
+<!-- One line per module/file explaining its role -->
+
+## Data Flow
+<!-- How data moves through the system (can be ASCII diagram) -->
+
+## Constraints & Off-Limits
+<!-- Things AI must NOT change or touch -->
+-
+
+## Next Step
+When implementation is stable and ready for tests, update `.ai-stage` to `TESTING` on this branch.

package/template/docs/deployment.md

@@ -0,0 +1,31 @@
+# Deployment
+
+## Environment Variables
+| Variable | Required | Description |
+|----------|----------|-------------|
+|          |          |             |
+
+## Deploy Steps
+```bash
+# 1.
+# 2.
+# 3.
+```
+
+## Rollback
+```bash
+# How to revert a bad deploy
+```
+
+## Environments
+| Env | URL / Target | Notes |
+|-----|-------------|-------|
+| dev |             |       |
+| prod|             |       |
+
+## Post-Deploy Checks
+<!-- What to verify after a successful deploy -->
+-
+
+## Known Risks
+-

package/template/docs/planning.md

@@ -0,0 +1,31 @@
+# Planning
+
+## Project Goal
+<!-- One sentence: what does this tool do and for whom? -->
+
+## Problem Statement
+<!-- What pain does it solve? Why does it need to exist? -->
+
+## Non-Goals
+<!-- Explicitly what this project will NOT do -->
+
+## Requirements
+### Must Have
+-
+
+### Nice to Have
+-
+
+## Key Decisions
+<!-- Record decisions HERE so AI doesn't re-litigate them -->
+| Decision | Chosen | Reason |
+|----------|--------|--------|
+|          |        |        |
+
+## Open Questions
+<!-- Unresolved items blocking progress -->
+-
+
+## Next Step
+<!-- Single next action to move to CODING stage -->
+When requirements are finalized, update `.ai-stage` to `CODING` on this branch.

package/template/docs/testing.md

@@ -0,0 +1,28 @@
+# Testing
+
+## Test Commands
+```bash
+# Run all tests
+# Run single test
+# Coverage report
+```
+
+## Coverage Requirements
+<!-- Minimum coverage %, critical paths that must be covered -->
+
+## Test Structure
+<!-- Where test files live, naming convention -->
+
+## What to Test
+<!-- Key behaviors, edge cases, known fragile areas -->
+-
+
+## What NOT to Test
+<!-- Third-party libs, trivial getters, etc. -->
+-
+
+## Known Issues / Flaky Tests
+-
+
+## Next Step
+When all critical paths are covered and tests pass, update `.ai-stage` to `DEPLOY` on this branch.