ai-dev-starter 0.0.0-stage → 1.0.0

package/workflows/architecture-review.md

@@ -0,0 +1,186 @@
+# Workflow: Architecture Review
+
+> **Purpose:** Evaluate the structural health, design quality, and scalability of the codebase.
+> **Authorization:** Read-only. No file writes.
+> **Scope:** Structural patterns, not code-level defects (use Code Review for those).
+
+---
+
+## Trigger
+
+- "architecture review", "design review", "evaluate structure"
+- "بررسی معماری", "ارزیابی ساختار"
+
+---
+
+## Required Context
+
+1. `core/agent-principles.md`
+2. `.agents/project-context.md`
+
+---
+
+## Execution Steps
+
+### Step 1 — Map the Structure
+
+```bash
+# High-level directory tree
+find . -maxdepth 3 -not -path "*/.git/*" -not -path "*/node_modules/*" \
+  -not -path "*/vendor/*" -not -path "*/__pycache__/*" | sort | head -100
+
+# Count files by type
+find . -name "*.php" -not -path "*/vendor/*" | wc -l
+find . -name "*.ts" -not -path "*/node_modules/*" | wc -l
+
+# Largest files (complexity indicator)
+find . -name "*.php" -not -path "*/vendor/*" | xargs wc -l 2>/dev/null | sort -rn | head -20
+
+# Dependency manifest
+cat composer.json 2>/dev/null || cat package.json 2>/dev/null
+```
+
+### Step 2 — Identify the Architectural Pattern
+
+Determine which pattern(s) the project uses:
+- **MVC** (Laravel, Ruby on Rails, Django).
+- **Clean Architecture / Hexagonal** (domain, application, infrastructure layers).
+- **Domain-Driven Design** (bounded contexts, aggregates).
+- **Microservices** (multiple services with their own data stores).
+- **Monolith with modules**.
+- **Component-based** (React, Vue, Angular with feature directories).
+
+Identify by reading:
+- Directory structure.
+- Base classes and interfaces.
+- Naming conventions.
+- Dependency injection setup.
+
+### Step 3 — Evaluate Layer Boundaries
+
+For each identified layer boundary, check:
+
+#### Controllers / Route Handlers
+- Do they contain business logic? (Anti-pattern: fat controllers)
+- Do they directly query the database? (Anti-pattern: bypassing service layer)
+- Do they handle authorization? (Expected: middleware or policy)
+
+```bash
+# Check controller file sizes
+wc -l app/Http/Controllers/*.php | sort -rn | head -10
+
+# Look for direct DB calls in controllers
+grep -rn "DB::\|->where\|->find\|->create" --include="*.php" app/Http/Controllers/ | head -10
+```
+
+#### Service / Use Case Layer
+- Is business logic centralized here?
+- Are services reusable across controllers and jobs?
+
+#### Data Layer
+- Are repositories or Eloquent models the data access mechanism?
+- Is there a consistent pattern?
+
+#### Frontend (if applicable)
+- Are components responsible for data fetching? (Acceptable in React, problematic if mixed with business logic)
+- Is state management centralized appropriately?
+
+### Step 4 — Evaluate Coupling and Cohesion
+
+**Tight Coupling Signals:**
+```bash
+# Classes importing many other classes
+grep -rn "^use " --include="*.php" app/Http/Controllers/ | awk '{print NF}' | sort -rn | head -10
+
+# Circular dependencies
+# (Manual inspection: Class A imports B, B imports A)
+grep -rn "^use App\\" --include="*.php" app/Services/ | head -20
+```
+
+**Low Cohesion Signals:**
+- Classes with many unrelated public methods.
+- Files > 500 lines.
+- Controllers with methods for unrelated entities.
+
+### Step 5 — Evaluate Dependencies
+
+```bash
+# Third-party dependencies
+cat composer.json | grep -A100 '"require"' | grep -v "php\|ext-"
+# or
+cat package.json | grep -A100 '"dependencies"'
+```
+
+Assess:
+- Are dependencies actively maintained?
+- Are there multiple packages solving the same problem?
+- Are there unnecessary dependencies for simple tasks?
+
+### Step 6 — Evaluate Scalability
+
+Consider:
+- **Database:** Are there single points of contention (table locks, unindexed joins)?
+- **State:** Is application state stored in-process (limits horizontal scaling)?
+- **Queues:** Are heavy operations async?
+- **Caching:** Is expensive computation cached?
+
+### Step 7 — Generate Report
+
+```markdown
+## Architecture Review Report
+
+**Project:** <name>
+**Pattern:** <identified pattern>
+**Date:** YYYY-MM-DD
+
+---
+
+### Executive Summary
+<3–5 sentences: overall health, main strengths, main concerns>
+
+---
+
+### Strengths
+- <What the architecture does well>
+
+---
+
+### Concerns
+
+#### [P1] Fat Controllers — Business Logic Leaking from Service Layer
+**Evidence:** `OrderController.php` (342 lines) contains pricing calculations, inventory checks, and email sending.
+**Impact:** Logic cannot be reused, cannot be unit tested in isolation, and grows indefinitely.
+**Recommendation:** Extract to `OrderService` with clearly named methods.
+
+---
+
+### Recommendations
+1. <Highest priority structural improvement>
+2. ...
+
+---
+
+### Dependency Health
+| Package | Status | Concern |
+|---------|--------|---------|
+| `laravel/framework` | Current | None |
+| `abandoned/package` | Abandoned | Replace with X |
+```
+
+---
+
+## Completion Criteria
+
+- Project structure mapped and pattern identified.
+- Layer boundaries evaluated.
+- Coupling and cohesion assessed.
+- Dependencies reviewed.
+- Findings are structural, not code-level.
+
+---
+
+## Limitations
+
+- Cannot evaluate runtime behavior or actual performance.
+- Cannot evaluate team conventions or processes.
+- Cannot assess security of infrastructure or deployment.

