nitm-ai-dev-toolkit 5.0.0 → 5.1.0

package/src/monorepo/.opencode/rules/server-client-separation.md

@@ -2,7 +2,7 @@
 
 Server and client code boundary enforcement.
 
-@.claude/rules-snippets/server-client-separation.md
+Read and follow `.claude/rules-snippets/server-client-separation.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/subagent-workflow.md

@@ -2,7 +2,7 @@
 
 Subagent workflow and orchestration patterns.
 
-@.claude/rules-snippets/subagent-workflow.md
+Read and follow `.claude/rules-snippets/subagent-workflow.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/testing-quality.md

@@ -2,7 +2,7 @@
 
 Testing standards and quality gates.
 
-@.claude/rules-snippets/testing-quality.md
+Read and follow `.claude/rules-snippets/testing-quality.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/ui-accessibility.md

@@ -2,7 +2,7 @@
 
 UI accessibility and responsive design standards.
 
-@.claude/rules-snippets/ui-accessibility.md
+Read and follow `.claude/rules-snippets/ui-accessibility.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/version-control.md

@@ -2,7 +2,7 @@
 
 Version control and commit conventions.
 
-@.claude/rules-snippets/version-control.md
+Read and follow `.claude/rules-snippets/version-control.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/what-to-avoid.md

@@ -2,7 +2,7 @@
 
 Patterns and practices to avoid.
 
-@.claude/rules-snippets/what-to-avoid.md
+Read and follow `.claude/rules-snippets/what-to-avoid.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/AGENTS.md

@@ -119,11 +119,11 @@ Each app has its own `AGENTS.md` with detailed patterns:
 
 ## OpenCode V2 Context
 
-OpenCode use with toolkit v4 requires native V2; Slim >=3.0.0 requires OpenCode >=2.0.7. Read [native setup](README.md#native-opencode-v2) before migration. All bootstrap flows run `opencode --version` before changes for confirmed OpenCode use: V1 must stop and upgrade OpenCode or remain on toolkit 3.x; missing/unparseable versions block OpenCode steps and toolkit 4.0.0 marking. Directory presence is not harness proof; other-harness-only setup is unaffected.
+OpenCode use with toolkit 4.0.0 and later requires native V2; Slim >=3.0.0 requires OpenCode >=2.0.7. Read [native setup](README.md#native-opencode-v2) before migration. All bootstrap flows run `opencode --version` before changes for confirmed OpenCode use: V1 must stop and upgrade OpenCode or remain on toolkit 3.x; missing/unparseable versions block OpenCode steps and marking the installed toolkit version (4.0.0 or later). Directory presence is not harness proof; other-harness-only setup is unaffected.
 
-Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`, `plugins`, directory-based `skills`, and `mcp.servers`. Preserve user models/providers/plugins and Slim's separate strict schema; do not host-migrate its `prompt`/`permission`/`variant` fields or silently upgrade the separate external starter. Templates register the author's native V2 `@dietrichgebert/ponytail@4.12.0` locally instead of a bundled Ponytail plugin; `opentmux` stays commented as V1-only. Remove only known obsolete toolkit Ponytail `.js`/`.mjs`/`.ts` copies after backup and approval, preserve unrelated local plugins, and merge/deduplicate upstream registration locally without editing global config. No local API port or bridge is used; plugin/runtime integration is untested.
+Use `agents`/`system`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`, `plugins`, directory-based `skills`, and `mcp.servers`. Preserve user models/providers/plugins and Slim's separate strict schema; do not host-migrate its `prompt`/`permission`/`variant` fields or silently upgrade the separate external starter. The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator; the toolkit does not register it. Bootstrap may check for it and tell the operator to install it globally, but must never add it to project config. `opentmux` stays commented as V1-only. Remove only known obsolete toolkit Ponytail `.js`/`.mjs`/`.ts` copies after backup and approval, and preserve unrelated local plugins. No local API port or bridge is used; plugin/runtime integration is untested. The Claude Code hooks in `hooks/*.json` use `${CLAUDE_PLUGIN_ROOT}` and are plugin-only: they fire only when installed through the Ponytail plugin, not from project settings.
 
-Ambient root/nested `AGENTS.md` works; config `instructions` entries do not load. `@refs` are ordinary text: explicitly read linked snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands, not unavailable V2 LSP diagnostics. Back up V1 before native conversion; converted files are incompatible with V1. Activate on the next run/restart.
+Ambient root/nested `AGENTS.md` works. Config `instructions` entries load only when the runtime injects them (OpenChamber does; other hosts may not), so do not rely on them: write explicit "Read and follow" wrappers regardless. `@refs` are ordinary text: explicitly read linked snippets. Do not set a temperature; the current runner does not send one. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands, not unavailable V2 LSP diagnostics. Back up V1 before native conversion; converted files are incompatible with V1. Activate on the next run/restart.
 
 ## Detailed Instructions
 
@@ -366,7 +366,7 @@ Subagents are typically **agent-initiated** — the coordinator decides when to
 
 ### Factory (opt-in)
 
-An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). Its seven agents are `factory-spec-writer`, `factory-builder`, `factory-reviewer-code`, `factory-reviewer-security`, `factory-reviewer-ux`, `factory-reviewer-ui`, and `factory-approver`, with wrappers in each harness's agents folder that point to the shared snippets in `.claude/agents-snippets/`. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md). Jobs name the affected apps and packages in their spec, and checks run for those with the filtered commands in [Commands](#commands).
+An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). It runs on the native `planner` (spec and plan), `implementer` (build, repair, and rework), and `reviewer` (the code, security, ux, and ui lenses, and approval) agents. Each role's Factory rules are in its brief in `.agents/skills/factory/roles/`. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md). Jobs name the affected apps and packages in their spec, and checks run for those with the filtered commands in [Commands](#commands).
 
 ## Documentation Requirements
 

