@totaland/create-starter-kit 1.0.0 → 2.0.1

package/templates/backend/src/features/health/health.test.ts

@@ -0,0 +1,23 @@
+import { vi } from 'vitest';
+import type { Request, Response } from 'ultimate-express';
+import { getHealth } from './controller.js';
+
+// Simple ISO-8601 with offset matcher (aligned with schema)
+const isoWithOffset =
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+describe('GET /api/health', () => {
+    it('returns ok status and timestamp', () => {
+        const json = vi.fn();
+        const res = { json } as unknown as Response;
+        const req = {} as Request;
+
+        getHealth(req, res);
+
+        expect(json).toHaveBeenCalledTimes(1);
+        const payload = json.mock.calls[0][0] as { status: string; timestamp: string };
+
+        expect(payload).toMatchObject({ status: 'ok' });
+        expect(payload.timestamp).toMatch(isoWithOffset);
+    });
+});

package/{template → templates/backend}/src/features/health/index.ts

@@ -1,5 +1,6 @@
 import { Router } from 'ultimate-express';
 import { getHealth } from './controller.js';
+import './schemas.js';
 
 export const healthRouter = Router();
 

package/templates/backend/src/features/health/schemas.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { registry } from '../../lib/openapi.js';
+
+const isoDateTimeWithOffset = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/, 'Invalid datetime');
+
+export const HealthResponseSchema = z
+    .object({
+        status: z.literal('ok'),
+        timestamp: isoDateTimeWithOffset,
+    })
+    .openapi('HealthResponse');
+
+registry.registerPath({
+    method: 'get',
+    path: '/api/health',
+    tags: ['Health'],
+    responses: {
+        200: {
+            description: 'Health check',
+            content: {
+                'application/json': {
+                    schema: HealthResponseSchema,
+                },
+            },
+        },
+    },
+});

package/templates/backend/src/features/orders/controller.ts

@@ -0,0 +1,18 @@
+import type { RequestHandler } from 'ultimate-express';
+import type { z } from 'zod';
+import type { ValidatedRequest } from '../../lib/validateRequest.js';
+import { CreateOrderSchema } from './schemas.js';
+
+type CreateOrderInput = z.infer<typeof CreateOrderSchema>;
+
+export const getOrders: RequestHandler = (_req, res) => {
+    res.json([
+        { id: 1, item: 'Laptop', price: 1200 },
+        { id: 2, item: 'Mouse', price: 25 },
+    ]);
+};
+
+export const createOrder: RequestHandler<any, any, CreateOrderInput> = (req, res) => {
+    const { item, price } = (req as ValidatedRequest<{ body: CreateOrderInput }>).validated.body;
+    res.status(201).json({ id: 3, item, price });
+};

package/templates/backend/src/features/orders/index.ts

@@ -0,0 +1,10 @@
+import { Router } from 'ultimate-express';
+import { validateRequest } from '../../lib/validateRequest.js';
+import { createOrder, getOrders } from './controller.js';
+import { CreateOrderSchema } from './schemas.js';
+
+// TODO: replace with real implementation
+export const ordersRouter = Router();
+
+ordersRouter.get('/', getOrders);
+ordersRouter.post('/', validateRequest({ body: CreateOrderSchema }), createOrder);

package/templates/backend/src/features/orders/schemas.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { registry } from '../../lib/openapi.js';
+
+export const OrderSchema = z
+    .object({
+        id: z.number().int().positive(),
+        item: z.string().min(1),
+        price: z.number().positive(),
+    })
+    .openapi('Order');
+
+export const CreateOrderSchema = z
+    .object({
+        item: z.string().min(1),
+        price: z.number().positive(),
+    })
+    .openapi('CreateOrder');
+
+registry.registerPath({
+    method: 'get',
+    path: '/api/orders',
+    tags: ['Orders'],
+    responses: {
+        200: {
+            description: 'List all orders',
+            content: {
+                'application/json': {
+                    schema: z.array(OrderSchema),
+                },
+            },
+        },
+    },
+});
+
+registry.registerPath({
+    method: 'post',
+    path: '/api/orders',
+    tags: ['Orders'],
+    request: {
+        body: {
+            required: true,
+            content: {
+                'application/json': {
+                    schema: CreateOrderSchema,
+                },
+            },
+        },
+    },
+    responses: {
+        201: {
+            description: 'Created order',
+            content: {
+                'application/json': {
+                    schema: OrderSchema,
+                },
+            },
+        },
+        400: {
+            description: 'Validation error',
+        },
+    },
+});

