nitm-ai-dev-toolkit 5.0.0 → 5.1.0

package/src/repo/{.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 dev server from the build location on the ui port, using the project's documented port flag or env var. 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 dev server from the build location on the ui port, using the project's documented port flag or env var. 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/repo/{.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 dev server from the build location on the ux port, using the project's documented port flag or env var. 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 dev server from the build location on the ux port, using the project's documented port flag or env var. 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/repo/{.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
 
@@ -9,7 +9,7 @@ Read these, in this order:
 1. The feature request in your prompt.
 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. [Feature spec template](../../templates/feature-spec.template.md) for the section structure.
+4. [Feature spec template](../../../../templates/feature-spec.template.md) for the section structure.
 5. 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.
 6. `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.
 

package/src/repo/.claude/agents/implementer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "implementer"
 description: "Implement code changes for a specific task. Follow TDD, write tests alongside code, and self-review before reporting completion."
-tools: ["Read", "Grep", "Write", "Edit", "Bash(*)"]
+tools: ["Read", "Grep", "Glob", "Write", "Edit", "Bash(*)"]
 user-invocable: true
 ---
 

package/src/repo/.claude/agents/planner.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "planner"
 description: "Break down feature requests into implementation tasks. Read specifications, analyze codebase patterns, and produce structured plans with dependencies."
-tools: ["Read", "Grep", "Write"]
+tools: ["Read", "Grep", "Glob", "Write", "Bash(*)"]
 user-invocable: true
 ---
 

package/src/repo/.claude/agents/reviewer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "reviewer"
 description: "Review code changes for correctness, code quality, security, and adherence to project patterns. Provide actionable feedback with specific file and line references. Use immediately after writing or modifying code, or as a quality gate in orchestrated workflows."
-tools: ["Read", "Grep", "Write", "Bash(*)"]
+tools: ["Read", "Grep", "Glob", "Write", "Bash(*)"]
 user-invocable: true
 ---
 

package/src/repo/.claude/commands/assign-tasks.md

@@ -7,6 +7,7 @@ argument-hint: "requirements or task file path"
 # Create Tickets from Requirements
 
 ## Agent Dispatch
+
 > **Recommended agent:** `fixer`
 > Task assignment and execution
 

package/src/repo/.claude/commands/factory.md

@@ -1,5 +1,5 @@
 ---
-description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, merge (local, or a merge request on the forge)"
 allowed-tools: "Read, Grep, Glob, Write, Edit, Bash(*), agent"
 argument-hint: "[--in-place] <feature request> | start [--in-place] <request | KEY | slug | job-id> | approve <job-id> | rework <job-id> <note> | abandon <job-id> | status [--all] | watch [--all] | archive [--all] [--dry-run] | prune [--all] [--abandoned] [--dry-run]"
 ---
@@ -11,14 +11,14 @@ argument-hint: "[--in-place] <feature request> | start [--in-place] <request | K
 
 | Agent | When to use |
 |-------|-------------|
-| `factory-spec-writer` | Spec stage (`spec` mode) writes `spec.md`; plan stage (`plan` mode) writes `plan.md` and `tasks.md` |
-| `factory-builder` | Build, repair, and rework: writes `build.md` in the job folder; its code goes in the build location |
-| `factory-reviewer-code` | Review round, `code` lens |
-| `factory-reviewer-security` | Review round, `security` lens |
-| `factory-reviewer-ux` | Review round, `ux` lens (opt-in) |
-| `factory-reviewer-ui` | Review round, `ui` lens (opt-in) |
-| `factory-approver` | Approval gate: writes `decision.md` |
+| `planner` | Spec writer. Spec stage (`spec` mode) writes `spec.md`; plan stage (`plan` mode) writes `plan.md` and `tasks.md`. Brief: `.agents/skills/factory/roles/spec.md` |
+| `implementer` | Builder. Build, repair, and rework: writes `build.md` in the job folder; its code goes in the build location. Brief: `.agents/skills/factory/roles/build.md` |
+| `reviewer` | Code reviewer. Review round, `code` lens. Brief: `.agents/skills/factory/roles/review-code.md` |
+| `reviewer` | Security reviewer, fresh context. Review round, `security` lens. Brief: `.agents/skills/factory/roles/review-security.md` |
+| `reviewer` | UX reviewer. Review round, `ux` lens (opt-in). Brief: `.agents/skills/factory/roles/review-ux.md` |
+| `reviewer` | UI reviewer. Review round, `ui` lens (opt-in). Brief: `.agents/skills/factory/roles/review-ui.md` |
+| `reviewer` | Approver, fresh context. Approval gate: returns the decision, which the orchestrator saves as `decision.md`. Brief: `.agents/skills/factory/roles/approve.md` |
 
-Dispatch each agent by its kebab-case name, as in the first column. Copilot may show a display name; pick the agent with that name.
+Dispatch each native agent by the name in the first column, and tell it to read the brief in the last column first. Reviewers and the approver return their report, and the orchestrator saves it. Copilot may show a display name; pick the agent with that name.
 
 Follow the prompt defined in [.claude/prompt-snippets/factory.md](../prompt-snippets/factory.md).

package/src/repo/.claude/commands/ponytail-review.md

@@ -1,6 +1,6 @@
 ---
 description: Review changes for over-engineering — find what can be deleted
-allowed-tools: "Read, Grep"
+allowed-tools: "Read, Grep, Bash(git diff:*), Bash(git status:*), Bash(git show:*)"
 argument-hint: "no arguments required"
 ---
 

package/src/repo/.claude/prompt-snippets/assign-tasks.md

@@ -50,11 +50,17 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
 1. **Parse Document**:
    - Load the specified document (.md, .txt, .json)
    - Detect document structure (headers, lists, task categories)
-   - For `tasks.md`: each `- [ ]` line is one task. The text after the ID is the summary. A trailing ` — <KEY>` means a ticket already exists, so skip that line. Sub-bullets, if any, are subtasks
+   - For `tasks.md`, detect the format first:
+     - **Slim** (has `- [ ] T<n>` or `- [x] T<n>` lines): each such line is one task. The text after the ID is the summary. Sub-bullets, if any, are subtasks. A line already has a ticket only when it ends with ` — {{PROJECT_KEY}}-<digits>`; skip it then. Any other ` — ` suffix (e.g. ` — depends on T3`) is a note, not a key: keep the line
+     - **Legacy** (no slim lines; has `#{2,4} T<n>` headings, e.g. `## T01`, `### T001`): each `T<n>` heading is one task. Checkboxes beneath it are subtasks: put them in the ticket description, never as separate tickets. Skip a heading that contains `{{PROJECT_KEY}}-<digits>` anywhere (e.g. `## T001 (PROJ-256): …`); it already has a ticket
+     - **Mixed** (slim lines and legacy headings): treat as slim and say in the report that the headings were ignored
+     - **Neither**: treat as a requirement document
+     - Keys are always `{{PROJECT_KEY}}-<digits>`. Nothing else counts as a key
    - For requirement documents: extract task hierarchy: Epic → Story → Task → Subtask
 
 2. **Consolidate First** (BEFORE creating tickets):
-   - **A `tasks.md` from `/tasks` is pre-consolidated**: one line = one ticket. Only merge lines that are clearly one deliverable; do not re-split them
+   - **A slim `tasks.md` from `/tasks` is pre-consolidated**: one line = one ticket. Only merge lines that are clearly one deliverable; do not re-split them
+   - **A legacy `tasks.md` is not pre-consolidated**: one heading = one ticket. Never merge or re-split headings. If the count exceeds the Maximum Ticket Counts, stop and ask before creating anything
    - **Group related items** by component, feature area, or deliverable
    - **Merge small tasks** (< 2 SP) into related larger tasks
    - **Eliminate redundant subtasks** that are obvious steps
@@ -79,10 +85,12 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - Set assignees, labels, and story points
    - Create dependency links where noted
    - Ticket description: the task summary plus the acceptance criteria from `spec.md` for that deliverable
-   - Write each ticket key back to its `tasks.md` line after the em dash (`- [ ] T1 Schema + migration — PROJ-124`)
+   - **Slim `tasks.md`**: append ` — <KEY>` at the end of the task's line, after any notes (`- [ ] T1 Schema + migration — PROJ-124`)
+   - **Legacy `tasks.md`**: never write back. Record heading → ticket key in the report instead
 
 6. **Generate Report**:
    - List all created tickets with IDs
+   - **Legacy `tasks.md`**: heading → ticket key mapping, plus headings skipped because they already had a key
    - Show hierarchy and relationships
    - Report total story points
    - **Consolidation summary**: "Merged X raw items into Y tickets"
@@ -153,6 +161,8 @@ Creating tickets...
 
 ## Document Format Support
 
+**Legacy `tasks.md` worked example**: a file with 45 `## T<n>` / `### T<n>` headings and 266 checkboxes plans **45 tickets**, not 266. Each ticket's description lists that heading's checkboxes. If 2 headings already carry a `{{PROJECT_KEY}}-<digits>` key, plan 43. Do not modify the file; report the heading → key mapping.
+
 **Markdown Headers**:
 
 ```markdown

package/src/repo/.claude/prompt-snippets/bootstrap-patch.md

@@ -1,12 +1,12 @@
 # Bootstrap Patch
 
-Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit repository's `v4.x` branch and merge updated, new, or missing guidance into this project.
+Fetch the published toolkit templates for the target version (4.0.0 or later) from npm or the ai-assisted-dev-toolkit repository's `<version>` git tag, and merge updated, new, or missing guidance into this project.
 
 ## OpenCode version preflight (before any changes)
 
 - Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
-- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
-- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.0.0 and later require `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as 4.0.0 or later. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
 - If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
 - If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
@@ -25,6 +25,8 @@ Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit reposito
 /bootstrap-patch --category commands,prompts
 ```
 
+The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit patch --dry-run` previews changes, `--only <categories>` and `--exclude <categories>` narrow the scope, and `npx nitm-ai-dev-toolkit upgrade@<version>` (or `--version <version>`) pins the target version. Pinning a version does not skip the gates in Step 1.
+
 ## Process
 
 **Codex invocation and scope:** `/bootstrap-patch` is not a native Codex command. Ask Codex to read and follow this snippet as a task document. Identify the actual harness from session/runtime evidence or ask; scaffold directories do not prove use. Codex targets `AGENTS.md`, relevant nested instructions, `.agents/skills/`, and optional `.codex/config.toml`. Include `.github/instructions/` and `.claude/rules-snippets/` solely as AGENTS-linked standards and their wrapper sources for Codex-scoped installs, not automatically loaded rules or evidence of Copilot/Claude use. Only include other harness command, agent, and config categories when those harnesses are confirmed in use.
@@ -33,33 +35,38 @@ Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit reposito
 
 1.  **Fetch Latest Templates**:
 
-    Fetch only the supported `v4.x` source branch:
+    **Resolve versions before any download.**
+    - **Installed version**: read `.toolkit-version` in the project root. If it is missing or unparseable, **STOP** and ask the user to confirm the installed version; absence alone does not prove a pre-3.0 installation.
+    - **Target version**: use the version the user pinned (`upgrade@<version>` or `--version <version>` in the CLI, or the version given to this task), validated as SemVer `X.Y.Z`. Otherwise use the latest published version from `npm view nitm-ai-dev-toolkit version`. If npm is unreachable or the output is unparseable, **STOP** and ask. Never guess a version.
+
+    **Fetch the matching release.** Try Option A first and use Option B only if `npm pack` fails (for example, the version is not on npm). Each download goes into a new, empty directory:
 
     ```bash
     set -e
-    TOOLKIT_TEMP=$(mktemp -d)
-    git clone --depth 1 --branch v4.x https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
+    TOOLKIT_TEMP=$(mktemp -d)   # removed in step 6
+    mkdir "$TOOLKIT_TEMP/pack" "$TOOLKIT_TEMP/unpacked"
+    # Option A (preferred): the published package, the same artifact users install
+    if (cd "$TOOLKIT_TEMP/pack" && npm pack "nitm-ai-dev-toolkit@<version>"); then
+      tar -xzf "$TOOLKIT_TEMP/pack/nitm-ai-dev-toolkit-<version>.tgz" -C "$TOOLKIT_TEMP/unpacked"
+      SOURCE_ROOT="$TOOLKIT_TEMP/unpacked/package"
+    else
+      # Option B (fallback): the git tag for that release (tags have no "v" prefix)
+      git clone --depth 1 --branch "<version>" https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP/git"
+      SOURCE_ROOT="$TOOLKIT_TEMP/git"
+    fi
     ```
 
-    **Source availability gate:** If the clone fails or `v4.x` is unavailable (for example, not yet published), **STOP** before diff/apply/version marking. Do not fall back to the default branch or V3, and do not push/publish a branch to unblock this task; ask for an approved available v4.x source.
+    **Source availability gate:** If both `npm pack` and the tag clone fail (the version is unpublished and the tag is missing), **STOP** before diff/apply/version marking. Do not fall back to the default branch, another version, or an older major, and do not publish anything to unblock this task; ask for an available source version.
 
-    Determine the correct source path based on project structure:
-    - **Single repo**: Use `$TOOLKIT_TEMP/src/repo/`
-    - **Monorepo**: Use `$TOOLKIT_TEMP/src/monorepo/`
+    Determine the correct source path based on project structure, under `$SOURCE_ROOT`:
+    - **Single repo**: `$SOURCE_ROOT/src/repo/`
+    - **Monorepo**: `$SOURCE_ROOT/src/monorepo/`
 
     Detection heuristic:
     - If `apps/` and `packages/` directories exist at root → monorepo
     - Otherwise → single repo
 
-    **Detect Toolkit Version:**
-
-    Check for a `.toolkit-version` file in the project root:
-    - If exists: Read the version string (e.g., `2.0.10`, `3.0.0`)
-    - If missing: Verify the installed version or legacy state with the user; absence alone does not prove a pre-3.0 installation
-
-    Read the toolkit's version from the `version` field in `$TOOLKIT_TEMP/package.json` to compare; `.toolkit-version` tracks the target project's installed version.
-
-    **Source version guard (before diff/apply/version marking):** Parse source/target versions as SemVer and compare them (major/minor/patch numerically). If the fetched package's major is not `4`, or its version is older than the target `.toolkit-version`, **STOP** without diffing, applying changes, or updating the marker. Unknown/unparseable versions must also **STOP** and ask rather than guess. Never auto-downgrade.
+    **Source version gate (before diff/apply/version marking):** Read the `version` field in `$SOURCE_ROOT/package.json` and parse it as SemVer. The fetched version must equal the target version exactly, its major must be greater than or equal to the installed major from `.toolkit-version`, and it must not be older than the installed `.toolkit-version`. If any check fails, or a version is unknown or unparseable, **STOP** without diffing, applying changes, or updating the marker. Never auto-downgrade, and never hard-code a major.
 
     **Version Comparison:**
     - **Same version**: No structural changes expected
@@ -100,11 +107,11 @@ Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit reposito
 
     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 schema may describe V1; neither it nor a V1 API fetch validates native V2. Plural keys are intentional.
 
-    - Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
+    - Use `agents`/`system`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
     - The version preflight must pass before changes. Back up V1 before native conversion (converted files are incompatible with V1). Preserve models/providers/user-global plugins. Only with approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema keeps `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter.
-    - **Ponytail replacement (plan here; apply after backup and approval in Step 5):** Remove only known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies. Preserve unrelated local plugins. Merge/deduplicate the author's native V2 `@dietrichgebert/ponytail@4.12.0` registration in the local `plugins` array where appropriate, retaining other registrations/options; do not edit global config. Keep `opentmux` commented as V1-only. Do not port local APIs or add bridges; runtime integration is untested. Native local discovery needs no duplicate registration.
-    - `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text: explicitly read snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
-    - `--env opencode` supplies minimal shared references without other harness activation. Activate on the next run/restart and report only installed-V2 checks actually run, not assumed runtime validation. Publishing 4.0.0 has not been executed.
+    - **Obsolete Ponytail cleanup (plan here; apply after backup and approval in Step 5):** Remove only known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies. Preserve unrelated local plugins. The OpenCode Ponytail plugin is installed globally by the operator; never add it to project config. If it is not installed globally, tell the operator to install it globally. Do not edit global config. Keep `opentmux` commented as V1-only. Do not port local APIs or add bridges; runtime integration is untested.
+    - Ambient `AGENTS.md` works. `instructions` entries load only when the runtime injects them (OpenChamber does; other hosts may not), so do not rely on them: write explicit "Read and follow" wrappers regardless. `@refs` are ordinary text: explicitly read snippets. Do not set a temperature; the current runner does not send one. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
+    - `--env opencode` supplies minimal shared references without other harness activation. Activate on the next run/restart and report only installed-V2 checks actually run, not assumed runtime validation.
 
 3.  **Diff Analysis** (parallelizable — dispatch one subagent per category):
 
@@ -175,8 +182,8 @@ Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit reposito
       a. **New files**: Copy directly from template
       b. **Updated files (no customization)**: Replace with template version
       c. **Updated files (customized)**: Apply structural additions while preserving project values
-      d. **OpenCode plugins**: Apply only the approved Ponytail replacement above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins.
-      e. **Toolkit version**: Update `.toolkit-version` to the fetched toolkit version (`4.0.0` for this migration) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
+      d. **OpenCode plugins**: Apply only the approved obsolete Ponytail cleanup above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins. Never add Ponytail to project config.
+      e. **Toolkit version**: Keep the `.toolkit-version` value the CLI writes for the verified target version (the installed package version, 4.0.0 or later; never hard-coded) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
       f. **Git commit**: Stage and commit all changes with message:
       ```bash
       git add -A

package/src/repo/.claude/prompt-snippets/bootstrap-upgrade.md

@@ -1,12 +1,12 @@
-# Bootstrap Upgrade to v4.0
+# Bootstrap Upgrade to toolkit <version>
 
-Upgrade to toolkit 4.0.0, including native OpenCode V2 for confirmed OpenCode users. For pre-3.0 installations, also migrate inline content to snippet-based architecture and clean up duplicate skills. Only modify confirmed harness targets; preserve unrelated harness/Codex behavior.
+Upgrade to toolkit <version> (the installed package version), including native OpenCode V2 for confirmed OpenCode users (toolkit 4.0.0 and later). For pre-3.0 installations, also migrate inline content to snippet-based architecture and clean up duplicate skills. Only modify confirmed harness targets; preserve unrelated harness/Codex behavior.
 
 ## OpenCode version preflight (before any changes)
 
 - Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
-- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
-- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.0.0 and later require `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as 4.0.0 or later. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
 - If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
 - If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
@@ -21,7 +21,7 @@ Read `.toolkit-version` and select the route before dispatching agents or changi
 
 ## OpenCode migration guardrails
 
-Back up V1; native-converted files are incompatible with V1. Preserve models/providers/user-global plugins. Templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0`; obsolete toolkit-local Ponytail copies are replaced only after backup and approval (Step 7), with no API port or bridge. Keep `opentmux` commented as V1-only. Only with approval, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter. Activate on the next run/restart; plugin/runtime integration is untested and publishing 4.0.0 has not been executed.
+Back up V1; native-converted files are incompatible with V1. Preserve models/providers/user-global plugins. The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator and is never registered by templates or project config; obsolete toolkit-local Ponytail copies are removed only after backup and approval (Step 7), with no API port or bridge. Keep `opentmux` commented as V1-only. Only with approval, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter. Activate on the next run/restart; plugin/runtime integration is untested.
 
 ## Usage
 
@@ -56,7 +56,7 @@ Run all checks before making any changes:
 3. **Confirm migration scope**:
 
    ```markdown
-   ## 🔄 Bootstrap Upgrade: toolkit v4.0.0
+   ## 🔄 Bootstrap Upgrade: toolkit <version>
 
     **Project type**: repo | monorepo
     **Current version**: <version or "none (legacy)">
@@ -68,7 +68,7 @@ Run all checks before making any changes:
     2.  Confirmed OpenCode only: merge native V2 host files and approved missing wrappers (Step 7)
     3.  Verified legacy only: approved hook installation and verified identical duplicate skill cleanup (Steps 8–10); preserve custom skills
     4.  Merge only applicable missing documentation and validate the selected route; v3 keeps existing snippet bodies/frontmatter unchanged
-    5.  Create `.toolkit-version` with `4.0.0` after the approved migration
+    5.  Keep the `.toolkit-version` the CLI writes (installed package version, 4.0.0 or later) after the approved migration
     6.  Commit all changes
 
    Proceed? (Y/n)
@@ -176,18 +176,17 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
      "$schema": "https://opencode.ai/config.json",
       "instructions": ["AGENTS.md", ".opencode/rules/*.md"],
       "skills": [".agents/skills"],
-      "plugins": ["@dietrichgebert/ponytail@4.12.0"],
       "lsp": true
    }
    ```
 
-   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 schema may describe V1; do not use it or a V1 API fetch as native V2 validation authority. Use `agents`/JSON `system` (Markdown bodies for file agents), `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `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 schema may describe V1; do not use it or a V1 API fetch as native V2 validation authority. Use `agents`/JSON `system` (Markdown bodies for file agents), ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
 
-   `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text, not attachments: wrappers must explicitly tell agents to read referenced snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics). `--env opencode` supplies minimal shared references without other harness activation. Verify using installed V2 after the next run/restart; report only checks actually run.
+   Ambient `AGENTS.md` works. `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 attachments: wrappers must explicitly tell agents to read referenced snippets. Do not set a temperature; the current runner does not send one. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics). `--env opencode` supplies minimal shared references without other harness activation. Verify using installed V2 after the next run/restart; report only checks actually run.
 
 2. **Replace obsolete toolkit Ponytail (backup and approval only)**:
    - Back up the local config and known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies; obtain approval before removing only those copies. Preserve unrelated local plugins.
-   - Merge/deduplicate the author's native V2 `@dietrichgebert/ponytail@4.12.0` package in the local `plugins` array where appropriate, preserving other registrations/options. Do not edit global config or overwrite global plugins. Keep `opentmux` commented as V1-only; do not copy local Ponytail source, port APIs, or introduce bridges. Native local discovery needs no duplicate explicit registration; runtime integration remains untested.
+   - The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator. Never add or pin it in the local `plugins` array. Check whether it is installed globally; if not, tell the operator to install it globally. Do not edit global config or overwrite global plugins. Keep `opentmux` commented as V1-only; do not copy local Ponytail source, port APIs, or introduce bridges. Runtime integration remains untested.
 
 3. **Create wrappers with explicit snippet-read instructions** — one file per snippet:
 
@@ -252,12 +251,13 @@ If `CLAUDE.md` is an applicable confirmed harness target and a thin redirect to
 
 See existing `CLAUDE.md` in the toolkit template (`src/repo/CLAUDE.md`) for the exact format.
 
-### 12. Create `.toolkit-version` File
+### 12. Check `.toolkit-version` File
 
 Only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope):
 
 ```bash
-echo "4.0.0" > .toolkit-version
+# Keep the value the CLI wrote (the installed package version). If it is missing, record it with the CLI:
+npx nitm-ai-dev-toolkit patch
 ```
 
 ### 13. Validation
@@ -277,13 +277,13 @@ If `--verbose`: log each check result with file paths.
 
 ### 14. Generate Upgrade Report
 
-Output the report to stdout (and optionally to `docs/upgrade-report-v4.md`). Include only operations/checks actually performed for the selected route; omit legacy extraction/cleanup rows on v3 and never pre-mark skipped checks as passed:
+Output the report to stdout (and optionally to `docs/upgrade-report-<version>.md`). Include only operations/checks actually performed for the selected route; omit legacy extraction/cleanup rows on v3 and never pre-mark skipped checks as passed:
 
 ```markdown
 ## 🚀 Bootstrap Upgrade Report
 
 **From**: detected installed version (include inline extraction only for pre-3.0)
-**To**: 4.0.0 (native V2 for confirmed OpenCode use; snippet conversion only for verified legacy)
+**To**: <version> (toolkit 4.0.0 or later; native V2 for confirmed OpenCode use; snippet conversion only for verified legacy)
 **Selected route**: verified legacy | v3 native OpenCode
 **Date**: {{DATE}}
 **Dry run**: yes | no
@@ -317,7 +317,7 @@ Output the report to stdout (and optionally to `docs/upgrade-report-v4.md`). Inc
 
 ### Files Created
 
-- `.toolkit-version` — 4.0.0
+- `.toolkit-version` — installed package version (written by the CLI)
 
 ### Validation
 
@@ -337,7 +337,7 @@ If not `--dry-run`, stage and commit all changes:
 
 ```bash
 git add -A
-git commit -m "chore: upgrade AI instructions to toolkit v4.0.0"
+git commit -m "chore: upgrade AI instructions to toolkit <version>"
 ```
 
 If `--dry-run`: skip commit, note in report: "Dry run — no changes committed."

package/src/repo/.claude/prompt-snippets/bootstrap.md

@@ -5,8 +5,8 @@ Analyze the project structure and customize AI instruction templates for this co
 ## OpenCode version preflight (before any changes)
 
 - Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
-- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
-- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.0.0 and later require `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as 4.0.0 or later. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
 - If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
 - If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
@@ -126,9 +126,9 @@ Map discovered information to template variables:
 | `{{PROJECT_KEY}}`           | Project ID or workspace ID (if applicable)                                                                                                                                                                 |
 | `{{PM_ISSUE_KEY}}`          | Issue key format (e.g., PROJ-###)                                                                                                                                                                          |
 | `{{DEFAULT_BRANCH}}`        | `git symbolic-ref --short refs/remotes/origin/HEAD`, minus `origin/`; else `main`                                                                                                                          |
-| `{{FACTORY_PORT_BASE}}`     | Default `5100`                                                                                                                                                                                             |
-| `{{APPROVAL_MODE}}`         | Default `human`                                                                                                                                                                                            |
-| `{{FACTORY_REVIEW_LENSES}}` | Default `code, security`; add `ux, ui` only if the project has a UI and a browser tool is configured (for example a browser MCP server)                                                                    |
+| `{{FACTORY_PORT_BASE}}`     | Only if Factory is installed. Default `5100`                                                                                                                                                                                             |
+| `{{APPROVAL_MODE}}`         | Only if Factory is installed. Default `human`                                                                                                                                                                                            |
+| `{{FACTORY_REVIEW_LENSES}}` | Only if Factory is installed. Default `code, security`; add `ux, ui` only if the project has a UI and a browser tool is configured (for example a browser MCP server)                                                                    |
 | `{{NEW_RELEVANT_VARIABLE}}` | ...other inferred values...                                                                                                                                                                                |
 
 ### Step 2.5: Project Management Detection
@@ -250,25 +250,25 @@ Replace placeholders in all template files:
 
 Follow the 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) guides, not a V1 API/schema fetch. The published schema URL may still describe V1; do not use it to reject native plural keys.
 
-- After the version preflight passes, use `agents` with JSON `system` or Markdown bodies; `request.body.temperature`; ordered `permissions` rules (`action`, `resource`, `effect`; `shell`/`subagent`; last match wins); `commands` with `subagent`; `plugins` with `{ "package": "…", "options": {} }`; `skills` as directory-path arrays; `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
+- After the version preflight passes, use `agents` with JSON `system` or Markdown bodies; ordered `permissions` rules (`action`, `resource`, `effect`; `shell`/`subagent`; last match wins); `commands` with `subagent`; `plugins` with `{ "package": "…", "options": {} }`; `skills` as directory-path arrays; `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
 - Back up V1; native-converted files are incompatible with V1. Merge, don't clobber models/providers/user-global plugins. With approval only, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema retains its own `prompt`, `permission`, and `variant`; do not host-migrate it or upgrade the separate external starter silently.
-- Templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0` locally; no local Ponytail source is bundled or ported. Keep `opentmux` commented as V1-only. Native local discovery needs no duplicate registration; do not introduce API ports or bridges or claim tested runtime integration.
-- Config `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text: explicitly read referenced snippet docs. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`, but use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics).
-- `--env opencode` supplies minimal shared references without activating other harnesses. Activate on the next run/restart and report only checks actually run using installed V2; scaffold/placeholder checks are not runtime validation. Publishing 4.0.0 has not been executed.
+- The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`, the author's native V2 package) is installed globally by the operator. Templates do not register or pin it, and no local Ponytail source is bundled or ported. Keep `opentmux` commented as V1-only. Do not introduce API ports or bridges or claim tested runtime integration.
+- 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: explicitly read referenced snippet docs. Do not set a temperature; the current runner does not send one. Preserve `lsp: true`, but use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics).
+- `--env opencode` supplies minimal shared references without activating other harnesses. Activate on the next run/restart and report only checks actually run using installed V2; scaffold/placeholder checks are not runtime validation.
 
 **Ponytail pre-activation cleanup (confirmed OpenCode use only):**
 
 1. In this bootstrap flow, inspect `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` for existing-target leftovers. Verify obsolete toolkit ownership from contents/provenance, not filename alone; absent paths need no deletion. Preserve unrelated/custom plugins and global config.
 2. Back up the local config and verified obsolete toolkit copies, obtain explicit removal approval, then remove ONLY those copies. Do not automatically delete files in the CLI or remove custom plugins.
-3. With approval, merge/deduplicate upstream `@dietrichgebert/ponytail@4.12.0` registration locally where appropriate, preserving other registrations/options and leaving global config untouched. No API port or bridge.
+3. Never add `@dietrichgebert/ponytail` to project `.opencode/opencode.jsonc`. Check whether it is installed globally; if not, tell the operator to install it globally and leave global and project config untouched. No API port or bridge.
 4. If any present copy's ownership or safe removal is unverified, or required removal approval is denied, **STOP OpenCode activation and migration completion**; leave `.toolkit-version` unchanged and report blocked, not complete. Proceed/restart only after this gate passes; runtime integration remains untested.
 
 **Create Toolkit Version File:**
 
-Create a `.toolkit-version` file in the project root with the current toolkit version only after the OpenCode preflight and Ponytail cleanup gate pass (or OpenCode is confirmed out of scope):
+Confirm `.toolkit-version` in the project root. The CLI writes it on install and patch with the installed package version. For toolkit 4.0.0 or later, keep the value the CLI wrote; do not write it by hand or overwrite it with a hard-coded version. If it is missing, run `npx nitm-ai-dev-toolkit patch` only after the OpenCode preflight and Ponytail cleanup gate pass (or OpenCode is confirmed out of scope). Expected form:
 
 ```
