ai-dev-starter 0.0.0-stage → 1.0.0

package/standards/security.md

@@ -0,0 +1,84 @@
+# Security Standards
+
+> **Scope:** Universal application security baseline.
+> **Load:** Always loaded for security-audit workflow. Referenced by code-review.
+
+---
+
+## OWASP Top 10 Baseline
+
+### A01 — Broken Access Control
+- Enforce authorization on every state-changing request.
+- Deny by default. Grant access explicitly.
+- Do not rely on obscure URLs or hidden UI elements for access control.
+- Validate that the authenticated user owns or has rights to each resource they access.
+
+### A02 — Cryptographic Failures
+- Use TLS 1.2+ for all data in transit.
+- Use AES-256 for symmetric encryption at rest.
+- Use bcrypt, argon2, or scrypt for password hashing.
+- Never roll custom cryptographic algorithms.
+- Rotate keys and manage them through a secrets manager, not source code.
+
+### A03 — Injection
+- Use parameterized queries or ORMs for all database interactions.
+- Never pass user input to `eval`, `exec`, `shell_exec`, `system`, or similar.
+- Sanitize and encode output before rendering in HTML (use framework templating engines).
+- Validate file paths — prevent directory traversal.
+
+### A04 — Insecure Design
+- Apply the principle of least privilege to all roles and service accounts.
+- Design rate limiting for authentication endpoints and sensitive operations.
+- Limit failed login attempts (lockout or CAPTCHA after N failures).
+
+### A05 — Security Misconfiguration
+- Disable debug mode and verbose errors in production.
+- Remove default accounts and credentials.
+- Apply security headers: `Content-Security-Policy`, `X-Frame-Options`, `Strict-Transport-Security`.
+- Review and restrict CORS policies — do not allow `*` for credentialed requests.
+
+### A06 — Vulnerable and Outdated Components
+- Track direct dependencies for known CVEs.
+- Run `composer audit`, `npm audit`, or `pip-audit` as part of CI.
+- Update dependencies regularly, especially for security patches.
+
+### A07 — Identification and Authentication Failures
+- Use multi-factor authentication for administrative access.
+- Use secure, `HttpOnly`, `Secure`, `SameSite=Strict` cookie attributes.
+- Implement CSRF protection for all state-changing form submissions.
+- Invalidate sessions after logout and after password change.
+
+### A08 — Software and Data Integrity Failures
+- Verify file checksums or signatures for critical downloads.
+- Use lockfiles (`composer.lock`, `package-lock.json`) for reproducible builds.
+- Do not deserialize untrusted data without strict type validation.
+
+### A09 — Security Logging and Monitoring
+- Log authentication events, permission denials, and input validation failures.
+- Do not log sensitive data (passwords, tokens, PII).
+- Set up alerts for suspicious patterns (many failed logins, unusual data volumes).
+
+### A10 — Server-Side Request Forgery (SSRF)
+- Validate and allowlist URLs before making server-side HTTP requests.
+- Block requests to internal IP ranges (169.254.x.x, 10.x.x.x, 172.16-31.x.x, 192.168.x.x).
+- Do not use user-provided URLs in server-side HTTP calls without validation.
+
+---
+
+## Credential Management
+
+- Store all secrets in environment variables or a secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager).
+- Never commit secrets, API keys, or passwords to version control.
+- Use `.gitignore` to exclude `.env` files.
+- Rotate credentials when team members leave.
+- Audit `.git` history if a credential has been accidentally committed.
+
+---
+
+## API Security
+
+- Authenticate all API endpoints unless explicitly designed to be public.
+- Rate limit all APIs — especially auth, registration, and search.
+- Return generic error messages for auth failures (do not reveal whether a user exists).
+- Version APIs — do not break existing clients with silent changes.
+- Validate `Content-Type` on request bodies.

package/standards/testing.md

