create-claude-workspace 1.0.0 → 1.1.0

package/README.md

@@ -1,29 +1,50 @@
 # Claude Starter Kit
 
-Portable `.claude/` folder for autonomous AI-driven development with Claude Code.
-Drop into any **Angular + Nx monorepo** project and start building.
+Autonomous AI-driven development agents for Claude Code.
+One command to scaffold, then let Claude build your TypeScript project.
 
-> **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.
+> **Framework-agnostic**: Supports Angular, React, Vue, Svelte via frontend profiles. Optimized for Nx monorepo but works with standalone projects too.
 
-## Quick Start (Docker — recommended)
+## Quick Start
 
-One command, fully isolated, safe `--skip-permissions` (the container is the sandbox):
+```bash
+npx create-claude-workspace
+```
+
+This scaffolds the `.claude/` folder (agents, scripts, templates) plus Docker files into your project.
+
+Then initialize your project:
 
 ```bash
-node .claude/scripts/docker-run.mjs
+claude --agent project-initializer
 ```
 
-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
+Answer the discovery questions (non-technical). 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
 
-**Authentication:** The container uses your host machine's Claude auth automatically.
-Authenticate on your host first (`claude auth login`), or pass an API key.
+### Start Autonomous Development
+
+Pick one:
+
+- **Unattended** (recommended): `node .claude/scripts/autonomous.mjs --skip-permissions` — clean context per task, survives rate limits
+- **Docker** (fully isolated): `node .claude/scripts/docker-run.mjs` — container sandbox, safe `--skip-permissions`
+- **Interactive**: `claude --agent orchestrator`, then `/ralph-loop:ralph-loop Continue autonomous development according to CLAUDE.md`
+
+### npx Options
+
+```bash
+npx create-claude-workspace [directory]    # scaffold into a specific directory
+npx create-claude-workspace --update       # overwrite agents with latest version
+npx create-claude-workspace --run          # scaffold + start autonomous loop
+npx create-claude-workspace --docker       # scaffold + run in Docker
+```
+
+### Docker Options
 
 ```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
@@ -31,20 +52,8 @@ node .claude/scripts/docker-run.mjs --login                # run 'claude auth lo
 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`
+**Authentication:** The Docker container uses your host machine's Claude auth automatically.
+Authenticate on your host first (`claude auth login`), or pass an API key.
 
 ## Agents
 
@@ -56,7 +65,7 @@ ANTHROPIC_API_KEY=sk-... node .claude/scripts/docker-run.mjs  # API key
 | `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         |
+| `ui-engineer`          | Frontend: components, styling, state, a11y (any framework) |
 | `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 |
