nitm-ai-dev-toolkit 4.0.0 → 5.0.1

package/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `patch --dry-run`, persisted `--exclude`/`--only` selections in `.nitm/toolkit.json`, version pinning for `upgrade <version>`/`--version`, and `.toolkit-version` plus `.nitm/manifest.json` state tracking. `doctor` now reports version mismatches, stale files without deleting them, and supports a placeholder allowlist.
+- Added `test/opencode-wrappers.test.js` to verify explicit "Read and follow" instructions in OpenCode wrappers.
+- Factory configuration now supports `{{FACTORY_FEATURE_PATHS}}` and `{{MERGE_MODE}}` (`local` or `push-mr`), per-workspace tests during monorepo merges, and `factory/worktree-bootstrap.md`.
+
+### Changed
+
+- `bootstrap-patch` resolves versions from `.toolkit-version`, tries `npm pack` with a no-`v` git-tag fallback, and gates supported OpenCode versions without a hard-coded major.
+- OpenCode wrappers replace bare `@.claude/` imports with explicit "Read and follow" instructions. Config `instructions` loading is runtime-dependent; wrappers no longer rely on it.
+- Legacy heading-style `tasks.md` assigns one ticket per heading without rewriting the file; task numbering starts at T1, and `implement-feature` ticks tasks only under the current heading.
+- CLI supports `--dry-run`, persisted file selection, exact-version upgrades (refusing `latest`), conditional `BOOTSTRAP.md` rewrites with backups, and toolkit version/manifest tracking.
+- The template no longer registers the Ponytail OpenCode plugin (`@dietrichgebert/ponytail`); the operator installs it globally. Bootstrap may check for it and tell the operator to install it globally, but never adds it to project config.
+- `ponytail-review` permits `git diff`, `git status`, and `git show`. Document its Claude hooks as plugin-only.
+- Backfilled 4.0.1 and 3.0.x release notes.
+
+### Fixed
+
+- Removed stale "publishing not executed" and "4.x" wording.
+
+## [5.0.0]
+
+### Breaking
+
+- `/tasks` now writes a slim `tasks.md`: one checklist line per task (checkbox, ID, short description, optional `[P]`, optional ` — <ticket key>`). Details stay in `spec.md` and `plan.md`. `/assign-tasks` and `/implement-feature` read the slim lines and write ticket keys back after the em dash. Existing `tasks.md` files are not rewritten; re-run `/tasks` on a feature to convert one.
+- `upgrade` no longer overwrites your files. It used to run `install --force`. It now adds missing files and keeps existing ones (`patch` semantics), then re-emits the bootstrap handoff. Overwriting needs an explicit `upgrade --force`, which prints a warning first. Scripts that relied on `upgrade` to refresh templates must add `--force`.
+
+### Added
+
+- Factory pipeline (opt-in): `/factory <request>` takes a feature through intake, spec gate, plan gate, build, parallel lens reviews, approval, and local merge, with subcommands `start`, `approve`, `rework`, `status`, and `watch`. Nothing runs until `/factory` is invoked. Job state lives in `factory/jobs/`, which is git-ignored. Entry points ship for Claude Code, GitHub Copilot, Cursor, and OpenCode; Codex uses the orchestrator skill `.agents/skills/factory/SKILL.md`.
+- Factory gates and intake: intake reads `AGENTS.md`, related features in `docs/features/`, and the code it touches, asks at most five glaring questions, and saves the answers to `intake.md`. Every job stops at `awaiting-spec` and `awaiting-plan` in every approval mode, and nothing is ticketed or built before the operator confirms the plan. Change requests are saved as `spec-<k>.md` or `plan-<k>.md`.
+- Factory feature folders and tracking: each job belongs to `docs/features/<KEY>-<slug>/` (or `docs/features/<slug>/` before a ticket exists). `job.json` records `feature_dir`, `issue_key`, `size`, `tracking`, and `worktree`. Large work with a documented tracker creates tickets through `/assign-tasks`, writes their keys onto `tasks.md`, and moves them through In Progress, In Review, and Done. Done only follows `/factory approve`.
+- Factory builds run in a git worktree on `factory/<id>`. `--in-place` builds in the main checkout instead, and only from a clean default branch with no other in-place job open. The builder writes `qa.md` with suggested checks, printed before approval; it never gates anything.
+- Factory agents: `factory-spec-writer`, `factory-builder`, `factory-reviewer-code`, `factory-reviewer-security`, `factory-reviewer-ux`, `factory-reviewer-ui`, and `factory-approver`, with shared snippets in `.claude/agents-snippets/`. Their OpenCode wrappers use native V2 `permissions`.
+- `factory/` template folder (README, `_gitignore`) installed by default. CLI `factory status` (one-shot table) and `factory watch` (live view) are read-only over `factory/jobs/*/job.json`; `abandoned` jobs are shown as closed.
+- Factory `/factory archive [--all] [--dry-run]` moves closed jobs (`merged` or `abandoned`) from `factory/jobs/` to `factory/archive/`. By default only jobs last updated more than 7 days ago move. `--all` moves every closed job, and open jobs never move. CLI `factory archive` makes the same moves. `/factory archive` also asks before deleting an archived abandoned job's branch and worktree, and never pushes. Archived jobs are not resumable (`/factory start` says they are closed), and their ids count toward job numbering until a prune removes them.
+- Factory `/factory prune [--all] [--abandoned] [--dry-run]` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`. By default only `merged` jobs are deleted, and only those last updated more than 7 days ago. `--all` drops the age limit for merged jobs. `--abandoned` also deletes `abandoned` jobs under the same age rule. Without it, abandoned jobs are kept and counted, and the flow offers to rerun with `--abandoned`. It lists the candidates, asks once in chat, and deletes only after a yes. When abandoned jobs are pruned, it then asks, per abandoned branch, whether to delete the branch and its worktree, as archive does. Open jobs and `docs/features/` are never touched. `/factory archive` keeps its selection: merged and abandoned. CLI `factory prune` lists by default and deletes with `--yes`; `--abandoned` is accepted only by `factory prune`.
+- Link checks in `test/links.test.js`: every relative markdown link and `@path` import in `src/repo` and `src/monorepo` must resolve, and so must every scoped install (each `--env` × layout).
+
+### Changed
+
+- Factory dashboard: `factory status` and `factory watch` hide closed jobs by default and print `N closed jobs hidden (--all to show)`. `--all` shows closed jobs and archived ones.
+- Scoped installs (`--env`) also copy `.agents/skills/`, `.claude/agents-snippets/`, `.claude/prompt-snippets/`, `.claude/rules-snippets/`, and `factory/`, the shared references every harness's wrappers use.
+- Templates named `_gitignore` install as `.gitignore`, because npm drops `.gitignore` files from packages.
+- Releases publish through npm trusted publishing (OIDC, with provenance) from `.github/workflows/publish.yml`, which now also does the auto patch bump and tag (`auto-patch-tag.yml` removed). The `NPM_TOKEN` secret is no longer used.
+
+### Fixed
+
+- Scoped Cursor, Copilot, and OpenCode installs no longer leave dangling links: `.claude/rules-snippets/` is now shared by every scope, since Cursor rules link there.
+- Scoped installs share only `.agents/skills/`, so Claude/Codex ambient rules in `.agents/rules/` no longer appear in Cursor, Copilot, or OpenCode installs.
+- `doctor` placeholder scan matches names with digits (for example `{{DB2_HOST}}`), skips `templates/` blank forms, and ignores runtime-only placeholders (`ISSUE_ID`, `ISSUE_KEY`, `FEATURE_NAME`, `NAME`), so a bootstrapped project can report clean.
+- `.cursor/rules/orient-to-recent-work.mdc` skill link now resolves (`../` → `../../`).
+
+## [4.0.1] - 2026-10-20
+
+### Changed
+
+- Updated the package version for the patch release.
+
+## [4.0.0]
+
 ### Migration
 
 - Toolkit v4 / package 4.0.0 requires native OpenCode V2 for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Native host config uses plural maps, ordered permissions, skill directories, and `mcp.servers`. Back up V1 (converted files are incompatible with it), preserve user/global settings and Slim's separate strict schema, leave the external starter unchanged, and activate on the next run/restart. Config `instructions` are ignored, ambient `AGENTS.md` works, `@refs` require explicit reads, and `request.body.temperature` is preserved but not currently sent by the runner. Preserve `lsp: true`; use project checks, not unavailable V2 LSP tools. Plugin/runtime integration is untested; publishing has not been executed.
@@ -93,6 +154,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Comprehensive template review fixes: corrected `CLAUDE.md` `@import` paths (`prompt-snippets` → `rules-snippets`); fixed broken `../.agents/` skill links in `src/repo/AGENTS.md` and `src/monorepo/AGENTS.md`; updated README bundled-skills count to 32 and added `bkt-cli`/`glab-cli` rows; synced truncated monorepo rules-snippets (`agent-conduct`, `subagent-workflow`, `coding-standards`, `core-libraries`) to repo; converted inlined Cursor commands (`review-pr`, `review`, `commit-push`) to thin wrappers; aligned monorepo agent `tools:` names to Claude Code standard; fixed root `.opencode/commands` snippet imports; added missing `testing.md` rule and `component-structure.md` snippet; removed remaining `composition-api-component-structure` stale files
 - Agent tool permissions corrected across repo and monorepo templates: Planner gained write + terminal (Copilot `edit`/`runInTerminal`/`terminalLastCommand`, OpenCode `edit: allow, bash: allow`, Claude `Bash(*)`); Documenter gained `Edit` + `Bash(*)` and OpenCode `edit: allow, bash: allow`; Researcher (Claude) lost `Write` (read-only); Reviewer (Claude) lost `Write` and OpenCode gained `bash: allow` (read + terminal). Added Agent Tool & Permission Calibration step to both `bootstrap.md` files
 
+## [3.0.x]
+
+3.0.0 is not on npm; use git tag `3.0.0` (`git clone --depth 1 --branch 3.0.0 …`) or npm 3.0.15+ as a merge base.
+
+### Added
+
+- **3.0.0 (2026-06-09):** Shared Claude/Copilot instructions, prompt snippets, and expanded agent workflows.
+- **3.0.2 (2026-06-10):** `gh-cli` skill with PR review-thread resolution.
+- **3.0.7 (2026-06-22):** Ponytail skill bundle, template parity improvements, documentation pre-commit check, and `orient-to-recent-work` skill.
+- **3.0.13 (2026-07-10):** `bkt-cli` and `glab-cli` skills.
+- **3.0.15 (2026-07-11):** npm package and zero-dependency CLI for install, patch, upgrade, doctor, and starter setup; CLI tests and CI.
+- **3.0.23 (2026-09-30):** Codex added to default bootstrap.
+
+### Changed
+
+- **3.0.1–3.0.6 (2026-06-09–2026-06-12):** Aligned shared prompts/rules and command wrappers; improved OpenCode bootstrap validation, argument hints, placeholder conventions, template consistency, and agent guidance.
+- **3.0.8–3.0.14 (2026-07-06–2026-07-10):** Refined OpenCode/Cursor commands and agent templates; corrected CLI skill guidance, references, and cross-tool template consistency.
+- **3.0.18 (2026-07-11):** Allowed manual npm publishing through workflow dispatch.
+- **3.0.19–3.0.23 (2026-07-13–2026-09-30):** Improved release automation and PR-thread guidance; migrated OpenCode config to `.jsonc` and prevented plugin config overwrite.
+
 ## [0.1.0] - 2026-01-26
 
 ### Added
@@ -118,5 +199,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Documentation structure templates (`docs/features/`, `docs/fixes/`)
 - Monthly fix log template
 
-[Unreleased]: https://github.com/ninjasitm/ai-assisted-dev-toolkit/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/ninjasitm/ai-assisted-dev-toolkit/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/ninjasitm/ai-assisted-dev-toolkit/compare/v3.0.23...v4.0.0
 [0.1.0]: https://github.com/ninjasitm/ai-assisted-dev-toolkit/releases/tag/v0.1.0

package/README.md

@@ -36,6 +36,7 @@ This repository serves as a **template source** for AI development instructions
 │   │   │   ├── rules/  # Agent behavior rules (ponytail, etc.)
 │   │   │   └── skills/ # Bundled skills (TDD, debugging, etc.)
 │   │   ├── docs/       # Documentation structure templates
+│   │   ├── factory/    # Opt-in factory pipeline (README, .gitignore)
 │   │   ├── templates/  # Reusable document templates
 │   │   ├── AGENTS.md   # AI agent context template
 │   │   └── README.md   # Project README template
@@ -59,13 +60,14 @@ This repository serves as a **template source** for AI development instructions
 │       ├── apps/       # App-specific templates
 │       ├── packages/   # Package-specific templates
 │       ├── docs/       # Documentation structure templates
+│       ├── factory/    # Opt-in factory pipeline (README, .gitignore)
 │       ├── templates/  # Reusable document templates
 │       └── AGENTS.md   # Monorepo agent context
 │
 ├── .cursor/            # This toolkit's own Cursor config
 ├── .github/            # This toolkit's own GitHub config
 ├── .opencode/          # This toolkit's own OpenCode config
-│   └── plugins/        # Other local OpenCode plugins (Ponytail uses upstream)
+│   └── plugins/        # Other local OpenCode plugins (Ponytail is installed globally)
 ├── hooks/              # Claude Code / Copilot activation hooks (ponytail, etc.)
 └── AGENTS.md           # This toolkit's agent context
 ```
