@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/SKILL.md

@@ -0,0 +1,512 @@
+---
+name: fullstack-developer
+description: |
+  Full-stack development with complete workflow and multi-skill orchestration.
+
+  Use when:
+  - Building new features (frontend + backend + database)
+  - Implementing API endpoints with database changes
+  - Architecture design and project bootstrap
+  - Any development requiring multiple tech domains
+
+  Key Features:
+  - 🔴 Phase 1: Mandatory requirements analysis with `product-requirements`
+  - 🔴 Phase 2: Feasibility analysis + multi-solution design
+  - 🔴 Phase 3: Detailed plan with skill assignments
+  - 🔴 Phase 4: Development with mandatory testing after each task
+  - 🔴 Phase 5: Comprehensive testing (unit + API + web automation)
+  - 🔴 Phase 6: Mandatory code-review → bug-fixing loop
+
+  Flow: Requirements → Feasibility → Plan → Develop+Test → Review → Ship
+allowed-tools: [read, write, execute, grep, glob, mcp__serena__find_symbol, mcp__serena__find_referencing_symbols, mcp__serena__get_symbols_overview]
+---
+
+# Full-Stack Developer
+
+Incremental development. UX-first, async by default. **Review-driven quality.**
+
+## The Iron Law
+
+```
+NO DEVELOPMENT WITHOUT REQUIREMENTS. NO TASK WITHOUT TEST. NO SHIP WITHOUT REVIEW.
+NO SKILL CALL WITHOUT ISOLATION. NO PROGRESS WITHOUT TRACKING.
+```
+
+- **需求先行**: 所有任务必须先用 `product-requirements` 分析需求
+- **测试闭环**: 每个任务完成后必须测试
+- **审查强制**: 开发完成后必须 `code-review`，发现问题必须 `bug-fixing`
+- **上下文隔离**: 每个 skill 使用 Subagent 隔离执行，防止污染
+- **进度追踪**: 维护进度追踪文档，防止遗漏
+
+---
+
+## 🔴🔴🔴 Complete Development Workflow (MANDATORY)
+
+### Phase 1: 需求分析 (FIRST!)
+
+**调用**: `product-requirements`
+
+```markdown
+## 需求分析输出
+- 核心目标: [用户真正想解决的问题]
+- 功能需求: [需求列表 + 优先级]
+- 验收标准: [Gherkin 格式]
+```
+
+### Phase 2: 可行性分析 + 多方案设计
+
+**使用 MCP serena 工具分析代码库，提供 2-3 个方案:**
+
+```markdown
+## 方案对比
+| 方案 | 描述 | 难度 | 优点 | 缺点 |
+|------|------|------|------|------|
+| A | ... | 低/中/高 | ... | ... |
+| B | ... | 低/中/高 | ... | ... |
+
+请选择：
+- [ ] A: [方案A]
+- [ ] B: [方案B]
+- [ ] 其他：___
+```
+
+### Phase 3: 详细计划制定
+
+**用户选择后，制定任务分解计划，明确每个任务调用的 Skills:**
+
+```markdown
+## 实施计划
+| # | 任务 | 调用 Skills | 测试类型 |
+|---|------|-------------|----------|
+| 1 | 数据库设计 | `database-migrations` | 单元测试 |
+| 2 | API 开发 | `api-scaffolding` + `api-testing-observability` | 接口测试 |
+| 3 | 前端页面 | `frontend-design` | Web 自动化 |
+```
+
+### Phase 4: 开发执行 + 即时测试 (Context Isolated)
+
+**🔴 使用 Subagent 隔离执行，防止上下文污染:**
+
+```
+For each task:
+1. 读取进度追踪 → 确认当前任务
+2. Task(subagent) → 执行 skill (隔离上下文)
+3. 记录输出 → 更新进度
+4. 读取计划 → 确认下一任务
+5. 每 2-3 任务 → 目标对齐检查
+```
+
+**任务完成确认:**
+```markdown
+## Task X 完成确认
+- 调用 Skills: [...]
+- 修改文件: [...]
+- 测试结果: ✅/❌
+- 下一步: Task Y
+```
+
+→ 隔离协议: `references/context-isolation-protocol.md`
+
+### Phase 5: 综合测试
+
+| 开发类型 | 必须测试 | 调用 Skills |
+|----------|----------|-------------|
+| 后端逻辑 | 单元测试 | `test-driven-development` |
+| API 接口 | 接口测试 | `api-testing-observability` |
+| 前端页面 | Web 自动化 | `webapp-testing` |
+
+### Phase 6: 代码审查 + 修复 (MANDATORY)
+
+```
+code-review → 发现问题? → bug-fixing → 返回 code-review → 循环直到通过
+```
+
+→ 完整流程: `references/complete-development-workflow.md`
+
+---
+
+## 🔴 技能路由表 (Skill Router)
+
+| 任务类型 | 调用 Skills |
+|----------|-------------|
+| 需求分析 | `product-requirements` |
+| API 开发 | `api-scaffolding` + `api-testing-observability` |
+| 数据库 | `database-migrations` |
+| 前端 UI | `frontend-design` + `react-best-practices` |
+| UI 审查 | `web-design-guidelines` |
+| 测试 | `test-driven-development` |
+| 代码审查 | `code-review` |
+| Bug 修复 | `bug-fixing` |
+| 部署 | `vercel-deploy` |
+
+→ 完整路由表: `references/skill-router-table.md`
+
+---
+
+## 🔴 开发规范引用 (避免常见问题)
+
+**开发时必须遵循以下规范，避免引入常见 bug:**
+
+| 规范类型 | 引用路径 |
+|----------|----------|
+| 通用模式 | `../code-review/references/common-patterns.md` |
+| 后端问题 | `../code-review/references/backend-common-issues.md` |
+| 前端问题 | `../code-review/references/frontend-common-issues.md` |
+| 隐藏 Bug | `../code-review/references/hidden-bugs-detection.md` |
+| 分层检查 | `../code-review/references/layered-checklist-protocol.md` |
+| 常见 Bug | `../bug-fixing/references/common-bugs.md` |
+| Bug 指南 | `../bug-fixing/references/bug-guide.md` |
+| 修复清单 | `../bug-fixing/references/fix-completeness-checklist.md` |
+
+---
+
+## Development Workflow
+
+```
+需求输入
+       │
+       ▼
+┌──────────────────────────────────────────────────────┐
+│ Phase 0: Tech Research (MANDATORY)                   │
+│ ─────────────────────────────────────────────────────│
+│ 1. Identify platform, framework, build system        │
+│ 2. Verify API availability (official docs only)      │
+│ 3. Check platform-specific requirements              │
+│ 4. 🔄 Query skill router → determine skills          │
+└──────────────────────────────────────────────────────┘
+       │
+       ▼
+┌──────────────────────────────────────────────────────┐
+│ Development Phases + Skill Triggers                  │
+│ ─────────────────────────────────────────────────────│
+│ UI/UX? → 🔴 `frontend-design` (MANDATORY)            │
+│ Database? → 🔴 `database-migration` (MANDATORY)      │
+│ API? → `api-design-principles`                       │
+│ AI/LLM? → `langchain-architecture` + `rag-implementation`│
+│ Testing? → `python-testing-patterns` / `javascript-testing-patterns`│
+└──────────────────────────────────────────────────────┘
+       │
+       ▼
+┌──────────────────────────────────────────────────────┐
+│ Quality Gates (MANDATORY)                            │
+│ ─────────────────────────────────────────────────────│
+│ 1. Format + Lint → fix P0/P1                         │
+│ 2. 🔴 `code-review` → issues? → `bug-fixing` → loop  │
+│ 3. Real environment test                             │
+└──────────────────────────────────────────────────────┘
+       │
+       ▼
+    Ship Ready ✅
+```
+
+---
+
+## 🔴 Phase 0: Tech Stack Research (MANDATORY)
+
+**Why**: Many features require rework because implementation uses APIs that don't exist in target platform.
+
+### Step 0.1: Platform & Framework Identification
+
+| Aspect | Identify | Impact |
+|--------|----------|--------|
+| **Platform Type** | Web / Desktop (Tauri/Electron) / Mobile (React Native) | Different APIs, security models |
+| **Framework Versions** | React 18 vs 19, Tauri v1 vs v2, Vue 2 vs 3 | Breaking changes, new patterns |
+| **Backend Runtime** | Node.js / Python / Rust / Go | Different IPC patterns |
+| **State Management** | Redux / Zustand / Pinia | Different patterns for updates |
+| **Build System** | Vite / Webpack / Turbopack | Plugin compatibility |
+
+### Step 0.2: API Availability Research
+
+**Before writing ANY code that uses external APIs:**
+
+| Check | How to Verify |
+|-------|---------------|
+| API exists | Search **official docs** (not Stack Overflow) |
+| API works in platform | Check platform compatibility |
+| API version match | Check which version introduced the API |
+| Configuration needed | Check security/permission config required |
+
+### 🔴 Step 0.3: Dependency Type Check (Electron/React Native)
+
+**Before installing ANY new dependency:**
+
+| Check | How to Verify | If Native Module |
+|-------|---------------|------------------|
+| Is native module? | `npm info <pkg> | grep -i "gyp\|native"` | Search for pure JS alternative |
+| Has .node files? | Check package contents | Prefer WASM or JS implementation |
+| Needs rebuild? | Check Electron compatibility | Configure electron-rebuild |
+
+**常见纯 JS 替代方案：**
+- SQLite: `sql.js` (替代 better-sqlite3)
+- 图片: `jimp` (替代 sharp)
+- 密码: `bcryptjs` (替代 bcrypt)
+
+### Step 0.3: Research Output Template
+
+```markdown
+## Tech Research for: [Feature Name]
+
+### Platform
+- Type: [Web / Desktop / Mobile / Hybrid]
+- Framework: [version]
+- Build: [build system]
+
+### APIs Needed
+| API | Source | Verified Working | Config Needed |
+|-----|--------|------------------|---------------|
+| ... | ... | ✅/❌ | ... |
+
+### 🔄 Collaborating Skills
+| Skill | Reason | Phase |
+|-------|--------|-------|
+| `frontend-design` | UI components | Phase 2 |
+| `database-migration` | New tables | Phase 1 |
+| ... | ... | ... |
+
+### Risks & Alternatives
+| Risk | Alternative Approach |
+|------|---------------------|
+| ... | ... |
+```
+
+---
+
+## 🔴 Dependency & Integrity Gate (MANDATORY)
+
+**修改代码涉及新依赖时，必须执行：**
+
+| 触发条件 | 必须操作 |
+|----------|----------|
+| 新增 import/require | 检查依赖是否已安装 → 安装 → 更新依赖文件 |
+| 引用新组件/库 | 检查文件是否存在 → 创建缺失文件 |
+| Python 依赖 | 🔴 **必须在虚拟环境中安装** |
+| 🔴 **Electron 依赖** | **检查是否原生模块 → 优先使用纯 JS 替代** |
+| 任务完成前 | 验证依赖安装 + 兼容性检查 + 🔴 **启动测试** |
+
+### 🔴 MCP 依赖兼容性检查 (MANDATORY)
+
+**新增任何依赖前，必须使用 MCP 工具验证兼容性：**
+
+| 检查阶段 | MCP 工具 | 查询内容 | 阻塞条件 |
+|----------|----------|----------|----------|
+| 版本兼容 | `context7` | "[pkg] version requirements node python" | 版本不满足 → **P0** |
+| 环境兼容 | `context7` | "[pkg] browser node electron compatibility" | 环境不支持 → **P0** |
+| 已知问题 | `exa` | "[pkg] known issues bugs conflicts 2024" | 严重问题 → **P1** |
+| 安全漏洞 | `exa` | "[pkg] security vulnerability CVE" | 有漏洞 → **P0** |
+| 依赖冲突 | `exa` | "[pkg] [existing-pkg] version conflict" | 有冲突 → **P0** |
+| 原生模块 | `exa` | "[pkg] native module electron" | 是原生 → 寻找替代 |
+| 许可证 | `context7` | "[pkg] license" | GPL 等限制性 → **P1** |
+
+**完整检查流程:**
+```
+1. 识别需要安装的依赖
+2. context7 查询: 版本要求、平台兼容性
+3. exa 查询: 已知问题、安全漏洞、依赖冲突
+4. 本地验证: npm install --dry-run / pip install --dry-run
+5. 记录兼容性报告
+6. 不兼容 → 寻找替代方案或阻塞
+```
+
+→ 完整协议: `../shared-references/mcp-dependency-compatibility-protocol.md`
+→ 详细流程: `references/dependency-and-integrity-protocol.md`
+
+### 🔴 原生模块选型规则 (Electron/React Native)
+
+| 需求 | ❌ 避免 | ✅ 推荐 |
+|------|--------|--------|
+| SQLite | `better-sqlite3`, `sqlite3` | `sql.js` |
+| 图片处理 | `sharp` | `jimp` |
+| 密码哈希 | `bcrypt` | `bcryptjs` |
+
+→ 详细流程: `references/dependency-and-integrity-protocol.md`
+
+## 🔴 Import Integrity Gate (MANDATORY)
+
+**每个 import 语句必须通过完整性校验：**
+
+| 检查项 | 触发条件 | 后果 |
+|--------|----------|------|
+| 路径解析 | 新增任意 import | P0 - 路径不存在将导致运行时错误 |
+| 环境兼容 | 导入第三方库 | P0 - Node.js 模块在浏览器崩溃 |
+| Barrel 副作用 | 从 index.ts 导入 | P0 - 可能触发环境不兼容模块加载 |
+
+**快速检查**: 从 barrel file 导入时，优先直接从源文件导入。
+
+→ 完整协议: `../shared-references/import-integrity-protocol.md`
+
+---
+
+## 🔴 Change Impact Protocol (MANDATORY)
+
+**Before modifying ANY code:**
+
+1. Identify file(s) to change
+2. Search for all imports/usages
+3. List all features that might be affected
+4. **Data layer check**: Does this affect ORM models/database schema?
+5. Document impact scope
+
+**After modifying:**
+
+1. Run `read_lints` on modified files → fix all errors
+2. **If ORM changed**: Verify database schema matches (Data Layer Gate)
+3. Test direct functionality
+4. Test ALL features in impact scope
+
+### 🔴 Data Layer Gate (when touching ORM models)
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Schema-Model sync | All model fields exist in DB |
+| Migration exists | Migration file created |
+| Migration applied | No "unknown column" errors |
+
+---
+
+## 🔴 代码质量检查 (MANDATORY)
+
+**开发完成前必须通过以下检查：**
+
+| 类别 | 检查项 | 严重等级 |
+|------|--------|----------|
+| 安全性 | SQL注入、XSS、CSRF、敏感信息泄露、权限验证 | **P0** |
+| 性能 | N+1查询、内存泄漏、阻塞主线程 | **P1** |
+| 错误处理 | 异常捕获、降级策略、超时设置 | **P1** |
+| 边界条件 | 空值、空数组、边界值、并发 | **P1** |
+| 资源管理 | 连接释放、监听器清理、定时器清除 | **P1** |
+
+→ 完整清单: `../shared-references/code-quality-checklist.md`
+
+---
+
+## Bug Prevention Checklist
+
+### Universal Rules (All Languages)
+
+| Rule | Bad Pattern | Good Pattern |
+|------|-------------|--------------|
+| 🔴 **Barrel import** | `from '@module'` 触发所有子模块 | `from '@module/source'` 直接导入 |
+| 🔴 **Env mismatch** | 浏览器代码导入 Node.js 模块 | 环境检查 + 条件导入 |
+| Batch callback | Process each item in callback | Buffer + timer/scheduler |
+| Resource release | `wait(timeout)` then assume done | Force terminate + confirm |
+| Exception scope | Outer try-catch wrapping loop | Separate iterator vs body |
+| Idempotent creation | Create directly | Check existence first |
+| Shared state | Direct read/write | Locks/atomics/thread-safe |
+| Cleanup | Assume auto-cleanup | Explicit stop in destructor |
+| 🔴 **Hard limit fail** | `if exceeded: return/break` | Compress/degrade → ensure output |
+| 🔴 **Silent exit** | Loop break with no handling | Set state/output before break |
+| 🔴 **Empty response** | Exception path returns empty | Always have fallback response |
+
+### Detection Questions (ask before submit)
+
+1. "If 1000 events arrive in 1 second, will UI freeze?"
+2. "If operation times out, is resource truly released?"
+3. "If one iteration fails, will entire loop abort?"
+4. "If called twice with same input, will it create duplicates?"
+5. "If two threads read/write this variable, is there a race?"
+6. "When closed, are all child resources stopped?"
+7. 🔴 **"If resource is only half available, does function still work?"** → Need degradation
+8. 🔴 **"If all loop iterations fail, what does user see?"** → Need fallback output
+9. 🔴 **"If external service is down, will user be stuck?"** → Need timeout + cache
+10. 🔴 **"Is this dependency a native module? Does it work in Electron?"** → Prefer pure JS
+
+→ Full checklist: `references/bug-prevention.md`
+→ 🔴 Degradation patterns: `references/graceful-degradation-patterns.md`
+
+---
+
+## Backend Checklist
+
+- [ ] Swagger/OpenAPI FIRST
+- [ ] Input validation (schema)
+- [ ] **🔴 ORM model change → `database-migration` (MANDATORY)**
+- [ ] Heavy operations use background tasks
+- [ ] Check all callers when changing functions
+- [ ] Response body business status: check code/success fields, not just HTTP
+
+## Frontend Checklist
+
+- [ ] **🔴 Any UI work → `frontend-design` (MANDATORY)**
+- [ ] Mock API before backend
+- [ ] Loading/error/empty states
+- [ ] Action feedback: every action has visual feedback
+- [ ] Keyboard support: ESC to close, Enter to submit
+
+## Integration Checklist
+
+- [ ] Field names match (camelCase/snake_case)
+- [ ] All status codes handled
+- [ ] **Avoid contract drift**: prefer single source of truth for DTOs
+- [ ] Response body validation: parse business status codes
+
+---
+
+## Output Contract (MANDATORY)
+
+```markdown
+## Tech Research
+- Platform: [Web / Desktop / Mobile]
+- Framework: [version]
+- APIs verified: [list]
+
+## Implementation Summary
+[What was built]
+
+## 🔄 Skill Orchestration Report
+| Phase | Skill | Reason | Contribution |
+|-------|-------|--------|--------------|
+| Phase -1 | `product-requirements` | Need clarity | PRD confirmed |
+| Phase 0 | (tech research) | - | APIs verified |
+| Phase 1 | `database-migration` | New tables | Migration files |
+| Phase 2 | `frontend-design` | UI components | Component design |
+| Phase 3 | `async-python-patterns` | Async API | Performance |
+| Phase 4 | `python-testing-patterns` | Unit tests | 85% coverage |
+| Phase 5 | `code-review` | Mandatory | Quality gate |
+
+## Enforcement Checklist
+- [ ] Phase 0 (Tech Research) completed
+- [ ] 🔴 Data Layer Gate passed (if ORM changed)
+- [ ] 🔴 `frontend-design` invoked (if UI work)
+- [ ] 🔴 `code-review` passed
+- [ ] 🔴 Dependency & Integrity Gate passed (if new dependencies)
+- [ ] 🔴 Native Module Check passed (if Electron + new deps)
+- [ ] 🔴 **Runtime Start Test passed** (`npm run dev` 无错误)
+- [ ] Console clean, no new errors
+
+## 依赖管理报告 (if applicable)
+| 包名 | 版本 | 安装状态 |
+|------|------|----------|
+| ... | ... | ✅/❌ |
+```
+
+---
+
+## Reference Navigation
+
+| Situation | Read This |
+|-----------|-----------|
+| 🔴🔴🔴 **完整开发流程** | `references/complete-development-workflow.md` |
+| 🔴🔴🔴 **技能路由表** | `references/skill-router-table.md` |
+| 🔴🔴🔴 **上下文隔离协议** | `references/context-isolation-protocol.md` |
+| 🔴🔴 **开发规范 (code-review)** | `../code-review/references/common-patterns.md` |
+| 🔴🔴 **常见 Bug (bug-fixing)** | `../bug-fixing/references/common-bugs.md` |
+| 🔴🔴 **分层检查清单** | `../code-review/references/layered-checklist-protocol.md` |
+| 🔴 **技能编排协议** | `../shared-references/skill-orchestration-protocol.md` |
+| 🔴 **React/Next.js 性能** | `../react-best-practices/SKILL.md` |
+| 🔴 **UI 可访问性** | `../web-design-guidelines/SKILL.md` |
+| 🔴 **快速部署** | `../vercel-deploy/SKILL.md` |
+| 🔴 **MCP 依赖兼容性检查** | `../shared-references/mcp-dependency-compatibility-protocol.md` |
+| 🔴 **代码质量检查清单** | `../shared-references/code-quality-checklist.md` |
+| 🔴 **审查效率指南** | `../shared-references/code-review-efficiency-guide.md` |
+| 🔴 **Import integrity** | `../shared-references/import-integrity-protocol.md` |
+| 🔴 **Multi-skill orchestration** | `references/skill-orchestration.md` |
+| 🔴 **Dependency & Integrity** | `references/dependency-and-integrity-protocol.md` |
+| Async patterns | `references/async-patterns.md` |
+| State sync | `references/state-sync.md` |
+| Database migration | `references/database-migration.md` |
+| API contract | `references/api-contract-guide.md` |
+| Bug prevention | `references/bug-prevention.md` |
+| IDE lint errors | `references/ide-lint-errors-guide.md` |
+| File import patterns | `references/file-import-patterns.md` |
+| API response patterns | `references/api-response-patterns.md` |
+| 🔴 **Graceful degradation** | `references/graceful-degradation-patterns.md` |