ai-dev-starter 0.0.0-stage → 1.0.0

package/workflows/performance-audit.md

@@ -0,0 +1,169 @@
+# Workflow: Performance Audit
+
+> **Purpose:** Identify measurable or evidence-supported performance bottlenecks.
+> **Authorization:** Read-only. No file writes.
+> **Principle:** Prioritize evidence-supported issues over theoretical ones.
+
+---
+
+## Trigger
+
+- "performance audit", "slow queries", "optimize", "performance review"
+- "بررسی کارایی", "بهینه‌سازی", "کوئری کند"
+
+---
+
+## Required Context
+
+1. `core/agent-principles.md`
+2. `core/severity-levels.md`
+3. `.agents/project-context.md`
+
+---
+
+## Execution Steps
+
+### Step 1 — Define Scope
+
+Confirm:
+- Specific area (database, frontend, API, background jobs) or full audit?
+- Any known slow endpoints or operations?
+- Current scale (approximate record counts, concurrent users).
+
+### Step 2 — Database Query Analysis
+
+#### N+1 Query Detection
+```bash
+# Laravel: look for loops that contain queries
+grep -rn "foreach\|for (" --include="*.php" app/ | head -20
+# Then manually inspect each loop body for ORM calls
+
+# Check for missing eager loading
+grep -rn "->get()\|->first()\|->find(" --include="*.php" app/ | head -20
+
+# Look for ->with() usage (eager loading)
+grep -rn "->with(\|->load(" --include="*.php" app/ | head -20
+```
+
+#### Missing Indexes
+```bash
+# Find migration files and check indexed columns
+find database/migrations -name "*.php" | xargs grep -l "index\|foreign\|unique" | head -10
+# Review recent migrations
+ls -t database/migrations | head -5 | xargs -I{} cat database/migrations/{}
+```
+
+#### Unbounded Queries
+```bash
+# Queries without pagination or LIMIT
+grep -rn "->get()\|->all()\|SELECT \*" --include="*.php" --include="*.ts" app/ src/ | \
+  grep -v "paginate\|limit\|take\|LIMIT" | head -20
+```
+
+#### Expensive Aggregations
+```bash
+grep -rn "->count()\|->sum()\|->avg()\|->max()\|->min()" --include="*.php" app/ | head -20
+```
+
+### Step 3 — API and HTTP Analysis
+
+```bash
+# Synchronous external HTTP calls
+grep -rn "Http::\|curl_exec\|file_get_contents.*http\|axios\.\|fetch(" --include="*.php" --include="*.ts" app/ src/ | head -20
+
+# Large response payloads
+grep -rn "toArray()\|->toJson()\|json_encode" --include="*.php" app/ | head -20
+
+# Missing caching
+grep -rn "Cache::\|Redis::\|remember\|cache(" --include="*.php" app/ | head -20
+# If caching is absent in hot paths, flag for investigation
+```
+
+### Step 4 — Frontend / Rendering Analysis
+
+```bash
+# Large bundle imports
+grep -rn "import \* as\|require(" --include="*.ts" --include="*.tsx" --include="*.js" src/ | head -20
+
+# Non-lazy-loaded routes
+grep -rn "import {" --include="*.tsx" --include="*.ts" src/app/ | head -20
+
+# Missing React.memo / useMemo / useCallback on expensive components
+grep -rn "useEffect\|useState" --include="*.tsx" src/ | head -20
+```
+
+### Step 5 — Background Jobs
+
+```bash
+# Large job payloads
+grep -rn "dispatch\|Queue::" --include="*.php" app/ | head -20
+
+# Synchronous operations in job handlers
+grep -rn "Http::\|curl\|file_get_contents" --include="*.php" app/Jobs/ | head -20
+```
+
+### Step 6 — Analyze Findings
+
+For each potential performance issue, assess:
+- **Measurable?** Can the impact be quantified or is it theoretical?
+- **Scale-dependent?** At what data volume or request rate does this become a problem?
+- **Evidence?** Can you identify the specific query, loop, or call that is slow?
+
+Do not report speculative performance concerns without evidence.
+
+### Step 7 — Generate Report
+
+```markdown
+## Performance Audit Report
+
+**Scope:** [Module / Full Codebase]
+**Date:** YYYY-MM-DD
+
+---
+
+### Critical Issues (P0–P1)
+
+#### [P1] N+1 Query in OrderController::index
+
+**File:** `app/Http/Controllers/OrderController.php` line 45
+
+**Problem:**
+Loop fetches related `Customer` model for each `Order` individually.
+
+**Evidence:**
+```php
+foreach ($orders as $order) {
+    $customerName = $order->customer->name; // DB query per iteration
+}
+```
+
+**Impact at scale:**
+100 orders → 101 queries. 10,000 orders → 10,001 queries. Response time degrades linearly.
+
+**Fix:**
+```php
+$orders = Order::with('customer')->paginate(50);
+```
+
+**Verification:**
+Enable query logging: `DB::enableQueryLog()`. Confirm single query after fix.
+
+---
+```
+
+---
+
+## Completion Criteria
+
+- Database query patterns inspected.
+- N+1 risks identified with specific code locations.
+- Missing indexes identified where queries exist on unindexed columns.
+- Each finding has evidence and estimated impact at scale.
+
+---
+
+## Limitations
+
+- Cannot profile actual query execution plans without database access.
+- Cannot measure frontend bundle sizes without build output.
+- Cannot identify application-layer bottlenecks without profiling tools (Telescope, Xdebug, New Relic).

