nitm-ai-dev-toolkit 3.0.23 → 5.0.0

package/src/monorepo/.claude/agents-snippets/factory-spec-writer.md

@@ -0,0 +1,119 @@
+# 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**.
+
+## Inputs
+
+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. 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.
+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.
+
+## Spec mode
+
+You write `spec.md` in the feature folder (paths block). Nothing else.
+
+Use this skeleton, keeping the template's section order and dropping sections that do not apply (Timeline, References, Changelog):
+
+```markdown
+# Feature Specification: <short title>
+
+## Summary
+
+One paragraph: what changes for whom.
+
+## Background
+
+- **Problem:** what is wrong or missing today.
+- **Current behavior:** what the code does now, with file references.
+
+## Requirements
+
+- **FR-1:** The system shall ...
+- **FR-2:** ...
+
+## Acceptance Criteria
+
+Numbered, each one testable by a command or an observable step.
+
+- **AC-1:** Given ..., when ..., then ... (verify: `<command or step>`)
+- **AC-2:** ...
+
+## Affected Code
+
+- `path/to/file`: why it changes
+
+## Out of Scope
+
+- ...
+
+## Assumptions
+
+- Technical assumption: ...
+- **[PRODUCT DECISION]** Assumption that a person must decide: ... (options: ...)
+
+## Open Questions
+
+- ... (or "None")
+```
+
+Rules for the spec:
+
+- Every acceptance criterion must be testable. Name the check (a test, a command, or an observable UI step). "Works well" is not testable.
+- Acceptance criteria are numbered `AC-n`, and requirements are numbered `FR-n`. Builders and reviewers refer to these numbers.
+- Keep scope to what the request asks. Put tempting extras under Out of Scope.
+- An assumption that a product owner should decide is flagged `[PRODUCT DECISION]`. Do not decide it silently. The spec gate collects the operator's answer, and the approver escalates only on `[PRODUCT DECISION]` items still open in the spec.
+- Prefer the smallest spec that covers the request. Ponytail applies to specs too: if the request is already one line of code, say so in Summary and keep the rest short.
+- Do not write a size line or a plan in the spec. Sizing happens in plan mode.
+
+## Plan mode
+
+You write `plan.md` in the feature folder, and `tasks.md` for large work. Nothing else. Do not change `spec.md`.
+
+`plan.md` is concise. Use this skeleton:
+
+```markdown
+# Plan: <short title>
+
+**Size:** small — one line of reason. (The word after `Size:` is exactly one of `small`, `large`, or `unclear`.)
+
+## Approach
+
+Short: how the change is built, and which files it touches.
+
+## Steps
+
+1. <step, in build order>
+2. ...
+
+## Checks
+
+- AC-n: <test or command that proves it>
+```
+
+Sizing: **small** is one or two steps, so write no `tasks.md` and delete a stale one. **Large** has more steps than that, so write `tasks.md`. **Unclear** means you cannot tell from the spec and the code. Say why in the Size line; the operator decides at the plan gate.
+
+`tasks.md` (large only) is a slim list, one line per task, with no per-task sections:
+
+```markdown
+# Tasks: <KEY-or-slug>
+- [ ] T1 <one-line task>
+- [ ] T2 <one-line task> [P]
+```
+
+Number tasks `T1`, `T2`, and so on in build order. Add `[P]` only to tasks that can run in parallel. Do not write ticket keys; the orchestrator adds them at tracking.
+
+On a re-plan, keep each existing task line that still applies, with its T-number, its text, and any ` — <KEY>` suffix, unchanged. Match a kept task by its T-number and text. Number new tasks after the highest existing number. A line that already has a ticket key keeps it, because that ticket exists.
+
+## Rules
+
+- A change note with `spec-<k>.md` or `plan-<k>.md` is the operator's request. Apply it, and keep everything else the operator already accepted.
+- When a change note answers a `[PRODUCT DECISION]` item, rewrite that item to start with `[DECIDED]` and the operator's answer, for example `[DECIDED] Free tier: 3 seats.`. Items the note does not answer stay `[PRODUCT DECISION]`. Never mark an item decided yourself.
+- Name every affected app and package in the plan's Steps and in the spec's Affected Code (`apps/<app>/...` or `packages/<pkg>/...`). If a shared package changes, list its downstream consumers too, so the build and reviews test them.
+- Keep `spec.md` and `plan.md` free of tooling chatter. They are feature docs that merge with the code.
+- Do not modify code, tests, `build.md`, `job.json`, `qa.md`, or any file outside the feature folder. Your writes are `spec.md` (spec mode), or `plan.md` and `tasks.md` (plan mode), in the feature folder only.

package/src/monorepo/.claude/agents-snippets/feature-builder.md

