@musashishao/agent-kit 1.0.0

package/.agent/workflows/orchestrate.md

@@ -0,0 +1,237 @@
+---
+description: Coordinate multiple agents for complex tasks. Use for multi-perspective analysis, comprehensive reviews, or tasks requiring different domain expertise.
+---
+
+# Multi-Agent Orchestration
+
+You are now in **ORCHESTRATION MODE**. Your task: coordinate specialized agents to solve this complex problem.
+
+## Task to Orchestrate
+$ARGUMENTS
+
+---
+
+## 🔴 CRITICAL: Minimum Agent Requirement
+
+> ⚠️ **ORCHESTRATION = MINIMUM 3 DIFFERENT AGENTS**
+> 
+> If you use fewer than 3 agents, you are NOT orchestrating - you're just delegating.
+> 
+> **Validation before completion:**
+> - Count invoked agents
+> - If `agent_count < 3` → STOP and invoke more agents
+> - Single agent = FAILURE of orchestration
+
+### Agent Selection Matrix
+
+| Task Type | REQUIRED Agents (minimum) |
+|-----------|---------------------------|
+| **Web App** | frontend-specialist, backend-specialist, test-engineer |
+| **API** | backend-specialist, security-auditor, test-engineer |
+| **UI/Design** | frontend-specialist, seo-specialist, performance-optimizer |
+| **Database** | database-architect, backend-specialist, security-auditor |
+| **Full Stack** | project-planner, frontend-specialist, backend-specialist, devops-engineer |
+| **Debug** | debugger, explorer-agent, test-engineer |
+| **Security** | security-auditor, penetration-tester, devops-engineer |
+
+---
+
+## Pre-Flight: Mode Check
+
+| Current Mode | Task Type | Action |
+|--------------|-----------|--------|
+| **plan** | Any | ✅ Proceed with planning-first approach |
+| **edit** | Simple execution | ✅ Proceed directly |
+| **edit** | Complex/multi-file | ⚠️ Ask: "This task requires planning. Switch to plan mode?" |
+| **ask** | Any | ⚠️ Ask: "Ready to orchestrate. Switch to edit or plan mode?" |
+
+---
+
+## 🔴 STRICT 2-PHASE ORCHESTRATION
+
+### PHASE 1: PLANNING (Sequential - NO parallel agents)
+
+| Step | Agent | Action |
+|------|-------|--------|
+| 1 | `project-planner` | Create docs/PLAN.md |
+| 2 | (optional) `explorer-agent` | Codebase discovery if needed |
+
+> 🔴 **NO OTHER AGENTS during planning!** Only project-planner and explorer-agent.
+
+### ⏸️ CHECKPOINT: User Approval
+
+```
+After PLAN.md is complete, ASK:
+
+"✅ Plan oluşturuldu: docs/PLAN.md
+
+Onaylıyor musunuz? (Y/N)
+- Y: Implementation başlatılır
+- N: Planı düzeltirim"
+```
+
+> 🔴 **DO NOT proceed to Phase 2 without explicit user approval!**
+
+### PHASE 2: IMPLEMENTATION (Parallel agents after approval)
+
+| Parallel Group | Agents |
+|----------------|--------|
+| Foundation | `database-architect`, `security-auditor` |
+| Core | `backend-specialist`, `frontend-specialist` |
+| Polish | `test-engineer`, `devops-engineer` |
+
+> ✅ After user approval, invoke multiple agents in PARALLEL.
+
+## Available Agents (17 total)
+
+| Agent | Domain | Use When |
+|-------|--------|----------|
+| `project-planner` | Planning | Task breakdown, PLAN.md |
+| `explorer-agent` | Discovery | Codebase mapping |
+| `frontend-specialist` | UI/UX | React, Vue, CSS, HTML |
+| `backend-specialist` | Server | API, Node.js, Python |
+| `database-architect` | Data | SQL, NoSQL, Schema |
+| `security-auditor` | Security | Vulnerabilities, Auth |
+| `penetration-tester` | Security | Active testing |
+| `test-engineer` | Testing | Unit, E2E, Coverage |
+| `devops-engineer` | Ops | CI/CD, Docker, Deploy |
+| `mobile-developer` | Mobile | React Native, Flutter |
+| `performance-optimizer` | Speed | Lighthouse, Profiling |
+| `seo-specialist` | SEO | Meta, Schema, Rankings |
+| `documentation-writer` | Docs | README, API docs |
+| `debugger` | Debug | Error analysis |
+| `game-developer` | Games | Unity, Godot |
+| `orchestrator` | Meta | Coordination |
+
+---
+
+## Orchestration Protocol
+
+### Step 1: Analyze Task Domains
+Identify ALL domains this task touches:
+```
+□ Security     → security-auditor, penetration-tester
+□ Backend/API  → backend-specialist
+□ Frontend/UI  → frontend-specialist
+□ Database     → database-architect
+□ Testing      → test-engineer
+□ DevOps       → devops-engineer
+□ Mobile       → mobile-developer
+□ Performance  → performance-optimizer
+□ SEO          → seo-specialist
+□ Planning     → project-planner
+```
+
+### Step 2: Phase Detection
+
+| If Plan Exists | Action |
+|----------------|--------|
+| NO `docs/PLAN.md` | → Go to PHASE 1 (planning only) |
+| YES `docs/PLAN.md` + user approved | → Go to PHASE 2 (implementation) |
+
+### Step 3: Execute Based on Phase
+
+**PHASE 1 (Planning):**
+```
+Use the project-planner agent to create PLAN.md
+→ STOP after plan is created
+→ ASK user for approval
+```
+
+**PHASE 2 (Implementation - after approval):**
+```
+Invoke agents in PARALLEL:
+Use the frontend-specialist agent to [task]
+Use the backend-specialist agent to [task]
+Use the test-engineer agent to [task]
+```
+
+**🔴 CRITICAL: Context Passing (MANDATORY)**
+
+When invoking ANY subagent, you MUST include:
+
+1. **Original User Request:** Full text of what user asked
+2. **Decisions Made:** All user answers to Socratic questions
+3. **Previous Agent Work:** Summary of what previous agents did
+4. **Current Plan State:** If plan files exist in workspace, include them
+
+**Example with FULL context:**
+```
+Use the project-planner agent to create PLAN.md:
+
+**CONTEXT:**
+- User Request: "Öğrenciler için sosyal platform, mock data ile"
+- Decisions: Tech=Vue 3, Layout=Grid Widget, Auth=Mock, Design=Genç Dinamik
+- Previous Work: Orchestrator asked 6 questions, user chose all options
+- Current Plan: playful-roaming-dream.md exists in workspace with initial structure
+
+**TASK:** Create detailed PLAN.md based on ABOVE decisions. Do NOT infer from folder name.
+```
+
+> ⚠️ **VIOLATION:** Invoking subagent without full context = subagent will make wrong assumptions!
+
+
+### Step 4: Verification (MANDATORY)
+The LAST agent must run appropriate verification scripts:
+```bash
+python .agent/skills/vulnerability-scanner/scripts/security_scan.py .
+python .agent/skills/lint-and-validate/scripts/lint_runner.py .
+```
+
+### Step 5: Synthesize Results
+Combine all agent outputs into unified report.
+
+---
+
+## Output Format
+
+```markdown
+## 🎼 Orchestration Report
+
+### Task
+[Original task summary]
+
+### Mode
+[Current Claude Code mode: plan/edit/ask]
+
+### Agents Invoked (MINIMUM 3)
+| # | Agent | Focus Area | Status |
+|---|-------|------------|--------|
+| 1 | project-planner | Task breakdown | ✅ |
+| 2 | frontend-specialist | UI implementation | ✅ |
+| 3 | test-engineer | Verification scripts | ✅ |
+
+### Verification Scripts Executed
+- [x] security_scan.py → Pass/Fail
+- [x] lint_runner.py → Pass/Fail
+
+### Key Findings
+1. **[Agent 1]**: Finding
+2. **[Agent 2]**: Finding
+3. **[Agent 3]**: Finding
+
+### Deliverables
+- [ ] PLAN.md created
+- [ ] Code implemented
+- [ ] Tests passing
+- [ ] Scripts verified
+
+### Summary
+[One paragraph synthesis of all agent work]
+```
+
+---
+
+## 🔴 EXIT GATE
+
+Before completing orchestration, verify:
+
+1. ✅ **Agent Count:** `invoked_agents >= 3`
+2. ✅ **Scripts Executed:** At least `security_scan.py` ran
+3. ✅ **Report Generated:** Orchestration Report with all agents listed
+
+> **If any check fails → DO NOT mark orchestration complete. Invoke more agents or run scripts.**
+
+---
+
+**Begin orchestration now. Select 3+ agents, execute sequentially, run verification scripts, synthesize results.**

