nitm-ai-dev-toolkit 4.0.0 → 5.0.1

package/src/monorepo/.opencode/agents/frontend-developer.md

@@ -17,4 +17,4 @@ permissions:
 
 Build user interfaces, implement components, handle state management, and optimize frontend performance.
 
-@.claude/agents-snippets/frontend-developer.md
+Read and follow `.claude/agents-snippets/frontend-developer.md` before performing this role.

package/src/monorepo/.opencode/agents/green.md

@@ -17,4 +17,4 @@ permissions:
 
 Write minimal code to make failing tests pass. Part of the TDD red-green-refactor cycle.
 
-@.claude/agents-snippets/green.md
+Read and follow `.claude/agents-snippets/green.md` before performing this role.

package/src/monorepo/.opencode/agents/implementer.md

@@ -17,4 +17,4 @@ permissions:
 
 Implement code changes for a specific task. Follow TDD, write tests alongside code, and self-review before reporting completion.
 
-@.claude/agents-snippets/implementer.md
+Read and follow `.claude/agents-snippets/implementer.md` before performing this role.

package/src/monorepo/.opencode/agents/planner.md

@@ -17,4 +17,4 @@ permissions:
 
 Break down feature requests into implementation tasks. Read specifications, analyze codebase patterns, and produce structured plans with dependencies.
 
-@.claude/agents-snippets/planner.md
+Read and follow `.claude/agents-snippets/planner.md` before performing this role.

package/src/monorepo/.opencode/agents/red.md

@@ -17,4 +17,4 @@ permissions:
 
 Write failing tests that define expected behavior. Part of the TDD red-green-refactor cycle.
 
-@.claude/agents-snippets/red.md
+Read and follow `.claude/agents-snippets/red.md` before performing this role.

package/src/monorepo/.opencode/agents/refactor.md

@@ -17,4 +17,4 @@ permissions:
 
 Improve code quality and structure while keeping all tests passing. Part of the TDD red-green-refactor cycle.
 
-@.claude/agents-snippets/refactor.md
+Read and follow `.claude/agents-snippets/refactor.md` before performing this role.

package/src/monorepo/.opencode/agents/researcher.md

@@ -17,4 +17,4 @@ permissions:
 
 Research codebase patterns, dependencies, and technical context. Analyze code structure, find relevant examples, and report findings without making changes.
 
-@.claude/agents-snippets/researcher.md
+Read and follow `.claude/agents-snippets/researcher.md` before performing this role.

package/src/monorepo/.opencode/agents/reviewer.md

@@ -17,4 +17,4 @@ permissions:
 
 Review code changes for correctness, code quality, security, and adherence to project patterns.
 
-@.claude/agents-snippets/reviewer.md
+Read and follow `.claude/agents-snippets/reviewer.md` before performing this role.

package/src/monorepo/.opencode/agents/tdd.md

@@ -20,4 +20,4 @@ permissions:
 
 Implement a feature using test-driven development with red-green-refactor cycle.
 
-@.claude/agents-snippets/tdd.md
+Read and follow `.claude/agents-snippets/tdd.md` before performing this role.

package/src/monorepo/.opencode/commands/assign-tasks.md

@@ -13,4 +13,4 @@ description: "Create {{ISSUE_TRACKER}} tickets from requirements or task files"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/assign-tasks.md
+Read and follow `.claude/prompt-snippets/assign-tasks.md` before executing this command.

package/src/monorepo/.opencode/commands/bootstrap-patch.md

@@ -15,4 +15,4 @@ description: "Patch AI instructions by fetching updates from the toolkit repo an
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/bootstrap-patch.md
+Read and follow `.claude/prompt-snippets/bootstrap-patch.md` before executing this command.

package/src/monorepo/.opencode/commands/bootstrap-upgrade.md

@@ -15,4 +15,4 @@ description: "Upgrade AI instructions from pre-3.0 inline pattern to 3.0+ snippe
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/bootstrap-upgrade.md
+Read and follow `.claude/prompt-snippets/bootstrap-upgrade.md` before executing this command.

package/src/monorepo/.opencode/commands/bootstrap.md

@@ -15,4 +15,4 @@ description: "Bootstrap AI instructions for monorepo by analyzing workspace and
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/bootstrap.md
+Read and follow `.claude/prompt-snippets/bootstrap.md` before executing this command.

package/src/monorepo/.opencode/commands/commit-push.md

@@ -11,6 +11,6 @@ description: "Commit and push changes with conventional commit messages"
 
 Commit and push changes using conventional commit format.
 