package/workflows/bug-fix.md

@@ -0,0 +1,149 @@
+# Workflow: Bug Fix
+
+> **Purpose:** Investigate a reported bug, identify root cause, and implement a minimal fix.
+> **Authorization:** Read files freely. Write only to fix-related files. Run tests with user awareness.
+> **Auto-commit:** Never.
+
+---
+
+## Trigger
+
+User reports a bug with any of:
+- Error message, stack trace, or log output.
+- Description of unexpected behavior.
+- Test failure name.
+- "باگ", "خطا", "bug fix", "fix this error"
+
+---
+
+## Required Context
+
+1. `core/agent-principles.md`
+2. `core/safety-policy.md`
+3. `.agents/project-context.md`
+
+---
+
+## Execution Steps
+
+### Step 1 — Understand the Bug Report
+
+Ask for clarification only if the minimum required information is absent:
+- **What is the unexpected behavior?** (or error message / stack trace)
+- **What was the expected behavior?**
+- **How to reproduce?** (steps, URL, command, test name)
+
+If the user has provided a stack trace or error message, proceed without asking.
+
+### Step 2 — Establish Evidence
+
+```bash
+# Check git status to understand current state
+git status
+git log --oneline -10
+
+# Search for the error message in source
+grep -rn "ErrorMessage\|ExceptionClass" --include="*.php" --include="*.ts" src/
+
+# Find the failing test if applicable
+grep -rn "test_name\|it('description'" tests/ --include="*.php" --include="*.ts"
+```
+
+Do not claim to have reproduced the bug unless you have executed the reproduction steps and observed the failure.
+
+### Step 3 — Identify Root Cause
+
+Trace the execution path:
+1. Entry point (route, CLI command, event handler).
+2. Each function call in the stack.
+3. The specific line that produces the incorrect behavior.
+4. The underlying condition that triggers it.
+
+Document the root cause hypothesis before proposing a fix.
+
+### Step 4 — Identify Affected Code
+
+```bash
+# Find all usages of the affected function/class
+grep -rn "functionName\|ClassName" --include="*.php" src/ | grep -v "\.git"
+
+# Find related tests
+find tests/ -name "*Test*" | xargs grep -l "ClassName" 2>/dev/null
+```
+
+Determine:
+- Minimum scope of the fix (single line, function, class).
+- Whether the fix could affect other callers.
+- Whether existing tests cover the fix path.
+
+### Step 5 — Propose Fix
+
+Present the fix plan to the user before implementing:
+
+```markdown
+## Proposed Fix
+
+**Root Cause:** <one sentence>
+
+**Fix Scope:** `path/to/file.php` line 42–55
+
+**Change:**
+```php
+// Before
+$result = $value / $count;
+
+// After (handles zero count)
+$result = $count > 0 ? $value / $count : 0;
+```
+
+**Side Effects:** None — this function is only called from X and Y.
+
+**Tests to run:** `php artisan test --filter=TestClassName`
+
+Shall I implement this fix?
+```
+
+**Wait for user approval before modifying any files.**
+
+### Step 6 — Implement
+
+After approval:
+1. Apply the minimal change.
+2. Do not reformat unrelated code.
+3. Do not rename unrelated variables.
+4. Do not add unrelated improvements.
+
+### Step 7 — Run Tests
+
+```bash
+# Run the relevant tests (not the full suite unless needed)
+php artisan test --filter=TestName
+# or
+npm test -- --testPathPattern=ComponentName
+# or
+pytest tests/test_module.py::test_function
+```
+
+Report the actual test output. Do not claim tests passed without evidence.
+
+### Step 8 — Explain the Change
+
+Provide:
+1. Summary of what changed and why.
+2. Test results (actual output).
+3. Any follow-up concerns (related code that may have the same bug).
+
+---
+
+## Completion Criteria
+
+- Root cause identified and documented.
+- Minimal fix implemented (no scope creep).
+- Relevant tests run and results reported.
+- User explicitly approved the fix before implementation.
+
+---
+
+## Boundaries
+
+Do not fix unrelated issues encountered during investigation. Note them separately as observations.

