agent-skill-kit 3.9.135

package/.agent/workflows/stage.md

@@ -0,0 +1,286 @@
+---
+description: Local development sandbox — auto-detect services, orchestrate multi-service startup with dependency ordering, resolve port conflicts, integrate Docker Compose, and monitor health.
+skills: [server-ops, cicd-pipeline, context-engineering, problem-checker, knowledge-compiler]
+agents: [orchestrator, assessor, recovery, learner, devops-engineer]
+---
+
+# /stage - Development Sandbox
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Manage local development environments with multi-service orchestration — auto-detect project type, start/stop services with dependency ordering, resolve port conflicts, integrate Docker Compose for infrastructure, and monitor service health. **Differs from `/launch` (production deployment) and `/monitor` (production observability) by focusing on local development sandbox management with hot-reload and debugging support.** Uses `cicd-pipeline` with `server-ops` for service management.
+
+---
+
+## ?? Meta-Agents Integration
+
+| Phase | Agent | Action |
+| ----- | ----- | ------ |
+| **Pre-Flight** | `assessor` | Evaluate environment, ports, and knowledge-compiler context |
+| **Execution** | `orchestrator` | Coordinate service startup and dependency ordering |
+| **Safety** | `recovery` | Save state and recover/rollback from service startup failures |
+| **Post-Stage** | `learner` | Log sandbox execution telemetry and port patterns |
+
+```
+Flow:
+recovery.save(server_state) ? detect(project) ? resolve(ports)
+       ?
+assessor.evaluate(port_conflicts) ? start(services)
+       ?
+health_check ? learner.log(config)
+```
+
+---
+
+## Sub-Commands
+
+| Command | Action |
+|---------|--------|
+| `/stage` | Show status of all services |
+| `/stage start` | Start all services (smart detection) |
+| `/stage start frontend` | Start specific service |
+| `/stage stop` | Stop all services |
+| `/stage restart` | Restart all / specific service |
+| `/stage check` | Health check all services |
+| `/stage logs` | Tail logs (all or specific) |
+| `/stage logs api --filter error` | Filter logs |
+| `/stage ports` | Show port allocation map |
+| `/stage docker` | Start Docker Compose stack |
+| `/stage docker down` | Stop Docker services |
+| `/stage docker --profile infra` | Start only infrastructure |
+| `/stage start --debug` | Start with debugging enabled |
+
+---
+
+## ?? MANDATORY: Development Sandbox 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-stage"`).
+
+### Phase 2: Environment Detection
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | $ARGUMENTS (sub-command + optional service name) |
+| **OUTPUT** | Project type, detected services, port assignments |
+| **AGENTS** | `cicd-pipeline`, `assessor` |
+| **SKILLS** | `server-ops`, `context-engineering` |
+
+// turbo — telemetry: phase-2-detect
+
+Auto-detect project type:
+
+| Detected File | Service | Default Port | Start Command |
+|--------------|---------|-------------|---------------|
+| `next.config.*` | Next.js | 3000 | `npm run dev` |
+| `vite.config.*` | Vite | 5173 | `npm run dev` |
+| `nuxt.config.*` | Nuxt | 3000 | `npm run dev` |
+| `package.json` (scripts.dev) | Node.js | 3001 | `npm run dev` |
+| `manage.py` | Django | 8000 | `python manage.py runserver` |
+| `main.py` / `app.py` | FastAPI/Flask | 8000 | `uvicorn app:app --reload` |
+| `docker-compose.yml` | Docker Stack | varies | `docker compose up` |
+| `prisma/schema.prisma` | Database | 5432 | `npx prisma studio` |
+
+Monorepo detection:
+```
+apps/web/    ? Frontend (port 3000)
+apps/api/    ? Backend (port 3001)
+packages/db/ ? Database service
+```
+
+### Phase 3: Port Resolution & Service Start
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Detected services from Phase 2 |
+| **OUTPUT** | Running services with resolved ports |
+| **AGENTS** | `cicd-pipeline`, `orchestrator` |
+| **SKILLS** | `server-ops` |
+
+// turbo — telemetry: phase-3-start
+
+Port allocation:
+
+| Service | Default | Fallback Range |
+|---------|---------|---------------|
+| Frontend | 3000 | 3000-3009 |
+| Backend API | 3001 | 3010-3019 |
+| PostgreSQL | 5432 | — |
+| Redis | 6379 | — |
+| Prisma Studio | 5555 | 5555-5559 |
+| Storybook | 6006 | 6006-6009 |
+
+Conflict resolution:
+```
+Port in use?
++-- OUR process? ? Reuse (already running)
++-- Another dev server? ? Offer kill or next port
++-- System service? ? Use fallback
+```
+
+Startup order (respecting dependencies):
+```
+1. Infrastructure  ? Database, Redis, Queue
+2. Backend         ? API server, Workers
+3. Frontend        ? Next.js / Vite dev server
+4. Tools           ? Prisma Studio, Storybook
+```
+
+Docker hybrid mode (recommended):
+- **Docker:** Database + Redis + Mailhog (stable infra)
+- **Local:** Frontend + Backend (fast HMR, better debugging)
+
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:stage" TRACE_ID="$TRACE_ID" node .agent/scripts/auto_preview.ts start
+```
+
+### Phase 4: Health Monitoring
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Running services from Phase 3 |
+| **OUTPUT** | Health status dashboard, auto-restart on crash |
+| **AGENTS** | `learner` |
+| **SKILLS** | `server-ops`, `problem-checker`, `knowledge-compiler` |
+
+// turbo — telemetry: phase-4-health
+
+Health gates:
+
+| Service | Wait For | Health Check |
+|---------|----------|-------------|
+| Database | — | TCP port open |
+| Redis | — | `PING ? PONG` |
+| API Server | Database, Redis | `GET /health ? 200` |
+| Frontend | API Server | `GET / ? 200` |
+
+Auto-restart on crash: 3 retry attempts with error logging.
+
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:stage" TRACE_ID="$TRACE_ID" node .agent/scripts/auto_preview.ts status
+```
+
+---
+
+## ? 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:** /stage manages services, not code. Problems are reported along with service health.
+
+---
+
+## ?? Rollback & Recovery
+
+If port orchestration fails or Docker containers hang:
+1. Trigger `recovery` meta-agent to run `docker compose down` and kill dangling Node/Python processes on target ports.
+2. Automatically select random fallback ports instead of interactive resolution.
+3. Restart safe baseline infrastructure without application services.
+
+---
+
+## Output Format
+
+```markdown
+## ?? Stage Status
+
+### Services
+
+| Service | Port | Health | Mode |
+|---------|------|--------|------|
+| Frontend | 3000 | ? OK | Local |
+| API | 3001 | ? OK | Local |
+| PostgreSQL | 5432 | ? OK | Docker |
+| Redis | 6379 | ? OK | Docker |
+
+### URLs
+
+| Service | URL |
+|---------|-----|
+| Frontend | http://localhost:3000 |
+| API | http://localhost:3001 |
+| Prisma Studio | http://localhost:5555 |
+
+### Next Steps
+
+- [ ] Test: http://localhost:3000
+- [ ] Run `/validate` for tests
+- [ ] Deploy with `/launch`
+```
+
+---
+
+## Examples
+
+```
+/stage
+/stage start
+/stage start --debug
+/stage stop
+/stage restart backend
+/stage check
+/stage docker --profile infra
+```
+
+---
+
+## Key Principles
+
+- **Auto-detect** — smart project type detection, zero config needed
+- **Dependency ordering** — start infra before backend before frontend
+- **Docker for infra, local for code** — hybrid mode for best DX
+- **Port conflict resolution** — never fail on port collision, auto-resolve
+- **Health gates** — verify each service before starting dependents
+
+---
+
+## ?? Workflow Chain
+
+**Skills Loaded (5):**
+
+- `server-ops` - Service management, process control, port management
+- `cicd-pipeline` - Docker Compose integration
+- `context-engineering` - Codebase parsing and environment detection
+- `problem-checker` - Service problem verification
+- `knowledge-compiler` - Learning and logging sandbox patterns
+
+```mermaid
+graph LR
+    A["/build"] --> B["/stage"]
+    B --> C["/validate"]
+    style B fill:#10b981
+```
+
+| After /stage | Run | Purpose |
+|-------------|-----|---------|
+| Services running | `/validate` | Test against live services |
+| Service crashing | `/diagnose` | Debug service failures |
+| All tests pass | `/launch` | Deploy to production |
+
+**Handoff to /validate:**
+
+```markdown
+?? Stage running! Services: [count] active on ports [ports].
+Run `/validate` to test against live services.
+```