@@ -172,20 +174,41 @@ npx nitm-ai-dev-toolkit patch
 # Inspect the install: missing files and unresolved placeholders
 npx nitm-ai-dev-toolkit doctor
 
-# Upgrade to the latest published version
+# Upgrade to the latest published version: adds missing files and keeps your existing ones
 npx nitm-ai-dev-toolkit upgrade
 
+# Also overwrite existing files with the latest templates (back up customisations first)
+npx nitm-ai-dev-toolkit upgrade --force
+
+# Preview install/patch/upgrade without writing (exits 1 on conflicts)
+npx nitm-ai-dev-toolkit patch --dry-run
+
+# Limit to some harnesses or features (saved to .nitm/toolkit.json; --exclude "" clears it)
+npx nitm-ai-dev-toolkit patch --exclude copilot,cursor
+npx nitm-ai-dev-toolkit patch --only claude,gh-cli
+
+# Pin an exact version (resolved and printed before anything runs)
+npx nitm-ai-dev-toolkit upgrade 5.0.1
+npx nitm-ai-dev-toolkit upgrade nitm-ai-dev-toolkit@5.0.1
+npx nitm-ai-dev-toolkit upgrade --version 5.0.1 --dry-run
+
 # Scaffold the oh-my-opencode-slim starter (delegates to `npx nitm-opencode-starter install`)
 npx nitm-ai-dev-toolkit omo-slim-starter install
 ```
 
+- **`--dry-run`** (install, patch, upgrade) lists adds, overwrites, skips, conflicts and the state files it would write, and writes nothing. Install and patch exit 1 if there are conflicts. `upgrade --dry-run` runs the pinned version's own dry run, so the target must be **5.0.1 or later**.
+- **`--exclude` / `--only`** take comma-separated groups. Harnesses: `claude`, `codex`, `copilot`, `cursor`, `opencode`. Features: `factory`, `prisma`, `bkt-cli`, `gh-cli`, `glab-cli`, `acli`, `linear-cli`. Shared files (AGENTS.md, `docs/`, `hooks/`, shared skills and snippets) are never excluded. The selection is saved to `.nitm/toolkit.json` and used by later install, patch and doctor runs; `--exclude ""` clears it.
+- **`upgrade <version>`**, **`upgrade nitm-ai-dev-toolkit@<version>`** and **`--version <version>`** pin an exact version. `latest`, dist-tags and version ranges are refused. Without a version, the latest published release is used.
+- **State files:** install, patch and upgrade write `.toolkit-version` (the installed package version) and `.nitm/manifest.json` (hashes of the files the toolkit wrote). `doctor` reports a `.toolkit-version` that differs from the package version, and lists stale toolkit files it recognises. It only reports them; it never deletes anything.
+- **`.nitm/BOOTSTRAP.md`** is rewritten only when its content differs. The previous copy is first saved to `.nitm/backups/`.
+
 After `install`, ask your AI agent to read and follow `.nitm/BOOTSTRAP.md`. Harnesses that supply a toolkit `/bootstrap` wrapper can also use it; **Codex has no native toolkit `/bootstrap` command**. Use `doctor` to verify the result.
 
 ### Native OpenCode V2 (toolkit 4.0.0)
 
-Toolkit v4 requires **OpenCode V2 (major >=2)** for OpenCode use; **oh-my-opencode-slim >=3.0.0** requires **OpenCode >=2.0.7**. All repo/monorepo bootstrap, patch, and upgrade flows run `opencode --version` before changes, accepting an optional leading `v`. 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 the user confirms/installs a supported version. Confirm harness use from runtime evidence or ask; scaffold directories are not proof. 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**. All repo/monorepo bootstrap, patch, and upgrade flows run `opencode --version` before changes, accepting an optional leading `v`. 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 the user confirms/installs a supported version. Confirm harness use from runtime evidence or ask; scaffold directories are not proof. Other-harness-only setup is unaffected.
 
-Publishing 4.0.0 has not been executed. The external `nitm-opencode-starter` is a separate package, not automatically upgraded.
+The external `nitm-opencode-starter` is a separate package, not automatically upgraded.
 
 With user approval, merge this reproducible registration without replacing user/global plugins:
 
@@ -193,9 +216,9 @@ With user approval, merge this reproducible registration without replacing user/
 { "plugins": ["oh-my-opencode-slim@3.0.0"] }
 ```
 