package/.agent/workflows/plan.md

@@ -0,0 +1,89 @@
+---
+description: Create project plan using project-planner agent. No code writing - only plan file generation.
+---
+
+# /plan - Project Planning Mode
+
+$ARGUMENTS
+
+---
+
+## 🔴 CRITICAL RULES
+
+1. **NO CODE WRITING** - This command creates plan file only
+2. **Use project-planner agent** - NOT Claude Code's native Plan subagent
+3. **Socratic Gate** - Ask clarifying questions before planning
+4. **Dynamic Naming** - Plan file named based on task
+
+---
+
+## Task
+
+Use the `project-planner` agent with this context:
+
+```
+CONTEXT:
+- User Request: $ARGUMENTS
+- Mode: PLANNING ONLY (no code)
+- Output: docs/PLAN-{task-slug}.md (dynamic naming)
+
+NAMING RULES:
+1. Extract 2-3 key words from request
+2. Lowercase, hyphen-separated
+3. Max 30 characters
+4. Example: "e-commerce cart" → PLAN-ecommerce-cart.md
+
+RULES:
+1. Follow project-planner.md Phase -1 (Context Check)
+2. Follow project-planner.md Phase 0 (Socratic Gate)
+3. Create PLAN-{slug}.md with task breakdown
+4. DO NOT write any code files
+5. REPORT the exact file name created
+```
+
+---
+
+## Expected Output
+
+| Deliverable | Location |
+|-------------|----------|
+| Project Plan | `docs/PLAN-{task-slug}.md` |
+| Task Breakdown | Inside plan file |
+| Agent Assignments | Inside plan file |
+| Verification Checklist | Phase X in plan file |
+
+---
+
+## After Planning
+
+Tell user:
+```
+[OK] Plan created: docs/PLAN-{slug}.md
+
+Next steps:
+- Review the plan
+- Run `/create` to start implementation
+- Or modify plan manually
+```
+
+---
+
+## Naming Examples
+
+| Request | Plan File |
+|---------|-----------|
+| `/plan e-commerce site with cart` | `docs/PLAN-ecommerce-cart.md` |
+| `/plan mobile app for fitness` | `docs/PLAN-fitness-app.md` |
+| `/plan add dark mode feature` | `docs/PLAN-dark-mode.md` |
+| `/plan fix authentication bug` | `docs/PLAN-auth-fix.md` |
+| `/plan SaaS dashboard` | `docs/PLAN-saas-dashboard.md` |
+
+---
+
+## Usage
+
+```
+/plan e-commerce site with cart
+/plan mobile app for fitness tracking
+/plan SaaS dashboard with analytics
+```