package/workflows/code-review.md

@@ -0,0 +1,189 @@
+# Workflow: Code Review
+
+> **Purpose:** Analyze Git changes and produce a structured, evidence-based review report.
+> **Authorization:** Read-only. No file writes. No commits.
+> **Report Language:** See project-context.md → `report_language` (default: Persian).
+
+---
+
+## Trigger
+
+User says any of:
+- "review my code", "review my changes", "code review"
+- "بررسی کد", "ریویو کن"
+- Provides a branch name or PR URL to review.
+
+---
+
+## Required Context
+
+Before starting, load:
+1. `core/agent-principles.md`
+2. `core/git-analysis.md`
+3. `core/review-methodology.md`
+4. `core/severity-levels.md`
+5. `.agents/project-context.md` (if present)
+
+---
+
+## Execution Steps
+
+### Step 1 — Orient
+```bash
+# Confirm we are in a git repository
+git rev-parse --show-toplevel
+
+# Get current branch
+git branch --show-current
+
+# Determine comparison base
+git remote show origin | grep "HEAD branch"
+# Or: git symbolic-ref refs/remotes/origin/HEAD --short
+```
+
+If the user specified a branch or base, use that. Otherwise use the auto-detected base.
+
+### Step 2 — Enumerate Changes
+```bash
+# Committed changes
+git diff --name-status origin/main...HEAD
+git log origin/main..HEAD --oneline
+
+# Staged changes
+git diff --cached --name-status
+
+# Unstaged changes
+git diff --name-status
+```
+
+Build the change summary: branch, base, file list, commit count.
+
+### Step 3 — Read Diffs
+```bash
+git diff origin/main...HEAD
+```
+
+Read the full diff. For large diffs (>500 lines), process file by file.
+
+### Step 4 — Read Affected Files
+
+For each modified file:
+1. Read the file to understand the full context of changed lines.
+2. Identify what functions, classes, or modules are affected.
+3. Note imports and dependencies relevant to the changes.
+
+Do not read files that have no changes unless they are critical dependencies.
+
+### Step 5 — Gather Supporting Context
+
+For each finding candidate:
+- Read related files (e.g., models, validators, tests, routes).
+- Read migration files if schema changes are present.
+- Read test files covering the changed code.
+
+```bash
+# Find tests for a changed file
+find . -name "*.test.*" -o -name "*.spec.*" -o -name "*Test.php" | \
+  xargs grep -l "ClassName\|functionName" 2>/dev/null | head -10
+
+# Find routes
+grep -rn "Route::" routes/ 2>/dev/null | grep "endpoint"
+```
+
+### Step 6 — Analyze
+
+Apply review dimensions from `core/review-methodology.md` in this order:
+1. Correctness and Business Logic
+2. Security
+3. Data Integrity
+4. Performance
+5. Architecture
+6. Test Coverage
+7. Code Quality
+
+For each candidate finding, complete the verification checklist before recording it.
+
+### Step 7 — Verify Findings
+
+For every finding:
+- [ ] The issue exists in newly added lines (not pre-existing).
+- [ ] I can point to the exact file, line, and code.
+- [ ] I can describe the realistic impact scenario.
+- [ ] I checked for mitigating factors (middleware, validators, tests).
+- [ ] I can suggest a concrete fix.
+
+Discard findings that fail this checklist.
+
+### Step 8 — Generate Report
+
+Produce the report in the project's configured `report_language`.
+
+Use the report template from `templates/review-report.md`.
+
+---
+
+## Report Template
+
+```markdown
+## گزارش بررسی کد / Code Review Report
+
+**شاخه (Branch):** `feature/xyz` → `main`
+**تعداد فایل‌های تغییریافته:** N
+**تعداد کامیت‌ها:** M
+**تاریخ:** YYYY-MM-DD
+
+---
+
+### خلاصه تغییرات (Walkthrough)
+<2–4 جمله توضیح می‌دهند که این تغییر چه می‌کند>
+
+---
+
+### یافته‌ها (Findings)
+
+#### [P0 — بحرانی] <عنوان>
+**فایل:** `path/to/file.php` خط ۴۲
+
+**مشکل:** <توضیح مشکل>
+
+**شواهد:**
+```php
+// کد مشکل‌دار
+```
+
+**تأثیر:** <توضیح واقع‌گرایانه>
+
+**پیشنهاد رفع:** <راه‌حل مشخص>
+
+**روش تأیید:** <چگونه مطمئن شویم که مشکل رفع شد>
+
+---
+
+### مشاهدات (Observations)
+<مشکلات موجود قبلاً که خارج از محدوده تغییر هستند>
+
+---
+
+### نکات مثبت (Positive Notes)
+<چه چیزهایی خوب انجام شده>
+```
+
+---
+
+## Completion Criteria
+
+- All changed files have been reviewed.
+- Findings are ordered P0 → P3.
+- Each finding has file, line, evidence, impact, and fix.
+- No speculative findings without code-level evidence.
+- Report language matches project configuration.
+
+---
+
+## Limitations
+
+This workflow cannot:
+- Access external CI/CD results.
+- Run tests automatically.
+- Review changes in external repositories without clone access.
+- Detect runtime behaviors not visible in code.