-The toolkit root deliberately omits `plugins` to inherit user/global registrations; its existing upstream Ponytail registration is unchanged. Both target templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0` in their local `plugins` arrays, alongside `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The local `ponytail.mjs` files are removed from the toolkit root and both templates; no local API port or bridge replaces them.
+The toolkit root deliberately omits `plugins` to inherit user/global registrations. Both target templates register `opencode-mem` and `@tarquinen/opencode-dcp@latest` in their local `plugins` arrays; `opentmux` remains commented as V1-only. The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator; neither the toolkit root nor the templates register it. The local `ponytail.mjs` files are removed from the toolkit root and both templates; no local API port or bridge replaces them.
 
-For existing targets, back up and obtain approval before removing only known obsolete toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies. Preserve unrelated local plugins; merge/deduplicate upstream package registration locally where appropriate, without editing or overwriting global plugins. Native local plugins are discovered automatically, so do not register them twice. Slim's separate strict schema keeps its own `prompt`, `permission`, and `variant`: do not host-migrate plugin-owned fields. The root's no-`plugins` policy is specific to this toolkit repository, not target templates.
+For existing targets, back up and obtain approval before removing only known obsolete toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies. Preserve unrelated local plugins. Never add the Ponytail plugin to project config; if it is not installed globally, tell the operator to install it globally, without editing or overwriting global plugins. Native local plugins are discovered automatically. Slim's separate strict schema keeps its own `prompt`, `permission`, and `variant`: do not host-migrate plugin-owned fields. The root's no-`plugins` policy is specific to this toolkit repository, not target templates.
 
 | Setting | Native V2 form |
 | --- | --- |
