nitm-ai-dev-toolkit 5.1.0 → 5.1.2

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.2] - 2026-10-21
+
+### Fixed
+
+- The `using-git-worktrees` skill uses only `.worktrees/` for project-local worktrees (the non-hidden `worktrees/` alternative is removed), expands `$HOME` in the global path, and commits the `.gitignore` change on the default branch. The Factory skill states that the worktree folder is named by the job id, not the branch, and that `factory/worktree-bootstrap.md` replaces the worktree skill's setup and baseline-test steps. The Factory README notes that tools ignoring `.gitignore` should exclude `.worktrees/`.
+
+## [5.1.1] - 2026-10-21
+
+### Fixed
+
+- Factory worktrees are created in `.worktrees/<id>/` at the repo root (the git root in a monorepo) instead of a sibling `../<repo>-factory/<id>/` folder outside the repo. The factory ensures `.worktrees/` is git-ignored.
+
 ## [5.1.0] - 2026-10-21
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "5.1.0",
+  "version": "5.1.2",
   "description": "Scaffold AI agent config (Cursor, GitHub Copilot, Claude Code, OpenCode, Codex) into any repo, then hand off to your AI agent to finish setup.",
   "bin": {
     "nitm-ai-dev-toolkit": "bin/cli.js"

package/src/monorepo/.agents/skills/factory/SKILL.md

@@ -100,7 +100,7 @@ Feature folders live under the roots in `{{FACTORY_FEATURE_PATHS}}`, relative to
   "tracker_errors": [],
   "branch": "factory/001-onboarding-bootstrap",
   "worktree": true,
-  "worktree_path": "/abs/path/to/repo-factory/001-onboarding-bootstrap",
+  "worktree_path": "/abs/path/to/repo/.worktrees/001-onboarding-bootstrap",
   "mr": null,
   "failed_stage": null,
   "stage": "awaiting-plan",
@@ -291,10 +291,12 @@ If a ticket cannot be created, stop at `awaiting-plan`. Report the lines that ha
 
 ## Worktree
 
-The default build location. Use the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill for its safety checks only. Its directory selection does not apply: the path below overrides it. Never edit `.gitignore` for the worktree.
+The default build location. Follow the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill. Factory always takes its project-local `.worktrees/` default and never the global `~/.worktrees` option, without asking.
 
 - Branch `factory/<id>` from `{{DEFAULT_BRANCH}}`.
-- Path `../<repo-name>-factory/<id>/` relative to the main checkout, where `<repo-name>` is the basename of the main checkout. Record it in `worktree_path`.
+- Path `.worktrees/<id>/` at the root of the main checkout (the git root, inside the repo folder). The folder is named by the job id, never by the branch: branch `factory/<id>` must not produce `.worktrees/factory/<id>`. Record its absolute path in `worktree_path`.
+- `factory/worktree-bootstrap.md` replaces the worktree skill's project-setup and baseline-test steps. Factory does not run those.
+- Before the first worktree, run that skill's `.gitignore` check. If it had to add `.worktrees/`, commit that on `{{DEFAULT_BRANCH}}` or tell the operator to.
 - Create it at the start of the build stage, after the plan gate and tracking. Reuse it if it exists (rework and repair).
 - Copy the job's `spec.md`, `plan.md`, and `tasks.md` (if any) from the main checkout's feature folder into the same relative path in the worktree. The builder ticks `tasks.md` there. Then run the bootstrap (next subsection) and make the feature docs commit.
 - Job state stays in the main checkout's `factory/jobs/<id>/`, never in the worktree.
@@ -350,7 +352,7 @@ PATHS
 - Main checkout (absolute): <abs>
 - Job folder (absolute): <abs>/factory/jobs/<id>
 - Feature folder (absolute, main checkout): <abs>/<feature_dir>
-- Worktree (absolute): <abs>/../<repo-name>-factory/<id>   (in-place: the main checkout)
+- Worktree (absolute): <abs>/.worktrees/<id>   (in-place: the main checkout)
 - Feature folder in worktree (absolute): <worktree>/<feature_dir>   (in-place: the main checkout's)
 - qa.md (absolute, build location): <worktree>/<feature_dir>/qa.md
 - Branch: factory/<id>

package/src/monorepo/.agents/skills/using-git-worktrees/SKILL.md

@@ -37,11 +37,10 @@ Follow this priority order:
 
 ```bash
 # Check in priority order
-ls -d .worktrees 2>/dev/null     # Preferred (hidden)
-ls -d worktrees 2>/dev/null      # Alternative
+ls -d .worktrees 2>/dev/null
 ```
 
-**If found:** Use that directory. If both exist, `.worktrees` wins.
+**If found:** Use that directory.
 
 ### 2. Check Project Configuration
 
@@ -67,21 +66,21 @@ Which would you prefer?
 
 ## Safety Verification
 
-### For Project-Local Directories (.worktrees or worktrees)
+### For Project-Local Directories (.worktrees)
 
 **MUST verify directory is ignored before creating worktree:**
 
 ```bash
 # Check if directory is ignored (respects local, global, and system gitignore)
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+git check-ignore -q .worktrees 2>/dev/null
 ```
 
 **If NOT ignored:**
 
 Fix immediately before proceeding:
 
-1. Add appropriate line to .gitignore
-2. Commit the change
+1. Add `.worktrees/` to .gitignore
+2. Commit the change on the default branch
 3. Proceed with worktree creation
 
 **Why critical:** Prevents accidentally committing worktree contents to repository.
@@ -103,11 +102,11 @@ project=$(basename "$(git rev-parse --show-toplevel)")
 ```bash
 # Determine full path
 case $LOCATION in
-  .worktrees|worktrees)
+  .worktrees)
     path="$LOCATION/$BRANCH_NAME"
     ;;
   ~/.worktrees/*)
-    path="~/.worktrees/$project/$BRANCH_NAME"
+    path="$HOME/.worktrees/$project/$BRANCH_NAME"
     ;;
 esac
 
@@ -164,8 +163,6 @@ Ready to implement <feature-name>
 | Situation                  | Action                          |
 | -------------------------- | ------------------------------- |
 | `.worktrees/` exists       | Use it (verify ignored)         |
-| `worktrees/` exists        | Use it (verify ignored)         |
-| Both exist                 | Use `.worktrees/`               |
 | Neither exists             | Check project config → Ask user |
 | Directory not ignored      | Add to .gitignore + commit      |
 | Tests fail during baseline | Report failures + ask           |

package/src/monorepo/factory/README.md

@@ -97,7 +97,9 @@ Any value other than exactly `auto` is treated as `human`.
 
 ## Build location
 
-By default each job builds in its own git worktree on branch `factory/<id>`, so the main checkout stays free. A job's `job.json` records this in `worktree` (`true`) and the worktree path in `worktree_path`.
+By default each job builds in its own git worktree on branch `factory/<id>`, so the main checkout stays free. A job's `job.json` records this in `worktree` (`true`) and the worktree path in `worktree_path`. Worktrees live in `.worktrees/<id>/` at the git root; the factory adds `.worktrees/` to `.gitignore` if it is missing.
+
+Tools that do not honor `.gitignore` (Jest/Vitest test discovery, ESLint, `tsc`, workspace globs) should exclude `.worktrees/`. The local merge runs tests in the main checkout while other job worktrees may still exist.
 
 ### Worktree bootstrap
 

package/src/repo/.agents/skills/factory/SKILL.md

@@ -100,7 +100,7 @@ Feature folders live under the roots in `{{FACTORY_FEATURE_PATHS}}`, relative to
   "tracker_errors": [],
   "branch": "factory/001-onboarding-bootstrap",
   "worktree": true,
-  "worktree_path": "/abs/path/to/repo-factory/001-onboarding-bootstrap",
+  "worktree_path": "/abs/path/to/repo/.worktrees/001-onboarding-bootstrap",
   "mr": null,
   "failed_stage": null,
   "stage": "awaiting-plan",
@@ -291,10 +291,12 @@ If a ticket cannot be created, stop at `awaiting-plan`. Report the lines that ha
 
 ## Worktree
 
-The default build location. Use the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill for its safety checks only. Its directory selection does not apply: the path below overrides it. Never edit `.gitignore` for the worktree.
+The default build location. Follow the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill. Factory always takes its project-local `.worktrees/` default and never the global `~/.worktrees` option, without asking.
 
 - Branch `factory/<id>` from `{{DEFAULT_BRANCH}}`.
-- Path `../<repo-name>-factory/<id>/` relative to the main checkout, where `<repo-name>` is the basename of the main checkout. Record it in `worktree_path`.
+- Path `.worktrees/<id>/` at the root of the main checkout (inside the repo folder). The folder is named by the job id, never by the branch: branch `factory/<id>` must not produce `.worktrees/factory/<id>`. Record its absolute path in `worktree_path`.
+- `factory/worktree-bootstrap.md` replaces the worktree skill's project-setup and baseline-test steps. Factory does not run those.
+- Before the first worktree, run that skill's `.gitignore` check. If it had to add `.worktrees/`, commit that on `{{DEFAULT_BRANCH}}` or tell the operator to.
 - Create it at the start of the build stage, after the plan gate and tracking. Reuse it if it exists (rework and repair).
 - Copy the job's `spec.md`, `plan.md`, and `tasks.md` (if any) from the main checkout's feature folder into the same relative path in the worktree. The builder ticks `tasks.md` there. Then run the bootstrap (next subsection) and make the feature docs commit.
 - Job state stays in the main checkout's `factory/jobs/<id>/`, never in the worktree.
@@ -350,7 +352,7 @@ PATHS
 - Main checkout (absolute): <abs>
 - Job folder (absolute): <abs>/factory/jobs/<id>
 - Feature folder (absolute, main checkout): <abs>/<feature_dir>
-- Worktree (absolute): <abs>/../<repo-name>-factory/<id>   (in-place: the main checkout)
+- Worktree (absolute): <abs>/.worktrees/<id>   (in-place: the main checkout)
 - Feature folder in worktree (absolute): <worktree>/<feature_dir>   (in-place: the main checkout's)
 - qa.md (absolute, build location): <worktree>/<feature_dir>/qa.md
 - Branch: factory/<id>

package/src/repo/.agents/skills/using-git-worktrees/SKILL.md

@@ -37,11 +37,10 @@ Follow this priority order:
 
 ```bash
 # Check in priority order
-ls -d .worktrees 2>/dev/null     # Preferred (hidden)
-ls -d worktrees 2>/dev/null      # Alternative
+ls -d .worktrees 2>/dev/null
 ```
 
-**If found:** Use that directory. If both exist, `.worktrees` wins.
+**If found:** Use that directory.
 
 ### 2. Check Project Configuration
 
@@ -67,21 +66,21 @@ Which would you prefer?
 
 ## Safety Verification
 
-### For Project-Local Directories (.worktrees or worktrees)
+### For Project-Local Directories (.worktrees)
 
 **MUST verify directory is ignored before creating worktree:**
 
 ```bash
 # Check if directory is ignored (respects local, global, and system gitignore)
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+git check-ignore -q .worktrees 2>/dev/null
 ```
 
 **If NOT ignored:**
 
 Fix immediately before proceeding:
 
-1. Add appropriate line to .gitignore
-2. Commit the change
+1. Add `.worktrees/` to .gitignore
+2. Commit the change on the default branch
 3. Proceed with worktree creation
 
 **Why critical:** Prevents accidentally committing worktree contents to repository.
@@ -103,11 +102,11 @@ project=$(basename "$(git rev-parse --show-toplevel)")
 ```bash
 # Determine full path
 case $LOCATION in
-  .worktrees|worktrees)
+  .worktrees)
     path="$LOCATION/$BRANCH_NAME"
     ;;
   ~/.worktrees/*)
-    path="~/.worktrees/$project/$BRANCH_NAME"
+    path="$HOME/.worktrees/$project/$BRANCH_NAME"
     ;;
 esac
 
@@ -164,8 +163,6 @@ Ready to implement <feature-name>
 | Situation                  | Action                          |
 | -------------------------- | ------------------------------- |
 | `.worktrees/` exists       | Use it (verify ignored)         |
-| `worktrees/` exists        | Use it (verify ignored)         |
-| Both exist                 | Use `.worktrees/`               |
 | Neither exists             | Check project config → Ask user |
 | Directory not ignored      | Add to .gitignore + commit      |
 | Tests fail during baseline | Report failures + ask           |

package/src/repo/factory/README.md

@@ -91,7 +91,9 @@ Any value other than exactly `auto` is treated as `human`.
 
 ## Build location
 
-By default each job builds in its own git worktree on branch `factory/<id>`, so the main checkout stays free. A job's `job.json` records this in `worktree` (`true`) and the worktree path in `worktree_path`.
+By default each job builds in its own git worktree on branch `factory/<id>`, so the main checkout stays free. A job's `job.json` records this in `worktree` (`true`) and the worktree path in `worktree_path`. Worktrees live in `.worktrees/<id>/` at the repo root; the factory adds `.worktrees/` to `.gitignore` if it is missing.
+
+Tools that do not honor `.gitignore` (Jest/Vitest test discovery, ESLint, `tsc`, workspace globs) should exclude `.worktrees/`. The local merge runs tests in the main checkout while other job worktrees may still exist.
 
 ### Worktree bootstrap