package/src/monorepo/README.md

@@ -58,17 +58,17 @@ This is a monorepo managed with {{BUILD_SYSTEM}}.
 
 ### Native OpenCode V2
 
-Toolkit v4 requires **OpenCode V2 (major >=2)** for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Bootstrap, patch, and upgrade run `opencode --version` before changes (optional leading `v` accepted). V1 must stop before OpenCode customization/migration or marking toolkit 4.0.0: upgrade OpenCode or remain on toolkit 3.x. A missing CLI or unparseable version stops OpenCode steps and version marking until confirmed/installed. Confirm harness use from runtime evidence or ask, not scaffold directories; other-harness-only setup is unaffected.
+Toolkit 4.0.0 and later require **OpenCode V2 (major >=2)** for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Bootstrap, patch, and upgrade run `opencode --version` before changes (optional leading `v` accepted). V1 must stop before OpenCode customization/migration or marking toolkit 4.0.0: upgrade OpenCode or remain on toolkit 3.x. A missing CLI or unparseable version stops OpenCode steps and version marking until confirmed/installed. Confirm harness use from runtime evidence or ask, not scaffold directories; other-harness-only setup is unaffected.
 
-The template's local `plugins` array registers the author's native V2 package `@dietrichgebert/ponytail@4.12.0`, alongside `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The obsolete local Ponytail plugin is no longer bundled; no local API port or bridge is used. For existing projects, back up and obtain approval before removing only known toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies; preserve unrelated local plugins and merge/deduplicate upstream registration locally without editing global plugins. Native local plugins are discovered automatically; do not register them twice.
+The template's local `plugins` array registers `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator and is not registered by the toolkit. Bootstrap may check for it and tell the operator to install it globally, but never adds it to project config. The obsolete local Ponytail plugin is no longer bundled; no local API port or bridge is used. For existing projects, back up and obtain approval before removing only known toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies; preserve unrelated local plugins and global plugins. Native local plugins are discovered automatically. The Claude Code hooks in `hooks/*.json` use `${CLAUDE_PLUGIN_ROOT}` and are plugin-only: they fire only when installed through the Ponytail plugin, not from project settings.
 
 With approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`, `permission`, and `variant`; do not host-migrate it. The external starter is a separate package, not automatically upgraded. Plugin/runtime integration has not been tested.
 
-Use native `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`. Follow the [V2 migration guide](https://opencode.ai/v2/docs/migrate-v1) and [plugin guide](https://opencode.ai/v2/docs/build/plugins); the published schema may describe V1 and is not V2 validation authority.
+Use native `agents`/`system`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`. Follow the [V2 migration guide](https://opencode.ai/v2/docs/migrate-v1) and [plugin guide](https://opencode.ai/v2/docs/build/plugins); the published schema may describe V1 and is not V2 validation authority.
 
-Ambient root/nested `AGENTS.md` works; config `instructions` entries are not loaded. `@refs` are ordinary text: read linked snippets explicitly. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
+Ambient root/nested `AGENTS.md` works. Config `instructions` entries load only when the runtime injects them (OpenChamber does; other hosts may not), so do not rely on them: write explicit "Read and follow" wrappers regardless. `@refs` are ordinary text: read linked snippets explicitly. Do not set a temperature; the current runner does not send one. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
 
-`--env opencode` supplies minimal shared references without activating other harnesses. Back up V1, merge rather than clobber models/providers/plugins, and activate on the next run/restart. Native-converted files are incompatible with V1. Verify with installed V2; `doctor` is not runtime validation. Toolkit 4.0.0 publishing has not been executed.
+`--env opencode` supplies minimal shared references without activating other harnesses. Back up V1, merge rather than clobber models/providers/plugins, and activate on the next run/restart. Native-converted files are incompatible with V1. Verify with installed V2; `doctor` is not runtime validation.
 
 ### Native Codex
 

package/src/monorepo/factory/README.md

@@ -1,17 +1,17 @@
 # Factory (opt-in)
 
-A file-driven pipeline for feature-sized work. One orchestrator session runs a feature through intake → spec → plan → build → review → approve → merge. Agents get their context only from files, and each agent writes only its own file. Feature docs live in `docs/features/`, and job state lives here in `factory/jobs/`.
+A file-driven pipeline for feature-sized work. One orchestrator session runs a feature through intake → spec → plan → build → review → approve → merge. Agents get their context only from files, and each agent writes only its own file. Feature docs live in feature folders (see Feature folders), and job state lives here in `factory/jobs/`.
 
 The factory is **opt-in**. It sits alongside Feature Builder and TDD and changes nothing they do. Nothing runs until you invoke `/factory`. Quick fixes stay direct.
 
-Orchestrator: [.agents/skills/factory/SKILL.md](../.agents/skills/factory/SKILL.md). Its agents have wrappers in `.claude/agents/`, `.github/agents/`, `.cursor/agents/`, and `.opencode/agents/`. See [Harnesses](#harnesses).
+Orchestrator: [.agents/skills/factory/SKILL.md](../.agents/skills/factory/SKILL.md). It runs on the native `planner`, `implementer`, and `reviewer` agents, and its role briefs live in `.agents/skills/factory/roles/`. See [Harnesses](#harnesses).
 
 ## Install
 
 1. **Install it.** The toolkit installer copies this folder into your project root as `factory/`.
-2. **Document your commands in `AGENTS.md`.** Agents read setup, dev, test, lint, and build commands from there, and the dev command must document how to pass a port (a flag or an env var). In a monorepo, document the root commands and the filtered form for each app and package, for example `--filter=<app>`. Without them the factory stops and asks you.
-3. **Replace the placeholders** below in `.agents/skills/factory/SKILL.md` and `.claude/agents-snippets/factory-*.md`. Bootstrap does this when it runs.
-4. **Commit** `factory/README.md`, `factory/.gitignore`, and the factory agents and skill. Runtime state is ignored (see Layout). Feature docs in `docs/features/` are committed with the code.
+2. **Document your commands in `AGENTS.md`.** Agents read setup, dev, test, lint, and build commands from there, and the dev command must document how to pass a port (a flag or an env var). In a monorepo, document the root commands and the filtered form for each app and package, for example `--filter=<app>`. Without them the factory stops and asks you. Edit `factory/worktree-bootstrap.md` for the setup each new worktree needs (see Build location).
+3. **Replace the placeholders** below in `.agents/skills/factory/SKILL.md` and `.agents/skills/factory/roles/*.md`. Bootstrap does this when it runs.
+4. **Commit** `factory/README.md`, `factory/.gitignore`, and the factory skill with its role briefs. Runtime state is ignored (see Layout). Feature docs in the feature folders are committed with the code.
 5. **Run it** from your harness: `/factory <feature request>` to start from a request, or `/factory start <KEY | slug | job-id>` to pick up an existing feature. See [Harnesses](#harnesses) for each entry point.
 
 ## Placeholders
@@ -22,6 +22,8 @@ Orchestrator: [.agents/skills/factory/SKILL.md](../.agents/skills/factory/SKILL.
 | FACTORY_PORT_BASE | Base dev-server port. Job `n` uses builder `base + 10n`, ux `+1`, ui `+2` | `5100` |
 | APPROVAL_MODE | `human`: stop at `awaiting-human` for `/factory approve`. `auto`: merge on `APPROVE` | `human` |
 | FACTORY_REVIEW_LENSES | Comma list from `code, security, ux, ui` | `code, security` |
+| FACTORY_FEATURE_PATHS | Feature-folder roots, comma list, relative to the repo root. `*` matches one folder name. Search covers every root. New folders go to the first root without `*`, or to a `*` root when the request's code sits in one app | monorepo: `apps/*/docs/features, docs/features`; repo: `docs/features` |
+| MERGE_MODE | `local`: `--no-ff` merge here, never pushed. `push-mr`: push and open a merge or pull request (see Merge modes). Any other value is `local` | `local` |
 
 `ux` and `ui` need browser tooling to verify anything. Without it they report every check as `Not verified`, and the job goes straight to `needs-human`. Enable them only when your agents can drive a browser.
 
@@ -31,13 +33,13 @@ Orchestrator: [.agents/skills/factory/SKILL.md](../.agents/skills/factory/SKILL.
 | --- | --- |
 | `/factory <request>` | Intake: the orchestrator reads the project and the features it touches, asks only the glaring questions, then asks you to continue or change the answers. Nothing is created before that |
 | `/factory start <request \| KEY \| slug \| job-id>` | Find or create the feature folder, then start a job, or resume the open job for it (for example one waiting at a gate) |
-| `/factory approve <job-id>` | Merge a job in `awaiting-human` or `needs-human`. On a `merged` job, moves its tickets to Done |
+| `/factory approve <job-id>` | Merge a job in `awaiting-human` or `needs-human` (`local`), or open its merge request (`push-mr`; approve again once the forge has merged it, to finish). On a `merged` job, moves its tickets to Done |
 | `/factory rework <job-id> <note>` | Start a fresh builder with your note and a fresh retry budget |
 | `/factory abandon <job-id>` | Close a job that will not continue. Nothing is merged. Removes its worktree and branch only when the branch has no unmerged commits. Tickets stay as they are |
 | `/factory status [--all]` | Summarize open jobs from their `job.json` files. Closed jobs are hidden unless `--all` |
 | `/factory watch [--all]` | Show the status table, then print the command for the live view to run in a terminal (read-only). Closed jobs are hidden unless `--all` |
 | `/factory archive [--all] [--dry-run]` | Move closed jobs to `factory/archive/`. Open jobs never move. See [Archive](#archive) |
-| `/factory prune [--all] [--abandoned] [--dry-run]` | Permanently delete closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation. Open jobs and `docs/features/` are never touched. See [Prune](#prune) |
+| `/factory prune [--all] [--abandoned] [--dry-run]` | Permanently delete closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation. Open jobs and feature folders are never touched. See [Prune](#prune) |
 
 `--in-place` can follow either form (`/factory --in-place <request>`, `/factory start --in-place <...>`). It builds in the main checkout instead of a worktree. See [In-place builds](#in-place-builds).
 
@@ -45,24 +47,32 @@ There is no queue. Start each feature with a request, a ticket key, or a slug.
 
 ## Harnesses
 
-The orchestrator and agents are the same in every harness. Each harness has its own entry point and agent wrappers. Every wrapper points to the shared snippets in `.claude/agents-snippets/`.
+The orchestrator and agents are the same in every harness. Each harness has its own entry point. Every role runs on a native agent: `planner` for the spec writer, `implementer` for the builder, and `reviewer` for each review lens and the approver, with the lens or approval mode named in the dispatch. The role briefs in `.agents/skills/factory/roles/` hold the Factory rules.
 
-| Harness | Entry point | Agent wrappers |
+| Harness | Entry point | Native agents |
 | --- | --- | --- |
 | Claude Code | `/factory` (`.claude/commands/factory.md`) | `.claude/agents/` |
 | GitHub Copilot | `/factory` prompt (`.github/prompts/factory.prompt.md`) | `.github/agents/` |
 | Cursor | `/factory` (`.cursor/commands/factory.md`) | `.cursor/agents/` |
 | OpenCode | `/factory` (`.opencode/commands/factory.md`) | `.opencode/agents/` |
-| Codex | The factory skill (`.agents/skills/factory/SKILL.md`) | None. Runs the snippets directly, one role at a time in one session (see Harness notes in SKILL.md) |
+| Codex | The factory skill (`.agents/skills/factory/SKILL.md`) | None. Runs each role brief directly, one role at a time in one session (see Harness notes in SKILL.md) |
+
+In OpenCode with the Slim plugin, `oracle` and `designer` are optional alternatives to `reviewer`, if you configure them as edit-denied. The default is the native agents.
 
 ## Feature folders and sizing
 
-Each job belongs to a feature folder, `docs/features/<KEY>-<slug>/` (or `docs/features/<slug>/` before a ticket exists). Feature folders always live at the repository root, even in a monorepo. Factory jobs do not use `apps/<app>/docs/features/`; the per-app docs rules cover app docs only. The spec writer puts `spec.md` there. Then the plan step adds `plan.md`, which carries the size, and, for large work, a slim `tasks.md`, one line per task:
+Each job belongs to a feature folder: `docs/features/<KEY>-<slug>/` at the repository root, or `apps/<app>/docs/features/<KEY>-<slug>/` for work in one app (`<slug>` in place of `<KEY>-<slug>` before a ticket exists). The roots come from `FACTORY_FEATURE_PATHS`. The spec writer puts `spec.md` there. Then the plan step adds `plan.md`, which carries the size, and, for large work, a slim `tasks.md`, one line per task:
 
 ```
 - [ ] T1 <one-line task> [P] — PROJ-1235
 ```
 
+Where a new folder goes:
+
+- Code in one app: `apps/<app>/docs/features/`. The per-app docs rules still cover the app's own docs.
+- Code in several apps, or none: the root `docs/features/`.
+- An existing folder stays where it is. Every root in `FACTORY_FEATURE_PATHS` is searched.
+
 Sizing is decided in `plan.md`:
 
 - **Small** (one or two steps): `spec.md` and `plan.md` only, no tickets.
@@ -89,16 +99,31 @@ Any value other than exactly `auto` is treated as `human`.
 
 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`.
 
+### Worktree bootstrap
+
+Before the builder starts in a new worktree, the factory runs the steps listed in `factory/worktree-bootstrap.md`: one shell command per line, in order, from the worktree root. Typical steps install dependencies or vendored packages, copy `.env` from the main checkout, and create or migrate a database for the job. The file ships with no active steps, so edit it for your project. Each step receives `FACTORY_JOB_ID`, `FACTORY_PORT_BUILDER`, `FACTORY_WORKTREE`, and `FACTORY_MAIN_CHECKOUT`.
+
+Steps must be safe to run again, because rework reruns them. A failing step stops the build and writes `bootstrap.md` in the job folder. Fix the cause, then run `/factory rework <job-id>`. In-place builds skip the bootstrap.
+
 ### In-place builds
 
 Ask for an in-place build with `--in-place`, or by saying so at intake or at the plan gate. The build then runs in the main checkout, on branch `factory/<id>`.
 
-- The job starts only when the main checkout is on the default branch with no tracked changes outside `docs/features/`, no other in-place job is open, and no worktree job holds its build location. Otherwise the job waits at the plan gate and says why.
+- The job starts only when the main checkout is on the default branch with no tracked changes outside the feature folders, no other in-place job is open, and no worktree job holds its build location. Otherwise the job waits at the plan gate and says why.
 - While the job is open, the main checkout stays on `factory/<id>`. Do not switch it until the job is merged or abandoned.
 - The feature docs are committed on the branch when the build starts, so the main checkout has no tracked feature-doc changes to block a merge.
 - The merge switches the main checkout back to the default branch and removes only the branch, not a worktree.
 - A worktree job cannot merge while an in-place job holds its build location, and an in-place job cannot start while a worktree job holds one. Each refusal names the job in the way.
 
+## Merge modes
+
+Set `MERGE_MODE`. The approval gates are the same in both modes.
+
+- **`local`** (default). The merge runs in the main checkout: `--no-ff`, the test commands, then the worktree and branch are removed. Nothing is pushed. Use it for a solo repo with no forge review.
+- **`push-mr`**. Approve pushes `factory/<id>` after a local test run, then opens a merge request (GitLab, `glab mr create`) or a pull request (GitHub, `gh pr create`). The job waits in `awaiting-human` with the request's URL. Review and merge it on the forge, then run `/factory approve <job-id>` again. That run removes the worktree and branch and moves tickets to Done. It needs the matching CLI, authenticated.
+
+`push-mr` suits forge-reviewed setups, where required reviews or CI gates sit on the forge after your approval. It never force-pushes and never merges locally. Under `auto`, approve opens the request without a pause, but the forge merge and the second `/factory approve` stay yours.
+
 ## Suggested checks (`qa.md`)
 
 The builder writes `qa.md` in the feature folder, on the job's branch. It has how to run the feature (dev server, port, seed data, flags), numbered manual checks tied to acceptance criteria, and what the automated tests do not cover. When a job waits for you, the orchestrator prints it with the reviewers' `Not verified` items under the line `Suggested checks before /factory approve — not a gate`. It is a checklist. It never affects a verdict, and a missing `qa.md` is only noted.
@@ -111,7 +136,7 @@ When a job is tracked, its tickets follow it:
 | --- | --- |
 | Build starts | In Progress |
 | Review starts | In Review |
-| You approve and the merge runs | Done |
+| The merge completes: the local merge, or a `push-mr` request merged and finished with approve | Done |
 | Job abandoned | Left as they are |
 
 The parent and every sub-task move together. The orchestrator uses the project's status names, and asks once for them if it does not know them. A failed ticket update is recorded in the job and reported. It never blocks the pipeline.
@@ -119,22 +144,22 @@ The parent and every sub-task move together. The orchestrator uses the project's
 ## How a job runs
 
 1. **Intake.** For `/factory <request>`, the orchestrator reads the project and asks only the glaring questions. You answer them, then choose to continue or change the answers. Nothing is created before you continue.
-2. **Spec.** `factory-spec-writer` inspects the code and writes `spec.md` with numbered acceptance criteria.
+2. **Spec.** `planner` (spec mode) inspects the code and writes `spec.md` with numbered acceptance criteria.
 3. **Spec gate.** You confirm the spec, or request changes.
-4. **Plan.** `factory-spec-writer` in plan mode writes `plan.md` (with the size) and `tasks.md` for large work.
+4. **Plan.** `planner` in plan mode writes `plan.md` (with the size) and `tasks.md` for large work.
 5. **Plan gate.** You confirm the plan, or request changes. Nothing is ticketed or built before you confirm.
-6. **Tickets and build location.** If tracked, the parent and sub-tasks are created and their keys are written into `tasks.md`. The folder is renamed to carry the key. Then a builder gets its own git worktree on branch `factory/<id>`, or the in-place branch. The job's feature docs are committed on that branch.
+6. **Tickets and build location.** If tracked, the parent and sub-tasks are created and their keys are written into `tasks.md`. The folder is renamed to carry the key. Then a builder gets its own git worktree on branch `factory/<id>` (bootstrapped first, see Build location), or the in-place branch. The job's feature docs are committed on that branch.
 7. **Build.** The builder follows TDD, ticks `tasks.md` as it completes tasks, writes `build.md`, and writes `qa.md`.
-8. **Review.** Every configured lens reviews the branch, writing `round-N/review-<lens>.md` with `VERDICT: PASS` or `VERDICT: CHANGES`.
+8. **Review.** Every configured lens reviews the branch, and each reviewer's report is saved as `round-N/review-<lens>.md` with `VERDICT: PASS` or `VERDICT: CHANGES`.
 9. **Repair.** Any `CHANGES` sends the builder back to fix it. Two repairs at most, so three review rounds. Then the job escalates to you.
-10. **Approve.** `factory-approver` writes `decision.md` with `APPROVE` or `ESCALATE`.
-11. **Merge.** Local only, never pushed. `--no-ff` merge, the project's test command, then the worktree (if any) and branch are removed. Feature docs in the main checkout are set aside first (copies in `main-copies/`), so the merge brings in the branch's committed copies.
+10. **Approve.** `reviewer` in approval mode (fresh context) returns `APPROVE` or `ESCALATE`, and the orchestrator writes it to `decision.md`.
+11. **Merge.** `local` mode: local only, never pushed. `push-mr` mode: push and open the request, then finish on the second approve (see Merge modes). `--no-ff` merge, the test commands for the affected apps and packages, then the worktree (if any) and branch are removed. Feature docs in the main checkout are set aside first (copies in `main-copies/`), so the merge brings in the branch's committed copies.
 
 Jobs that escalate (`needs-human`) keep their branch and worktree so you can inspect them. Use `/factory rework` or `/factory approve` to continue.
 
 ## Abandon
 
-`/factory abandon <job-id>` closes a job that will not continue. It merges nothing. The worktree and branch are removed only when the branch has no unmerged commits. Every job that reached its build keeps its branch and worktree, because its feature-docs commit is unmerged; review them and remove the branch yourself when you are done. Tickets stay where they are, and the report lists their keys. An abandoned job cannot be resumed: `/factory start <slug or KEY>` starts a new one.
+`/factory abandon <job-id>` closes a job that will not continue. It merges nothing. The worktree and branch are removed only when the branch has no unmerged commits. Every job that reached its build keeps its branch and worktree, because its feature-docs commit is unmerged; review them and remove the branch yourself when you are done. Tickets stay where they are, and the report lists their keys. A `push-mr` request stays open on the forge; the report gives its URL for the operator to close. An abandoned job cannot be resumed: `/factory start <slug or KEY>` starts a new one.
 
 ## Archive
 
@@ -147,14 +172,14 @@ Jobs that escalate (`needs-human`) keep their branch and worktree so you can ins
 
 ## Prune
 
-`/factory prune [--all] [--abandoned] [--dry-run]` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`. By default only `merged` jobs are deleted; `--abandoned` also deletes `abandoned` jobs. The age rule is the same as archive: jobs last updated more than 7 days ago, and `--all` drops the age limit. The list comes first, and nothing is deleted until you confirm once in chat. A pruned job cannot be recovered. Open jobs and `docs/features/` are never touched.
+`/factory prune [--all] [--abandoned] [--dry-run]` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`. By default only `merged` jobs are deleted; `--abandoned` also deletes `abandoned` jobs. The age rule is the same as archive: jobs last updated more than 7 days ago, and `--all` drops the age limit. The list comes first, and nothing is deleted until you confirm once in chat. A pruned job cannot be recovered. Open jobs and feature folders are never touched.
 
 Without `--abandoned`, abandoned jobs are kept and counted, and the flow offers to rerun with it. When abandoned jobs are pruned, each one whose branch still exists gets the same per-branch question as archive. Merged branches are only listed. `npx nitm-ai-dev-toolkit factory prune` lists by default; add `--yes` to delete (and `--abandoned` to include abandoned jobs).
 
 ## Layout
 
 ```
-docs/features/            tracked by the project
+<feature root>/           tracked by the project (roots: FACTORY_FEATURE_PATHS)
   <KEY>-<slug>/
     spec.md
     plan.md
@@ -163,9 +188,10 @@ docs/features/            tracked by the project
 factory/
   README.md               this file
   .gitignore              ignores jobs/ and archive/
+  worktree-bootstrap.md   setup steps run in each new worktree (edit for your project)
   jobs/                   runtime state (ignored by git)
     <NNN-slug>/
-      job.json            stage, round, reviews, size, tracking, worktree, failed_stage, approval mode
+      job.json            stage, round, reviews, size, tracking, worktree, mr, failed_stage, approval mode
       intake.md           intake questions and answers (only when asked)
       spec-<k>.md         after a change request at the spec gate
       plan-<k>.md         after a change request at the plan gate
@@ -173,6 +199,7 @@ factory/
       round-<N>/review-<lens>.md
       decision.md
       merge-conflict.md   after a merge conflict; blocks approve
+      bootstrap.md        after a failed worktree bootstrap step; blocks the build
       rework-<k>.md
       main-copies/        feature docs moved aside at merge
   archive/                closed jobs moved by /factory archive (ignored by git)
@@ -187,7 +214,7 @@ Stages, in order: `spec`, `awaiting-spec`, `plan`, `awaiting-plan`, `build`, `re
 
 - **Write boundaries are conventions.** Each agent is told which files it writes, but nothing enforces that. The real gates are the spec and plan gates, the reviewer verdicts, the approver's checks, and the merge preconditions and test run.
 - **Harness behavior varies.** Parallel review and builder resume depend on the harness. If dispatch is background-only, the orchestrator polls for each file until a 15-minute default timeout (the request can set another). A timed-out agent is never re-dispatched: the job stops at `needs-human`. See Harness notes in [SKILL.md](../.agents/skills/factory/SKILL.md).
-- **Local merge only.** The factory never pushes. Open a pull request yourself if you want review on a remote.
+- **Local merge by default.** `local` never pushes. `push-mr` pushes only on approve, and only the `factory/<id>` branch. Force-push is never used.
 - **One job at a time per checkout** is the tested path. An in-place job also holds the main checkout until it merges or is abandoned.
 - **UI lenses need a browser.** Without one they cannot verify anything and the job escalates.
 - **Tickets are best-effort.** Creation failures stop at the plan gate. Transition failures are recorded and reported.

package/src/monorepo/factory/worktree-bootstrap.md

@@ -0,0 +1,32 @@
+# Worktree bootstrap (factory)
+
+The factory runs the steps below in each new job worktree, in order, before the builder starts. Edit this file for your project; it is yours after install and `upgrade` never overwrites it without `--force`.
+
+Rules:
+
+- One shell command per line. Lines starting with `#` are notes. Blank lines are skipped.
+- Each command runs from the worktree root with `sh -c`. It stops the build at the first failure.
+- Each command gets these variables:
+  - `FACTORY_JOB_ID`: the job id, such as `001-onboarding-bootstrap`. Use it to name per-job resources, such as a database.
+  - `FACTORY_PORT_BUILDER`: the builder's dev-server port. Pass it with the flag or env var that `AGENTS.md` documents.
+  - `FACTORY_WORKTREE`: the worktree path (also the current directory).
+  - `FACTORY_MAIN_CHECKOUT`: the main checkout, where ignored local files such as `.env` live.
+- Steps must be safe to run again. Rework reruns the whole list.
+- Keep secrets out of this file. Copy them from `FACTORY_MAIN_CHECKOUT` instead.
+
+The list ships with no active steps. Uncomment the ones your project needs, or replace them. Examples:
+
+```sh
+# Dependencies: pick the one AGENTS.md documents.
+# npm ci
+# pnpm install --frozen-lockfile
+# composer install --no-interaction
+# bundle install --path vendor/bundle
+# go mod vendor
+
+# Local env file, copied only when the main checkout has one and this worktree does not.
+# [ -f "$FACTORY_MAIN_CHECKOUT/.env" ] && [ ! -f .env ] && cp "$FACTORY_MAIN_CHECKOUT/.env" .env
+
+# Database for this job only. Replace with your own create and migrate commands.
+# createdb "app_${FACTORY_JOB_ID}" && DATABASE_URL="postgres:///app_${FACTORY_JOB_ID}" npm run db:migrate
+```