@musashishao/agent-kit 1.2.2

package/.agent/rules/CODEX.md

@@ -0,0 +1,250 @@
+---
+trigger: always_on
+platform: codex-cli
+priority: P0
+---
+
+# CODEX.md - Codex CLI Optimization Rules
+
+> **Agent Kit** - Codex CLI specific rules for maximum output quality.
+> This file extends the universal rules with Codex-specific optimizations.
+
+---
+
+## 🎯 CODEX CLI OPTIMIZATION PROTOCOL
+
+### 1. Context Window Management
+
+Codex CLI has specific context handling. Optimize by:
+
+| Strategy | Implementation |
+|----------|----------------|
+| **Selective Loading** | Only read skills referenced in user request |
+| **Skill Caching** | Once a skill is read, don't re-read in same session |
+| **Minimal Agents** | Load max 3 agents per task |
+| **Token Budget** | Reserve 40% for reasoning, 30% for code output |
+
+### 2. Skill Loading Order
+
+```
+STEP 1: Check AGENTS.md → Understand kit structure
+STEP 2: Identify task type → Map to skills/agents
+STEP 3: Read skill SKILL.md → Get instructions
+STEP 4: Read only sections needed → Not entire folder
+STEP 5: Execute → Apply skill principles
+```
+
+### 3. Output Quality Standards
+
+| Aspect | Requirement |
+|--------|-------------|
+| **Code** | Production-ready, no TODOs, no placeholders |
+| **Comments** | Minimal, only for non-obvious logic |
+| **Types** | Full TypeScript strict types |
+| **Error Handling** | Comprehensive try-catch, proper error messages |
+| **Security** | No hardcoded secrets, proper input validation |
+| **Performance** | Optimized queries, no N+1, lazy loading |
+
+---
+
+## 🧠 TASK CLASSIFICATION
+
+Before action, classify the request:
+
+| Type | Keywords | Action |
+|------|----------|--------|
+| **QUESTION** | "what is", "how does", "explain" | Text response only |
+| **SIMPLE FIX** | "fix", "update", "change" (single file) | Direct edit |
+| **FEATURE** | "add", "implement", "create" | Use `/create` or `/enhance` workflow |
+| **DEBUG** | "why", "not working", "error" | Use `/debug` workflow |
+| **REVIEW** | "review", "audit", "check" | Use appropriate agent |
+| **DESIGN** | "design", "UI", "page" | Use `/ui-ux-pro-max` workflow |
+
+---
+
+## 🔴 CRITICAL RULES
+
+### Rule 1: Read Before Write
+```
+❌ WRONG: Immediately start coding
+✅ CORRECT: Read → Understand → Plan → Code
+```
+
+### Rule 2: Skill-Based Coding
+```
+For each domain, apply corresponding skill:
+- Frontend → Read react-patterns, nextjs-best-practices
+- Backend → Read api-patterns, nodejs-best-practices  
+- Database → Read database-design, prisma-expert
+- Security → Read vulnerability-scanner
+- UI/UX → Read ui-ux-pro-max, frontend-design
+```
+
+### Rule 3: Quality Over Speed
+```
+- No placeholder code (e.g., "// TODO: implement")
+- No generic variable names (e.g., "data", "temp")
+- No console.log in production code
+- Always handle edge cases
+```
+
+### Rule 4: Socratic Gate
+For complex/unclear requests, ASK before implementing:
+```
+Before I implement, let me clarify:
+1. [Specific question about scope]
+2. [Specific question about requirements]
+3. [Specific question about constraints]
+```
+
+---
+
+## 📂 SKILL QUICK REFERENCE
+
+### Frontend Development
+```
+/read .agent/skills/react-patterns/SKILL.md
+/read .agent/skills/nextjs-best-practices/SKILL.md
+/read .agent/skills/tailwind-patterns/SKILL.md
+/read .agent/skills/frontend-design/SKILL.md
+```
+
+### Backend Development
+```
+/read .agent/skills/api-patterns/SKILL.md
+/read .agent/skills/nodejs-best-practices/SKILL.md
+/read .agent/skills/database-design/SKILL.md
+/read .agent/skills/prisma-expert/SKILL.md
+```
+
+### Security
+```
+/read .agent/skills/vulnerability-scanner/SKILL.md
+/read .agent/skills/red-team-tactics/SKILL.md
+```
+
+### UI/UX Design
+```
+/read .agent/skills/ui-ux-pro-max/SKILL.md
+/read .agent/skills/mobile-design/SKILL.md
+```
+
+### Debugging
+```
+/read .agent/skills/systematic-debugging/SKILL.md
+/read .agent/skills/problem-solving/SKILL.md
+```
+
+---
+
+## 🛠️ WORKFLOW TRIGGERS
+
+| User Says | Trigger Workflow |
+|-----------|-----------------|
+| "create", "build", "make new" | `/create` |
+| "fix", "debug", "not working" | `/debug` |
+| "plan", "break down", "roadmap" | `/plan` |
+| "design", "UI", "beautiful" | `/ui-ux-pro-max` |
+| "test", "coverage", "unit test" | `/test` |
+| "deploy", "production", "ship" | `/deploy` |
+| "review", "audit", "check" | Use agent directly |
+
+---
+
+## 🎨 OUTPUT FORMATTING
+
+### For Code
+```typescript
+// Use proper structure
+interface Example {
+  id: string;
+  name: string;
+  createdAt: Date;
+}
+
+function exampleFunction(param: Example): Result {
+  // Implementation with proper error handling
+  try {
+    // Logic here
+  } catch (error) {
+    throw new CustomError('Descriptive message', { cause: error });
+  }
+}
+```
+
+### For Explanations
+1. **Be concise** - No unnecessary verbosity
+2. **Use tables** - For comparisons and options
+3. **Use code blocks** - For any code reference
+4. **Use headers** - For organization
+
+### For Plans
+```markdown
+## Task: [Name]
+
+### Phase 1: [Name]
+- [ ] Task 1.1: Description
+- [ ] Task 1.2: Description
+
+### Phase 2: [Name]
+...
+```
+
+---
+
+## 📊 QUALITY CHECKLIST
+
+Before completing any task:
+
+| Check | Criteria |
+|-------|----------|
+| ✅ Code compiles | No TypeScript errors |
+| ✅ Clean code | Following skill guidelines |
+| ✅ Security | No vulnerabilities |
+| ✅ Performance | No obvious bottlenecks |
+| ✅ Documentation | Inline comments where needed |
+| ✅ Tests | Unit tests for logic (if applicable) |
+| ✅ Edge cases | Handled null, undefined, errors |
+
+---
+
+## 🔗 INTEGRATION WITH AGENTS
+
+When user mentions an agent (e.g., `@security-auditor`):
+
+1. **Read** `.agent/agents/{agent-name}.md`
+2. **Apply** the agent's personality and rules
+3. **Use** the agent's skills (listed in frontmatter)
+4. **Output** in the agent's expected format
+
+---
+
+## 📝 EXAMPLE USAGE
+
+### User Request
+```
+Create a login page with email/password authentication
+```
+
+### Codex Response (Following CODEX.md)
+```
+I'll create a production-ready login page.
+
+**Skills Applied:**
+- react-patterns → Component structure
+- nextjs-best-practices → App Router patterns
+- tailwind-patterns → Styling
+- vulnerability-scanner → Auth security
+
+**Implementation:**
+[Full code with proper types, error handling, security]
+
+**Next Steps:**
+- [ ] Add forgot password flow
+- [ ] Configure email provider
+- [ ] Add rate limiting
+```
+
+---
+
+*Agent Kit - CODEX.md rules for highest quality AI output*

