izanagi-ai 2.0.0

package/skills/software-architect.md

@@ -0,0 +1,356 @@
+# Skill: Software Architect
+
+> Version 1.0.0
+> Priority: Critical
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Responsável por projetar a arquitetura de software antes que qualquer código seja escrito. É a primeira skill ativada em projetos novos, features complexas ou refactors. Nenhuma linha de código é produzida sem passar por esta skill.
+
+---
+
+## Goals
+
+- Scalability — a arquitetura suporta crescimento sem reescrita.
+- Maintainability — qualquer dev consegue navegar e modificar.
+- Simplicity — a solução mais simples que atende os requisitos.
+- Separation of Concerns — domínios isolados, responsabilidades claras.
+- Risk Mitigation — riscos identificados e endereçados antes do código.
+
+---
+
+## Triggers
+
+| Condição | Ativa |
+|----------|-------|
+| `task == "new_project"` | ✅ Sempre |
+| `task == "new_feature"` | ✅ Se complexidade > média |
+| `task == "refactor"` | ✅ Sempre |
+| `task == "architecture_review"` | ✅ Sempre |
+| Usuário pergunta "qual arquitetura usar?" | ✅ |
+
+---
+
+## Dependencies
+
+core: [Decision Engine, Context Engine]
+skills: [Planning Engine, Risk Analyzer]
+memory: [Project Memory, Long Term Memory]
+
+---
+
+## Workflow
+
+```
+STEP 1 — Read Requirements
+    ↓
+STEP 2 — Identify Stakeholders (who uses this?)
+    ↓
+STEP 3 — Identify Risks
+    ↓
+STEP 4 — Choose Architecture Pattern
+    ↓
+STEP 5 — Design Components
+    ↓
+STEP 6 — Define Data Flow
+    ↓
+STEP 7 — Estimate Complexity
+    ↓
+STEP 8 — Generate Implementation Plan
+    ↓
+STEP 9 — Validate Against Checklist
+    ↓
+STEP 10 — Only Now → Hand off to Coding
+```
+
+---
+
+## Decision Tree
+
+```
+if project is small (< 3 modules, 1 dev):
+    → Monolith (simplicity)
+    
+elif project is medium (3-10 modules, 2-5 devs):
+    → Modular Monolith or Layered
+    
+elif project is large (>10 modules, >5 devs):
+    if domain complexity is high:
+        → Clean Architecture or Hexagonal
+    elif requires scalability:
+        → Microservices + API Gateway
+    elif event-heavy:
+        → Event-Driven + CQRS
+    
+elif project is a microservice:
+    → Hexagonal or Onion
+
+elif project is a library/package:
+    → Simple layered
+
+elif project requires real-time:
+    → Event-Driven + WebSockets
+
+else:
+    → Layered (default safe choice)
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Analyze requirements before proposing architecture.
+- ✅ Question ambiguities. Do not assume.
+- ✅ Explain trade-offs of every decision.
+- ✅ Document architectural decisions (ADRs).
+- ✅ Consider future changes (extensibility).
+- ✅ Validate against SOLID, DRY, KISS, YAGNI.
+- ✅ Produce folder structure as part of the output.
+
+### Never
+
+- ❌ Start coding without architecture.
+- ❌ Assume requirements are complete.
+- ❌ Ignore scalability (even for small projects).
+- ❌ Use microservices when monolith suffices.
+- ❌ Add technology for novelty (e.g., Kafka for a CRUD app).
+- ❌ Skip risk analysis.
+
+---
+
+## Checklists
+
+### Architecture Checklist
+
+- [ ] Requirements fully understood
+- [ ] Stakeholders identified
+- [ ] Architecture pattern chosen
+- [ ] Components defined
+- [ ] Data flow mapped
+- [ ] Folder structure generated
+- [ ] Risks documented
+- [ ] Trade-offs explained
+- [ ] SOLID validated
+- [ ] Scalability considered
+- [ ] Security considered
+- [ ] Testing strategy considered
+- [ ] Deployment strategy considered
+
+### ADR Checklist
+
+- [ ] Title and status
+- [ ] Context (why this decision?)
+- [ ] Options considered (at least 2)
+- [ ] Decision (which option and why)
+- [ ] Consequences (positive and negative)
+- [ ] Date and author
+
+---
+
+## Algorithms
+
+### Complexity Estimator
+
+```
+if modules <= 3 AND integrations <= 2:
+    complexity = "low"
+elif modules <= 8 AND integrations <= 5:
+    complexity = "medium"
+else:
+    complexity = "high"
+```
+
+### Risk Score
+
+```
+risk_score = (ambiguous_requirements * 3) 
+           + (new_team_members * 2) 
+           + (external_integrations * 2) 
+           + (unfamiliar_tech * 3)
+
+if risk_score > 10:
+    → require prototype first
+elif risk_score > 5:
+    → require design review
+else:
+    → proceed normally
+```
+
+---
+
+## Examples
+
+### Bad
+
+```
+User: Create a login.
+AI: Here is the Laravel code...
+```
+
+❌ No architecture, no planning, no risk analysis.
+
+### Good
+
+```
+User: Create a login.
+AI: 
+## Requirements Analysis
+- Auth method: JWT vs Session?
+- DB: Which database?
+- Rate limiting needed?
+
+## Architecture
+Pattern: Layered (Controller → Service → Repository)
+Components: AuthController, AuthService, UserRepository
+Data Flow: Request → Middleware → Controller → Service → Repository → DB
+
+## Folder Structure
+app/Http/Controllers/Auth/
+app/Http/Requests/Auth/
+app/Services/
+app/Repositories/
+database/migrations/
+
+## Risks
+- Token storage on client side (XSS vector)
+- Brute force on login endpoint
+
+## Mitigations
+- Use httpOnly cookies for tokens
+- Implement rate limiting
+
+## Implementation Plan
+1. Create migration
+2. Create User model
+3. Create AuthController
+4. Create AuthService
+5. Create UserRepository
+6. Implement rate limiting
+7. Write tests
+8. Review
+
+Now coding begins.
+```
+
+✅ Architecture first, code second.
+
+---
+
+## Tests
+
+### Given
+User asks to create a new feature
+
+### Expected
+The skill should:
+
+- [ ] Ask clarifying questions about requirements
+- [ ] Propose at least 2 architecture options
+- [ ] Explain trade-offs of each option
+- [ ] Generate folder structure
+- [ ] Identify risks
+- [ ] Generate implementation plan
+- [ ] Validate against SOLID
+- [ ] Not write any code yet
+
+### Test Cases
+
+| Input | Expected Behavior |
+|-------|------------------|
+| "Create a blog" | Propose monolith vs modular. Explain trade-offs. |
+| "Create a payment system" | Propose clean architecture. Identify PCI risks. |
+| "Refactor legacy code" | Identify current issues. Propose migration plan. |
+| "Add real-time chat" | Propose event-driven + WebSockets. Identify complexity. |
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Architecture produced before code | 100% | Check if code appears before architecture |
+| Risks identified per task | ≥ 2 | Count risks in output |
+| Trade-offs explained per decision | ≥ 2 | Count trade-offs in output |
+| User questions answered | 100% | Check if all user questions addressed |
+| Architecture acceptance rate | ≥ 80% | Follow-up user satisfaction |
+
+---
+
+## Evolution
+
+### Known Improvements (logged from reflections)
+
+- [ ] Add support for C4 model diagrams
+- [ ] Add deployment architecture consideration
+- [ ] Add cost estimation for cloud resources
+- [ ] Generate PlantUML diagrams automatically
+
+---
+
+## Memory Hooks
+
+```yaml
+on_activate:
+  - load: project_architecture (if exists)
+  - load: user_preferences_pattern
+
+on_complete:
+  - save: project_architecture
+  - save: decisions_log
+  - compress: if size > budget
+
+on_failure:
+  - log: architecture_error
+  - notify: Reflection Engine
+```
+
+---
+
+## Token Budget
+
+| Phase | Tokens |
+|-------|--------|
+| Requirements analysis | 200 |
+| Risk analysis | 150 |
+| Architecture proposal | 400 |
+| Folder structure | 100 |
+| Implementation plan | 200 |
+| Validation | 100 |
+| **Total** | **1150** |
+
+---
+
+## Reflection
+
+### Pre-delivery
+
+- [ ] Did I understand the requirements fully?
+- [ ] Did I consider at least 2 architecture options?
+- [ ] Did I explain trade-offs?
+- [ ] Did I identify risks?
+- [ ] Did I validate against the checklist?
+
+### Post-delivery
+
+- [ ] Did the user need to ask for clarifications?
+- [ ] Did I miss any requirement?
+- [ ] What would I do differently next time?
+- [ ] Should I update the skill based on this interaction?
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- Decision tree for architecture selection
+- Complexity estimator algorithm
+- Risk score algorithm
+- Full workflow with 10 steps
+- Integration with Planning Engine

package/skills/solid-validator.md

@@ -0,0 +1,332 @@
+# Skill: SOLID Validator
+
+> Version 1.0.0
+> Priority: High
+> Dependencies: Clean Code Validator, Software Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+The SOLID Validator checks every class and module against the five SOLID principles. It identifies violations, explains why they are problematic, and suggests specific refactoring techniques to resolve them.
+
+---
+
+## Goals
+
+- Validate every class against all 5 SOLID principles.
+- Identify violations with specific evidence.
+- Explain why the violation is harmful.
+- Suggest specific refactoring to resolve it.
+- Track SOLID adherence over time.
+
+---
+
+## Triggers
+
+| Condition | Action |
+|-----------|--------|
+| After any new class | SOLID validation |
+| After code review | Deep SOLID pass |
+| `task == "solid"` or `task == "validate"` | Full SOLID audit |
+| Before refactoring | Baseline SOLID score |
+
+---
+
+## SRP — Single Responsibility Principle
+
+> A class should have only one reason to change.
+
+### Checks
+
+- [ ] Class name describes a single responsibility
+- [ ] Class has ≤ 3 public methods (if service/controller)
+- [ ] All methods operate on the same level of abstraction
+- [ ] No method mixes business logic with infrastructure concerns
+
+### Violation Example
+
+```php
+// ❌ Violates SRP — Controller handles HTTP, business logic, and email
+class UserController {
+    public function store(Request $request) {
+        $validated = $request->validate([...]);
+        $user = User::create($validated);              // Business logic
+        Mail::to($user)->send(new WelcomeEmail($user)); // Email logic
+        Log::info('User created: ' . $user->id);        // Logging logic
+        return response()->json($user, 201);            // HTTP logic
+    }
+}
+
+// ✅ SRP Compliant
+class UserController {
+    public function __construct(
+        private UserService $userService
+    ) {}
+
+    public function store(StoreUserRequest $request): JsonResponse {
+        $user = $this->userService->create($request->validated());
+        return response()->json($user, 201);
+    }
+}
+
+// UserService handles business logic + coordination
+class UserService {
+    public function create(array $data): User {
+        $user = User::create($data);
+        Event::dispatch(new UserRegistered($user));
+        return $user;
+    }
+}
+```
+
+---
+
+## OCP — Open/Closed Principle
+
+> Software entities should be open for extension but closed for modification.
+
+### Checks
+
+- [ ] New behavior is added via extension, not modification
+- [ ] Switch/if-else chains use polymorphism instead
+- [ ] Abstract classes or interfaces define extension points
+- [ ] Strategy pattern used for varying behavior
+
+### Violation Example
+
+```php
+// ❌ Violates OCP — adding new notification type requires modifying this class
+class NotificationService {
+    public function send(string $type, string $message): void {
+        if ($type === 'email') { ... }
+        elseif ($type === 'sms') { ... }
+        elseif ($type === 'slack') { ... }
+    }
+}
+
+// ✅ OCP Compliant
+interface NotificationChannel {
+    public function send(string $message): void;
+}
+
+class EmailChannel implements NotificationChannel { ... }
+class SmsChannel implements NotificationChannel { ... }
+class SlackChannel implements NotificationChannel { ... }
+
+class NotificationService {
+    public function __construct(
+        /** @var NotificationChannel[] */
+        private array $channels
+    ) {}
+
+    public function send(string $message): void {
+        foreach ($this->channels as $channel) {
+            $channel->send($message);
+        }
+    }
+}
+```
+
+---
+
+## LSP — Liskov Substitution Principle
+
+> Subtypes must be substitutable for their base types.
+
+### Checks
+
+- [ ] Subclass does not weaken preconditions
+- [ ] Subclass does not strengthen postconditions
+- [ ] Subclass does not throw new exception types
+- [ ] Subclass preserves invariants of parent
+- [ ] No "is-a" violations (Square extends Rectangle)
+
+### Violation Example
+
+```php
+// ❌ Violates LSP — Square changes behavior of setWidth/setHeight
+class Rectangle {
+    public function setWidth(int $w): void { $this->width = $w; }
+    public function setHeight(int $h): void { $this->height = $h; }
+    public function getArea(): int { return $this->width * $this->height; }
+}
+
+class Square extends Rectangle {
+    public function setWidth(int $w): void {
+        $this->width = $w;
+        $this->height = $w;  // Violates LSP — changing height too
+    }
+}
+
+// ✅ LSP Compliant — use a Shape interface instead
+interface Shape {
+    public function getArea(): int;
+}
+class Rectangle implements Shape { ... }
+class Square implements Shape { ... }
+```
+
+---
+
+## ISP — Interface Segregation Principle
+
+> Clients should not be forced to depend on interfaces they do not use.
+
+### Checks
+
+- [ ] Interfaces are small and focused
+- [ ] No "fat" interfaces with unrelated methods
+- [ ] Classes don't implement methods they don't need
+- [ ] Multiple specific interfaces over one general interface
+
+### Violation Example
+
+```php
+// ❌ Violates ISP — UserService must implement sendEmail
+interface UserOperations {
+    public function create(array $data): User;
+    public function update(int $id, array $data): User;
+    public function sendEmail(int $userId, string $template): void;
+    public function exportCsv(): string;
+}
+
+// ✅ ISP Compliant
+interface UserRepository {
+    public function create(array $data): User;
+    public function update(int $id, array $data): User;
+}
+
+interface EmailService {
+    public function send(int $userId, string $template): void;
+}
+
+interface ExportService {
+    public function exportCsv(): string;
+}
+```
+
+---
+
+## DIP — Dependency Inversion Principle
+
+> Depend on abstractions, not concretions.
+
+### Checks
+
+- [ ] High-level modules don't depend on low-level modules
+- [ ] Both depend on abstractions (interfaces/abstract classes)
+- [ ] No `new` keyword in constructors (inject dependencies)
+- [ ] No static method calls to concrete classes
+- [ ] Dependency injection used throughout
+
+### Violation Example
+
+```php
+// ❌ Violates DIP — depends on concrete MySQLRepository
+class UserService {
+    private MySQLRepository $repo;
+
+    public function __construct() {
+        $this->repo = new MySQLRepository();  // Tight coupling
+    }
+}
+
+// ✅ DIP Compliant
+class UserService {
+    public function __construct(
+        private UserRepositoryInterface $repo  // Depends on abstraction
+    ) {}
+}
+
+// Binding in service provider
+$this->app->bind(UserRepositoryInterface::class, MySQLRepository::class);
+```
+
+---
+
+## SOLID Score
+
+```yaml
+solid_report:
+  class: "app/Services/OrderService.php"
+  overall_score: 3.8 / 5.0
+  
+  principles:
+    srp:
+      score: 3 / 5
+      violations: ["Mixes validation, pricing, and notification"]
+      passed_checks: 2 / 4
+      
+    ocp:
+      score: 5 / 5
+      violations: []
+      passed_checks: 4 / 4
+      
+    lsp:
+      score: 5 / 5
+      violations: []
+      passed_checks: 4 / 4
+      
+    isp:
+      score: 3 / 5
+      violations: ["UserService implements EmailNotifiableInterface"]
+      passed_checks: 3 / 4
+      
+    dip:
+      score: 3 / 5
+      violations: ["New MySQLRepository() in constructor"]
+      passed_checks: 3 / 5
+  
+  recommendations:
+    - principle: srp
+      action: "Extract OrderValidator, OrderPricing, OrderNotification classes"
+      effort: "medium"
+    - principle: dip
+      action: "Inject UserRepositoryInterface instead of instantiating MySQLRepository"
+      effort: "low"
+```
+
+---
+
+## Rules
+
+### Always
+
+- ✅ Check all 5 principles on every class.
+- ✅ Explain why each violation is harmful.
+- ✅ Suggest specific refactoring for each violation.
+- ✅ Score each principle individually.
+- ✅ Prioritize SRP and DIP (most commonly violated).
+
+### Never
+
+- ❌ Claim SOLID compliance without checking all 5.
+- ❌ Suggest refactoring that introduces new violations.
+- ❌ Ignore violations because "it works fine now".
+- ❌ Apply SOLID dogmatically when it adds accidental complexity.
+
+---
+
+## Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|---------------|
+| Average SOLID score | ≥ 4.0 / 5 | Score per class, average |
+| SRP compliance | ≥ 80% | Classes with single responsibility |
+| DIP compliance | ≥ 90% | Classes using DI / total classes |
+| Violations per class | ≤ 1 | Average violations per class |
+
+---
+
+## Changelog
+
+### 1.0.0 (2026-07-17)
+
+- Initial release
+- All 5 SOLID principles with checklists
+- Before/after examples for each principle
+- SOLID score report in YAML
+- Violation explanations with "why harmful"
+- Refactoring recommendations per violation