package/workflows/refactor.md

@@ -0,0 +1,128 @@
+# Workflow: Refactoring
+
+> **Purpose:** Improve code structure and maintainability without changing observable behavior.
+> **Authorization:** Read freely. Write incrementally within authorized scope.
+> **Golden Rule:** If behavior changes, it is not refactoring — stop and discuss.
+
+---
+
+## Trigger
+
+- "refactor", "clean up", "simplify", "improve readability"
+- "ریفکتور", "بهبود کد", "ساده‌سازی"
+
+---
+
+## Required Context
+
+1. `core/agent-principles.md`
+2. `core/safety-policy.md`
+3. `.agents/project-context.md`
+
+---
+
+## Execution Steps
+
+### Step 1 — Understand Scope
+
+Confirm:
+- Which file(s) or module(s) are in scope.
+- What quality problem the user wants to address.
+- Whether there is existing test coverage (critical for safe refactoring).
+
+### Step 2 — Assess Test Coverage
+
+```bash
+# Run existing tests to establish baseline
+php artisan test --filter=ScopeClass
+# or
+npm test -- --testPathPattern=ScopedModule
+```
+
+**If no tests exist:** Alert the user.
+> "⚠️ No tests found covering this code. Refactoring without tests risks introducing regressions. Recommend writing tests first. Shall I generate tests before refactoring?"
+
+Do not proceed with refactoring on untested code without user explicit acknowledgment of the risk.
+
+### Step 3 — Identify Improvements
+
+Look for:
+
+| Anti-Pattern | Description |
+|---|---|
+| Long method | Function > 30 lines doing multiple things |
+| Deep nesting | More than 3 levels of if/loop nesting |
+| Duplicated logic | Same logic copy-pasted in 2+ places |
+| God class | Class doing too many unrelated things |
+| Magic values | Hardcoded numbers or strings without explanation |
+| Primitive obsession | Using raw strings/ints where a type/enum fits |
+| Dead code | Unreachable, commented-out, or unused code |
+| Leaky abstraction | Implementation details exposed across layer boundary |
+
+### Step 4 — Present Refactoring Plan
+
+```markdown
+## Refactoring Plan: <File or Module>
+
+**Current problems:**
+1. `processOrder()` is 120 lines doing validation, calculation, and persistence.
+2. Magic number `0.15` appears 4 times without explanation.
+3. Nested condition depth reaches 5 levels.
+
+**Proposed changes:**
+1. Extract `validateOrder()`, `calculateTotals()`, `persistOrder()`.
+2. Define `const TAX_RATE = 0.15` with a comment.
+3. Replace nested conditions with early returns.
+
+**Behavior preserved:** Yes — externally visible interface unchanged.
+**Tests needed:** Existing tests will cover all changes.
+
+Shall I proceed?
+```
+
+**Wait for approval before writing any files.**
+
+### Step 5 — Implement in Small Steps
+
+Apply one change category at a time:
+1. Extract methods / functions.
+2. Eliminate duplication.
+3. Rename for clarity.
+4. Remove dead code.
+5. Restructure control flow.
+
+Run tests after each step:
+```bash
+php artisan test --filter=ScopeClass
+```
+
+If any test fails: **stop**, report the failure, and revert the last step.
+
+### Step 6 — Verify Behavior Preservation
+
+After all changes:
+```bash
+# Run the full test suite for the affected module
+php artisan test --filter=ScopeModule
+```
+
+Report actual output. Do not declare success without evidence.
+
+---
+
+## Boundaries
+
+- Do not add features during refactoring.
+- Do not change public APIs or interfaces.
+- Do not modify database migrations.
+- Do not change test assertions.
+- Do not reformat code outside the changed functions.
+
+---
+
+## Completion Criteria
+
+- Original behavior preserved (tests still pass).
+- Code is measurably simpler (fewer lines, less nesting, less duplication).
+- No scope creep.
+- Tests ran and results reported.

