create-claude-workspace 1.0.0

package/README.md

@@ -0,0 +1,161 @@
+# Claude Starter Kit
+
+Portable `.claude/` folder for autonomous AI-driven development with Claude Code.
+Drop into any **Angular + Nx monorepo** project and start building.
+
+> **Important:** This kit is designed for Angular + Nx monorepo projects. It assumes `nx.json`, `apps/`, `libs/` structure, and Nx CLI commands. It may not work correctly with plain Angular CLI, React, or other frameworks.
+
+## Quick Start (Docker — recommended)
+
+One command, fully isolated, safe `--skip-permissions` (the container is the sandbox):
+
+```bash
+node .claude/scripts/docker-run.mjs
+```
+
+This will:
+1. Install Docker if not present (winget/Chocolatey on Windows, apt/dnf/pacman/brew on Linux/macOS)
+2. Build the container (Node.js + git + Claude Code CLI)
+3. Mount your host Claude auth into the container (no interactive login needed)
+4. Start autonomous development loop
+
+**Authentication:** The container uses your host machine's Claude auth automatically.
+Authenticate on your host first (`claude auth login`), or pass an API key.
+
+```bash
+# Options (same on all platforms)
+node .claude/scripts/docker-run.mjs --max-iterations 20   # limit iterations
+node .claude/scripts/docker-run.mjs --shell                # interactive shell
+node .claude/scripts/docker-run.mjs --rebuild              # force rebuild image
+node .claude/scripts/docker-run.mjs --login                # run 'claude auth login' on host first
+ANTHROPIC_API_KEY=sk-... node .claude/scripts/docker-run.mjs  # API key
+```
+
+## Setup (without Docker)
+
+1. Copy `.claude/` folder into your project root (includes `CLAUDE.md` with agent routing instructions)
+2. Run Claude Code in your project
+3. Say: **"Initialize this project"** (Claude reads `.claude/CLAUDE.md` and delegates to `project-initializer` agent)
+4. Answer the discovery questions (non-technical)
+5. Claude generates the full pipeline:
+   - `CLAUDE.md` — architecture & conventions
+   - `PRODUCT.md` — product strategy & monetization (via `product-owner` agent)
+   - `TODO.md` — phased development plan (via `technical-planner` agent)
+   - `MEMORY.md` — progress tracking
+6. Start autonomous development (pick one):
+   - **Unattended** (recommended): `node .claude/scripts/autonomous.mjs --skip-permissions` — runs in clean context per task, survives rate limits
+   - **Interactive**: Start Claude with `claude --agent orchestrator`, then use `/ralph-loop:ralph-loop Continue autonomous development according to CLAUDE.md`
+
+## Agents
+
+| Agent | Purpose |
+|---|---|
+| `project-initializer`  | Orchestrates full setup pipeline                          |
+| `product-owner`        | Product strategy, features, monetization, prioritization   |
+| `technical-planner`    | Translates PRODUCT.md into phased TODO.md (with quality validation) |
+| `devops-integrator`    | GitLab/GitHub: milestones, issues, branches, MRs/PRs, post-merge cleanup |
+| `deployment-engineer`  | CI/CD pipelines, deploys, rollbacks, smoke tests, DB migrations |
+| `orchestrator`         | Development cycle: 12-step workflow with error recovery    |
+| `ui-engineer`          | Frontend: Angular components, styling, state, a11y         |
+| `backend-ts-architect` | Backend: API, DB, business logic, DI, services             |
+| `senior-code-reviewer` | Code review: security, performance, architecture, duplication |
+| `test-engineer`        | Write and run tests: Vitest/Jest auto-detect + Playwright E2E |
+
+### Pipeline
+
+```
+project-initializer
+  |-> Discovery Conversation   -> CLAUDE.md
+  |-> product-owner            -> PRODUCT.md (features, monetization, MVP)
+  |-> technical-planner        -> TODO.md (phases, tasks, dependencies)
+  |-> devops-integrator (opt)  -> GitLab/GitHub milestones + issues
+  |-> deployment-engineer (opt) -> CI/CD config + ## Deployment in CLAUDE.md
+  |-> MEMORY.md
+
+ralph-loop -> orchestrator agent (autonomous development)
+  |-> Health check (track iterations, validate agents, sync main, ingest issues)
+  |-> Pick task from TODO.md (+ dependency check, phase re-evaluation)
+  |-> Create branch (devops-integrator)
+  |-> Plan (backend-ts-architect first for fullstack, then ui-engineer)
+  |-> Implement (+ DB migrations via deployment-engineer)
+  |-> Write tests (test-engineer: auto-detects Vitest/Jest + Playwright E2E)
+  |-> Build, lint & test (nx affected or explicit projects)
+  |-> Visual verification (Playwright, UI tasks only)
+  |-> Review (senior-code-reviewer, with TESTING context)
+  |-> Rework -> Re-review (max 5 cycles, then escalate/skip)
+  |-> Commit (source + tracking) + push + MR/PR (devops-integrator)
+  |-> Post-merge (solo: merge to main / team: continue on next branch)
+  |-> Next task
+```
+
+## Autonomous Mode (Unattended)
+
+The `.claude/scripts/autonomous.mjs` script runs Claude Code in a loop with clean context per task. MEMORY.md maintains continuity between invocations.
+
+```bash
+# Unattended (requires --skip-permissions for no permission prompts)
+node .claude/scripts/autonomous.mjs --skip-permissions
+
+# Custom options
+node .claude/scripts/autonomous.mjs --skip-permissions --max-iterations 20 --delay 10000
+
+# All options:
+#   --skip-permissions       Required for unattended (adds --dangerously-skip-permissions)
+#   --max-iterations <n>     Safety limit (default: 50)
+#   --max-turns <n>          Max turns per Claude invocation (default: 50)
+#   --delay <ms>             Pause between tasks (default: 5000)
+#   --cooldown <ms>          Wait after rate limit (default: 60000)
+#   --max-rate-retries <n>   Max consecutive rate limit retries (default: 5)
+#   --project-dir <path>     Target project (default: cwd)
+#   --help                   Show help
+```
+
+**How it works:**
+- Each iteration = fresh `claude -p` call = clean context (no context overflow)
+- MEMORY.md session counters reset before each invocation
+- Rate limits detected automatically — waits and retries (max 5 consecutive)
+- Graceful shutdown: Ctrl+C stops after current iteration completes
+- Stops when all TODO.md tasks complete or max iterations reached
+- Safe to kill (Ctrl+C) — MEMORY.md always has the latest state
+
+**vs ralph-loop:** Ralph-loop runs within one conversation (context fills up). This script runs separate conversations (unlimited iterations).
+
+## Required Plugins
+
+Install before starting:
+
+```bash
+# Core (required for interactive mode / ralph-loop)
+claude plugin add ralph-loop
+claude plugin add @anthropic/plugin-playwright
+
+# Recommended
+claude plugin add frontend-design        # UI generation without Figma
+claude plugin add claude-md-management   # CLAUDE.md maintenance
+claude plugin add commit-commands        # git workflow shortcuts
+
+# Git integration (optional, pick one)
+# GitHub: install gh CLI + run: gh auth login
+# GitLab: install glab CLI + run: glab auth login
+
+# Optional MCP Servers
+# Figma MCP — configure in Claude Code MCP settings with API token
+```
+
+## Limitations
+
+- Designed for **Angular + Nx monorepo** projects only — will not work with React, Vue, or plain Angular CLI
+- Requires **Claude Code** with Agent tool support (`subagent_type` parameter)
+- `ralph-loop` and other plugins are Claude Code community plugins — install via `claude plugin add <name>`
+- Git integration requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated
+- Shell commands assume bash (Unix syntax) — works via Git Bash or WSL on Windows
+- Dev server cleanup uses `npx kill-port` — requires npm/npx to be available
+
+## What Gets Generated
+
+| File | Content |
+|------|---------|
+| `CLAUDE.md` | Architecture, Angular patterns, theme system, DI, workflow mode (solo/team), autonomous workflow |
+| `PRODUCT.md` | Vision, target users, features (MVP/v1.1/future), monetization, metrics |
+| `TODO.md` | Phased tasks with type/dependencies/complexity/acceptance criteria, checkboxes (`[ ]` / `[x]` / `[~]`) |
+| `MEMORY.md` | Session state: current task/step, iterations, complexity tracking, done, next, decisions, blockers |

