nitm-ai-dev-toolkit 4.0.0 → 5.0.0

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

@@ -0,0 +1,117 @@
+# 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. [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.
+
+## 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.
+- 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/repo/.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/repo/.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/repo/.claude/prompt-snippets/assign-tasks.md

@@ -50,9 +50,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 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
    - **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
@@ -64,7 +66,7 @@ When interacting with {{ISSUE_TRACKER}}, use MCP tools first (see the `issue-tra
    - **Task**: Implementation work, 2-8 story points (avoid < 2 SP)
    - **Subtask**: Only for complex tasks, 1-3 story points (use sparingly)
 
-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
@@ -76,6 +78,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/repo/.claude/prompt-snippets/bootstrap.md

@@ -100,26 +100,36 @@ Detect the language ecosystem by checking for these files:
 
 Map discovered information to template variables:
 
-| Variable                    | Source                                                                      |
-| --------------------------- | --------------------------------------------------------------------------- |
-| `{{PROJECT_NAME}}`          | Config file name field or directory                                         |
-| `{{PROJECT_DESCRIPTION}}`   | Config description or README                                                |
-| `{{LANGUAGE}}`              | Detected language (TypeScript, PHP, C#, Python, etc.)                       |
-| `{{FRAMEWORK}}`             | Detected framework with version                                             |
-| `{{PACKAGE_MANAGER}}`       | Lock file or config (npm, composer, dotnet, pip, bundler, go, cargo, maven) |
-| `{{DEV_PORT}}`              | Scripts, config, or framework default                                       |
-| `{{SRC_DIR}}`               | Source directory structure                                                  |
-| `{{TEST_DIR}}`              | Test directory location                                                     |
-| `{{FILE_EXTENSION}}`        | Primary extension (ts, php, cs, py, rb, go, rs, java)                       |
-| `{{DATABASE}}`              | ORM/database dependencies                                                   |
-| `{{TEST_FRAMEWORK}}`        | Test framework                                                              |
-| `{{DEPLOY_PLATFORM}}`       | Deployment config files                                                     |
-| `{{RUNTIME_VERSION}}`       | Runtime version from config                                                 |
-| `{{ISSUE_TRACKER}}`         | Detected project management tool                                            |
-| `{{PM_URL}}`                | Project management tool URL/workspace (if applicable)                       |
-| `{{PROJECT_KEY}}`           | Project ID or workspace ID (if applicable)                                  |
-| `{{PM_ISSUE_KEY}}`          | Issue key format (e.g., PROJ-###)                                           |
-| `{{NEW_RELEVANT_VARIABLE}}` | ...other inferred values...                                                 |
+| Variable                    | Source                                                                                                                                                                                                     |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{{PROJECT_NAME}}`          | Config file name field or directory                                                                                                                                                                        |
+| `{{PROJECT_DESCRIPTION}}`   | Config description or README                                                                                                                                                                               |
+| `{{LANGUAGE}}`              | Detected language (TypeScript, PHP, C#, Python, etc.)                                                                                                                                                      |
+| `{{FRAMEWORK}}`             | Detected framework with version                                                                                                                                                                            |
+| `{{PACKAGE_MANAGER}}`       | Lock file or config (npm, composer, dotnet, pip, bundler, go, cargo, maven)                                                                                                                                |
+| `{{SETUP_COMMAND}}`         | Install step from the lock file (`npm ci`, `pnpm install --frozen-lockfile`, `composer install`, `dotnet restore`, `pip install -r requirements.txt`); a `setup` script or Makefile target wins if present |
+| `{{DEV_PORT}}`              | Scripts, config, or framework default                                                                                                                                                                      |
+| `{{DEV_COMMAND}}`           | `dev` or `start` script, Makefile `dev` target, or framework CLI (`php artisan serve`, `dotnet run`, `cargo run`)                                                                                          |
+| `{{DEV_PORT_FLAG}}`         | Flag or env var that sets the dev port: `--port <port>`, `-- --port <port>` (npm script passthrough), or `PORT=<port>`; check the script and framework config. Ask if none                                 |
+| `{{SRC_DIR}}`               | Source directory structure                                                                                                                                                                                 |
+| `{{TEST_DIR}}`              | Test directory location                                                                                                                                                                                    |
+| `{{FILE_EXTENSION}}`        | Primary extension (ts, php, cs, py, rb, go, rs, java)                                                                                                                                                      |
+| `{{DATABASE}}`              | ORM/database dependencies                                                                                                                                                                                  |
+| `{{TEST_FRAMEWORK}}`        | Test framework                                                                                                                                                                                             |
+| `{{TEST_COMMAND}}`          | `test` script, or the runner (`vitest run`, `phpunit`, `pytest`, `go test ./...`, `cargo test`, `dotnet test`)                                                                                             |
+| `{{LINT_COMMAND}}`          | `lint` script, or the linter (ESLint, Biome, ruff, phpstan, golangci-lint, clippy, dotnet format)                                                                                                          |
+| `{{BUILD_COMMAND}}`         | `build` script, or the build tool (`go build ./...`, `cargo build`, `dotnet build`, `mvn package`)                                                                                                         |
+| `{{DEPLOY_PLATFORM}}`       | Deployment config files                                                                                                                                                                                    |
+| `{{RUNTIME_VERSION}}`       | Runtime version from config                                                                                                                                                                                |
+| `{{ISSUE_TRACKER}}`         | Detected project management tool                                                                                                                                                                           |
+| `{{PM_URL}}`                | Project management tool URL/workspace (if applicable)                                                                                                                                                      |
+| `{{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)                                                                    |
+| `{{NEW_RELEVANT_VARIABLE}}` | ...other inferred values...                                                                                                                                                                                |
 
 ### Step 2.5: Project Management Detection
 

package/src/repo/.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/repo/.claude/prompt-snippets/implement-feature.md

@@ -55,7 +55,7 @@ Implement a feature by completing tasks sequentially with proper tracking.
    - Understand dependencies
 
    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)
@@ -85,7 +85,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/repo/.claude/prompt-snippets/tasks.md

@@ -1,6 +1,8 @@
-# Generate Task Breakdown
+# Generate Task Checklist
 
-Break down the implementation plan into executable tasks. This is the third step in the development lifecycle.
+Break the implementation plan into a slim task checklist. This is the third step in the development lifecycle.
+
+`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.
 
 ## Usage
 
@@ -9,138 +11,73 @@ Break down the implementation plan into executable tasks. This is the third step
 /tasks docs/features/user-authentication/tasks.md
 ```
 
-## Task Consolidation Rules (CRITICAL)
+## When Not to Create tasks.md
 
-Before creating tasks, apply these consolidation principles:
+Small work (1-2 steps) needs no `tasks.md`. Implement it directly.
 
-### Target Task Counts
+## Consolidation Rules (CRITICAL)
 
-| Feature Complexity  | Total Tasks | Max Subtasks/Task |
-| ------------------- | ----------- | ----------------- |
-| Simple (< 4 hours)  | 2-3         | 0                 |
-| Medium (4-16 hours) | 3-5         | 2-4               |
-| Complex (16-40 hrs) | 5-8         | 3-6               |
-| Large (40+ hours)   | 8-12        | 5-10              |
+### Target Task Counts
 
-### Consolidation Principles
+| Feature Complexity  | Total Tasks |
+| ------------------- | ----------- |
+| Simple (< 4 hours)  | 2-3         |
+| Medium (4-16 hours) | 3-5         |
+| Complex (16-40 hrs) | 5-8         |
+| Large (40+ hours)   | 8-12        |
 
-- **Group by deliverable**: Combine work that ships together
-- **Merge related files**: Model + migration + factory = 1 task
-- **Bundle by layer**: All service layer work = 1 task (if related)
-- **Avoid micro-tasks**: Nothing under 1-2 hours as standalone
-- **Limit phases**: Combine Foundation + Implementation when small
+### Principles
 
-### Before Finalizing, Ask:
+- **Group by deliverable**: combine work that ships together (model + migration + factory = 1 task)
+- **Bundle by layer or resource**: all service work for one area, all endpoints for one resource
+- **Avoid micro-tasks**: nothing under 1-2 hours standalone
+- **Limit phases**: combine Foundation + Implementation when small
 
-1. Can any adjacent phases be combined?
-2. Are there tasks under 2 hours that should be merged?
-3. Would a developer naturally complete these together?
-4. Does each task represent meaningful progress?
+Before finalizing, ask: Can adjacent tasks merge? Would one developer naturally finish these together? Does each task show meaningful progress?
 
 ## Process
 
-1. **Load Context**:
-   - Read specification from `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`
-   - Read plan from `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/plan.md`
-   - Review `AGENTS.md` for project patterns
-
-2. **Generate Consolidated Task Breakdown**:
-
-   Create `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/tasks.md` with phases (combine where appropriate):
-
-   ### Phase 1: Foundation & Setup (combine into 1 task)
-   - Database schema changes, migrations, seeders
-   - Type definitions and interfaces
-   - Base models and validators
-   - Configuration and dependencies
-
-   ### Phase 2: Core Implementation (group by feature area)
-   - Core functionality grouped by component
-   - API endpoints or components (CRUD together)
-   - Business logic and services
-
-   ### Phase 3: Testing (1 task per major component)
-   - Unit tests for component
-   - Integration tests for feature
-   - E2E tests (if applicable)
-
-   ### Phase 4: Polish & Documentation (combine into 1 task)
-   - Error handling improvements
-   - Performance optimization
-   - Documentation updates
+1. **Load context**: `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/spec.md`, `plan.md`, and `AGENTS.md` (project patterns).
 
-3. **Consolidated Task Format**:
+2. **Write `docs/features/{{ISSUE_ID}}-{{FEATURE_NAME}}/tasks.md`** in the format below.
 
-   ```markdown
-   ### T001: [Consolidated Task Name]
+3. **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.
 
-   **Phase**: [Foundation/Implementation/Testing/Polish]
-   **Estimated Effort**: [Hours - aim for 2-8 hours per task]
-   **Parallel**: [Yes/No]
+## Task Line Format
 
-   **Scope** (what this task covers):
+```markdown
+# Tasks: {{ISSUE_ID}}-{{FEATURE_NAME}}
 
-   - [Component/feature 1]
-   - [Component/feature 2]
-   - [Related component 3]
-
-   **Files to Create/Modify**:
-
-   - `{{SRC_DIR}}/path/to/file.{{FILE_EXTENSION}}`
-   - `{{SRC_DIR}}/path/to/related.{{FILE_EXTENSION}}`
-   - `{{TEST_DIR}}/path/to/test.{{FILE_EXTENSION}}`
-
-   **Acceptance Criteria**:
-
-   - [ ] All components implemented
-   - [ ] Tests passing
-   - [ ] No type/lint errors
-
-   **Subtasks** (only if task > 8 hours):
-
-   - [ ] Subtask 1
-   - [ ] Subtask 2
-   ```
-
-4. **Task Ordering Rules**:
-   - Setup before implementation
-   - Tests before or alongside code (TDD)
-   - Core before integration
-   - Everything before polish
-
-5. **Parallel Execution**:
-   - Mark parallelizable tasks with `[P]`
-   - Different feature areas = can be parallel
-   - Same files = sequential
+- [ ] T1 Schema + migration for sessions — PROJ-124
+- [ ] T2 Login/logout endpoints [P]
+- [ ] T3 Login form + error states [P]
+```
 
-6. **Report Completion**:
-   - Tasks file path
-   - **Consolidated task count** (should be 3-7)
-   - Estimated total effort
-   - **Consolidation note**: "Combined X items into Y tasks"
-   - Ready for `/implement` command
+Each task is one line:
 
-## Anti-Patterns to Avoid
+- **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).
 
-❌ **Don't create separate tasks for**:
+Ordering: setup before implementation; tests before or alongside code (TDD); core before integration; polish last. Tasks that touch the same files run sequentially and are never `[P]`.
 
-- Each individual file
-- "Create X" then "Configure X" then "Test X"
-- Setup tasks under 1 hour
-- Each CRUD operation separately
+## Anti-Patterns
 
-✅ **Do combine into single tasks**:
+❌ One task per file, per CRUD operation, or split into "Create X" / "Configure X" / "Test X"
+❌ Standalone setup tasks under 1 hour
 
-- All database work for an entity
-- All API endpoints for a resource
-- All configuration/setup work
-- Related service layer methods
+✅ All database work for an entity
+✅ All API endpoints for a resource
+✅ All configuration and setup for the feature
 
 ## 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/repo/.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/repo/.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/repo/.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/repo/.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/repo/.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/repo/.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/repo/.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/repo/.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/repo/.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/repo/.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)