nitm-ai-dev-toolkit 3.0.23 → 5.0.0

package/CHANGELOG.md

@@ -7,8 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.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.
+- Removed all three local Ponytail plugin copies (root, repo template, monorepo template). Both templates register the author's native V2 `@dietrichgebert/ponytail@4.12.0` package locally; `opentmux` remains commented as V1-only. No API port or bridge was added. The toolkit root alone omits `plugins` to inherit existing user/global registrations; no global config was changed. Existing targets remove only known obsolete toolkit Ponytail `.js`/`.mjs`/`.ts` copies after backup and approval, preserving unrelated plugins and deduplicating upstream registration locally.
+
 ### Fixed
 
+- All six repo/monorepo bootstrap flows now require a fail-closed `opencode --version` preflight before changes for confirmed OpenCode use: accept an optional leading `v`, reject V1 before OpenCode customization/migration or toolkit 4.0.0 marking, and stop on a missing CLI or unparseable version. Slim >=3.0.0 enforces OpenCode >=2.0.7; other-harness-only setup is unaffected. Focused instruction-order/version-metadata regression checks cover the guard.
 - Bootstrap audit/creation examples are explicitly conditional on confirmed Copilot use; completion reports describe performed harness-specific checks without assuming OpenCode configuration, Codex trust/loading, or Copilot/Cursor readiness. Codex-scoped install documentation now includes linked standards and their wrapper sources without implying other harness activation.
 
 ### Added
@@ -32,7 +73,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `bkt-cli` skill — Bitbucket CLI (`bkt`) command reference for repo and monorepo templates
 - `glab-cli` skill — GitLab CLI (`glab`) command reference for repo and monorepo templates
 - Ponytail skill bundle — 6 YAGNI/stdlib/native/minimum-discipline skills (`ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`)
-- Ponytail OpenCode plugin (`.opencode/plugins/ponytail.mjs`) loaded via the `plugin` config key
+- Author's upstream Ponytail OpenCode plugin registration (`@dietrichgebert/ponytail@4.12.0`) in both template configs; no bundled local plugin source
 - 7 ponytail hooks in `hooks/` (`ponytail-activate`, `ponytail-config`, `ponytail-instructions`, `ponytail-mode-tracker`, `ponytail-runtime`, `ponytail-statusline.sh`, `ponytail-statusline.ps1`), plus 2 hook configuration files for Claude/Codex and Copilot (`claude-codex-hooks.json`, `copilot-hooks.json`)
 - Ponytail rule in `.agents/rules/` and `.cursor/rules/` for ambient agent context
 - 6 ponytail commands (`ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`) with thin-wrapper sources in `.claude/prompt-snippets/`