-@.claude/prompt-snippets/commit-push.md
+Read and follow `.claude/prompt-snippets/commit-push.md` before executing this command.
 
 $ARGUMENTS

package/src/monorepo/.opencode/commands/constitution.md

@@ -15,4 +15,4 @@ description: "Create or update the project constitution defining core principles
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/constitution.md
+Read and follow `.claude/prompt-snippets/constitution.md` before executing this command.

package/src/monorepo/.opencode/commands/create-skill.md

@@ -13,4 +13,4 @@ description: "Create a new agent skill following VS Code and agentskills.io spec
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/create-skill.md
+Read and follow `.claude/prompt-snippets/create-skill.md` before executing this command.

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

@@ -0,0 +1,29 @@
+---
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+---
+
+# 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; edits code at 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.
+
+## Arguments
+
+Subcommands: `[--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]`
+
+$ARGUMENTS
+
+Read and follow `.claude/prompt-snippets/factory.md` before executing this command.

package/src/monorepo/.opencode/commands/implement-feature.md

@@ -15,4 +15,4 @@ description: "Implement a feature by completing tasks sequentially"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/implement-feature.md
+Read and follow `.claude/prompt-snippets/implement-feature.md` before executing this command.

package/src/monorepo/.opencode/commands/implement-fixes.md

@@ -17,4 +17,4 @@ argument-hint: "bug description or fix requirements"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/implement-fixes.md
+Read and follow `.claude/prompt-snippets/implement-fixes.md` before executing this command.

package/src/monorepo/.opencode/commands/implement.md

@@ -15,4 +15,4 @@ description: "Execute implementation tasks from a task list or specification"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/implement.md
+Read and follow `.claude/prompt-snippets/implement.md` before executing this command.

package/src/monorepo/.opencode/commands/plan.md

@@ -15,4 +15,4 @@ description: "Create an implementation plan from a feature specification or requ
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/plan.md
+Read and follow `.claude/prompt-snippets/plan.md` before executing this command.

package/src/monorepo/.opencode/commands/playwright-test.md

@@ -13,4 +13,4 @@ description: "Run or create E2E tests using Playwright"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/playwright-test.md
+Read and follow `.claude/prompt-snippets/playwright-test.md` before executing this command.

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

@@ -7,4 +7,4 @@ description: "Whole-repo audit for over-engineering. Scans entire codebase for w
 > **Recommended agent:** `oracle`
 > Whole-repo over-engineering analysis
 
-@.claude/prompt-snippets/ponytail-audit.md
+Read and follow `.claude/prompt-snippets/ponytail-audit.md` before executing this command.

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

@@ -7,4 +7,4 @@
 > **Recommended agent:** `fixer`
 > Debt ledger harvesting
 
-@.claude/prompt-snippets/ponytail-debt.md
+Read and follow `.claude/prompt-snippets/ponytail-debt.md` before executing this command.

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

@@ -7,4 +7,4 @@
 > **Recommended agent:** `fixer`
 > Impact scoreboard display
 
-@.claude/prompt-snippets/ponytail-gain.md
+Read and follow `.claude/prompt-snippets/ponytail-gain.md` before executing this command.

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

@@ -7,4 +7,4 @@
 > **Recommended agent:** `fixer`
 > Quick-reference display
 
-@.claude/prompt-snippets/ponytail-help.md
+Read and follow `.claude/prompt-snippets/ponytail-help.md` before executing this command.

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

@@ -7,4 +7,4 @@
 > **Recommended agent:** `oracle`
 > Diff-level over-engineering review
 
-@.claude/prompt-snippets/ponytail-review.md
+Read and follow `.claude/prompt-snippets/ponytail-review.md` before executing this command.

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

@@ -7,4 +7,4 @@ description: "Forces the laziest solution that actually works — YAGNI, stdlib,
 > **Recommended agent:** `fixer`
 > Apply YAGNI/stdlib discipline
 
-@.claude/prompt-snippets/ponytail.md
+Read and follow `.claude/prompt-snippets/ponytail.md` before executing this command.

package/src/monorepo/.opencode/commands/release-notes.md

@@ -13,4 +13,4 @@ description: "Generate release notes from git commits (web, git tag, or document
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/release-notes.md
+Read and follow `.claude/prompt-snippets/release-notes.md` before executing this command.

package/src/monorepo/.opencode/commands/review-pr.md

@@ -13,6 +13,6 @@ description: "Conduct comprehensive pull request code review"
 
 Conduct comprehensive code review for pull requests.
 