package/workflows/security-audit.md

@@ -0,0 +1,164 @@
+# Workflow: Security Audit
+
+> **Purpose:** Identify realistic security vulnerabilities in the codebase.
+> **Authorization:** Read-only. No file writes. No commits.
+> **Scope:** Realistic vulnerabilities only. No theoretical or low-evidence findings.
+
+---
+
+## Trigger
+
+- "security audit", "security review", "vulnerability check"
+- "بررسی امنیتی", "آسیب‌پذیری"
+
+---
+
+## Required Context
+
+1. `core/agent-principles.md`
+2. `core/severity-levels.md`
+3. `.agents/project-context.md`
+4. `standards/security.md`
+
+---
+
+## Execution Steps
+
+### Step 1 — Define Scope
+
+Confirm with the user:
+- Full codebase audit, or specific module/endpoint?
+- Recent changes only, or entire codebase?
+- Any known areas of concern?
+
+### Step 2 — Enumerate Attack Surface
+
+```bash
+# Routes and endpoints
+cat routes/web.php routes/api.php 2>/dev/null
+# or
+grep -rn "app\.(get|post|put|delete|patch)" --include="*.js" --include="*.ts" src/ | head -30
+
+# Authentication middleware
+grep -rn "auth\|middleware\|guard\|protect" --include="*.php" routes/ app/ | head -20
+
+# Public endpoints (no auth)
+grep -rn "Route::" routes/web.php | grep -v "auth\|middleware" | head -20
+```
+
+Identify:
+- All authentication entry points.
+- All endpoints that mutate data.
+- All endpoints that return sensitive data.
+- All file upload or download handlers.
+- All external service integrations.
+
+### Step 3 — Inspect Vulnerability Categories
+
+#### A. Injection
+
+```bash
+# SQL Injection — look for raw queries or string concatenation
+grep -rn "DB::select\|DB::statement\|whereRaw\|orderByRaw\|havingRaw" --include="*.php" app/ | head -20
+grep -rn "query\|exec\|execute" --include="*.js" --include="*.ts" src/ | grep "req\.\|user\.\|\$_" | head -20
+
+# Command Injection
+grep -rn "exec\|shell_exec\|system\|passthru\|popen\|proc_open" --include="*.php" app/ | head -10
+grep -rn "exec\|spawn\|execSync\|execFile" --include="*.ts" --include="*.js" src/ | head -10
+
+# XSS — unescaped output
+grep -rn "echo \$\|{!!\|v-html\|dangerouslySetInnerHTML" --include="*.php" --include="*.blade.php" --include="*.tsx" . | head -20
+```
+
+#### B. Authentication and Authorization
+
+```bash
+# Missing auth middleware
+grep -rn "Route::\(get\|post\|put\|delete\)" routes/ | head -30
+
+# Authorization checks in controllers
+grep -rn "\$this->authorize\|Gate::\|can(\|Policy" --include="*.php" app/Http/Controllers/ | head -20
+
+# JWT / session validation
+grep -rn "token\|jwt\|session\|cookie" --include="*.php" --include="*.ts" app/ src/ | grep -i "valid\|verif\|check" | head -10
+```
+
+#### C. Sensitive Data Exposure
+
+```bash
+# Hardcoded secrets
+grep -rn "password\|secret\|key\|token" --include="*.php" --include="*.ts" --include="*.js" . \
+  | grep -v "\.env\|config\|test\|spec\|\.git" \
+  | grep -i "['\"].\{8,\}['\"]" | head -20
+
+# API responses that may leak sensitive data
+grep -rn "toArray\|toJson\|->makeHidden\|->makeVisible\|hidden\|visible" --include="*.php" app/Models/ | head -20
+
+# Error messages that expose internals
+grep -rn "getMessage\|getTrace\|debug.*true\|APP_DEBUG" --include="*.php" . | grep -v test | head -10
+```
+
+#### D. Mass Assignment
+
+```bash
+# Laravel: unguarded models
+grep -rn "unguarded\|fillable\|guarded" --include="*.php" app/Models/ | head -20
+grep -rn "\$request->all()\|\$request->input()" --include="*.php" app/Http/ | head -20
+```
+
+#### E. CSRF and Request Forgery
+
+```bash
+# Check which routes are exempt from CSRF
+grep -rn "VerifyCsrfToken\|except\|csrf" --include="*.php" app/Http/Middleware/ | head -10
+```
+
+#### F. File Operations
+
+```bash
+# Unsafe file operations
+grep -rn "unlink\|rename\|move\|copy\|file_put_contents" --include="*.php" app/ | head -10
+grep -rn "Storage::\|File::\|Filesystem" --include="*.php" app/ | head -10
+
+# File upload handling
+grep -rn "->store\|->move\|getClientOriginalExtension\|getMimeType" --include="*.php" app/ | head -10
+```
+
+### Step 4 — Read and Analyze
+
+For each suspicious pattern found, read the surrounding code:
+- 20–50 lines of context around the finding.
+- The route definition and middleware chain.
+- The model's `$fillable` or `$guarded` list.
+
+Apply the verification checklist from `core/review-methodology.md` before recording any finding.
+
+### Step 5 — Generate Report
+
+Report findings by severity (P0 → P3).
+
+Include for each finding:
+- Vulnerability type (from OWASP category).
+- File and line number.
+- Exact problematic code.
+- Realistic attack scenario.
+- Recommended fix.
+
+---
+
+## Completion Criteria
+
+- Full attack surface enumerated.
+- All six vulnerability categories inspected.
+- Each finding has evidence, attack scenario, and fix.
+- No speculative findings.
+
+---
+
+## Limitations
+
+This workflow cannot:
+- Run dynamic analysis (DAST) or penetration testing.
+- Inspect third-party package source code thoroughly.
+- Test cryptographic implementation correctness mathematically.
+- Detect vulnerabilities requiring runtime state.