@@ -0,0 +1,132 @@
+# Testing Standards
+
+> **Scope:** Universal testing principles. Framework-specific details inferred from project setup.
+> **Load:** On demand for test-generation workflow and code reviews.
+
+---
+
+## Testing Pyramid
+
+```
+         /\
+        /  \  E2E Tests
+       /----\  (few, slow, expensive)
+      /      \
+     / Integr. \  Integration Tests
+    /------------\  (moderate, test real interactions)
+   /              \
+  /   Unit Tests   \  (many, fast, isolated)
+ /------------------\
+```
+
+- **Unit tests:** Test one function or class in isolation. Fast, numerous.
+- **Integration tests:** Test multiple units working together (service + database, controller + middleware).
+- **E2E tests:** Test full user flows through the UI or API. Expensive; use sparingly.
+
+Target: **Unit tests for business logic, Integration tests for API endpoints, E2E for critical user flows only.**
+
+---
+
+## Test Quality Criteria
+
+### A Good Test
+- Tests a single, clearly named behavior.
+- Has a descriptive name: `test_create_order_with_zero_stock_returns_error`.
+- Has three distinct sections: Arrange / Act / Assert.
+- Passes consistently (no flakiness from timing or external state).
+- Runs in isolation (no dependency on test execution order).
+- Cleans up after itself (no residual database or file state).
+
+### A Bad Test
+- Tests multiple behaviors in one test method.
+- Has an uninformative name: `test_order_1`.
+- Relies on external services without mocking.
+- Checks implementation details rather than behavior.
+- Cannot fail — asserts are missing or trivially true.
+
+---
+
+## What to Test
+
+### Always Test
+- Core business logic (calculations, state transitions, validations).
+- Authorization rules (who can access what).
+- Data validation (what inputs are accepted and rejected).
+- Error paths (what happens when dependencies fail).
+- Security-critical behavior (input sanitization, permission checks).
+
+### Usually Test
+- API endpoint contracts (request/response shapes, status codes).
+- Database persistence (do the right records get created/updated/deleted?).
+- Background job behavior.
+
+### Often Skip
+- Framework boilerplate (resource controllers that only delegate to services).
+- Simple getters and setters.
+- Generated code.
+
+---
+
+## Test Structure
+
+```php
+// PHP — Pest
+it('charges the customer once per order', function () {
+    // Arrange
+    $payment = Mockery::mock(PaymentGateway::class);
+    $payment->expects('charge')->once()->andReturn(['status' => 'success']);
+    app()->instance(PaymentGateway::class, $payment);
+    $order = Order::factory()->make();
+
+    // Act
+    $result = app(OrderService::class)->place($order);
+
+    // Assert
+    expect($result->status)->toBe('confirmed');
+});
+```
+
+```typescript
+// TypeScript — Vitest / Jest
+describe('OrderService', () => {
+    it('places an order and returns confirmed status', async () => {
+        // Arrange
+        const mockPayment = { charge: vi.fn().mockResolvedValue({ status: 'success' }) };
+        const service = new OrderService(mockPayment);
+
+        // Act
+        const result = await service.place({ productId: 1, quantity: 2 });
+
+        // Assert
+        expect(result.status).toBe('confirmed');
+        expect(mockPayment.charge).toHaveBeenCalledTimes(1);
+    });
+});
+```
+
+---
+
+## Mocking Guidelines
+
+- Mock at the boundary of your system (external APIs, email providers, payment gateways).
+- Do not mock internal business logic — test it directly.
+- Use fakes (in-memory implementations) over mocks when possible for stability.
+- Reset mocks between tests.
+
+---
+
+## Test Coverage
+
+- Coverage metrics are a guide, not a goal. 100% coverage does not mean correctness.
+- Target 80%+ branch coverage on business logic classes.
+- Prioritize covering error paths and edge cases.
+- Use coverage reports to find untested critical paths, not to game percentages.
+
+---
+
+## Test Data
+
+- Use factories to generate test data. Do not use production data in tests.
+- Seed deterministic test data for predictable assertions.
+- Do not rely on specific IDs (auto-increment values differ between runs).
+- Isolate database state between tests (transaction rollback or database refresh).

package/templates/architecture-decision.md