package/.agent/workflows/preview.md

@@ -0,0 +1,80 @@
+---
+description: Preview server start, stop, and status check. Local development server management.
+---
+
+# /preview - Preview Management
+
+$ARGUMENTS
+
+---
+
+## Task
+
+Manage preview server: start, stop, status check.
+
+### Commands
+
+```
+/preview           - Show current status
+/preview start     - Start server
+/preview stop      - Stop server
+/preview restart   - Restart
+/preview check     - Health check
+```
+
+---
+
+## Usage Examples
+
+### Start Server
+```
+/preview start
+
+Response:
+🚀 Starting preview...
+   Port: 3000
+   Type: Next.js
+
+✅ Preview ready!
+   URL: http://localhost:3000
+```
+
+### Status Check
+```
+/preview
+
+Response:
+=== Preview Status ===
+
+🌐 URL: http://localhost:3000
+📁 Project: C:/projects/my-app
+🏷️ Type: nextjs
+💚 Health: OK
+```
+
+### Port Conflict
+```
+/preview start
+
+Response:
+⚠️ Port 3000 is in use.
+
+Options:
+1. Start on port 3001
+2. Close app on 3000
+3. Specify different port
+
+Which one? (default: 1)
+```
+
+---
+
+## Technical
+
+Auto preview uses `auto_preview.py` script:
+
+```bash
+python .agent/scripts/auto_preview.py start [path] [port]
+python .agent/scripts/auto_preview.py stop
+python .agent/scripts/auto_preview.py status
+```

package/.agent/workflows/status.md