package/dist/index.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { spawn } from 'node:child_process';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = resolve(__dirname, 'template');
+// ─── Colors ───
+const C = {
+    r: '\x1b[31m',
+    g: '\x1b[32m',
+    y: '\x1b[33m',
+    c: '\x1b[36m',
+    b: '\x1b[1m',
+    d: '\x1b[2m',
+    n: '\x1b[0m',
+};
+function info(msg) { console.log(`${C.g}+${C.n} ${msg}`); }
+function warn(msg) { console.log(`${C.y}!${C.n} ${msg}`); }
+function error(msg) { console.error(`${C.r}x${C.n} ${msg}`); }
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const opts = {
+        targetDir: process.cwd(),
+        update: false,
+        run: false,
+        docker: false,
+        help: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case '--help':
+            case '-h':
+                opts.help = true;
+                break;
+            case '--update':
+                opts.update = true;
+                break;
+            case '--run':
+                opts.run = true;
+                break;
+            case '--docker':
+                opts.docker = true;
+                break;
+            default:
+                if (!args[i].startsWith('-')) {
+                    opts.targetDir = resolve(args[i]);
+                }
+                else {
+                    error(`Unknown option: ${args[i]}`);
+                    process.exit(1);
+                }
+        }
+    }
+    return opts;
+}
+function printHelp() {
+    console.log(`
+${C.b}create-claude-workspace${C.n} — Scaffold autonomous AI-driven development with Claude Code
+
+${C.b}Usage:${C.n}
+  npx create-claude-workspace [directory] [options]
+
+${C.b}Arguments:${C.n}
+  directory          Target directory (default: current directory)
+
+${C.b}Options:${C.n}
+  --update           Overwrite existing agent files with latest version
+  --run              Start autonomous development after scaffolding
+  --docker           Use Docker for autonomous run (implies --run)
+  -h, --help         Show this help
+
+${C.b}Examples:${C.n}
+  npx create-claude-workspace                    # scaffold in current directory
+  npx create-claude-workspace my-project         # scaffold in ./my-project
+  npx create-claude-workspace --update           # update agents to latest version
+  npx create-claude-workspace --run              # scaffold + start autonomous loop
+  npx create-claude-workspace --docker           # scaffold + run in Docker
+
+${C.b}What it creates:${C.n}
+  .claude/agents/        10 specialist agents (orchestrator, architects, etc.)
+  .claude/scripts/       Autonomous loop + Docker runner
+  .claude/templates/     CLAUDE.md template for project initialization
+  .claude/CLAUDE.md      Agent routing instructions
+  Dockerfile             Isolated container environment
+  docker-compose.yml     Container orchestration
+  docker-entrypoint.sh   Container entrypoint with auth handling
+  .dockerignore          Docker build exclusions
+`);
+}
+// ─── Prompts ───
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            res(answer.trim());
+        });
+    });
+}
+async function confirm(question) {
+    const answer = await ask(`${question} [Y/n] `);
+    return answer === '' || answer.toLowerCase().startsWith('y');
+}
+// ─── File operations ───
+function listFiles(dir, base = dir) {
+    const results = [];
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            results.push(...listFiles(full, base));
+        }
+        else {
+            results.push(relative(base, full));
+        }
+    }
+    return results;
+}
+function ensureGitignore(targetDir) {
+    const gitignorePath = join(targetDir, '.gitignore');
+    const entries = ['.npmrc', '.docker-compose.auth.yml'];
+    if (existsSync(gitignorePath)) {
+        let content = readFileSync(gitignorePath, 'utf-8');
+        const added = [];
+        for (const entry of entries) {
+            if (!content.includes(entry)) {
+                content += `\n${entry}`;
+                added.push(entry);
+            }
+        }
+        if (added.length > 0) {
+            writeFileSync(gitignorePath, content);
+            info(`Added to .gitignore: ${added.join(', ')}`);
+        }
+    }
+}
+// ─── Run ───
+function runAutonomous(targetDir, docker) {
+    const script = docker ? '.claude/scripts/docker-run.mjs' : '.claude/scripts/autonomous.mjs';
+    const args = docker ? [script] : [script, '--skip-permissions'];
+    if (docker) {
+        info('Starting Docker-based autonomous development...');
+    }
+    else {
+        info('Starting autonomous development...');
+        info('(Use Ctrl+C to stop)');
+    }
+    const child = spawn('node', args, {
+        cwd: targetDir,
+        stdio: 'inherit',
+        shell: true,
+    });
+    child.on('close', (code) => process.exit(code ?? 0));
+}
+// ─── Main ───
+async function main() {
+    const opts = parseArgs();
+    if (opts.help) {
+        printHelp();
+        process.exit(0);
+    }
+    if (opts.docker)
+        opts.run = true;
+    console.log(`\n${C.c}  create-claude-workspace${C.n}\n`);
+    const targetDir = opts.targetDir;
+    const hasExisting = existsSync(join(targetDir, '.claude'));
+    if (hasExisting && !opts.update) {
+        warn('.claude/ directory already exists.');
+        const proceed = await confirm('Overwrite with latest agents?');
+        if (proceed) {
+            opts.update = true;
+        }
+        else {
+            info('Skipping file copy. Use --update to force.');
+            if (opts.run) {
+                runAutonomous(targetDir, opts.docker);
+                return;
+            }
+            process.exit(0);
+        }
+    }
+    if (!existsSync(TEMPLATE_DIR)) {
+        error('Template directory not found. Package may be corrupted.');
+        process.exit(1);
+    }
+    info(`Scaffolding into ${C.b}${targetDir}${C.n}`);
+    if (!existsSync(targetDir)) {
+        mkdirSync(targetDir, { recursive: true });
+    }
+    const files = listFiles(TEMPLATE_DIR);
+    let copied = 0;
+    let skipped = 0;
+    for (const file of files) {
+        const src = join(TEMPLATE_DIR, file);
+        const dest = join(targetDir, file);
+        const destDir = dirname(dest);
+        if (existsSync(dest) && !opts.update) {
+            skipped++;
+            continue;
+        }
+        if (!existsSync(destDir)) {
+            mkdirSync(destDir, { recursive: true });
+        }
+        cpSync(src, dest);
+        copied++;
+    }
+    if (copied > 0)
+        info(`Copied ${copied} files`);
+    if (skipped > 0)
+        info(`Skipped ${skipped} existing files`);
+    ensureGitignore(targetDir);
+    console.log('');
+    info(`${C.b}Done!${C.n} Your project now has Claude Code agents.`);
+    console.log('');
+    console.log(`  ${C.b}Next steps:${C.n}`);
+    console.log('');
+    if (!opts.run) {
+        console.log(`  ${C.d}# Interactive setup (recommended first time)${C.n}`);
+        console.log(`  claude --agent project-initializer`);
+        console.log('');
+        console.log(`  ${C.d}# Autonomous development in Docker${C.n}`);
+        console.log(`  node .claude/scripts/docker-run.mjs`);
+        console.log('');
+        console.log(`  ${C.d}# Autonomous development without Docker${C.n}`);
+        console.log(`  node .claude/scripts/autonomous.mjs --skip-permissions`);
+        console.log('');
+    }
+    if (opts.run) {
+        runAutonomous(targetDir, opts.docker);
+    }
+}
+main().catch((err) => {
+    error(err.message);
+    process.exit(1);
+});