-@.claude/prompt-snippets/review-pr.md
+Read and follow `.claude/prompt-snippets/review-pr.md` before executing this command.
 
 $ARGUMENTS

package/src/monorepo/.opencode/commands/review.md

@@ -13,6 +13,6 @@ description: "Conduct code review for files or features"
 
 Review code for quality, security, and adherence to project patterns.
 
-@.claude/prompt-snippets/review.md
+Read and follow `.claude/prompt-snippets/review.md` before executing this command.
 
 $ARGUMENTS

package/src/monorepo/.opencode/commands/specify.md

@@ -15,4 +15,4 @@ description: "Create a feature specification from a natural language description
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/specify.md
+Read and follow `.claude/prompt-snippets/specify.md` before executing this command.

package/src/monorepo/.opencode/commands/tasks.md

@@ -13,4 +13,4 @@ description: "Generate an actionable task list from a specification or plan"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/tasks.md
+Read and follow `.claude/prompt-snippets/tasks.md` before executing this command.

package/src/monorepo/.opencode/opencode.jsonc

@@ -11,8 +11,7 @@
 	],
 	"plugins": [
 		"opencode-mem",
-		"@tarquinen/opencode-dcp@latest",
-		"@dietrichgebert/ponytail@4.12.0"
+		"@tarquinen/opencode-dcp@latest"
 		// "opentmux": V1-only; enable only after it supports V2.
 	],
 	"lsp": true

package/src/monorepo/.opencode/rules/agent-conduct.md

@@ -2,7 +2,7 @@
 
 Agent conduct and clarification rules for ambiguous requirements.
 
-@.claude/rules-snippets/agent-conduct.md
+Read and follow `.claude/rules-snippets/agent-conduct.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/api-server.md

@@ -2,7 +2,7 @@
 
 API and server-side development standards.
 
-@.claude/rules-snippets/api-server.md
+Read and follow `.claude/rules-snippets/api-server.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/coding-standards.md

@@ -2,7 +2,7 @@
 
 Coding standards and language conventions.
 
-@.claude/rules-snippets/coding-standards.md
+Read and follow `.claude/rules-snippets/coding-standards.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/component-structure.md

@@ -2,7 +2,7 @@
 
 Component structure and composition patterns.
 
-@.claude/rules-snippets/component-structure.md
+Read and follow `.claude/rules-snippets/component-structure.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/core-libraries.md

@@ -2,7 +2,7 @@
 
 Core library and framework usage conventions.
 
-@.claude/rules-snippets/core-libraries.md
+Read and follow `.claude/rules-snippets/core-libraries.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/environment-tooling.md

@@ -2,7 +2,7 @@
 
 Environment and tooling configuration.
 
-@.claude/rules-snippets/environment-tooling.md
+Read and follow `.claude/rules-snippets/environment-tooling.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/logging-comments.md

@@ -2,7 +2,7 @@
 
 Logging identifiers and code comment conventions.
 
-@.claude/rules-snippets/logging-comments.md
+Read and follow `.claude/rules-snippets/logging-comments.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/logging.md

@@ -2,7 +2,7 @@
 
 Structured logging standards and best practices.
 
-@.claude/rules-snippets/logging.md
+Read and follow `.claude/rules-snippets/logging.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/prisma-migrations.md

@@ -2,7 +2,7 @@
 
 Database migration and schema management.
 
-@.claude/rules-snippets/prisma-migrations.md
+Read and follow `.claude/rules-snippets/prisma-migrations.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/project-context.md

@@ -2,7 +2,7 @@
 
 Project context and documentation references.
 
-@.claude/rules-snippets/project-context.md
+Read and follow `.claude/rules-snippets/project-context.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/server-client-separation.md

@@ -2,7 +2,7 @@
 
 Server and client code boundary enforcement.
 
-@.claude/rules-snippets/server-client-separation.md
+Read and follow `.claude/rules-snippets/server-client-separation.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/subagent-workflow.md

@@ -2,7 +2,7 @@
 
 Subagent workflow and orchestration patterns.
 
-@.claude/rules-snippets/subagent-workflow.md
+Read and follow `.claude/rules-snippets/subagent-workflow.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/testing-quality.md

@@ -2,7 +2,7 @@
 
 Testing standards and quality gates.
 
-@.claude/rules-snippets/testing-quality.md
+Read and follow `.claude/rules-snippets/testing-quality.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/ui-accessibility.md

@@ -2,7 +2,7 @@
 
 UI accessibility and responsive design standards.
 
-@.claude/rules-snippets/ui-accessibility.md
+Read and follow `.claude/rules-snippets/ui-accessibility.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/version-control.md

