@maestro-ai/mcp-server 1.0.0 → 1.1.0

package/dist/content/content/skills/nextjs-best-practices/SKILL.md

@@ -1,203 +0,0 @@
----
-name: nextjs-best-practices
-description: Next.js App Router principles. Server Components, data fetching, routing patterns.
-allowed-tools: Read, Write, Edit, Glob, Grep
----
-
-# Next.js Best Practices
-
-> Principles for Next.js App Router development.
-
----
-
-## 1. Server vs Client Components
-
-### Decision Tree
-
-```
-Does it need...?
-│
-├── useState, useEffect, event handlers
-│   └── Client Component ('use client')
-│
-├── Direct data fetching, no interactivity
-│   └── Server Component (default)
-│
-└── Both? 
-    └── Split: Server parent + Client child
-```
-
-### By Default
-
-| Type | Use |
-|------|-----|
-| **Server** | Data fetching, layout, static content |
-| **Client** | Forms, buttons, interactive UI |
-
----
-
-## 2. Data Fetching Patterns
-
-### Fetch Strategy
-
-| Pattern | Use |
-|---------|-----|
-| **Default** | Static (cached at build) |
-| **Revalidate** | ISR (time-based refresh) |
-| **No-store** | Dynamic (every request) |
-
-### Data Flow
-
-| Source | Pattern |
-|--------|---------|
-| Database | Server Component fetch |
-| API | fetch with caching |
-| User input | Client state + server action |
-
----
-
-## 3. Routing Principles
-
-### File Conventions
-
-| File | Purpose |
-|------|---------|
-| `page.tsx` | Route UI |
-| `layout.tsx` | Shared layout |
-| `loading.tsx` | Loading state |
-| `error.tsx` | Error boundary |
-| `not-found.tsx` | 404 page |
-
-### Route Organization
-
-| Pattern | Use |
-|---------|-----|
-| Route groups `(name)` | Organize without URL |
-| Parallel routes `@slot` | Multiple same-level pages |
-| Intercepting `(.)` | Modal overlays |
-
----
-
-## 4. API Routes
-
-### Route Handlers
-
-| Method | Use |
-|--------|-----|
-| GET | Read data |
-| POST | Create data |
-| PUT/PATCH | Update data |
-| DELETE | Remove data |
-
-### Best Practices
-
-- Validate input with Zod
-- Return proper status codes
-- Handle errors gracefully
-- Use Edge runtime when possible
-
----
-
-## 5. Performance Principles
-
-### Image Optimization
-
-- Use next/image component
-- Set priority for above-fold
-- Provide blur placeholder
-- Use responsive sizes
-
-### Bundle Optimization
-
-- Dynamic imports for heavy components
-- Route-based code splitting (automatic)
-- Analyze with bundle analyzer
-
----
-
-## 6. Metadata
-
-### Static vs Dynamic
-
-| Type | Use |
-|------|-----|
-| Static export | Fixed metadata |
-| generateMetadata | Dynamic per-route |
-
-### Essential Tags
-
-- title (50-60 chars)
-- description (150-160 chars)
-- Open Graph images
-- Canonical URL
-
----
-
-## 7. Caching Strategy
-
-### Cache Layers
-
-| Layer | Control |
-|-------|---------|
-| Request | fetch options |
-| Data | revalidate/tags |
-| Full route | route config |
-
-### Revalidation
-
-| Method | Use |
-|--------|-----|
-| Time-based | `revalidate: 60` |
-| On-demand | `revalidatePath/Tag` |
-| No cache | `no-store` |
-
----
-
-## 8. Server Actions
-
-### Use Cases
-
-- Form submissions
-- Data mutations
-- Revalidation triggers
-
-### Best Practices
-
-- Mark with 'use server'
-- Validate all inputs
-- Return typed responses
-- Handle errors
-
----
-
-## 9. Anti-Patterns
-
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| 'use client' everywhere | Server by default |
-| Fetch in client components | Fetch in server |
-| Skip loading states | Use loading.tsx |
-| Ignore error boundaries | Use error.tsx |
-| Large client bundles | Dynamic imports |
-
----
-
-## 10. Project Structure
-
-```
-app/
-├── (marketing)/     # Route group
-│   └── page.tsx
-├── (dashboard)/
-│   ├── layout.tsx   # Dashboard layout
-│   └── page.tsx
-├── api/
-│   └── [resource]/
-│       └── route.ts
-└── components/
-    └── ui/
-```
-
----
-
-> **Remember:** Server Components are the default for a reason. Start there, add client only when needed.

package/dist/content/content/skills/nodejs-best-practices/SKILL.md

