@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/context-isolation-protocol.md

@@ -0,0 +1,256 @@
+# Context Isolation Protocol
+
+## 核心原则
+
+**多技能编排时，必须防止上下文污染，确保计划准确执行。**
+
+---
+
+## 上下文污染的表现
+
+| 问题 | 表现 | 后果 |
+|------|------|------|
+| **目标漂移** | 调用 skill A 后，忘记原始任务目标 | 偏离用户需求 |
+| **计划丢失** | 执行到一半，忘记后续步骤 | 任务不完整 |
+| **状态混乱** | 多个 skill 输出混在一起 | 无法追踪进度 |
+| **重复执行** | 忘记已完成的任务 | 浪费时间 |
+
+---
+
+## 隔离机制 (3 层防护)
+
+### Layer 1: Subagent 隔离
+
+**每个 skill 在独立的 subagent 中执行，天然隔离上下文。**
+
+```
+主 Agent (fullstack-developer)
+    │
+    ├── Task(subagent_type="general-purpose") → product-requirements
+    │       └── 返回: 需求文档
+    │
+    ├── Task(subagent_type="general-purpose") → database-migrations
+    │       └── 返回: 迁移文件
+    │
+    ├── Task(subagent_type="general-purpose") → api-scaffolding
+    │       └── 返回: API 代码
+    │
+    └── Task(subagent_type="superpowers:code-reviewer") → code-review
+            └── 返回: 审查报告
+```
+
+**调用模板**:
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="执行 [skill-name] 技能，任务: [具体任务描述]",
+  description="[3-5 字描述]"
+)
+```
+
+### Layer 2: 计划锚点
+
+**每次调用 skill 前后，重新读取计划文档。**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Before Skill Call                                          │
+│  ─────────────────────────────────────────────────────────  │
+│  1. 读取计划文档 (确认当前任务)                              │
+│  2. 读取进度追踪 (确认已完成任务)                            │
+│  3. 输出: "开始执行 Task X: [任务描述]"                      │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Skill Execution (in Subagent)                              │
+│  ─────────────────────────────────────────────────────────  │
+│  独立上下文，不受主 Agent 干扰                               │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  After Skill Call                                           │
+│  ─────────────────────────────────────────────────────────  │
+│  1. 记录 skill 输出到进度追踪                                │
+│  2. 重新读取计划文档 (确认下一任务)                          │
+│  3. 输出: "完成 Task X，下一步: Task Y"                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Layer 3: 进度追踪文档
+
+**维护一个进度追踪文档，记录每个 skill 的输入/输出。**
+
+```markdown
+# Development Progress Tracker
+
+## Session Info
+- **Session ID**: DEV-{YYYYMMDD}-{HHmm}
+- **Original Goal**: [用户原始需求]
+- **Plan File**: [计划文档路径]
+
+---
+
+## Task Progress
+
+| # | Task | Skill | Status | Input | Output |
+|---|------|-------|--------|-------|--------|
+| 1 | 需求分析 | `product-requirements` | ✅ Done | 用户需求 | PRD 文档 |
+| 2 | 数据库设计 | `database-migrations` | ✅ Done | PRD | 迁移文件 |
+| 3 | API 开发 | `api-scaffolding` | 🔄 In Progress | - | - |
+| 4 | 前端页面 | `frontend-design` | ⏳ Pending | - | - |
+
+**Current Task**: 3 - API 开发
+**Progress**: 2/4 (50%)
+
+---
+
+## Skill Outputs (Evidence)
+
+### Task 1: 需求分析
+- **Skill**: `product-requirements`
+- **Input**: 用户需求描述
+- **Output**: `docs/prd/feature-x.md`
+- **Key Points**: [核心需求摘要]
+
+### Task 2: 数据库设计
+- **Skill**: `database-migrations`
+- **Input**: PRD 文档
+- **Output**: `migrations/001_create_users.py`
+- **Key Points**: [表结构摘要]
+
+---
+
+## Goal Alignment Check
+
+| Check | Status |
+|-------|--------|
+| 当前任务与原始目标一致 | ✅ |
+| 已完成任务符合计划 | ✅ |
+| 无遗漏任务 | ✅ |
+```
+
+---
+
+## 执行流程
+
+### Step 1: 创建进度追踪文档
+
+```markdown
+开始开发前:
+1. 创建 `.dev/progress-{timestamp}.md`
+2. 记录原始目标
+3. 记录计划文档路径
+4. 初始化任务列表
+```
+
+### Step 2: 每个任务执行前
+
+```markdown
+执行任务前:
+1. 读取进度追踪文档
+2. 确认当前任务
+3. 输出: "🔄 开始 Task X: [任务描述]"
+4. 输出: "📋 调用 Skill: [skill-name]"
+```
+
+### Step 3: 使用 Subagent 执行 Skill
+
+```markdown
+调用 Task 工具:
+- subagent_type: "general-purpose" 或特定类型
+- prompt: 包含完整任务描述 + 输入数据
+- description: 简短描述
+```
+
+### Step 4: 每个任务执行后
+
+```markdown
+执行任务后:
+1. 记录 skill 输出到进度追踪
+2. 更新任务状态
+3. 输出: "✅ 完成 Task X"
+4. 读取计划，确认下一任务
+5. 输出: "📋 下一步: Task Y"
+```
+
+### Step 5: 目标对齐检查
+
+```markdown
+每 2-3 个任务后:
+1. 重新读取原始目标
+2. 检查已完成任务是否符合目标
+3. 检查是否有遗漏
+4. 输出: "🎯 目标对齐检查: ✅/⚠️"
+```
+
+---
+
+## Subagent 调用模板
+
+### 需求分析
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="执行 product-requirements 技能分析以下需求:\n\n[需求描述]\n\n输出需求文档。",
+  description="需求分析"
+)
+```
+
+### 数据库设计
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="执行 database-migrations 技能，根据以下需求设计数据库:\n\n[需求摘要]\n\n输出迁移文件。",
+  description="数据库设计"
+)
+```
+
+### API 开发
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="执行 api-scaffolding 技能，根据以下需求开发 API:\n\n[需求摘要]\n[数据库结构]\n\n输出 API 代码。",
+  description="API 开发"
+)
+```
+
+### 代码审查
+```
+Task(
+  subagent_type="superpowers:code-reviewer",
+  prompt="审查以下代码变更:\n\n[变更文件列表]\n\n按照 code-review 技能标准审查。",
+  description="代码审查"
+)
+```
+
+---
+
+## 回归检查清单
+
+每个 skill 完成后，检查:
+
+| 检查项 | 问题 |
+|--------|------|
+| 目标一致 | 当前任务是否与原始目标一致？ |
+| 计划符合 | 执行的是计划中的任务吗？ |
+| 无遗漏 | 是否跳过了任何任务？ |
+| 输出正确 | skill 输出是否符合预期？ |
+| 下一步明确 | 下一个任务是什么？ |
+
+---
+
+## 与 SKILL.md 集成
+
+在 fullstack-developer 的 Phase 4 中添加:
+
+```markdown
+### Phase 4: 开发执行 (Context Isolated)
+
+**每个任务使用 Subagent 隔离执行:**
+
+1. 读取进度追踪 → 确认当前任务
+2. Task(subagent) → 执行 skill
+3. 记录输出 → 更新进度
+4. 读取计划 → 确认下一任务
+5. 每 2-3 任务 → 目标对齐检查
+```