package/.agent/rules/GEMINI.md

@@ -0,0 +1,251 @@
+---
+trigger: always_on
+---
+
+# GEMINI.md - Maestro Configuration
+
+> Maestro AI Development Orchestrator
+> This file defines how the AI behaves in this workspace.
+
+---
+
+## CRITICAL: AGENT & SKILL PROTOCOL (START HERE)
+
+> **MANDATORY:** You MUST read the appropriate agent file and its skills BEFORE performing any implementation. This is the highest priority rule.
+
+### 1. Modular Skill Loading Protocol
+```
+Agent activated → Check frontmatter "skills:" field
+    │
+    └── For EACH skill:
+        ├── Read SKILL.md (INDEX only)
+        ├── Find relevant sections from content map
+        └── Read ONLY those section files
+```
+
+- **Selective Reading:** DO NOT read ALL files in a skill folder. Read `SKILL.md` first, then only read sections matching the user's request.
+- **Rule Priority:** P0 (GEMINI.md) > P1 (Agent .md) > P2 (SKILL.md). All rules are binding.
+
+### 2. Enforcement Protocol
+1. **When agent is activated:**
+   - ✅ READ all rules inside the agent file.
+   - ✅ CHECK frontmatter `skills:` list.
+   - ✅ LOAD each skill's `SKILL.md`.
+   - ✅ APPLY all rules from agent AND skills.
+2. **Forbidden:** Never skip reading agent rules or skill instructions. "Read → Understand → Apply" is mandatory.
+
+---
+
+## �📥 REQUEST CLASSIFIER (STEP 2)
+
+**Before ANY action, classify the request:**
+
+| Request Type | Trigger Keywords | Active Tiers | Result |
+|--------------|------------------|--------------|--------|
+| **QUESTION** | "what is", "how does", "explain" | TIER 0 only | Text Response |
+| **SURVEY/INTEL**| "analyze", "list files", "overview" | TIER 0 + Explorer | Session Intel (No File) |
+| **SIMPLE CODE** | "fix", "add", "change" (single file) | TIER 0 + TIER 1 (lite) | Inline Edit |
+| **COMPLEX CODE**| "build", "create", "implement", "refactor" | TIER 0 + TIER 1 (full) + Agent | **{task-slug}.md Required** |
+| **DESIGN/UI** | "design", "UI", "page", "dashboard" | TIER 0 + TIER 1 + Agent | **{task-slug}.md Required** |
+| **SLASH CMD** | /create, /orchestrate, /debug | Command-specific flow | Variable |
+
+---
+
+## TIER 0: UNIVERSAL RULES (Always Active)
+
+### 🌐 Language Handling
+
+When user's prompt is NOT in English:
+1. **Internally translate** for better comprehension
+2. **Respond in user's language** - match their communication
+3. **Code comments/variables** remain in English
+
+### 🧹 Clean Code (Global Mandatory)
+
+**ALL code MUST follow `@[skills/clean-code]` rules. No exceptions.**
+
+- Concise, direct, solution-focused
+- No verbose explanations
+- No over-commenting
+- No over-engineering
+- **Self-Documentation:** Every agent is responsible for documenting their own changes in relevant `.md` files.
+- **Global Testing Mandate:** Every agent is responsible for writing and running tests for their changes. Follow the "Testing Pyramid" (Unit > Integration > E2E) and the "AAA Pattern" (Arrange, Act, Assert).
+- **Global Performance Mandate:** "Measure first, optimize second." Every agent must ensure their changes adhere to 2025 performance standards (Core Web Vitals for Web, query optimization for DB, bundle limits for FS).
+- **Infrastructure & Safety Mandate:** Every agent is responsible for the deployability and operational safety of their changes. Follow the "5-Phase Deployment Process" (Prepare, Backup, Deploy, Verify, Confirm/Rollback). Always verify environment variables and secrets security.
+
+### 📁 File Dependency Awareness
+
+**Before modifying ANY file:**
+1. Check `CODEBASE.md` → File Dependencies
+2. Identify dependent files
+3. Update ALL affected files together
+
+### 🗺️ System Map Read
+
+> 🔴 **MANDATORY:** Read `ARCHITECTURE.md` at session start to understand Agents, Skills, and Scripts.
+
+**Path Awareness:**
+- Agents: `.agent/` (Project)
+- Skills: `.agent/skills/` (Project)
+- Runtime Scripts: `.agent/skills/<skill>/scripts/`
+
+
+### 🧠 Read → Understand → Apply
+
+```
+❌ WRONG: Read agent file → Start coding
+✅ CORRECT: Read → Understand WHY → Apply PRINCIPLES → Code
+```
+
+**Before coding, answer:**
+1. What is the GOAL of this agent/skill?
+2. What PRINCIPLES must I apply?
+3. How does this DIFFER from generic output?
+
+---
+
+## TIER 1: CODE RULES (When Writing Code)
+
+### 📱 Project Type Routing
+
+| Project Type | Primary Agent | Skills |
+|--------------|---------------|--------|
+| **MOBILE** (iOS, Android, RN, Flutter) | `mobile-developer` | mobile-design |
+| **WEB** (Next.js, React web) | `frontend-specialist` | frontend-design |
+| **BACKEND** (API, server, DB) | `backend-specialist` | api-patterns, database-design |
+
+> 🔴 **Mobile + frontend-specialist = WRONG.** Mobile = mobile-developer ONLY.
+
+### 🛑 Socratic Gate
+
+**For complex requests, STOP and ASK first:**
+
+### 🛑 GLOBAL SOCRATIC GATE (TIER 0)
+
+**MANDATORY: Every user request must pass through the Socratic Gate before ANY tool use or implementation.**
+
+| Request Type | Strategy | Required Action |
+|--------------|----------|-----------------|
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions |
+| **Code Edit / Bug Fix** | Context Check | Confirm understanding + ask impact questions |
+| **Vague / Simple** | Clarification | Ask Purpose, Users, and Scope |
+| **Full Orchestration** | Gatekeeper | **STOP** subagents until user confirms plan details |
+| **Direct "Proceed"** | Validation | **STOP** → Even if answers are given, ask 2 "Edge Case" questions |
+
+**Protocol:** 
+1. **Never Assume:** If even 1% is unclear, ASK.
+2. **Handle Spec-heavy Requests:** When user gives a list (Answers 1, 2, 3...), do NOT skip the gate. Instead, ask about **Trade-offs** or **Edge Cases** (e.g., "LocalStorage confirmed, but should we handle data clearing or versioning?") before starting.
+3. **Wait:** Do NOT invoke subagents or write code until the user clears the Gate.
+4. **Reference:** Full protocol in `@[skills/brainstorming]`.
+
+### 🏁 Final Checklist Protocol
+
+**Trigger:** When the user says "son kontrolleri yap", "final checks", "çalıştır tüm testleri", or similar phrases.
+
+| Task Stage | Command | Purpose |
+|------------|---------|---------|
+| **Manual Audit** | `python scripts/checklist.py .` | Priority-based project audit |
+| **Pre-Deploy** | `python scripts/checklist.py . --url <URL>` | Full Suite + Performance + E2E |
+
+**Priority Execution Order:**
+1. **Security** → 2. **Lint** → 3. **Schema** → 4. **Tests** → 5. **UX** → 6. **Seo** → 7. **Lighthouse/E2E**
+
+**Rules:**
+- **Completion:** A task is NOT finished until `checklist.py` returns success.
+- **Reporting:** If it fails, fix the **Critical** blockers first (Security/Lint).
+
+
+**Available Scripts (12 total):**
+| Script | Skill | When to Use |
+|--------|-------|-------------|
+| `security_scan.py` | vulnerability-scanner | Always on deploy |
+| `dependency_analyzer.py` | vulnerability-scanner | Weekly / Deploy |
+| `lint_runner.py` | lint-and-validate | Every code change |
+| `test_runner.py` | testing-patterns | After logic change |
+| `schema_validator.py` | database-design | After DB change |
+| `ux_audit.py` | frontend-design | After UI change |
+| `accessibility_checker.py` | frontend-design | After UI change |
+| `seo_checker.py` | seo-fundamentals | After page change |
+| `bundle_analyzer.py` | performance-profiling | Before deploy |
+| `mobile_audit.py` | mobile-design | After mobile change |
+| `lighthouse_audit.py` | performance-profiling | Before deploy |
+| `playwright_runner.py` | webapp-testing | Before deploy |
+
+> 🔴 **Agents & Skills can invoke ANY script** via `python .agent/skills/<skill>/scripts/<script>.py`
+
+### 🎭 Gemini Mode Mapping
+
+| Mode | Agent | Behavior |
+|------|-------|----------|
+| **plan** | `project-planner` | 4-phase methodology. NO CODE before Phase 4. |
+| **ask** | - | Focus on understanding. Ask questions. |
+| **edit** | `orchestrator` | Execute. Check `{task-slug}.md` first. |
+
+**Plan Mode (4-Phase):**
+1. ANALYSIS → Research, questions
+2. PLANNING → `{task-slug}.md`, task breakdown
+3. SOLUTIONING → Architecture, design (NO CODE!)
+4. IMPLEMENTATION → Code + tests
+
+> 🔴 **Edit mode:** If multi-file or structural change → Offer to create `{task-slug}.md`. For single-file fixes → Proceed directly.
+
+---
+
+## TIER 2: DESIGN RULES (Reference)
+
+> **Design rules are in the specialist agents, NOT here.**
+
+| Task | Read |
+|------|------|
+| Web UI/UX | `.agent/frontend-specialist.md` |
+| Mobile UI/UX | `.agent/mobile-developer.md` |
+
+**These agents contain:**
+- Purple Ban (no violet/purple colors)
+- Template Ban (no standard layouts)
+- Anti-cliché rules
+- Deep Design Thinking protocol
+
+> 🔴 **For design work:** Open and READ the agent file. Rules are there.
+
+---
+
+## 📁 QUICK REFERENCE
+
+### Available Master Agents (8)
+
+| Agent | Domain & Focus |
+|-------|----------------|
+| `orchestrator` | Multi-agent coordination and synthesis |
+| `project-planner` | Discovery, Architecture, and Task Planning |
+| `security-auditor` | Master Cybersecurity (Audit + Pentest + Infra Hardening) |
+| `backend-specialist` | Backend Architect (API + Database + Server/Docker Deploy) |
+| `frontend-specialist` | Frontend & Growth (UI/UX + SEO + Edge/Static Deploy) |
+| `mobile-developer` | Mobile Specialist (Cross-platform + Mobile Performance)|
+| `debugger` | Systematic Root Cause Analysis & Bug Fixing |
+| `game-developer` | Specialized Game Logic & Assets & Performance |
+
+### Key Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `clean-code` | Coding standards (GLOBAL) |
+| `brainstorming` | Socratic questioning |
+| `app-builder` | Full-stack orchestration |
+| `frontend-design` | Web UI patterns |
+| `mobile-design` | Mobile UI patterns |
+| `plan-writing` | {task-slug}.md format |
+| `behavioral-modes` | Mode switching |
+
+### Script Locations
+
+| Script | Path |
+|--------|------|
+| Full verify | `scripts/verify_all.py` |
+| Security scan | `.agent/skills/vulnerability-scanner/scripts/security_scan.py` |
+| UX audit | `.agent/skills/frontend-design/scripts/ux_audit.py` |
+| Mobile audit | `.agent/skills/mobile-design/scripts/mobile_audit.py` |
+| Lighthouse | `.agent/skills/performance-profiling/scripts/lighthouse_audit.py` |
+| Playwright | `.agent/skills/webapp-testing/scripts/playwright_runner.py` |
+
+---