-4.0.0
+<installed package version, for example 5.0.0>
 ```
 
 This file enables `bootstrap-patch` to detect version changes and apply migrations automatically.

package/src/repo/.claude/prompt-snippets/factory.md

@@ -1,5 +1,5 @@
 ---
-description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, merge (local, or a merge request on the forge)"
 ---
 
 You are the factory orchestrator for this session. Arguments: $ARGUMENTS
@@ -8,13 +8,13 @@ Follow the [factory orchestrator skill](../../.agents/skills/factory/SKILL.md) e
 
 Ground rules:
 
-- Run the orchestrator in this session. Dispatch the `factory-*` agents for every spec, plan, build, review, and approval step, and do not write their files yourself.
-- Only write `job.json`, `intake.md`, `spec-<k>.md`, `plan-<k>.md`, `rework-<k>.md`, the escalation `decision.md`, `merge-conflict.md`, the ticket keys in `tasks.md`, the feature folder rename or copy, the feature docs commit on the job branch, and worktree, branch, or merge steps, and the `archive` moves.
+- Run the orchestrator in this session. Dispatch the native agents (`planner`, `implementer`, `reviewer`, see the skill's Subagent dispatch) for every spec, plan, build, review, and approval step, and do not write their files yourself. Reviewers and the approver return their reports, which you save.
+- Only write `job.json`, `intake.md`, `spec-<k>.md`, `plan-<k>.md`, `rework-<k>.md`, the review files and `decision.md` from the reviewer and approver replies, the escalation `decision.md`, `merge-conflict.md`, `bootstrap.md`, the ticket keys in `tasks.md`, the feature folder rename or copy, the feature docs commit on the job branch, and worktree, branch, or merge steps, and the `archive` moves.
 - Intake asks in chat before any folder, job, or spec exists. Hold the intake gate: nothing is created until the operator picks to continue.
 - Hold the spec gate and the plan gate: nothing is planned, ticketed, or built until the operator confirms in chat. The spec cannot be confirmed while a `[PRODUCT DECISION]` item is open.
 - `--in-place` on the command, or the operator saying in place, builds in the main checkout instead of a worktree. Only a new job takes it.
 - `abandon <job-id>` closes a job without merging it. Ask first when an agent may still be running.
-- Never push. Merges stay local.
+- Local merges never push. With `MERGE_MODE` set to `push-mr`, the branch is pushed and its merge request opened only on `/factory approve` or an `auto` APPROVE, and never force-pushed.
 - `archive` moves closed jobs only, to `factory/archive/`. It deletes an abandoned job's branch and worktree only after the operator says yes.
-- `prune` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation in chat: merged jobs by default, and abandoned jobs too with `--abandoned`. It never touches an open job or `docs/features/`.
+- `prune` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation in chat: merged jobs by default, and abandoned jobs too with `--abandoned`. It never touches an open job or the feature folders.
 - If `$ARGUMENTS` is empty, show the invocation list from the skill and ask which one the user wants.

package/src/repo/.claude/prompt-snippets/implement-feature.md

@@ -85,7 +85,9 @@ Implement a feature by completing tasks sequentially with proper tracking.
    git commit -m "feat({{SCOPE}}): {{DESCRIPTION}}"
    ```
 
