nitm-ai-dev-toolkit 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.0] - 2026-10-21
+
+### Changed
+
+- Factory runs on the native `planner`, `implementer`, and `reviewer` agents instead of seven `factory-*` agents. Each role's Factory rules (outputs, evidence, verdict format, escalation triggers) moved into role briefs in `.agents/skills/factory/roles/`. Reviewers and the approver return their report, and the orchestrator saves it as `round-<N>/review-<lens>.md` or `decision.md`. The gates, verdicts, approval rules, and rework flow are unchanged.
+- `doctor` lists the removed `factory-*` files as stale toolkit files (matched by path and content hash) and never deletes them. The OpenCode `factory-*` agents also match their 5.0.0 hashes, not only 5.0.1.
+- Factory dispatch states that the role brief overrides the dispatched agent's default output format and file-writing rules, and the reply's first line follows the brief.
+- The Claude `planner` agent gets `Glob` and `Bash(*)` (plan mode deletes a stale `tasks.md`); `implementer` and `reviewer` get `Glob`.
+
+### Removed
+
+- The seven `factory-*` agents (spec writer, builder, code, security, ux, and ui reviewers, approver) and their `.claude/agents-snippets/` prompts, from `.claude/agents/`, `.cursor/agents/`, `.github/agents/`, `.opencode/agents/`, and `.claude/agents-snippets/` in both templates.
+- `request.body.temperature` from every OpenCode agent file, and the AGENTS.md guidance that set it. The current OpenCode runner does not send it.
+
+### Migration
+
+- Run `patch` in each installed project, then run `doctor`. It lists the old `factory-*` files as stale. Check each listed file, then delete it by hand. Doctor does not delete anything.
+
+## [5.0.1] - 2026-10-21
+
+### 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
@@ -40,6 +80,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `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
@@ -128,6 +174,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

package/README.md

@@ -67,7 +67,7 @@ This repository serves as a **template source** for AI development instructions
 ├── .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
 ```
@@ -180,17 +180,35 @@ 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:
 
@@ -198,13 +216,13 @@ 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 |
 | --- | --- |
-| Agents | `agents`, JSON `system` (Markdown body for file agents), `request.body.temperature`, model `provider/model#variant` |
+| Agents | `agents`, JSON `system` (Markdown body for file agents), model `provider/model#variant` |
 | Permissions | Ordered `permissions` with `action`, `resource`, `effect`; `shell`/`subagent` actions; last match wins |
 | Commands | `commands`; delegated commands use `subagent` |
 | Plugins | `plugins`; options use `{ "package": "…", "options": {} }` |
@@ -213,7 +231,7 @@ 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. Do not set a temperature; the current runner does not send one. 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.
 
@@ -300,7 +318,7 @@ Templates use `{{PLACEHOLDER}}` syntax for values you need to customize. The boo
 
 ### Factory Placeholders
 
-Used by the opt-in factory (`.agents/skills/factory/SKILL.md` and `.claude/agents-snippets/factory-*.md`).
+Used by the opt-in factory (`.agents/skills/factory/SKILL.md` and `.agents/skills/factory/roles/*.md`).
 
 | Placeholder                 | Description                                                                                 | Example                  |
 | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ |
@@ -308,6 +326,8 @@ Used by the opt-in factory (`.agents/skills/factory/SKILL.md` and `.claude/agent
 | `{{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
 
@@ -640,7 +660,7 @@ The factory is an opt-in pipeline for feature-sized work. One orchestrator takes
 
 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.
+- **Agents:** `planner` (spec and plan), `implementer` (build, repair, and rework), and `reviewer` (the code, security, ux, and ui lenses, and approval, each in the mode its dispatch names). The native agents ship for Claude Code, GitHub Copilot, Cursor, and OpenCode. Each role's Factory rules are in `.agents/skills/factory/roles/`. Codex runs those briefs directly.
 - **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 |
@@ -788,7 +808,7 @@ This toolkit includes **33 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