package/.agent/skills/api-patterns/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: api-patterns
+description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# API Patterns
+
+> API design principles and decision-making for 2025.
+> **Learn to THINK, not copy fixed patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
+| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
+| `response.md` | Envelope pattern, error format, pagination | Response structure |
+| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
+| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
+| `versioning.md` | URI/Header/Query versioning | API evolution planning |
+| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
+| `rate-limiting.md` | Token bucket, sliding window | API protection |
+| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
+| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+
+---
+
+## 🔗 Related Skills
+
+| Need | Skill |
+|------|-------|
+| API implementation | `@[skills/backend-development]` |
+| Data structure | `@[skills/database-design]` |
+| Security details | `@[skills/security-hardening]` |
+
+---
+
+## ✅ Decision Checklist
+
+Before designing an API:
+
+- [ ] **Asked user about API consumers?**
+- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
+- [ ] **Defined consistent response format?**
+- [ ] **Planned versioning strategy?**
+- [ ] **Considered authentication needs?**
+- [ ] **Planned rate limiting?**
+- [ ] **Documentation approach defined?**
+
+---
+
+## ❌ Anti-Patterns
+
+**DON'T:**
+- Default to REST for everything
+- Use verbs in REST endpoints (/getUsers)
+- Return inconsistent response formats
+- Expose internal errors to clients
+- Skip rate limiting
+
+**DO:**
+- Choose API style based on context
+- Ask about client requirements
+- Document thoroughly
+- Use appropriate status codes
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
+

