agent-skill-kit 3.9.135

package/.agent/workflows/optimize.md

@@ -0,0 +1,269 @@
+---
+description: Full-stack performance optimization — profile bottlenecks, fix N+1 queries, configure Redis caching, reduce bundle size, and validate with k6 load testing.
+skills: [perf-optimizer, data-modeler, server-ops, problem-checker, smart-router, context-engineering, knowledge-compiler]
+agents: [orchestrator, assessor, recovery, learner, performance-specialist, backend-specialist]
+---
+
+# /optimize - Performance Optimization
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Profile application performance, optimize bottlenecks (database queries, bundle size, caching), and validate improvements with load testing. **Differs from `/validate` (runs test suites, no optimization) and `/monitor` (tracks production metrics) by actively identifying and fixing performance issues across frontend, backend, and infrastructure.** Uses `perf-optimizer` with `perf-optimizer` for profiling and `nodejs-pro` with `data-modeler` for database optimization.
+
+---
+
+## ?? Meta-Agents Integration
+
+| Phase | Agent | Action |
+| ----- | ----- | ------ |
+| **Pre-Flight** | `assessor` | Evaluate optimization scope and knowledge-compiler context |
+| **Execution** | `orchestrator` | Coordinate profiling, database, and cache optimization |
+| **Safety** | `recovery` | Save state and recover/rollback from performance regressions |
+| **Post-Optimize**| `learner` | Log optimization telemetry and performance patterns |
+
+```
+Flow:
+recovery.save() ? profile ? optimize ? benchmark
+       ?
+benchmark ? worse? ? recovery.restore()
+       ? better
+learner.log(optimization_patterns)
+```
+
+---
+
+## ?? MANDATORY: Performance Optimization Protocol
+
+### Phase 1: Pre-flight & knowledge-compiler Context
+
+> **Rule 0.5-K:** knowledge-compiler pattern check.
+
+1. Read `.agent/skills/knowledge-compiler/patterns/` for past failures before proceeding.
+2. Trigger `recovery` agent to run Checkpoint (`git commit -m "chore(checkpoint): pre-optimize"`).
+
+### Phase 2: Performance Profiling
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | $ARGUMENTS (app/component to optimize + optional targets) |
+| **OUTPUT** | Performance audit: bottlenecks identified with metrics |
+| **AGENTS** | `perf-optimizer`, `assessor` |
+| **SKILLS** | `perf-optimizer`, `context-engineering` |
+
+// turbo — telemetry: phase-2-profile
+
+1. `recovery` saves current state before any changes
+2. Run profiling:
+
+| Area | Profile | Metrics |
+|------|---------|---------|
+| Frontend | Lighthouse, bundle analysis | LCP, CLS, FID, bundle KB |
+| Backend | API profiling | p50, p95, p99 latency |
+| Database | Query analysis | Query count, duration, N+1 |
+| Cache | Hit/miss analysis | Hit rate %, DB load |
+
+3. Identify bottlenecks and rank by impact
+
+Performance targets:
+
+| Metric | Target | Critical |
+|--------|--------|----------|
+| p95 Latency | <200ms | <500ms |
+| Error Rate | <0.5% | <1% |
+| Cache Hit Rate | >80% | >70% |
+| Concurrent Users | 10,000+ | 5,000+ |
+| LCP | <2.5s | <4s |
+| CLS | <0.1 | <0.25 |
+
+### Phase 3: Database Optimization
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Bottleneck report from Phase 2 |
+| **OUTPUT** | Optimized queries, added indexes, fixed N+1 patterns |
+| **AGENTS** | `nodejs-pro`, `orchestrator` |
+| **SKILLS** | `data-modeler`, `perf-optimizer`, `smart-router` |
+
+// turbo — telemetry: phase-3-db
+
+| Issue | Solution | Impact |
+|-------|----------|--------|
+| N+1 queries | Use `include` or JOINs | 90%+ faster |
+| Missing indexes | Add indexes on foreign keys | 95%+ faster |
+| Small connection pool | Increase to 20-50 | Eliminates timeouts |
+| Unoptimized queries | Rewrite with proper filtering | Variable |
+
+### Phase 4: Caching & Frontend
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Optimized database from Phase 3 |
+| **OUTPUT** | Redis cache configured, CDN setup, bundle optimized |
+| **AGENTS** | `perf-optimizer`, `orchestrator` |
+| **SKILLS** | `perf-optimizer`, `server-ops`, `smart-router` |
+
+// turbo — telemetry: phase-4-cache
+
+Backend caching:
+- Redis cache-aside pattern
+- TTL strategy per data volatility
+- Target: >80% cache hit rate
+
+Frontend optimization:
+- Code splitting and lazy loading
+- Image optimization (WebP, lazy load)
+- CDN configuration (Cloudflare/Vercel)
+- HTTP caching headers
+
+### Phase 5: Load Testing & Validation
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Optimized application from Phase 4 |
+| **OUTPUT** | Load test results: before/after comparison, go/no-go |
+| **AGENTS** | `perf-optimizer`, `learner` |
+| **SKILLS** | `perf-optimizer`, `problem-checker`, `knowledge-compiler` |
+
+// turbo — telemetry: phase-5-loadtest
+
+1. Run realistic user scenarios at target scale
+2. Compare before/after metrics
+3. If regression detected ? `recovery` restores checkpoint
+4. If improved ? `learner` logs patterns
+
+---
+
+## ? MANDATORY: Problem Verification Before Completion
+
+> **CRITICAL:** This check MUST be performed before any `notify_user` or task completion.
+
+### Check @[current_problems]
+
+```
+1. Read @[current_problems] from IDE
+2. If errors/warnings > 0:
+   a. Auto-fix: imports, types, lint errors
+   b. Re-check @[current_problems]
+   c. If still > 0 ? STOP ? Notify user
+3. If count = 0 ? Proceed to completion
+```
+
+### Auto-Fixable
+
+| Type | Fix |
+|------|-----|
+| Missing import | Add import statement |
+| Unused variable | Remove or prefix `_` |
+| Type mismatch | Fix type annotation |
+| Lint errors | Run eslint --fix |
+
+> **Rule:** Never mark complete with errors in `@[current_problems]`.
+
+---
+
+## ?? Rollback & Recovery
+
+If performance optimization causes regression, breaks functionality, or ruins benchmarks:
+1. Revert to safe checkpoint using `recovery` meta-agent immediately.
+2. Discard unoptimized caching layers or breaking query rewrites.
+3. Log failure reason via `learner`.
+
+---
+
+## Output Format
+
+```markdown
+## ? Performance Optimization Complete
+
+### Improvements
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| p95 Latency | 850ms | 180ms | 79% faster |
+| DB Load | 1000 qps | 150 qps | 85% reduction |
+| Cache Hit | 0% | 85% | New caching |
+| Bundle Size | 1.2MB | 380KB | 68% smaller |
+
+### Changes Applied
+
+| Area | Change | Impact |
+|------|--------|--------|
+| Database | Added indexes, fixed N+1 | ? 95% faster |
+| Cache | Redis + CDN | ? 85% hit rate |
+| Frontend | Code splitting | ? 68% smaller |
+
+### Load Test Result
+
+| Metric | Target | Actual | Status |
+|--------|--------|--------|--------|
+| p95 | <200ms | 180ms | ? |
+| Error rate | <0.5% | 0.2% | ? |
+| Concurrent | 5,000+ | 5,000 | ? |
+
+### Next Steps
+
+- [ ] Run `/validate` for extended test coverage
+- [ ] Run `/monitor` to track production metrics
+- [ ] Run `/launch` to deploy optimized version
+```
+
+---
+
+## Examples
+
+```
+/optimize my-slow-api
+/optimize checkout flow target p95 < 200ms
+/optimize production app 10K users
+/optimize frontend bundle size reduction
+/optimize database queries for user service
+```
+
+---
+
+## Key Principles
+
+- **Profile before optimizing** — measure first, don't guess bottlenecks
+- **Database first** — fix queries and indexes before adding caching
+- **Cache second** — add Redis/CDN after database is optimized
+- **Validate with load tests** — prove improvements with realistic traffic
+- **Rollback on regression** — if metrics worsen, restore immediately
+
+---
+
+## ?? Workflow Chain
+
+**Skills Loaded (7):**
+
+- `perf-optimizer` - Performance profiling, Core Web Vitals, bundle analysis
+- `data-modeler` - Database query optimization, index recommendations
+- `server-ops` - Redis caching, CDN, cache-aside patterns
+- `context-engineering` - Codebase parsing and context extraction
+- `smart-router` - Dynamic agent routing for backend/frontend
+- `problem-checker` - IDE problem verification
+- `knowledge-compiler` - Learning and logging optimization patterns
+
+```mermaid
+graph LR
+    A["/diagnose"] --> B["/optimize"]
+    B --> C["/validate"]
+    C --> D["/launch"]
+    style B fill:#10b981
+```
+
+| After /optimize | Run | Purpose |
+|----------------|-----|---------|
+| Validate results | `/validate` | Run full test suite |
+| Ready to deploy | `/launch` | Deploy optimized version |
+| Track metrics | `/monitor` | Setup production monitoring |
+
+**Handoff to /validate:**
+
+```markdown
+? Optimization complete! Latency: [before]ms ? [after]ms ([X]% faster).
+Run `/validate` to verify at scale or `/launch` to deploy.
+```