@@ -0,0 +1,86 @@
+---
+description: Display agent and project status. Progress tracking and status board.
+---
+
+# /status - Show Status
+
+$ARGUMENTS
+
+---
+
+## Task
+
+Show current project and agent status.
+
+### What It Shows
+
+1. **Project Info**
+   - Project name and path
+   - Tech stack
+   - Current features
+
+2. **Agent Status Board**
+   - Which agents are running
+   - Which tasks are completed
+   - Pending work
+
+3. **File Statistics**
+   - Files created count
+   - Files modified count
+
+4. **Preview Status**
+   - Is server running
+   - URL
+   - Health check
+
+---
+
+## Example Output
+
+```
+=== Project Status ===
+
+📁 Project: my-ecommerce
+📂 Path: C:/projects/my-ecommerce
+🏷️ Type: nextjs-ecommerce
+📊 Status: active
+
+🔧 Tech Stack:
+   Framework: next.js
+   Database: postgresql
+   Auth: clerk
+   Payment: stripe
+
+✅ Features (5):
+   • product-listing
+   • cart
+   • checkout
+   • user-auth
+   • order-history
+
+⏳ Pending (2):
+   • admin-panel
+   • email-notifications
+
+📄 Files: 73 created, 12 modified
+
+=== Agent Status ===
+
+✅ database-architect → Completed
+✅ backend-specialist → Completed
+🔄 frontend-specialist → Dashboard components (60%)
+⏳ test-engineer → Waiting
+
+=== Preview ===
+
+🌐 URL: http://localhost:3000
+💚 Health: OK
+```
+
+---
+
+## Technical
+
+Status uses these scripts:
+- `session_manager.py status`
+- `auto_preview.py status`

package/.agent/workflows/test.md

@@ -0,0 +1,144 @@
+---
+description: Test generation and test running command. Creates and executes tests for code.
+---
+
+# /test - Test Generation and Execution
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command generates tests, runs existing tests, or checks test coverage.
+
+---
+
+## Sub-commands
+
+```
+/test                - Run all tests
+/test [file/feature] - Generate tests for specific target
+/test coverage       - Show test coverage report
+/test watch          - Run tests in watch mode
+```
+
+---
+
+## Behavior
+
+### Generate Tests
+
+When asked to test a file or feature:
+
+1. **Analyze the code**
+   - Identify functions and methods
+   - Find edge cases
+   - Detect dependencies to mock
+
+2. **Generate test cases**
+   - Happy path tests
+   - Error cases
+   - Edge cases
+   - Integration tests (if needed)
+
+3. **Write tests**
+   - Use project's test framework (Jest, Vitest, etc.)
+   - Follow existing test patterns
+   - Mock external dependencies
+
+---
+
+## Output Format
+
+### For Test Generation
+
+```markdown
+## 🧪 Tests: [Target]
+
+### Test Plan
+| Test Case | Type | Coverage |
+|-----------|------|----------|
+| Should create user | Unit | Happy path |
+| Should reject invalid email | Unit | Validation |
+| Should handle db error | Unit | Error case |
+
+### Generated Tests
+
+`tests/[file].test.ts`
+
+[Code block with tests]
+
+---
+
+Run with: `npm test`
+```
+
+### For Test Execution
+
+```
+🧪 Running tests...
+
+✅ auth.test.ts (5 passed)
+✅ user.test.ts (8 passed)
+❌ order.test.ts (2 passed, 1 failed)
+
+Failed:
+  ✗ should calculate total with discount
+    Expected: 90
+    Received: 100
+
+Total: 15 tests (14 passed, 1 failed)
+```
+
+---
+
+## Examples
+
+```
+/test src/services/auth.service.ts
+/test user registration flow
+/test coverage
+/test fix failed tests
+```
+
+---
+
+## Test Patterns
+
+### Unit Test Structure
+
+```typescript
+describe('AuthService', () => {
+  describe('login', () => {
+    it('should return token for valid credentials', async () => {
+      // Arrange
+      const credentials = { email: 'test@test.com', password: 'pass123' };
+      
+      // Act
+      const result = await authService.login(credentials);
+      
+      // Assert
+      expect(result.token).toBeDefined();
+    });
+
+    it('should throw for invalid password', async () => {
+      // Arrange
+      const credentials = { email: 'test@test.com', password: 'wrong' };
+      
+      // Act & Assert
+      await expect(authService.login(credentials)).rejects.toThrow('Invalid credentials');
+    });
+  });
+});
+```
+
+---
+
+## Key Principles
+
+- **Test behavior not implementation**
+- **One assertion per test** (when practical)
+- **Descriptive test names**
+- **Arrange-Act-Assert pattern**
+- **Mock external dependencies**