nitm-ai-dev-toolkit 4.0.0 → 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/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.md

@@ -49,19 +49,28 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
 
 2. **Infer Root-Level Variables**:
 
-   | Variable                  | How to Infer                                       |
-   | ------------------------- | -------------------------------------------------- |
-   | `{{PROJECT_NAME}}`        | Root config name or directory name                 |
-   | `{{PROJECT_DESCRIPTION}}` | Root config description                            |
-   | `{{LANGUAGE}}`            | Detected ecosystem                                 |
-   | `{{PACKAGE_MANAGER}}`     | Lock file or config (pnpm, composer, dotnet, etc.) |
-   | `{{BUILD_SYSTEM}}`        | Build tool (Turborepo, Nx, MSBuild, Maven, etc.)   |
-   | `{{DEFAULT_BRANCH}}`      | Git config or assume "main"                        |
-   | `{{TEST_FRAMEWORK}}`      | Common test framework across packages              |
-   | `{{ISSUE_TRACKER}}`       | Detected project management tool                   |
-   | `{{PM_URL}}`              | Project management URL (if applicable)             |
-   | `{{PROJECT_KEY}}`         | Project/workspace ID (if applicable)               |
-   | `{{PM_ISSUE_KEY}}`        | Issue key format (e.g., PROJ-###, #42)             |
+   | Variable                    | How to Infer                                                                                                                                    |
+   | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `{{PROJECT_NAME}}`          | Root config name or directory name                                                                                                              |
+   | `{{PROJECT_DESCRIPTION}}`   | Root config description                                                                                                                         |
+   | `{{LANGUAGE}}`              | Detected ecosystem                                                                                                                              |
+   | `{{PACKAGE_MANAGER}}`       | Lock file or config (pnpm, composer, dotnet, etc.)                                                                                              |
+   | `{{SETUP_COMMAND}}`         | Root install from the lock file (`pnpm install --frozen-lockfile`, `npm ci`, `yarn install --immutable`); a root `setup` script wins if present |
+   | `{{BUILD_SYSTEM}}`          | Build tool (Turborepo, Nx, MSBuild, Maven, etc.)                                                                                                |
+   | `{{DEFAULT_BRANCH}}`        | `git symbolic-ref --short refs/remotes/origin/HEAD`, minus `origin/`; else `main`                                                               |
+   | `{{TEST_FRAMEWORK}}`        | Common test framework across packages                                                                                                           |
+   | `{{DEV_COMMAND}}`           | Root dev script or task (`turbo run dev`, `nx run-many -t serve`)                                                                               |
+   | `{{DEV_PORT_FLAG}}`         | Port flag or env var the root dev command passes to apps (`--port <port>`, `PORT=<port>`); check each app config. Ask if none                   |
+   | `{{TEST_COMMAND}}`          | Root test script or task (`turbo run test`, `nx run-many -t test`)                                                                              |
+   | `{{LINT_COMMAND}}`          | Root lint script or task (`turbo run lint`, `nx run-many -t lint`)                                                                              |
+   | `{{BUILD_COMMAND}}`         | Root build script or task (`turbo run build`, `nx run-many -t build`)                                                                           |
+   | `{{ISSUE_TRACKER}}`         | Detected project management tool                                                                                                                |
+   | `{{PM_URL}}`                | Project management URL (if applicable)                                                                                                          |
+   | `{{PROJECT_KEY}}`           | Project/workspace ID (if applicable)                                                                                                            |
+   | `{{PM_ISSUE_KEY}}`          | Issue key format (e.g., PROJ-###, #42)                                                                                                          |
+   | `{{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)         |
 
 3. **Analyze Apps**:
 

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

@@ -0,0 +1,20 @@
+---
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+---
+
+You are the factory orchestrator for this session. Arguments: $ARGUMENTS
+
+Follow the [factory orchestrator skill](../../.agents/skills/factory/SKILL.md) exactly. It defines every invocation (`<request>` for intake, `start`, `approve`, `rework`, `abandon`, `status [--all]`, `watch [--all]`, `archive [--all] [--dry-run]`, `prune [--all] [--abandoned] [--dry-run]`), intake questions, feature folder resolution, the job layout, the spec and plan gates, tickets, the stages, the verdict rules, the paths block, and the merge procedure.
+
+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.
+- 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.
+- `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/`.
+- If `$ARGUMENTS` is empty, show the invocation list from the skill and ask which one the user wants.

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

@@ -56,7 +56,7 @@ Implement a feature by completing tasks sequentially with proper tracking.
 
    c. **Implement (TDD required)**:
 
-   - Follow acceptance criteria exactly
+   - Follow the acceptance criteria in `spec.md` for this task's deliverable
    - Use patterns from `AGENTS.md`
    - **Write a failing test first** — one behavior per test, clear name, real code
    - **Verify it fails** — watch it fail for the right reason (feature missing, not error)
@@ -79,7 +79,7 @@ Implement a feature by completing tasks sequentially with proper tracking.
    git commit -m "feat({{SCOPE}}): {{DESCRIPTION}}"
    ```
 
-   f. **Mark Task Complete**
+   f. **Mark Task Complete**: tick `- [x]` for the task in `tasks.md`
 
 5. **Post-Implementation Review**:
    - Dispatch **Reviewer** agent on all changes before proceeding

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

@@ -1,5 +1,7 @@
 You are helping to break down a feature into actionable tasks.
 
+`tasks.md` is a checklist only. Acceptance criteria live in `spec.md`; approach, files, and effort live in `plan.md`. Do not repeat them here.
+
 ## Your Task
 
 1. **Load context**:
@@ -7,102 +9,62 @@ You are helping to break down a feature into actionable tasks.
    - Read the plan in `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/plan.md` (if exists)
    - Review `AGENTS.md` for project patterns
 
-2. **Break down into tasks** (aim for 3-7 total tasks):
-   - **Setup**: Dependencies, configuration, scaffolding (combine into 1 task)
-   - **Core**: Main implementation tasks (group by component/feature area)
-   - **Tests**: Unit and integration tests (1 task per component)
-   - **Polish**: Documentation, cleanup, optimization (combine into 1 task)
-
-3. **Task Consolidation Rules** (CRITICAL):
-   - **Group related work**: Combine tasks that touch the same files or feature area
-   - **Merge small tasks**: Tasks under 2 hours should be combined with related work
-   - **Limit total tasks**: Target 3-7 tasks total; never exceed 10 for any feature
-   - **Avoid over-granularity**: "Create model + migration + factory" = 1 task, not 3
-   - **Bundle by outcome**: Group by what gets delivered, not individual steps
-
-4. **Complexity-Based Task Sizing**:
-
-   | Complexity          | Task Count | Subtask Limit     |
-   | ------------------- | ---------- | ----------------- |
-   | Simple (< 4 hours)  | 2-3 tasks  | 0 subtasks        |
-   | Medium (4-16 hours) | 3-5 tasks  | 2-4 per task max  |
-   | Complex (16-40 hrs) | 5-8 tasks  | 3-6 per task max  |
-   | Large (40+ hours)   | 8-12 tasks | 5-10 per task max |
-
-5. **Task ordering rules**:
+2. **Break down into tasks** (aim for 3-7 total; never exceed 10):
+   - **Setup**: dependencies, configuration, scaffolding (combine into 1 task)
+   - **Core**: main implementation, grouped by component or feature area
+   - **Tests**: unit and integration tests (1 task per component)
+   - **Polish**: documentation, cleanup, optimization (combine into 1 task)
+
+3. **Consolidation rules** (CRITICAL):
+   - **Group related work**: combine tasks that touch the same files or feature area
+   - **Merge small tasks**: anything under 2 hours folds into related work
+   - **Bundle by outcome**: group by what gets delivered, not individual steps
+   - **Keep each task inside one app**. Cross-app work: shared package task first, then app tasks
+
+4. **Create the task list** at `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/tasks.md`:
+
+   ```markdown
+   # Tasks: {{ISSUE_ID}}-{{FEATURE_NAME}}
+
+   - [ ] T1 Setup: dependencies and configuration
+   - [ ] T2 Models, services, and endpoints for sessions
+   - [ ] T3 Session tests [P]
+   - [ ] T4 Docs and cleanup
+   ```
+
+   Each task is one line:
+   - **Checkbox** `- [ ]`. Tick to `- [x]` once the task is implemented and reviewed.
+   - **ID** `T<n>`, sequential, in dependency order.
+   - **Description**: short and deliverable-focused (what ships, not how). No file lists, effort, or acceptance criteria.
+   - **`[P]`** only when the task can run in parallel (different files, no shared state). Omit otherwise.
+   - **` — <ticket key>`** appended after an em dash once a ticket exists. Written by `/assign-tasks`; never added before the ticket is created.
+   - **Sub-bullets** only when a task truly needs them (rare).
+
+5. **Task ordering**:
    - Setup before implementation
    - Tests before or alongside code (TDD)
    - Core features before integrations
-   - Mark parallelizable tasks with [P]
-
-6. **Create task list**:
-   - Output to `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/tasks.md`
-   - Each task should be specific and actionable
-   - Include file paths where relevant
-
-## Task Template
-
-```markdown
-# Tasks: {{FEATURE_NAME}}
-
-**Complexity**: Simple | Medium | Complex
-**Estimated Total**: X hours
-**Task Count**: X tasks
-
-## T001: Setup & Configuration
-
-- Install dependencies and configure environment
-- Create file structure and scaffolding
-- **Files**: `package.json`, `{{CONFIG_DIR}}/*`
-
-## T002: Core Implementation - [Feature Area]
+   - Polish last
+   - Tasks touching the same files run sequentially and are never `[P]`
 
-- Implement [feature part] including models, services, and controllers
-- **Files**: `{{SRC_DIR}}/models/*`, `{{SRC_DIR}}/services/*`
-- **Subtasks** (only if complex):
-  - Model and database layer
-  - Business logic and services
-  - API/Controller layer
-
-## T003 [P]: Testing
-
-- Add unit and integration tests for all components
-- **Files**: `{{TEST_DIR}}/*`
-
-## T004: Polish & Documentation
-
-- Update documentation, error handling, and cleanup
-- **Files**: `README.md`, `docs/*`
-```
+6. **Report**: tasks file path, task count, number of `[P]` tasks, and the consolidation note ("Combined X items into Y tasks"). Next step: `/implement-feature`, or `/assign-tasks` to create tickets.
 
 ## Anti-Patterns to Avoid
 
-❌ **Don't create separate tasks for**:
-
-- Each individual file in a feature
-- "Create X" then "Configure X" then "Test X" (combine them)
-- Minor changes that take < 30 minutes
-- Obvious steps like "commit code" or "run linter"
-
-✅ **Do combine into single tasks**:
-
-- All model/migration/factory work for an entity
-- Related API endpoints that share logic
-- All configuration and environment setup
-- Documentation updates across multiple files
-
-## Notes
+❌ One task per file in a feature
+❌ "Create X" then "Configure X" then "Test X"
+❌ Minor changes under 30 minutes, or obvious steps like "commit code" or "run linter"
 
-- [P] indicates tasks that can run in parallel
-- Tasks affecting the same file should be sequential
-- Each task should be completable independently
-- **Quality over quantity**: Fewer, well-defined tasks beat many granular ones
+✅ All model, migration, and factory work for an entity
+✅ Related API endpoints that share logic
+✅ All configuration and environment setup
+✅ Documentation updates across multiple files
 
 ## Orchestrator Dispatch Guide
 
-When this task list is used by `/implement-feature` or `/implement`:
+When this list is used by `/implement-feature` or `/implement`:
 
-- **Parallel [P] tasks**: Dispatch one subagent per `[P]` task concurrently using `dispatching-parallel-agents` skill
-- **Sequential tasks**: Execute in dependency order, one subagent per task using `subagent-driven-development` skill
-- **Domain routing**: Match each task to the appropriate specialist agent (Backend Architect, Frontend Developer, API Specialist, etc.)
-- **Review gate**: Every task must pass a Reviewer agent before being marked complete
+- **`[P]` tasks**: dispatch one subagent per task concurrently, using `dispatching-parallel-agents`
+- **Other tasks**: execute in dependency order, one subagent per task, using `subagent-driven-development`
+- **Domain routing**: match each task to a specialist (Backend Architect, Frontend Developer, API Specialist, etc.)
+- **Review gate**: every task passes a Reviewer before it is ticked `[x]`

package/src/monorepo/.claude/rules-snippets/documentation.md

@@ -8,13 +8,15 @@ This monorepo uses a **distributed documentation strategy** where app-specific d
 
 **App-specific documentation** must live in respective app folders:
 
-- **{{APP_1}} Features** → `apps/{{APP_1}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/`
-- **{{APP_2}} Features** → `apps/{{APP_2}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/`
+- **{{APP_1}} Features** → `apps/{{APP_1}}/docs/features/<feature>/`
+- **{{APP_2}} Features** → `apps/{{APP_2}}/docs/features/<feature>/`
 - **{{APP_1}} Fixes** → `apps/{{APP_1}}/docs/fixes/`
 - **{{APP_2}} Fixes** → `apps/{{APP_2}}/docs/fixes/`
 - **Shared Package Features** → `packages/{{PACKAGE_NAME}}/docs/features/`
 - **Shared Package Fixes** → `packages/{{PACKAGE_NAME}}/docs/fixes/`
 
+**Factory features are root-scoped.** The factory pipeline runs from the monorepo root, so features it runs live at root `docs/features/<feature>/` (for example `docs/features/PROJ-1234-onboarding/`). Other features stay in their app or package folder as listed above. `<feature>` is the per-run feature folder name: `<KEY>-<slug>`, or `<slug>` when there is no ticket.
+
 **Root `docs/` folder** is ONLY for monorepo-wide documentation:
 
 - Architecture decisions affecting multiple apps (`docs/architecture/`)
@@ -81,12 +83,12 @@ If the monorepo includes a documentation app (e.g., Docus, Nuxt Content, Docusau
 
 Each app maintains its own feature documentation:
 
-**Location:** `apps/{{APP_NAME}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/`
+**Location:** `apps/{{APP_NAME}}/docs/features/<feature>/`
 
 **Required Files:**
 
 ```
-apps/{{APP_1}}/docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/
+apps/{{APP_1}}/docs/features/<feature>/
 ├── spec.md       # Functional specification
 ├── plan.md       # Implementation plan
 └── [optional]    # Code examples, component diagrams
@@ -160,8 +162,8 @@ Before running `git commit`, verify ALL items that apply to your change:
 
 **All changes:**
 
-- [ ] **Features**: `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md` exists and reflects the current implementation
-- [ ] **Features**: `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/plan.md` is updated if scope changed
+- [ ] **Features**: `docs/features/<feature>/spec.md` exists and reflects the current implementation
+- [ ] **Features**: `docs/features/<feature>/plan.md` is updated if scope changed
 - [ ] **Fixes**: Entry added to `apps/{{APP_NAME}}/docs/fixes/{{YYYY-MM}}.md` (or complex fix folder created)
 - [ ] **Breaking changes**: `CHANGELOG.md` updated
 - [ ] **Architectural decisions**: ADR created in `docs/architecture/` if a significant choice was made

package/src/monorepo/.cursor/agents/factory-approver.agent.md

@@ -0,0 +1,11 @@
+---
+description: "Decide whether a factory job is approved for merge or escalated to a human, checking history, final diff, a spot-checked criterion, a dry-run merge, and escalation triggers."
+globs:
+alwaysApply: agent
+---
+
+# Factory Approver Agent
+
+Decide whether a factory job is approved for merge or escalated to a human.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-approver.md](../../.claude/agents-snippets/factory-approver.md)

package/src/monorepo/.cursor/agents/factory-builder.agent.md

@@ -0,0 +1,11 @@
+---
+description: "Build a factory job's feature inside its git worktree, following TDD, and log results in build.md."
+globs:
+alwaysApply: agent
+---
+
+# Factory Builder Agent
+
+Build a factory job's feature inside its git worktree, following TDD, and log results in build.md.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-builder.md](../../.claude/agents-snippets/factory-builder.md)

package/src/monorepo/.cursor/agents/factory-reviewer-code.agent.md

@@ -0,0 +1,11 @@
+---
+description: "Review a factory job's branch for correctness, simplicity, reuse, conventions, and docs, and run the project's checks."
+globs:
+alwaysApply: agent
+---
+
+# Factory Reviewer (Code) Agent
+
+Review a factory job's branch for correctness, simplicity, reuse, conventions, and docs, and run the project's checks.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-reviewer-code.md](../../.claude/agents-snippets/factory-reviewer-code.md)

package/src/monorepo/.cursor/agents/factory-reviewer-security.agent.md

@@ -0,0 +1,11 @@
+---
+description: "Audit a factory job's branch diff for security problems in a fresh context."
+globs:
+alwaysApply: agent
+---
+
+# Factory Reviewer (Security) Agent
+
+Audit a factory job's branch diff for security problems in a fresh context.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-reviewer-security.md](../../.claude/agents-snippets/factory-reviewer-security.md)

package/src/monorepo/.cursor/agents/factory-reviewer-ui.agent.md

@@ -0,0 +1,11 @@
+---
+description: "Review a factory job's feature at its build location for design-system consistency, spacing, typography, contrast, and responsive layout, without signing in or writing to real services."
+globs:
+alwaysApply: agent
+---
+
+# Factory Reviewer (UI) Agent
+
+Review a factory job's feature at its build location for design-system consistency, spacing, typography, contrast, and responsive layout, without signing in or writing to real services.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-reviewer-ui.md](../../.claude/agents-snippets/factory-reviewer-ui.md)

package/src/monorepo/.cursor/agents/factory-reviewer-ux.agent.md

@@ -0,0 +1,11 @@
+---
+description: "Review a factory job's feature at its build location for flows, states, copy, accessibility, and mobile, without signing in or writing to real services."
+globs:
+alwaysApply: agent
+---
+
+# Factory Reviewer (UX) Agent
+
+Review a factory job's feature at its build location for flows, states, copy, accessibility, and mobile, without signing in or writing to real services.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-reviewer-ux.md](../../.claude/agents-snippets/factory-reviewer-ux.md)

package/src/monorepo/.cursor/agents/factory-spec-writer.agent.md

@@ -0,0 +1,11 @@
+---
+description: "Write a testable spec.md for a factory job from a feature request, after inspecting the real code."
+globs:
+alwaysApply: agent
+---
+
+# Factory Spec Writer Agent
+
+Write a testable spec.md for a factory job from a feature request, after inspecting the real code.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-spec-writer.md](../../.claude/agents-snippets/factory-spec-writer.md)

package/src/monorepo/.cursor/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"
+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.
+
+**CRITICAL: READ:** [.claude/prompt-snippets/factory.md](../../.claude/prompt-snippets/factory.md)

package/src/monorepo/.github/agents/factory-approver.agent.md

@@ -0,0 +1,11 @@
+---
+name: Factory Approver
+description: "Decide whether a factory job is approved for merge or escalated to a human, checking history, final diff, a spot-checked criterion, a dry-run merge, and escalation triggers. Dispatched by the factory orchestrator."
+tools: ["read", "search", "edit", "runInTerminal", "terminalLastCommand"]
+---
+
+# Factory Approver Agent
+
+Decide whether a factory job is approved for merge or escalated to a human.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-approver.md](../../.claude/agents-snippets/factory-approver.md)

package/src/monorepo/.github/agents/factory-builder.agent.md

@@ -0,0 +1,11 @@
+---
+name: Factory Builder
+description: "Build a factory job's feature inside its git worktree, following TDD, and log results in build.md. Runs in build, repair, or rework mode. Dispatched by the factory orchestrator."
+tools: ["read", "search", "edit", "runInTerminal", "terminalLastCommand"]
+---
+
+# Factory Builder Agent
+
+Build a factory job's feature inside its git worktree, following TDD, and log results in build.md.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-builder.md](../../.claude/agents-snippets/factory-builder.md)

package/src/monorepo/.github/agents/factory-reviewer-code.agent.md

@@ -0,0 +1,11 @@
+---
+name: Factory Reviewer Code
+description: "Review a factory job's branch for correctness, simplicity, reuse, conventions, and docs, and run the project's checks. Dispatched by the factory orchestrator."
+tools: ["read", "search", "edit", "runInTerminal", "terminalLastCommand"]
+---
+
+# Factory Reviewer (Code) Agent
+
+Review a factory job's branch for correctness, simplicity, reuse, conventions, and docs, and run the project's checks.
+
+**CRITICAL: READ:** [.claude/agents-snippets/factory-reviewer-code.md](../../.claude/agents-snippets/factory-reviewer-code.md)