@relipa/ai-flow-kit 0.0.6 → 0.0.7-beta.1

package/README.md

@@ -16,18 +16,18 @@ Developers only need a single command to load ticket context → AI automaticall
 | New plugins (superpowers, MCP...) require manual setup | Package auto-sets up hooks, skills, and MCP on init |
 | Missing investigation / bug reproduction flow | Skill `investigate-bug` (inherits systematic-debugging) |
 | Missing impact analysis flow | Skill `impact-analysis` |
-| Hard to resume tasks | **State Resumption**: Unified `plan/` docs and context across tools |
+| Hard to resume tasks | **State Resumption**: Unified `plan/` docs, `task-summary.md` progress tracking, and intelligent session continuity (automatic Gate 3 resumption). |
 
 ## Documentation & Guides
 
 > [!TIP]
 > After running `aiflow init`, documentation files are automatically copied to `.aiflow/docs/` in your project for easy access.
 
-- **[Quick Start Guide](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
-- **[Full Workflow (5 Gates)](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/AIFLOW.md)** — In-depth look at the Gate process.
-- **[Troubleshooting](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/troubleshooting.md)** — Common issues and fixes.
-- **[Integration Guide](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
-- **[Changelog](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/CHANGELOG.md)** — Version history and release notes.
+- **[Quick Start Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
+- **[Full Workflow (5 Gates)](https://github.com/example/ai-flow-kit/blob/main/docs/common/AIFLOW.md)** — In-depth look at the Gate process.
+- **[Troubleshooting](https://github.com/example/ai-flow-kit/blob/main/docs/common/troubleshooting.md)** — Common issues and fixes.
+- **[Integration Guide](https://github.com/example/ai-flow-kit/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
+- **[Changelog](https://github.com/example/ai-flow-kit/blob/main/docs/common/CHANGELOG.md)** — Version history and release notes.
 
 ---
 
@@ -52,7 +52,7 @@ PM writes ticket on Backlog/Jira
         ▼
 ⛩️ GATE 3 — Code Generation (TDD)           [AI]
   AI writes tests first → implement → tests pass
-  Commit each small step
+  Verify implementation works
         │ Code done
         ▼
 ⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
@@ -74,13 +74,13 @@ PM writes ticket on Backlog/Jira
 
 ```bash
 # Stable version
-npm install -g @relipa/ai-flow-kit
+npm install -g ai-flow-kit
 
 # Beta version (recommend for newest features)
-npm install -g @relipa/ai-flow-kit@beta
+npm install -g ai-flow-kit@beta
 
 # Uninstall
-npm uninstall -g @relipa/ai-flow-kit
+npm uninstall -g ai-flow-kit
 ```
 
 ---
@@ -93,6 +93,7 @@ npm uninstall -g @relipa/ai-flow-kit
 | `aiflow use <ticket>` | Load ticket context (Backlog/Jira). |
 | `aiflow task` | Manage multiple tasks — pause, switch, resume. |
 | `aiflow prompt` | Generate tool-optimized prompts (`--env cursor`). |
+| `aiflow sync-skills` | Manually synchronize AI Instruction files with local custom skills. |
 | `aiflow telemetry` | Manage telemetry tracking (enable/disable/status). |
 | `aiflow guide` | View integrated multi-AI integration guide. |
 
@@ -104,8 +105,10 @@ Initial setup for the project. Run once per project.
 # Single framework + adapter
 aiflow init --framework spring-boot --adapter backlog
 
-# Force enable RTK token compression
-aiflow init --with-rtk
+# Enable token savings tools
+aiflow init --with-rtk                     # RTK: compress bash outputs (60–90% reduction)
+# aiflow init --with-gitnexus               # GitNexus: code intelligence (waits for index)
+# aiflow init --with-gitnexus --no-wait     # GitNexus: index in background
 
 # Multiple frameworks and adapters
 aiflow init --framework spring-boot,reactjs --adapter backlog,jira
@@ -120,12 +123,27 @@ aiflow init --framework spring-boot,reactjs --adapter backlog,jira
 - `.mcp.json` + Claude Desktop config — MCP adapter
 - `.aiflow/credentials.json` — save API credentials
 
-**Supported Frameworks:** `spring-boot`, `laravel`, `reactjs`, `nextjs`, `vue-nuxt`
+**Supported Frameworks:** `spring-boot`, `laravel`, `php-plain`, `nestjs`, `reactjs`, `nextjs`, `vue-nuxt`, `nodejs-express`, `python-django`, `python-fastapi`
 
 **Supported Adapters:** `backlog`, `jira`, `google-sheets`, `figma`
 
 ---
 
+### `aiflow sync-skills`
+
+Synchronize AI instruction files (`CLAUDE.md`, `GEMINI.md`, etc.) and Skills without upgrading the package version. 
+
+```bash
+aiflow sync-skills
+```
+
+**Features:**
+- Intelligent marker-based updates (`<!-- aiflow-kit-start -->`)
+- Confirmation prompts before overwriting custom rules
+- English notifications and status reports
+
+---
+
 ### `aiflow use <ticket>`
 
 Load ticket context into `.aiflow/context/current.json`.
@@ -154,7 +172,7 @@ aiflow use PROJ-33 --comments-from 3
 aiflow use --manual
 
 # Load from local file (JSON or plain text)
-aiflow use --file task.md
+aiflow use --file task.md      # Auto-generates taskId from filename & prompts for taskType
 
 # Modes (Fast is default)
 aiflow use PROJ-33          # Fast Mode: skip Q&A, target < 5 min
@@ -179,6 +197,8 @@ aiflow task switch PROJ-99          # pause current + switch to another task
 aiflow task resume PROJ-33          # resume a paused task (restores context + gate state)
 aiflow task reset  PROJ-33          # reset to Gate 1 (keeps ticket context, clears progress)
 aiflow task remove PROJ-33          # permanently delete all saved data for the task
+aiflow task next                    # approve current gate + prepare for fresh session
+aiflow task next --ticket PROJ-33   # same, but specify ticket explicitly
 ```
 
 **Use case — switching tasks mid-flow:**
@@ -285,9 +305,14 @@ aiflow memory list
 |-----------|---------|--------------|
 | `spring-boot` | Java 17+ | `rules/java/` |
 | `laravel` | PHP 8.1+ | `rules/php/` |
+| `php-plain` | PHP 8.1+ (no framework) | `rules/php/` |
+| `nestjs` | TypeScript | `rules/javascript/` |
 | `reactjs` | TypeScript | `rules/javascript/` |
 | `nextjs` | TypeScript | `rules/javascript/` |
 | `vue-nuxt` | TypeScript | `rules/javascript/` |
+| `nodejs-express` | JavaScript/TypeScript | `rules/javascript/` |
+| `python-django` | Python | — |
+| `python-fastapi` | Python | — |
 
 ---
 
@@ -337,7 +362,7 @@ ai-flow-kit/
 
 **Custom skill:** create `custom/skills/<name>/SKILL.md`
 
-Then run `aiflow update` to apply.
+Then run `aiflow update` or `aiflow sync-skills` to apply.
 
 ---
 
@@ -355,7 +380,7 @@ Then run `aiflow update` to apply.
 
 **`aiflow` not found:**
 ```bash
-npm install -g @relipa/ai-flow-kit
+npm install -g ai-flow-kit
 ```
 
 **Backlog load fails:**

package/bin/aiflow.js

@@ -16,6 +16,7 @@ const removeCommand   = require('../scripts/remove');
 const guideCommand    = require('../scripts/guide');
 const telemetryCommand= require('../scripts/telemetry/cli');
 const taskCommand     = require('../scripts/task');
+const checkpointCommand = require('../scripts/checkpoint');
 const { record }      = require('../scripts/telemetry/record');
 
 program
@@ -63,6 +64,8 @@ program
     .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated (e.g. cursor,gemini,copilot)')
     .option('--with-rtk', 'force enable RTK token compression hook')
     .option('--no-rtk', 'skip RTK setup even if RTK is detected')
+    // .option('--with-gitnexus', 'enable GitNexus code intelligence (indexes in background)')
+    // .option('--wait', 'wait for GitNexus indexing to complete before exiting')
     .action((options) => {
         options.frameworks = options.framework
             ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
@@ -162,6 +165,15 @@ taskCmd
     .description('Permanently delete all saved data for a task')
     .action((ticketId) => { record('command.invoked', { command: 'task.remove' }); taskCommand('remove', { taskId: ticketId }); });
 
+taskCmd
+    .command('next')
+    .description('Approve current gate and prepare next session (saves state for resume)')
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        record('command.invoked', { command: 'task.next' });
+        taskCommand('next', { taskId: opts.ticket });
+    });
+
 // ── context ───────────────────────────────────────────────────
 program
     .command('context [action]')
@@ -176,6 +188,19 @@ program
         contextCommand(action, options);
     });
 
+// ── checkpoint ────────────────────────────────────────────────
+program
+    .command('checkpoint')
+    .description('Record token usage checkpoint (called by AI during gate work)')
+    .requiredOption('--gate <n>', 'gate number (1–5)', parseInt)
+    .requiredOption('--step <name>', 'step name (e.g. "tests-written")')
+    .requiredOption('--tokens <n>', 'estimated token count', parseInt)
+    .option('-t, --ticket <id>', 'ticket ID (defaults to active task)')
+    .action((opts) => {
+        record('command.invoked', { command: 'checkpoint' });
+        checkpointCommand({ gate: opts.gate, step: opts.step, tokens: opts.tokens, ticket: opts.ticket });
+    });
+
 // ── validate ──────────────────────────────────────────────────
 program
     .command('validate <file>')
@@ -253,6 +278,13 @@ program
             command: `gate${gateNum}.${action}`,
             ai_tool: options.aiTool || ''
         });
+
+        if (action === 'approved') {
+            console.log(chalk.cyan(`\n  Gate ${gateNum} approved!`));
+            console.log(chalk.yellow(`  Pro-Tip: To avoid context pollution, it's recommended to start a fresh chat session.`));
+            console.log(chalk.gray(`  Run: aiflow task next${options.ticket ? ` --ticket ${options.ticket}` : ''} to save progress,`));
+            console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
+        }
     });
 
 // ── remove ────────────────────────────────────────────────────
@@ -276,14 +308,45 @@ program
         updateCommand(options);
     });
 
+// ── sync-skills ───────────────────────────────────────────────
+program
+    .command('sync-skills')
+    .description('Manually synchronize AI Instruction files with local custom skills')
+    .action(async () => {
+        record('command.invoked', { command: 'sync-skills' });
+        const projectDir = process.cwd();
+        const { setupFramework, AI_TOOL_FILES, ensureAiflowGitignored } = require('../scripts/init');
+        const fs = require('fs-extra');
+        const path = require('path');
+        const chalk = require('chalk');
+
+        const stateFile = path.join(projectDir, '.aiflow', 'state.json');
+        if (!(await fs.pathExists(stateFile))) {
+            console.log(chalk.red('Project is not initialized. Please run `aiflow init` first.'));
+            return;
+        }
+
+        const state = await fs.readJson(stateFile);
+        const frameworks = state.frameworks || [];
+        const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
+
+        console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
+        for (const fw of frameworks) {
+            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
+        }
+        await ensureAiflowGitignored(projectDir);
+        console.log(chalk.green('✨ Sync completed!'));
+    });
+
 // ── doctor ────────────────────────────────────────────────────
 program
     .command('doctor')
     .description('Health check of AI Flow Kit setup')
+    .option('-t, --ticket <id>', 'show token breakdown for specific ticket')
     .option('-v, --verbose', 'detailed output')
-    .action(() => {
+    .action((opts) => {
         record('command.invoked', { command: 'doctor' });
-        doctorCommand();
+        doctorCommand({ ticket: opts.ticket, verbose: opts.verbose });
     });
 
 // ── telemetry ──────────────────────────────────────────────────

package/custom/mcp-presets/gitnexus.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}

package/custom/skills/generate-spec/SKILL.md

@@ -17,6 +17,13 @@ keywords: spec, plan, implementation, tdd, coding plan
 - ✅ Gate 1 APPROVED — `plan/[ticket-id]/requirement.md` reviewed and approved by DEV
 - ✅ Requirement document includes: requirements, solution, impact analysis, estimate
 
+## Fast Mode Output Rules (CRITICAL)
+
+When updating `plan/[ticket-id]/summary.md` in **fast mode**:
+- **Keep it extremely short.**
+- Add a bullet point indicating Gate 2 plan is ready.
+- **DO NOT copy the entire plan.md into summary.md.**
+
 ---
 
 ## Process

package/custom/skills/impact-analysis/SKILL.md

@@ -20,6 +20,16 @@ keywords: impact, refactor, breaking change, scope
 
 ### Step 1: Find all usage (Dependency Map)
 
+**Preferred — If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry):
+```
+impact("ClassName")    → structured blast radius: callers, dependents, risk score
+detect_changes()       → reads current git diff, maps changed lines → affected symbols
+```
+- Use `impact()` when you know the class/function name being modified.
+- Use `detect_changes()` when starting Gate 4 review — it auto-detects what changed from git diff without needing to specify names.
+- One call replaces all grep commands below. Proceed directly to Step 2 with the result.
+
+**Fallback — grep manually** (if GitNexus not configured):
 ```bash
 # Find all files importing/calling the class/function being modified
 grep -r "ClassName\|functionName\|methodName" --include="*.php" .

package/custom/skills/investigate-bug/SKILL.md

@@ -50,6 +50,23 @@ Route / Controller
         → Database
 ```
 
+**NestJS**
+```
+Controller (@Controller)
+  → Service (@Injectable)
+    → Repository / TypeORM Entity
+      → Database
+```
+
+**PHP Plain (no framework)**
+```
+index.php (router)
+  → Controller
+    → Service
+      → Repository (PDO)
+        → Database
+```
+
 **React / Next.js**
 ```
 Page / Route component

package/custom/skills/read-study-requirement/SKILL.md

@@ -28,6 +28,13 @@ Check `mode` in `.aiflow/context/current.json` before starting:
 
 > Target: Gate 1 complete in **< 5 minutes**, minimum token usage.
 
+## Fast Mode Output Rules (CRITICAL)
+
+When creating `plan/[ticket-id]/summary.md` during Gate 1:
+- You must create the `summary.md` file after Gate 1 is APPROVED, to track session progress.
+- Keep `summary.md` concise. Only include short bullet points tracking Gates.
+- Do not write verbose implementation details in `summary.md` at Gate 1.
+
 1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
 2. Identify **directly affected files** from ticket text and file names only.
    DO NOT trace data flow or read unrelated source files.
@@ -73,6 +80,10 @@ Check `mode` in `.aiflow/context/current.json` before starting:
 1. Read `.aiflow/context/current.json` — ticket info from Backlog/Jira
 2. Read `CLAUDE.md` — understand project architecture, tech stack, conventions
 3. Read related source files — trace data flow, identify patterns, dependencies
+   - **If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry): invoke GitNexus MCP tools instead of reading files directly — one call returns full context without multi-file exploration:
+     - `gitnexus: context("ClassName")` → 360° view of a symbol (dependencies, callers, methods)
+     - `gitnexus: query("keyword or description")` → hybrid search across codebase
+     - Saves ~50% of token cost at this step vs reading files manually
    - **If task is a Bug Fix:** Invoke `superpowers:systematic-debugging` to trace root cause before proposing fixes.
 4. Read ticket comments — additional context from PM/team
 

package/custom/skills/review-plan/SKILL.md

@@ -41,6 +41,21 @@ Assess impact by reasoning about the changed files only:
 - [ ] No hardcoded credentials or secrets
 - [ ] No SQL injection risk in new queries
 
+## Fast Mode Output Rules (CRITICAL)
+
+When creating `plan/[ticket-id]/summary.md` in **fast mode**:
+- **Do not write long explanations or descriptions.**
+- **List format only:** Bullet points with `[NEW]`, `[MODIFIED]`, `[DELETED]`.
+- **Purpose:** Next to each file, write exactly 1 sentence explaining the *purpose* (the "why"), not the implementation details.
+
+**Example summary.md block:**
+```markdown
+### Gate 3 — Code
+- ✅ **Implemented batch endpoints**
+  - \`[NEW] src/controllers/BatchController.ts\`: Handle bulk export requests
+  - \`[MODIFIED] src/services/ExportService.ts\`: Added S3 upload integration
+```
+
 ---
 
 ## Process

package/custom/templates/php-plain.md

@@ -0,0 +1,261 @@
+# PHP Plain AI System Prompt
+
+You are an expert PHP developer working with plain PHP (no framework). Follow these rules to produce clean, secure, maintainable code.
+
+---
+
+## Architecture
+
+Organise code in a layered structure. Avoid writing logic directly in view files.
+
+```
+public/              # Web root — index.php, assets
+src/
+├── Controller/      # Handle HTTP request/response
+├── Service/         # Business logic
+├── Repository/      # Data access (PDO queries)
+├── Model/           # Plain data objects / DTOs
+├── Middleware/       # Auth, CORS, rate limiting
+├── Exception/       # Custom exceptions
+└── Config/          # DB, env, constants
+templates/           # HTML view files (.php/.html)
+```
+
+---
+
+## Coding Rules
+
+### General
+
+- Use **PHP 8.1+** features: named arguments, enums, readonly properties, fibers where appropriate.
+- Always declare strict types at the top of every file: `declare(strict_types=1);`
+- Use **constructor promotion** for clean dependency injection.
+- Follow **PSR-12** coding style.
+- Prefer `match` over long `switch` blocks.
+- Never suppress errors with `@` — handle them properly.
+
+```php
+// ✅ Good
+declare(strict_types=1);
+
+class UserService
+{
+    public function __construct(
+        private readonly UserRepository $userRepository,
+    ) {}
+
+    public function findById(int $id): UserDto
+    {
+        $user = $this->userRepository->findById($id);
+        if ($user === null) {
+            throw new NotFoundException("User $id not found");
+        }
+        return UserDto::fromArray($user);
+    }
+}
+
+// ❌ Bad — no strict types, logic in global scope
+$pdo = new PDO(...);
+$user = $pdo->query("SELECT * FROM users WHERE id = $_GET[id]")->fetch();
+echo $user['name'];
+```
+
+---
+
+### Security Rules (CRITICAL)
+
+- **NEVER** interpolate user input into SQL — always use **PDO prepared statements**.
+- **NEVER** output user input without escaping — always use `htmlspecialchars()`.
+- Validate and sanitize ALL user input at the controller/entry boundary.
+- Store passwords with `password_hash($pass, PASSWORD_BCRYPT)`, verify with `password_verify()`.
+- Use `random_bytes()` / `bin2hex(random_bytes(32))` for tokens — never `rand()` or `md5()`.
+- Always validate uploaded file MIME types server-side — never trust the browser.
+
+```php
+// ✅ Good — prepared statement
+$stmt = $pdo->prepare('SELECT * FROM users WHERE email = :email');
+$stmt->execute([':email' => $email]);
+$user = $stmt->fetch(PDO::FETCH_ASSOC);
+
+// ✅ Good — safe HTML output
+echo htmlspecialchars($user['name'], ENT_QUOTES, 'UTF-8');
+
+// ❌ Bad — SQL injection
+$result = $pdo->query("SELECT * FROM users WHERE email = '$email'");
+```
+
+---
+
+### Database / Repository Rules
+
+- All DB access goes through Repository classes — never call PDO from controllers or services.
+- Use PDO with `PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION`.
+- Wrap multi-step writes in transactions.
+- Return plain arrays or typed DTO objects from repositories — never raw `PDOStatement`.
+
+```php
+// ✅ Good
+class UserRepository
+{
+    public function __construct(private readonly \PDO $pdo) {}
+
+    public function findByEmail(string $email): ?array
+    {
+        $stmt = $this->pdo->prepare(
+            'SELECT id, email, full_name FROM users WHERE email = :email AND deleted = 0'
+        );
+        $stmt->execute([':email' => $email]);
+        $row = $stmt->fetch(\PDO::FETCH_ASSOC);
+        return $row ?: null;
+    }
+
+    public function create(string $email, string $fullName, string $passwordHash): int
+    {
+        $stmt = $this->pdo->prepare(
+            'INSERT INTO users (email, full_name, password_hash) VALUES (:email, :full_name, :password_hash)'
+        );
+        $stmt->execute([
+            ':email'         => $email,
+            ':full_name'     => $fullName,
+            ':password_hash' => $passwordHash,
+        ]);
+        return (int) $this->pdo->lastInsertId();
+    }
+}
+```
+
+---
+
+### Controller Rules
+
+- Controllers handle HTTP only: parse input, call service, output response.
+- Never put business logic or direct DB calls in controllers.
+- Validate input before passing to the service layer.
+- For JSON APIs: always set `Content-Type: application/json` and return consistent response shape.
+
+```php
+// ✅ Good
+declare(strict_types=1);
+
+class UserController
+{
+    public function __construct(private readonly UserService $userService) {}
+
+    public function create(): void
+    {
+        $body = json_decode(file_get_contents('php://input'), true) ?? [];
+        $email    = trim($body['email'] ?? '');
+        $fullName = trim($body['full_name'] ?? '');
+        $password = $body['password'] ?? '';
+
+        if ($email === '' || !filter_var($email, FILTER_VALIDATE_EMAIL)) {
+            http_response_code(400);
+            echo json_encode(['error' => 'Invalid email']);
+            return;
+        }
+
+        $user = $this->userService->create($email, $fullName, $password);
+        http_response_code(201);
+        echo json_encode($user);
+    }
+}
+```
+
+---
+
+### Error Handling
+
+- Define custom exception classes (`NotFoundException`, `ValidationException`, etc.).
+- Register a global exception handler via `set_exception_handler()`.
+- Never expose stack traces or internal paths to the client.
+- Log errors to a file/syslog with a timestamp and context.
+
+```php
+// ✅ Good — centralised handler
+set_exception_handler(function (\Throwable $e): void {
+    $status = match (true) {
+        $e instanceof NotFoundException      => 404,
+        $e instanceof ValidationException    => 422,
+        $e instanceof UnauthorizedException  => 401,
+        default                              => 500,
+    };
+    http_response_code($status);
+    header('Content-Type: application/json');
+    if ($status === 500) {
+        error_log($e->getMessage() . ' ' . $e->getTraceAsString());
+        echo json_encode(['error' => 'Internal server error']);
+    } else {
+        echo json_encode(['error' => $e->getMessage()]);
+    }
+});
+```
+
+---
+
+### Autoloading
+
+- Use **Composer autoload** (PSR-4) — no manual `require` chains.
+- `composer.json` minimum:
+
+```json
+{
+    "autoload": {
+        "psr-4": {
+            "App\\": "src/"
+        }
+    }
+}
+```
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Class | PascalCase | `UserService`, `OrderRepository` |
+| Method | camelCase | `findById`, `createOrder` |
+| Variable | camelCase | `$userId`, `$orderList` |
+| Constant | UPPER_SNAKE_CASE | `MAX_LOGIN_ATTEMPTS` |
+| DB table | snake_case | `user_orders` |
+| DB column | snake_case | `created_at` |
+| File | Matches class name | `UserService.php` |
+
+---
+
+## Testing Rules
+
+- Use **PHPUnit** for unit and integration tests.
+- Test class mirrors source path: `tests/Service/UserServiceTest.php`.
+- Mock dependencies with `$this->createMock()` or a stub.
+- Cover: happy path, validation errors, not-found cases.
+
+```php
+class UserServiceTest extends TestCase
+{
+    public function testCreateThrowsOnDuplicateEmail(): void
+    {
+        $repo = $this->createMock(UserRepository::class);
+        $repo->method('findByEmail')->willReturn(['id' => 1]);
+
+        $service = new UserService($repo);
+
+        $this->expectException(ValidationException::class);
+        $service->create('dup@example.com', 'Test', 'password');
+    }
+}
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Raw SQL in controllers or views
+- ❌ User input directly in SQL / HTML output
+- ❌ Global `$_GET` / `$_POST` access outside the controller boundary
+- ❌ `die()` / `exit()` for error handling — use exceptions
+- ❌ Storing plain-text passwords
+- ❌ `include`/`require` inside business logic — use autoloading
+- ❌ Logic-heavy view files (`.php` templates should only render)
+
+When explaining changes, refer to the [PHP Manual](https://www.php.net/manual) and [PSR standards](https://www.php-fig.org/psr/).