package/workflows/test-generation.md

@@ -0,0 +1,168 @@
+# Workflow: Test Generation
+
+> **Purpose:** Generate meaningful tests for existing or new code.
+> **Authorization:** Read freely. Write only test files.
+> **Constraint:** Use only the testing frameworks already present in the project.
+
+---
+
+## Trigger
+
+- "generate tests", "write tests", "add tests", "test coverage"
+- "تست بنویس", "تست اضافه کن", "پوشش تست"
+
+---
+
+## Required Context
+
+1. `core/agent-principles.md`
+2. `.agents/project-context.md`
+3. `standards/testing.md`
+
+---
+
+## Execution Steps
+
+### Step 1 — Identify Testing Setup
+
+```bash
+# PHP
+cat composer.json | grep -i "phpunit\|pest\|codeception"
+ls tests/
+
+# JavaScript / TypeScript
+cat package.json | grep -i "jest\|vitest\|mocha\|cypress\|playwright"
+ls __tests__/ 2>/dev/null; ls src/__tests__/ 2>/dev/null; ls tests/ 2>/dev/null
+
+# Python
+cat pyproject.toml 2>/dev/null | grep -i "pytest\|unittest"
+ls tests/
+
+# Read one existing test file to understand conventions
+find tests/ -name "*.test.*" -o -name "*Test.php" -o -name "*_test.py" | head -3 | xargs cat
+```
+
+Identify:
+- Test framework (PHPUnit, Pest, Jest, Vitest, pytest).
+- Test file naming conventions (`FeatureTest.php`, `Feature.test.ts`, etc.).
+- Test organization (feature vs unit, mirroring `src/` structure).
+- Assertion style.
+- Mocking library.
+- Database testing strategy (refresh, factory, fixtures).
+
+### Step 2 — Understand the Code to Test
+
+Read the target class or module fully:
+- Public interface (all public methods).
+- Dependencies (what it needs to function).
+- Error conditions (what it throws or returns on failure).
+
+```bash
+# PHP: list public methods
+grep -n "public function" app/Services/TargetService.php
+
+# TypeScript: list exports
+grep -n "^export " src/services/TargetService.ts
+```
+
+### Step 3 — Identify Test Cases
+
+For each public method / exported function, identify:
+
+| Scenario | Priority |
+|----------|----------|
+| Happy path (expected inputs → expected output) | High |
+| Validation error (invalid input → validation error) | High |
+| Not found (missing resource → 404 / null / exception) | High |
+| Unauthorized (wrong permissions → 403 / error) | High |
+| Boundary values (empty string, zero, max value) | Medium |
+| Concurrent access (if relevant) | Medium |
+| External service failure (if mocked) | Medium |
+
+Do not generate tests for private methods directly. Test through the public interface.
+
+### Step 4 — Present Test Plan
+
+```markdown
+## Test Plan: OrderService
+
+**Framework:** PHPUnit / Pest
+**Location:** `tests/Unit/Services/OrderServiceTest.php`
+**Mocks required:** `PaymentGateway`, `InventoryService`
+
+**Test cases:**
+1. `test_create_order_with_valid_data_returns_order_model`
+2. `test_create_order_with_missing_product_throws_not_found_exception`
+3. `test_create_order_with_insufficient_stock_returns_error`
+4. `test_create_order_calls_payment_gateway_once`
+5. `test_create_order_rolls_back_on_payment_failure`
+
+Shall I generate these tests?
+```
+
+**Wait for approval before writing files.**
+
+### Step 5 — Generate Tests
+
+Write tests that:
+- Follow the project's naming and organization conventions exactly.
+- Use `arrange / act / assert` (or `given / when / then`) structure with clear comments.
+- Test one thing per test method.
+- Have descriptive names that explain the scenario.
+- Use the project's existing factory or fixture setup.
+
+```php
+// Example: PHPUnit / Pest (PHP)
+it('creates an order and charges the payment gateway', function () {
+    // Arrange
+    $paymentGateway = Mockery::mock(PaymentGateway::class);
+    $paymentGateway->expects('charge')->once()->andReturn(true);
+    $this->app->instance(PaymentGateway::class, $paymentGateway);
+
+    $product = Product::factory()->create(['stock' => 10]);
+
+    // Act
+    $order = app(OrderService::class)->create([
+        'product_id' => $product->id,
+        'quantity' => 2,
+    ]);
+
+    // Assert
+    expect($order)->toBeInstanceOf(Order::class);
+    expect($order->status)->toBe('confirmed');
+});
+```
+
+### Step 6 — Run Generated Tests
+
+```bash
+# PHP
+php artisan test --filter=OrderServiceTest
+# or
+./vendor/bin/pest tests/Unit/Services/OrderServiceTest.php
+
+# JavaScript
+npm test -- --testPathPattern=OrderService
+# or
+npx vitest run src/services/OrderService.test.ts
+
+# Python
+pytest tests/unit/test_order_service.py -v
+```
+
+Report actual output. Do not claim tests pass without running them.
+
+---
+
+## Completion Criteria
+
+- Testing framework identified from existing setup.
+- Test cases cover happy path and primary failure modes.
+- Generated tests follow existing conventions exactly.
+- Tests run successfully (or failures are documented with explanation).
+
+---
+
+## Boundaries
+
+Do not introduce new testing dependencies (new libraries, new assertion styles) without user approval.