package/.agent/workflows/plan.md

@@ -0,0 +1,278 @@
+---
+description: Project blueprint generator — requirements discovery, architecture decisions, hierarchical task breakdown, agent assignment, and PLAN.md creation without writing code.
+skills: [idea-storm, project-planner, system-design, context-engineering, problem-checker, knowledge-compiler]
+agents: [orchestrator, assessor, recovery, learner, project-planner]
+---
+
+# /plan - Project Blueprint
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Create comprehensive project plans with task breakdown, architecture decisions, tech stack selection, and agent assignments — generating `docs/PLAN-{slug}.md` as the execution blueprint. **Differs from `/think` (explores options) and `/build` (writes code) by producing planning artifacts only — NO CODE.** Uses `project-planner` with `project-planner` skill for task decomposition and `idea-storm` for requirements discovery.
+
+---
+
+## ?? Meta-Agents Integration
+
+| Phase | Agent | Action |
+| ----- | ----- | ------ |
+| **Pre-Flight** | `assessor` | Evaluate planning scope, risks, and knowledge-compiler context |
+| **Execution** | `orchestrator` | Coordinate requirements, architecture, and task breakdown |
+| **Safety** | `recovery` | Save state and recover from planning failures |
+| **Post-Plan** | `learner` | Log architecture decisions and planning patterns |
+
+```
+Flow:
+requirements ? architecture ? task breakdown
+       ?
+assessor.evaluate(plan_risk)
+       ?
+agent assignment ? PLAN.md ? learner.log()
+       ?
+handoff to /build
+```
+
+---
+
+## ?? MANDATORY: 4-Phase Planning Protocol
+
+### Phase 1: Pre-flight & knowledge-compiler Context
+
+> **Rule 0.5-K:** knowledge-compiler pattern check.
+
+1. Read `.agent/skills/knowledge-compiler/patterns/` for past failures before proceeding.
+2. Trigger `recovery` agent to run Checkpoint (`git commit -m "chore(checkpoint): pre-plan"`).
+
+### Phase 2: Requirements Discovery
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | $ARGUMENTS (project description) |
+| **OUTPUT** | Requirements doc: goal, users, features, constraints |
+| **AGENTS** | `project-planner`, `assessor` |
+| **SKILLS** | `idea-storm`, `context-engineering` |
+
+// turbo — telemetry: phase-2-requirements
+
+Ask if not provided:
+
+| Question | Purpose |
+|----------|---------|
+| What is the GOAL? | One sentence objective |
+| Who are the USERS? | Target persona |
+| MUST-HAVE features? | 3-5 core items |
+| NICE-TO-HAVE? | Optional features |
+| TIMELINE? | Deadline or estimate |
+| CONSTRAINTS? | Budget, tech, team |
+
+### Phase 3: Architecture Decision
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Requirements from Phase 2 |
+| **OUTPUT** | Tech stack decisions with rationale, architecture diagram |
+| **AGENTS** | `project-planner`, `orchestrator` |
+| **SKILLS** | `system-design`, `project-planner` |
+
+// turbo — telemetry: phase-3-architecture
+
+| Decision | Options | Selection Criteria |
+|----------|---------|-------------------|
+| Frontend | Next.js / Vite / Remix / Astro | SSR needs, SEO, complexity |
+| Backend | Hono / Express / FastAPI / NestJS | Scale, team, language |
+| Database | PostgreSQL / MongoDB / Supabase | Structure, scale, cost |
+| Auth | Clerk / NextAuth / Custom | Speed, features, budget |
+| Hosting | Vercel / Railway / AWS | Scale, budget, complexity |
+
+Architecture patterns:
+
+| Pattern | When | Complexity |
+|---------|------|-----------|
+| **Monolith** | MVP, small team | Low |
+| **Modular Monolith** | Growing team, future split | Medium |
+| **Serverless** | Event-driven, variable load | Medium |
+| **Microservices** | Large team, independent scaling | High |
+
+Generate C4 architecture diagram (mermaid) and ADR for key decisions.
+
+### Phase 4: Task Breakdown
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Architecture decisions from Phase 3 |
+| **OUTPUT** | Hierarchical task list: Epics ? Stories ? Tasks ? Subtasks |
+| **AGENTS** | `project-planner` |
+| **SKILLS** | `project-planner` |
+
+// turbo — telemetry: phase-4-breakdown
+
+```
+Level 1: Epics (major features)
+Level 2: Stories (user-facing items)
+Level 3: Tasks (technical work)
+Level 4: Subtasks (atomic units)
+```
+
+### Phase 5: Agent Assignment & Plan Generation
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Task breakdown from Phase 4 |
+| **OUTPUT** | `docs/PLAN-{slug}.md` with execution plan |
+| **AGENTS** | `project-planner`, `learner` |
+| **SKILLS** | `project-planner`, `problem-checker`, `knowledge-compiler` |
+
+// turbo — telemetry: phase-5-generate
+
+1. Assign agents to tasks based on capability:
+
+| Task Type | Agent | Skill |
+|-----------|-------|-------|
+| Schema design | `data-modeler` | `data-modeler` |
+| API routes | `nodejs-pro` | `nodejs-pro` |
+| UI components | `react-pro` | `react-pro` |
+| Tests | `test-architect` | `test-architect` |
+
+2. `assessor` evaluates architecture risk
+3. Generate `docs/PLAN-{slug}.md`
+
+---
+
+## ? MANDATORY: Problem Verification Before Completion
+
+> **CRITICAL:** This check MUST be performed before any `notify_user` or task completion.
+
+### Check @[current_problems]
+
+```
+1. Read @[current_problems] from IDE
+2. If errors/warnings > 0:
+   a. Auto-fix: imports, types, lint errors
+   b. Re-check @[current_problems]
+   c. If still > 0 ? STOP ? Notify user
+3. If count = 0 ? Proceed to completion
+```
+
+> **Note:** /plan produces markdown artifacts, not code. This check applies to any generated config or schema files.
+
+---
+
+## ?? Rollback & Recovery
+
+If planning produces an invalid architecture or overwrites an existing valid PLAN.md:
+1. Revert the file changes using `recovery` meta-agent.
+2. Review past architecture decisions through `learner`.
+3. Prompt for correct requirements before generating the plan again.
+
+---
+
+## Output Format
+
+Generated file: `docs/PLAN-{slug}.md`
+
+```markdown
+## ?? Plan: [Project Name]
+
+### Overview
+
+| Aspect | Value |
+|--------|-------|
+| Goal | [One sentence] |
+| Timeline | [X days/weeks] |
+| Complexity | Low / Medium / High |
+| Agents | [Count] assigned |
+
+### Stack Decision
+
+| Layer | Choice | Rationale |
+|-------|--------|-----------|
+| Frontend | Next.js 15 | SSR, Vercel integration |
+| Backend | Hono | Type-safe, edge |
+| Database | PostgreSQL | Structured, scalable |
+
+### Architecture
+
+[Mermaid C4 diagram]
+
+### Task Breakdown
+
+- [ ] Epic 1: [Feature]
+  - [ ] Story 1.1: [Description]
+    - [ ] Task 1.1.1: [Work item]
+
+### Agent Execution Plan
+
+| Phase | Agent | Task | Duration |
+|-------|-------|------|----------|
+| 1 | `data-modeler` | Schema | 30m |
+| 2 | `nodejs-pro` | API | 2h |
+| 3 | `react-pro` | UI | 3h |
+| 4 | `test-architect` | Tests | 1h |
+
+### Next Steps
+
+- [ ] Review architecture decisions
+- [ ] Approve plan
+- [ ] Run `/build` to start implementation
+```
+
+---
+
+## Examples
+
+```
+/plan e-commerce site with cart and checkout
+/plan REST API for user management
+/plan mobile fitness app with tracking
+/plan SaaS dashboard with analytics
+/plan microservices architecture for fintech
+```
+
+---
+
+## Key Principles
+
+- **No code** — /plan produces planning artifacts only, never implementations
+- **Ask before assuming** — clarify requirements with Socratic questions
+- **Decisions with rationale** — every tech choice must explain WHY
+- **Atomic tasks** — break down to the smallest executable unit
+- **Agent-ready** — assign agents so `/build` can execute immediately
+
+---
+
+## ?? Workflow Chain
+
+**Skills Loaded (6):**
+
+- `idea-storm` - Socratic questioning and requirements clarification
+- `project-planner` - Task breakdown and dependency planning
+- `system-design` - Architecture decision-making framework
+- `context-engineering` - Codebase parsing and context extraction
+- `problem-checker` - Generated config and schema problem verification
+- `knowledge-compiler` - Learning and logging planning patterns
+
+```mermaid
+graph LR
+    A["/think"] --> B["/plan"]
+    B --> C["/build"]
+    C --> D["/validate"]
+    style B fill:#10b981
+```
+
+| After /plan | Run | Purpose |
+|------------|-----|---------|
+| Plan approved | `/build` | Start implementation |
+| Complex project | `/autopilot` | Full orchestration |
+| Need more thinking | `/think` | Explore alternatives |
+
+**Handoff to /build:**
+
+```markdown
+?? Plan created: docs/PLAN-{slug}.md
+Stack: [stack]. Tasks: [count]. Agents: [count].
+Review and run `/build` to start implementation.
+```