@@ -0,0 +1,92 @@
+# Architecture Decision Record (ADR)
+
+> **Template:** Use this to document significant architectural decisions.
+> **File naming:** `docs/adr/NNNN-short-title.md` (e.g., `docs/adr/0001-use-event-sourcing.md`).
+
+---
+
+## ADR-{{NUMBER}}: {{TITLE}}
+
+**Status:** `Proposed` | `Accepted` | `Deprecated` | `Superseded by ADR-NNN`
+**Date:** YYYY-MM-DD
+**Deciders:** {{names or roles}}
+
+---
+
+## Context
+
+<!-- What is the situation that is forcing us to make a decision?
+     What constraints or forces are at play? Be specific. -->
+
+{{context_description}}
+
+---
+
+## Decision Drivers
+
+- {{driver_1}}: e.g., "Team is unfamiliar with event sourcing"
+- {{driver_2}}: e.g., "We need audit logs for compliance"
+- {{driver_3}}
+
+---
+
+## Options Considered
+
+### Option A: {{option_a_name}}
+
+**Description:** {{brief description}}
+
+**Pros:**
+- {{pro_1}}
+
+**Cons:**
+- {{con_1}}
+
+---
+
+### Option B: {{option_b_name}}
+
+**Description:** {{brief description}}
+
+**Pros:**
+- {{pro_1}}
+
+**Cons:**
+- {{con_1}}
+
+---
+
+## Decision
+
+**Chosen:** Option {{A/B/C}}
+
+**Rationale:**
+{{1–3 paragraphs explaining why this option was chosen over the alternatives, referencing the decision drivers}}
+
+---
+
+## Consequences
+
+### Positive
+- {{positive_outcome_1}}
+
+### Negative / Trade-offs
+- {{trade_off_1}}
+
+### Neutral
+- {{neutral_note_1}}
+
+---
+
+## Implementation Notes
+
+<!-- Specific guidance for implementing this decision. -->
+
+{{implementation_notes_or_none}}
+
+---
+
+## References
+
+- {{link_to_relevant_documentation}}
+- {{link_to_related_ADR}}

package/templates/project-context.md

@@ -0,0 +1,144 @@
+# Project Context
+
+> **Instructions for the AI agent:** Read this file first when starting any task in this project.
+> Do NOT overwrite this file without user permission.
+> Fill in every field. Leave unknown fields as `unknown` or `[]`.
+
+---
+
+## Project Identity
+
+```yaml
+project_name: "My Project"
+version: "1.0.0"
+description: "Brief description of what this project does"
+repository: "https://github.com/org/repo"
+```
+
+---
+
+## Tech Stack
+
+```yaml
+# Backend
+backend_language: ""          # php, typescript, python, go, etc.
+backend_framework: ""         # laravel, express, fastapi, gin, etc.
+backend_version: ""           # e.g., Laravel 11, Node.js 20
+
+# Frontend
+frontend_framework: ""        # react, next, vue, nuxt, angular, none
+frontend_language: ""         # typescript, javascript
+styling: ""                   # tailwind, css-modules, styled-components, etc.
+
+# Database
+databases:                    # list all
+  - type: ""                  # mysql, postgresql, mongodb, redis, etc.
+    version: ""
+    orm: ""                   # eloquent, prisma, sqlalchemy, etc.
+
+# Infrastructure
+hosting: ""                   # AWS, GCP, Azure, Vercel, Hetzner, etc.
+containerized: false          # true/false
+ci_cd: ""                     # GitHub Actions, GitLab CI, Bitbucket Pipelines, etc.
+```
+
+---
+
+## Architecture
+
+```yaml
+pattern: ""         # MVC, Clean Architecture, Hexagonal, DDD, Microservices, etc.
+layers:
+  - name: ""        # e.g., Controllers, Services, Repositories, Models
+    path: ""        # e.g., app/Http/Controllers
+
+key_directories:
+  - path: ""        # e.g., app/Services
+    purpose: ""     # Business logic layer
+```
+
+---
+
+## Development Commands
+
+```yaml
+install: "composer install && npm install"
+dev_server: "php artisan serve"
+build: "npm run build"
+test: "php artisan test"
+lint: "php cs-fixer fix --dry-run"
+format: "php cs-fixer fix"
+migrate: "php artisan migrate"
+```
+
+---
+
+## Testing Setup
+
+```yaml
+backend_test_framework: ""      # phpunit, pest, pytest, jest, vitest
+test_directory: "tests/"
+integration_tests: false
+e2e_tests: false
+test_database: ""               # e.g., sqlite in-memory, test MySQL database
+coverage_target: 80
+```
+
+---
+
+## Coding Conventions
+
+```yaml
+# Naming
+class_naming: ""          # PascalCase
+method_naming: ""         # camelCase
+variable_naming: ""       # camelCase / snake_case
+file_naming: ""           # PascalCase for classes, kebab-case for components
+
+# Formatting
+indentation: 4            # spaces
+max_line_length: 120
+trailing_commas: true
+
+# Specific rules (add project-specific rules here)
+custom_rules:
+  - ""
+```
+
+---
+
+## Important Constraints
+
+```yaml
+# Things the AI must never do in this project
+never_do:
+  - "Never push to main branch directly"
+  - "Never run migrations in production manually"
+  - "Never bypass the OrderService for order creation"
+
+# High-risk areas requiring extra caution
+sensitive_areas:
+  - path: ""
+    reason: ""
+
+# External dependencies or services this project uses
+external_services:
+  - name: ""
+    purpose: ""
+```
+
+---
+
+## Review and Report Settings
+
+```yaml
+report_language: "fa"       # fa = Persian (Farsi), en = English
+severity_threshold: "P2"    # Minimum severity to include in reports (P0, P1, P2, P3)
+```
+
+---
+
+## Project Notes
+
+<!-- Add any additional context the AI should know about this project. -->
+<!-- Examples: unusual conventions, legacy areas to avoid, known technical debt, etc. -->