@@ -34,7 +34,7 @@ For each feature request:
 
 When dispatching a specialist subagent, provide:
 
-1. Full task description and acceptance criteria
+1. Full task description (the `tasks.md` line) and the acceptance criteria from `spec.md` that it covers
 2. Relevant file paths and patterns from the codebase
 3. Related tasks already completed (for context)
 4. Testing expectations

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

@@ -0,0 +1,24 @@
+---
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+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]"
+---
+
+# Factory
+
+## Agent Dispatch
+> **Run in the main session.** The orchestrator dispatches these agents; they cannot dispatch others.
+
+| 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` |
+
+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.
+
+Follow the prompt defined in [.claude/prompt-snippets/factory.md](../prompt-snippets/factory.md).

package/src/monorepo/.claude/commands/ponytail-audit.md

@@ -1,15 +1,13 @@
 ---
-description: Audit the whole repo for over-engineering and identify what can be deleted
-allowed-tools: "Read, Grep, Bash"
+description: Audit the whole repo for over-engineering — find what can be deleted
+allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Audit
 
+## Agent Dispatch
 > **Recommended agent:** `oracle`
 > Whole-repo over-engineering analysis
 
-
-# Ponytail Audit
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-audit.md](../prompt-snippets/ponytail-audit.md).

package/src/monorepo/.claude/commands/ponytail-debt.md

@@ -1,15 +1,13 @@
 ---
 description: "Harvest ponytail: comments into a tracked debt ledger"
-allowed-tools: "Read, Grep, Bash"
+allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Debt
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Debt ledger harvesting
 
-
-# Ponytail Debt
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-debt.md](../prompt-snippets/ponytail-debt.md).

package/src/monorepo/.claude/commands/ponytail-gain.md

@@ -4,12 +4,10 @@ allowed-tools: "Read"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Gain
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Impact scoreboard display
 
-
-# Ponytail Gain
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-gain.md](../prompt-snippets/ponytail-gain.md).

package/src/monorepo/.claude/commands/ponytail-help.md

@@ -4,12 +4,10 @@ allowed-tools: "Read"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Help
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Quick-reference display
 
-
-# Ponytail Help
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-help.md](../prompt-snippets/ponytail-help.md).

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

@@ -1,15 +1,13 @@
 ---
-description: Review changes for over-engineering and identify what can be deleted
+description: Review changes for over-engineering — find what can be deleted
 allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Review
 
+## Agent Dispatch
 > **Recommended agent:** `oracle`
 > Diff-level over-engineering review
 
-
-# Ponytail Review
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-review.md](../prompt-snippets/ponytail-review.md).

package/src/monorepo/.claude/commands/ponytail.md

@@ -1,15 +1,13 @@
 ---
 description: Switch ponytail intensity level (lite/full/ultra/off)
-allowed-tools: "Read, Grep, Bash, Edit, Write"
+allowed-tools: "Read, Grep"
 argument-hint: "optional level (lite/full/ultra/off)"
 ---
 
-## Agent Dispatch
+# Ponytail
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Apply YAGNI/stdlib discipline
 
-
-# Ponytail
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail.md](../prompt-snippets/ponytail.md).

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

@@ -48,9 +48,11 @@ 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)
-   - Extract task hierarchy: Epic → Story → Task → Subtask
+   - 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 requirement documents: extract task hierarchy: Epic → Story → Task → Subtask
 
 2. **Consolidate & Classify** (do this 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
    - **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
@@ -62,7 +64,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - **Task**: Implementation work, 2-8 story points (avoid < 2 SP tasks)
    - **Subtask**: Only for complex tasks needing breakdown, 1-3 story points
 
-4. **Estimate Effort**:
+4. **Estimate Effort** (`tasks.md` has no effort field: take hours from `plan.md` for the matching work, or estimate from the scope in `spec.md`):
    - 0.5-1 hours → Merge with related task (too small alone)
    - 2-3 hours → 2 story points
    - 4-6 hours → 3-5 story points
@@ -74,6 +76,8 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - Link child issues to parents
    - 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`)
 
 6. **Generate Report**:
    - List all created tickets with IDs

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

@@ -1,9 +1,17 @@
-You are helping to patch AI instructions in this project by comparing against the latest templates from the ai-assisted-dev-toolkit repository and applying any updates.
+You are helping to patch AI instructions by comparing against supported toolkit v4.x templates from the ai-assisted-dev-toolkit repository's `v4.x` branch and merging updates 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.
+- 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.
 
 ## Orchestrator Checkpoint
 
 > **🛑 Before starting**: This command involves fetching, diffing, and applying changes across many files.
