ai-project-boilerplate 1.3.2 → 1.4.0

package/.ai-project-refining-template

@@ -0,0 +1,26 @@
+# 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-boilerplate",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "CLI to scaffold AI-collaborated projects with stage-based AI instruction files",
   "bin": {
     "ai-project": "bin/cli.js"
@@ -11,7 +11,8 @@
   "files": [
     "bin",
     "template",
-    "scripts/preuninstall.js"
+    "scripts/preuninstall.js",
+    ".ai-project-refining-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>
+```