package/.claude/skills/fullstack-developer/references/database-migration.md

@@ -0,0 +1,331 @@
+# Database Migration Guide
+
+> Schema changes are the most dangerous operations. Handle with extreme care.
+
+## Core Principles
+
+1. **Migration before code** — Schema must exist before code that uses it
+2. **Always reversible** — Every migration must have a rollback
+3. **Zero downtime** — Production migrations should not lock tables
+4. **Verify after migrate** — Always check data integrity post-migration
+
+---
+
+## Migration Workflow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    MIGRATION FLOW                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  1. Create migration file                                    │
+│  2. Write up() and down() functions                          │
+│  3. Test locally (up + down + up)                            │
+│  4. Review ORM model matches schema                          │
+│  5. Test with production data snapshot                       │
+│  6. Deploy to staging, verify                                │
+│  7. Deploy to production with backup                         │
+│  8. Verify data integrity                                    │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Common Migration Bugs
+
+### 1. Schema-Model Mismatch
+
+```python
+# 🔴 BUG: ORM model has field, database doesn't
+class User(Base):
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    email = Column(String)
+    avatar_url = Column(String)  # 💀 Not in database!
+
+# Error: column "avatar_url" does not exist
+```
+
+**Prevention**:
+```bash
+# Always check schema matches model
+# Python/SQLAlchemy
+alembic check
+
+# Compare ORM with actual DB
+python -c "from app.models import *; Base.metadata.create_all(engine, checkfirst=True)"
+```
+
+### 2. Missing Migration
+
+```python
+# 🔴 BUG: Added field to model, forgot migration
+class User(Base):
+    phone = Column(String)  # Added in code
+    
+# But no migration file exists
+# Works locally (dev DB recreated), fails in production
+```
+
+**Prevention**:
+- Auto-generate migrations: `alembic revision --autogenerate`
+- Never manually edit DB without migration
+- CI check: Compare model with migration history
+
+### 3. Non-Reversible Migration
+
+```python
+# 🔴 BUG: Can't rollback
+def upgrade():
+    op.drop_column('users', 'legacy_field')  # Data lost!
+
+def downgrade():
+    op.add_column('users', sa.Column('legacy_field', sa.String))
+    # 💀 Data is gone, can't restore
+```
+
+**Prevention**:
+```python
+# ✅ CORRECT: Backup before destructive operations
+def upgrade():
+    # 1. First migration: Add new column, copy data
+    op.add_column('users', sa.Column('new_field', sa.String))
+    op.execute("UPDATE users SET new_field = legacy_field")
+    
+def downgrade():
+    op.drop_column('users', 'new_field')
+
+# 2. Second migration (after verification): Drop old column
+```
+
+### 4. Field Type Mismatch
+
+```python
+# 🔴 BUG: Frontend expects number, DB stores string
+# Migration
+op.add_column('products', sa.Column('price', sa.String))  # String!
+
+# Frontend
+interface Product {
+    price: number;  // Expects number
+}
+
+# Result: price = "99.99" not 99.99, calculations fail
+```
+
+**Prevention**:
+- Define types in API schema first (Swagger/OpenAPI)
+- Generate types from schema for both ends
+- Add conversion layer if needed
+
+### 5. Null Constraint on Existing Data
+
+```python
+# 🔴 BUG: Adding NOT NULL to column with existing NULLs
+def upgrade():
+    op.alter_column('users', 'email', nullable=False)
+    # 💀 Fails if any email is NULL
+
+# ✅ CORRECT: Handle existing data first
+def upgrade():
+    # 1. Update NULLs
+    op.execute("UPDATE users SET email = 'unknown@temp.com' WHERE email IS NULL")
+    # 2. Then add constraint
+    op.alter_column('users', 'email', nullable=False)
+```
+
+---
+
+## Field Consistency Checklist
+
+### Frontend-Backend-Database Alignment
+
+```markdown
+## Field: [field_name]
+
+| Layer | Name | Type | Nullable | Default |
+|-------|------|------|----------|---------|
+| Database | created_at | TIMESTAMP | NO | NOW() |
+| ORM Model | created_at | DateTime | NO | func.now() |
+| API Schema | createdAt | string | NO | - |
+| Frontend | createdAt | string | NO | - |
+
+Issues:
+- [ ] Naming: snake_case → camelCase (handled by serializer?)
+- [ ] Type: DateTime → string (ISO format?)
+- [ ] Nullable mismatch?
+- [ ] Default mismatch?
+```
+
+### Detection Commands
+
+```bash
+# Find all model fields
+grep -rn "Column\|Field" --include="*.py" models/
+
+# Find all API schema fields
+grep -rn "class.*Schema\|Field(" --include="*.py" schemas/
+
+# Find all frontend types
+grep -rn "interface\|type " --include="*.ts" types/
+
+# Compare (manual or script)
+```
+
+---
+
+## Migration Safety Checklist
+
+### Before Migration
+
+- [ ] Migration file has both `up()` and `down()`
+- [ ] Tested rollback locally: `migrate up` → `migrate down` → `migrate up`
+- [ ] No data loss in destructive operations
+- [ ] Large table? Use batched operations
+- [ ] Adding NOT NULL? Default value provided
+- [ ] Adding index? Will it lock table?
+- [ ] ORM model updated to match schema
+
+### During Migration (Production)
+
+- [ ] Database backup taken
+- [ ] Maintenance window scheduled (if needed)
+- [ ] Team notified
+- [ ] Monitoring dashboard open
+- [ ] Rollback command ready
+
+### After Migration
+
+- [ ] Data integrity verified
+- [ ] Application tested
+- [ ] No errors in logs
+- [ ] Performance acceptable
+- [ ] Rollback tested (in staging)
+
+---
+
+## Common Patterns
+
+### Adding a New Field
+
+```python
+# 1. Migration
+def upgrade():
+    op.add_column('users', sa.Column('phone', sa.String, nullable=True))
+
+def downgrade():
+    op.drop_column('users', 'phone')
+
+# 2. ORM Model
+class User(Base):
+    phone = Column(String, nullable=True)
+
+# 3. API Schema
+class UserSchema(BaseModel):
+    phone: Optional[str] = None
+
+# 4. Frontend Type
+interface User {
+    phone?: string;
+}
+```
+
+### Renaming a Field (Zero Downtime)
+
+```python
+# Phase 1: Add new column, copy data
+def upgrade_phase1():
+    op.add_column('users', sa.Column('full_name', sa.String))
+    op.execute("UPDATE users SET full_name = name")
+
+# Phase 2: Update code to use new column (deploy)
+
+# Phase 3: Drop old column
+def upgrade_phase3():
+    op.drop_column('users', 'name')
+```
+
+### Changing Field Type
+
+```python
+# 🔴 DANGEROUS: Direct type change
+op.alter_column('products', 'price', type_=sa.Integer)  # Data loss!
+
+# ✅ SAFE: Create new column, migrate data
+def upgrade():
+    op.add_column('products', sa.Column('price_cents', sa.Integer))
+    op.execute("UPDATE products SET price_cents = CAST(price * 100 AS INTEGER)")
+```
+
+---
+
+## Framework-Specific Commands
+
+### Python (Alembic)
+
+```bash
+# Generate migration
+alembic revision --autogenerate -m "add phone to users"
+
+# Apply migration
+alembic upgrade head
+
+# Rollback
+alembic downgrade -1
+
+# Check current version
+alembic current
+
+# Show history
+alembic history
+```
+
+### Node.js (Prisma)
+
+```bash
+# Generate migration
+npx prisma migrate dev --name add_phone_to_users
+
+# Apply to production
+npx prisma migrate deploy
+
+# Reset (DANGEROUS)
+npx prisma migrate reset
+```
+
+### Node.js (TypeORM)
+
+```bash
+# Generate migration
+npm run typeorm migration:generate -- -n AddPhoneToUsers
+
+# Run migrations
+npm run typeorm migration:run
+
+# Revert last
+npm run typeorm migration:revert
+```
+
+---
+
+## Data Integrity Verification
+
+```sql
+-- After migration, verify data
+
+-- Check no NULLs where not expected
+SELECT COUNT(*) FROM users WHERE email IS NULL;
+
+-- Check type conversion worked
+SELECT * FROM products WHERE price_cents IS NULL AND price IS NOT NULL;
+
+-- Check no orphaned records
+SELECT * FROM orders WHERE user_id NOT IN (SELECT id FROM users);
+
+-- Check counts match
+SELECT 
+    (SELECT COUNT(*) FROM old_table) as old_count,
+    (SELECT COUNT(*) FROM new_table) as new_count;
+```
+