nitm-ai-dev-toolkit 5.0.1 → 5.1.1

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.1] - 2026-10-21
+
+### Fixed
+
+- Factory worktrees are created in `.worktrees/<id>/` at the repo root (the git root in a monorepo) instead of a sibling `../<repo>-factory/<id>/` folder outside the repo. The factory ensures `.worktrees/` is git-ignored.
+
+## [5.1.0] - 2026-10-21
+
+### Changed
+
+- 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.

package/README.md

@@ -222,7 +222,7 @@ For existing targets, back up and obtain approval before removing only known obs
 
 | 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": {} }` |
@@ -231,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:** 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.
+**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.
 
@@ -318,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                  |
 | --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ |
@@ -660,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 |

package/bin/cli.js

@@ -76,6 +76,43 @@ const HARNESS_OWNED = {
 // test/data/ponytail-3.0.23.mjs.fixture holds that exact content.
 const KNOWN_HISTORICAL = {
   '.opencode/plugins/ponytail.mjs': ['3ca6fe6e560da71109af7e40ed04ca47aa22219e4c9edf674bf895acadce8605'],
+  // factory-* agents and their snippets, removed in 5.1.0 (repo and monorepo versions of each file).
+  // The .opencode/agents entries also carry the 5.0.0 hash (5.0.1 changed them).
+  '.claude/agents/factory-spec-writer.agent.md': ['7d12cd197d71cd52d31d4e17f756abd984c012c786cff8c23465b637e2c1cb30'],
+  '.cursor/agents/factory-spec-writer.agent.md': ['03c70de3a9b570972ff14e5dcd946b22948fb216e075452df46ccd4f4bd457cf'],
+  '.github/agents/factory-spec-writer.agent.md': ['76f87fe65a7a552f4645d67b375c464943fe2d92bcbfac4a91d8880cb726b4b2'],
+  '.opencode/agents/factory-spec-writer.md': ['591ba39990f2037f0093b2aaf5a178c269c5b4d723a8dcf61a6a3cbb350ce1cc', '2c778565cbe80f0d610e886f2c150ad9a6478a60c8e7653eb7ece8fe1b7d85d7'],
+  '.claude/agents-snippets/factory-spec-writer.md': ['cdb34e0195981008c0962df78bcdbe2c53e04ef930e0d1d456e02162d4553528', '4644730e83f4ae5eb7b5b8b78021cb9cd9db81bdbc32fcfb745251a8326343b0'],
+  '.claude/agents/factory-builder.agent.md': ['8cc3434f6ee7e1a24098f15428f0810bfe0421288992b1bf4783d4304e0ee999'],
+  '.cursor/agents/factory-builder.agent.md': ['4e14b4588baf99bc98437bf85ce3fc67bf94a30fa0243c7e7cf67c716e75a852'],
+  '.github/agents/factory-builder.agent.md': ['1f7998713df8f5163ea231ce37103cd8be5f757ffa8b8145888dbc889a202807'],
+  '.opencode/agents/factory-builder.md': ['d35fde702d4e8f3876f5f3bbe3b1dd5c16b0f20b375a9b6c6ad0508e0a8b773e', '87e2d9bcc4b4bb387782e202c8b26a8c0a5ca63d86a3f1f0b018698f7fc56a6c'],
+  '.claude/agents-snippets/factory-builder.md': ['08b757399ebb72b57df279cd47a9a681e285e9615151bc6354b58ceab12f45a3', '5526e25aee44ebcce73c868a65ad61221b63575466eb25f05c1f98cce5c1c36b'],
+  '.claude/agents/factory-reviewer-code.agent.md': ['b61ff8ec33b5f0fc9890046e15d6e0886d45e9a472602e75d362537a4ef8f181'],
+  '.cursor/agents/factory-reviewer-code.agent.md': ['303e314cdeb6637e6d76adc257a65095a14ff7b578f7dc8e653ccb804ce1c4ea'],
+  '.github/agents/factory-reviewer-code.agent.md': ['cd729889637f543d79d4daf9e09df07633ff66835c0412dddb5443a729bdd278'],
+  '.opencode/agents/factory-reviewer-code.md': ['bbe16860782736a8389dfb94647dfc4fb0cae1ad46617d34f4e896df29d73489', '681c93ed0432c93898f8f53f9ff78b13e6bb618f9bf8c3f0e6fb2b9083afa05e'],
+  '.claude/agents-snippets/factory-reviewer-code.md': ['92a1726bdec0d94222b08654fa8db481e1710163fd06f439019ab737bdae55c8', '44097bf782912e34eb1d0946cb9ed42be8753fea13036db8edcbb9524b7be8b2'],
+  '.claude/agents/factory-reviewer-security.agent.md': ['7685bb4a2433c7069bdf6f48b7264f46febfe905cd0a8315dd7cefeae2d77add'],
+  '.cursor/agents/factory-reviewer-security.agent.md': ['8bfce3dfbaab8d4a9d7d2b9ec2fd067214028bd8578a53af3ae0933898b0cb2e'],
+  '.github/agents/factory-reviewer-security.agent.md': ['96f0e8697dabb0567b67426214809de870e06df30c1058a4753ac3bf13cff456'],
+  '.opencode/agents/factory-reviewer-security.md': ['55895e193aec20ffcb42a7c12553116f777c91db97e107f240ab15db0d85a7c0', '9302937a79f89c703c6fdb60cfbd65985cd00e52e580786d3be0a4fe8e8ae213'],
+  '.claude/agents-snippets/factory-reviewer-security.md': ['8a4c5a411e47d5b1e50b18d40d177e931cc6bf20a96dfb4286a39719f863b37d'],
+  '.claude/agents/factory-reviewer-ux.agent.md': ['4ff8769a04fcfee2214243b5f1099e69f8fefc8760261321c1cbeb9ab796cb85'],
+  '.cursor/agents/factory-reviewer-ux.agent.md': ['00155aabea522cfa0f20a2c03d194e374958130ec8fc8bb88210ab6f2185fcfa'],
+  '.github/agents/factory-reviewer-ux.agent.md': ['2965a81ebf7d455e07c9270fc5066480e34c8168c552d0fab6602b826caaed8d'],
+  '.opencode/agents/factory-reviewer-ux.md': ['7175b4b5ca713a8b15c0909c84eb2bb6e29630ffeb90157f9e2df9b6a62a6649', 'c192cc5f1dffcfa8879a3d9ede7270e1098fa25dcd2f989627b217edc4b9446d'],
+  '.claude/agents-snippets/factory-reviewer-ux.md': ['a16b188d275f3fba1527b3ef510f61ea3bada11594488720146a8560b17efb98', '6e114305e5d18b284d7f9ececa6b64d6f06c5a272ec2651dcdaea74e81e95554'],
+  '.claude/agents/factory-reviewer-ui.agent.md': ['1107289a1429c795a7c9a8c16426692ca62593483c0ff8b6863a96de166f1cfc'],
+  '.cursor/agents/factory-reviewer-ui.agent.md': ['388b66c8368d642ccbdcb35c55a0c994d510d85b9c04b3f926806d0c1bf824de'],
+  '.github/agents/factory-reviewer-ui.agent.md': ['97aed62c6716fa96834985704dc0e34850842cbd92ceaa987acd70f42769e3dc'],
+  '.opencode/agents/factory-reviewer-ui.md': ['b1e1a5544df1cdd54fedf0a65fd54007600e29ec54a423055858780b363c6d60', 'f93c2410ac2a9d3b358ac21085dd1804e111981b8d24495c411ba06dd6aa5495'],
+  '.claude/agents-snippets/factory-reviewer-ui.md': ['7399863904241ab875cfb7862c683b1135eb4f8027a4a422e377b016007f7bf5', '0142ec37dc2306320d613b58505c31852c02f502b80c6070ff72b5eb77d8b2e1'],
+  '.claude/agents/factory-approver.agent.md': ['2de2420de55a72268f24672a92a4df0d78e133b14a9ccf62ab4e2b0b8f1c090c'],
+  '.cursor/agents/factory-approver.agent.md': ['5bc3df10f0784804bcd54fe4a3de60c6116c55d34eb85bc5be0f1417613bc25c'],
+  '.github/agents/factory-approver.agent.md': ['2a061b34802eb9b5396b76d139bbea5dd21dd89b3e5af06cf09c53c7f6897d94'],
+  '.opencode/agents/factory-approver.md': ['62dbfb689025bf79a2e8f86f7a5afb52a73e07e677ff384d26301d494c3ba21f', '35b3b45950ae1a36ebd8e8b7d46d8499ed427a138d422457a72de2f98c891b0c'],
+  '.claude/agents-snippets/factory-approver.md': ['cacf515a661d25120824d38a81ef2a5753c3bfc5fce8732728cbdd394dda6857'],
 };
 
 // First release with --dry-run, --exclude and --only. `upgrade` refuses a dry run below it (older
@@ -185,7 +222,7 @@ function harnessOf(rel) {
 }
 
 // Feature groups a file belongs to: a path segment or its file stem equals the group name
-// (factory/, .agents/skills/gh-cli/, prisma-migrations.md, factory-builder.md).
+// (factory/, .agents/skills/gh-cli/, prisma-migrations.md).
 function featuresOf(rel) {
   const n = path.normalize(rel);
   const segments = n.split(path.sep).map((s) => s.replace(/^\./, ''));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "5.0.1",
+  "version": "5.1.1",
   "description": "Scaffold AI agent config (Cursor, GitHub Copilot, Claude Code, OpenCode, Codex) into any repo, then hand off to your AI agent to finish setup.",
   "bin": {
     "nitm-ai-dev-toolkit": "bin/cli.js"

package/src/monorepo/.agents/skills/factory/SKILL.md

@@ -5,7 +5,7 @@ description: Opt-in software factory for feature-sized work. Runs one job throug
 
 # Factory (orchestrator)
 
-One orchestrator session runs a feature through intake → spec → plan → build → review → approve → merge. Agents get their context from files and each agent writes only its own file. You are the orchestrator: you ask the intake questions, dispatch agents, read their files, rewrite `job.json`, run the gates with the operator, handle tickets, and run the merge. You never write code, specs, plans, reviews, or `qa.md` yourself. Exceptions: you write `intake.md` from the operator's answers, `spec-<k>.md` and `plan-<k>.md` from the operator's change requests, `tasks.md` ticket keys, the feature folder rename and copy, the feature docs commit on the job branch, worktree and branch removal, the moves and branch deletions in Archive, `decision.md` with `ESCALATE` when retries run out, `merge-conflict.md` on a merge conflict, `bootstrap.md` on a failed worktree bootstrap step, the push and merge request in `push-mr` mode (see Merge procedure), and `rework-<k>.md` from the user's note.
+One orchestrator session runs a feature through intake → spec → plan → build → review → approve → merge. Agents get their context from files. Builders and spec writers write their own files; reviewers and the approver return their report, and you save it (see Subagent dispatch). You are the orchestrator: you ask the intake questions, dispatch agents, read their files, rewrite `job.json`, run the gates with the operator, handle tickets, and run the merge. You never write code, specs, plans, reviews, or `qa.md` yourself. Exceptions: you write `intake.md` from the operator's answers, `spec-<k>.md` and `plan-<k>.md` from the operator's change requests, `tasks.md` ticket keys, the feature folder rename and copy, the feature docs commit on the job branch, worktree and branch removal, the moves and branch deletions in Archive, the review files and `decision.md` from the reviewers' and approver's replies (see Subagent dispatch), and `decision.md` with `ESCALATE` when retries run out, `merge-conflict.md` on a merge conflict, `bootstrap.md` on a failed worktree bootstrap step, the push and merge request in `push-mr` mode (see Merge procedure), and `rework-<k>.md` from the user's note.
 
 The factory is opt-in and sits alongside Feature Builder and TDD. Nothing runs unless the user invokes `/factory`.
 
@@ -100,7 +100,7 @@ Feature folders live under the roots in `{{FACTORY_FEATURE_PATHS}}`, relative to
   "tracker_errors": [],
   "branch": "factory/001-onboarding-bootstrap",
   "worktree": true,
-  "worktree_path": "/abs/path/to/repo-factory/001-onboarding-bootstrap",
+  "worktree_path": "/abs/path/to/repo/.worktrees/001-onboarding-bootstrap",
   "mr": null,
   "failed_stage": null,
   "stage": "awaiting-plan",
@@ -187,13 +187,13 @@ Resume by stage:
 
 | Stage | Resume action |
 | --- | --- |
-| `spec` | Rerun `factory-spec-writer` in spec mode, then show the spec gate |
+| `spec` | Rerun `planner` in spec mode (brief `roles/spec.md`), then show the spec gate |
 | `awaiting-spec` | Show the spec gate |
-| `plan` | Rerun `factory-spec-writer` in plan mode, then show the plan gate |
+| `plan` | Rerun `planner` in plan mode (brief `roles/spec.md`), then show the plan gate |
 | `awaiting-plan` | Show the plan gate |
-| `build` | Rerun `factory-builder` in the mode the files call for: rework if a `rework-<k>.md` is newer than `build.md`, repair if the last review round has `CHANGES`, otherwise build |
+| `build` | Rerun `implementer` (brief `roles/build.md`) in the mode the files call for: rework if a `rework-<k>.md` is newer than `build.md`, repair if the last review round has `CHANGES`, otherwise build |
 | `review` | Rerun the review round `round` |
-| `approve` | Rerun `factory-approver` |
+| `approve` | Rerun the approval (`reviewer` in approval mode, brief `roles/approve.md`) |
 | `awaiting-human` | Print the approver's rationale, the suggested checks from `qa.md` (see QA guidance), and the `/factory approve` command |
 | `needs-human`, `failed_stage` `spec` | Rerun the spec stage (see Spec), then show the spec gate |
 | `needs-human`, `failed_stage` `plan` | Rerun the plan stage (see Plan), then show the plan gate |
@@ -216,7 +216,7 @@ A job with no work started (stage before `build`, so no build has begun and no `
 
 ## Spec
 
-Set stage `spec`. Dispatch `factory-spec-writer` in spec mode with the paths block, the feature request, and the feature folder. It writes `spec.md`. If `intake.md` is in the paths block, the spec writer reads it, and the operator's answers win over the request text where they conflict. Wait for `spec.md` (see Harness notes). Set stage `awaiting-spec` and show the spec gate.
+Set stage `spec`. Dispatch `planner` in spec mode (brief `roles/spec.md`) with the paths block, the feature request, and the feature folder. It writes `spec.md`. If `intake.md` is in the paths block, the spec writer reads it, and the operator's answers win over the request text where they conflict. Wait for `spec.md` (see Harness notes). Set stage `awaiting-spec` and show the spec gate.
 
 ## Spec gate (mandatory)
 
@@ -232,13 +232,13 @@ Then ask in chat, as a numbered choice:
 Handle the answer:
 
 - **Confirm** → continue to Plan. If decision items are still open, do not continue: list them and ask again.
-- **Request changes:** write the operator's text verbatim to `spec-<k>.md` in the job folder (`k` = next free index). Set stage `spec`, rerun `factory-spec-writer` in spec mode with the paths block and `spec-<k>.md`. It updates `spec.md`. Set stage `awaiting-spec` and show the gate again. The spec writer records each answered decision as `[DECIDED] <answer>`.
+- **Request changes:** write the operator's text verbatim to `spec-<k>.md` in the job folder (`k` = next free index). Set stage `spec`, rerun `planner` in spec mode (brief `roles/spec.md`) with the paths block and `spec-<k>.md`. It updates `spec.md`. Set stage `awaiting-spec` and show the gate again. The spec writer records each answered decision as `[DECIDED] <answer>`.
 
 If the session ends at this gate, `/factory start <job-id|slug|KEY>` shows it again (see Start).
 
 ## Plan
 
-Set stage `plan`. Dispatch `factory-spec-writer` in plan mode with the paths block, and `plan-<k>.md` when a plan change request is pending. It writes `plan.md` in the feature folder, and `tasks.md` for large work (or removes a stale `tasks.md` when the plan is small). It does not change `spec.md`.
+Set stage `plan`. Dispatch `planner` in plan mode (brief `roles/spec.md`) with the paths block, and `plan-<k>.md` when a plan change request is pending. It writes `plan.md` in the feature folder, and `tasks.md` for large work (or removes a stale `tasks.md` when the plan is small). It does not change `spec.md`.
 
 Read the `**Size:**` line of `plan.md`:
 
@@ -270,7 +270,7 @@ Then ask in chat, as a numbered choice:
 Handle the answer:
 
 - **Confirm** with size known → continue to Tracking. If size is still `unclear`, ask again.
-- **Request changes:** write the operator's text verbatim to `plan-<k>.md` (`k` = next free index). Set stage `plan`, rerun `factory-spec-writer` in plan mode with the paths block and `plan-<k>.md`. Show the gate again. If the change touches the spec itself, send it through the spec gate instead: write it to `spec-<k>.md`, rerun spec mode, show the spec gate, then plan again.
+- **Request changes:** write the operator's text verbatim to `plan-<k>.md` (`k` = next free index). Set stage `plan`, rerun `planner` in plan mode (brief `roles/spec.md`) with the paths block and `plan-<k>.md`. Show the gate again. If the change touches the spec itself, send it through the spec gate instead: write it to `spec-<k>.md`, rerun spec mode, show the spec gate, then plan again.
 - **Change size only:** the operator's answer to choice 3 sets `size` in `job.json`. The plan does not change.
 - **Change tracking only:** update `tracking` in `job.json`. Do not rerun the spec writer.
 - **Change build mode only:** update `worktree` in `job.json`. Do not rerun the spec writer. In-place is checked when the build starts (see In-place mode).
@@ -291,10 +291,11 @@ If a ticket cannot be created, stop at `awaiting-plan`. Report the lines that ha
 
 ## Worktree
 
-The default build location. Use the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill for its safety checks only. Its directory selection does not apply: the path below overrides it. Never edit `.gitignore` for the worktree.
+The default build location. Follow the [using-git-worktrees](../using-git-worktrees/SKILL.md) skill. Factory always takes its project-local `.worktrees/` default and never the global `~/.worktrees` option, without asking.
 
 - Branch `factory/<id>` from `{{DEFAULT_BRANCH}}`.
-- Path `../<repo-name>-factory/<id>/` relative to the main checkout, where `<repo-name>` is the basename of the main checkout. Record it in `worktree_path`.
+- Path `.worktrees/<id>/` at the root of the main checkout (the git root, inside the repo folder). Record its absolute path in `worktree_path`.
+- Before the first worktree, run that skill's `.gitignore` check. If it had to add `.worktrees/`, commit that on `{{DEFAULT_BRANCH}}` or tell the operator to.
 - Create it at the start of the build stage, after the plan gate and tracking. Reuse it if it exists (rework and repair).
 - Copy the job's `spec.md`, `plan.md`, and `tasks.md` (if any) from the main checkout's feature folder into the same relative path in the worktree. The builder ticks `tasks.md` there. Then run the bootstrap (next subsection) and make the feature docs commit.
 - Job state stays in the main checkout's `factory/jobs/<id>/`, never in the worktree.
@@ -350,7 +351,7 @@ PATHS
 - Main checkout (absolute): <abs>
 - Job folder (absolute): <abs>/factory/jobs/<id>
 - Feature folder (absolute, main checkout): <abs>/<feature_dir>
-- Worktree (absolute): <abs>/../<repo-name>-factory/<id>   (in-place: the main checkout)
+- Worktree (absolute): <abs>/.worktrees/<id>   (in-place: the main checkout)
 - Feature folder in worktree (absolute): <worktree>/<feature_dir>   (in-place: the main checkout's)
 - qa.md (absolute, build location): <worktree>/<feature_dir>/qa.md
 - Branch: factory/<id>
@@ -360,28 +361,28 @@ PATHS
 - Ports: builder <p>, ux <p+1>, ui <p+2>
 ```
 
-Agents read their inputs and write their one output file by these absolute paths. The spec-writer works in the main-checkout feature folder. Reviewers and the approver read the spec and plan there. The builder reads them there and ticks `tasks.md` in the build location's copy. Reviewers read `qa.md` at the paths block's `qa.md` line, for context only.
+Agents read their inputs by these absolute paths. Builders and spec writers write their output files there; reviewers and the approver return their report instead (see Subagent dispatch). The spec-writer works in the main-checkout feature folder. Reviewers and the approver read the spec and plan there. The builder reads them there and ticks `tasks.md` in the build location's copy. Reviewers read `qa.md` at the paths block's `qa.md` line, for context only.
 
 ## Loop
 
 Let `N` be the current round, starting at `1` for a new job.
 
-1. **Spec.** Dispatch `factory-spec-writer` in spec mode (see Spec).
+1. **Spec.** Dispatch `planner` in spec mode (brief `roles/spec.md`) (see Spec).
 2. **Spec gate.** Show the gate and wait for the operator's confirmation (see Spec gate). Do not continue until the operator confirms.
-3. **Plan.** Dispatch `factory-spec-writer` in plan mode (see Plan). Set stage `awaiting-plan`.
+3. **Plan.** Dispatch `planner` in plan mode (brief `roles/spec.md`) (see Plan). Set stage `awaiting-plan`.
 4. **Plan gate.** Show the gate and wait for the operator's confirmation (see Plan gate). Do not continue until the operator confirms.
 5. **Tracking and build location.** Run Tracking if `tracking` is `tracked`. Create the build location: the worktree and its copy of the feature docs (see Worktree), or the in-place branch (see In-place mode). Set `worktree_path` if a worktree was made. Set stage `build`. Move any tracked tickets to In Progress (see Ticket lifecycle).
-6. **Build.** Dispatch `factory-builder` in build mode. Wait (see Harness notes), then read the first line of `build.md`:
+6. **Build.** Dispatch `implementer` (brief `roles/build.md`) in build mode. Wait (see Harness notes), then read the first line of `build.md`:
    - `STATUS: READY` → continue.
    - `STATUS: BLOCKED` → stage `needs-human`. Tell the user the reason from `build.md`. Stop.
    - Anything else → treat as BLOCKED with reason "builder wrote no valid status".
 7. **Review round N.** Set stage `review`, `round` to `N`, and every configured lens to `pending` in `reviews`. Move tracked tickets to In Review. Dispatch the lenses from `{{FACTORY_REVIEW_LENSES}}` in two stages, each with the paths block:
-   - **Stage A:** `code` → `factory-reviewer-code` and `security` → `factory-reviewer-security`. Dispatch both in one parallel batch (one message with multiple agent calls) when the harness can.
-   - **Stage B:** `ux` → `factory-reviewer-ux` and `ui` → `factory-reviewer-ui`, the browser lenses. Start them only after every stage A review is written. The code reviewer's build runs in the shared build location and would clobber the browser lenses' dev servers. The two browser lenses use separate ports and may run in parallel with each other.
+   - **Stage A:** `code` → `reviewer` (brief `roles/review-code.md`) and `security` → `reviewer`, in fresh context (brief `roles/review-security.md`). Dispatch both in one parallel batch (one message with multiple agent calls) when the harness can.
+   - **Stage B:** `ux` → `reviewer` (brief `roles/review-ux.md`) and `ui` → `reviewer` (brief `roles/review-ui.md`), the browser lenses. Start them only after every stage A review is written. The code reviewer's build runs in the shared build location and would clobber the browser lenses' dev servers. The two browser lenses use separate ports and may run in parallel with each other.
 
    If the harness cannot dispatch in parallel, run the lenses one at a time, in the order above.
 
-   Wait for every `round-N/review-<lens>.md` (see Harness notes). Each must have a first line `VERDICT: PASS` or `VERDICT: CHANGES`. A reviewer that returns without a valid file is re-dispatched alone, once. If it still fails, stage `needs-human`. Never resume the builder during a review round. Update `reviews` from the verdicts.
+   Wait for every reviewer's reply, and save each as `round-N/review-<lens>.md` (see Harness notes). Each must have a first line `VERDICT: PASS` or `VERDICT: CHANGES`. A reviewer whose reply has no valid first line is re-dispatched alone, once. If it still fails, stage `needs-human`. Never resume the builder during a review round. Update `reviews` from the verdicts.
 8. **Verdicts.** Check in this order:
    - Any blocking item titled `Not verified:`, from any lens: no repair. Stage `needs-human`. Tell the user the `Not verified` items. Stop.
    - Any `CHANGES`, and the cycle has used fewer than 3 review rounds: run a builder repair (below) with `Round` set to `N`, the round just reviewed. Then set `N` to `N + 1` and go to step 7.
@@ -389,14 +390,14 @@ Let `N` be the current round, starting at `1` for a new job.
    - All `PASS`: go to step 9.
 
    A review cycle is the rounds since the job started, or since the latest `rework-<k>.md` (see Rework). "Third review round of the cycle" means two repairs have already been made in this cycle. The rework note records where its cycle starts.
-9. **Approve.** Set stage `approve`. Dispatch `factory-approver` with the paths block. Wait for `decision.md` (see Harness notes). Its first line must be `APPROVE` or `ESCALATE`. If the line is missing or invalid, re-dispatch once, then stage `needs-human`.
+9. **Approve.** Set stage `approve`. Dispatch `reviewer` in approval mode (brief `roles/approve.md`, fresh context) with the paths block. Wait for the approver's reply and save it as `decision.md` (see Harness notes). Its first line must be `APPROVE` or `ESCALATE`. If the line is missing or invalid, re-dispatch once, then stage `needs-human`.
    - `ESCALATE` → stage `needs-human`. Tell the user the rationale. Stop.
    - `APPROVE` and `{{APPROVAL_MODE}}` is exactly `auto` → run the merge procedure.
    - `APPROVE` otherwise: stage `awaiting-human`. Print the suggested checks (see QA guidance). Tell the user to run `/factory approve <id>` after reviewing the branch. Stop. Any value other than exactly `auto` is treated as `human`.
 
 ### Repair
 
-Dispatch `factory-builder` in repair mode with the paths block, where `Round` is the round just reviewed (the `N` from step 7, before it increments). It reads `spec.md`, `plan.md`, `build.md`, and `round-<Round>/review-*.md`. It must address every `CHANGES` item or justify it in `build.md`. It also rewrites `qa.md`. Wait for `build.md` (see Harness notes) and check its first line again (step 6 rules).
+Dispatch `implementer` (brief `roles/build.md`) in repair mode with the paths block, where `Round` is the round just reviewed (the `N` from step 7, before it increments). It reads `spec.md`, `plan.md`, `build.md`, and `round-<Round>/review-*.md`. It must address every `CHANGES` item or justify it in `build.md`. It also rewrites `qa.md`. Wait for `build.md` (see Harness notes) and check its first line again (step 6 rules).
 
 ### Builder continuity
 
@@ -410,7 +411,7 @@ Either way the builder runs only between reviews, never during one.
 ### Failures
 
 - Missing or unreadable `AGENTS.md` commands → stop and ask the user to add them. Do not guess commands.
-- An agent that finishes without its expected file → re-dispatch that agent once, then `needs-human`. For a spec or plan agent, set `failed_stage` to `spec` or `plan` with it.
+- An agent that finishes without its expected output (a file, or for a reviewer or the approver, a reply with a valid first line) → re-dispatch that agent once, then `needs-human`. For a spec or plan agent, set `failed_stage` to `spec` or `plan` with it.
 - An agent that times out is not re-dispatched (see Harness notes).
 
 ## Ticket lifecycle
@@ -447,7 +448,7 @@ Rules:
    <the user's note, verbatim>
    ```
 
-4. Set `round` to `N`, stage `build`. Move tracked tickets to In Progress. For an in-place job, switch the main checkout to `factory/<id>` if needed (see In-place mode). For a worktree job, rerun the bootstrap first (see Worktree bootstrap); a failed step stops the rework the way it stops a build. Dispatch a fresh `factory-builder` in rework mode. It reads the latest `rework-<k>.md` and rewrites `qa.md`. Wait for it. Then continue from step 6's status check on `build.md` (do not dispatch the builder again), and run review round `N` from step 7.
+4. Set `round` to `N`, stage `build`. Move tracked tickets to In Progress. For an in-place job, switch the main checkout to `factory/<id>` if needed (see In-place mode). For a worktree job, rerun the bootstrap first (see Worktree bootstrap); a failed step stops the rework the way it stops a build. Dispatch a fresh `implementer` (brief `roles/build.md`) in rework mode. It reads the latest `rework-<k>.md` and rewrites `qa.md`. Wait for it. Then continue from step 6's status check on `build.md` (do not dispatch the builder again), and run review round `N` from step 7.
 
 The new cycle starts with a fresh repair budget. Old rounds and reviews are kept, not overwritten.
 
@@ -600,30 +601,46 @@ The age rule is the same as Archive: by default only jobs whose `updatedAt` is m
 
 ## Subagent dispatch
 
-Dispatch with the paths block first, then the task line, then the files to read. The task line names the mode when the agent has one (spec or plan for the spec writer; build, repair, or rework for the builder). The dispatch primitive is the Claude Agent tool, the Copilot `agent` tool, or the harness's own subagent mechanism elsewhere.
+Dispatch with the paths block first, then the task line, then the role brief and the files to read. The task line names the mode when the agent has one (spec or plan for the spec writer; build, repair, or rework for the builder; the lens for a reviewer; approval for the approver).
 
-Each harness has its own wrappers. Every wrapper points to its snippet in `.claude/agents-snippets/`:
+Factory adds no agents of its own. Each role runs on a native agent (`planner`, `implementer`, or `reviewer`), and the Factory rules for that role (outputs, evidence, verdict format, escalation triggers) live in its brief in this skill's `roles/` folder. Every dispatch tells the agent to read the matching brief first. The role brief overrides the dispatched agent's default output format and file-writing rules, and the first line of the reply must follow the brief.
 
-| Harness | Agent wrappers | Entry point |
+| Role | Native agent | Task line | Brief | Fresh context | Output |
+| --- | --- | --- | --- | --- | --- |
+| Spec writer | `planner` | `spec` or `plan` mode | `roles/spec.md` | no | writes `spec.md`, or `plan.md` and `tasks.md` |
+| Builder | `implementer` | `build`, `repair`, or `rework` mode | `roles/build.md` | no | writes `build.md` and `qa.md` |
+| Code reviewer | `reviewer` | lens `code` | `roles/review-code.md` | no | returns its review |
+| Security reviewer | `reviewer` | lens `security` | `roles/review-security.md` | yes | returns its review |
+| UX reviewer | `reviewer` | lens `ux` | `roles/review-ux.md` | no | returns its review |
+| UI reviewer | `reviewer` | lens `ui` | `roles/review-ui.md` | no | returns its review |
+| Approver | `reviewer` | `approval` mode | `roles/approve.md` | yes | returns its decision |
+
+Reviewers and the approver return their report in their final reply and do not write files. You save the reply: the review as `round-<N>/review-<lens>.md`, the decision as `decision.md`. The first line of the reply is the verdict or decision, and that is what you check.
+
+Each harness dispatches the native agent by name:
+
+| Harness | How to dispatch | Entry point |
 | --- | --- | --- |
-| Claude Code | `.claude/agents/factory-*.agent.md` | `.claude/commands/factory.md` |
-| GitHub Copilot | `.github/agents/factory-*.agent.md` | `.github/prompts/factory.prompt.md` |
-| Cursor | `.cursor/agents/factory-*.agent.md` | `.cursor/commands/factory.md` |
-| OpenCode | `.opencode/agents/factory-*.md` | `.opencode/commands/factory.md` |
-| Codex | none | this skill |
+| Claude Code | the Agent tool, naming the agent | `.claude/commands/factory.md` |
+| GitHub Copilot | the `agent` tool, naming the agent | `.github/prompts/factory.prompt.md` |
+| Cursor | the agent by name from `.cursor/agents` | `.cursor/commands/factory.md` |
+| OpenCode | the agent by name from `.opencode/agents` | `.opencode/commands/factory.md` |
+| Codex | none: run the brief directly | this skill |
+
+Codex has no agent files. Run each role brief directly, as a delegated or fresh session, passing the paths block first. If the harness gives you one session only, use single-session mode (see Harness notes).
 
-Codex has no wrappers. Run each `.claude/agents-snippets/factory-*.md` as a delegated or fresh session, passing the paths block first. If the harness gives you one session only, use single-session mode (see Harness notes).
+In OpenCode with the Slim plugin, `oracle` (security or approval) and `designer` (ux or ui) are optional alternatives to the native agents. Use them only if you have configured them as edit-denied reviewers. The native agents above are the default.
 
-Dispatch each agent by its kebab-case name, for example `factory-builder`. Copilot may show a display name in its agent list; pick the agent with that name.
+Copilot may show a display name in its agent list; pick the agent with the name above.
 
 ## Harness notes
 
-The loop is the same in every harness. Use a parallel lens batch where the harness offers one, otherwise run the lenses in order. If dispatch is background-only, poll each expected file for a valid first line until the timeout, then apply Failures. Builder resume is under Builder continuity; wrappers are under Subagent dispatch.
+The loop is the same in every harness. Use a parallel lens batch where the harness offers one, otherwise run the lenses in order. If dispatch is background-only, poll each expected file for a valid first line until the timeout, then apply Failures. A reviewer or approver reply arrives as its result; check its first line the same way. Builder resume is under Builder continuity; agent names are under Subagent dispatch.
 
 - **Timeout.** The default is 15 minutes per agent. The operator can set another value for one run by saying so in the request, for example `timeout 30 min`.
 - **A timed-out agent is never re-dispatched.** It may still be running, and a second run could write the same file. Stage `needs-human` with the reason "`<agent>` timed out after `<N>` min; it may still be running". For a spec or plan agent, also set `failed_stage`. Tell the operator to check the job folder and the build location, and to confirm the agent has stopped, before `/factory start` or `/factory rework`.
 
-**Single-session mode (Codex).** Codex has no wrappers, so one session plays every role. The orchestrator switches roles one at a time. For each agent it reads only that role's snippet and input files, writes only that role's output, and keeps the same write boundaries. The rule "never write code" applies per role: as orchestrator it writes only orchestrator files, and it writes code only as the builder, and only in the build location. Lenses run in order (stage A, then stage B). The security reviewer judges the diff, not the builder's account. A timed-out role is handled as above; a role that ends without its file is re-run once, then `needs-human`.
+**Single-session mode (Codex).** Codex has no agent files, so one session plays every role. The orchestrator switches roles one at a time. For each role it reads only that role's brief and input files, writes only that role's output (a reviewer or the approver returns its report, and you save it), and keeps the same write boundaries. The rule "never write code" applies per role: as orchestrator it writes only orchestrator files, and it writes code only as the builder, and only in the build location. Lenses run in order (stage A, then stage B). The security reviewer judges the diff, not the builder's account. A timed-out role is handled as above; a role that ends without its file is re-run once, then `needs-human`.
 
 ## Limits
 

package/src/monorepo/{.claude/agents-snippets/factory-approver.md → .agents/skills/factory/roles/approve.md}

@@ -1,6 +1,6 @@
 # Factory Approver
 
-You decide whether a job goes to merge or to a human. You are the approval gate of the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you. You decide; you do not merge, fix, or re-review.
+You decide whether a job goes to merge or to a human. You are the approval gate of the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you. You decide; you do not merge, fix, or re-review.
 
 ## Inputs
 
@@ -32,7 +32,7 @@ You decide whether a job goes to merge or to a human. You are the approval gate
 
 ## Output
 
-You write exactly one file: `<job folder>/decision.md`. Use this skeleton:
+You do not write files. Your final reply is the decision, and the orchestrator saves it as `<job folder>/decision.md`, so start the reply with the decision line. Use this skeleton:
 
 ```markdown
 APPROVE
@@ -66,7 +66,7 @@ The first line must be exactly `APPROVE` or `ESCALATE`, followed by the rational
 
 - When in doubt, `ESCALATE`. A wrong escalation costs one human click. A wrong approval can ship a security or data problem.
 - An `ESCALATE` rationale names the trigger or the failed step, so the human can decide quickly.
-- Do not edit code, reviews, `build.md`, `job.json`, `tasks.md`, or any file other than `decision.md`.
+- Do not edit code, reviews, `build.md`, `job.json`, `tasks.md`, or any other file.
 - Do not merge, push, or change branches.
 - Do not transition tickets. The orchestrator owns ticket status, and the approver never touches the tracker.
 - `qa.md` is not a gate. Do not count its checks in the decision, and do not escalate because it is missing.

package/src/monorepo/{.claude/agents-snippets/factory-builder.md → .agents/skills/factory/roles/build.md}

@@ -1,6 +1,6 @@
 # Factory Builder
 
-You build one job's feature inside its build location. You are one agent in the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
+You build one job's feature inside its build location. You are one agent in the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
 
 ## Modes
 
@@ -30,9 +30,9 @@ The orchestrator tells you which mode you are in:
 
 ## Method
 
-Follow the [test-driven development](../../.agents/skills/test-driven-development/SKILL.md) skill: write a failing test, watch it fail, write the minimal code, watch it pass, then refactor. Keep the diff as small as the spec allows, per [ponytail](../../.agents/skills/ponytail/SKILL.md).
+Follow the [test-driven development](../../test-driven-development/SKILL.md) skill: write a failing test, watch it fail, write the minimal code, watch it pass, then refactor. Keep the diff as small as the spec allows, per [ponytail](../../ponytail/SKILL.md).
 
-Before you claim any acceptance criterion is met, follow [verification before completion](../../.agents/skills/verification-before-completion/SKILL.md): run the check and record the command and its result as evidence.
+Before you claim any acceptance criterion is met, follow [verification before completion](../../verification-before-completion/SKILL.md): run the check and record the command and its result as evidence.
 
 ## Output
 

package/src/monorepo/{.claude/agents-snippets/factory-reviewer-code.md → .agents/skills/factory/roles/review-code.md}

@@ -1,6 +1,6 @@
 # Factory Reviewer: Code
 
-You review one round of a job's branch for correctness, simplicity, reuse, conventions, and docs, and you run the project's checks. You are the `code` lens of the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
+You review one round of a job's branch for correctness, simplicity, reuse, conventions, and docs, and you run the project's checks. You are the `code` lens of the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
 
 ## Inputs
 
@@ -16,17 +16,17 @@ Run each command the project documents in `AGENTS.md` from the build location: t
 
 ## Review
 
-Use the [requesting code review](../../.agents/skills/requesting-code-review/SKILL.md) checklist for process. Then cover:
+Use the [requesting code review](../../requesting-code-review/SKILL.md) checklist for process. Then cover:
 
 - **Correctness:** logic, edge cases, error handling at boundaries, every acceptance criterion in `spec.md` covered by a test or check.
-- **Simplicity:** use the [ponytail-review](../../.agents/skills/ponytail-review/SKILL.md) lens. Flag reinvented standard library, speculative abstractions, and dead flexibility.
+- **Simplicity:** use the [ponytail-review](../../ponytail-review/SKILL.md) lens. Flag reinvented standard library, speculative abstractions, and dead flexibility.
 - **Reuse:** the change should extend existing utilities rather than duplicate them.
 - **Conventions:** the project's `AGENTS.md`, the `AGENTS.md` of each affected app or package, and `.claude/rules-snippets/` standards.
 - **Docs:** documentation the project's `AGENTS.md` requires for this kind of change, in the affected app's docs folder for per-app work.
 
 ## Output
 
-You write exactly one file: `<job folder>/round-<N>/review-code.md`. Use this skeleton:
+You do not write files. Your final reply is the report, and the orchestrator saves it as `<job folder>/round-<N>/review-code.md`, so start the reply with the verdict line. Use this skeleton:
 
 ```markdown
 VERDICT: PASS
@@ -54,4 +54,4 @@ The first line must be exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `CHANGES` needs at least one blocking item. Each blocking item is specific (file and line), actionable, and about correctness, a failing check, a missing acceptance criterion, or a clear convention break.
 - Taste goes under non-blocking notes. Taste never blocks a PASS.
 - A failing test, lint, or build command is a blocking item unless the failure is in code the branch does not touch and is shown on the default branch too.
-- Do not edit code, tests, or any file other than your review. Do not fix problems yourself.
+- Do not edit code, tests, or any file. Do not fix problems yourself.

package/src/{repo/.claude/agents-snippets/factory-reviewer-security.md → monorepo/.agents/skills/factory/roles/review-security.md}

@@ -1,6 +1,6 @@
 # Factory Reviewer: Security
 
-You audit one round of a job's branch for security problems. You are the `security` lens of the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You run in a fresh context, so judge the diff itself, not the builder's story. You work from the paths block the orchestrator gives you.
+You audit one round of a job's branch for security problems. You are the `security` lens of the [factory](../SKILL.md) pipeline. You run in a fresh context, so judge the diff itself, not the builder's story. You work from the paths block the orchestrator gives you.
 
 ## Inputs
 
@@ -11,7 +11,7 @@ You audit one round of a job's branch for security problems. You are the `securi
 
 ## Method
 
-Apply the [security reviewer](../../.agents/skills/security-reviewer/SKILL.md) skill to the diff. Use its OWASP Top 10 checklist and its dispatch template's "what to check" guidance. Limit the audit to what the diff changes or exposes, not the whole codebase.
+Apply the [security reviewer](../../security-reviewer/SKILL.md) skill to the diff. Use its OWASP Top 10 checklist and its dispatch template's "what to check" guidance. Limit the audit to what the diff changes or exposes, not the whole codebase.
 
 Pay particular attention to: input validation at trust boundaries, injection (SQL, command, template, XSS), authentication and authorization checks on new routes, secrets or tokens in code or logs, data exposure in responses and logs, and file handling.
 
@@ -19,7 +19,7 @@ Do not run exploits against any real service. A local test that demonstrates a f
 
 ## Output
 
-You write exactly one file: `<job folder>/round-<N>/review-security.md`. Use this skeleton:
+You do not write files. Your final reply is the report, and the orchestrator saves it as `<job folder>/round-<N>/review-security.md`, so start the reply with the verdict line. Use this skeleton:
 
 ```markdown
 VERDICT: PASS
@@ -45,4 +45,4 @@ The first line must be exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 
 - `CHANGES` needs at least one blocking item, and every blocking item names a concrete exploit path. Theoretical concerns go under non-blocking notes.
 - A PASS means you checked the diff and found no exploitable issue. It does not mean the code is perfect. Say what you checked.
-- Do not edit code or any file other than your review.
+- Do not edit code or any file.

package/src/monorepo/{.claude/agents-snippets/factory-reviewer-ui.md → .agents/skills/factory/roles/review-ui.md}

@@ -1,6 +1,6 @@
 # Factory Reviewer: UI
 
-You look at a job's feature running in the build location and review the visual design: consistency with the existing design system, spacing, typography, contrast, and responsive layout. You are the `ui` lens of the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
+You look at a job's feature running in the build location and review the visual design: consistency with the existing design system, spacing, typography, contrast, and responsive layout. You are the `ui` lens of the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
 
 ## Safety rules (absolute)
 
@@ -20,18 +20,18 @@ You look at a job's feature running in the build location and review the visual
 
 ## Method
 
-1. If the feature has no visual surface, write a PASS with the note "No visual change in spec". Stop there.
-2. Start the affected app's dev server from the build location on the ui port, using the filtered dev command and the port flag or env var that `AGENTS.md` documents. If `AGENTS.md` documents none, do not guess and do not use `PORT`. Skip the browser checks, record `Not verified: dev server port` as a blocking item, and write the review. Stop the server if you started one.
+1. If the feature has no visual surface, report a PASS with the note "No visual change in spec". Stop there.
+2. Start the affected app's dev server from the build location on the ui port, using the filtered dev command and the port flag or env var that `AGENTS.md` documents. If `AGENTS.md` documents none, do not guess and do not use `PORT`. Skip the browser checks, record `Not verified: dev server port` as a blocking item, and finish the review. Stop the server if you started one.
 3. Open each affected view with a browser tool. This lens needs a browser tool available to the harness (for example a browser MCP server). Without one, nothing is verified. Check:
    - **Consistency:** the same components, tokens, and patterns the rest of the app uses. A new one-off style is a blocking item.
    - **Spacing and typography:** follows the project's scale. No arbitrary values where a token exists.
-   - **Contrast:** text and interactive elements meet WCAG AA contrast. Follow [UI accessibility](../rules-snippets/ui-accessibility.md).
+   - **Contrast:** text and interactive elements meet WCAG AA contrast. Follow [UI accessibility](../../../../.claude/rules-snippets/ui-accessibility.md).
    - **Responsive:** the layout holds at a narrow and a wide viewport. No overflow, no clipped controls.
 4. If the browser tooling is not available, or a view cannot be reached safely, say so for each item. Do not guess what the page looks like.
 
 ## Output
 
-You write exactly one file: `<job folder>/round-<N>/review-ui.md`. Use this skeleton:
+You do not write files. Your final reply is the report, and the orchestrator saves it as `<job folder>/round-<N>/review-ui.md`, so start the reply with the verdict line. Use this skeleton:
 
 ```markdown
 VERDICT: PASS
@@ -61,4 +61,4 @@ The first line must be exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `CHANGES` needs at least one blocking item that is specific and actionable.
 - If something the spec requires was **not verified**, the verdict is `CHANGES` with a blocking item titled `Not verified: <what>`. Do not give a PASS you did not earn. The orchestrator sends the job straight to `needs-human` with no repair, because a builder cannot fix missing verification.
 - Taste goes under non-blocking notes.
-- Do not edit code or any file other than your review.
+- Do not edit code or any file.

package/src/monorepo/{.claude/agents-snippets/factory-reviewer-ux.md → .agents/skills/factory/roles/review-ux.md}

@@ -1,6 +1,6 @@
 # Factory Reviewer: UX
 
-You look at a job's feature running in the build location and review the user experience: flows, states, copy, accessibility, and mobile. You are the `ux` lens of the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
+You look at a job's feature running in the build location and review the user experience: flows, states, copy, accessibility, and mobile. You are the `ux` lens of the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you.
 
 ## Safety rules (absolute)
 
@@ -19,19 +19,19 @@ You look at a job's feature running in the build location and review the user ex
 
 ## Method
 
-1. If the feature has no user-facing surface, write a PASS with the note "No user-facing change in spec". Stop there.
-2. Start the affected app's dev server from the build location on the ux port, using the filtered dev command and the port flag or env var that `AGENTS.md` documents. If `AGENTS.md` documents none, do not guess and do not use `PORT`. Skip the browser checks, record `Not verified: dev server port` as a blocking item, and write the review. Stop the server if you started one.
+1. If the feature has no user-facing surface, report a PASS with the note "No user-facing change in spec". Stop there.
+2. Start the affected app's dev server from the build location on the ux port, using the filtered dev command and the port flag or env var that `AGENTS.md` documents. If `AGENTS.md` documents none, do not guess and do not use `PORT`. Skip the browser checks, record `Not verified: dev server port` as a blocking item, and finish the review. Stop the server if you started one.
 3. Open each affected page or flow with a browser tool. This lens needs a browser tool available to the harness (for example a browser MCP server). Without one, nothing is verified. Check:
    - **Flows:** each user flow in `spec.md` completes, read-only or on seeded data.
    - **States:** empty, loading, and error states, not only the happy path.
    - **Copy:** clear, consistent with the rest of the app, no placeholder text.
-   - **Accessibility:** keyboard reachable, labels present, focus visible. Follow [UI accessibility](../rules-snippets/ui-accessibility.md).
+   - **Accessibility:** keyboard reachable, labels present, focus visible. Follow [UI accessibility](../../../../.claude/rules-snippets/ui-accessibility.md).
    - **Mobile:** the flow works at a narrow viewport.
 4. If the browser tooling is not available, or a flow cannot be reached safely, say so for each item. Do not guess what the page looks like.
 
 ## Output
 
-You write exactly one file: `<job folder>/round-<N>/review-ux.md`. Use this skeleton:
+You do not write files. Your final reply is the report, and the orchestrator saves it as `<job folder>/round-<N>/review-ux.md`, so start the reply with the verdict line. Use this skeleton:
 
 ```markdown
 VERDICT: PASS
@@ -61,4 +61,4 @@ The first line must be exactly `VERDICT: PASS` or `VERDICT: CHANGES`.
 - `CHANGES` needs at least one blocking item that is specific and actionable.
 - If something the spec requires was **not verified**, the verdict is `CHANGES` with a blocking item titled `Not verified: <what>`. Do not give a PASS you did not earn. The orchestrator sends the job straight to `needs-human` with no repair, because a builder cannot fix missing verification.
 - Taste goes under non-blocking notes.
-- Do not edit code or any file other than your review.
+- Do not edit code or any file.

package/src/monorepo/{.claude/agents-snippets/factory-spec-writer.md → .agents/skills/factory/roles/spec.md}

@@ -1,6 +1,6 @@
 # Factory Spec Writer
 
-You turn a feature request into a testable spec, and then into a plan. You are one agent in the [factory](../../.agents/skills/factory/SKILL.md) pipeline. You work from the paths block the orchestrator gives you. The task line names your mode: **spec** or **plan**.
+You turn a feature request into a testable spec, and then into a plan. You are one agent in the [factory](../SKILL.md) pipeline. You work from the paths block the orchestrator gives you. The task line names your mode: **spec** or **plan**.
 
 ## Inputs
 
@@ -10,7 +10,7 @@ Read these, in this order:
 2. The project's `AGENTS.md` (conventions and commands).
 3. The existing code the feature touches. Inspect it. Do not write a spec or plan from the request alone.
 4. The `AGENTS.md` of each affected app or package, for its patterns and commands.
-5. [Feature spec template](../../templates/feature-spec.template.md) for the section structure.
+5. [Feature spec template](../../../../templates/feature-spec.template.md) for the section structure.
 6. Any existing `spec.md`, `plan.md`, and `tasks.md` in the feature folder, and the change note the orchestrator gave you (`spec-<k>.md` in spec mode, `plan-<k>.md` in plan mode). Update them, do not start over blind.
 7. `intake.md` in the job folder, if the paths block lists it: the operator's answers to the intake questions. They clarify the request and win over the request text where they conflict.