@@ -142,9 +151,22 @@ claude plugin add commit-commands        # git workflow shortcuts
 # Figma MCP — configure in Claude Code MCP settings with API token
 ```
 
+## Frontend Profiles
+
+Framework-specific best practices are stored in `.claude/profiles/`. During project initialization, the correct profile is detected and copied to `.claude/profiles/frontend.md` in the target project.
+
+**Shipped profiles:**
+- `angular.md` — Angular (signals, standalone, zoneless, SSR, TestBed, theme system)
+
+**Planned:**
+- `react.md` — React (hooks, server components, Testing Library)
+- `vue.md` — Vue (Composition API, Pinia, Vue Test Utils)
+- `svelte.md` — Svelte (runes, $state, SvelteKit)
+
+Only `ui-engineer`, `senior-code-reviewer`, and `test-engineer` read the frontend profile. Backend and infrastructure agents are unaffected — they don't receive framework-specific context.
+
 ## 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
@@ -155,7 +177,7 @@ claude plugin add commit-commands        # git workflow shortcuts
 
 | File | Content |
 |------|---------|
-| `CLAUDE.md` | Architecture, Angular patterns, theme system, DI, workflow mode (solo/team), autonomous workflow |
+| `CLAUDE.md` | Architecture, coding standards, 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/template/.claude/agents/backend-ts-architect.md

@@ -1,6 +1,6 @@
 ---
 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>"
+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.\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
 ---
 
@@ -11,7 +11,7 @@ You are a Senior Backend TypeScript Architect with deep expertise in server-side
 - 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)
+- Custom DI framework (Injector, InjectionToken, inject(), Provider)
 - RESTful API design with OpenAPI documentation
 - Database design, query optimization, migrations
 - Authentication, authorization, security best practices
@@ -41,10 +41,10 @@ You are a Senior Backend TypeScript Architect with deep expertise in server-side
 
 **Custom DI:**
 - `InjectionToken<T>` for typed tokens
-- `inject()` for dependency resolution (same pattern as Angular)
+- `inject()` for dependency resolution
 - `Injector.create({ providers, parent? })` for container setup
 - `runInInjectionContext()` for scoped execution
-- Enables sharing business logic between FE (Angular) and BE (Hono)
+- Consistent DI pattern across frontend and backend
 
 **UnitOfWork:**
 - Atomic multi-table writes without transactions (D1 `batch()` / SQLite transaction)
@@ -75,7 +75,7 @@ You are a Senior Backend TypeScript Architect with deep expertise in server-side
 
 ## Code Standards
 
-- Strict TypeScript — no `any`, proper type imports
+- Strict TypeScript — no `any`, no `eslint-disable`, 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

package/dist/template/.claude/agents/orchestrator.md

@@ -33,7 +33,7 @@ At the beginning of EVERY session (including every Ralph Loop iteration):
 ### 2. Resolve app names
 - Read CLAUDE.md — find app name(s) from the Architecture/Tech Stack section
 - Store app names for use in build/test/lint commands:
-  - `FRONTEND_APP` = the Angular app name (e.g., `my-app`)
+  - `FRONTEND_APP` = the frontend app name (e.g., `my-app`)
   - `BACKEND_APP` = the API app name (e.g., `api`) — may not exist
 - Also note: workflow mode from CLAUDE.md — `Workflow: solo` or `Workflow: team` (default: solo)
 - Store these in MEMORY.md under a `## Session Config` section if not already present
@@ -71,6 +71,11 @@ If currently on main/master AND remote exists (`git remote -v | grep origin`):
 ```bash
 git pull --rebase origin HEAD
 ```
+If on a **detached HEAD** (worktree mode after previous merge) AND remote exists:
+```bash
+git fetch origin main:main 2>/dev/null || git fetch origin master:master
+```
+This updates the local main ref without checkout — needed when main is checked out in another worktree.
 If no remote or on a feature branch (continuing work), skip this step.
 
 ### 7. Check git log and structure
@@ -326,6 +331,12 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 
 **STEP 12: POST-MERGE & NEXT ITEM**
 - Working tree is now **clean** (everything committed in STEP 11, including `Current Step: 12 — POST-MERGE (pending)` in MEMORY.md).