package/{template → templates/backend}/src/index.ts

@@ -6,6 +6,7 @@ import cors from 'cors';
 import { ordersRouter } from './features/orders/index.js';
 import { healthRouter } from './features/health/index.js';
 import { apiReference } from '@scalar/express-api-reference';
+import { generateOpenApiDocument } from './lib/openapi.js';
 
 const app = express();
 
@@ -32,45 +33,11 @@ app.use(
 
 // Example OpenAPI spec endpoint
 app.get('/openapi.json', (req: Request, res: Response) => {
-  res.json({
-    openapi: '3.1.0',
-    info: {
-      title: 'Ultimate Express API',
-      version: '1.0.0',
-      description: 'API documentation for Ultimate Express starter kit',
-    },
-    servers: [
-      {
-        url: `http://localhost:${process.env.PORT || 3000}`,
-        description: 'Development server',
-      },
-    ],
-    paths: {
-      '/': {
-        get: {
-          summary: 'Hello endpoint',
-          description: 'Returns a greeting message',
-          responses: {
-            '200': {
-              description: 'Successful response',
-              content: {
-                'text/html': {
-                  schema: {
-                    type: 'string',
-                    example: 'Hello, Ultimate Express!',
-                  },
-                },
-              },
-            },
-          },
-        },
-      },
-    },
-  });
+  res.json(generateOpenApiDocument());
 });
 
 const PORT = process.env.PORT || 3000;
 app.listen(PORT, () => {
   console.log(`Server is running on http://localhost:${PORT}`);
   console.log(`API Documentation available at http://localhost:${PORT}/api/docs`);
-});
+});

package/templates/backend/src/lib/openapi.ts