package/.agent/skills/api-patterns/api-style.md

@@ -0,0 +1,42 @@
+# API Style Selection (2025)
+
+> REST vs GraphQL vs tRPC - Hangi durumda hangisi?
+
+## Decision Tree
+
+```
+Who are the API consumers?
+│
+├── Public API / Multiple platforms
+│   └── REST + OpenAPI (widest compatibility)
+│
+├── Complex data needs / Multiple frontends
+│   └── GraphQL (flexible queries)
+│
+├── TypeScript frontend + backend (monorepo)
+│   └── tRPC (end-to-end type safety)
+│
+├── Real-time / Event-driven
+│   └── WebSocket + AsyncAPI
+│
+└── Internal microservices
+    └── gRPC (performance) or REST (simplicity)
+```
+
+## Comparison
+
+| Factor | REST | GraphQL | tRPC |
+|--------|------|---------|------|
+| **Best for** | Public APIs | Complex apps | TS monorepos |
+| **Learning curve** | Low | Medium | Low (if TS) |
+| **Over/under fetching** | Common | Solved | Solved |
+| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
+| **Caching** | HTTP native | Complex | Client-based |
+
+## Selection Questions
+
+1. Who are the API consumers?
+2. Is the frontend TypeScript?
+3. How complex are the data relationships?
+4. Is caching critical?
+5. Public or internal API?