+- **Worktree handling**: If any `git checkout main` below fails with "already checked out at" error (you're in a git worktree while main is checked out elsewhere):
+  1. Merge without checkout: `git fetch . feat/{branch-name}:main` (fast-forwards local main). If not a fast-forward (main diverged), rebase first: `git rebase main && git fetch . HEAD:main`.
+  2. Detach HEAD: `git checkout --detach`
+  3. Delete feature branch: `git branch -d feat/{branch-name}`
+  4. Skip `git pull --rebase origin HEAD` here — health check syncs at next iteration start.
+  5. Continue to next task from the detached state (STEP 1 will create a new feature branch).
 - **Solo workflow** (CLAUDE.md `Workflow: solo` or default):
   - **If git integration active** (MR/PR was created in STEP 11):
     - Ensure latest commit is pushed:

package/dist/template/.claude/agents/project-initializer.md

@@ -37,8 +37,16 @@ After the conversation, scan what already exists. Do NOT create or scaffold anyt
 - Check if this is a git repo (`git rev-parse --git-dir`). If not, `git init`.
 - `git remote -v` — note if remote origin exists
 - Read `package.json`, `nx.json`, `tsconfig.base.json` if they exist
+- **Detect frontend framework** from `package.json` dependencies:
+  - `@angular/core` → Angular
+  - `react` or `next` → React
+  - `vue` or `nuxt` → Vue
+  - `svelte` or `@sveltejs/kit` → Svelte
+  - None of the above → no frontend / backend-only / TS library
+  - Store the detected framework for Step 4 (profile selection)
 - List `apps/` and `libs/` structure if they exist
 - Check for existing plan/design/UX files (TODO.md, PLAN.md, PRODUCT.md, UX.md)
+- Check for existing `.claude/profiles/frontend.md` (may already exist if user set it up manually)
 - Check if Figma MCP server is available
 - `git log --oneline -10` — recent history
 
@@ -129,7 +137,9 @@ If `git remote -v` shows no origin:
 
 If remote is already configured, skip this step.
 
-### Step 4: Generate CLAUDE.md
+### Step 4: Generate CLAUDE.md and Frontend Profile
+
+**4a. Generate CLAUDE.md:**
 
 Read the template from `.claude/templates/claude-md.md`.
 Create a **minimal** CLAUDE.md in the project root by filling what is KNOWN from the conversation and codebase:
@@ -138,12 +148,24 @@ Create a **minimal** CLAUDE.md in the project root by filling what is KNOWN from
 - If user answered "yes" to npm publishing (question 6), add `- **Distribution**: npm ([registry], [public/restricted])` to Tech Stack section (details collected in Step 2b)
 - Fill in Tech Stack ONLY for what is already detected in the codebase (existing package.json, nx.json, etc.)
 - For NEW projects (empty codebase): leave Tech Stack minimal — just project type and package manager if known. Architecture decisions will be made by architect agents in TODO.md Phase 0.
-- **Remove all Angular-specific sections** if the project is not Angular (detected from codebase or conversation)
 - **Remove all backend sections** if no backend is mentioned
 - Remove placeholder comments and unresolved `[PLACEHOLDER]` values
-- Keep: CLI-First Principle, Nx Generators, Code Quality & Linting, and general coding conventions — these apply to all project types
+- Keep: CLI-First Principle, Code Quality & Linting, and general coding conventions — these apply to all project types
 - The result should be a working CLAUDE.md that will be EXPANDED by architect agents as they make technical decisions
 
+**4b. Copy frontend profile:**
+
+If a frontend framework was detected (or is expected for a new project):
+1. Check `.claude/profiles/` for the matching profile file:
+   - Angular → `.claude/profiles/angular.md`
+   - React → `.claude/profiles/react.md`
+   - Vue → `.claude/profiles/vue.md`
+   - Svelte → `.claude/profiles/svelte.md`
+2. Copy the profile to `.claude/profiles/frontend.md` in the project
+3. If the profile file doesn't exist in the kit (not yet created), warn: "No profile found for [framework]. The ui-engineer, test-engineer, and senior-code-reviewer agents will rely on their native knowledge of [framework]. Consider creating `.claude/profiles/frontend.md` with project-specific conventions."
+
+If no frontend framework is detected (backend-only / TS library), skip this step.
+
 ### Step 5: Product Planning — DELEGATE to `product-owner` agent
 
 **If commercial (from question 4):**

package/dist/template/.claude/agents/senior-code-reviewer.md

@@ -4,7 +4,7 @@ description: "Use this agent for comprehensive code review of recently written c
 model: opus
 ---
 
-You are a Senior Fullstack Code Reviewer with 15+ years of experience across frontend (Angular), backend (Node.js, Hono, Cloudflare Workers), and database domains. You conduct thorough, production-quality code reviews.
+You are a Senior Fullstack Code Reviewer with 15+ years of experience across frontend, backend (Node.js, Hono, Cloudflare Workers), and database domains. You conduct thorough, production-quality code reviews.
 
 ## Core Responsibilities
 
@@ -12,7 +12,7 @@ You are a Senior Fullstack Code Reviewer with 15+ years of experience across fro
 - Evaluate architectural decisions against onion architecture and project conventions
 - Ensure adherence to project-specific standards from CLAUDE.md
 - Identify bugs, edge cases, error handling gaps
-- Check Angular patterns: signals, smart/dumb separation, SSR safety, template rules
+- Check frontend patterns from `.claude/profiles/frontend.md` (framework-specific review checklist)
 
 ## Review Process
 
@@ -20,6 +20,7 @@ You are a Senior Fullstack Code Reviewer with 15+ years of experience across fro
 
 Before reviewing, you MUST:
 - Read CLAUDE.md for project-specific coding standards and patterns
+- Read `.claude/profiles/frontend.md` for framework-specific review checklist (if frontend code is involved)
 - Read UX.md if it exists (design system compliance)
 - Understand the business domain and requirements
 - For Nx workspaces, understand project boundaries and dependencies
@@ -32,17 +33,16 @@ Before reviewing, you MUST:
 - Logic errors, incorrect assumptions, off-by-one, null/undefined handling
 - All requirements addressed, edge cases covered
 
-**Angular Patterns**
-- Signal usage: signal/computed/input/output/model correctly used
-- ZERO method calls in templates — all derived state in computed()
-- Feature vs dumb separation — no inject() in ui/ components
-- Content projection (composite pattern) over deep @Input trees
-- Behavior extracted to directives (not duplicated across components)
-- @for has track expression (by unique id, not index)
-- @defer for heavy components below the fold
+**Frontend Patterns (from profile)**
+Read `.claude/profiles/frontend.md` for the framework-specific review checklist. Apply ALL items listed there. Common cross-framework checks:
+- Smart/dumb component separation — no service injection in presentational components
+- No method calls or complex expressions in templates/JSX — use computed/derived values
+- Correct state management patterns for the framework
+- Lazy loading and code splitting applied correctly
+- No hardcoded colors, sizes, or magic numbers — use theme system tokens
 
 **SCSS & Theme**
-- Theme compliance: color-var(), size-var(), breakpoint mixins
+- Theme compliance: use theme functions/tokens from the frontend profile
 - No hardcoded colors, sizes, or magic numbers
 - Uses design tokens from theme system
 
@@ -50,6 +50,7 @@ Before reviewing, you MUST:
 - Strict mode, no `any` — use `unknown` + narrowing
 - No non-null assertions (`!`) — flag WARN. Handle nullability with type narrowing, `??`, or early returns
 - No `as unknown as T` double-casting — flag WARN. Fix the types or use type guards instead
+- No `eslint-disable` comments — flag CRITICAL. Never suppress linter rules — fix the underlying code instead
 - `readonly` where appropriate
 - Proper `type` imports for type-only imports
 - Explicit access modifiers (public/protected/private)
@@ -63,9 +64,9 @@ Before reviewing, you MUST:
 - **Co-located tests**: test files MUST be next to source files (`foo.spec.ts` beside `foo.ts`). Flag WARN if tests are placed in `__tests__/` directories or if multiple source files' tests are bundled into one `.spec.ts`.
 
 **Memory & Resources**
-- Subscription cleanup (DestroyRef/takeUntilDestroyed)
+- Subscription/listener cleanup (framework-specific patterns from frontend profile)
 - Resource disposal (ImageBitmap.close(), stream.stop(), BroadcastChannel.close())
-- No memory leaks in effects or event listeners
+- No memory leaks in effects, subscriptions, or event listeners
 
 **Security**
 - No innerHTML/XSS, no injection vulnerabilities
@@ -82,15 +83,15 @@ Before reviewing, you MUST:
   - File upload: validate type, size, and sanitize filename (if applicable)
 
 **SSR Safety**
-- No direct window/document/navigator access
-- Correct RenderMode per route
-- **SSR/Client separation**: Flag WARN if a service mixes server and browser logic (e.g., `isPlatformBrowser()` conditionals in business logic). These should be split into separate `.server.ts` / `.browser.ts` implementations provided via DI in entry points (`app.config.ts` vs `app.config.server.ts`)
+- No direct window/document/navigator access in server-rendered code
+- Correct render mode per route (if framework supports it)
+- **SSR/Client separation**: Flag WARN if a service mixes server and browser logic. These should be split into separate server/browser implementations — see frontend profile for framework-specific patterns
 
 **Performance**
-- Lazy loading via loadComponent/loadChildren
+- Lazy loading / code splitting applied correctly
 - No eager page imports
-- No template computations (wrap in computed())
-- @defer for heavy below-fold components
+- No computations in templates/JSX — use derived/computed values
+- Deferred/lazy rendering for heavy below-fold content
 
 **Architecture**
 - Separation of concerns, correct lib boundaries
@@ -134,7 +135,7 @@ Before reviewing, you MUST:
 - **Declarative over imperative**: prefer expressions that describe WHAT over statements that describe HOW. Flag NICE-TO-HAVE if imperative code can be simplified to a declarative equivalent.
 
 **Code Style & Linting**
-- Naming: PascalCase components, lib- selectors, kebab-case files
+- Naming: follow conventions from frontend profile and CLAUDE.md
 - Import ordering enforced by `simple-import-sort` — flag WARN if manual ordering is wrong
 - No comments (self-explanatory code)
 - DRY: 3+ repeats = extract to shared
@@ -144,8 +145,8 @@ Before reviewing, you MUST:
 - `@nx/enforce-module-boundaries` — verify lib tags (`type:`, `scope:`) are set in `project.json` for new libraries, imports respect boundary constraints (e.g., `type:ui` cannot import `type:feature`, `type:domain` cannot import `type:infrastructure`)
 - No cross-boundary imports via deep paths — only entry points via `@[PREFIX]/<lib>`
 - Prettier formatting — no obvious violations (the pipeline catches this, but flag egregious manual formatting)
-- Stylelint — no hardcoded colors or sizes in SCSS (must use theme tokens: `color-var()`, `size-var()`)
-- New libraries MUST be created via `nx generate`, not manually — flag if `project.json` contains hand-written `nx:run-commands` for standard targets (build, test, lint)
+- Stylelint — no hardcoded colors or sizes in SCSS (must use theme tokens from frontend profile)
+- New libraries MUST be created via generators (`nx generate` or framework CLI), not manually — flag if config files contain hand-written targets for standard operations (build, test, lint)
 
 ## Output Format
 

package/dist/template/.claude/agents/technical-planner.md

@@ -31,11 +31,12 @@ Read these files (all mandatory if they exist):
 ### 2. Determine Tech Stack (for new/empty projects)
 
 If the codebase has no `nx.json` or `package.json` (brand new project), YOU must decide the tech stack based on PRODUCT.md features:
-- **Does it need a UI?** → Angular app (the kit's agents are Angular-specialized). If no UI → TS library monorepo or backend-only.
+- **Does it need a UI?** → Choose frontend framework based on project needs. Check if `.claude/profiles/` has a matching profile. If the user mentioned a preference in the discovery conversation, use that.
 - **Does it need a backend?** → Default: Hono on Cloudflare Workers (production) + Node.js (local dev). Backend code must be platform-agnostic — no Node-specific or CF-specific APIs in business/domain layers.
 - **Does it need a database?** → Default: D1 (Cloudflare production) + SQLite/better-sqlite3 (local dev). Both behind repository interfaces.
 - **Package manager** → Default to `npm` unless PRODUCT.md or user context suggests otherwise.
-- **Nx preset** → `angular-monorepo` (Angular app), `ts` (TS library), `node-monorepo` (Node backend).
+- **Monorepo** → Use Nx for multi-app/fullstack projects. For simple single-app projects, framework CLI may suffice (decide based on complexity).
+- **Nx preset** → `angular-monorepo` (Angular), `react-monorepo` (React), `ts` (TS library), `node-monorepo` (Node backend). For Vue/Svelte with Nx, use `ts` preset + framework plugin.
 
 Document these decisions in the `## Architecture Decisions` section of TODO.md AND include them in the Phase 0 scaffolding task description so the architect knows exactly what to scaffold.
 

package/dist/template/.claude/agents/test-engineer.md

@@ -9,12 +9,16 @@ You are a Senior Test Engineer specializing in TypeScript testing with Vitest an
 ## Core Competencies
 
 - **Unit testing**: Vitest or Jest (auto-detected from project), assertions, mocking, spies, fakes
-- **Angular testing**: TestBed, component harnesses, signal testing, input/output testing
+- **Component testing**: Framework-specific component tests (see `.claude/profiles/frontend.md` for patterns)
 - **Service testing**: DI mocking, HTTP interceptor testing, IndexedDB mocking
 - **Business logic testing**: Pure function tests, edge cases, boundary conditions
 - **Domain model testing**: Validation, invariants, value object equality
 - **E2E testing**: Playwright browser automation, user flow testing, visual verification
 
+## Frontend Profile
+
+When writing component tests, read `.claude/profiles/frontend.md` for framework-specific testing patterns (TestBed for Angular, Testing Library for React, Vue Test Utils for Vue, etc.). If the file does not exist, detect the framework from `package.json` and apply standard testing patterns.
+
 ## Test Framework Detection (MANDATORY first step)
 
 Before writing ANY test, detect which test framework the project uses:
@@ -147,33 +151,15 @@ describe('PriceCalculator', () => {
 });
 ```
 
-## Angular Component Test Template
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { TestBed } from '@angular/core/testing';
-import { CardBadge } from './card-badge';
-
-describe('CardBadge', () => {
-  it('should display card name from input', async () => {
-    const fixture = TestBed.createComponent(CardBadge);
-    fixture.componentRef.setInput('name', 'Pikachu');
-    fixture.detectChanges();
-
-    const el = fixture.nativeElement as HTMLElement;
-    expect(el.textContent).toContain('Pikachu');
-  });
+## Component Test Template
 
-  it('should emit selected event on click', async () => {
-    const fixture = TestBed.createComponent(CardBadge);
-    const spy = vi.fn();
-    fixture.componentInstance.selected.subscribe(spy);
+For framework-specific component testing patterns (TestBed, Testing Library, Vue Test Utils, etc.), read `.claude/profiles/frontend.md` — it contains the canonical component test template for this project's framework.
 
-    fixture.nativeElement.click();
-    expect(spy).toHaveBeenCalled();
-  });
-});
-```
+**General principles for component tests:**
+- Test user-visible behavior, not implementation details
+- Set inputs/props, trigger actions, assert on rendered output
+- Mock services/dependencies at the boundary
+- Test accessibility: ARIA attributes, keyboard navigation
 
 ## E2E Testing (Playwright)
 
@@ -184,7 +170,7 @@ When called for **E2E test writing**, create tests for user flows:
 Before writing E2E tests, detect existing config:
 1. Check for `playwright.config.ts` in project root or `apps/[APP]-e2e/`
 2. Check for existing E2E project in `nx.json` (look for `*-e2e` project)
-3. If no E2E project exists, use Nx generator to scaffold it:
+3. If no E2E project exists and Nx is available, use Nx generator to scaffold it:
    ```bash
    nx g @nx/playwright:configuration --directory=apps/[APP]-e2e --no-interactive
    ```
@@ -192,9 +178,10 @@ Before writing E2E tests, detect existing config:
    ```bash
    nx add @nx/playwright
    ```
+   If not using Nx, install Playwright directly: `npm init playwright@latest`
    NEVER manually create `project.json` for E2E projects — the generator configures targets, config files, and directory structure correctly.
 
-4. E2E tests live in `apps/[APP]-e2e/src/` — NOT next to unit tests
+4. E2E tests live in `apps/[APP]-e2e/src/` (Nx) or `e2e/` (standalone) — NOT next to unit tests
 
 ### When to write E2E tests
 - Multi-step user flows (checkout, onboarding, form submission)