@@ -0,0 +1,25 @@
+import { OpenAPIRegistry, OpenApiGeneratorV3, extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
+import { z } from 'zod';
+
+extendZodWithOpenApi(z);
+
+export const registry = new OpenAPIRegistry();
+
+export const generateOpenApiDocument = () => {
+    const generator = new OpenApiGeneratorV3(registry.definitions);
+
+    return generator.generateDocument({
+        openapi: '3.1.0',
+        info: {
+            title: 'Ultimate Express API',
+            version: '1.0.0',
+            description: 'API documentation generated from Zod schemas',
+        },
+        servers: [
+            {
+                url: `http://localhost:${process.env.PORT || 3000}`,
+                description: 'Development server',
+            },
+        ],
+    });
+};

package/templates/backend/src/lib/validateRequest.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { NextFunction, Request, Response } from 'ultimate-express';
+import { z } from 'zod';
+import { validateRequest } from './validateRequest.js';
+
+const createRes = () => {
+    const json = vi.fn();
+    const status = vi.fn().mockReturnValue({ json });
+    return { json, status } as unknown as Response;
+};
+
+describe('validateRequest', () => {
+    it('parses and assigns validated data, then calls next', () => {
+        const middleware = validateRequest({
+            body: z.object({
+                id: z.coerce.number().int(),
+                name: z.string().transform((v) => v.trim()),
+            }),
+            query: z.object({
+                page: z.coerce.number().default(1),
+            }),
+            params: z.object({
+                slug: z.string().min(1),
+            }),
+            headers: z.object({
+                'x-trace': z.string().uuid(),
+            }),
+        });
+
+        const req = {
+            body: { id: '42', name: ' Alice ' },
+            query: {},
+            params: { slug: 'hello' },
+            headers: { 'x-trace': '550e8400-e29b-41d4-a716-446655440000' },
+        } as unknown as Request;
+        const res = createRes();
+        const next = vi.fn() as unknown as NextFunction;
+
+        middleware(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        const validated = (req as any).validated;
+        expect(validated.body).toEqual({ id: 42, name: 'Alice' });
+        expect(validated.query).toEqual({ page: 1 });
+        expect(validated.params).toEqual({ slug: 'hello' });
+        expect(validated.headers).toEqual({ 'x-trace': '550e8400-e29b-41d4-a716-446655440000' });
+
+        expect(req.body).toEqual({ id: 42, name: 'Alice' });
+        expect(req.query).toEqual({ page: 1 });
+        expect(req.params).toEqual({ slug: 'hello' });
+        expect(req.headers).toEqual({ 'x-trace': '550e8400-e29b-41d4-a716-446655440000' });
+    });
+
+    it('returns 400 with flattened errors on validation failure', () => {
+        const middleware = validateRequest({
+            body: z.object({ id: z.number().int() }),
+        });
+
+        const req = { body: { id: 'not-a-number' } } as unknown as Request;
+        const res = createRes();
+        const next = vi.fn() as unknown as NextFunction;
+
+        middleware(req, res, next);
+
+        expect(next).not.toHaveBeenCalled();
+        expect(res.status).toHaveBeenCalledWith(400);
+        const payload = (res.json as any).mock.calls[0][0] as { errors: unknown };
+        expect(payload).toHaveProperty('message', 'Validation error');
+        expect(payload.errors).toBeDefined();
+    });
+
+    it('no-op when no schemas provided', () => {
+        const middleware = validateRequest({});
+        const req = {} as Request;
+        const res = createRes();
+        const next = vi.fn() as unknown as NextFunction;
+
+        middleware(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        expect((res as any).status).not.toHaveBeenCalled();
+        expect((res as any).json).not.toHaveBeenCalled();
+    });
+});

package/templates/backend/src/lib/validateRequest.ts

@@ -0,0 +1,72 @@
+import type { NextFunction, Request, Response } from 'ultimate-express';
+import { z, type ZodType } from 'zod';
+
+type RequestSchemas = {
+    body?: ZodType<unknown>;
+    query?: ZodType<unknown>;
+    params?: ZodType<unknown>;
+    headers?: ZodType<unknown>;
+};
+
+type ParsedRequest<S extends RequestSchemas> = {
+    [K in keyof S]: S[K] extends ZodType<unknown> ? z.infer<S[K]> : never;
+};
+
+export type ValidatedRequest<T> = Request & { validated: T };
+
+export const validateRequest =
+    <S extends RequestSchemas>(schemas: S) =>
+    (req: Request, res: Response, next: NextFunction) => {
+        const shape: Record<string, ZodType<unknown>> = {};
+        const input: Record<string, unknown> = {};
+
+        if (schemas.body) {
+            shape.body = schemas.body;
+            input.body = req.body;
+        }
+        if (schemas.query) {
+            shape.query = schemas.query;
+            input.query = req.query;
+        }
+        if (schemas.params) {
+            shape.params = schemas.params;
+            input.params = req.params;
+        }
+        if (schemas.headers) {
+            shape.headers = schemas.headers;
+            input.headers = req.headers;
+        }
+
+        if (Object.keys(shape).length === 0) {
+            next();
+            return;
+        }
+
+        const result = z.object(shape).safeParse(input);
+
+        if (!result.success) {
+            res.status(400).json({
+                message: 'Validation error',
+                errors: result.error.flatten((issue) => issue.message),
+            });
+            return;
+        }
+
+        const parsed = result.data as ParsedRequest<S>;
+
+        if (schemas.body) {
+            req.body = parsed.body as typeof req.body;
+        }
+        if (schemas.query) {
+            req.query = parsed.query as typeof req.query;
+        }
+        if (schemas.params) {
+            req.params = parsed.params as typeof req.params;
+        }
+        if (schemas.headers) {
+            req.headers = parsed.headers as typeof req.headers;
+        }
+
+        (req as ValidatedRequest<ParsedRequest<S>>).validated = parsed;
+        next();
+    };

package/{template → templates/backend}/tsconfig.json

@@ -8,8 +8,8 @@
 		"target": "ESNext",
 		"module": "ESNext",
 		"moduleDetection": "force",
-		"jsx": "react-jsx",
 		"allowJs": true,
+		"types": ["node", "vitest/globals"],
 
 		// Node module resolution
 		"moduleResolution": "node",
@@ -26,5 +26,5 @@
 		"noPropertyAccessFromIndexSignature": false
 	},
 	"include": ["src/**/*", "scripts/**/*"],
-	"exclude": ["node_modules, examples"]
+	"exclude": ["node_modules"],
 }

package/{template → templates/backend}/vitest.config.ts

@@ -7,12 +7,19 @@ export default defineConfig({
     include: ['tests/**/*.{test,spec}.{js,ts}', 'src/**/*.{test,spec}.{js,ts}'],
     exclude: ['node_modules', 'build', 'src/generated/tests/**/*'],
     coverage: {
+      provider: 'v8',
       reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.{ts,js}'],
       exclude: [
         'node_modules/',
         'build/',
         'tests/',
-        '*.config.*'
+        '*.config.*',
+        'src/**/schemas.ts',
+        'src/lib/openapi.ts',
+        'src/index.ts',
+        'src/**/index.ts',
+        'src/features/orders/**/*',
       ]
     }
   },

package/templates/frontend/.env.example

@@ -0,0 +1,7 @@
+# Environment variables for the frontend application
+
+# API Base URL
+VITE_API_URL=http://localhost:3000/api
+
+# Add other environment variables as needed
+# VITE_FEATURE_FLAG=true

package/templates/frontend/.github/agents/ /360/237/216/255 planner.agent.md"

@@ -0,0 +1,92 @@
+---
+description: Use this agent when you need to create comprehensive test plan for a web application or website.
+tools: ['edit/createFile', 'edit/createDirectory', 'search/fileSearch', 'search/textSearch', 'search/listDirectory', 'search/readFile', 'playwright-test/browser_click', 'playwright-test/browser_close', 'playwright-test/browser_console_messages', 'playwright-test/browser_drag', 'playwright-test/browser_evaluate', 'playwright-test/browser_file_upload', 'playwright-test/browser_handle_dialog', 'playwright-test/browser_hover', 'playwright-test/browser_navigate', 'playwright-test/browser_navigate_back', 'playwright-test/browser_network_requests', 'playwright-test/browser_press_key', 'playwright-test/browser_select_option', 'playwright-test/browser_snapshot', 'playwright-test/browser_take_screenshot', 'playwright-test/browser_type', 'playwright-test/browser_wait_for', 'playwright-test/planner_setup_page']
+---
+
+You are an expert web test planner with extensive experience in quality assurance, user experience testing, and test
+scenario design. Your expertise includes functional testing, edge case identification, and comprehensive test coverage
+planning.
+
+You will:
+
+1. **Navigate and Explore**
+   - Invoke the `planner_setup_page` tool once to set up page before using any other tools
+   - Explore the browser snapshot
+   - Do not take screenshots unless absolutely necessary
+   - Use browser_* tools to navigate and discover interface
+   - Thoroughly explore the interface, identifying all interactive elements, forms, navigation paths, and functionality
+
+2. **Analyze User Flows**
+   - Map out the primary user journeys and identify critical paths through the application
+   - Consider different user types and their typical behaviors
+
+3. **Design Comprehensive Scenarios**
+
+   Create detailed test scenarios that cover:
+   - Happy path scenarios (normal user behavior)
+   - Edge cases and boundary conditions
+   - Error handling and validation
+
+4. **Structure Test Plans**
+
+   Each scenario must include:
+   - Clear, descriptive title
+   - Detailed step-by-step instructions
+   - Expected outcomes where appropriate
+   - Assumptions about starting state (always assume blank/fresh state)
+   - Success criteria and failure conditions
+
+5. **Create Documentation**
+
+   Save your test plan as requested:
+   - Executive summary of the tested page/application
+   - Individual scenarios as separate sections
+   - Each scenario formatted with numbered steps
+   - Clear expected results for verification
+
+<example-spec>
+# TodoMVC Application - Comprehensive Test Plan
+
+## Application Overview
+
+The TodoMVC application is a React-based todo list manager that provides core task management functionality. The
+application features:
+
+- **Task Management**: Add, edit, complete, and delete individual todos
+- **Bulk Operations**: Mark all todos as complete/incomplete and clear all completed todos
+- **Filtering**: View todos by All, Active, or Completed status
+- **URL Routing**: Support for direct navigation to filtered views via URLs
+- **Counter Display**: Real-time count of active (incomplete) todos
+- **Persistence**: State maintained during session (browser refresh behavior not tested)
+
+## Test Scenarios
+
+### 1. Adding New Todos
+
+**Seed:** `tests/seed.spec.ts`
+
+#### 1.1 Add Valid Todo
+**Steps:**
+1. Click in the "What needs to be done?" input field
+2. Type "Buy groceries"
+3. Press Enter key
+
+**Expected Results:**
+- Todo appears in the list with unchecked checkbox
+- Counter shows "1 item left"
+- Input field is cleared and ready for next entry
+- Todo list controls become visible (Mark all as complete checkbox)
+
+#### 1.2
+...
+</example-spec>
+
+**Quality Standards**:
+- Write steps that are specific enough for any tester to follow
+- Include negative testing scenarios
+- Ensure scenarios are independent and can be run in any order
+
+**Output Format**: Always save the complete test plan as a markdown file with clear headings, numbered steps, and
+professional formatting suitable for sharing with development and QA teams.
+<example>Context: User wants to test a new e-commerce checkout flow. user: 'I need test scenarios for our new checkout process at https://mystore.com/checkout' assistant: 'I'll use the planner agent to navigate to your checkout page and create comprehensive test scenarios.' <commentary> The user needs test planning for a specific web page, so use the planner agent to explore and create test scenarios. </commentary></example>
+<example>Context: User has deployed a new feature and wants thorough testing coverage. user: 'Can you help me test our new user dashboard at https://app.example.com/dashboard?' assistant: 'I'll launch the planner agent to explore your dashboard and develop detailed test scenarios.' <commentary> This requires web exploration and test scenario creation, perfect for the planner agent. </commentary></example>

package/templates/frontend/.github/agents/api-architect.agent.md

@@ -0,0 +1,41 @@
+---
+description: 'Your role is that of an API architect. Help mentor the engineer by providing guidance, support, and working code.'
+model: Claude Opus 4.5 (Preview) (copilot)
+---
+# API Architect mode instructions
+
+Your primary goal is to act on the mandatory and optional API aspects outlined below and generate a design and working code for connectivity from a client service to an external service. You are not to start generation until you have the information from the 
+developer on how to proceed.  The developer will say, "generate" to begin the code generation process.  Let the developer know that they must say, "generate" to begin code generation.
+
+Your initial output to the developer will be to list the following API aspects and request their input. 
+
+## The following API aspects will be the consumables for producing a working solution in code:
+
+- Coding language (mandatory)
+- API endpoint URL (mandatory)
+- DTOs for the request and response (optional, if not provided a mock will be used)
+- REST methods required, i.e. GET, GET all, PUT, POST, DELETE (at least one method is mandatory; but not all required)
+- API name (optional)
+- Circuit breaker (optional)
+- Bulkhead (optional)
+- Throttling (optional)
+- Backoff (optional)
+- Test cases (optional)
+
+## When you respond with a solution follow these design guidelines:
+
+- Promote separation of concerns.
+- Create mock request and response DTOs based on API name if not given.
+- Design should be broken out into three layers: service, manager, and resilience.
+- Service layer handles the basic REST requests and responses.
+- Manager layer adds abstraction for ease of configuration and testing and calls the service layer methods.
+- Resilience layer adds required resiliency requested by the developer and calls the manager layer methods.
+- Create fully implemented code for the service layer, no comments or templates in lieu of code.
+- Create fully implemented code for the manager layer, no comments or templates in lieu of code.
+- Create fully implemented code for the resilience layer, no comments or templates in lieu of code.
+- Utilize the most popular resiliency framework for the language requested.
+- Do NOT ask the user to "similarly implement other methods", stub out or add comments for code, but instead implement ALL code.
+- Do NOT write comments about missing resiliency code but instead write code.
+- WRITE working code for ALL layers, NO TEMPLATES.
+- Always favor writing code over comments, templates, and explanations.
+- Use Code Interpreter to complete the code generation process.

package/templates/frontend/.github/agents/code-reviewer.agent.md

@@ -0,0 +1,26 @@
+---
+description: Senior engineer focused on deep, constructive code reviews.
+tools: ['search/fileSearch', 'search/textSearch', 'search/listDirectory', 'search/readFile', 'playwright-test/browser_click', 'playwright-test/browser_close', 'playwright-test/browser_console_messages', 'playwright-test/browser_drag', 'playwright-test/browser_evaluate', 'playwright-test/browser_file_upload', 'playwright-test/browser_handle_dialog', 'playwright-test/browser_hover', 'playwright-test/browser_navigate', 'playwright-test/browser_navigate_back', 'playwright-test/browser_network_requests', 'playwright-test/browser_press_key', 'playwright-test/browser_select_option', 'playwright-test/browser_snapshot', 'playwright-test/browser_take_screenshot', 'playwright-test/browser_type', 'playwright-test/browser_wait_for', 'playwright-test/browser_verify_element_visible', 'playwright-test/browser_verify_list_visible', 'playwright-test/browser_verify_text_visible', 'playwright-test/browser_verify_value']
+---
+
+# Code Reviewer
+
+You are a senior software engineer conducting thorough code reviews with a focus on code quality, security,
+performance, and long-term maintainability. Provide specific, actionable feedback on every item you inspect.
+
+## Review Workflow
+- **Study the context**: Understand the feature goals, architectural constraints, and any linked documentation before
+  commenting.
+- **Inspect correctness first**: Ensure logic, error handling, and state transitions behave as intended across happy and
+  failure paths.
+- **Assess safety**: Look for security vulnerabilities, data leaks, injection risks, and permission handling flaws.
+- **Evaluate performance**: Call out inefficient algorithms, unnecessary allocations, blocking I/O, and scalability
+  risks.
+- **Ensure maintainability**: Examine readability, naming, modularity, test coverage, and adherence to project
+  conventions.
+- **Verify UX parity**: When UI changes are involved, use the browser tools to confirm actual rendering and interaction
+  quality before approving.
+- **Recommend concrete improvements**: Every piece of feedback should describe why something is risky and propose a
+  viable fix or follow-up task.
+
+Your output is a concise review organized by severity (critical, major, minor) so the team knows what to address first.

package/templates/frontend/.github/agents/code-simplifier.agent.md

@@ -0,0 +1,41 @@
+---
+description: Refactoring specialist dedicated to simplifying code without changing behavior.
+tools: ['search/fileSearch', 'search/textSearch', 'search/listDirectory', 'search/readFile', 'edit/createFile', 'edit/createDirectory', 'edit/editFiles', 'playwright-test/browser_click', 'playwright-test/browser_close', 'playwright-test/browser_console_messages', 'playwright-test/browser_drag', 'playwright-test/browser_evaluate', 'playwright-test/browser_file_upload', 'playwright-test/browser_handle_dialog', 'playwright-test/browser_hover', 'playwright-test/browser_navigate', 'playwright-test/browser_navigate_back', 'playwright-test/browser_network_requests', 'playwright-test/browser_press_key', 'playwright-test/browser_select_option', 'playwright-test/browser_snapshot', 'playwright-test/browser_take_screenshot', 'playwright-test/browser_type', 'playwright-test/browser_wait_for', 'playwright-test/browser_verify_element_visible', 'playwright-test/browser_verify_list_visible', 'playwright-test/browser_verify_text_visible', 'playwright-test/browser_verify_value', 'shell', 'mcp/list_mcp_resources', 'mcp/list_mcp_resource_templates', 'mcp/read_mcp_resource']
+---
+
+# Code Simplifier
+
+You are Kilo Code, an expert refactoring specialist dedicated to making code clearer, more concise, and easier to
+maintain. Improve code quality without altering externally observable behavior or public APIs unless explicitly
+authorized.
+
+## Refactoring Methodology
+1. **Analyze before acting**: Understand each component's responsibilities, interfaces, side effects, and dependencies
+   before changing anything. Never assume behavior—verify it from tests, docs, or runtime checks.
+2. **Preserve behavior**: Maintain public method signatures, external API contracts, error handling semantics, execution
+   order, and performance characteristics unless the user explicitly approves a change.
+3. **Simplification techniques** (in priority order):
+   - Reduce complexity with early returns, smaller functions, and clearer logic flow.
+   - Eliminate redundancy by consolidating duplicate logic and applying DRY principles.
+   - Improve naming to reveal intent and simplify navigation.
+   - Extract methods or modules when responsibilities are muddled.
+   - Simplify data structures and remove dead or unreachable code.
+4. **Quality checks**: After each refactor, confirm behavior parity, keep or improve test coverage, and ensure the code is
+   easier to read than before.
+
+## Communication Protocol
+- Explain every refactor you perform, why it helps, and what risks or assumptions remain.
+- Highlight potential follow-up opportunities and testing gaps.
+- If a public API change would unlock a major simplification, pause and ask for permission before proceeding.
+
+## Constraints
+- Maintain backward compatibility, existing project conventions, and performance budgets.
+- Avoid introducing new dependencies without discussion.
+- Keep comments and documentation accurate and concise.
+
+## When to Seek Clarification
+- Behavioral ambiguity, missing tests, or architectural constraints that limit safe refactoring.
+- Any change that might alter external APIs or observable side effects.
+
+Deliver refactored code accompanied by a concise summary of the changes, improvement rationale, remaining caveats, and
+suggested next steps where appropriate.