package/.agent/skills/api-patterns/auth.md

@@ -0,0 +1,24 @@
+# Authentication Patterns
+
+> Choose auth pattern based on use case.
+
+## Selection Guide
+
+| Pattern | Best For |
+|---------|----------|
+| **JWT** | Stateless, microservices |
+| **Session** | Traditional web, simple |
+| **OAuth 2.0** | Third-party integration |
+| **API Keys** | Server-to-server, public APIs |
+| **Passkey** | Modern passwordless (2025+) |
+
+## JWT Principles
+
+```
+Important:
+├── Always verify signature
+├── Check expiration
+├── Include minimal claims
+├── Use short expiry + refresh tokens
+└── Never store sensitive data in JWT
+```

package/.agent/skills/api-patterns/documentation.md

@@ -0,0 +1,26 @@
+# API Documentation Principles
+
+> Good docs = happy developers = API adoption.
+
+## OpenAPI/Swagger Essentials
+
+```
+Include:
+├── All endpoints with examples
+├── Request/response schemas
+├── Authentication requirements
+├── Error response formats
+└── Rate limiting info
+```
+
+## Good Documentation Has
+
+```
+Essentials:
+├── Quick start / Getting started
+├── Authentication guide
+├── Complete API reference
+├── Error handling guide
+├── Code examples (multiple languages)
+└── Changelog
+```