@@ -74,7 +115,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added missing templates referenced in templates/README.md
 - `scripts/pre-commit-check.sh` — early-exit when no files are staged so the CHANGELOG check no longer fires on empty commits (PR #20 review)
 - `scripts/check-parity.sh` — removed duplicate `check_body_match` call for the cursor ↔ github prompt body (PR #20 review)
-- `.opencode/plugins/ponytail.mjs` — wrapped `writeMode` in a try/catch so an unwritable state directory no longer crashes the plugin (PR #20 review)
 - `ponytail-help` SKILL.md and prompt snippet — added missing `ponytail-audit`, `ponytail-debt`, and `/ponytail-gain` entries; corrected OpenCode slash-command count to six; rewrote the Claude-Code-specific Update section to describe the template update flow (PR #20 review)
 - `ponytail-gain` SKILL.md and prompt snippet (repo, monorepo, root) — replaced the phantom `benchmarks/` source reference with the upstream `DietrichGebert/ponytail` repo link (PR #20 review)
 - `README.md` — corrected "8 activation hooks" to "7 activation hooks" to match CHANGELOG and the actual hook count (PR #20 review)
@@ -113,5 +153,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/        # OpenCode plugins (ponytail mode manager, etc.)
+│   └── plugins/        # Other local OpenCode plugins (Ponytail uses upstream)
 ├── hooks/              # Claude Code / Copilot activation hooks (ponytail, etc.)
 └── AGENTS.md           # This toolkit's agent context
 ```
@@ -172,18 +174,52 @@ 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
+
 # Scaffold the oh-my-opencode-slim starter (delegates to `npx nitm-opencode-starter install`)
 npx nitm-ai-dev-toolkit omo-slim-starter install
 ```
 
 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.
+
+Publishing 4.0.0 has not been executed. The external `nitm-opencode-starter` is a separate package, not automatically upgraded.
+
+With user approval, merge this reproducible registration without replacing user/global plugins:
+
+```jsonc
+{ "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.
+
+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.
+
+| Setting | Native V2 form |
+| --- | --- |
+| Agents | `agents`, JSON `system` (Markdown body for file agents), `request.body.temperature`, 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": {} }` |
+| Skills | Directory-path array, e.g. `[".agents/skills"]`, not Markdown globs |
+| MCP | `mcp.servers`; `disabled` inverts legacy `enabled`; `timeout.catalog`/`timeout.execution` |
+
+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.
+
+`--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.
@@ -207,6 +243,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`              |
@@ -229,6 +266,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`   |
@@ -260,6 +298,17 @@ 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`         |
+
 ## Supported Ecosystems
 
 The bootstrap command supports the following language ecosystems:
@@ -585,6 +634,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.
@@ -662,7 +748,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                                                                                          |
 | ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
@@ -671,6 +757,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.                                                    |
@@ -701,7 +788,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, an OpenCode plugin, 7 activation hooks, and ambient agent rules — all pre-configured and ready to use.
+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.
 
 ### Additional Recommended Skills
 
@@ -862,7 +949,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)

package/bin/cli.js

@@ -9,6 +9,9 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync, spawnSync } = require('child_process');
+const factory = require('./factory-watch.js');
+const factoryArchive = require('./factory-archive.js');
+const factoryPrune = require('./factory-prune.js');
 
 const PKG_ROOT = path.join(__dirname, '..');
 const SRC_DIR = path.join(PKG_ROOT, 'src');
@@ -16,10 +19,13 @@ const SRC_DIR = path.join(PKG_ROOT, 'src');
 // Platform config dirs per harness. Claude and Codex share `.agents` (universal skills).
 const ENV_DIRS = {
   claude: ['.claude', '.agents'],
-  codex: ['.codex', '.agents', path.join('.github', 'instructions'), path.join('.claude', 'rules-snippets')],
+  codex: ['.codex', '.agents', path.join('.github', 'instructions')],
   copilot: ['.github', '.vscode'],
   cursor: ['.cursor'],
-  opencode: ['.opencode'],
+  // Shared reference sources, not other harnesses' active config/agent wrappers.
+  opencode: ['.opencode', path.join('.agents', 'skills'),
+    path.join('.claude', 'agents-snippets'), path.join('.claude', 'prompt-snippets'),
+    path.join('.github', 'instructions')],
 };
 const ENV_INFO = {
   claude: { name: 'Claude Code', command: '/bootstrap (Claude Code command in .claude/commands/)' },
@@ -30,8 +36,17 @@ const ENV_INFO = {
 };
 // Files/dirs copied for every environment (shared across harnesses).
 const SHARED_ROOT = ['AGENTS.md', 'README.md', 'CLAUDE.md', '.mcp.json'];
-const SHARED_DIRS = ['docs', 'templates', 'hooks'];
-
+// `factory` is the job queue every harness reads and writes, so it is shared.
+// Agent/skill bodies and prompt snippets are referenced by wrappers in every harness
+// (e.g. `.claude/agents-snippets/*` from Cursor and Copilot agents), so they are shared too.
+// `.claude/rules-snippets` is linked the same way from every harness's rules and instructions.
+// Only `.agents/skills` is shared: `.agents/rules` is Claude/Codex ambient config.
+const SHARED_DIRS = ['docs', 'templates', 'hooks', 'factory', path.join('.agents', 'skills'),
+  path.join('.claude', 'agents-snippets'), path.join('.claude', 'prompt-snippets'),
+  path.join('.claude', 'rules-snippets')];
+// npm drops `.gitignore` files from packages, so templates ship them as `_gitignore`
+// and install them under the real name.
+const TEMPLATE_RENAMES = { '_gitignore': '.gitignore' };
 const C = {
   reset: '\x1b[0m',
   cyan: '\x1b[36m',
@@ -82,6 +97,12 @@ function templateFiles(type) {
   return files;
 }
 
+// Path a template file is installed to (see TEMPLATE_RENAMES).
+function installName(rel) {
+  const renamed = TEMPLATE_RENAMES[path.basename(rel)];
+  return renamed ? path.join(path.dirname(rel), renamed) : rel;
+}
+
 // Restrict the file set to the chosen environment (shared + that env's dirs).
 function scopeFiles(files, env) {
   if (!env || !ENV_DIRS[env]) return files;
@@ -102,7 +123,8 @@ function copyMissing(type, cwd, force, env) {
   let skipped = 0;
   for (const rel of files) {
     const from = path.join(src, rel);
-    const to = path.join(cwd, rel);
+    const dest = installName(rel);
+    const to = path.join(cwd, dest);
     if (fs.existsSync(to) && !force) {
       skipped++;
       continue;
@@ -127,7 +149,8 @@ function conflicts(type, cwd, env) {
   const files = scopeFiles(templateFiles(type), env);
   const out = [];
   for (const rel of files) {
-    if (fs.existsSync(path.join(cwd, rel))) out.push(rel);
+    const dest = installName(rel);
+    if (fs.existsSync(path.join(cwd, dest))) out.push(dest);
   }
   return out;
 }
@@ -216,14 +239,25 @@ function cmdPatch(cwd, flags) {
   return { copied, skipped };
 }
 
+// Placeholders the agent fills per task or feature at runtime, so they are not bootstrap leftovers.
+const RUNTIME_PLACEHOLDERS = new Set(['ISSUE_ID', 'ISSUE_KEY', 'FEATURE_NAME', 'NAME']);
+// `templates/` ships blank forms whose placeholders are meant to stay until a feature is written.
+const PLACEHOLDER_EXEMPT_DIR = 'templates';
+
+function hasUnresolvedPlaceholder(content) {
+  const names = content.match(/\{\{[A-Z][A-Z0-9_]*\}\}/g) || [];
+  return names.some((name) => !RUNTIME_PLACEHOLDERS.has(name.slice(2, -2)));
+}
+
 function scanPlaceholders(cwd, relFiles) {
   const found = [];
   for (const rel of relFiles) {
+    if (path.normalize(rel).split(path.sep)[0] === PLACEHOLDER_EXEMPT_DIR) continue;
     const p = path.join(cwd, rel);
     if (!fs.existsSync(p)) continue;
     try {
       const content = fs.readFileSync(p, 'utf8');
-      if (/\{\{[A-Z_]+\}\}/.test(content)) found.push(rel);
+      if (hasUnresolvedPlaceholder(content)) found.push(rel);
     } catch (_) { /* ignore */ }
   }
   return found;
@@ -231,7 +265,7 @@ function scanPlaceholders(cwd, relFiles) {
 
 function cmdDoctor(cwd, flags) {
   const type = detectType(cwd, flags);
-  const files = scopeFiles(templateFiles(type), flags.env);
+  const files = scopeFiles(templateFiles(type), flags.env).map(installName);
   const missingFiles = [];
   let present = 0;
   for (const rel of files) {
@@ -258,6 +292,16 @@ function cmdDoctor(cwd, flags) {
   return result;
 }
 
+// Upgrade runs the latest package in patch mode: missing files are added and existing
+// (possibly customised) files are kept. Only an explicit --force reaches `install --force`.
+function upgradeArgs(flags) {
+  const force = Boolean(flags && flags.force);
+  const args = ['--yes', 'nitm-ai-dev-toolkit@latest', force ? 'install' : 'patch'];
+  if (force) args.push('--force');
+  if (flags && flags.env) args.push('--env', flags.env);
+  return args;
+}
+
 function cmdUpgrade(cwd, flags) {
   let latest;
   try {
@@ -272,17 +316,17 @@ function cmdUpgrade(cwd, flags) {
   } catch (_) {
     cur = 'unknown';
   }
-  if (latest === cur) {
-    ok(`Already on latest version (${cur}).`);
-    return;
+  if (latest === cur) info(`Already on latest version (${cur}); refreshing missing files and the handoff.`);
+  else info(`New version available: ${latest} (current ${cur}).`);
+  if (flags && flags.force) {
+    warn('--force: existing files will be overwritten with the latest templates. Back up your customisations first.');
+  } else {
+    info('Adding missing files only; your existing files are kept. Pass --force to overwrite them.');
   }
-  info(`New version available: ${latest} (current ${cur}).`);
   info('Upgrading via latest package...');
-  const args = ['--yes', 'nitm-ai-dev-toolkit@latest', 'install', '--force'];
-  if (flags && flags.env) args.push('--env', flags.env);
-  const r = spawnSync('npx', args, { cwd, stdio: 'inherit', timeout: 120000 });
+  const r = spawnSync('npx', upgradeArgs(flags), { cwd, stdio: 'inherit', timeout: 120000 });
   if (r.error) { err('Upgrade failed: ' + r.error.message); return; }
-  if (r.status === 0) ok('Upgrade complete.');
+  if (r.status === 0) ok('Upgrade complete. Hand off to your AI agent with .nitm/BOOTSTRAP.md to finish setup.');
   else err('Upgrade failed.');
 }
 
@@ -303,6 +347,38 @@ function cmdOmoStarter(cwd, flags) {
   }
 }
 
+const FACTORY_USAGE = 'Usage: nitm-ai-dev-toolkit factory <status|watch|archive|prune> [--dir <path>] [--all] [--abandoned] [--interval <ms>] [--dry-run] [--yes]';
+const FACTORY_SUB_USAGE = {
+  archive: 'Usage: nitm-ai-dev-toolkit factory archive [--dir <path>] [--all] [--dry-run]',
+  prune: 'Usage: nitm-ai-dev-toolkit factory prune [--dir <path>] [--all] [--abandoned] [--dry-run] [--yes]',
+};
+
+function cmdFactory(cwd, flags) {
+  const sub = flags._[1];
+  // --abandoned changes what prune deletes; elsewhere it would be a silent no-op, so refuse it.
+  if (flags.abandoned && sub !== 'prune') {
+    err('--abandoned is only for factory prune');
+    process.exitCode = 1;
+    return;
+  }
+  if (sub === 'status') return factory.cmdFactoryStatus(cwd, flags);
+  if (sub === 'watch') return factory.cmdFactoryWatch(cwd, flags);
+  if (sub === 'archive' || sub === 'prune') {
+    const extra = flags._.slice(2);
+    if (extra.length) {
+      err(`Unknown option for factory ${sub}: ${extra[0]}`);
+      err(FACTORY_SUB_USAGE[sub]);
+      process.exitCode = 1;
+      return;
+    }
+    return sub === 'archive'
+      ? factoryArchive.cmdFactoryArchive(cwd, flags)
+      : factoryPrune.cmdFactoryPrune(cwd, flags);
+  }
+  err(FACTORY_USAGE);
+  process.exitCode = 1;
+}
+
 function parseFlags(argv) {
   const flags = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -310,7 +386,21 @@ function parseFlags(argv) {
     if (a === '--monorepo') flags.monorepo = true;
     else if (a === '--repo') flags.repo = true;
     else if (a === '--force' || a === '-f') flags.force = true;
+    else if (a === '--all') flags.all = true;
+    else if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--yes') flags.yes = true;
+    else if (a === '--abandoned') flags.abandoned = true;
     else if (a === '--help' || a === '-h') flags.help = true;
+    else if (a === '--dir' || a === '--interval') {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith('--')) throw new Error(`${a} requires a value`);
+      flags[a.slice(2)] = v;
+    } else if (a.startsWith('--dir=') || a.startsWith('--interval=')) {
+      const eq = a.indexOf('=');
+      const v = a.slice(eq + 1);
+      if (!v) throw new Error(`${a.slice(0, eq)}= requires a value`);
+      flags[a.slice(2, eq)] = v;
+    }
     else if (a === '--env') {
       const v = argv[++i];
       if (v === undefined || v.startsWith('--')) throw new Error('--env requires a value (e.g. --env claude)');
@@ -338,8 +428,10 @@ Usage:
       Add only missing template files (never overwrites existing ones), then
       re-emit the bootstrap handoff so your AI agent can finish configuration.
 
-  npx nitm-ai-dev-toolkit upgrade
-      Upgrade to the latest published version (re-scaffolds via @latest).
+  npx nitm-ai-dev-toolkit upgrade [--env <env>] [--force]
+      Upgrade to the latest published version. Like \`patch\`, adds missing files and
+      keeps your existing ones, then re-emits the bootstrap handoff. --force also
+      overwrites existing files with the latest templates (back up customisations first).
 
   npx nitm-ai-dev-toolkit doctor [--monorepo|--repo] [--env <env>]
       Inspect the current install: missing files, unresolved {{PLACEHOLDER}}
@@ -349,6 +441,31 @@ Usage:
       Run \`npx nitm-opencode-starter install\` to scaffold the oh-my-opencode-slim
       starter (published to npm). Falls back to printing the command if unavailable.
 
+  npx nitm-ai-dev-toolkit factory status [--dir <path>] [--all]
+      Print one table of factory jobs (factory/jobs/<NNN-slug>/job.json), then exit.
+      Closed jobs (merged, abandoned) are hidden and counted; --all shows them,
+      plus archived jobs from factory/archive/ (marked [archived]).
+      Read-only. Run /factory <feature> in your agent to create jobs.
+
+  npx nitm-ai-dev-toolkit factory watch [--dir <path>] [--interval <ms>] [--all]
+      Live terminal view of factory jobs. ↑/↓ or j/k select, Enter opens a job's
+      markdown files, q quits. Closed jobs are hidden unless --all.
+      Not a TTY? Behaves like \`factory status\`.
+
+  npx nitm-ai-dev-toolkit factory archive [--dir <path>] [--all] [--dry-run]
+      Move closed jobs (merged, abandoned) from factory/jobs/ to factory/archive/.
+      Default: only jobs closed more than 7 days ago. --all: every closed job.
+      --dry-run: list what would move, move nothing. Open jobs are never touched.
+      Does not touch git or branches (/factory archive and /factory prune handle those).
+
+  npx nitm-ai-dev-toolkit factory prune [--dir <path>] [--all] [--abandoned] [--dry-run] [--yes]
+      PERMANENTLY delete closed jobs from factory/jobs/ and factory/archive/.
+      Default: only merged jobs closed more than 7 days ago. --all: every merged job
+      (no age limit). --abandoned: also delete abandoned jobs (same age rule).
+      Without --yes it only lists what would be deleted. --dry-run always only
+      lists, even with --yes. Open jobs are never touched. Deletes job folders only;
+      git, docs and branches are not touched.
+
 Options:
   --env <env>  Optional. Limit the scaffold to ONE harness:
                claude | codex | copilot | cursor | opencode
@@ -358,26 +475,36 @@ Options:
                file directly (no native /bootstrap command is provided).
   --monorepo   Force monorepo template
   --repo       Force single-repo template
-  --force      Overwrite existing files
+  --force      Overwrite existing files (install, upgrade). patch never overwrites
+  --dir <path> factory: jobs directory (default: ./factory/jobs)
+  --interval <ms>
+               factory watch: refresh interval (default: 2000, minimum: 100)
+  --all        factory status/watch: include closed and archived jobs
+               factory archive: include every closed job, not just those older than 7 days
+               factory prune: include every merged job, not just those older than 7 days
+  --abandoned  factory prune: also delete abandoned jobs (default: merged only)
+  --dry-run    factory archive/prune: list only, change nothing
+  --yes        factory prune: actually delete (without it, prune only lists)
   -h, --help   Show this help
 `);
 }
 
 function main() {
-  const flags = parseFlags(process.argv.slice(2));
-  if (flags.help) {
-    usage();
-    return;
-  }
-  const cmd = flags._[0];
   const cwd = process.cwd();
   try {
+    const flags = parseFlags(process.argv.slice(2));
+    if (flags.help) {
+      usage();
+      return;
+    }
+    const cmd = flags._[0];
     switch (cmd) {
       case 'install': return cmdInstall(cwd, flags);
       case 'patch': return cmdPatch(cwd, flags);
       case 'upgrade': return cmdUpgrade(cwd, flags);
       case 'doctor': return cmdDoctor(cwd, flags);
       case 'omo-slim-starter': return cmdOmoStarter(cwd, flags);
+      case 'factory': return cmdFactory(cwd, flags);
       default:
         if (cmd) err(`Unknown command: ${cmd}`);
         usage();
@@ -394,6 +521,7 @@ module.exports = {
   detectType,
   scopeFiles,
   templateFiles,
+  installName,
   copyMissing,
   scanPlaceholders,
   envHeader,
@@ -403,7 +531,9 @@ module.exports = {
   cmdPatch,
   cmdDoctor,
   cmdUpgrade,
+  upgradeArgs,
   cmdOmoStarter,
+  cmdFactory,
   ENV_DIRS,
   SHARED_ROOT,
   SHARED_DIRS,