@@ -1,333 +0,0 @@
----
-name: nodejs-best-practices
-description: Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
-allowed-tools: Read, Write, Edit, Glob, Grep
----
-
-# Node.js Best Practices
-
-> Principles and decision-making for Node.js development in 2025.
-> **Learn to THINK, not memorize code patterns.**
-
----
-
-## ⚠️ How to Use This Skill
-
-This skill teaches **decision-making principles**, not fixed code to copy.
-
-- ASK user for preferences when unclear
-- Choose framework/pattern based on CONTEXT
-- Don't default to same solution every time
-
----
-
-## 1. Framework Selection (2025)
-
-### Decision Tree
-
-```
-What are you building?
-│
-├── Edge/Serverless (Cloudflare, Vercel)
-│   └── Hono (zero-dependency, ultra-fast cold starts)
-│
-├── High Performance API
-│   └── Fastify (2-3x faster than Express)
-│
-├── Enterprise/Team familiarity
-│   └── NestJS (structured, DI, decorators)
-│
-├── Legacy/Stable/Maximum ecosystem
-│   └── Express (mature, most middleware)
-│
-└── Full-stack with frontend
-    └── Next.js API Routes or tRPC
-```
-
-### Comparison Principles
-
-| Factor | Hono | Fastify | Express |
-|--------|------|---------|---------|
-| **Best for** | Edge, serverless | Performance | Legacy, learning |
-| **Cold start** | Fastest | Fast | Moderate |
-| **Ecosystem** | Growing | Good | Largest |
-| **TypeScript** | Native | Excellent | Good |
-| **Learning curve** | Low | Medium | Low |
-
-### Selection Questions to Ask:
-1. What's the deployment target?
-2. Is cold start time critical?
-3. Does team have existing experience?
-4. Is there legacy code to maintain?
-
----
-
-## 2. Runtime Considerations (2025)
-
-### Native TypeScript
-
-```
-Node.js 22+: --experimental-strip-types
-├── Run .ts files directly
-├── No build step needed for simple projects
-└── Consider for: scripts, simple APIs
-```
-
-### Module System Decision
-
-```
-ESM (import/export)
-├── Modern standard
-├── Better tree-shaking
-├── Async module loading
-└── Use for: new projects
-
-CommonJS (require)
-├── Legacy compatibility
-├── More npm packages support
-└── Use for: existing codebases, some edge cases
-```
-
-### Runtime Selection
-
-| Runtime | Best For |
-|---------|----------|
-| **Node.js** | General purpose, largest ecosystem |
-| **Bun** | Performance, built-in bundler |
-| **Deno** | Security-first, built-in TypeScript |
-
----
-
-## 3. Architecture Principles
-
-### Layered Structure Concept
-
-```
-Request Flow:
-│
-├── Controller/Route Layer
-│   ├── Handles HTTP specifics
-│   ├── Input validation at boundary
-│   └── Calls service layer
-│
-├── Service Layer
-│   ├── Business logic
-│   ├── Framework-agnostic
-│   └── Calls repository layer
-│
-└── Repository Layer
-    ├── Data access only
-    ├── Database queries
-    └── ORM interactions
-```
-
-### Why This Matters:
-- **Testability**: Mock layers independently
-- **Flexibility**: Swap database without touching business logic
-- **Clarity**: Each layer has single responsibility
-
-### When to Simplify:
-- Small scripts → Single file OK
-- Prototypes → Less structure acceptable
-- Always ask: "Will this grow?"
-
----
-
-## 4. Error Handling Principles
-
-### Centralized Error Handling
-
-```
-Pattern:
-├── Create custom error classes
-├── Throw from any layer
-├── Catch at top level (middleware)
-└── Format consistent response
-```
-
-### Error Response Philosophy
-
-```
-Client gets:
-├── Appropriate HTTP status
-├── Error code for programmatic handling
-├── User-friendly message
-└── NO internal details (security!)
-
-Logs get:
-├── Full stack trace
-├── Request context
-├── User ID (if applicable)
-└── Timestamp
-```
-
-### Status Code Selection
-
-| Situation | Status | When |
-|-----------|--------|------|
-| Bad input | 400 | Client sent invalid data |
-| No auth | 401 | Missing or invalid credentials |
-| No permission | 403 | Valid auth, but not allowed |
-| Not found | 404 | Resource doesn't exist |
-| Conflict | 409 | Duplicate or state conflict |
-| Validation | 422 | Schema valid but business rules fail |
-| Server error | 500 | Our fault, log everything |
-
----
-
-## 5. Async Patterns Principles
-
-### When to Use Each
-
-| Pattern | Use When |
-|---------|----------|
-| `async/await` | Sequential async operations |
-| `Promise.all` | Parallel independent operations |
-| `Promise.allSettled` | Parallel where some can fail |
-| `Promise.race` | Timeout or first response wins |
-
-### Event Loop Awareness
-
-```
-I/O-bound (async helps):
-├── Database queries
-├── HTTP requests
-├── File system
-└── Network operations
-
-CPU-bound (async doesn't help):
-├── Crypto operations
-├── Image processing
-├── Complex calculations
-└── → Use worker threads or offload
-```
-
-### Avoiding Event Loop Blocking
-
-- Never use sync methods in production (fs.readFileSync, etc.)
-- Offload CPU-intensive work
-- Use streaming for large data
-
----
-
-## 6. Validation Principles
-
-### Validate at Boundaries
-
-```
-Where to validate:
-├── API entry point (request body/params)
-├── Before database operations
-├── External data (API responses, file uploads)
-└── Environment variables (startup)
-```
-
-### Validation Library Selection
-
-| Library | Best For |
-|---------|----------|
-| **Zod** | TypeScript first, inference |
-| **Valibot** | Smaller bundle (tree-shakeable) |
-| **ArkType** | Performance critical |
-| **Yup** | Existing React Form usage |
-
-### Validation Philosophy
-
-- Fail fast: Validate early
-- Be specific: Clear error messages
-- Don't trust: Even "internal" data
-
----
-
-## 7. Security Principles
-
-### Security Checklist (Not Code)
-
-- [ ] **Input validation**: All inputs validated
-- [ ] **Parameterized queries**: No string concatenation for SQL
-- [ ] **Password hashing**: bcrypt or argon2
-- [ ] **JWT verification**: Always verify signature and expiry
-- [ ] **Rate limiting**: Protect from abuse
-- [ ] **Security headers**: Helmet.js or equivalent
-- [ ] **HTTPS**: Everywhere in production
-- [ ] **CORS**: Properly configured
-- [ ] **Secrets**: Environment variables only
-- [ ] **Dependencies**: Regularly audited
-
-### Security Mindset
-
-```
-Trust nothing:
-├── Query params → validate
-├── Request body → validate
-├── Headers → verify
-├── Cookies → validate
-├── File uploads → scan
-└── External APIs → validate response
-```
-
----
-
-## 8. Testing Principles
-
-### Test Strategy Selection
-
-| Type | Purpose | Tools |
-|------|---------|-------|
-| **Unit** | Business logic | node:test, Vitest |
-| **Integration** | API endpoints | Supertest |
-| **E2E** | Full flows | Playwright |
-
-### What to Test (Priorities)
-
-1. **Critical paths**: Auth, payments, core business
-2. **Edge cases**: Empty inputs, boundaries
-3. **Error handling**: What happens when things fail?
-4. **Not worth testing**: Framework code, trivial getters
-
-### Built-in Test Runner (Node.js 22+)
-
-```
-node --test src/**/*.test.ts
-├── No external dependency
-├── Good coverage reporting
-└── Watch mode available
-```
-
----
-
-## 10. Anti-Patterns to Avoid
-
-### ❌ DON'T:
-- Use Express for new edge projects (use Hono)
-- Use sync methods in production code
-- Put business logic in controllers
-- Skip input validation
-- Hardcode secrets
-- Trust external data without validation
-- Block event loop with CPU work
-
-### ✅ DO:
-- Choose framework based on context
-- Ask user for preferences when unclear
-- Use layered architecture for growing projects
-- Validate all inputs
-- Use environment variables for secrets
-- Profile before optimizing
-
----
-
-## 11. Decision Checklist
-
-Before implementing:
-
-- [ ] **Asked user about stack preference?**
-- [ ] **Chosen framework for THIS context?** (not just default)
-- [ ] **Considered deployment target?**
-- [ ] **Planned error handling strategy?**
-- [ ] **Identified validation points?**
-- [ ] **Considered security requirements?**
-
----
-
-> **Remember**: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.

