nitm-ai-dev-toolkit 5.1.0 → 5.1.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.1",
   "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,11 @@ 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). Record its absolute path in `worktree_path`.
+- 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 +351,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/factory/README.md

@@ -97,7 +97,7 @@ 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.
 
 ### 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,11 @@ 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). Record its absolute path in `worktree_path`.
+- 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 +351,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/factory/README.md

@@ -91,7 +91,7 @@ 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.
 
 ### Worktree bootstrap