-   f. **Mark Task Complete**: tick `- [x]` for the task in `tasks.md`
+   f. **Mark Task Complete**:
+   - Slim `tasks.md`: tick `- [x]` on the task's line
+   - Legacy `tasks.md`: tick `- [x]` only on checkboxes under the current task's heading (until the next heading). Never tick checkboxes under other headings. If that heading has no checkboxes, report "no checkboxes under <heading>; nothing ticked" and continue
 
 5. **Post-Implementation Review**:
    - Dispatch **Reviewer** agent on all changes before proceeding

package/src/repo/.claude/rules-snippets/subagent-workflow.md

@@ -103,8 +103,8 @@ Before executing any task list, the orchestrator MUST run this analysis:
    - **Mixed** → Dispatch independent group in parallel, then continue sequential chain
 
 ```
-Example: 5 tasks → T001 (setup) → T002 [P] (backend API) + T003 [P] (frontend UI) + T004 [P] (docs) → T005 (integration tests)
-         Dispatch: T001 sequential → T002+T003+T004 parallel → T005 sequential
+Example: 5 tasks → T1 (setup) → T2 [P] (backend API) + T3 [P] (frontend UI) + T4 [P] (docs) → T5 (integration tests)
+         Dispatch: T1 sequential → T2+T3+T4 parallel → T5 sequential
 ```
 
 ## Quality Gates