-> Dispatch parallel subagents for independent file groups (rules, commands, prompts, instructions, skills, agents).
+> Complete Step 1's source/version gates before dispatching parallel diff agents for independent file groups (rules, commands, prompts, instructions, skills, agents).
 > See `.claude/rules-snippets/subagent-workflow.md` for patterns.
 
 ## Usage
@@ -23,13 +31,16 @@ You are helping to patch AI instructions in this project by comparing against th
 
 1.  **Fetch Latest Templates**:
 
-    Clone or fetch the latest ai-assisted-dev-toolkit templates:
+    Fetch only the supported `v4.x` source branch:
 
     ```bash
+    set -e
     TOOLKIT_TEMP=$(mktemp -d)
-    git clone --depth 1 https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
+    git clone --depth 1 --branch v4.x https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
     ```
 
+    **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.
+
     Determine the correct source path based on project structure:
     - **Single repo**: Use `$TOOLKIT_TEMP/src/repo/`
     - **Monorepo**: Use `$TOOLKIT_TEMP/src/monorepo/`
@@ -42,9 +53,11 @@ You are helping to patch AI instructions in this project by comparing against th
 
     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: Assume legacy version (pre-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 `$TOOLKIT_TEMP/.toolkit-version` to compare.
+    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.
 
     **Version Comparison:**
     - **Same version**: No structural changes expected
@@ -76,20 +89,20 @@ You are helping to patch AI instructions in this project by comparing against th
     | **OpenCode Commands**      | `.opencode/commands/*.md`                | `src/{type}/.opencode/commands/*.md`                |
     | **OpenCode Rules**         | `.opencode/rules/*.md`                   | `src/{type}/.opencode/rules/*.md`                   |
     | **OpenCode Agents**        | `.opencode/agents/*.md`                  | `src/{type}/.opencode/agents/*.md`                  |
-    | **OpenCode Plugins**       | `.opencode/plugins/*.mjs`                | `src/{type}/.opencode/plugins/*.mjs`                |
+    | **OpenCode Local Plugins** | `.opencode/plugins/*.{js,mjs,ts}`        | Inventory only; preserve unrelated plugins         |
     | **Hooks**                  | `hooks/*.{js,sh,ps1}`                    | `src/{type}/hooks/*.{js,sh,ps1}`                    |
     | **Agent Rules**            | `.agents/rules/*.md`                     | `src/{type}/.agents/rules/*.md`                     |
-    | **Toolkit Version**        | `.toolkit-version`                       | `.toolkit-version` (root of toolkit)                |
-
-    **⚠️ OpenCode `opencode.jsonc` Schema Validation:**
-
-    When patching `.opencode/opencode.jsonc`, **only add or modify supported top-level keys**. The schema is defined at `https://opencode.ai/config.json`. Do NOT add unsupported keys.
+    | **Toolkit Version**        | `.toolkit-version`                       | `package.json` `version` (toolkit root)             |
 
-    **Supported top-level keys:** `$schema`, `instructions`, `skills`, `agent`, `default_agent`, `model`, `small_model`, `provider`, `mcp`, `tools`, `permission`, `lsp`, `formatter`, `server`, `shell`, `command`, `plugin`, `watcher`, `snapshot`, `share`, `autoupdate`, `compaction`, `attachment`, `logLevel`, `disabled_providers`, `enabled_providers`, `tool_output`, `enterprise`, `experimental`
+    **OpenCode native V2 merge checks (confirmed OpenCode use only):**
 
-        **Do NOT add** keys like `rules`, `agents`, `commands`, `prompts` as top-level keys — OpenCode uses the `.opencode/` directory structure and `instructions` array instead.
+    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.
 
-    > **Watch out:** the ponytail template uses the `plugin` key (singular). If you see `plugins` (plural) in your `opencode.jsonc`, that's a typo and the plugin won't load.
+    - 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`.
+    - 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 root/nested `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 workspace 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.
 
 3.  **Diff Analysis** (parallelizable — dispatch one subagent per category):
 
@@ -100,7 +113,7 @@ You are helping to patch AI instructions in this project by comparing against th
     - **📝 Updated**: Exists in both but template has newer content → candidate for merge
     - **✅ Current**: Exists in both and content matches → no action needed
     - **🔧 Customized**: Exists in both, project version has non-placeholder customizations → careful merge
-    - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is
+    - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is except the approved obsolete toolkit Ponytail removal above
 
     b. **For updated files, generate a structured diff**:
     - Preserve project-specific `{{PLACEHOLDER}}` replacements (already-bootstrapped values)
@@ -161,7 +174,9 @@ You are helping to patch AI instructions in this project by comparing against th
       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. **Git commit**: Stage and commit all changes with message:
+      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).
+      f. **Git commit**: Stage and commit all changes with message:
       ```bash
       git add -A
       git commit -m "chore: patch AI instructions from toolkit [$(date +%Y-%m-%d)]"