@@ -2,7 +2,7 @@
 
 Version control and commit conventions.
 
-@.claude/rules-snippets/version-control.md
+Read and follow `.claude/rules-snippets/version-control.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/.opencode/rules/what-to-avoid.md

@@ -2,7 +2,7 @@
 
 Patterns and practices to avoid.
 
-@.claude/rules-snippets/what-to-avoid.md
+Read and follow `.claude/rules-snippets/what-to-avoid.md` when these standards apply.
 
 ## Key points
 

package/src/monorepo/AGENTS.md

@@ -44,6 +44,21 @@ The [orient-to-recent-work](.agents/skills/orient-to-recent-work/SKILL.md) skill
 | `{{PACKAGE_SCOPE}}/{{PACKAGE_NAME_2}}` | {{PACKAGE_2_DESCRIPTION}} |
 | `{{PACKAGE_SCOPE}}/config`             | Shared configuration      |
 
+## Commands
+
+Root commands cover every app and package. Filtered commands run one workspace, where `<workspace>` is its package name. The filter syntax follows `{{PACKAGE_MANAGER}}` (pnpm and turbo `--filter`, npm `-w`, yarn `workspace`). `dev`, `test`, `lint`, and `build` are the workspace's script names. Default dev port for each app: its own `AGENTS.md`.
+
+| Task            | Root                | Filtered (one workspace)                         |
+| --------------- | ------------------- | ------------------------------------------------ |
+| Setup           | `{{SETUP_COMMAND}}` | n/a, setup runs once at the root                 |
+| Dev server      | `{{DEV_COMMAND}}`   | `{{PACKAGE_MANAGER}} --filter <workspace> dev`   |
+| Dev server port | `{{DEV_PORT_FLAG}}` | same flag on the filtered dev command            |
+| Test            | `{{TEST_COMMAND}}`  | `{{PACKAGE_MANAGER}} --filter <workspace> test`  |
+| Lint            | `{{LINT_COMMAND}}`  | `{{PACKAGE_MANAGER}} --filter <workspace> lint`  |
+| Build           | `{{BUILD_COMMAND}}` | `{{PACKAGE_MANAGER}} --filter <workspace> build` |
+
+`{{DEV_PORT_FLAG}}` is the flag or env var that sets the port; `<port>` is the port value.
+
 ## Project Management
 
 **Tracker:** {{ISSUE_TRACKER}}
@@ -104,11 +119,11 @@ Each app has its own `AGENTS.md` with detailed patterns:
 
 ## OpenCode V2 Context
 
-OpenCode use with toolkit v4 requires native V2; Slim >=3.0.0 requires OpenCode >=2.0.7. Read [native setup](README.md#native-opencode-v2) before migration. All bootstrap flows run `opencode --version` before changes for confirmed OpenCode use: V1 must stop and upgrade OpenCode or remain on toolkit 3.x; missing/unparseable versions block OpenCode steps and toolkit 4.0.0 marking. Directory presence is not harness proof; other-harness-only setup is unaffected.
+OpenCode use with toolkit 4.0.0 and later requires native V2; Slim >=3.0.0 requires OpenCode >=2.0.7. Read [native setup](README.md#native-opencode-v2) before migration. All bootstrap flows run `opencode --version` before changes for confirmed OpenCode use: V1 must stop and upgrade OpenCode or remain on toolkit 3.x; missing/unparseable versions block OpenCode steps and marking the installed toolkit version (4.0.0 or later). Directory presence is not harness proof; other-harness-only setup is unaffected.
 
-Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`, `plugins`, directory-based `skills`, and `mcp.servers`. Preserve user models/providers/plugins and Slim's separate strict schema; do not host-migrate its `prompt`/`permission`/`variant` fields or silently upgrade the separate external starter. Templates register the author's native V2 `@dietrichgebert/ponytail@4.12.0` locally instead of a bundled Ponytail plugin; `opentmux` stays commented as V1-only. Remove only known obsolete toolkit Ponytail `.js`/`.mjs`/`.ts` copies after backup and approval, preserve unrelated local plugins, and merge/deduplicate upstream registration locally without editing global config. No local API port or bridge is used; plugin/runtime integration is untested.
+Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`, `plugins`, directory-based `skills`, and `mcp.servers`. Preserve user models/providers/plugins and Slim's separate strict schema; do not host-migrate its `prompt`/`permission`/`variant` fields or silently upgrade the separate external starter. The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator; the toolkit does not register it. Bootstrap may check for it and tell the operator to install it globally, but must never add it to project config. `opentmux` stays commented as V1-only. Remove only known obsolete toolkit Ponytail `.js`/`.mjs`/`.ts` copies after backup and approval, and preserve unrelated local plugins. No local API port or bridge is used; plugin/runtime integration is untested. The Claude Code hooks in `hooks/*.json` use `${CLAUDE_PLUGIN_ROOT}` and are plugin-only: they fire only when installed through the Ponytail plugin, not from project settings.
 
-Ambient root/nested `AGENTS.md` works; config `instructions` entries do not load. `@refs` are ordinary text: explicitly read linked snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands, not unavailable V2 LSP diagnostics. Back up V1 before native conversion; converted files are incompatible with V1. Activate on the next run/restart.
+Ambient root/nested `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 linked snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands, not unavailable V2 LSP diagnostics. Back up V1 before native conversion; converted files are incompatible with V1. Activate on the next run/restart.
 
 ## Detailed Instructions
 
@@ -149,6 +164,7 @@ For detailed standards on specific topics, refer to these skills in `.agents/ski
 | **Debugging**             | `systematic-debugging/SKILL.md`           | Debugging workflows                                  |
 | **Documentation**         | `project-documentation/SKILL.md`          | README, comments, ADRs, changelogs                   |
 | **Executing Plans**       | `executing-plans/SKILL.md`                | Following through on implementation plans            |
+| **Factory**               | `factory/SKILL.md`                        | Opt-in spec-to-merge feature pipeline                |
 | **Finishing Branches**    | `finishing-a-development-branch/SKILL.md` | Completing and merging branches                      |
 | **GitHub CLI**            | `gh-cli/SKILL.md`                         | GitHub Issues CLI command reference                  |
 | **GitLab CLI**            | `glab-cli/SKILL.md`                       | GitLab MRs, issues, pipelines CLI reference          |
@@ -348,13 +364,18 @@ Subagents are typically **agent-initiated** — the coordinator decides when to
 
 > **Docs:** [VS Code Subagents](https://code.visualstudio.com/docs/copilot/agents/subagents) · [Cursor Subagents](https://cursor.com/docs/subagents)
 
+### Factory (opt-in)
+
+An optional file-driven pipeline for feature-sized work, alongside Feature Builder and TDD. Start it with `/factory <request>` in Claude Code, Copilot, Cursor, or OpenCode. The orchestrator reads the project and asks only the glaring questions before it creates anything, then asks you to continue or change the answers. Resume a feature with `/factory start <KEY | slug | job-id>`. Codex runs the orchestrator skill directly. Each job belongs to a feature folder in `docs/features/`, stops at a spec gate and a plan gate for your confirmation before any ticket or build, builds in its own git worktree unless you ask for `--in-place`, and moves its tickets when the project tracks them. The orchestrator is [.agents/skills/factory/SKILL.md](.agents/skills/factory/SKILL.md). Its seven agents are `factory-spec-writer`, `factory-builder`, `factory-reviewer-code`, `factory-reviewer-security`, `factory-reviewer-ux`, `factory-reviewer-ui`, and `factory-approver`, with wrappers in each harness's agents folder that point to the shared snippets in `.claude/agents-snippets/`. Setup, placeholders, and approval modes are in [factory/README.md](factory/README.md). Jobs name the affected apps and packages in their spec, and checks run for those with the filtered commands in [Commands](#commands).
+
 ## Documentation Requirements
 
 Documentation updates are **mandatory before committing** any feature or fix. See [`.github/instructions/documentation.instructions.md`](.github/instructions/documentation.instructions.md) for the full pre-commit checklist, templates, and AI agent directives.
 
 **Quick summary:**
 
-- Create or update `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/` (spec + plan) for every feature
+- Create or update `apps/{{APP_NAME}}/docs/features/<feature>/` (spec + plan) for every feature, where `<feature>` is `<KEY>-<slug>` or `<slug>`
+- Features run through the factory pipeline live in root `docs/features/<feature>/` because the pipeline is root-scoped; other features stay in their app or package
 - Add fixes to the monthly log in `apps/{{APP_NAME}}/docs/fixes/{{YYYY-MM}}.md` (or a dedicated folder for complex fixes)
 - Use root `docs/` only for monorepo-wide concerns: `docs/architecture/`, `docs/integration/`, `docs/guides/`
 - Update `docs/api/`, `README.md`, and `CHANGELOG.md` when applicable

package/src/monorepo/README.md

@@ -13,6 +13,12 @@ Templates use `{{PLACEHOLDER}}` syntax (SCREAMING_SNAKE_CASE). The most common p
 | `{{LANGUAGE}}` | Programming language (TypeScript, PHP, Python, C#, etc.) |
 | `{{PACKAGE_MANAGER}}` | Package manager (npm, pnpm, composer, pip, etc.) |
 | `{{DEV_PORT}}` | Development server port |
+| `{{DEV_PORT_FLAG}}` | Flag or env var that sets the dev port |
+| `{{SETUP_COMMAND}}` | Install command |
+| `{{DEV_COMMAND}}` | Dev server command |
+| `{{TEST_COMMAND}}` | Test command |
+| `{{LINT_COMMAND}}` | Lint command |
+| `{{BUILD_COMMAND}}` | Build command |
 | `{{DEPLOY_PLATFORM}}` | Deployment target |
 | `{{ISSUE_TRACKER}}` | Issue tracker (Jira, Linear, GitHub Issues) |
 | `{{ISSUE_ID}}` | Issue or ticket identifier |
@@ -52,17 +58,17 @@ This is a monorepo managed with {{BUILD_SYSTEM}}.
 
 ### Native OpenCode V2
 
-Toolkit v4 requires **OpenCode V2 (major >=2)** for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Bootstrap, patch, and upgrade run `opencode --version` before changes (optional leading `v` accepted). V1 must stop before OpenCode customization/migration or marking toolkit 4.0.0: upgrade OpenCode or remain on toolkit 3.x. A missing CLI or unparseable version stops OpenCode steps and version marking until confirmed/installed. Confirm harness use from runtime evidence or ask, not scaffold directories; other-harness-only setup is unaffected.
+Toolkit 4.0.0 and later require **OpenCode V2 (major >=2)** for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Bootstrap, patch, and upgrade run `opencode --version` before changes (optional leading `v` accepted). V1 must stop before OpenCode customization/migration or marking toolkit 4.0.0: upgrade OpenCode or remain on toolkit 3.x. A missing CLI or unparseable version stops OpenCode steps and version marking until confirmed/installed. Confirm harness use from runtime evidence or ask, not scaffold directories; other-harness-only setup is unaffected.
 
-The template's local `plugins` array registers the author's native V2 package `@dietrichgebert/ponytail@4.12.0`, alongside `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The obsolete local Ponytail plugin is no longer bundled; no local API port or bridge is used. For existing projects, back up and obtain approval before removing only known toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies; preserve unrelated local plugins and merge/deduplicate upstream registration locally without editing global plugins. Native local plugins are discovered automatically; do not register them twice.
+The template's local `plugins` array registers `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator and is not registered by the toolkit. Bootstrap may check for it and tell the operator to install it globally, but never adds it to project config. The obsolete local Ponytail plugin is no longer bundled; no local API port or bridge is used. For existing projects, back up and obtain approval before removing only known toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies; preserve unrelated local plugins and global plugins. Native local plugins are discovered automatically. The Claude Code hooks in `hooks/*.json` use `${CLAUDE_PLUGIN_ROOT}` and are plugin-only: they fire only when installed through the Ponytail plugin, not from project settings.
 
 With approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`, `permission`, and `variant`; do not host-migrate it. The external starter is a separate package, not automatically upgraded. Plugin/runtime integration has not been tested.
 
 Use native `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`. Follow the [V2 migration guide](https://opencode.ai/v2/docs/migrate-v1) and [plugin guide](https://opencode.ai/v2/docs/build/plugins); the published schema may describe V1 and is not V2 validation authority.
 
-Ambient root/nested `AGENTS.md` works; config `instructions` entries are not loaded. `@refs` are ordinary text: read linked snippets explicitly. `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).
+Ambient root/nested `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: read linked snippets explicitly. `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 activating other harnesses. Back up V1, merge rather than clobber models/providers/plugins, and activate on the next run/restart. Native-converted files are incompatible with V1. Verify with installed V2; `doctor` is not runtime validation. Toolkit 4.0.0 publishing has not been executed.
+`--env opencode` supplies minimal shared references without activating other harnesses. Back up V1, merge rather than clobber models/providers/plugins, and activate on the next run/restart. Native-converted files are incompatible with V1. Verify with installed V2; `doctor` is not runtime validation.
 
 ### Native Codex