Initial commit

2025-11-30 08:53:07 +08:00
commit b5ab310674
19 changed files with 5687 additions and 0 deletions
--- a/skills/agent-delegation/examples/sequential-build.md
+++ b/skills/agent-delegation/examples/sequential-build.md
@@ -0,0 +1,504 @@
+# Example: Sequential Build Delegation
+
+This example shows how to coordinate dependent implementation tasks that must execute sequentially.
+
+## Scenario
+
+**User Request:** "Implement JWT authentication for our REST API"
+
+## Task Decomposition
+
+```
+Original Task: Implement JWT authentication for REST API
+
+Activities Identified:
+1. Design authentication database schema
+   - Expertise: Database design
+   - Output: Schema design document
+   - Dependencies: None
+
+2. Create database migration
+   - Expertise: Database implementation
+   - Output: Migration files
+   - Dependencies: Activity 1 (schema design)
+
+3. Implement authentication middleware
+   - Expertise: Backend development
+   - Output: JWT middleware code
+   - Dependencies: Activity 2 (tables must exist)
+
+4. Create auth endpoints (login/logout)
+   - Expertise: Backend development
+   - Output: Auth routes and controllers
+   - Dependencies: Activity 3 (middleware needed)
+
+5. Add tests for auth flow
+   - Expertise: Test automation
+   - Output: Integration tests
+   - Dependencies: Activity 4 (endpoints must work)
+
+Execution Strategy: Sequential
+Reasoning: Each activity depends on the previous one's output. No parallelization possible in this chain.
+
+Dependency Chain: 1 → 2 → 3 → 4 → 5
+```
+
+## Agent Prompts Generated
+
+### Agent 1: Schema Design (First)
+
+```
+DISCOVERY_FIRST: Before starting, understand the environment:
+    - Check existing database structure: ls migrations/ or db/schema/
+    - Identify database system: PostgreSQL, MySQL, SQLite?
+    - Review existing table patterns: user-related tables
+    - Note naming conventions: snake_case, camelCase, PascalCase?
+
+FOCUS: Design database schema for JWT authentication
+    - Users table (if not exists) with email, password_hash
+    - Sessions table for active JWT tokens
+    - Include created_at, updated_at timestamps
+    - Design appropriate indexes for performance
+    - Plan foreign key relationships
+
+EXCLUDE:
+    - Don't create the migration yet (next task)
+    - Don't implement OAuth tables (separate feature)
+    - Don't modify existing user table if it exists
+    - Don't add two-factor auth tables (not in scope)
+
+CONTEXT: Building JWT authentication for REST API.
+    - From security requirements: bcrypt hashing, cost factor 12
+    - Session expiry: 24 hours
+    - Email must be unique
+    - Follow project database conventions exactly
+
+OUTPUT: Schema design document at docs/patterns/auth-database-schema.md
+    - Table definitions with column types
+    - Indexes and constraints
+    - Foreign key relationships
+    - Example data
+
+SUCCESS: Schema designed and documented
+    - All required fields included
+    - Performance indexes identified
+    - Follows project conventions
+    - Ready for migration implementation
+
+TERMINATION:
+    - Design complete and documented
+    - Blocked by missing existing schema info
+```
+
+### Agent 2: Database Migration (After Agent 1)
+
+```
+DISCOVERY_FIRST: Before starting, understand the environment:
+    - Check migration system: Knex, Sequelize, TypeORM, raw SQL?
+    - Find migration directory location
+    - Review existing migration file format
+    - Note up/down pattern used
+
+FOCUS: Create database migration for authentication tables
+    - Implement users table from schema design
+    - Implement sessions table from schema design
+    - Add all indexes from schema design
+    - Create both up (create) and down (drop) migrations
+    - Follow migration naming conventions
+
+EXCLUDE:
+    - Don't run the migration yet (separate step)
+    - Don't seed data (separate concern)
+    - Don't modify existing migrations
+    - Don't add tables not in schema design
+
+CONTEXT: Implementing schema designed in previous step.
+    - Schema document: docs/patterns/auth-database-schema.md
+    - Tables: users (email, password_hash, created_at, updated_at)
+    - Tables: sessions (id, user_id, token_hash, expires_at, created_at)
+    - Indexes: users.email (unique), sessions.token_hash, sessions.user_id
+
+OUTPUT: Migration file at [DISCOVERED_MIGRATION_PATH]/[timestamp]_create_auth_tables.js
+    - Up migration creates tables and indexes
+    - Down migration drops tables cleanly
+    - Follows project migration format
+
+SUCCESS: Migration created and ready to run
+    - Matches schema design exactly
+    - Both up and down work correctly
+    - Follows project patterns
+    - No syntax errors
+
+TERMINATION:
+    - Migration file created successfully
+    - Blocked by unclear migration system
+    - Migration format doesn't match project (document issue)
+```
+
+### Agent 3: JWT Middleware (After Agent 2)
+
+```
+DISCOVERY_FIRST: Before starting, understand the environment:
+    - Find existing middleware location: src/middleware/ or app/middleware/?
+    - Check JWT library in use: jsonwebtoken, jose, other?
+    - Review existing middleware patterns
+    - Note error handling style used
+
+FOCUS: Implement JWT authentication middleware
+    - Verify JWT token from Authorization header
+    - Decode and validate token
+    - Check token against sessions table (not blacklisted)
+    - Attach user object to request
+    - Handle missing/invalid/expired tokens appropriately
+
+EXCLUDE:
+    - Don't implement login/logout endpoints (next task)
+    - Don't implement token refresh (not in scope)
+    - Don't add rate limiting (separate concern)
+    - Don't implement permission checking (just authentication)
+
+CONTEXT: JWT middleware for REST API authentication.
+    - JWT secret: from environment variable JWT_SECRET
+    - Token expiry: 24 hours
+    - Sessions table: check if token_hash exists and not expired
+    - Error responses: 401 for invalid/missing token
+    - Follow project error handling patterns
+
+OUTPUT: Middleware file at [DISCOVERED_LOCATION]/auth.middleware.ts
+    - verifyJWT function (main middleware)
+    - Helper functions (decode, validate, etc.)
+    - Error handling for all cases
+    - TypeScript types if applicable
+
+SUCCESS: Middleware implemented and ready to use
+    - Verifies JWT correctly
+    - Checks session validity
+    - Attaches user to request
+    - Handles all error cases
+    - Follows project patterns
+
+TERMINATION:
+    - Middleware complete
+    - Blocked by missing JWT library
+    - Database connection pattern unclear
+```
+
+### Agent 4: Auth Endpoints (After Agent 3)
+
+```
+DISCOVERY_FIRST: Before starting, understand the environment:
+    - Find routes directory: src/routes/ or app/routes/?
+    - Check router library: Express, Fastify, Koa?
+    - Review existing route patterns
+    - Note controller/handler organization
+
+FOCUS: Implement authentication endpoints
+    - POST /api/auth/login (email, password → JWT token)
+    - POST /api/auth/logout (invalidate current session)
+    - Use auth middleware from previous step
+    - Create sessions table entry on login
+    - Remove sessions table entry on logout
+
+EXCLUDE:
+    - Don't implement registration (separate feature)
+    - Don't implement password reset (separate feature)
+    - Don't add OAuth endpoints (separate feature)
+    - Don't implement GET /me endpoint (separate task)
+
+CONTEXT: Auth endpoints using JWT middleware implemented in previous step.
+    - Middleware location: [from Agent 3 OUTPUT]
+    - Login validates: email format, password against bcrypt hash
+    - Login creates: session entry, JWT token with user_id claim
+    - Logout requires: valid JWT (use middleware)
+    - Logout invalidates: session entry in database
+
+OUTPUT:
+    - Routes file at [DISCOVERED_LOCATION]/auth.routes.ts
+    - Controller file at [DISCOVERED_LOCATION]/auth.controller.ts
+    - Follow project route organization pattern
+
+SUCCESS: Endpoints implemented and functional
+    - Login validates credentials correctly
+    - Login returns valid JWT
+    - Logout requires authentication
+    - Logout invalidates session
+    - All errors handled appropriately
+    - Follows project patterns
+
+TERMINATION:
+    - Endpoints complete
+    - Blocked by unclear auth middleware interface
+    - bcrypt usage pattern unclear
+```
+
+### Agent 5: Integration Tests (After Agent 4)
+
+```
+DISCOVERY_FIRST: Before starting, understand the environment:
+    - Find test directory: tests/, __tests__/, spec/?
+    - Identify test framework: Jest, Mocha, Vitest?
+    - Review existing test patterns
+    - Note test database setup approach
+
+FOCUS: Create integration tests for authentication flow
+    - Test successful login (valid credentials → JWT returned)
+    - Test failed login (invalid credentials → 401)
+    - Test logout (valid JWT → session invalidated)
+    - Test protected route with valid JWT (→ 200)
+    - Test protected route with invalid JWT (→ 401)
+    - Test protected route with no JWT (→ 401)
+
+EXCLUDE:
+    - Don't test registration (not implemented)
+    - Don't test password reset (not implemented)
+    - Don't unit test internal functions (integration tests only)
+    - Don't test OAuth flows (not implemented)
+
+CONTEXT: Testing JWT authentication implemented in previous steps.
+    - Endpoints: POST /api/auth/login, POST /api/auth/logout
+    - Middleware: JWT verification from auth.middleware.ts
+    - Test database: Use test database, clean between tests
+    - Follow project testing patterns exactly
+
+OUTPUT: Test file at [DISCOVERED_LOCATION]/auth.integration.test.ts
+    - All test cases listed in FOCUS
+    - Setup and teardown (database, test user)
+    - Clear test descriptions
+    - Assertions verify correct behavior
+
+SUCCESS: Complete test coverage for auth flow
+    - All tests pass
+    - Tests are independent (can run in any order)
+    - Database cleanup works correctly
+    - Follows project test patterns
+    - Coverage includes happy path and error cases
+
+TERMINATION:
+    - Tests complete and passing
+    - Blocked by test framework unclear
+    - Test database setup pattern unclear
+```
+
+## Execution Flow
+
+### Phase 1: Schema Design (Agent 1)
+
+```
+🚀 Launching Agent 1: Schema Design
+
+Status: RUNNING
+Time: 15 minutes
+
+Agent 1: COMPLETE ✅
+Output: docs/patterns/auth-database-schema.md
+
+Deliverables:
+- Users table design (5 columns + indexes)
+- Sessions table design (5 columns + indexes)
+- Foreign key relationship documented
+- Performance considerations noted
+
+Validation: ✅ Ready for migration implementation
+```
+
+### Phase 2: Database Migration (Agent 2)
+
+```
+🚀 Launching Agent 2: Database Migration
+Dependencies: Agent 1 complete ✅
+
+Context provided:
+- Schema document from Agent 1
+- Table definitions and indexes
+
+Status: RUNNING
+Time: 20 minutes
+
+Agent 2: COMPLETE ✅
+Output: migrations/20250124120000_create_auth_tables.js
+
+Deliverables:
+- Up migration creates both tables
+- Down migration drops cleanly
+- All indexes included
+- Follows Knex migration pattern
+
+Validation: ✅ Ready for middleware implementation
+```
+
+### Phase 3: JWT Middleware (Agent 3)
+
+```
+🚀 Launching Agent 3: JWT Middleware
+Dependencies: Agent 2 complete ✅
+
+Context provided:
+- Migration created tables
+- Database schema known
+
+Status: RUNNING
+Time: 30 minutes
+
+Agent 3: COMPLETE ✅
+Output: src/middleware/auth.middleware.ts
+
+Deliverables:
+- verifyJWT middleware function
+- Token validation logic
+- Session checking against database
+- Error handling for all cases
+
+Validation: ✅ Ready for endpoint implementation
+```
+
+### Phase 4: Auth Endpoints (Agent 4)
+
+```
+🚀 Launching Agent 4: Auth Endpoints
+Dependencies: Agent 3 complete ✅
+
+Context provided:
+- Middleware from Agent 3
+- Function signatures and usage
+
+Status: RUNNING
+Time: 35 minutes
+
+Agent 4: COMPLETE ✅
+Output:
+- src/routes/auth.routes.ts
+- src/controllers/auth.controller.ts
+
+Deliverables:
+- POST /api/auth/login endpoint
+- POST /api/auth/logout endpoint
+- Integration with middleware
+- Error responses
+
+Validation: ✅ Ready for testing
+```
+
+### Phase 5: Integration Tests (Agent 5)
+
+```
+🚀 Launching Agent 5: Integration Tests
+Dependencies: Agent 4 complete ✅
+
+Context provided:
+- All endpoints from Agent 4
+- Middleware from Agent 3
+- Expected behavior
+
+Status: RUNNING
+Time: 25 minutes
+
+Agent 5: COMPLETE ✅
+Output: tests/integration/auth.test.ts
+
+Deliverables:
+- 6 integration tests
+- Database setup/teardown
+- All tests passing ✅
+- 95% coverage of auth flow
+
+Validation: ✅ Feature complete and tested
+```
+
+## Results
+
+### Total Time: 125 minutes (sequential)
+
+**Sequential necessary:** Each task depends on previous
+**No parallelization possible** in this dependency chain
+
+### Context Accumulation
+
+Each agent received growing context:
+
+- Agent 1: Fresh start
+- Agent 2: Agent 1's schema design
+- Agent 3: Agent 2's migration + Agent 1's schema
+- Agent 4: Agent 3's middleware + all prior context
+- Agent 5: All previous implementations
+
+### Deliverables
+
+```
+📁 Project structure:
+├── docs/patterns/
+│   └── auth-database-schema.md (Agent 1)
+├── migrations/
+│   └── 20250124120000_create_auth_tables.js (Agent 2)
+├── src/
+│   ├── middleware/
+│   │   └── auth.middleware.ts (Agent 3)
+│   ├── routes/
+│   │   └── auth.routes.ts (Agent 4)
+│   └── controllers/
+│       └── auth.controller.ts (Agent 4)
+└── tests/integration/
+    └── auth.test.ts (Agent 5)
+```
+
+## Lessons Learned
+
+### What Worked Well
+
+✅ **Clear dependency chain:** Each agent knew exactly what it needed
+✅ **Context accumulation:** Prior outputs informed each subsequent agent
+✅ **DISCOVERY_FIRST:** Ensured consistency with project patterns
+✅ **Validation at each step:** Caught issues before they propagated
+
+### Challenges Encountered
+
+⚠️ **Agent 2 Issue:** Initial migration didn't match project format
+- **Solution:** Retry with more specific Knex pattern in CONTEXT
+- **Lesson:** DISCOVERY_FIRST examples critical
+
+⚠️ **Agent 3 Issue:** Used wrong JWT library (jose instead of jsonwebtoken)
+- **Solution:** More explicit in EXCLUDE and CONTEXT
+- **Lesson:** Specify exact libraries when project uses specific ones
+
+⚠️ **Agent 5 Issue:** Tests didn't clean up database properly
+- **Solution:** Retry with explicit teardown requirements
+- **Lesson:** Test isolation must be explicit in SUCCESS criteria
+
+### Improvements for Next Time
+
+1. **Specify exact libraries** in CONTEXT (don't assume agent will discover)
+2. **Include output of previous agent** verbatim in next agent's CONTEXT
+3. **Validation step between agents** to catch issues before next dependency
+4. **Checkpoint approach:** Allow user to review after each agent before launching next
+
+## Reusable Template
+
+This pattern works for any sequential build:
+
+```
+1. Identify dependency chain (what depends on what)
+2. Order activities by dependencies
+3. Each agent's CONTEXT includes prior agent outputs
+4. Launch sequentially, validate each before next
+5. Accumulate context as you go
+```
+
+**Use when:**
+- Building implementation layers (DB → Logic → API → UI)
+- Pipeline-style workflows (Design → Build → Test → Deploy)
+- Learning workflows (Research → Design → Implement → Validate)
+- Any task where B genuinely needs A's output
+
+## Comparison: What If We Tried Parallel?
+
+**Attempted parallel (would fail):**
+
+```
+Agent 2 (Migration): Needs Agent 1's schema design → BLOCKED
+Agent 3 (Middleware): Needs Agent 2's tables to exist → BLOCKED
+Agent 4 (Endpoints): Needs Agent 3's middleware → BLOCKED
+Agent 5 (Tests): Needs Agent 4's endpoints → BLOCKED
+
+Result: All agents blocked or produce incorrect results
+```
+
+**Lesson:** Don't force parallelization when dependencies exist. Sequential is correct here.