package/workflows/feature-development.md

@@ -0,0 +1,154 @@
+# Workflow: Feature Development
+
+> **Purpose:** Implement a new feature following the project's existing architecture and conventions.
+> **Authorization:** Read freely. Write incrementally within authorized scope.
+> **Auto-commit:** Never.
+
+---
+
+## Trigger
+
+User requests a new feature:
+- "add feature X", "implement Y", "build Z"
+- "اضافه کن", "پیاده‌سازی کن", "بساز"
+
+---
+
+## Required Context
+
+1. `core/agent-principles.md`
+2. `core/safety-policy.md`
+3. `.agents/project-context.md`
+4. Relevant standards from `standards/` based on project tech stack.
+
+---
+
+## Execution Steps
+
+### Step 1 — Understand Requirements
+
+Before writing a single line of code, confirm:
+- **What** the feature does (user-facing behavior).
+- **Who** uses it (user role, API consumer, background job).
+- **Where** it integrates with existing functionality.
+- **What it must not do** (constraints, out-of-scope items).
+
+If the requirements are ambiguous, ask targeted questions. Maximum 3 questions at a time.
+
+### Step 2 — Inspect Existing Architecture
+
+```bash
+# Understand project structure
+ls -la
+cat composer.json  # or package.json
+
+# Find similar existing features
+grep -rn "similarPattern\|relatedFeature" src/ --include="*.php" -l | head -10
+
+# Understand routing conventions
+cat routes/web.php  # Laravel
+cat routes/api.php
+# or
+find . -name "*.routes.*" -not -path "*/node_modules/*" | head -5
+
+# Understand data models
+ls app/Models/ 2>/dev/null || ls src/entities/ 2>/dev/null || echo "Check project structure"
+
+# Check test conventions
+ls tests/ 2>/dev/null; ls __tests__/ 2>/dev/null; ls spec/ 2>/dev/null
+```
+
+Identify:
+- The project's layering pattern (MVC, Clean Architecture, etc.).
+- Naming conventions from existing code.
+- Reusable components (services, repositories, hooks, utilities).
+- The testing framework and test file location conventions.
+
+### Step 3 — Present Implementation Plan
+
+Before writing code, present a plan:
+
+```markdown
+## Implementation Plan: <Feature Name>
+
+**Approach:** <One paragraph describing the technical approach>
+
+**Files to create:**
+- `app/Http/Controllers/FeatureController.php` — HTTP handler
+- `app/Services/FeatureService.php` — Business logic
+- `app/Models/Feature.php` — Data model (if new)
+- `database/migrations/xxxx_create_features_table.php` — Schema
+- `tests/Feature/FeatureTest.php` — Feature tests
+
+**Files to modify:**
+- `routes/api.php` — Add new endpoints
+- `app/Providers/AppServiceProvider.php` — Register service (if needed)
+
+**Dependencies introduced:** None
+
+**Breaking changes:** None
+
+**Estimated scope:** Medium
+
+Shall I proceed with this plan?
+```
+
+**Wait for user approval before writing any files.**
+
+### Step 4 — Implement Incrementally
+
+Implement one logical unit at a time:
+1. Database schema / migration (if needed).
+2. Data model.
+3. Business logic layer (service, use case).
+4. HTTP / API layer (controller, route).
+5. Frontend (component, page, hook) if applicable.
+6. Tests.
+
+After each unit, describe what was done and what comes next.
+
+### Step 5 — Follow Existing Conventions
+
+- Match the naming patterns from similar existing code (do not invent new patterns).
+- Match the import style.
+- Match the error handling style.
+- Match the validation approach.
+- Do not introduce new linting rules or formatting changes.
+
+### Step 6 — Write Tests
+
+Identify what must be tested:
+- Happy path.
+- Expected failure cases (validation errors, not-found, unauthorized).
+- Edge cases specific to this feature.
+
+Write tests compatible with the project's existing testing setup.
+
+### Step 7 — Self-Review
+
+Before declaring completion, run the Code Review workflow mentally on your own changes:
+- Security: Are inputs validated and sanitized?
+- Authorization: Are endpoints protected?
+- Data integrity: Are mutations wrapped in transactions?
+- Performance: Any N+1 queries introduced?
+
+### Step 8 — Run Tests
+
+```bash
+# Run only the new feature tests
+php artisan test --filter=FeatureName
+# or
+npm test -- --testPathPattern=FeatureName
+```
+
+Report actual test output.
+
+---
+
+## Completion Criteria
+
+- Requirements confirmed before implementation.
+- Plan approved by user before writing files.
+- Implementation follows existing conventions.
+- Tests written and passing.
+- No unrelated code changed.