package/dist/content/content/skills/parallel-agents/SKILL.md

@@ -1,175 +0,0 @@
----
-name: parallel-agents
-description: Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives.
-allowed-tools: Read, Glob, Grep
----
-
-# Native Parallel Agents
-
-> Orchestration through Antigravity's built-in Agent Tool
-
-## Overview
-
-This skill enables coordinating multiple specialized agents through Antigravity's native agent system. Unlike external scripts, this approach keeps all orchestration within Antigravity's control.
-
-## When to Use Orchestration
-
-✅ **Good for:**
-- Complex tasks requiring multiple expertise domains
-- Code analysis from security, performance, and quality perspectives
-- Comprehensive reviews (architecture + security + testing)
-- Feature implementation needing backend + frontend + database work
-
-❌ **Not for:**
-- Simple, single-domain tasks
-- Quick fixes or small changes
-- Tasks where one agent suffices
-
----
-
-## Native Agent Invocation
-
-### Single Agent
-```
-Use the security-auditor agent to review authentication
-```
-
-### Sequential Chain
-```
-First, use the explorer-agent to discover project structure.
-Then, use the backend-specialist to review API endpoints.
-Finally, use the test-engineer to identify test gaps.
-```
-
-### With Context Passing
-```
-Use the frontend-specialist to analyze React components.
-Based on those findings, have the test-engineer generate component tests.
-```
-
-### Resume Previous Work
-```
-Resume agent [agentId] and continue with additional requirements.
-```
-
----
-
-## Orchestration Patterns
-
-### Pattern 1: Comprehensive Analysis
-```
-Agents: explorer-agent → [domain-agents] → synthesis
-
-1. explorer-agent: Map codebase structure
-2. security-auditor: Security posture
-3. backend-specialist: API quality
-4. frontend-specialist: UI/UX patterns
-5. test-engineer: Test coverage
-6. Synthesize all findings
-```
-
-### Pattern 2: Feature Review
-```
-Agents: affected-domain-agents → test-engineer
-
-1. Identify affected domains (backend? frontend? both?)
-2. Invoke relevant domain agents
-3. test-engineer verifies changes
-4. Synthesize recommendations
-```
-
-### Pattern 3: Security Audit
-```
-Agents: security-auditor → penetration-tester → synthesis
-
-1. security-auditor: Configuration and code review
-2. penetration-tester: Active vulnerability testing
-3. Synthesize with prioritized remediation
-```
-
----
-
-## Available Agents
-
-| Agent | Expertise | Trigger Phrases |
-|-------|-----------|-----------------|
-| `orchestrator` | Coordination | "comprehensive", "multi-perspective" |
-| `security-auditor` | Security | "security", "auth", "vulnerabilities" |
-| `penetration-tester` | Security Testing | "pentest", "red team", "exploit" |
-| `backend-specialist` | Backend | "API", "server", "Node.js", "Express" |
-| `frontend-specialist` | Frontend | "React", "UI", "components", "Next.js" |
-| `test-engineer` | Testing | "tests", "coverage", "TDD" |
-| `devops-engineer` | DevOps | "deploy", "CI/CD", "infrastructure" |
-| `database-architect` | Database | "schema", "Prisma", "migrations" |
-| `mobile-developer` | Mobile | "React Native", "Flutter", "mobile" |
-| `api-designer` | API Design | "REST", "GraphQL", "OpenAPI" |
-| `debugger` | Debugging | "bug", "error", "not working" |
-| `explorer-agent` | Discovery | "explore", "map", "structure" |
-| `documentation-writer` | Documentation | "write docs", "create README", "generate API docs" |
-| `performance-optimizer` | Performance | "slow", "optimize", "profiling" |
-| `project-planner` | Planning | "plan", "roadmap", "milestones" |
-| `seo-specialist` | SEO | "SEO", "meta tags", "search ranking" |
-| `game-developer` | Game Development | "game", "Unity", "Godot", "Phaser" |
-
----
-
-## Antigravity Built-in Agents
-
-These work alongside custom agents:
-
-| Agent | Model | Purpose |
-|-------|-------|---------|
-| **Explore** | Haiku | Fast read-only codebase search |
-| **Plan** | Sonnet | Research during plan mode |
-| **General-purpose** | Sonnet | Complex multi-step modifications |
-
-Use **Explore** for quick searches, **custom agents** for domain expertise.
-
----
-
-## Synthesis Protocol
-
-After all agents complete, synthesize:
-
-```markdown
-## Orchestration Synthesis
-
-### Task Summary
-[What was accomplished]
-
-### Agent Contributions
-| Agent | Finding |
-|-------|---------|
-| security-auditor | Found X |
-| backend-specialist | Identified Y |
-
-### Consolidated Recommendations
-1. **Critical**: [Issue from Agent A]
-2. **Important**: [Issue from Agent B]
-3. **Nice-to-have**: [Enhancement from Agent C]
-
-### Action Items
-- [ ] Fix critical security issue
-- [ ] Refactor API endpoint
-- [ ] Add missing tests
-```
-
----
-
-## Best Practices
-
-1. **Available agents** - 17 specialized agents can be orchestrated
-2. **Logical order** - Discovery → Analysis → Implementation → Testing
-3. **Share context** - Pass relevant findings to subsequent agents
-4. **Single synthesis** - One unified report, not separate outputs
-5. **Verify changes** - Always include test-engineer for code modifications
-
----
-
-## Key Benefits
-
-- ✅ **Single session** - All agents share context
-- ✅ **AI-controlled** - Claude orchestrates autonomously
-- ✅ **Native integration** - Works with built-in Explore, Plan agents
-- ✅ **Resume support** - Can continue previous agent work
-- ✅ **Context passing** - Findings flow between agents