package/.agent/workflows/studio.md

@@ -0,0 +1,276 @@
+---
+description: AI-powered design system generator — 50+ styles, 97 color palettes, 57 font pairings, and anti-AI-slop intelligence across 10 technology stacks with searchable database.
+skills: [studio, design-system, frontend-design, idea-storm, context-engineering, problem-checker, knowledge-compiler]
+agents: [orchestrator, assessor, recovery, learner, frontend-specialist]
+---
+
+# /studio - Design Intelligence
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Generate comprehensive design systems for web and mobile applications — 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and chart recommendations across 10 technology stacks with AI-powered searchable database. **Differs from `/build` (implements full apps) and `/plan` (creates task breakdown) by focusing exclusively on design system generation and UI quality standards with anti-AI-slop intelligence.** Uses `react-pro` with `studio` for design search and `design-system` for color theory and typography.
+
+---
+
+## ?? Meta-Agents Integration
+
+| Phase | Agent | Action |
+| ----- | ----- | ------ |
+| **Pre-Flight** | `assessor` | Evaluate design risks and knowledge-compiler UX patterns |
+| **Execution** | `orchestrator` | Coordinate style selection, search, and UI generation |
+| **Safety** | `recovery` | Save state checkpoint before design system implementation |
+| **Post-Design** | `learner` | Log successful design decisions and slop patterns |
+
+```
+Flow:
+learner.analyze(past_designs) ? recommendations
+       ?
+search(product, style, color, typography) ? design system
+       ?
+verify(accessibility, contrast) ? learner.log(patterns)
+```
+
+---
+
+## ?? MANDATORY: Design System 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-studio"`).
+
+### Phase 2: Requirements Analysis
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | $ARGUMENTS (UI/UX request with product type, style, industry) |
+| **OUTPUT** | Extracted requirements: product type, style keywords, industry, stack |
+| **AGENTS** | `react-pro`, `assessor` |
+| **SKILLS** | `studio`, `idea-storm`, `context-engineering` |
+
+// turbo — telemetry: phase-2-requirements
+
+Extract from user request:
+
+| Extract | Examples |
+|---------|---------|
+| Product type | SaaS, e-commerce, portfolio, dashboard, landing page |
+| Style keywords | minimal, playful, professional, elegant, dark mode |
+| Industry | healthcare, fintech, gaming, education, beauty |
+| Stack | html-tailwind (default), react, nextjs, vue, svelte |
+
+### Phase 3: Design System Generation
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Requirements from Phase 2 |
+| **OUTPUT** | Complete design system: pattern, style, colors, typography, effects |
+| **AGENTS** | `react-pro`, `orchestrator` |
+| **SKILLS** | `studio`, `design-system` |
+
+// turbo — telemetry: phase-3-generation
+
+1. Generate design system (always start here):
+
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:studio" TRACE_ID="$TRACE_ID" node .agent/skills/studio/scripts/search.ts "<product_type> <industry> <keywords>" --design-system -p "Project Name"
+```
+
+2. Optionally persist for hierarchical retrieval:
+
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:studio" TRACE_ID="$TRACE_ID" node .agent/skills/studio/scripts/search.ts "<query>" --design-system --persist -p "Project Name"
+```
+
+Creates `design-system/MASTER.md` + optional `design-system/pages/<page>.md` overrides.
+
+3. Supplement with domain searches as needed:
+
+| Need | Domain | Command |
+|------|--------|---------|
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Chart types | `chart` | `--domain chart "real-time dashboard"` |
+| UX guidelines | `ux` | `--domain ux "animation accessibility"` |
+| Font alternatives | `typography` | `--domain typography "elegant luxury"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+
+Available domains: `product`, `style`, `typography`, `color`, `landing`, `chart`, `ux`, `react`, `web`, `prompt`
+
+### Phase 4: Stack Guidelines & Implementation
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Design system from Phase 3 |
+| **OUTPUT** | Stack-specific implementation guidelines |
+| **AGENTS** | `react-pro` |
+| **SKILLS** | `studio`, `design-system` |
+
+// turbo — telemetry: phase-4-implementation
+
+// turbo
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:studio" TRACE_ID="$TRACE_ID" node .agent/skills/studio/scripts/search.ts "<keyword>" --stack html-tailwind
+```
+
+Available stacks: html-tailwind, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, react-native, `flutter`, `shadcn`, jetpack-compose
+
+### Phase 5: Pre-Delivery Verification
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Implemented UI from Phase 4 |
+| **OUTPUT** | Verified design: accessibility, contrast, responsiveness |
+| **AGENTS** | `react-pro`, `learner` |
+| **SKILLS** | `design-system`, `design-system`, `problem-checker`, `knowledge-compiler` |
+
+// turbo — telemetry: phase-5-verification
+
+Pre-delivery checklist:
+
+| Category | Checks |
+|----------|--------|
+| Visual | No emoji icons (use SVG), consistent icon set, correct brand logos |
+| Interaction | cursor-pointer on clickable, hover feedback, smooth transitions (150-300ms) |
+| Contrast | Light mode text =4.5:1, glass elements visible, borders in both modes |
+| Layout | Floating navbar spacing, no hidden content, responsive (375-1440px) |
+| Accessibility | Alt text, labeled inputs, color not sole indicator, prefers-reduced-motion |
+
+---
+
+## ? 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 `_` |
+| Lint errors | Run eslint --fix |
+| CSS issues | Fix class names, contrast |
+
+> **Rule:** Never mark complete with errors in `@[current_problems]`.
+
+---
+
+## ?? Rollback & Recovery
+
+If AI generates slop, inconsistent patterns, or hallucinates styling components:
+1. Revert UI file changes using `recovery` meta-agent.
+2. Provide feedback to `learner` about specific styling failures (e.g., bad contrast, unwanted emojis).
+3. Retry Phase 2 with more restrictive style constraints or specific domain filters.
+
+---
+
+## Output Format
+
+```markdown
+## ?? Design System: [Project Name]
+
+### Configuration
+
+| Setting | Value |
+|---------|-------|
+| Product | [type] |
+| Style | [style name] |
+| Stack | html-tailwind |
+
+### Design Tokens
+
+| Token | Value |
+|-------|-------|
+| Primary | [color] |
+| Typography | [font pairing] |
+| Effects | [style effects] |
+
+### Quality Check
+
+| Check | Status |
+|-------|--------|
+| Accessibility | ? WCAG AA |
+| Responsive | ? 375-1440px |
+| Dark mode | ? Contrast verified |
+
+### Next Steps
+
+- [ ] Review design system
+- [ ] Run `/build` to implement
+- [ ] Run `/validate` for accessibility audit
+```
+
+---
+
+## Examples
+
+```
+/studio SaaS dashboard with dark mode
+/studio e-commerce product page elegant
+/studio healthcare portal accessible
+/studio fintech crypto modern
+/studio beauty spa wellness landing page
+```
+
+---
+
+## Key Principles
+
+- **Design system first** — always generate `--design-system` before implementation
+- **Anti-AI-slop** — no emoji icons, no generic colors, no layout shifts on hover
+- **Accessibility mandatory** — WCAG AA contrast, keyboard navigation, alt text
+- **Persist for consistency** — use `--persist` for multi-page projects
+- **SVG icons only** — use Heroicons/Lucide, never emoji as UI elements
+
+---
+
+## ?? Workflow Chain
+
+**Skills Loaded (7):**
+
+- `studio` - 50+ styles, 97 color palettes, 57 font pairings, searchable database
+- `design-system` - Color theory, typography, visual effects
+- `design-system` - Anti-AI-slop aesthetics and bold design
+- `idea-storm` - Requirements clarification
+- `context-engineering` - Codebase parsing and context extraction
+- `problem-checker` - Code problem verification
+- `knowledge-compiler` - Learning and logging design patterns
+
+```mermaid
+graph LR
+    A["/plan"] --> B["/studio"]
+    B --> C["/build"]
+    C --> D["/validate"]
+    style B fill:#ec4899
+```
+
+| After /studio | Run | Purpose |
+|--------------|-----|---------|
+| Design ready | `/build` | Implement the design |
+| Need review | `/inspect` | Code review |
+| Ready to ship | `/launch` | Deploy |
+
+**Handoff to /build:**
+
+```markdown
+?? Design system generated! Style: [style], Palette: [palette], Fonts: [fonts].
+Run `/build` to implement the UI.
+```