package/templates/review-report.md

@@ -0,0 +1,102 @@
+# Code Review Report
+
+> **Template:** Used by the Code Review workflow to structure output.
+> **Language:** Fill report in the language configured in project-context.md → `report_language`.
+
+---
+
+## گزارش بررسی کد / Code Review Report
+
+**شاخه (Branch):** `{{branch}}` → `{{base_branch}}`
+**تعداد فایل‌های تغییریافته (Files changed):** {{file_count}}
+**تعداد کامیت‌ها (Commits):** {{commit_count}}
+**تاریخ (Date):** {{date}}
+**بررسی‌کننده (Reviewer):** AI Agent (ai-dev-starter)
+
+---
+
+## خلاصه تغییرات / Walkthrough
+
+{{walkthrough_paragraph}}
+
+---
+
+## فایل‌های تغییریافته / Changed Files
+
+| فایل (File) | تغییرات (Changes) | نوع (Type) |
+|-------------|-------------------|------------|
+| `{{file_path}}` | +{{added}} / -{{removed}} | {{type: modified/added/deleted}} |
+
+---
+
+## یافته‌ها / Findings
+
+<!-- Repeat the following block for each finding, ordered P0 → P3 -->
+
+### [{{SEVERITY}}] {{short_title}}
+
+**فایل (File):** `{{file_path}}` خط (Line) {{line_number}}
+**نوع آسیب‌پذیری (Type):** {{category: Security / Logic / Performance / Architecture / Quality}}
+
+**مشکل (Problem):**
+{{problem_description_in_report_language}}
+
+**شواهد (Evidence):**
+```{{language}}
+{{relevant_code_snippet}}
+```
+
+**تأثیر (Impact):**
+{{impact_description}}
+
+**پیشنهاد رفع (Fix):**
+{{fix_suggestion}}
+
+```{{language}}
+{{fix_code_snippet_if_applicable}}
+```
+
+**روش تأیید (Verification):**
+{{verification_method}}
+
+---
+
+<!-- End of finding block -->
+
+---
+
+## مشاهدات / Observations
+
+<!-- Pre-existing issues noticed outside the diff scope -->
+
+{{observations_or_none}}
+
+---
+
+## نکات مثبت / Positive Notes
+
+{{positive_observations}}
+
+---
+
+## خلاصه اولویت‌ها / Priority Summary
+
+| اولویت (Severity) | تعداد (Count) |
+|-------------------|---------------|
+| P0 — بحرانی (Critical) | {{p0_count}} |
+| P1 — بالا (High) | {{p1_count}} |
+| P2 — متوسط (Medium) | {{p2_count}} |
+| P3 — پایین (Low) | {{p3_count}} |
+
+---
+
+## اقدامات پیشنهادی / Recommended Actions
+
+1. {{action_1_p0_or_p1_fix}}
+2. {{action_2}}
+3. ...
+
+---
+
+*گزارش توسط ai-dev-starter تولید شد. منابع: PR-Agent methodology (Qodo, MIT License).*
+*Report generated by ai-dev-starter. Source methodology adapted from PR-Agent (Qodo, MIT License).*