@@ -208,13 +231,13 @@ For existing targets, back up and obtain approval before removing only known obs
 
 Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config](https://opencode.ai/v2/docs/config), [agents](https://opencode.ai/v2/docs/agents), and [plugins](https://opencode.ai/v2/docs/build/plugins) docs. The published `https://opencode.ai/config.json` schema may describe V1; it is not native V2 validation authority.
 
-**Runtime limits:** config `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text, not automatic attachments: agents must read referenced snippets explicitly. `request.body.temperature` remains in config, but the current runner does not send it. Plugin/runtime integration has not been tested. Preserve `lsp: true`, but V2 currently exposes no LSP tools or diagnostics: use project lint/typecheck/compiler commands.
+**Runtime limits:** Ambient `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, not automatic attachments: agents must read referenced snippets explicitly. `request.body.temperature` remains in config, but the current runner does not send it. Plugin/runtime integration has not been tested. Preserve `lsp: true`, but V2 currently exposes no LSP tools or diagnostics: use project lint/typecheck/compiler commands.
 
 `--env opencode` includes minimal shared references for wrappers and AGENTS-linked standards without activating other harnesses. Merge, don't clobber: back up V1, preserve models/providers and user/global plugins, and ask before changes. Native-converted files are **incompatible with V1**. Activate on the next run/restart, then check behavior with the installed V2 runtime. `doctor` checks scaffold files/placeholders, not runtime behavior; do not substitute a V1 API/schema fetch or claim checks that were not run.
 
 ### Native Codex
 
-- `--env codex` includes `.codex/`, `.agents/`, and shared context, plus `.github/instructions/` and `.claude/rules-snippets/` solely to supply the standards linked from `AGENTS.md` and those standards' wrapper source content. It does not install other harness command, agent, or config directories. These reference files neither establish Copilot/Claude use nor load automatically as Codex rules; other harness scopes are unchanged.
+- `--env codex` includes `.codex/`, `.agents/`, and shared context, plus `.github/instructions/` solely to supply the standards linked from `AGENTS.md`. The shared `.claude/rules-snippets/` standards are installed in every scope, so those standards' wrapper source content is present too. It does not install other harness command, agent, or config directories. These reference files neither establish Copilot/Claude use nor load automatically as Codex rules; other harness scopes are unchanged.
 - Codex reads `AGENTS.md` and discovers `.agents/skills/*/SKILL.md` natively. Monorepos can use more-specific nested `AGENTS.md` files for app/package guidance. Linked standards are references to read as needed, not automatically loaded Claude/Copilot rules.
 - The optional `.codex/config.toml` is deliberately comment-only: it preserves the user's inherited defaults. Codex loads project config only after the user explicitly trusts the project; the toolkit does not grant trust or set model/provider, approval, sandbox, security, or feature overrides.
 - For manual copies without `.nitm/`, provide `.claude/prompt-snippets/bootstrap.md` to Codex directly. For incremental AI-guided merges, provide `.claude/prompt-snippets/bootstrap-patch.md` as a task document; the CLI `patch` command only adds missing files.
@@ -238,6 +261,7 @@ Templates use `{{PLACEHOLDER}}` syntax for values you need to customize. The boo
 | `{{PACKAGE_MANAGER}}`     | Package manager           | `npm`, `composer`, `dotnet`, `pip`, `bundler`, `go`, `cargo`, `maven` |
 | `{{FILE_EXTENSION}}`      | File extension            | `ts`, `php`, `cs`, `py`, `rb`, `go`, `rs`, `java`                     |
 | `{{DEV_PORT}}`            | Development server port   | `3000`, `8000`, `5000`                                                |
+| `{{DEV_PORT_FLAG}}`       | Flag or env var that sets the dev port | `--port 3000`, `PORT=3000`                                |
 | `{{DEPLOY_PLATFORM}}`     | Deployment target         | `Vercel`, `AWS`, `Azure`, `Heroku`                                    |
 | `{{DATABASE}}`            | Database/ORM              | `Prisma`, `Eloquent`, `EF Core`, `SQLAlchemy`, `ActiveRecord`         |
 | `{{TEST_FRAMEWORK}}`      | Testing framework         | `Vitest`, `PHPUnit`, `xUnit`, `pytest`, `RSpec`, `JUnit`              |
@@ -260,6 +284,7 @@ Templates use `{{PLACEHOLDER}}` syntax for values you need to customize. The boo
 | Placeholder           | Description          | Example                                             |
 | --------------------- | -------------------- | --------------------------------------------------- |
 | `{{INSTALL_COMMAND}}` | Install dependencies | `npm install`, `composer install`, `dotnet restore` |
+| `{{SETUP_COMMAND}}`   | Install command      | `npm install`, `composer install`, `dotnet restore` |
 | `{{DEV_COMMAND}}`     | Run dev server       | `npm run dev`, `php artisan serve`, `dotnet watch`  |
 | `{{BUILD_COMMAND}}`   | Build for production | `npm run build`, `dotnet publish`                   |
 | `{{TEST_COMMAND}}`    | Run tests            | `npm test`, `./vendor/bin/phpunit`, `dotnet test`   |
@@ -291,6 +316,19 @@ Templates use `{{PLACEHOLDER}}` syntax for values you need to customize. The boo
 | `{{APP_3}}`                 | Third app name             | `web`, `marketing`, `landing`                           |
 | `{{PROJECT_STRUCTURE}}`     | Full project structure     | (Generated tree diagram)                                |
 
+### Factory Placeholders
+
+Used by the opt-in factory (`.agents/skills/factory/SKILL.md` and `.claude/agents-snippets/factory-*.md`).
+
+| Placeholder                 | Description                                                                                 | Example                  |
+| --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ |
+| `{{DEFAULT_BRANCH}}`        | Branch factory jobs start from and merge into                                               | `main`, `master`         |
+| `{{FACTORY_PORT_BASE}}`     | Base dev-server port. Job `n` uses `base + 10n` for the builder, `+1` for ux, and `+2` for ui | `5100`                   |
+| `{{APPROVAL_MODE}}`         | `human` stops at `awaiting-human`; `auto` merges on approval                                | `human`, `auto`          |
+| `{{FACTORY_REVIEW_LENSES}}` | Review lenses to run. `ux` and `ui` need browser tooling                                    | `code, security`         |
+| `{{FACTORY_FEATURE_PATHS}}` | Comma-separated feature documentation paths; repo default is `docs/features`, monorepo default is `apps/*/docs/features, docs/features` | `docs/features` |
+| `{{MERGE_MODE}}`            | `local` merges locally (default); `push-mr` pushes and opens a merge request                | `local`, `push-mr`       |
+
 ## Supported Ecosystems
 
 The bootstrap command supports the following language ecosystems:
@@ -616,6 +654,43 @@ The bundled skills complement custom agents:
 - **`writing-plans`** — Creating the plans that Feature Builder and TDD agents execute
 - **`test-driven-development`** — The TDD methodology that Red/Green/Refactor agents implement
 
+## Factory (opt-in, v5)
+
+The factory is an opt-in pipeline for feature-sized work. One orchestrator takes a feature through spec → plan gate → build → review → approve → merge. Each job belongs to a feature folder, `docs/features/<KEY>-<slug>/` (or `docs/features/<slug>/` before a ticket exists), which holds `spec.md` and, for large work, a slim `tasks.md`. Job state lives under `factory/jobs/<NNN-slug>/`, and each job builds in its own git worktree on branch `factory/<id>` (or in place on the job's branch, when you ask for `--in-place`).
+
+It runs alongside Feature Builder and TDD and does not replace them. Nothing runs until you invoke `/factory`. Quick fixes stay direct.
+
+- **Agents:** `factory-spec-writer`, `factory-builder`, `factory-reviewer-code`, `factory-reviewer-security`, `factory-reviewer-ux`, `factory-reviewer-ui`, and `factory-approver`. Wrappers ship for Claude Code, GitHub Copilot, Cursor, and OpenCode. Codex uses the orchestrator skill only.
+- **Setup and reference:** [`src/repo/factory/README.md`](src/repo/factory/README.md) (the monorepo copy is in `src/monorepo/factory/`). The installer copies `factory/` into your project.
+
+| Command | What it does |
+| --- | --- |
+| `/factory <feature request>` | Intake: 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 you continue |
+| `/factory start <KEY \| slug \| job-id>` | Pick up an existing feature folder by ticket key or slug, or resume its open job (for example one waiting at a gate). Add `--in-place` only for a new job |
+| `/factory approve <job-id>` | Merge a job waiting for you (`awaiting-human` or `needs-human`); on a `merged` job, move its tickets to Done |
+| `/factory rework <job-id> <note>` | Restart the builder with your note and a fresh retry budget |
+| `/factory status [--all]` | Summarize open jobs (read-only). Closed jobs are hidden unless `--all` |
+| `/factory watch [--all]` | Show the status table here, then print the command to run the live view in your terminal (read-only). Closed jobs are hidden unless `--all` |
+| `/factory archive [--all] [--dry-run]` | Move closed jobs (`merged` or `abandoned`) from `factory/jobs/` to `factory/archive/`. By default only jobs not updated for 7 days move. `--dry-run` moves nothing. Open jobs never move |
+| `/factory prune [--all] [--abandoned] [--dry-run]` | Permanently delete closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation. By default only `merged` jobs (same 7-day age rule as archive; `--all` drops the age limit). `--abandoned` also deletes `abandoned` jobs. Open jobs and `docs/features/` are never touched |
+
+**Two gates are mandatory.** Every job stops at `awaiting-spec` after the spec, and at `awaiting-plan` after the plan. At the spec gate you confirm the spec or request changes. At the plan gate you review the tasks, the size, the tracking proposal, and the build mode, then confirm or request changes. Leave either gate for later with `/factory start <job-id>`. Nothing is ticketed or built before you confirm the plan.
+
+**The builder also writes `qa.md`.** It lists how to run the feature, numbered manual checks tied to the acceptance criteria, and what the automated tests do not cover. The orchestrator shows it before approval as suggested checks. It is not a gate.
+
+**The approval gate is on by default.** With `{{APPROVAL_MODE}}` set to `human`, an approved job stops at `awaiting-human` until you run `/factory approve <job-id>`. Set `{{APPROVAL_MODE}}` to `auto` to merge on approval instead. The approver still escalates changes to auth, payments, migrations, and similar high-risk areas. Merges are local, and the factory never pushes.
+
+Check jobs from a terminal:
+
+```bash
+npx nitm-ai-dev-toolkit factory status [--all]        # one-shot table of open jobs (--all: closed too)
+npx nitm-ai-dev-toolkit factory watch [--all]         # live view: ↑/↓ to select, Enter to open, q to quit
+npx nitm-ai-dev-toolkit factory archive [--all] [--dry-run]   # move closed jobs to factory/archive/
+npx nitm-ai-dev-toolkit factory prune [--all] [--abandoned] [--dry-run]   # list merged jobs to delete; add --yes to delete them
+```
+
+`status` and `watch` read `factory/jobs/*/job.json`, write nothing, and hide closed jobs unless `--all` is passed. `archive` moves closed jobs and touches no git state. `prune` permanently deletes merged jobs from both folders, after you confirm. Pass `--abandoned` to delete abandoned jobs too. Neither touches open jobs or `docs/features/`. The factory's placeholders are listed under [Factory Placeholders](#factory-placeholders).
+
 ## AI Agent Skills
 
 Enhance your AI agents with specialized capabilities using the **Agent Skills** open format. Skills are folders of instructions, scripts, and resources that agents can discover and use to perform tasks more accurately and efficiently.
@@ -693,7 +768,7 @@ Skills are installed to `{.cursor|.agents|.github}/skills/` and automatically av
 
 ### Bundled Universal Skills
 
-This toolkit includes **32 pre-installed universal skills** in the `.agents/skills/` folder. These skills are copied automatically when you set up your project and require **no additional installation**.
+This toolkit includes **33 pre-installed universal skills** in the `.agents/skills/` folder. These skills are copied automatically when you set up your project and require **no additional installation**.
 
 | Skill                              | Description                                                                                          |
 | ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
@@ -702,6 +777,7 @@ This toolkit includes **32 pre-installed universal skills** in the `.agents/skil
 | **verification-before-completion** | Quality checks before claiming work is done. Evidence before assertions, always.                     |
 | **writing-plans**                  | Creating clear implementation plans before coding.                                                   |
 | **executing-plans**                | Following through on implementation plans systematically.                                            |
+| **factory**                        | Opt-in spec-to-merge feature pipeline with review lenses and an approval gate.                       |
 | **requesting-code-review**         | Best practices for requesting code reviews from teammates.                                           |
 | **receiving-code-review**          | Responding constructively to review feedback.                                                        |
 | **brainstorming**                  | Structured ideation and problem-solving sessions.                                                    |
@@ -732,7 +808,7 @@ This toolkit includes **32 pre-installed universal skills** in the `.agents/skil
 
 **These skills are ready to use immediately after copying the templates.** No `npx -y skills add -a <agent> <owner/repo> --skill '*' --agent github-copilot cursor` commands needed.
 
-The **ponytail** skill bundle is an integrated optional skill set from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) that adds YAGNI/stdlib/native/one-line/minimum discipline to your AI agents. It includes 6 skills, 6 commands, 7 activation hooks, and ambient agent rules. OpenCode uses the author's upstream `@dietrichgebert/ponytail@4.12.0` package, not a bundled local plugin. See [native setup](#native-opencode-v2-toolkit-400); scaffolding alone does not establish activation.
+The **ponytail** skill bundle is an integrated optional skill set from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) that adds YAGNI/stdlib/native/one-line/minimum discipline to your AI agents. It includes 6 skills, 6 commands, 7 activation hooks, and ambient agent rules. OpenCode uses the author's upstream `@dietrichgebert/ponytail` package, installed globally by the operator, not a bundled local plugin. See [native setup](#native-opencode-v2-toolkit-400); scaffolding alone does not establish activation. 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.
 
 ### Additional Recommended Skills
 
@@ -893,7 +969,7 @@ After copying templates and installing additional skills, your project will have
     │   └── SKILL.md
     ├── verification-before-completion/
     │   └── SKILL.md
-    └── ... (32 skills total)
+    └── ... (33 skills total)
 
 .cursor/                  # or .github/ for GitHub Copilot
 ├── rules/                # IDE behavior rules (from this toolkit)