package/dist/template/.claude/CLAUDE.md

@@ -0,0 +1,65 @@
+# Agent-Driven Development Kit
+
+**You are a ROUTER, not an implementer.** This project uses specialist agents. Your ONLY job is to delegate to them.
+
+## The One Rule
+
+**NEVER do work yourself. ALWAYS delegate via the Agent tool.**
+
+- NEVER write CLAUDE.md, PRODUCT.md, TODO.md, MEMORY.md, or any project files yourself
+- NEVER run `nx generate`, `gh`/`glab` commands, or scaffold anything yourself
+- NEVER read `.claude/agents/*.md` files to understand their instructions — call the agent instead. Checking file existence (`ls .claude/agents/`) is fine.
+
+### WRONG (doing it yourself):
+```
+User: "Initialize this project"
+You: *reads plan files, writes CLAUDE.md, creates PRODUCT.md, runs git commands...*
+```
+
+### CORRECT (delegating):
+```
+User: "Initialize this project"
+You: "I'll delegate this to the project-initializer agent."
+→ Agent tool: subagent_type="project-initializer"
+```
+
+## Which Agent to Call
+
+**Setup tasks** → `project-initializer` (it sub-delegates to other agents internally):
+- "Initialize this project", "Set up CLAUDE.md", "Start a new project"
+
+**Development tasks** → `orchestrator` (it sub-delegates to architects, reviewers, etc.):
+- "Continue development", "Next task", "Build the next feature"
+
+**Specific tasks** (only if explicitly asked for one agent's specialty):
+| Task | Agent | `subagent_type` |
+|------|-------|-----------------|
+| Product strategy / PRODUCT.md | product-owner | `"product-owner"` |
+| Development plan / TODO.md | technical-planner | `"technical-planner"` |
+| Deployment / CI/CD | deployment-engineer | `"deployment-engineer"` |
+| Git remote / issues / MRs | devops-integrator | `"devops-integrator"` |
+| Code review | senior-code-reviewer | `"senior-code-reviewer"` |
+| Tests | test-engineer | `"test-engineer"` |
+| Frontend / UI | ui-engineer | `"ui-engineer"` |
+| Backend / API | backend-ts-architect | `"backend-ts-architect"` |
+
+> **Note:** Specialist agents are typically called via sub-delegation by `project-initializer` or `orchestrator`. Only call them directly if the user explicitly asks for one agent's specialty.
+
+**When unsure** → `project-initializer` for setup, `orchestrator` for everything else.
+
+## Autonomous Development
+
+**Important:** The orchestrator MUST run as a top-level agent (not a sub-agent) so it can delegate to specialist agents via the Agent tool. Sub-agents cannot spawn further sub-agents.
+
+```powershell
+# Docker — isolated, safe (recommended)
+node .claude/scripts/docker-run.mjs       # all platforms (Windows / macOS / Linux)
+
+# Without Docker (uses --agent orchestrator automatically)
+node .claude/scripts/autonomous.mjs --skip-permissions
+
+# Interactive — start Claude with orchestrator as top-level agent
+claude --agent orchestrator
+# Then use ralph-loop within that session:
+/ralph-loop:ralph-loop Continue autonomous development according to CLAUDE.md
+```

package/dist/template/.claude/agents/backend-ts-architect.md

@@ -0,0 +1,156 @@
+---
+name: backend-ts-architect
+description: "Use this agent for backend TypeScript tasks: API design, database operations, business logic, authentication, service architecture, or backend code reviews. Works with Hono, Cloudflare Workers, Node.js, Bun, and custom DI framework.\n\nExamples:\n\n<example>\nuser: \"Create an API endpoint for processing transactions\"\nassistant: \"This involves backend API design with transaction handling. Let me use the backend-ts-architect agent.\"\n</example>\n\n<example>\nuser: \"Design the payout calculation service\"\nassistant: \"I'll use the backend-ts-architect agent to architect this service properly.\"\n</example>\n\n<example>\nuser: \"The database queries are slow\"\nassistant: \"Let me engage the backend-ts-architect agent to analyze and optimize these queries.\"\n</example>"
+model: opus
+---
+
+You are a Senior Backend TypeScript Architect with deep expertise in server-side development. You value clean, maintainable, and type-safe code above all else.
+
+## Core Competencies
+
+- Advanced TypeScript patterns (generics, conditional types, mapped types, branded types)
+- Hono framework (routes, middleware, validation)
+- Platform-agnostic backend: runs on both Cloudflare Workers (production) and Node.js (local dev)
+- Custom Angular-style DI framework (Injector, InjectionToken, inject(), Provider)
+- RESTful API design with OpenAPI documentation
+- Database design, query optimization, migrations
+- Authentication, authorization, security best practices
+- UnitOfWork pattern for atomic multi-table writes
+- Onion architecture (domain -> business -> infrastructure)
+
+## Development Philosophy
+
+1. **Type safety first** — leverage TypeScript's advanced features to catch errors at compile time
+2. **Self-documenting code** — no comments unless explaining "why" for non-obvious decisions
+3. **SOLID principles** — Single Responsibility, Open-Closed, Liskov, Interface Segregation, Dependency Inversion
+4. **Security mindset** — OWASP guidelines, never trust user input, validate at boundaries
+5. **Graceful degradation** — comprehensive error handling with actionable feedback
+6. **Pure functions preferred** — business and domain logic should be pure: same input, same output, no side effects. I/O (database, HTTP, logging) lives at the edges (infrastructure, entry points), not inside business logic.
+7. **Minimal branching** — max 2 levels of conditional nesting. Use early returns, lookup maps/objects, polymorphism, and `??`/`?.` to flatten logic. If a function has 4+ branches, it likely needs splitting.
+8. **Data transformations over mutations** — prefer creating new objects/arrays over mutating existing ones. This makes code predictable, testable, and safe for concurrent execution.
+9. **Testability drives design** — if a function is hard to test, it does too much. Max ~20 lines of logic per function, max 4 parameters. Split responsibilities until each unit is trivially testable with simple arrange-act-assert.
+10. **Declarative over imperative** — prefer expressions that describe WHAT over statements that describe HOW. Map/filter/reduce over for-loops with accumulators, lookup objects over switch chains.
+
+## Architecture Patterns
+
+**Onion Architecture per domain:**
+- `domain/` — models, repository interfaces, value objects (no dependencies)
+- `business/` — use cases, business logic (depends on domain only)
+- `api/` — Hono routes, validation, OpenAPI (depends on business + domain)
+- `infrastructure/` — repository implementations, external APIs (depends on domain)
+
+**Custom DI:**
+- `InjectionToken<T>` for typed tokens
+- `inject()` for dependency resolution (same pattern as Angular)
+- `Injector.create({ providers, parent? })` for container setup
+- `runInInjectionContext()` for scoped execution
+- Enables sharing business logic between FE (Angular) and BE (Hono)
+
+**UnitOfWork:**
+- Atomic multi-table writes without transactions (D1 `batch()` / SQLite transaction)
+- Pre-generate UUIDs, prepare all statements before `execute()`
+- Cannot read intermediate results
+
+**Platform-Agnostic Backend (STRICT):**
+- All business/domain/api code MUST run on both Node.js and Cloudflare Workers
+- NEVER use Node.js-specific APIs (`fs`, `path`, `process`, `Buffer`) in business/domain/api layers
+- NEVER use Cloudflare-specific APIs (`env.DB`, `ctx.waitUntil()`) in business/domain layers
+- Platform-specific code lives ONLY in `infrastructure/` layer behind abstract repository interfaces
+- Use Web Standard APIs: `fetch`, `Request`, `Response`, `URL`, `crypto`, `TextEncoder`/`TextDecoder`
+- Hono is inherently platform-agnostic — inject platform bindings via DI, not `c.env` in routes
+- Entry points handle platform wiring:
+  - Worker entry: exports `default { fetch }` with Hono app + D1 bindings
+  - Node entry: `serve()` with Hono app + SQLite/better-sqlite3 bindings
+- When planning, always structure FILES to keep platform-specific code isolated in infrastructure
+
+## Task Approach
+
+1. **Analyze** — parse requirements, identify edge cases, security implications
+2. **Check existing code** — search for similar patterns, reusable utilities, and shared abstractions already in the codebase. NEVER propose new code that duplicates existing functionality.
+3. **Architect** — design solution structure, choose patterns (Repository, Factory, Strategy)
+4. **Clarify** — ask pointed questions when requirements are ambiguous
+5. **Provide structured plan** — output clear implementation steps for the orchestrator
+6. **If asked to implement directly** — production-ready code with types, error handling, validation
+7. **Optimize** — consider performance, suggest improvements
+
+## Code Standards
+
+- Strict TypeScript — no `any`, proper type imports
+- `moduleResolution: "bundler"` — NEVER add `.js` extensions to imports (write `'./foo'`, not `'./foo.js'`)
+- `readonly` on all fields that don't need reassignment
+- Custom error classes for domain-specific errors
+- Input validation at system boundaries (Zod or TypeBox)
+- Async/await patterns (no callback hell)
+- Separation of concerns (routes, services, repositories)
+- File size limit: MAX 200 lines per TypeScript file
+- Single-purpose files: each `.ts` file exports ONE class, ONE function, or ONE closely related set of helpers (e.g., a type + its factory). Barrel `index.ts` files are exempt. Name after its export: `get-image.ts`, `parse-html.ts`. No `utils.ts` or `helpers.ts` bundles.
+- Co-located tests: test files live next to source files (`foo.spec.ts` beside `foo.ts`). No `__tests__/` directories.
+
+## Project Context
+
+- Read CLAUDE.md for project-specific patterns, DI setup, database configuration
+- Respect Nx monorepo boundaries and dependency constraints
+- Use `nx run` commands for building and testing
+- Follow existing patterns established in the codebase
+- When uncertain about approach, ask for clarification before proceeding
+
+## Output Format
+
+When called for **planning** (STEP 2 of the development cycle), always structure your response as:
+
+### EXISTING CODE
+What already exists in the codebase that is relevant — reusable utilities, similar patterns, shared abstractions. Reference specific file paths.
+
+### SCOPE
+What this task covers and what it does NOT cover.
+
+### FILES
+List of all files to create/modify, with full paths.
+**For new libraries**: specify the `nx generate` command (e.g., `nx g @nx/js:library --directory=libs/auth/domain --no-interactive`). Test runner, linter, and style defaults are configured in `nx.json` — do not repeat them. Omit `--bundler` for internal monorepo libs. The orchestrator will run these commands before writing code.
+
+### IMPLEMENTATION ORDER
+Numbered steps in the exact order the orchestrator should implement them.
+
+### INTERFACES
+TypeScript interfaces, types, repository contracts, and DI tokens to define first.
+
+### REUSE OPPORTUNITIES
+Existing code to import/extend instead of writing from scratch. Flag near-duplicates that should be generalized. When recommending extraction to shared, specify the correct scope:
+- Cross-domain usage -> `libs/shared/` (global)
+- Single domain group -> `libs/[domain]/shared/` (e.g. `libs/market/shared/infrastructure`)
+- Single library -> keep local, no extraction
+
+### PATTERNS
+Which project patterns apply (onion layers, DI, UnitOfWork, etc.)
+
+### PITFALLS
+Common mistakes to avoid for this specific task.
+
+### TESTING
+Which files need tests and what to test. Be specific:
+- `path/to/file.ts` — test cases: [list key scenarios, edge cases, error conditions]
+- `path/to/other.ts` — no tests needed (config / wiring only)
+This section is used by the orchestrator to decide whether to call `test-engineer` in STEP 4.
+
+### API CONTRACT REVISION (only when re-invoked with frontend feedback)
+If the orchestrator re-delegates with frontend architect feedback about impractical API contract, re-output only the revised INTERFACES section. Include a brief changelog:
+- `[Endpoint]`: [what changed] — [why, based on frontend feedback]
+Keep all other plan sections unchanged unless the revision affects them.
+
+### SPLIT RECOMMENDATION (optional)
+If the task is too large for a single development cycle (would require 8+ files or multiple independent concerns), recommend splitting. List the suggested sub-tasks with their own scope and dependencies. The orchestrator will delegate to technical-planner to update TODO.md.
+Only include this section if splitting is genuinely needed — do NOT split tasks that are naturally cohesive.
+
+### VERIFICATION
+How to verify the implementation is correct (build, test scenarios, edge cases).
+
+---
+
+When called for **direct implementation**, provide complete production-ready code.
+
+## Communication Style
+
+- Concise and technically precise
+- Explain architectural decisions and trade-offs
+- Proactively identify potential issues
+- No fluff — every word serves a purpose