Initial commit
This commit is contained in:
Zhongwei Li
882
skills/agent-delegation/SKILL.md
Normal file
882
skills/agent-delegation/SKILL.md
Normal file
@@ -0,0 +1,882 @@
|
||||
---
|
||||
name: agent-delegation
|
||||
description: Generate structured agent prompts with FOCUS/EXCLUDE templates for task delegation. Use when breaking down complex tasks, launching parallel specialists, coordinating multiple agents, creating agent instructions, determining execution strategy, or preventing file path collisions. Handles task decomposition, parallel vs sequential logic, scope validation, and retry strategies.
|
||||
allowed-tools: Task, TodoWrite
|
||||
---
|
||||
|
||||
You are an agent delegation specialist that helps orchestrators break down complex tasks and coordinate multiple specialist agents.
|
||||
|
||||
## When to Activate
|
||||
|
||||
Activate this skill when you need to:
|
||||
- **Break down a complex task** into multiple distinct activities
|
||||
- **Launch specialist agents** (parallel or sequential)
|
||||
- **Create structured agent prompts** with FOCUS/EXCLUDE templates
|
||||
- **Coordinate multiple agents** working on related tasks
|
||||
- **Determine execution strategy** (parallel vs sequential)
|
||||
- **Prevent file path collisions** between agents creating files
|
||||
- **Validate agent responses** for scope compliance
|
||||
- **Generate retry strategies** for failed agents
|
||||
- **Assess dependencies** between activities
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Activity-Based Decomposition
|
||||
|
||||
Decompose complex work by **ACTIVITIES** (what needs doing), not roles.
|
||||
|
||||
✅ **DO:** "Analyze security requirements", "Design database schema", "Create API endpoints"
|
||||
❌ **DON'T:** "Backend engineer do X", "Frontend developer do Y"
|
||||
|
||||
**Why:** The system automatically matches activities to specialized agents. Focus on the work, not the worker.
|
||||
|
||||
### Parallel-First Mindset
|
||||
|
||||
**DEFAULT:** Always execute in parallel unless tasks depend on each other.
|
||||
|
||||
Parallel execution maximizes velocity. Only go sequential when dependencies or shared state require it.
|
||||
|
||||
---
|
||||
|
||||
## Task Decomposition
|
||||
|
||||
### Decision Process
|
||||
|
||||
When faced with a complex task:
|
||||
|
||||
1. **Identify distinct activities** - What separate pieces of work are needed?
|
||||
2. **Determine expertise required** - What type of knowledge does each need?
|
||||
3. **Find natural boundaries** - Where do activities naturally separate?
|
||||
4. **Check for dependencies** - Does any activity depend on another's output?
|
||||
5. **Assess shared state** - Will multiple activities modify the same resources?
|
||||
|
||||
### Decomposition Template
|
||||
|
||||
```
|
||||
Original Task: [The complex task to break down]
|
||||
|
||||
Activities Identified:
|
||||
1. [Activity 1 name]
|
||||
- Expertise: [Type of knowledge needed]
|
||||
- Output: [What this produces]
|
||||
- Dependencies: [What it needs from other activities]
|
||||
|
||||
2. [Activity 2 name]
|
||||
- Expertise: [Type of knowledge needed]
|
||||
- Output: [What this produces]
|
||||
- Dependencies: [What it needs from other activities]
|
||||
|
||||
3. [Activity 3 name]
|
||||
- Expertise: [Type of knowledge needed]
|
||||
- Output: [What this produces]
|
||||
- Dependencies: [What it needs from other activities]
|
||||
|
||||
Execution Strategy: [Parallel / Sequential / Mixed]
|
||||
Reasoning: [Why this strategy fits]
|
||||
```
|
||||
|
||||
### When to Decompose
|
||||
|
||||
**Decompose when:**
|
||||
- Multiple distinct activities needed
|
||||
- Independent components that can be validated separately
|
||||
- Natural boundaries between system layers
|
||||
- Different stakeholder perspectives required
|
||||
- Task complexity exceeds single agent capacity
|
||||
|
||||
**Don't decompose when:**
|
||||
- Single focused activity
|
||||
- No clear separation of concerns
|
||||
- Overhead exceeds benefits
|
||||
- Task is already atomic
|
||||
|
||||
### Decomposition Examples
|
||||
|
||||
**Example 1: Add User Authentication**
|
||||
|
||||
```
|
||||
Original Task: Add user authentication to the application
|
||||
|
||||
Activities:
|
||||
1. Analyze security requirements
|
||||
- Expertise: Security analysis
|
||||
- Output: Security requirements document
|
||||
- Dependencies: None
|
||||
|
||||
2. Design database schema
|
||||
- Expertise: Database design
|
||||
- Output: Schema design with user tables
|
||||
- Dependencies: Security requirements (Activity 1)
|
||||
|
||||
3. Create API endpoints
|
||||
- Expertise: Backend development
|
||||
- Output: Login/logout/register endpoints
|
||||
- Dependencies: Database schema (Activity 2)
|
||||
|
||||
4. Build login/register UI
|
||||
- Expertise: Frontend development
|
||||
- Output: Authentication UI components
|
||||
- Dependencies: API endpoints (Activity 3)
|
||||
|
||||
Execution Strategy: Mixed
|
||||
- Sequential: 1 → 2 → (3 & 4 parallel)
|
||||
Reasoning: Early activities inform later ones, but API and UI can be built in parallel once schema exists
|
||||
```
|
||||
|
||||
**Example 2: Research Competitive Landscape**
|
||||
|
||||
```
|
||||
Original Task: Research competitive landscape for pricing strategy
|
||||
|
||||
Activities:
|
||||
1. Analyze competitor A pricing
|
||||
- Expertise: Market research
|
||||
- Output: Competitor A pricing analysis
|
||||
- Dependencies: None
|
||||
|
||||
2. Analyze competitor B pricing
|
||||
- Expertise: Market research
|
||||
- Output: Competitor B pricing analysis
|
||||
- Dependencies: None
|
||||
|
||||
3. Analyze competitor C pricing
|
||||
- Expertise: Market research
|
||||
- Output: Competitor C pricing analysis
|
||||
- Dependencies: None
|
||||
|
||||
4. Synthesize findings
|
||||
- Expertise: Strategic analysis
|
||||
- Output: Unified competitive analysis
|
||||
- Dependencies: All competitor analyses (Activities 1-3)
|
||||
|
||||
Execution Strategy: Mixed
|
||||
- Parallel: 1, 2, 3 → Sequential: 4
|
||||
Reasoning: Each competitor analysis is independent, synthesis requires all results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Decision Making
|
||||
|
||||
When decomposing tasks, explicitly decide whether documentation should be created.
|
||||
|
||||
### Criteria for Documentation
|
||||
|
||||
Include documentation in OUTPUT only when **ALL** criteria are met:
|
||||
|
||||
1. **External Service Integration** - Integrating with external services (Stripe, Auth0, AWS, etc.)
|
||||
2. **Reusable** - Pattern/interface/rule used in 2+ places OR clearly reusable
|
||||
3. **Non-Obvious** - Not standard practices (REST, MVC, CRUD)
|
||||
4. **Not a Duplicate** - Check existing docs first: `grep -ri "keyword" docs/` or `find docs -name "*topic*"`
|
||||
|
||||
### Decision Logic
|
||||
|
||||
- **Found existing docs** → OUTPUT: "Update docs/[category]/[file.md]"
|
||||
- **No existing docs + meets criteria** → OUTPUT: "Create docs/[category]/[file.md]"
|
||||
- **Doesn't meet criteria** → No documentation in OUTPUT
|
||||
|
||||
### Categories
|
||||
|
||||
- **docs/interfaces/** - External service integrations (Stripe, Auth0, AWS, webhooks)
|
||||
- **docs/patterns/** - Technical patterns (caching, auth flow, error handling)
|
||||
- **docs/domain/** - Business rules and domain logic (permissions, pricing, workflows)
|
||||
|
||||
### What NOT to Document
|
||||
|
||||
- ❌ Meta-documentation (SUMMARY.md, REPORT.md, ANALYSIS.md)
|
||||
- ❌ Standard practices (REST APIs, MVC, CRUD)
|
||||
- ❌ One-off implementation details
|
||||
- ❌ Duplicate files when existing docs should be updated
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
Task: Implement Stripe payment processing
|
||||
Check: grep -ri "stripe" docs/ → No results
|
||||
Decision: CREATE docs/interfaces/stripe-payment-integration.md
|
||||
|
||||
OUTPUT:
|
||||
- Payment processing code
|
||||
- docs/interfaces/stripe-payment-integration.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Parallel vs Sequential Determination
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Scenario | Dependencies | Shared State | Validation | File Paths | Recommendation |
|
||||
|----------|--------------|--------------|------------|------------|----------------|
|
||||
| Research tasks | None | Read-only | Independent | N/A | **PARALLEL** ⚡ |
|
||||
| Analysis tasks | None | Read-only | Independent | N/A | **PARALLEL** ⚡ |
|
||||
| Documentation | None | Unique paths | Independent | Unique | **PARALLEL** ⚡ |
|
||||
| Code creation | None | Unique files | Independent | Unique | **PARALLEL** ⚡ |
|
||||
| Build pipeline | Sequential | Shared files | Dependent | Same | **SEQUENTIAL** 📝 |
|
||||
| File editing | None | Same file | Collision risk | Same | **SEQUENTIAL** 📝 |
|
||||
| Dependent tasks | B needs A | Any | Dependent | Any | **SEQUENTIAL** 📝 |
|
||||
|
||||
### Parallel Execution Checklist
|
||||
|
||||
Run this checklist to confirm parallel execution is safe:
|
||||
|
||||
✅ **Independent tasks** - No task depends on another's output
|
||||
✅ **No shared state** - No simultaneous writes to same data
|
||||
✅ **Separate validation** - Each can be validated independently
|
||||
✅ **Won't block** - No resource contention
|
||||
✅ **Unique file paths** - If creating files, paths don't collide
|
||||
|
||||
**Result:** ✅ **PARALLEL EXECUTION** - Launch all agents in single response
|
||||
|
||||
### Sequential Execution Indicators
|
||||
|
||||
Look for these signals that require sequential execution:
|
||||
|
||||
🔴 **Dependency chain** - Task B needs Task A's output
|
||||
🔴 **Shared state** - Multiple tasks modify same resource
|
||||
🔴 **Validation dependency** - Must validate before proceeding
|
||||
🔴 **File path collision** - Multiple tasks write same file
|
||||
🔴 **Order matters** - Business logic requires specific sequence
|
||||
|
||||
**Result:** 📝 **SEQUENTIAL EXECUTION** - Launch agents one at a time
|
||||
|
||||
### Mixed Execution Strategy
|
||||
|
||||
Many complex tasks benefit from mixed strategies:
|
||||
|
||||
**Pattern:** Parallel groups connected sequentially
|
||||
|
||||
```
|
||||
Group 1 (parallel): Tasks A, B, C
|
||||
↓ (sequential)
|
||||
Group 2 (parallel): Tasks D, E
|
||||
↓ (sequential)
|
||||
Group 3: Task F
|
||||
```
|
||||
|
||||
**Example:** Authentication implementation
|
||||
- Group 1: Analyze security, Research best practices (parallel)
|
||||
- Sequential: Design schema (needs Group 1 results)
|
||||
- Group 2: Build API, Build UI (parallel)
|
||||
|
||||
---
|
||||
|
||||
## Agent Prompt Template Generation
|
||||
|
||||
### Base Template Structure
|
||||
|
||||
Every agent prompt should follow this structure:
|
||||
|
||||
```
|
||||
FOCUS: [Complete task description with all details]
|
||||
|
||||
EXCLUDE: [Task-specific things to avoid]
|
||||
- Do not create new patterns when existing ones work
|
||||
- Do not duplicate existing work
|
||||
[Add specific exclusions for this task]
|
||||
|
||||
CONTEXT: [Task background and constraints]
|
||||
- [Include relevant rules for this task]
|
||||
- Follow discovered patterns exactly
|
||||
[Add task-specific context]
|
||||
|
||||
OUTPUT: [Expected deliverables with exact paths if applicable]
|
||||
|
||||
SUCCESS: [Measurable completion criteria]
|
||||
- Follows existing patterns
|
||||
- Integrates with existing system
|
||||
[Add task-specific success criteria]
|
||||
|
||||
TERMINATION: [When to stop]
|
||||
- Completed successfully
|
||||
- Blocked by [specific blockers]
|
||||
- Maximum 3 attempts reached
|
||||
```
|
||||
|
||||
### Template Customization Rules
|
||||
|
||||
#### For File-Creating Agents
|
||||
|
||||
Add **DISCOVERY_FIRST** section at the beginning:
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting your task, understand the environment:
|
||||
- [Appropriate discovery commands for the task type]
|
||||
- Identify existing patterns and conventions
|
||||
- Locate where similar files live
|
||||
- Check project structure and naming conventions
|
||||
|
||||
[Rest of template follows]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting your task, understand the environment:
|
||||
- find . -name "*test*" -o -name "*spec*" -type f | head -20
|
||||
- Identify test framework (Jest, Vitest, Mocha, etc.)
|
||||
- Check existing test file naming patterns
|
||||
- Note test directory structure
|
||||
```
|
||||
|
||||
#### For Review Agents
|
||||
|
||||
Use **REVIEW_FOCUS** variant:
|
||||
|
||||
```
|
||||
REVIEW_FOCUS: [Implementation to review]
|
||||
|
||||
VERIFY:
|
||||
- [Specific criteria to check]
|
||||
- [Quality requirements]
|
||||
- [Specification compliance]
|
||||
- [Security considerations]
|
||||
|
||||
CONTEXT: [Background about what's being reviewed]
|
||||
|
||||
OUTPUT: [Review report format]
|
||||
- Issues found (if any)
|
||||
- Approval status
|
||||
- Recommendations
|
||||
|
||||
SUCCESS: Review completed with clear decision (approve/reject/revise)
|
||||
|
||||
TERMINATION: Review decision made OR blocked by missing context
|
||||
```
|
||||
|
||||
#### For Research Agents
|
||||
|
||||
Emphasize **OUTPUT** format specificity:
|
||||
|
||||
```
|
||||
FOCUS: [Research question or area]
|
||||
|
||||
EXCLUDE: [Out of scope topics]
|
||||
|
||||
CONTEXT: [Why this research is needed]
|
||||
|
||||
OUTPUT: Structured findings including:
|
||||
- Executive Summary (2-3 sentences)
|
||||
- Key Findings (bulleted list)
|
||||
- Detailed Analysis (organized by theme)
|
||||
- Recommendations (actionable next steps)
|
||||
- References (sources consulted)
|
||||
|
||||
SUCCESS: All sections completed with actionable insights
|
||||
|
||||
TERMINATION: Research complete OR information unavailable
|
||||
```
|
||||
|
||||
### Context Insertion Strategy
|
||||
|
||||
**Always include in CONTEXT:**
|
||||
|
||||
1. **Relevant rules** - Extract applicable rules from CLAUDE.md or project docs
|
||||
2. **Project constraints** - Technical stack, coding standards, conventions
|
||||
3. **Prior outputs** - For sequential tasks, include relevant results from previous steps
|
||||
4. **Specification references** - For implementation tasks, cite PRD/SDD/PLAN sections
|
||||
|
||||
**Context Example:**
|
||||
```
|
||||
CONTEXT: Testing authentication service handling login, tokens, and sessions.
|
||||
- TDD required: Write tests before implementation
|
||||
- One behavior per test: Each test should verify single behavior
|
||||
- Mock externals only: Don't mock internal application code
|
||||
- Follow discovered test patterns exactly
|
||||
- Current auth flow: docs/patterns/authentication-flow.md
|
||||
- Security requirements: PRD Section 3.2
|
||||
```
|
||||
|
||||
### Template Generation Examples
|
||||
|
||||
**Example 1: Parallel Research Tasks**
|
||||
|
||||
```
|
||||
Agent 1 - Competitor A Analysis:
|
||||
|
||||
FOCUS: Research Competitor A's pricing strategy, tiers, and feature bundling
|
||||
- Identify all pricing tiers
|
||||
- Map features to tiers
|
||||
- Note promotional strategies
|
||||
- Calculate price per feature value
|
||||
|
||||
EXCLUDE: Don't analyze their technology stack or implementation
|
||||
- Don't make pricing recommendations yet
|
||||
- Don't compare to other competitors
|
||||
|
||||
CONTEXT: We're researching competitive landscape for our pricing strategy.
|
||||
- Focus on B2B SaaS pricing
|
||||
- Competitor A is our primary competitor
|
||||
- Looking for pricing patterns and positioning
|
||||
|
||||
OUTPUT: Structured analysis including:
|
||||
- Pricing tiers table
|
||||
- Feature matrix by tier
|
||||
- Key insights about their strategy
|
||||
- Notable patterns or differentiators
|
||||
|
||||
SUCCESS: Complete analysis with actionable data
|
||||
- All tiers documented
|
||||
- Features mapped accurately
|
||||
- Insights are specific and evidence-based
|
||||
|
||||
TERMINATION: Analysis complete OR information not publicly available
|
||||
```
|
||||
|
||||
**Example 2: Sequential Implementation Tasks**
|
||||
|
||||
```
|
||||
Agent 1 - Database Schema (runs first):
|
||||
|
||||
DISCOVERY_FIRST: Before starting, understand the environment:
|
||||
- Check existing database migrations
|
||||
- Identify ORM/database tool in use
|
||||
- Review existing table structures
|
||||
- Note naming conventions
|
||||
|
||||
FOCUS: Design database schema for user authentication
|
||||
- Users table with email, password hash, created_at
|
||||
- Sessions table for active sessions
|
||||
- Use appropriate indexes for performance
|
||||
|
||||
EXCLUDE: Don't implement the actual migration yet
|
||||
- Don't add OAuth tables (separate feature)
|
||||
- Don't modify existing tables
|
||||
|
||||
CONTEXT: From security analysis, we need:
|
||||
- Bcrypt password hashing (cost factor 12)
|
||||
- Email uniqueness constraint
|
||||
- Session expiry mechanism
|
||||
- Follow discovered database patterns exactly
|
||||
|
||||
OUTPUT: Schema design document at docs/patterns/auth-schema.md
|
||||
- Table definitions with types
|
||||
- Indexes and constraints
|
||||
- Relationships between tables
|
||||
|
||||
SUCCESS: Schema designed and documented
|
||||
- Follows project conventions
|
||||
- Meets security requirements
|
||||
- Ready for migration implementation
|
||||
|
||||
TERMINATION: Design complete OR blocked by missing requirements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Creation Coordination
|
||||
|
||||
### Collision Prevention Protocol
|
||||
|
||||
When multiple agents will create files:
|
||||
|
||||
**Check before launching:**
|
||||
1. ✅ Are file paths specified explicitly in each agent's OUTPUT?
|
||||
2. ✅ Are all file paths unique (no two agents write same path)?
|
||||
3. ✅ Do paths follow project conventions?
|
||||
4. ✅ Are paths deterministic (not ambiguous)?
|
||||
|
||||
**If any check fails:** 🔴 Adjust OUTPUT sections to prevent collisions
|
||||
|
||||
### Path Assignment Strategies
|
||||
|
||||
#### Strategy 1: Explicit Unique Paths
|
||||
|
||||
Assign each agent a specific file path:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: Create pattern at docs/patterns/authentication-flow.md
|
||||
Agent 2 OUTPUT: Create interface at docs/interfaces/oauth-providers.md
|
||||
Agent 3 OUTPUT: Create domain rule at docs/domain/user-permissions.md
|
||||
```
|
||||
|
||||
**Result:** ✅ No collisions possible
|
||||
|
||||
#### Strategy 2: Discovery-Based Paths
|
||||
|
||||
Use placeholder that agent discovers:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: Test file at [DISCOVERED_LOCATION]/AuthService.test.ts
|
||||
where DISCOVERED_LOCATION is found via DISCOVERY_FIRST
|
||||
|
||||
Agent 2 OUTPUT: Test file at [DISCOVERED_LOCATION]/UserService.test.ts
|
||||
where DISCOVERED_LOCATION is found via DISCOVERY_FIRST
|
||||
```
|
||||
|
||||
**Result:** ✅ Agents discover same location, but filenames differ
|
||||
|
||||
#### Strategy 3: Hierarchical Paths
|
||||
|
||||
Use directory structure to separate agents:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: docs/patterns/backend/api-versioning.md
|
||||
Agent 2 OUTPUT: docs/patterns/frontend/state-management.md
|
||||
Agent 3 OUTPUT: docs/patterns/database/migration-strategy.md
|
||||
```
|
||||
|
||||
**Result:** ✅ Different directories prevent collisions
|
||||
|
||||
### Coordination Checklist
|
||||
|
||||
Before launching agents that create files:
|
||||
|
||||
- [ ] Each agent has explicit OUTPUT with file path
|
||||
- [ ] All file paths are unique
|
||||
- [ ] Paths follow project naming conventions
|
||||
- [ ] If using DISCOVERY, filenames differ
|
||||
- [ ] No potential for race conditions
|
||||
|
||||
---
|
||||
|
||||
## Scope Validation & Response Review
|
||||
|
||||
### Auto-Accept Criteria 🟢
|
||||
|
||||
Continue without user review when agent delivers:
|
||||
|
||||
**Security improvements:**
|
||||
- Vulnerability fixes
|
||||
- Input validation additions
|
||||
- Authentication enhancements
|
||||
- Error handling improvements
|
||||
|
||||
**Quality improvements:**
|
||||
- Code clarity enhancements
|
||||
- Documentation updates
|
||||
- Test coverage additions (if in scope)
|
||||
- Performance optimizations under 10 lines
|
||||
|
||||
**Specification compliance:**
|
||||
- Exactly matches FOCUS requirements
|
||||
- Respects all EXCLUDE boundaries
|
||||
- Delivers expected OUTPUT format
|
||||
- Meets SUCCESS criteria
|
||||
|
||||
### Requires User Review 🟡
|
||||
|
||||
Present to user for confirmation when agent delivers:
|
||||
|
||||
**Architectural changes:**
|
||||
- New external dependencies added
|
||||
- Database schema modifications
|
||||
- Public API changes
|
||||
- Design pattern changes
|
||||
- Configuration file updates
|
||||
|
||||
**Scope expansions:**
|
||||
- Features beyond FOCUS (but valuable)
|
||||
- Additional improvements requested
|
||||
- Alternative approaches suggested
|
||||
|
||||
### Auto-Reject Criteria 🔴
|
||||
|
||||
Reject as scope creep when agent delivers:
|
||||
|
||||
**Out of scope work:**
|
||||
- Features not in requirements
|
||||
- Work explicitly in EXCLUDE list
|
||||
- Breaking changes without migration path
|
||||
- Untested code modifications
|
||||
|
||||
**Quality issues:**
|
||||
- Missing required OUTPUT format
|
||||
- Doesn't meet SUCCESS criteria
|
||||
- "While I'm here" additions
|
||||
- Unrequested improvements
|
||||
|
||||
**Process violations:**
|
||||
- Skipped DISCOVERY_FIRST when required
|
||||
- Ignored CONTEXT constraints
|
||||
- Exceeded TERMINATION conditions
|
||||
|
||||
### Validation Report Format
|
||||
|
||||
When reviewing agent responses:
|
||||
|
||||
```
|
||||
✅ Agent Response Validation
|
||||
|
||||
Agent: [Agent type/name]
|
||||
Task: [Original FOCUS]
|
||||
|
||||
Deliverables Check:
|
||||
✅ [Deliverable 1]: Matches OUTPUT requirement
|
||||
✅ [Deliverable 2]: Matches OUTPUT requirement
|
||||
⚠️ [Deliverable 3]: Extra feature added (not in FOCUS)
|
||||
🔴 [Deliverable 4]: Violates EXCLUDE constraint
|
||||
|
||||
Scope Compliance:
|
||||
- FOCUS coverage: [%]
|
||||
- EXCLUDE violations: [count]
|
||||
- OUTPUT format: [matched/partial/missing]
|
||||
- SUCCESS criteria: [met/partial/unmet]
|
||||
|
||||
Recommendation:
|
||||
🟢 ACCEPT - Fully compliant
|
||||
🟡 REVIEW - User decision needed on [specific item]
|
||||
🔴 REJECT - Scope creep, retry with stricter FOCUS
|
||||
```
|
||||
|
||||
### When Agent Response Seems Off
|
||||
|
||||
**Ask yourself:**
|
||||
- Did I provide ambiguous instructions in FOCUS?
|
||||
- Should I have been more explicit in EXCLUDE?
|
||||
- Is this actually valuable despite being out of scope?
|
||||
- Would stricter FOCUS help or create more issues?
|
||||
|
||||
**Response options:**
|
||||
1. **Accept and update requirements** - If valuable and safe
|
||||
2. **Reject and retry** - With refined FOCUS/EXCLUDE
|
||||
3. **Cherry-pick** - Keep compliant parts, discard scope creep
|
||||
4. **Escalate to user** - For architectural decisions
|
||||
|
||||
---
|
||||
|
||||
## Failure Recovery & Retry Strategies
|
||||
|
||||
### Fallback Chain
|
||||
|
||||
When an agent fails, follow this escalation:
|
||||
|
||||
```
|
||||
1. 🔄 Retry with refined prompt
|
||||
- More specific FOCUS
|
||||
- More explicit EXCLUDE
|
||||
- Better CONTEXT
|
||||
↓ (if still fails)
|
||||
|
||||
2. 🔄 Try different specialist agent
|
||||
- Different expertise angle
|
||||
- Simpler task scope
|
||||
↓ (if still fails)
|
||||
|
||||
3. 🔄 Break into smaller tasks
|
||||
- Decompose further
|
||||
- Sequential smaller steps
|
||||
↓ (if still fails)
|
||||
|
||||
4. 🔄 Sequential instead of parallel
|
||||
- Dependency might exist
|
||||
- Coordination issue
|
||||
↓ (if still fails)
|
||||
|
||||
5. 🔄 Handle directly (DIY)
|
||||
- Task too specialized
|
||||
- Agent limitation
|
||||
↓ (if blocked)
|
||||
|
||||
6. ⚠️ Escalate to user
|
||||
- Present options
|
||||
- Request guidance
|
||||
```
|
||||
|
||||
### Retry Decision Tree
|
||||
|
||||
**Agent failed? Diagnose why:**
|
||||
|
||||
| Symptom | Likely Cause | Solution |
|
||||
|---------|--------------|----------|
|
||||
| Scope creep | FOCUS too vague | Refine FOCUS, expand EXCLUDE |
|
||||
| Wrong approach | Wrong specialist | Try different agent type |
|
||||
| Incomplete work | Task too complex | Break into smaller tasks |
|
||||
| Blocked/stuck | Missing dependency | Check if should be sequential |
|
||||
| Wrong output | OUTPUT unclear | Specify exact format/path |
|
||||
| Quality issues | CONTEXT insufficient | Add more constraints/examples |
|
||||
|
||||
### Template Refinement for Retry
|
||||
|
||||
**Original (failed):**
|
||||
```
|
||||
FOCUS: Implement authentication
|
||||
|
||||
EXCLUDE: Don't add tests
|
||||
```
|
||||
|
||||
**Why it failed:** Too vague, agent added OAuth when we wanted JWT
|
||||
|
||||
**Refined (retry):**
|
||||
```
|
||||
FOCUS: Implement JWT-based authentication for REST API endpoints
|
||||
- Create middleware for token validation
|
||||
- Add POST /auth/login endpoint that returns JWT
|
||||
- Add POST /auth/logout endpoint that invalidates token
|
||||
- Use bcrypt for password hashing (cost factor 12)
|
||||
- JWT expiry: 24 hours
|
||||
|
||||
EXCLUDE: OAuth implementation (separate feature)
|
||||
- Don't modify existing user table schema
|
||||
- Don't add frontend components
|
||||
- Don't implement refresh tokens yet
|
||||
- Don't add password reset flow
|
||||
|
||||
CONTEXT: API-only authentication for mobile app consumption.
|
||||
- Follow REST API patterns in docs/patterns/api-design.md
|
||||
- Security requirements from PRD Section 3.2
|
||||
- Use existing User model from src/models/User.ts
|
||||
|
||||
OUTPUT:
|
||||
- Middleware: src/middleware/auth.ts
|
||||
- Routes: src/routes/auth.ts
|
||||
- Tests: src/routes/auth.test.ts
|
||||
|
||||
SUCCESS:
|
||||
- Login returns valid JWT
|
||||
- Protected routes require valid token
|
||||
- All tests pass
|
||||
- Follows existing API patterns
|
||||
|
||||
TERMINATION: Implementation complete OR blocked by missing User model
|
||||
```
|
||||
|
||||
**Changes:**
|
||||
- ✅ Specific JWT requirement (not generic "authentication")
|
||||
- ✅ Explicit endpoint specifications
|
||||
- ✅ Detailed EXCLUDE (OAuth, frontend, etc.)
|
||||
- ✅ Exact file paths in OUTPUT
|
||||
- ✅ Measurable SUCCESS criteria
|
||||
|
||||
### Partial Success Handling
|
||||
|
||||
**When agent delivers partial results:**
|
||||
|
||||
1. **Assess what worked:**
|
||||
- Which deliverables are complete?
|
||||
- Which meet SUCCESS criteria?
|
||||
- What's missing?
|
||||
|
||||
2. **Determine if acceptable:**
|
||||
- Can we ship partial results?
|
||||
- Is missing work critical?
|
||||
- Can we iterate on what exists?
|
||||
|
||||
3. **Options:**
|
||||
- **Accept partial + new task** - Ship what works, new agent for missing parts
|
||||
- **Retry complete task** - If partial isn't useful
|
||||
- **Sequential completion** - Build on partial results
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Agent delivered:
|
||||
✅ POST /auth/login endpoint (works perfectly)
|
||||
✅ JWT generation logic (correct)
|
||||
🔴 POST /auth/logout endpoint (missing)
|
||||
🔴 Tests (missing)
|
||||
|
||||
Decision: Accept partial
|
||||
- Login endpoint is production-ready
|
||||
- Launch new agent for logout + tests
|
||||
- Faster than full retry
|
||||
```
|
||||
|
||||
### Retry Limit
|
||||
|
||||
**Maximum retries: 3 attempts**
|
||||
|
||||
After 3 failed attempts:
|
||||
1. **Present to user** - Explain what failed and why
|
||||
2. **Offer options** - Different approaches to try
|
||||
3. **Get guidance** - User decides next steps
|
||||
|
||||
**Don't infinite loop** - If it's not working after 3 tries, human input needed.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
After delegation work, always report:
|
||||
|
||||
```
|
||||
🎯 Task Decomposition Complete
|
||||
|
||||
Original Task: [The complex task]
|
||||
|
||||
Activities Identified: [N]
|
||||
1. [Activity 1] - [Parallel/Sequential]
|
||||
2. [Activity 2] - [Parallel/Sequential]
|
||||
3. [Activity 3] - [Parallel/Sequential]
|
||||
|
||||
Execution Strategy: [Parallel / Sequential / Mixed]
|
||||
Reasoning: [Why this strategy]
|
||||
|
||||
Agent Prompts Generated: [Yes/No]
|
||||
File Coordination: [Checked/Not applicable]
|
||||
Ready to launch: [Yes/No - if No, explain blocker]
|
||||
```
|
||||
|
||||
**For scope validation:**
|
||||
```
|
||||
✅ Scope Validation Complete
|
||||
|
||||
Agent: [Agent name]
|
||||
Result: [ACCEPT / REVIEW NEEDED / REJECT]
|
||||
|
||||
Summary:
|
||||
- Deliverables: [N matched, N extra, N missing]
|
||||
- Scope compliance: [percentage]
|
||||
- Recommendation: [Action to take]
|
||||
|
||||
[If REVIEW or REJECT, provide details]
|
||||
```
|
||||
|
||||
**For retry strategy:**
|
||||
```
|
||||
🔄 Retry Strategy Generated
|
||||
|
||||
Agent: [Agent name]
|
||||
Failure cause: [Diagnosis]
|
||||
Retry approach: [What's different]
|
||||
|
||||
Template refinements:
|
||||
- FOCUS: [What changed]
|
||||
- EXCLUDE: [What was added]
|
||||
- CONTEXT: [What was enhanced]
|
||||
|
||||
Retry attempt: [N of 3]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### When to Use This Skill
|
||||
|
||||
✅ "Break down this complex task"
|
||||
✅ "Launch parallel agents for these activities"
|
||||
✅ "Create agent prompts with FOCUS/EXCLUDE"
|
||||
✅ "Should these run in parallel or sequential?"
|
||||
✅ "Validate this agent response for scope"
|
||||
✅ "Generate retry strategy for failed agent"
|
||||
✅ "Coordinate file creation across agents"
|
||||
|
||||
### Key Principles
|
||||
|
||||
1. **Activity-based decomposition** (not role-based)
|
||||
2. **Parallel-first mindset** (unless dependencies exist)
|
||||
3. **Explicit FOCUS/EXCLUDE** (no ambiguity)
|
||||
4. **Unique file paths** (prevent collisions)
|
||||
5. **Scope validation** (auto-accept/review/reject)
|
||||
6. **Maximum 3 retries** (then escalate to user)
|
||||
|
||||
### Template Checklist
|
||||
|
||||
Every agent prompt needs:
|
||||
- [ ] FOCUS: Complete, specific task description
|
||||
- [ ] EXCLUDE: Explicit boundaries
|
||||
- [ ] CONTEXT: Relevant rules and constraints
|
||||
- [ ] OUTPUT: Expected deliverables with paths
|
||||
- [ ] SUCCESS: Measurable criteria
|
||||
- [ ] TERMINATION: Clear stop conditions
|
||||
- [ ] DISCOVERY_FIRST: If creating files (optional)
|
||||
|
||||
### Parallel Execution Safety
|
||||
|
||||
Before launching parallel agents, verify:
|
||||
- [ ] No dependencies between tasks
|
||||
- [ ] No shared state modifications
|
||||
- [ ] Independent validation possible
|
||||
- [ ] Unique file paths if creating files
|
||||
- [ ] No resource contention
|
||||
|
||||
If all checked: ✅ **PARALLEL SAFE**
|
||||
495
skills/agent-delegation/examples/file-coordination.md
Normal file
495
skills/agent-delegation/examples/file-coordination.md
Normal file
@@ -0,0 +1,495 @@
|
||||
# Example: File Coordination for Parallel Agents
|
||||
|
||||
This example shows how to prevent file path collisions when multiple agents create documentation in parallel.
|
||||
|
||||
## Scenario
|
||||
|
||||
**User Request:** "Document our codebase patterns for authentication, caching, and error handling"
|
||||
|
||||
## Initial Decomposition (Incorrect)
|
||||
|
||||
```
|
||||
❌ WRONG APPROACH
|
||||
|
||||
Activities:
|
||||
1. Document authentication patterns
|
||||
2. Document caching patterns
|
||||
3. Document error handling patterns
|
||||
|
||||
All parallel, all OUTPUT: "docs/patterns/[pattern-name].md"
|
||||
|
||||
Problem: What if agents choose same filename?
|
||||
- Agent 1 might create: docs/patterns/auth.md
|
||||
- Agent 2 might create: docs/patterns/cache.md
|
||||
- Agent 3 might create: docs/patterns/error.md
|
||||
|
||||
OR worse:
|
||||
- Agent 1: docs/patterns/authentication.md
|
||||
- Agent 2: docs/patterns/authentication-patterns.md
|
||||
- Both trying to document auth? Collision!
|
||||
|
||||
Result: Ambiguous, potential collisions, inconsistent naming
|
||||
```
|
||||
|
||||
## Correct Decomposition (File Coordination)
|
||||
|
||||
```
|
||||
✅ CORRECT APPROACH
|
||||
|
||||
Activities:
|
||||
1. Document authentication patterns
|
||||
- OUTPUT: docs/patterns/authentication-flow.md (EXPLICIT PATH)
|
||||
|
||||
2. Document caching patterns
|
||||
- OUTPUT: docs/patterns/caching-strategy.md (EXPLICIT PATH)
|
||||
|
||||
3. Document error handling patterns
|
||||
- OUTPUT: docs/patterns/error-handling.md (EXPLICIT PATH)
|
||||
|
||||
File Coordination Check:
|
||||
✅ All paths explicit and unique
|
||||
✅ No ambiguity in naming
|
||||
✅ No collision risk
|
||||
|
||||
Status: SAFE FOR PARALLEL EXECUTION
|
||||
```
|
||||
|
||||
## Agent Prompts with File Coordination
|
||||
|
||||
### Agent 1: Authentication Pattern
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, check existing documentation:
|
||||
- List docs/patterns/ directory
|
||||
- Search for existing auth-related files
|
||||
- Note naming conventions used
|
||||
- Check if authentication-flow.md already exists
|
||||
|
||||
FOCUS: Document authentication patterns discovered in codebase
|
||||
- JWT token generation and validation
|
||||
- Password hashing (bcrypt usage)
|
||||
- Session management approach
|
||||
- Protected route patterns
|
||||
- Error responses for auth failures
|
||||
|
||||
EXCLUDE:
|
||||
- Don't document caching (Agent 2 handles this)
|
||||
- Don't document error handling generally (Agent 3 handles this)
|
||||
- Don't create multiple files (single document)
|
||||
- Don't modify existing authentication files if they exist
|
||||
|
||||
CONTEXT: Documenting patterns found in src/middleware/auth.*, src/routes/auth.*
|
||||
- Focus on how authentication works, not implementation details
|
||||
- Use pattern template: docs/templates/pattern-template.md
|
||||
- Follow existing documentation style
|
||||
|
||||
OUTPUT: EXACTLY this path: docs/patterns/authentication-flow.md
|
||||
- If file exists: STOP and report (don't overwrite)
|
||||
- If file doesn't exist: Create new
|
||||
- Use pattern template structure
|
||||
- Include code examples from codebase
|
||||
|
||||
SUCCESS: Authentication patterns documented
|
||||
- File created at exact path specified
|
||||
- Follows pattern template
|
||||
- Includes JWT, bcrypt, and session patterns
|
||||
- Code examples are accurate
|
||||
- No collision with other agents
|
||||
|
||||
TERMINATION:
|
||||
- Documentation complete at specified path
|
||||
- File already exists (report to user)
|
||||
- No authentication patterns found in codebase
|
||||
```
|
||||
|
||||
### Agent 2: Caching Pattern
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, check existing documentation:
|
||||
- List docs/patterns/ directory
|
||||
- Search for existing cache-related files
|
||||
- Note naming conventions
|
||||
- Check if caching-strategy.md already exists
|
||||
|
||||
FOCUS: Document caching patterns discovered in codebase
|
||||
- Redis usage patterns
|
||||
- Cache key naming conventions
|
||||
- TTL (time-to-live) strategies
|
||||
- Cache invalidation approaches
|
||||
- What gets cached and why
|
||||
|
||||
EXCLUDE:
|
||||
- Don't document authentication (Agent 1 handles this)
|
||||
- Don't document error handling (Agent 3 handles this)
|
||||
- Don't create multiple files (single document)
|
||||
- Don't overlap with Agent 1's work
|
||||
|
||||
CONTEXT: Documenting patterns found in src/cache/*, src/services/*
|
||||
- Focus on caching strategy, not Redis API details
|
||||
- Use pattern template
|
||||
- Follow existing documentation style
|
||||
|
||||
OUTPUT: EXACTLY this path: docs/patterns/caching-strategy.md
|
||||
- If file exists: STOP and report (don't overwrite)
|
||||
- If file doesn't exist: Create new
|
||||
- Use pattern template structure
|
||||
- Include code examples from codebase
|
||||
|
||||
SUCCESS: Caching patterns documented
|
||||
- File created at exact path specified
|
||||
- Follows pattern template
|
||||
- Includes Redis patterns and cache strategies
|
||||
- No collision with other agents
|
||||
|
||||
TERMINATION:
|
||||
- Documentation complete at specified path
|
||||
- File already exists (report)
|
||||
- No caching patterns found
|
||||
```
|
||||
|
||||
### Agent 3: Error Handling Pattern
|
||||
|
||||
```
|
||||
DISCOVERY_FIRST: Before starting, check existing documentation:
|
||||
- List docs/patterns/ directory
|
||||
- Search for existing error-related files
|
||||
- Note naming conventions
|
||||
- Check if error-handling.md already exists
|
||||
|
||||
FOCUS: Document error handling patterns discovered in codebase
|
||||
- Error class hierarchy
|
||||
- HTTP status code mapping
|
||||
- Error response format
|
||||
- Logging strategy for errors
|
||||
- Recovery patterns
|
||||
|
||||
EXCLUDE:
|
||||
- Don't document authentication (Agent 1's domain)
|
||||
- Don't document caching (Agent 2's domain)
|
||||
- Don't create multiple files
|
||||
- Don't overlap with other agents
|
||||
|
||||
CONTEXT: Documenting patterns found in src/errors/*, src/middleware/error.*
|
||||
- Focus on error handling strategy and patterns
|
||||
- Use pattern template
|
||||
- Follow existing documentation style
|
||||
|
||||
OUTPUT: EXACTLY this path: docs/patterns/error-handling.md
|
||||
- If file exists: STOP and report (don't overwrite)
|
||||
- If file doesn't exist: Create new
|
||||
- Use pattern template structure
|
||||
- Include code examples
|
||||
|
||||
SUCCESS: Error handling patterns documented
|
||||
- File created at exact path specified
|
||||
- Follows pattern template
|
||||
- Includes error classes and response patterns
|
||||
- No collision with other agents
|
||||
|
||||
TERMINATION:
|
||||
- Documentation complete at specified path
|
||||
- File already exists (report)
|
||||
- No error handling patterns found
|
||||
```
|
||||
|
||||
## File Coordination Checklist
|
||||
|
||||
Before launching these agents:
|
||||
|
||||
```
|
||||
📋 File Coordination Pre-Flight Check
|
||||
|
||||
Agent 1 OUTPUT: docs/patterns/authentication-flow.md
|
||||
Agent 2 OUTPUT: docs/patterns/caching-strategy.md
|
||||
Agent 3 OUTPUT: docs/patterns/error-handling.md
|
||||
|
||||
✅ All paths are explicit (no ambiguity)
|
||||
✅ All paths are unique (no two agents write same file)
|
||||
✅ All paths follow convention (docs/patterns/[name].md)
|
||||
✅ All agents instructed to check if file exists first
|
||||
✅ All agents instructed to STOP if collision detected
|
||||
|
||||
File Collision Risk: NONE
|
||||
Safe to launch in parallel: YES
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Launch All Three Agents in Parallel
|
||||
|
||||
```
|
||||
🚀 Launching 3 parallel documentation agents
|
||||
|
||||
Agent 1: Authentication Pattern → RUNNING
|
||||
TARGET: docs/patterns/authentication-flow.md
|
||||
|
||||
Agent 2: Caching Pattern → RUNNING
|
||||
TARGET: docs/patterns/caching-strategy.md
|
||||
|
||||
Agent 3: Error Handling Pattern → RUNNING
|
||||
TARGET: docs/patterns/error-handling.md
|
||||
|
||||
File coordination: ✅ All unique paths
|
||||
Collision risk: ✅ None
|
||||
Parallel safety: ✅ Confirmed
|
||||
```
|
||||
|
||||
### Monitoring for Collisions
|
||||
|
||||
```
|
||||
⏳ Agents running...
|
||||
|
||||
[Agent 1] Checking: docs/patterns/authentication-flow.md → NOT EXISTS
|
||||
[Agent 1] Safe to create → PROCEEDING
|
||||
|
||||
[Agent 2] Checking: docs/patterns/caching-strategy.md → NOT EXISTS
|
||||
[Agent 2] Safe to create → PROCEEDING
|
||||
|
||||
[Agent 3] Checking: docs/patterns/error-handling.md → NOT EXISTS
|
||||
[Agent 3] Safe to create → PROCEEDING
|
||||
|
||||
No collisions detected. All agents proceeding independently.
|
||||
```
|
||||
|
||||
### Completion
|
||||
|
||||
```
|
||||
Agent 1: COMPLETE ✅ (22 minutes)
|
||||
Created: docs/patterns/authentication-flow.md (3.2 KB)
|
||||
|
||||
Agent 2: COMPLETE ✅ (18 minutes)
|
||||
Created: docs/patterns/caching-strategy.md (2.8 KB)
|
||||
|
||||
Agent 3: COMPLETE ✅ (25 minutes)
|
||||
Created: docs/patterns/error-handling.md (4.1 KB)
|
||||
|
||||
All agents complete. No collisions occurred.
|
||||
```
|
||||
|
||||
## Results
|
||||
|
||||
```
|
||||
📁 docs/patterns/
|
||||
├── authentication-flow.md ✅ Created by Agent 1
|
||||
├── caching-strategy.md ✅ Created by Agent 2
|
||||
└── error-handling.md ✅ Created by Agent 3
|
||||
```
|
||||
|
||||
**Total time:** 25 minutes (parallel)
|
||||
**Sequential would take:** 65 minutes
|
||||
**Time saved:** 40 minutes (61% faster)
|
||||
|
||||
## Alternative Coordination Strategies
|
||||
|
||||
### Strategy 1: Directory Separation
|
||||
|
||||
If agents might create multiple files:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: docs/patterns/authentication/
|
||||
- flow.md
|
||||
- jwt-tokens.md
|
||||
- session-management.md
|
||||
|
||||
Agent 2 OUTPUT: docs/patterns/caching/
|
||||
- redis-usage.md
|
||||
- invalidation.md
|
||||
- key-naming.md
|
||||
|
||||
Agent 3 OUTPUT: docs/patterns/error-handling/
|
||||
- error-classes.md
|
||||
- response-format.md
|
||||
- recovery-patterns.md
|
||||
```
|
||||
|
||||
**Result:** Each agent owns a directory, no file collisions possible.
|
||||
|
||||
### Strategy 2: Timestamp-Based Naming
|
||||
|
||||
For logs or reports that accumulate:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: logs/auth-analysis-2025-01-24-10-30-00.md
|
||||
Agent 2 OUTPUT: logs/cache-analysis-2025-01-24-10-30-00.md
|
||||
Agent 3 OUTPUT: logs/error-analysis-2025-01-24-10-30-00.md
|
||||
```
|
||||
|
||||
**Result:** Timestamps ensure uniqueness even if same topic.
|
||||
|
||||
### Strategy 3: Agent ID Namespacing
|
||||
|
||||
When dynamic number of agents:
|
||||
|
||||
```
|
||||
For each module in [moduleA, moduleB, moduleC, moduleD]:
|
||||
Launch agent with OUTPUT: analysis/module-${MODULE_NAME}.md
|
||||
|
||||
Results:
|
||||
- analysis/module-moduleA.md
|
||||
- analysis/module-moduleB.md
|
||||
- analysis/module-moduleC.md
|
||||
- analysis/module-moduleD.md
|
||||
```
|
||||
|
||||
**Result:** Template-based naming prevents collisions.
|
||||
|
||||
## What Could Go Wrong (Anti-Patterns)
|
||||
|
||||
### ❌ Anti-Pattern 1: Ambiguous Paths
|
||||
|
||||
```
|
||||
BAD:
|
||||
Agent 1 OUTPUT: "Create pattern documentation"
|
||||
Agent 2 OUTPUT: "Document caching patterns"
|
||||
|
||||
Problem: Where exactly? What filename?
|
||||
Result: Agents might choose same name or wrong location
|
||||
```
|
||||
|
||||
### ❌ Anti-Pattern 2: Overlapping Domains
|
||||
|
||||
```
|
||||
BAD:
|
||||
Agent 1 FOCUS: "Document authentication and security"
|
||||
Agent 2 FOCUS: "Document security patterns"
|
||||
|
||||
Problem: Both might document auth security!
|
||||
Result: Duplicate or conflicting documentation
|
||||
```
|
||||
|
||||
**Fix:** Clear FOCUS boundaries, explicit EXCLUDE
|
||||
|
||||
### ❌ Anti-Pattern 3: No Existence Check
|
||||
|
||||
```
|
||||
BAD:
|
||||
OUTPUT: docs/patterns/auth.md
|
||||
(No instruction to check if exists)
|
||||
|
||||
Problem: If file exists, agent might overwrite
|
||||
Result: Lost documentation
|
||||
```
|
||||
|
||||
**Fix:** Always include existence check in FOCUS or OUTPUT
|
||||
|
||||
### ❌ Anti-Pattern 4: Generic Filenames
|
||||
|
||||
```
|
||||
BAD:
|
||||
Agent 1 OUTPUT: docs/patterns/pattern.md
|
||||
Agent 2 OUTPUT: docs/patterns/patterns.md
|
||||
Agent 3 OUTPUT: docs/patterns/pattern-doc.md
|
||||
|
||||
Problem: All similar, confusing, might collide
|
||||
Result: Unclear which agent created what
|
||||
```
|
||||
|
||||
**Fix:** Descriptive, specific filenames
|
||||
|
||||
## File Coordination Best Practices
|
||||
|
||||
### 1. Explicit Paths
|
||||
|
||||
✅ **Always specify exact OUTPUT path:**
|
||||
```
|
||||
OUTPUT: docs/patterns/authentication-flow.md
|
||||
NOT: "Document authentication patterns"
|
||||
```
|
||||
|
||||
### 2. Unique Names
|
||||
|
||||
✅ **Ensure all agents have unique filenames:**
|
||||
```
|
||||
Before launching:
|
||||
- Agent 1: authentication-flow.md
|
||||
- Agent 2: caching-strategy.md
|
||||
- Agent 3: error-handling.md
|
||||
✅ All unique → SAFE
|
||||
```
|
||||
|
||||
### 3. Existence Checks
|
||||
|
||||
✅ **Instruct agents to check before creating:**
|
||||
```
|
||||
OUTPUT: docs/patterns/authentication-flow.md
|
||||
- If file exists: STOP and report (don't overwrite)
|
||||
- If file doesn't exist: Create new
|
||||
```
|
||||
|
||||
### 4. Clear Boundaries
|
||||
|
||||
✅ **Use EXCLUDE to prevent overlap:**
|
||||
```
|
||||
Agent 1:
|
||||
FOCUS: Document authentication
|
||||
EXCLUDE: Don't document caching (Agent 2) or errors (Agent 3)
|
||||
|
||||
Agent 2:
|
||||
FOCUS: Document caching
|
||||
EXCLUDE: Don't document auth (Agent 1) or errors (Agent 3)
|
||||
```
|
||||
|
||||
### 5. Validation
|
||||
|
||||
✅ **Check coordination before launching:**
|
||||
```
|
||||
Checklist:
|
||||
- [ ] All paths explicit
|
||||
- [ ] All paths unique
|
||||
- [ ] All agents have existence checks
|
||||
- [ ] Clear FOCUS boundaries
|
||||
- [ ] No overlap in domains
|
||||
```
|
||||
|
||||
## Integration with Documentation Skill
|
||||
|
||||
When these agents complete, documentation skill may activate:
|
||||
|
||||
```
|
||||
Agent 1 completes → Creates authentication-flow.md
|
||||
↓
|
||||
Documentation skill notices "pattern" created
|
||||
↓
|
||||
Checks: Is this in correct location? (docs/patterns/ ✅)
|
||||
Checks: Does it follow template? (✅)
|
||||
Checks: Should it be cross-referenced? (Yes)
|
||||
↓
|
||||
Documentation skill adds cross-references:
|
||||
- Links to related authentication interfaces
|
||||
- Links to domain rules about user permissions
|
||||
```
|
||||
|
||||
**Coordination:** Agent-delegation ensures unique paths, documentation skill ensures quality and linking.
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### What Worked
|
||||
|
||||
✅ **Explicit paths:** Zero ambiguity, zero collisions
|
||||
✅ **Existence checks:** Prevented accidental overwrites
|
||||
✅ **Clear boundaries:** No domain overlap
|
||||
✅ **Parallel execution:** 61% time savings
|
||||
|
||||
### What to Watch For
|
||||
|
||||
⚠️ **Naming conventions:** Ensure consistency (kebab-case vs snake_case)
|
||||
⚠️ **Template usage:** All agents should use same template
|
||||
⚠️ **Directory structure:** Verify docs/patterns/ exists before launching
|
||||
|
||||
## Reusable Coordination Template
|
||||
|
||||
For any parallel file creation:
|
||||
|
||||
```
|
||||
1. List all files to be created
|
||||
2. Verify all paths are unique
|
||||
3. Add existence checks to OUTPUT
|
||||
4. Use EXCLUDE to prevent overlap
|
||||
5. Launch in parallel with confidence
|
||||
```
|
||||
|
||||
**This prevents:**
|
||||
- File path collisions
|
||||
- Accidental overwrites
|
||||
- Domain overlap
|
||||
- Naming inconsistencies
|
||||
337
skills/agent-delegation/examples/parallel-research.md
Normal file
337
skills/agent-delegation/examples/parallel-research.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# Example: Parallel Research Delegation
|
||||
|
||||
This example shows how to decompose a research task into parallel specialist activities.
|
||||
|
||||
## Scenario
|
||||
|
||||
**User Request:** "Research competitive landscape for our B2B SaaS pricing strategy"
|
||||
|
||||
## Task Decomposition
|
||||
|
||||
```
|
||||
Original Task: Research competitive landscape for B2B SaaS pricing
|
||||
|
||||
Activities Identified:
|
||||
1. Analyze Competitor A (Salesforce) pricing
|
||||
- Expertise: Market research
|
||||
- Output: Pricing analysis document
|
||||
- Dependencies: None
|
||||
|
||||
2. Analyze Competitor B (HubSpot) pricing
|
||||
- Expertise: Market research
|
||||
- Output: Pricing analysis document
|
||||
- Dependencies: None
|
||||
|
||||
3. Analyze Competitor C (Zendesk) pricing
|
||||
- Expertise: Market research
|
||||
- Output: Pricing analysis document
|
||||
- Dependencies: None
|
||||
|
||||
4. Synthesize competitive findings
|
||||
- Expertise: Strategic analysis
|
||||
- Output: Unified competitive strategy
|
||||
- Dependencies: Activities 1, 2, 3
|
||||
|
||||
Execution Strategy: Mixed
|
||||
- Parallel: Activities 1-3 (independent research)
|
||||
- Sequential: Activity 4 (requires all results)
|
||||
|
||||
Reasoning: Each competitor analysis is independent. Synthesis must wait for all analyses to complete.
|
||||
```
|
||||
|
||||
## Agent Prompts Generated
|
||||
|
||||
### Agent 1: Salesforce Analysis
|
||||
|
||||
```
|
||||
FOCUS: Research Salesforce's B2B SaaS pricing strategy
|
||||
- Identify all pricing tiers (Essentials, Professional, Enterprise, Unlimited)
|
||||
- Map features to each tier
|
||||
- Note promotional strategies and discounts
|
||||
- Calculate price-per-user for each tier
|
||||
- Identify what features drive tier upgrades
|
||||
|
||||
EXCLUDE:
|
||||
- Don't analyze their technology stack or implementation
|
||||
- Don't make pricing recommendations yet (synthesis phase)
|
||||
- Don't compare to other competitors (separate analyses)
|
||||
- Don't analyze Salesforce Platform (focus on CRM product)
|
||||
|
||||
CONTEXT: We're researching competitive landscape for our B2B SaaS pricing strategy.
|
||||
- Target market: Mid-market companies (100-500 employees)
|
||||
- Looking for pricing patterns and positioning insights
|
||||
- Focus on transparent, public pricing only
|
||||
|
||||
OUTPUT: Structured analysis document including:
|
||||
- Pricing Tiers Table (tier name, price, billing cycle)
|
||||
- Feature Matrix by Tier (features mapped to each tier)
|
||||
- Key Insights (3-5 bullet points about their strategy)
|
||||
- Notable Patterns (what we can learn from their approach)
|
||||
- Competitive Positioning (how they position each tier)
|
||||
|
||||
SUCCESS: Complete analysis with actionable data
|
||||
- All publicly available tiers documented
|
||||
- Features accurately mapped to tiers
|
||||
- Insights are specific and evidence-based
|
||||
- Patterns identified are relevant to our market
|
||||
|
||||
TERMINATION:
|
||||
- Analysis complete with all sections filled
|
||||
- Information not publicly available (document what's missing)
|
||||
- Maximum 2 hours of research time reached
|
||||
```
|
||||
|
||||
### Agent 2: HubSpot Analysis
|
||||
|
||||
```
|
||||
FOCUS: Research HubSpot's B2B SaaS pricing strategy
|
||||
- Identify all pricing tiers (Starter, Professional, Enterprise)
|
||||
- Map features to each tier
|
||||
- Note freemium offering and upgrade triggers
|
||||
- Calculate price-per-contact for marketing hub
|
||||
- Identify bundling strategy across products
|
||||
|
||||
EXCLUDE:
|
||||
- Don't analyze technology implementation
|
||||
- Don't make pricing recommendations yet
|
||||
- Don't compare to other competitors
|
||||
- Don't analyze HubSpot Academy or services pricing
|
||||
|
||||
CONTEXT: Competitive landscape research for B2B SaaS pricing.
|
||||
- Target market: Mid-market companies (100-500 employees)
|
||||
- Interest in freemium-to-paid conversion strategies
|
||||
- Focus on Marketing Hub and Sales Hub pricing
|
||||
|
||||
OUTPUT: Structured analysis document including:
|
||||
- Pricing Tiers Table
|
||||
- Feature Matrix by Tier
|
||||
- Freemium Analysis (what's free, what triggers upgrade)
|
||||
- Key Insights (3-5 bullet points)
|
||||
- Bundling Strategy (how products bundle together)
|
||||
- Notable Patterns
|
||||
|
||||
SUCCESS: Complete analysis with freemium insights
|
||||
- All tiers documented
|
||||
- Freemium model understood
|
||||
- Bundle pricing analyzed
|
||||
- Insights are actionable
|
||||
|
||||
TERMINATION:
|
||||
- Analysis complete
|
||||
- Information unavailable
|
||||
- 2 hours research time reached
|
||||
```
|
||||
|
||||
### Agent 3: Zendesk Analysis
|
||||
|
||||
```
|
||||
FOCUS: Research Zendesk's B2B SaaS pricing strategy
|
||||
- Identify all pricing tiers (Suite Team, Growth, Professional, Enterprise)
|
||||
- Map features to each tier
|
||||
- Note per-agent pricing model
|
||||
- Analyze add-on pricing strategy
|
||||
- Identify what drives customer to higher tiers
|
||||
|
||||
EXCLUDE:
|
||||
- Don't analyze implementation details
|
||||
- Don't make recommendations yet
|
||||
- Don't compare to competitors
|
||||
- Don't analyze Zendesk Sell (focus on Support product)
|
||||
|
||||
CONTEXT: Competitive research for B2B SaaS pricing strategy.
|
||||
- Target market: Mid-market companies
|
||||
- Interest in per-seat vs per-usage pricing models
|
||||
- Focus on customer support software pricing
|
||||
|
||||
OUTPUT: Structured analysis including:
|
||||
- Pricing Tiers Table
|
||||
- Feature Matrix by Tier
|
||||
- Per-Agent Economics (cost per agent at scale)
|
||||
- Add-On Pricing (what extras cost money)
|
||||
- Key Insights (3-5 bullet points)
|
||||
- Upgrade Drivers (what makes customers move up tiers)
|
||||
|
||||
SUCCESS: Complete analysis with per-seat insights
|
||||
- All tiers documented
|
||||
- Per-agent model understood
|
||||
- Add-on strategy mapped
|
||||
- Insights are specific
|
||||
|
||||
TERMINATION:
|
||||
- Analysis complete
|
||||
- Information unavailable
|
||||
- 2 hours research reached
|
||||
```
|
||||
|
||||
### Agent 4: Synthesis (Sequential, after 1-3)
|
||||
|
||||
```
|
||||
FOCUS: Synthesize competitive pricing findings into unified strategy insights
|
||||
|
||||
EXCLUDE:
|
||||
- Don't create our pricing (separate decision)
|
||||
- Don't add new competitor research
|
||||
- Don't analyze product features (stick to pricing patterns)
|
||||
|
||||
CONTEXT: We have three completed competitor analyses.
|
||||
- Salesforce analysis: [Results from Agent 1]
|
||||
- HubSpot analysis: [Results from Agent 2]
|
||||
- Zendesk analysis: [Results from Agent 3]
|
||||
- Goal: Extract patterns and strategic insights
|
||||
|
||||
OUTPUT: Competitive Pricing Strategy Document including:
|
||||
- Cross-Competitor Patterns (themes across all three)
|
||||
- Pricing Model Comparison (per-user vs per-contact vs per-usage)
|
||||
- Tier Strategy Analysis (how competitors structure tiers)
|
||||
- Freemium Insights (who uses it, how it works)
|
||||
- Feature Differentiation (what features separate tiers)
|
||||
- Positioning Opportunities (gaps or opportunities for us)
|
||||
- Strategic Recommendations (3-5 actionable insights)
|
||||
|
||||
SUCCESS: Unified synthesis with strategic value
|
||||
- Patterns identified across competitors
|
||||
- Comparisons are fair and evidence-based
|
||||
- Recommendations are actionable
|
||||
- No contradiction between analyses
|
||||
|
||||
TERMINATION:
|
||||
- Synthesis complete
|
||||
- Conflicting data needs clarification (escalate)
|
||||
- All sections filled
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 1: Launch Parallel Research (Agents 1-3)
|
||||
|
||||
```
|
||||
🚀 Launching 3 parallel research agents
|
||||
|
||||
Agent 1: Salesforce Analysis → RUNNING
|
||||
Agent 2: HubSpot Analysis → RUNNING
|
||||
Agent 3: Zendesk Analysis → RUNNING
|
||||
|
||||
File Coordination Check:
|
||||
✅ Agent 1 OUTPUT: research/salesforce-pricing.md
|
||||
✅ Agent 2 OUTPUT: research/hubspot-pricing.md
|
||||
✅ Agent 3 OUTPUT: zendesk-pricing.md
|
||||
✅ All paths unique - No collision risk
|
||||
|
||||
Parallel Safety Check:
|
||||
✅ Independent tasks - No dependencies
|
||||
✅ Read-only research - No shared state
|
||||
✅ Separate validation - Each can be reviewed independently
|
||||
✅ Won't block - Different data sources
|
||||
|
||||
Status: ✅ SAFE FOR PARALLEL EXECUTION
|
||||
```
|
||||
|
||||
### Phase 2: Await Completion
|
||||
|
||||
```
|
||||
⏳ Waiting for parallel agents...
|
||||
|
||||
Agent 1: COMPLETE ✅ (45 minutes)
|
||||
- Salesforce analysis delivered
|
||||
- All sections complete
|
||||
- 4 tiers documented
|
||||
|
||||
Agent 2: COMPLETE ✅ (52 minutes)
|
||||
- HubSpot analysis delivered
|
||||
- Freemium model analyzed
|
||||
- 3 tiers + free tier documented
|
||||
|
||||
Agent 3: COMPLETE ✅ (38 minutes)
|
||||
- Zendesk analysis delivered
|
||||
- Per-agent model mapped
|
||||
- 4 tiers + add-ons documented
|
||||
|
||||
All parallel agents complete. Proceeding to synthesis.
|
||||
```
|
||||
|
||||
### Phase 3: Launch Synthesis (Agent 4)
|
||||
|
||||
```
|
||||
🚀 Launching synthesis agent
|
||||
|
||||
Agent 4: Competitive Synthesis → RUNNING
|
||||
|
||||
Context provided:
|
||||
- Salesforce results (from Agent 1)
|
||||
- HubSpot results (from Agent 2)
|
||||
- Zendesk results (from Agent 3)
|
||||
|
||||
Agent 4: COMPLETE ✅ (25 minutes)
|
||||
- Cross-competitor patterns identified
|
||||
- 5 strategic recommendations generated
|
||||
- Positioning opportunities highlighted
|
||||
```
|
||||
|
||||
## Results
|
||||
|
||||
### Total Time: 52 minutes (parallel) + 25 minutes (synthesis) = 77 minutes
|
||||
|
||||
**Compare to sequential:** 45 + 52 + 38 + 25 = 160 minutes
|
||||
**Time saved:** 83 minutes (52% faster)
|
||||
|
||||
### Deliverables
|
||||
|
||||
```
|
||||
📁 research/
|
||||
├── salesforce-pricing.md (Agent 1)
|
||||
├── hubspot-pricing.md (Agent 2)
|
||||
├── zendesk-pricing.md (Agent 3)
|
||||
└── competitive-strategy.md (Agent 4 synthesis)
|
||||
```
|
||||
|
||||
### Key Insights Generated
|
||||
|
||||
From the synthesis agent:
|
||||
|
||||
1. **Tiering Pattern:** All three use 3-4 tier structure with similar progression (basic → professional → enterprise)
|
||||
|
||||
2. **Pricing Models:** Mixed approaches
|
||||
- Salesforce: Per-user, all-inclusive features
|
||||
- HubSpot: Per-contact, freemium base
|
||||
- Zendesk: Per-agent, add-on marketplace
|
||||
|
||||
3. **Feature Gating:** Core features in all tiers, advanced analytics/automation in top tiers
|
||||
|
||||
4. **Freemium:** Only HubSpot uses freemium successfully (strong upgrade triggers identified)
|
||||
|
||||
5. **Opportunity:** Gap in mid-market transparent pricing - competitors hide "contact sales" behind top tier
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### What Worked Well
|
||||
|
||||
✅ **Parallel execution:** Saved 52% time
|
||||
✅ **Independent research:** No coordination overhead
|
||||
✅ **Synthesis phase:** Unified findings effectively
|
||||
✅ **Unique file paths:** No collisions
|
||||
✅ **Explicit FOCUS/EXCLUDE:** Agents stayed on task
|
||||
|
||||
### Improvements for Next Time
|
||||
|
||||
- Add time limits to prevent research rabbit holes
|
||||
- Specify exact format (all agents used slightly different table formats)
|
||||
- Request specific pricing data points (some agents missed cost-per-user calculations)
|
||||
- Consider adding validation agent before synthesis (check data accuracy)
|
||||
|
||||
## Reusable Template
|
||||
|
||||
This pattern works for any parallel research:
|
||||
|
||||
```
|
||||
1. Decompose research into independent topics
|
||||
2. Create identical FOCUS/EXCLUDE templates
|
||||
3. Customize context and output paths only
|
||||
4. Launch all in parallel
|
||||
5. Synthesis agent consolidates findings
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Researching multiple competitors
|
||||
- Analyzing multiple technologies
|
||||
- Gathering multiple data sources
|
||||
- Interviewing multiple stakeholders
|
||||
504
skills/agent-delegation/examples/sequential-build.md
Normal file
504
skills/agent-delegation/examples/sequential-build.md
Normal file
@@ -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.
|
||||
825
skills/agent-delegation/reference.md
Normal file
825
skills/agent-delegation/reference.md
Normal file
@@ -0,0 +1,825 @@
|
||||
# Agent Delegation Skill Reference
|
||||
|
||||
Complete reference for advanced delegation patterns, edge cases, and optimization strategies.
|
||||
|
||||
## Advanced Decomposition Patterns
|
||||
|
||||
### Multi-Level Decomposition
|
||||
|
||||
For very complex tasks, decompose in layers:
|
||||
|
||||
**Layer 1: High-Level Activities**
|
||||
```
|
||||
Task: Build e-commerce checkout flow
|
||||
|
||||
Activities:
|
||||
1. Frontend checkout interface
|
||||
2. Backend payment processing
|
||||
3. Order fulfillment system
|
||||
4. Email notifications
|
||||
```
|
||||
|
||||
**Layer 2: Sub-Activity Decomposition**
|
||||
|
||||
Take Activity 2 and decompose further:
|
||||
```
|
||||
Activity: Backend payment processing
|
||||
|
||||
Sub-activities:
|
||||
2.1 Stripe API integration
|
||||
2.2 Payment validation logic
|
||||
2.3 Transaction database schema
|
||||
2.4 Refund handling
|
||||
```
|
||||
|
||||
**Execution Strategy:**
|
||||
- Layer 1: Mixed (some parallel, some sequential)
|
||||
- Layer 2: Decompose only when agent starts Activity 2
|
||||
- Don't decompose all layers upfront (overwhelming)
|
||||
|
||||
### Dependency Graph Decomposition
|
||||
|
||||
For complex dependency chains:
|
||||
|
||||
```
|
||||
Task: Deploy new microservice
|
||||
|
||||
Activity Map:
|
||||
A: Write service code
|
||||
B: Write unit tests (depends on A)
|
||||
C: Create Docker image (depends on A)
|
||||
D: Write integration tests (depends on A, C)
|
||||
E: Deploy to staging (depends on B, C, D)
|
||||
F: Run smoke tests (depends on E)
|
||||
G: Deploy to production (depends on F)
|
||||
|
||||
Execution Groups:
|
||||
Group 1: A (sequential)
|
||||
Group 2: B, C (parallel after A)
|
||||
Group 3: D (sequential after Group 2)
|
||||
Group 4: E (sequential after Group 3)
|
||||
Group 5: F (sequential after E)
|
||||
Group 6: G (sequential after F)
|
||||
```
|
||||
|
||||
**Pattern:** Identify critical path, parallelize where possible.
|
||||
|
||||
### Expertise-Based Decomposition
|
||||
|
||||
When multiple domains are involved:
|
||||
|
||||
```
|
||||
Task: Add real-time chat feature
|
||||
|
||||
Decompose by expertise:
|
||||
1. UI/UX design (design expertise)
|
||||
2. Frontend component (React expertise)
|
||||
3. WebSocket server (Backend expertise)
|
||||
4. Message persistence (Database expertise)
|
||||
5. Security review (Security expertise)
|
||||
6. Performance testing (Performance expertise)
|
||||
|
||||
Execution:
|
||||
- Phase 1: Activity 1 (sequential)
|
||||
- Phase 2: Activities 2-4 (parallel, informed by Activity 1)
|
||||
- Phase 3: Activities 5-6 (parallel review after Phase 2)
|
||||
```
|
||||
|
||||
## Advanced Parallel Patterns
|
||||
|
||||
### Fan-Out/Fan-In Pattern
|
||||
|
||||
Parallel expansion followed by sequential consolidation:
|
||||
|
||||
```
|
||||
Start
|
||||
↓
|
||||
[Activity 1]
|
||||
↓
|
||||
┌─────┼─────┐
|
||||
↓ ↓ ↓
|
||||
[A2] [A3] [A4] ← Fan-out (parallel)
|
||||
↓ ↓ ↓
|
||||
└─────┼─────┘
|
||||
↓
|
||||
[Synthesize] ← Fan-in (sequential)
|
||||
↓
|
||||
Done
|
||||
```
|
||||
|
||||
**Example:** Competitive analysis
|
||||
- Fan-out: Analyze competitors A, B, C in parallel
|
||||
- Fan-in: Synthesize findings into unified strategy
|
||||
|
||||
### Pipeline Pattern
|
||||
|
||||
Sequential groups where each group can be parallel:
|
||||
|
||||
```
|
||||
Stage 1: Research (parallel within stage)
|
||||
- Market research
|
||||
- Competitive analysis
|
||||
- User interviews
|
||||
↓
|
||||
Stage 2: Design (parallel within stage)
|
||||
- UI mockups
|
||||
- API design
|
||||
- Database schema
|
||||
↓
|
||||
Stage 3: Implementation (parallel within stage)
|
||||
- Frontend build
|
||||
- Backend build
|
||||
- Database setup
|
||||
```
|
||||
|
||||
**Pattern:** Stages are sequential, activities within each stage are parallel.
|
||||
|
||||
### MapReduce Pattern
|
||||
|
||||
Parallel processing with aggregation:
|
||||
|
||||
```
|
||||
Map Phase (parallel):
|
||||
Agent 1: Process dataset chunk 1
|
||||
Agent 2: Process dataset chunk 2
|
||||
Agent 3: Process dataset chunk 3
|
||||
Agent 4: Process dataset chunk 4
|
||||
|
||||
Reduce Phase (sequential):
|
||||
Aggregate all results into final output
|
||||
```
|
||||
|
||||
**Example:** Code analysis across modules
|
||||
- Map: Each agent analyzes one module
|
||||
- Reduce: Aggregate findings into project-wide report
|
||||
|
||||
## Advanced Template Patterns
|
||||
|
||||
### Context Accumulation Pattern
|
||||
|
||||
For sequential tasks, accumulate context:
|
||||
|
||||
```
|
||||
Agent 1:
|
||||
CONTEXT: Fresh start, no prior context
|
||||
OUTPUT: Result A
|
||||
|
||||
Agent 2:
|
||||
CONTEXT:
|
||||
- Prior results: [Result A from Agent 1]
|
||||
- Build on: [Specific insights from A]
|
||||
OUTPUT: Result B (informed by A)
|
||||
|
||||
Agent 3:
|
||||
CONTEXT:
|
||||
- Prior results: [Result A, Result B]
|
||||
- Conflicts to resolve: [Any conflicts between A and B]
|
||||
- Build on: [Insights from both]
|
||||
OUTPUT: Result C (synthesizes A and B)
|
||||
```
|
||||
|
||||
**Key:** Each agent gets relevant prior outputs, not everything.
|
||||
|
||||
### Constraint Propagation Pattern
|
||||
|
||||
Cascade constraints through dependent tasks:
|
||||
|
||||
```
|
||||
Agent 1 (Schema Design):
|
||||
SUCCESS:
|
||||
- Uses PostgreSQL (project standard)
|
||||
- Follows naming: snake_case tables
|
||||
- All tables have created_at, updated_at
|
||||
|
||||
Agent 2 (API Implementation, depends on Agent 1):
|
||||
CONTEXT:
|
||||
- Database constraints from Agent 1:
|
||||
* PostgreSQL only
|
||||
* snake_case table names
|
||||
* created_at/updated_at in all tables
|
||||
- Must match schema exactly
|
||||
```
|
||||
|
||||
**Pattern:** SUCCESS criteria from earlier tasks become CONTEXT constraints for later ones.
|
||||
|
||||
### Specification Reference Pattern
|
||||
|
||||
For implementation tasks, reference specs explicitly:
|
||||
|
||||
```
|
||||
FOCUS: Implement user registration endpoint
|
||||
|
||||
CONTEXT:
|
||||
- PRD Section 3.1.2: User registration requirements
|
||||
- SDD Section 4.2: API endpoint specifications
|
||||
- SDD Section 5.3: Database schema for users table
|
||||
- PLAN Phase 2, Task 3: Implementation checklist
|
||||
|
||||
SDD_REQUIREMENTS:
|
||||
- Endpoint: POST /api/auth/register
|
||||
- Request body: { email, password, name }
|
||||
- Response: { user_id, token }
|
||||
- Validation: Email format, password strength (8+ chars)
|
||||
- Security: Bcrypt hashing (cost 12)
|
||||
|
||||
SPECIFICATION_CHECK: Must match SDD Section 4.2 exactly
|
||||
```
|
||||
|
||||
**Pattern:** Explicit spec references prevent context drift.
|
||||
|
||||
## File Coordination Advanced Strategies
|
||||
|
||||
### Timestamp-Based Uniqueness
|
||||
|
||||
When paths might collide, add timestamps:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: logs/analysis-${TIMESTAMP}.md
|
||||
Agent 2 OUTPUT: logs/research-${TIMESTAMP}.md
|
||||
Agent 3 OUTPUT: logs/synthesis-${TIMESTAMP}.md
|
||||
|
||||
where TIMESTAMP = ISO 8601 format
|
||||
```
|
||||
|
||||
**Result:** No collisions even if agents run simultaneously.
|
||||
|
||||
### Directory Hierarchy Assignment
|
||||
|
||||
Assign each agent a subdirectory:
|
||||
|
||||
```
|
||||
Agent 1 OUTPUT: results/agent-1/findings.md
|
||||
Agent 2 OUTPUT: results/agent-2/findings.md
|
||||
Agent 3 OUTPUT: results/agent-3/findings.md
|
||||
```
|
||||
|
||||
**Result:** Each agent owns a directory, filenames can repeat.
|
||||
|
||||
### Atomic File Creation Pattern
|
||||
|
||||
For critical files, ensure atomic creation:
|
||||
|
||||
```
|
||||
OUTPUT: Create file at exact path: docs/patterns/auth.md
|
||||
- If file exists, FAIL and report (don't overwrite)
|
||||
- Use atomic write (temp file + rename)
|
||||
- Verify write succeeded before marking complete
|
||||
```
|
||||
|
||||
**Pattern:** Prevents race conditions and corruption.
|
||||
|
||||
### Merge Strategy Pattern
|
||||
|
||||
When multiple agents create similar content:
|
||||
|
||||
```
|
||||
Strategy: Sequential merge
|
||||
|
||||
Agent 1: Create base document
|
||||
Agent 2: Read base, add section 2
|
||||
Agent 3: Read base + section 2, add section 3
|
||||
|
||||
Each agent:
|
||||
DISCOVERY_FIRST: Read current state of document
|
||||
FOCUS: Add my section without modifying others
|
||||
OUTPUT: Updated document with my section added
|
||||
```
|
||||
|
||||
**Pattern:** Sequential additions to shared document.
|
||||
|
||||
## Scope Validation Advanced Patterns
|
||||
|
||||
### Severity-Based Acceptance
|
||||
|
||||
Categorize scope creep by severity:
|
||||
|
||||
**Minor (Auto-accept):**
|
||||
- Variable name improvements
|
||||
- Comment additions
|
||||
- Whitespace formatting
|
||||
- Import organization
|
||||
|
||||
**Medium (Review):**
|
||||
- Small refactors related to task
|
||||
- Additional error handling
|
||||
- Logging additions
|
||||
- Documentation updates
|
||||
|
||||
**Major (Reject):**
|
||||
- New features
|
||||
- Architecture changes
|
||||
- Dependency additions
|
||||
- Breaking changes
|
||||
|
||||
### Value-Based Exception Handling
|
||||
|
||||
Sometimes scope creep is valuable:
|
||||
|
||||
```
|
||||
Agent delivered:
|
||||
✅ Required: Authentication endpoint
|
||||
⚠️ Extra: Rate limiting on endpoint (not requested)
|
||||
|
||||
Analysis:
|
||||
- Extra work: Rate limiting
|
||||
- In EXCLUDE? No (not explicitly excluded)
|
||||
- Valuable? Yes (security best practice)
|
||||
- Risky? No (standard pattern)
|
||||
- Increases scope? Minimally
|
||||
|
||||
Decision: 🟡 ACCEPT with note
|
||||
"Agent proactively added rate limiting for security.
|
||||
Aligns with best practices, accepting this valuable addition."
|
||||
```
|
||||
|
||||
**Pattern:** Auto-accept valuable, low-risk extras that align with project goals.
|
||||
|
||||
### Specification Drift Detection
|
||||
|
||||
For implement tasks, detect drift from specs:
|
||||
|
||||
```
|
||||
Validation:
|
||||
1. Check FOCUS matches PLAN task description
|
||||
2. Check implementation matches SDD requirements
|
||||
3. Check business logic matches PRD rules
|
||||
|
||||
Drift detected if:
|
||||
- Implementation differs from SDD design
|
||||
- Business rules differ from PRD
|
||||
- Features not in PLAN added
|
||||
|
||||
Report:
|
||||
📊 Specification Alignment: 85%
|
||||
✅ Aligned: [aspects that match]
|
||||
⚠️ Deviations: [aspects that differ]
|
||||
🔴 Critical drift: [major misalignments]
|
||||
```
|
||||
|
||||
## Retry Strategy Advanced Patterns
|
||||
|
||||
### Progressive Refinement
|
||||
|
||||
Refine template progressively across retries:
|
||||
|
||||
**Attempt 1 (Failed - too vague):**
|
||||
```
|
||||
FOCUS: Add caching
|
||||
```
|
||||
|
||||
**Attempt 2 (Failed - still ambiguous):**
|
||||
```
|
||||
FOCUS: Add Redis caching for API responses
|
||||
EXCLUDE: Don't cache user-specific data
|
||||
```
|
||||
|
||||
**Attempt 3 (Success - specific enough):**
|
||||
```
|
||||
FOCUS: Add Redis caching for public API endpoints
|
||||
- Cache GET requests only
|
||||
- TTL: 5 minutes
|
||||
- Key format: api:endpoint:params:hash
|
||||
- Invalidate on POST/PUT/DELETE to same resource
|
||||
|
||||
EXCLUDE:
|
||||
- Don't cache authenticated user requests
|
||||
- Don't cache admin endpoints
|
||||
- Don't implement cache warming
|
||||
- Don't add Redis cluster setup (single node for now)
|
||||
|
||||
CONTEXT:
|
||||
- Redis already configured: localhost:6379
|
||||
- Use ioredis client
|
||||
- Follow caching pattern: docs/patterns/caching-strategy.md
|
||||
```
|
||||
|
||||
**Pattern:** Each retry adds specificity based on previous failure.
|
||||
|
||||
### Agent Type Rotation
|
||||
|
||||
If specialist fails, try different angle:
|
||||
|
||||
```
|
||||
Attempt 1: Backend specialist
|
||||
- Focused on technical implementation
|
||||
- Failed: Too technical, missed user experience
|
||||
|
||||
Attempt 2: UX specialist
|
||||
- Focused on user flows
|
||||
- Failed: Too high-level, missed technical constraints
|
||||
|
||||
Attempt 3: Product specialist
|
||||
- Balanced user needs with technical reality
|
||||
- Success: Right blend of perspectives
|
||||
```
|
||||
|
||||
**Pattern:** Rotate expertise angle based on failure mode.
|
||||
|
||||
### Scope Reduction Strategy
|
||||
|
||||
If task too complex, reduce scope progressively:
|
||||
|
||||
```
|
||||
Attempt 1 (Failed - too much):
|
||||
FOCUS: Build complete authentication system
|
||||
- Registration, login, logout, password reset
|
||||
- OAuth integration
|
||||
- Two-factor authentication
|
||||
|
||||
Attempt 2 (Failed - still complex):
|
||||
FOCUS: Build basic authentication
|
||||
- Registration, login, logout
|
||||
|
||||
Attempt 3 (Success - minimal):
|
||||
FOCUS: Build login endpoint only
|
||||
- POST /auth/login
|
||||
- Email + password validation
|
||||
- Return JWT token
|
||||
```
|
||||
|
||||
**Pattern:** Reduce scope until agent succeeds, then expand incrementally.
|
||||
|
||||
## Edge Cases and Solutions
|
||||
|
||||
### Edge Case 1: Circular Dependencies
|
||||
|
||||
**Problem:** Agent A needs Agent B's output, Agent B needs Agent A's output
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
Activity A depends on B
|
||||
Activity B depends on A
|
||||
→ Circular dependency detected
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Break the cycle:**
|
||||
```
|
||||
Original:
|
||||
A (needs B) ↔ B (needs A)
|
||||
|
||||
Refactored:
|
||||
C (shared foundation) → A (builds on C) → B (builds on A)
|
||||
```
|
||||
|
||||
2. **Iterative approach:**
|
||||
```
|
||||
Round 1: A (with assumptions about B)
|
||||
Round 2: B (using Round 1 A)
|
||||
Round 3: A (refined with actual B)
|
||||
```
|
||||
|
||||
3. **Merge activities:**
|
||||
```
|
||||
Single agent handles both A and B together
|
||||
(They're too coupled to separate)
|
||||
```
|
||||
|
||||
### Edge Case 2: Dynamic Dependencies
|
||||
|
||||
**Problem:** Don't know dependencies until runtime
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Task: Analyze codebase
|
||||
|
||||
Don't know which modules exist until discovery
|
||||
Can't plan parallel structure upfront
|
||||
```
|
||||
|
||||
**Solution - Two-phase approach:**
|
||||
|
||||
**Phase 1: Discovery (sequential)**
|
||||
```
|
||||
Agent 1: Discover project structure
|
||||
OUTPUT: List of modules
|
||||
|
||||
Result: [moduleA, moduleB, moduleC, moduleD]
|
||||
```
|
||||
|
||||
**Phase 2: Analysis (parallel, dynamic)**
|
||||
```
|
||||
For each module in result:
|
||||
Launch analysis agent
|
||||
|
||||
Agent A: Analyze moduleA
|
||||
Agent B: Analyze moduleB
|
||||
Agent C: Analyze moduleC
|
||||
Agent D: Analyze moduleD
|
||||
```
|
||||
|
||||
**Pattern:** Sequential discovery, dynamic parallel execution.
|
||||
|
||||
### Edge Case 3: Partial Agent Availability
|
||||
|
||||
**Problem:** Some specialist agents unavailable
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Planned:
|
||||
- Frontend specialist (available)
|
||||
- Backend specialist (available)
|
||||
- DevOps specialist (NOT AVAILABLE)
|
||||
```
|
||||
|
||||
**Solution - Fallback delegation:**
|
||||
|
||||
```
|
||||
If specialist unavailable:
|
||||
1. Try broader domain agent (general-purpose)
|
||||
2. Try sequential breakdown (smaller tasks)
|
||||
3. Handle directly if simple enough
|
||||
4. Escalate to user if critical
|
||||
```
|
||||
|
||||
**Example execution:**
|
||||
```
|
||||
DevOps work:
|
||||
Attempt 1: DevOps specialist → UNAVAILABLE
|
||||
Attempt 2: Backend specialist with DevOps context → SUCCESS
|
||||
Reasoning: Backend specialist has some DevOps overlap
|
||||
```
|
||||
|
||||
### Edge Case 4: Agent Response Conflicts
|
||||
|
||||
**Problem:** Parallel agents return conflicting recommendations
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Agent 1 (Security): "Use bcrypt with cost 14 (maximum security)"
|
||||
Agent 2 (Performance): "Use bcrypt with cost 10 (reasonable security, better performance)"
|
||||
```
|
||||
|
||||
**Solution - Conflict resolution:**
|
||||
|
||||
**1. Present to user:**
|
||||
```
|
||||
⚠️ Agent Conflict Detected
|
||||
|
||||
Topic: Bcrypt cost factor
|
||||
Agent 1 (Security): Cost 14 (maximize security)
|
||||
Agent 2 (Performance): Cost 10 (balance security/performance)
|
||||
|
||||
Trade-off:
|
||||
- Cost 14: ~200ms hashing time, highest security
|
||||
- Cost 10: ~50ms hashing time, strong security
|
||||
|
||||
Recommendation needed: Which priority matters more?
|
||||
```
|
||||
|
||||
**2. Specification arbitration:**
|
||||
```
|
||||
Check specs:
|
||||
- SDD Section 5.2: "Use bcrypt cost factor 12"
|
||||
→ Use specification value (12)
|
||||
→ Both agents adjusted to match spec
|
||||
```
|
||||
|
||||
**3. Synthesis agent:**
|
||||
```
|
||||
Launch Agent 3 (Architect):
|
||||
FOCUS: Resolve conflict between security and performance recommendations
|
||||
CONTEXT:
|
||||
- Security recommendation: cost 14
|
||||
- Performance recommendation: cost 10
|
||||
- Trade-offs: [details]
|
||||
OUTPUT: Final recommendation with reasoning
|
||||
```
|
||||
|
||||
### Edge Case 5: Resource Constraints
|
||||
|
||||
**Problem:** Can't launch all parallel agents simultaneously (rate limits, memory, etc.)
|
||||
|
||||
**Solution - Batched parallel execution:**
|
||||
|
||||
```
|
||||
Activities: [A1, A2, A3, A4, A5, A6, A7, A8]
|
||||
Constraint: Maximum 3 parallel agents
|
||||
|
||||
Execution:
|
||||
Batch 1: A1, A2, A3 (parallel)
|
||||
→ Wait for completion
|
||||
Batch 2: A4, A5, A6 (parallel)
|
||||
→ Wait for completion
|
||||
Batch 3: A7, A8 (parallel)
|
||||
→ Complete
|
||||
```
|
||||
|
||||
**Pattern:** Maintain parallelism within constraints.
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Minimize Context Size
|
||||
|
||||
Don't pass everything to every agent:
|
||||
|
||||
❌ **Bad - Full context:**
|
||||
```
|
||||
CONTEXT:
|
||||
- Entire PRD (50 pages)
|
||||
- Entire SDD (40 pages)
|
||||
- All prior agent outputs (30 pages)
|
||||
```
|
||||
|
||||
✅ **Good - Relevant context:**
|
||||
```
|
||||
CONTEXT:
|
||||
- PRD Section 3.2 (User authentication requirements)
|
||||
- SDD Section 4.1 (API endpoint design)
|
||||
- Prior output: Authentication flow diagram from Agent 1
|
||||
```
|
||||
|
||||
**Pattern:** Extract only relevant portions, reference docs by section.
|
||||
|
||||
### Parallel Batching
|
||||
|
||||
Group related parallel tasks:
|
||||
|
||||
```
|
||||
Don't:
|
||||
Launch 20 individual research agents
|
||||
|
||||
Do:
|
||||
Launch 4 research agents, each handles 5 topics
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Fewer coordination overhead
|
||||
- Better context utilization
|
||||
- Faster overall completion
|
||||
|
||||
### Early Termination
|
||||
|
||||
Build termination conditions into templates:
|
||||
|
||||
```
|
||||
TERMINATION:
|
||||
- Completed successfully
|
||||
- Blocked by missing dependency X
|
||||
- Information not publicly available
|
||||
- Maximum 3 attempts reached
|
||||
- ERROR: [specific error conditions]
|
||||
```
|
||||
|
||||
**Pattern:** Let agents fail fast instead of hanging.
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
### With Documentation Skill
|
||||
|
||||
When agents discover patterns:
|
||||
|
||||
```
|
||||
Agent completes task
|
||||
↓
|
||||
Discovers reusable pattern
|
||||
↓
|
||||
Documentation skill activates
|
||||
↓
|
||||
Pattern documented in docs/patterns/
|
||||
↓
|
||||
Reported back to orchestrator
|
||||
```
|
||||
|
||||
**Coordination:** Agent-delegation creates prompts, documentation skill handles pattern storage.
|
||||
|
||||
### With Specification Review Skill
|
||||
|
||||
For implementation tasks:
|
||||
|
||||
```
|
||||
Agent completes implementation
|
||||
↓
|
||||
Agent-delegation validates scope
|
||||
↓
|
||||
Specification review skill validates against PRD/SDD
|
||||
↓
|
||||
Both validations pass → Complete
|
||||
```
|
||||
|
||||
**Coordination:** Agent-delegation handles scope, spec-review handles alignment.
|
||||
|
||||
### With Quality Gates Skill
|
||||
|
||||
At phase boundaries:
|
||||
|
||||
```
|
||||
Phase completes
|
||||
↓
|
||||
Agent-delegation confirms all tasks done
|
||||
↓
|
||||
Quality gates skill runs DOD checks
|
||||
↓
|
||||
Both pass → Proceed to next phase
|
||||
```
|
||||
|
||||
**Coordination:** Agent-delegation manages execution, quality-gates validates quality.
|
||||
|
||||
## Debugging Failed Delegations
|
||||
|
||||
### Symptom: Agents ignore EXCLUDE
|
||||
|
||||
**Diagnosis:**
|
||||
- EXCLUDE too vague
|
||||
- Agent sees value in excluded work
|
||||
- Conflict between FOCUS and EXCLUDE
|
||||
|
||||
**Fix:**
|
||||
```
|
||||
Before:
|
||||
EXCLUDE: Don't add extra features
|
||||
|
||||
After:
|
||||
EXCLUDE: Do not add these specific features:
|
||||
- OAuth integration (separate task)
|
||||
- Password reset flow (separate task)
|
||||
- Two-factor authentication (not in scope)
|
||||
Any feature not explicitly in FOCUS is out of scope.
|
||||
```
|
||||
|
||||
### Symptom: Parallel agents conflict
|
||||
|
||||
**Diagnosis:**
|
||||
- Hidden shared state
|
||||
- File path collision
|
||||
- Dependency not identified
|
||||
|
||||
**Fix:**
|
||||
```
|
||||
Review parallel safety checklist:
|
||||
- Independent tasks? → Check dependencies again
|
||||
- Unique file paths? → Verify OUTPUT sections
|
||||
- No shared state? → Identify what's shared
|
||||
|
||||
If any fail → Make sequential or coordinate better
|
||||
```
|
||||
|
||||
### Symptom: Sequential too slow
|
||||
|
||||
**Diagnosis:**
|
||||
- False dependencies
|
||||
- Over-cautious sequencing
|
||||
- Could be parallel with coordination
|
||||
|
||||
**Fix:**
|
||||
```
|
||||
Re-analyze dependencies:
|
||||
- Must Task B use Task A's output? → True dependency
|
||||
- Could Task B assume Task A's approach? → False dependency
|
||||
|
||||
If false dependency:
|
||||
→ Make parallel with coordinated assumptions
|
||||
```
|
||||
|
||||
### Symptom: Template too complex
|
||||
|
||||
**Diagnosis:**
|
||||
- Too many constraints
|
||||
- Context overload
|
||||
- Agent confused by detail
|
||||
|
||||
**Fix:**
|
||||
```
|
||||
Simplify:
|
||||
1. Keep FOCUS to essentials
|
||||
2. Move details to CONTEXT
|
||||
3. Provide examples instead of rules
|
||||
|
||||
Before (overwhelming):
|
||||
FOCUS: [20 lines of detailed requirements]
|
||||
|
||||
After (simplified):
|
||||
FOCUS: [2 lines of core task]
|
||||
CONTEXT: [Details and constraints]
|
||||
```
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
1. **Decompose by activities**, not roles
|
||||
2. **Parallel by default**, sequential only when necessary
|
||||
3. **Explicit FOCUS/EXCLUDE**, no ambiguity
|
||||
4. **Unique file paths**, verify before launching
|
||||
5. **Minimal context**, only relevant information
|
||||
6. **Auto-accept safe changes**, review architectural ones
|
||||
7. **Maximum 3 retries**, then escalate
|
||||
8. **Early termination**, fail fast when blocked
|
||||
9. **Validate scope**, check FOCUS/EXCLUDE adherence
|
||||
10. **Document patterns**, activate documentation skill when discovered
|
||||
|
||||
## Common Patterns Quick Reference
|
||||
|
||||
| Pattern | When to Use | Structure |
|
||||
|---------|-------------|-----------|
|
||||
| Fan-Out/Fan-In | Parallel research → synthesis | Parallel → Sequential |
|
||||
| Pipeline | Stages with parallel within | Sequential stages, parallel tasks |
|
||||
| MapReduce | Large dataset processing | Parallel map → Sequential reduce |
|
||||
| Progressive Refinement | Retry with more detail | Retry N adds specificity |
|
||||
| Batched Parallel | Resource constraints | Groups of parallel tasks |
|
||||
| Context Accumulation | Sequential with learning | Each task gets prior outputs |
|
||||
| Constraint Propagation | Dependent implementations | SUCCESS → next CONTEXT |
|
||||
| Specification Reference | Implementation tasks | Explicit PRD/SDD references |
|
||||
|
||||
---
|
||||
|
||||
This reference covers advanced scenarios beyond the main skill. Load this when dealing with complex coordination, optimization, or edge cases.
|
||||
213
skills/documentation/SKILL.md
Normal file
213
skills/documentation/SKILL.md
Normal file
@@ -0,0 +1,213 @@
|
||||
---
|
||||
name: documentation
|
||||
description: Document business rules, technical patterns, and service interfaces discovered during analysis or implementation. Use when you find reusable patterns, external integrations, domain-specific rules, or API contracts. Always check existing documentation before creating new files. Handles deduplication and proper categorization.
|
||||
allowed-tools: Read, Write, Edit, Grep, Glob
|
||||
---
|
||||
|
||||
You are a documentation specialist that captures and organizes knowledge discovered during development work.
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
All documentation follows this hierarchy:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── domain/ # Business rules, domain logic, workflows, validation rules
|
||||
├── patterns/ # Technical patterns, architectural solutions, code patterns
|
||||
├── interfaces/ # External API contracts, service integrations, webhooks
|
||||
```
|
||||
|
||||
## Decision Tree: What Goes Where?
|
||||
|
||||
### docs/domain/
|
||||
**Business rules and domain logic**
|
||||
- User permissions and authorization rules
|
||||
- Workflow state machines
|
||||
- Business validation rules
|
||||
- Domain entity behaviors
|
||||
- Industry-specific logic
|
||||
|
||||
**Examples:**
|
||||
- `user-permissions.md` - Who can do what
|
||||
- `order-workflow.md` - Order state transitions
|
||||
- `pricing-rules.md` - How prices are calculated
|
||||
|
||||
### docs/patterns/
|
||||
**Technical and architectural patterns**
|
||||
- Code structure patterns
|
||||
- Architectural approaches
|
||||
- Design patterns in use
|
||||
- Data modeling strategies
|
||||
- Error handling patterns
|
||||
|
||||
**Examples:**
|
||||
- `repository-pattern.md` - Data access abstraction
|
||||
- `caching-strategy.md` - How caching is implemented
|
||||
- `error-handling.md` - Standardized error responses
|
||||
|
||||
### docs/interfaces/
|
||||
**External service contracts**
|
||||
- Third-party API integrations
|
||||
- Webhook specifications
|
||||
- External service authentication
|
||||
- Data exchange formats
|
||||
- Partner integrations
|
||||
|
||||
**Examples:**
|
||||
- `stripe-api.md` - Payment processing integration
|
||||
- `sendgrid-webhooks.md` - Email event handling
|
||||
- `oauth-providers.md` - Authentication integrations
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 0: DEDUPLICATION (REQUIRED - DO THIS FIRST)
|
||||
|
||||
**Always check for existing documentation before creating new files:**
|
||||
|
||||
```bash
|
||||
# Search for existing documentation
|
||||
grep -ri "main keyword" docs/domain/ docs/patterns/ docs/interfaces/
|
||||
find docs -name "*topic-keyword*"
|
||||
```
|
||||
|
||||
**Decision Tree**:
|
||||
- **Found similar documentation** → Use Edit to UPDATE existing file instead
|
||||
- **Found NO similar documentation** → Proceed to Step 1 (Determine Category)
|
||||
|
||||
**Critical**: Always prefer updating existing files over creating new ones. Deduplication prevents documentation fragmentation.
|
||||
|
||||
### Step 1: Determine Category
|
||||
|
||||
Ask yourself:
|
||||
- **Is this about business logic?** → `docs/domain/`
|
||||
- **Is this about how we build?** → `docs/patterns/`
|
||||
- **Is this about external services?** → `docs/interfaces/`
|
||||
|
||||
### Step 2: Choose: Create New or Update Existing
|
||||
|
||||
**Create new** if:
|
||||
- No related documentation exists
|
||||
- Topic is distinct enough to warrant separation
|
||||
- Would create confusion to merge with existing doc
|
||||
|
||||
**Update existing** if:
|
||||
- Related documentation already exists
|
||||
- New info enhances existing document
|
||||
- Same category and closely related topic
|
||||
|
||||
### Step 3: Use Descriptive, Searchable Names
|
||||
|
||||
**Good names:**
|
||||
- `authentication-flow.md` (clear, searchable)
|
||||
- `database-migration-strategy.md` (specific)
|
||||
- `stripe-payment-integration.md` (exact)
|
||||
|
||||
**Bad names:**
|
||||
- `auth.md` (too vague)
|
||||
- `db.md` (unclear)
|
||||
- `api.md` (which API?)
|
||||
|
||||
### Step 4: Follow the Template Structure
|
||||
|
||||
Use the templates in `templates/` for consistent formatting:
|
||||
- `pattern-template.md` - For technical patterns
|
||||
- `interface-template.md` - For external integrations
|
||||
- `domain-template.md` - For business rules
|
||||
|
||||
## Document Structure Standards
|
||||
|
||||
Every document should include:
|
||||
|
||||
1. **Title and Purpose** - What this documents
|
||||
2. **Context** - When/why this applies
|
||||
3. **Details** - The actual content (patterns, rules, contracts)
|
||||
4. **Examples** - Code snippets or scenarios
|
||||
5. **References** - Related docs or external links
|
||||
|
||||
## Deduplication Protocol
|
||||
|
||||
Before creating any documentation:
|
||||
|
||||
1. **Search by topic**: `grep -ri "topic" docs/`
|
||||
2. **Check category**: List files in target category
|
||||
3. **Read related files**: Verify no overlap
|
||||
4. **Decide**: Create new vs enhance existing
|
||||
5. **Cross-reference**: Link between related docs
|
||||
|
||||
## Examples in Action
|
||||
|
||||
### Example 1: API Integration Discovery
|
||||
|
||||
**Scenario:** Implementing Stripe payment processing
|
||||
|
||||
**Analysis:**
|
||||
- External service? → YES → `docs/interfaces/`
|
||||
- Check existing: `find docs/interfaces -name "*stripe*"`
|
||||
- Not found? → Create `docs/interfaces/stripe-payments.md`
|
||||
- Use `interface-template.md`
|
||||
|
||||
### Example 2: Caching Pattern Discovery
|
||||
|
||||
**Scenario:** Found Redis caching in authentication module
|
||||
|
||||
**Analysis:**
|
||||
- External service? → NO
|
||||
- Business rule? → NO
|
||||
- Technical pattern? → YES → `docs/patterns/`
|
||||
- Check existing: `find docs/patterns -name "*cach*"`
|
||||
- Found `caching-strategy.md`? → Update it
|
||||
- Not found? → Create `docs/patterns/caching-strategy.md`
|
||||
|
||||
### Example 3: Permission Rule Discovery
|
||||
|
||||
**Scenario:** Users can only edit their own posts
|
||||
|
||||
**Analysis:**
|
||||
- Business rule? → YES → `docs/domain/`
|
||||
- External service? → NO
|
||||
- Check existing: `find docs/domain -name "*permission*"`
|
||||
- Found `user-permissions.md`? → Update it
|
||||
- Not found? → Create `docs/domain/user-permissions.md`
|
||||
|
||||
## Cross-Referencing
|
||||
|
||||
When documentation relates to other docs:
|
||||
|
||||
```markdown
|
||||
## Related Documentation
|
||||
|
||||
- [Authentication Flow](../patterns/authentication-flow.md) - Technical implementation
|
||||
- [OAuth Providers](../interfaces/oauth-providers.md) - External integrations
|
||||
- [User Permissions](../domain/user-permissions.md) - Business rules
|
||||
```
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before finalizing any documentation:
|
||||
|
||||
- [ ] Checked for existing related documentation
|
||||
- [ ] Chosen correct category (domain/patterns/interfaces)
|
||||
- [ ] Used descriptive, searchable filename
|
||||
- [ ] Included title, context, details, examples
|
||||
- [ ] Added cross-references to related docs
|
||||
- [ ] Used appropriate template structure
|
||||
- [ ] Verified no duplicate content
|
||||
|
||||
## Output Format
|
||||
|
||||
After documenting, always report:
|
||||
|
||||
```
|
||||
📝 Documentation Created/Updated:
|
||||
- docs/[category]/[filename].md
|
||||
Purpose: [Brief description]
|
||||
Action: [Created new / Updated existing / Merged with existing]
|
||||
```
|
||||
|
||||
## Remember
|
||||
|
||||
- **Deduplication is critical** - Always check first
|
||||
- **Categories matter** - Business vs Technical vs External
|
||||
- **Names are discoverable** - Use full, descriptive names
|
||||
- **Templates ensure consistency** - Follow the structure
|
||||
- **Cross-reference liberally** - Connect related knowledge
|
||||
388
skills/documentation/reference.md
Normal file
388
skills/documentation/reference.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# Documentation Skill Reference
|
||||
|
||||
Complete reference for the documentation skill including advanced patterns, edge cases, and detailed protocols.
|
||||
|
||||
## Advanced Categorization Rules
|
||||
|
||||
### Gray Areas and Edge Cases
|
||||
|
||||
#### When Business and Technical Overlap
|
||||
|
||||
**Authentication Example:**
|
||||
- `docs/domain/user-roles.md` - WHO can access WHAT (business rule)
|
||||
- `docs/patterns/authentication-flow.md` - HOW authentication works (technical)
|
||||
- `docs/interfaces/oauth-providers.md` - EXTERNAL services used (integration)
|
||||
|
||||
**Guideline:** If it affects WHAT users can do → domain. If it affects HOW we build it → patterns.
|
||||
|
||||
#### When Pattern Becomes Interface
|
||||
|
||||
**Caching Example:**
|
||||
- Local in-memory caching → `docs/patterns/caching-strategy.md`
|
||||
- Redis/Memcached integration → `docs/interfaces/redis-cache.md`
|
||||
|
||||
**Guideline:** Self-contained code patterns → patterns. External service dependencies → interfaces.
|
||||
|
||||
#### When Multiple Categories Apply
|
||||
|
||||
**Payment Processing Example:**
|
||||
Could span all three:
|
||||
- `docs/domain/payment-rules.md` - Refund policies, pricing rules
|
||||
- `docs/patterns/payment-processing.md` - Internal payment handling
|
||||
- `docs/interfaces/stripe-api.md` - Stripe integration specifics
|
||||
|
||||
**Guideline:** Create separate documents for each perspective. Cross-reference heavily.
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Pattern: `[noun]-[noun/verb].md`
|
||||
|
||||
**Good Examples:**
|
||||
- `error-handling.md`
|
||||
- `database-migrations.md`
|
||||
- `api-versioning.md`
|
||||
- `event-sourcing.md`
|
||||
|
||||
**Avoid:**
|
||||
- Single words: `cache.md`, `auth.md`
|
||||
- Abbreviations: `db-mig.md`, `err-hdl.md`
|
||||
- Generic terms: `utilities.md`, `helpers.md`
|
||||
|
||||
### Interface: `[service-name]-[integration-type].md`
|
||||
|
||||
**Good Examples:**
|
||||
- `stripe-payments.md`
|
||||
- `sendgrid-webhooks.md`
|
||||
- `github-api.md`
|
||||
- `aws-s3-storage.md`
|
||||
|
||||
**Avoid:**
|
||||
- Generic: `payment-gateway.md` (which one?)
|
||||
- Vague: `email.md` (what about email?)
|
||||
- Tech-only: `rest-api.md` (which service?)
|
||||
|
||||
### Domain: `[entity/concept]-[aspect].md`
|
||||
|
||||
**Good Examples:**
|
||||
- `user-permissions.md`
|
||||
- `order-workflow.md`
|
||||
- `inventory-tracking.md`
|
||||
- `pricing-rules.md`
|
||||
|
||||
**Avoid:**
|
||||
- Implementation details: `user-table.md` (that's technical)
|
||||
- Generic: `rules.md` (which rules?)
|
||||
- Too broad: `business-logic.md` (everything?)
|
||||
|
||||
## Update vs Create Decision Matrix
|
||||
|
||||
| Scenario | Existing Doc | Action |
|
||||
|----------|--------------|--------|
|
||||
| New payment provider | `stripe-payments.md` exists | **Create** `paypal-payments.md` (different service) |
|
||||
| Additional caching layer | `caching-strategy.md` exists | **Update** existing (same pattern, new details) |
|
||||
| New user role type | `user-permissions.md` exists | **Update** existing (extends same rule set) |
|
||||
| Different auth method | `jwt-authentication.md` exists | **Create** `oauth-authentication.md` (different approach) |
|
||||
| API version change | `github-api.md` exists | **Update** existing (same service, evolved) |
|
||||
| New business constraint | `order-workflow.md` exists | **Update** if related, **Create** if distinct |
|
||||
|
||||
**Guiding Principle:** Same topic/service = update. Different topic/service = create new.
|
||||
|
||||
## Template Usage Guidelines
|
||||
|
||||
### Pattern Template
|
||||
Use for:
|
||||
- Architectural decisions (MVC, microservices, event-driven)
|
||||
- Code organization patterns (repository, factory, singleton)
|
||||
- Data handling approaches (caching, validation, serialization)
|
||||
- Testing strategies (unit, integration, e2e)
|
||||
|
||||
### Interface Template
|
||||
Use for:
|
||||
- Third-party API integrations
|
||||
- Webhook implementations
|
||||
- External service authentication
|
||||
- Data exchange protocols
|
||||
- Partner system integrations
|
||||
|
||||
### Domain Template
|
||||
Use for:
|
||||
- Business rules and constraints
|
||||
- User permission systems
|
||||
- Workflow state machines
|
||||
- Validation requirements
|
||||
- Domain entity behaviors
|
||||
|
||||
## Deduplication Techniques
|
||||
|
||||
### Technique 1: Keyword Search
|
||||
```bash
|
||||
# Search filenames
|
||||
find docs -type f -name "*.md" | grep -i keyword
|
||||
|
||||
# Search content
|
||||
grep -ri "search term" docs/
|
||||
```
|
||||
|
||||
### Technique 2: Category Listing
|
||||
```bash
|
||||
# List all patterns
|
||||
ls docs/patterns/
|
||||
|
||||
# List all interfaces
|
||||
ls docs/interfaces/
|
||||
|
||||
# List all domain docs
|
||||
ls docs/domain/
|
||||
```
|
||||
|
||||
### Technique 3: Content Scanning
|
||||
```bash
|
||||
# Show first 5 lines of each file
|
||||
find docs/patterns -name "*.md" -exec head -5 {} \; -print
|
||||
|
||||
# Search for specific concept
|
||||
grep -l "authentication" docs/**/*.md
|
||||
```
|
||||
|
||||
### Technique 4: Related Term Mapping
|
||||
|
||||
For a new document about "caching":
|
||||
- Check for: cache, caching, cached, memoization, storage
|
||||
- Check categories: patterns (implementation), interfaces (Redis/Memcached)
|
||||
- Read related files before deciding
|
||||
|
||||
## Merge vs Separate Guidelines
|
||||
|
||||
### Merge When:
|
||||
- Same category and closely related topic
|
||||
- Information enhances without confusing
|
||||
- Single cohesive narrative possible
|
||||
- Total length stays under 500 lines
|
||||
|
||||
**Example:** Merging "JWT tokens" into existing `authentication-flow.md`
|
||||
|
||||
### Keep Separate When:
|
||||
- Different approaches to same problem
|
||||
- Distinct services/technologies
|
||||
- Would make document unfocused
|
||||
- Exceeds reasonable length
|
||||
|
||||
**Example:** `jwt-authentication.md` and `oauth-authentication.md` as separate files
|
||||
|
||||
## Cross-Reference Patterns
|
||||
|
||||
### Within Same Category
|
||||
```markdown
|
||||
## Related Patterns
|
||||
- [Repository Pattern](./repository-pattern.md) - Data access layer
|
||||
- [Service Layer](./service-layer.md) - Business logic organization
|
||||
```
|
||||
|
||||
### Across Categories
|
||||
```markdown
|
||||
## Related Documentation
|
||||
- **Domain:** [User Permissions](../domain/user-permissions.md) - Authorization rules
|
||||
- **Patterns:** [Authentication Flow](../patterns/authentication-flow.md) - Technical implementation
|
||||
- **Interfaces:** [OAuth Providers](../interfaces/oauth-providers.md) - External auth services
|
||||
```
|
||||
|
||||
### To Specifications
|
||||
```markdown
|
||||
## Implementations
|
||||
- [User Authentication](../specs/001-user-auth/SDD.md) - Technical specification
|
||||
- [OAuth Integration](../specs/015-oauth/PRD.md) - Product requirements
|
||||
```
|
||||
|
||||
## Version Management
|
||||
|
||||
### When Patterns Evolve
|
||||
|
||||
**Approach 1: Update in Place**
|
||||
- Add "Version History" section
|
||||
- Document what changed and when
|
||||
- Keep current approach primary
|
||||
|
||||
**Approach 2: Separate Documents**
|
||||
- `authentication-v1.md` (legacy)
|
||||
- `authentication-v2.md` (current)
|
||||
- Clear migration path documented
|
||||
|
||||
**Guideline:** Update in place unless breaking change makes old version still relevant for existing code.
|
||||
|
||||
### Deprecation
|
||||
|
||||
When a pattern/interface is superseded:
|
||||
|
||||
```markdown
|
||||
# Old Authentication Pattern
|
||||
|
||||
> **⚠️ DEPRECATED:** This pattern is no longer recommended.
|
||||
> See [New Authentication Flow](./authentication-flow.md) for current approach.
|
||||
>
|
||||
> This document is maintained for reference by legacy code in modules X, Y, Z.
|
||||
|
||||
[Original content preserved...]
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Completeness Checklist
|
||||
- [ ] Title clearly states what is documented
|
||||
- [ ] Context explains when/why this applies
|
||||
- [ ] Examples show real usage
|
||||
- [ ] Edge cases are covered
|
||||
- [ ] Related docs are linked
|
||||
- [ ] Code snippets use real project conventions
|
||||
|
||||
### Clarity Checklist
|
||||
- [ ] New team member could understand it
|
||||
- [ ] Technical terms are explained
|
||||
- [ ] Assumptions are stated explicitly
|
||||
- [ ] Steps are in logical order
|
||||
- [ ] Diagrams included for complex flows (if applicable)
|
||||
|
||||
### Maintainability Checklist
|
||||
- [ ] Searchable filename
|
||||
- [ ] Correct category
|
||||
- [ ] No duplicate content
|
||||
- [ ] Cross-references are bidirectional
|
||||
- [ ] Version history if evolved
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ Mistake 1: Creating Without Checking
|
||||
**Problem:** Duplicate documentation proliferates
|
||||
**Solution:** Always search first - multiple ways (grep, find, ls)
|
||||
|
||||
### ❌ Mistake 2: Wrong Category
|
||||
**Problem:** Business rules in patterns/, technical details in domain/
|
||||
**Solution:** Ask "Is this about WHAT (domain) or HOW (patterns)?"
|
||||
|
||||
### ❌ Mistake 3: Too Generic Names
|
||||
**Problem:** Can't find documentation later
|
||||
**Solution:** Full descriptive names, not abbreviations
|
||||
|
||||
### ❌ Mistake 4: No Cross-References
|
||||
**Problem:** Related knowledge stays siloed
|
||||
**Solution:** Link liberally between related docs
|
||||
|
||||
### ❌ Mistake 5: Template Ignored
|
||||
**Problem:** Inconsistent structure makes scanning hard
|
||||
**Solution:** Follow templates for consistency
|
||||
|
||||
### ❌ Mistake 6: No Examples
|
||||
**Problem:** Abstract descriptions don't help
|
||||
**Solution:** Include real code snippets and scenarios
|
||||
|
||||
## Edge Case Handling
|
||||
|
||||
### What if Nothing Fits the Categories?
|
||||
|
||||
**Option 1:** Expand categories (rare, think hard first)
|
||||
**Option 2:** Create `docs/architecture/` for cross-cutting concerns
|
||||
**Option 3:** Add to specification docs if feature-specific
|
||||
|
||||
**Example:** ADRs (Architecture Decision Records) might warrant `docs/decisions/`
|
||||
|
||||
### What if It's Too Small to Document?
|
||||
|
||||
**Guideline:** If it's reusable or non-obvious, document it.
|
||||
|
||||
**Too small:**
|
||||
- "We use camelCase" (coding standard, not pattern)
|
||||
- "API returns JSON" (obvious, not worth documenting)
|
||||
|
||||
**Worth documenting:**
|
||||
- "We use optimistic locking for inventory" (non-obvious pattern)
|
||||
- "Rate limiting uses token bucket algorithm" (specific approach)
|
||||
|
||||
### What if It's Extremely Specific?
|
||||
|
||||
**Guideline:** Very feature-specific logic goes in specs, not shared docs.
|
||||
|
||||
**Spec-level:**
|
||||
- `specs/023-checkout/SDD.md` - Checkout flow specifics
|
||||
|
||||
**Shared docs:**
|
||||
- `docs/patterns/state-machines.md` - Reusable state machine pattern
|
||||
- `docs/domain/order-workflow.md` - General order rules
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Keep Docs Focused
|
||||
- Single file shouldn't exceed 1000 lines
|
||||
- Split large topics into multiple focused docs
|
||||
- Use cross-references instead of duplicating
|
||||
|
||||
### Optimize for Searchability
|
||||
- Use keywords in filename
|
||||
- Include synonyms in content
|
||||
- Add tags/topics section at top
|
||||
|
||||
### Progressive Detail
|
||||
```markdown
|
||||
# Caching Strategy
|
||||
|
||||
Quick overview: We use Redis for session and API response caching.
|
||||
|
||||
## Details
|
||||
[Detailed implementation...]
|
||||
|
||||
## Advanced Configuration
|
||||
[Complex edge cases...]
|
||||
```
|
||||
|
||||
## Integration with Specifications
|
||||
|
||||
### During Analysis (`/start:analyze`)
|
||||
Documentation skill captures discovered patterns:
|
||||
- Code analysis reveals patterns → Document in `docs/patterns/`
|
||||
- Business rules discovered → Document in `docs/domain/`
|
||||
- External APIs found → Document in `docs/interfaces/`
|
||||
|
||||
### During Specification (`/start:specify`)
|
||||
- PRD/SDD references existing documentation
|
||||
- New patterns discovered → Document them
|
||||
- Specifications live in `docs/specs/`, reference shared docs
|
||||
|
||||
### During Implementation (`/start:implement`)
|
||||
- Implementation follows documented patterns
|
||||
- Deviations discovered → Update documentation
|
||||
- New patterns emerge → Document for reuse
|
||||
|
||||
## Automation Support
|
||||
|
||||
### Pre-documentation Checks
|
||||
Automate the search process:
|
||||
```bash
|
||||
# Check if topic exists
|
||||
./scripts/check-doc-exists.sh "authentication"
|
||||
|
||||
# List related docs
|
||||
./scripts/find-related-docs.sh "payment"
|
||||
```
|
||||
|
||||
### Post-documentation Validation
|
||||
```bash
|
||||
# Verify no duplicates
|
||||
./scripts/validate-docs.sh
|
||||
|
||||
# Check cross-references
|
||||
./scripts/check-links.sh
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
The documentation skill ensures:
|
||||
1. **No duplication** - Always check before creating
|
||||
2. **Correct categorization** - Business vs Technical vs External
|
||||
3. **Discoverability** - Descriptive names and cross-references
|
||||
4. **Consistency** - Template-based structure
|
||||
5. **Maintainability** - Clear, complete, and up-to-date
|
||||
|
||||
When in doubt, ask:
|
||||
- Does related documentation already exist?
|
||||
- Which category fits best?
|
||||
- What name would I search for?
|
||||
- What template applies?
|
||||
- How does this connect to other knowledge?
|
||||
325
skills/documentation/templates/domain-template.md
Normal file
325
skills/documentation/templates/domain-template.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# [Domain Concept/Entity Name]
|
||||
|
||||
> **Category:** Domain/Business Rules
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Under Review/Deprecated]
|
||||
|
||||
## Overview
|
||||
|
||||
**What:** [What this concept represents in the business]
|
||||
**Why:** [Why this exists, business justification]
|
||||
**Scope:** [Where in the application this applies]
|
||||
|
||||
## Business Context
|
||||
|
||||
### Background
|
||||
|
||||
[Business context and history of this domain concept]
|
||||
|
||||
### Stakeholders
|
||||
|
||||
- **[Role 1]:** [How they interact with this]
|
||||
- **[Role 2]:** [How they interact with this]
|
||||
- **[Role 3]:** [How they interact with this]
|
||||
|
||||
### Business Goals
|
||||
|
||||
1. [Goal 1]
|
||||
2. [Goal 2]
|
||||
3. [Goal 3]
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### [Concept 1]
|
||||
|
||||
**Definition:** [Clear definition]
|
||||
**Examples:** [Real-world examples]
|
||||
**Constraints:** [Business constraints]
|
||||
|
||||
### [Concept 2]
|
||||
|
||||
**Definition:** [Clear definition]
|
||||
**Examples:** [Real-world examples]
|
||||
**Constraints:** [Business constraints]
|
||||
|
||||
## Business Rules
|
||||
|
||||
### Rule 1: [Rule Name]
|
||||
|
||||
**Statement:** [Clear rule statement]
|
||||
|
||||
**Rationale:** [Why this rule exists]
|
||||
|
||||
**Applies to:** [Who/what this affects]
|
||||
|
||||
**Exceptions:** [When this rule doesn't apply]
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Given: [Initial state]
|
||||
When: [Action occurs]
|
||||
Then: [Expected outcome]
|
||||
```
|
||||
|
||||
### Rule 2: [Rule Name]
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## States and Transitions
|
||||
|
||||
### State Machine (if applicable)
|
||||
|
||||
```
|
||||
[Initial State]
|
||||
↓ [Event/Action]
|
||||
[Next State]
|
||||
↓ [Event/Action]
|
||||
[Final State]
|
||||
```
|
||||
|
||||
### State Definitions
|
||||
|
||||
**[State 1]**
|
||||
- **Meaning:** [What this state represents]
|
||||
- **Entry conditions:** [How entity enters this state]
|
||||
- **Exit conditions:** [How entity leaves this state]
|
||||
- **Allowed actions:** [What can happen in this state]
|
||||
|
||||
**[State 2]**
|
||||
[Same structure]
|
||||
|
||||
### Transition Rules
|
||||
|
||||
**[State A] → [State B]**
|
||||
- **Trigger:** [What causes transition]
|
||||
- **Conditions:** [Required conditions]
|
||||
- **Side effects:** [What else happens]
|
||||
- **Validation:** [What must be true]
|
||||
|
||||
## Permissions and Access Control
|
||||
|
||||
### Who Can Do What
|
||||
|
||||
**[Role 1]:**
|
||||
- ✅ Can: [Action 1, Action 2]
|
||||
- ❌ Cannot: [Action 3, Action 4]
|
||||
- ⚠️ Conditional: [Action 5 - under conditions]
|
||||
|
||||
**[Role 2]:**
|
||||
[Same structure]
|
||||
|
||||
### Permission Rules
|
||||
|
||||
**Rule:** [Permission rule statement]
|
||||
**Logic:**
|
||||
```
|
||||
IF [condition]
|
||||
AND [condition]
|
||||
THEN [permission granted/denied]
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Field Validations
|
||||
|
||||
**[Field 1]:**
|
||||
- **Type:** [Data type]
|
||||
- **Required:** [Yes/No]
|
||||
- **Format:** [Pattern or format]
|
||||
- **Range:** [Min/max values]
|
||||
- **Business rule:** [Any business constraint]
|
||||
|
||||
**[Field 2]:**
|
||||
[Same structure]
|
||||
|
||||
### Cross-Field Validations
|
||||
|
||||
**Validation 1:** [Description]
|
||||
```
|
||||
IF [field1] is [value]
|
||||
THEN [field2] must be [constraint]
|
||||
```
|
||||
|
||||
**Validation 2:** [Description]
|
||||
```
|
||||
[Validation logic]
|
||||
```
|
||||
|
||||
## Workflows
|
||||
|
||||
### Workflow 1: [Workflow Name]
|
||||
|
||||
**Trigger:** [What initiates this workflow]
|
||||
|
||||
**Steps:**
|
||||
1. **[Step 1]**
|
||||
- Actor: [Who performs this]
|
||||
- Action: [What happens]
|
||||
- Validation: [What's checked]
|
||||
- Outcome: [Result]
|
||||
|
||||
2. **[Step 2]**
|
||||
[Same structure]
|
||||
|
||||
3. **[Step 3]**
|
||||
[Same structure]
|
||||
|
||||
**Success Criteria:** [What defines success]
|
||||
**Failure Scenarios:** [What can go wrong]
|
||||
|
||||
## Calculations and Algorithms
|
||||
|
||||
### Calculation 1: [Name]
|
||||
|
||||
**Purpose:** [What this calculates]
|
||||
|
||||
**Formula:**
|
||||
```
|
||||
[Mathematical or logical formula]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Given:
|
||||
- input1 = [value]
|
||||
- input2 = [value]
|
||||
|
||||
Calculation:
|
||||
result = [formula applied]
|
||||
|
||||
Output: [result]
|
||||
```
|
||||
|
||||
**Edge Cases:**
|
||||
- [Edge case 1 and handling]
|
||||
- [Edge case 2 and handling]
|
||||
|
||||
## Constraints and Limits
|
||||
|
||||
### Business Constraints
|
||||
|
||||
1. **[Constraint 1]:** [Description and rationale]
|
||||
2. **[Constraint 2]:** [Description and rationale]
|
||||
3. **[Constraint 3]:** [Description and rationale]
|
||||
|
||||
### System Limits
|
||||
|
||||
- **[Limit 1]:** [Value and reason]
|
||||
- **[Limit 2]:** [Value and reason]
|
||||
- **[Limit 3]:** [Value and reason]
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### Edge Case 1: [Scenario]
|
||||
|
||||
**Situation:** [Describe the edge case]
|
||||
**Business Rule:** [How to handle it]
|
||||
**Example:** [Concrete example]
|
||||
|
||||
### Edge Case 2: [Scenario]
|
||||
|
||||
[Same structure]
|
||||
|
||||
## Compliance and Regulations
|
||||
|
||||
### Regulatory Requirements
|
||||
|
||||
**[Regulation 1]:** [How it affects this domain concept]
|
||||
**[Regulation 2]:** [How it affects this domain concept]
|
||||
|
||||
### Audit Requirements
|
||||
|
||||
- **What to log:** [Events/changes to track]
|
||||
- **Retention:** [How long to keep records]
|
||||
- **Who can access:** [Audit log access rules]
|
||||
|
||||
## Reporting and Analytics
|
||||
|
||||
### Key Metrics
|
||||
|
||||
1. **[Metric 1]:** [What it measures and why it matters]
|
||||
2. **[Metric 2]:** [What it measures and why it matters]
|
||||
3. **[Metric 3]:** [What it measures and why it matters]
|
||||
|
||||
### Reporting Requirements
|
||||
|
||||
- **[Report 1]:** [Purpose, frequency, audience]
|
||||
- **[Report 2]:** [Purpose, frequency, audience]
|
||||
|
||||
## Examples and Scenarios
|
||||
|
||||
### Scenario 1: [Happy Path]
|
||||
|
||||
**Description:** [Common successful scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Step with data]
|
||||
3. [Step with outcome]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
### Scenario 2: [Error Case]
|
||||
|
||||
**Description:** [Common error scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Error condition]
|
||||
3. [Error handling per business rules]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
### Scenario 3: [Edge Case]
|
||||
|
||||
**Description:** [Unusual but valid scenario]
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
1. [Step with data]
|
||||
2. [Edge condition]
|
||||
3. [Special handling]
|
||||
```
|
||||
|
||||
**Business Rules Applied:** [Which rules from above]
|
||||
|
||||
## Integration Points
|
||||
|
||||
### System Touchpoints
|
||||
|
||||
**[System 1]:**
|
||||
- **Interaction:** [How they interact]
|
||||
- **Data shared:** [What data flows]
|
||||
- **Trigger:** [What causes interaction]
|
||||
|
||||
**[System 2]:**
|
||||
[Same structure]
|
||||
|
||||
## Glossary
|
||||
|
||||
**[Term 1]:** [Definition in this context]
|
||||
**[Term 2]:** [Definition in this context]
|
||||
**[Term 3]:** [Definition in this context]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Patterns:** [Pattern Doc](../patterns/doc.md) - [Technical implementation]
|
||||
- **Interfaces:** [Interface Doc](../interfaces/doc.md) - [External systems]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/PRD.md) - [Feature requirements]
|
||||
|
||||
## References
|
||||
|
||||
- [Business document or policy]
|
||||
- [Industry standard or regulation]
|
||||
- [Internal decision document]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Reason | Author |
|
||||
|------|--------|--------|--------|
|
||||
| [Date] | Initial documentation | [Why] | [Name/Tool] |
|
||||
| [Date] | Updated [aspect] | [Why] | [Name/Tool] |
|
||||
255
skills/documentation/templates/interface-template.md
Normal file
255
skills/documentation/templates/interface-template.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# [Service Name] Integration
|
||||
|
||||
> **Category:** External Interface
|
||||
> **Service:** [Service Name]
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Deprecated/Planned]
|
||||
|
||||
## Overview
|
||||
|
||||
**Service:** [Full service name]
|
||||
**Provider:** [Company/organization]
|
||||
**Purpose:** [What this integration accomplishes]
|
||||
**Documentation:** [Link to official API docs]
|
||||
|
||||
## Authentication
|
||||
|
||||
### Method
|
||||
|
||||
[OAuth 2.0 / API Key / Basic Auth / JWT / etc.]
|
||||
|
||||
### Credentials Management
|
||||
|
||||
**Location:** [Where credentials are stored]
|
||||
**Environment Variables:**
|
||||
```bash
|
||||
SERVICE_API_KEY=xxx
|
||||
SERVICE_SECRET=xxx
|
||||
SERVICE_ENDPOINT=https://...
|
||||
```
|
||||
|
||||
**Rotation Policy:** [How often credentials change]
|
||||
|
||||
### Authentication Example
|
||||
|
||||
```[language]
|
||||
// Example of authentication setup
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## API Endpoints Used
|
||||
|
||||
### Endpoint 1: [Name]
|
||||
|
||||
**URL:** `[METHOD] /path/to/endpoint`
|
||||
**Purpose:** [What this endpoint does]
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"field1": "value",
|
||||
"field2": "value"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"data": { }
|
||||
}
|
||||
```
|
||||
|
||||
**Error Handling:**
|
||||
- `400`: [How we handle]
|
||||
- `401`: [How we handle]
|
||||
- `500`: [How we handle]
|
||||
|
||||
### Endpoint 2: [Name]
|
||||
|
||||
**URL:** `[METHOD] /path/to/endpoint`
|
||||
**Purpose:** [What this endpoint does]
|
||||
|
||||
[Same structure as above]
|
||||
|
||||
## Webhooks (if applicable)
|
||||
|
||||
### Webhook 1: [Event Name]
|
||||
|
||||
**Event Type:** `[event.type]`
|
||||
**Trigger:** [When this fires]
|
||||
**URL:** `[Your webhook endpoint]`
|
||||
|
||||
**Payload:**
|
||||
```json
|
||||
{
|
||||
"event": "type",
|
||||
"data": { }
|
||||
}
|
||||
```
|
||||
|
||||
**Signature Verification:**
|
||||
```[language]
|
||||
// How to verify webhook authenticity
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
```[language]
|
||||
// How we process this webhook
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
- **Requests per second:** [Limit]
|
||||
- **Requests per day:** [Limit]
|
||||
- **Burst limit:** [Limit]
|
||||
|
||||
**Handling Strategy:** [How we respect limits]
|
||||
```[language]
|
||||
// Rate limiting implementation
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Data Mapping
|
||||
|
||||
### Our Model → Service Model
|
||||
|
||||
| Our Field | Service Field | Transformation |
|
||||
|-----------|---------------|----------------|
|
||||
| `userId` | `external_id` | String conversion |
|
||||
| `email` | `email_address` | Direct mapping |
|
||||
| `amount` | `total_cents` | Multiply by 100 |
|
||||
|
||||
### Service Model → Our Model
|
||||
|
||||
| Service Field | Our Field | Transformation |
|
||||
|---------------|-----------|----------------|
|
||||
| `id` | `externalId` | Direct mapping |
|
||||
| `status` | `state` | Enum mapping |
|
||||
| `created_at` | `createdAt` | ISO 8601 parse |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Error 1: [Name/Code]**
|
||||
- **Cause:** [What triggers this]
|
||||
- **Recovery:** [How we handle it]
|
||||
- **Retry:** [Yes/No, strategy]
|
||||
|
||||
**Error 2: [Name/Code]**
|
||||
- **Cause:** [What triggers this]
|
||||
- **Recovery:** [How we handle it]
|
||||
- **Retry:** [Yes/No, strategy]
|
||||
|
||||
### Retry Strategy
|
||||
|
||||
```[language]
|
||||
// Exponential backoff implementation
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Credentials
|
||||
|
||||
**Sandbox URL:** `https://sandbox.service.com`
|
||||
**Test API Key:** `[Where to get it]`
|
||||
|
||||
### Mock Server
|
||||
|
||||
**Location:** `tests/mocks/[service]-mock.ts`
|
||||
**Usage:**
|
||||
```[language]
|
||||
// How to use mock in tests
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```[language]
|
||||
// Example integration test
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Health Checks
|
||||
|
||||
**Endpoint:** `[Service status endpoint]`
|
||||
**Frequency:** [How often we check]
|
||||
|
||||
### Metrics to Track
|
||||
|
||||
- Request success rate
|
||||
- Response time (p50, p95, p99)
|
||||
- Error rate by type
|
||||
- Rate limit proximity
|
||||
|
||||
### Alerts
|
||||
|
||||
- **Critical:** [Conditions that trigger urgent alerts]
|
||||
- **Warning:** [Conditions that trigger warnings]
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- [Security consideration 1]
|
||||
- [Security consideration 2]
|
||||
- [Security consideration 3]
|
||||
|
||||
## Compliance
|
||||
|
||||
**Data Handling:**
|
||||
- PII fields: [List]
|
||||
- Retention policy: [Duration]
|
||||
- Geographic restrictions: [Any]
|
||||
|
||||
**Regulations:**
|
||||
- GDPR: [Compliance notes]
|
||||
- CCPA: [Compliance notes]
|
||||
- Other: [Relevant regulations]
|
||||
|
||||
## Cost Considerations
|
||||
|
||||
**Pricing Model:** [How service charges]
|
||||
**Cost per request:** [Estimate]
|
||||
**Monthly estimate:** [Based on usage]
|
||||
|
||||
## Migration/Upgrade Path
|
||||
|
||||
**Current Version:** [Version]
|
||||
**Upgrade Available:** [Yes/No, version]
|
||||
**Breaking Changes:** [List if applicable]
|
||||
|
||||
**Migration Steps:**
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Patterns:** [Pattern Doc](../patterns/doc.md) - [How we use this service]
|
||||
- **Domain:** [Domain Doc](../domain/doc.md) - [Business rules related to this]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Implementation details]
|
||||
|
||||
## External Resources
|
||||
|
||||
- [Official API documentation]
|
||||
- [Status page]
|
||||
- [Developer community/forum]
|
||||
- [SDK/library used]
|
||||
|
||||
## Contact
|
||||
|
||||
**Support:** [How to get help]
|
||||
**Account Manager:** [If applicable]
|
||||
**Escalation:** [Critical issue contact]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Author |
|
||||
|------|--------|--------|
|
||||
| [Date] | Initial integration | [Name/Tool] |
|
||||
| [Date] | Updated to v2 API | [Name/Tool] |
|
||||
144
skills/documentation/templates/pattern-template.md
Normal file
144
skills/documentation/templates/pattern-template.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# [Pattern Name]
|
||||
|
||||
> **Category:** Technical Pattern
|
||||
> **Last Updated:** [Date]
|
||||
> **Status:** [Active/Deprecated/Proposed]
|
||||
|
||||
## Purpose
|
||||
|
||||
[Brief description of what this pattern accomplishes and why it exists]
|
||||
|
||||
## Context
|
||||
|
||||
**When to use this pattern:**
|
||||
- [Scenario 1]
|
||||
- [Scenario 2]
|
||||
- [Scenario 3]
|
||||
|
||||
**When NOT to use this pattern:**
|
||||
- [Anti-scenario 1]
|
||||
- [Anti-scenario 2]
|
||||
|
||||
## Implementation
|
||||
|
||||
### Overview
|
||||
|
||||
[High-level description of how the pattern works]
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
[Directory structure or component organization]
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
**[Component 1 Name]**
|
||||
- Purpose: [What it does]
|
||||
- Responsibilities: [What it handles]
|
||||
- Location: [Where to find it]
|
||||
|
||||
**[Component 2 Name]**
|
||||
- Purpose: [What it does]
|
||||
- Responsibilities: [What it handles]
|
||||
- Location: [Where to find it]
|
||||
|
||||
### Code Example
|
||||
|
||||
```[language]
|
||||
// Example implementation showing the pattern in action
|
||||
[Code snippet]
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: [Scenario Name]
|
||||
|
||||
**Situation:** [Describe the use case]
|
||||
|
||||
**Implementation:**
|
||||
```[language]
|
||||
[Code showing how pattern is applied]
|
||||
```
|
||||
|
||||
**Result:** [What this achieves]
|
||||
|
||||
### Example 2: [Scenario Name]
|
||||
|
||||
**Situation:** [Describe the use case]
|
||||
|
||||
**Implementation:**
|
||||
```[language]
|
||||
[Code showing how pattern is applied]
|
||||
```
|
||||
|
||||
**Result:** [What this achieves]
|
||||
|
||||
## Edge Cases and Gotchas
|
||||
|
||||
### Edge Case 1: [Case Name]
|
||||
|
||||
**Problem:** [What can go wrong]
|
||||
**Solution:** [How to handle it]
|
||||
|
||||
### Edge Case 2: [Case Name]
|
||||
|
||||
**Problem:** [What can go wrong]
|
||||
**Solution:** [How to handle it]
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **[Practice 1]:** [Description]
|
||||
2. **[Practice 2]:** [Description]
|
||||
3. **[Practice 3]:** [Description]
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
❌ **Don't:** [What to avoid]
|
||||
**Why:** [Reason]
|
||||
**Instead:** [Better approach]
|
||||
|
||||
❌ **Don't:** [What to avoid]
|
||||
**Why:** [Reason]
|
||||
**Instead:** [Better approach]
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**How to test code using this pattern:**
|
||||
- [Testing approach 1]
|
||||
- [Testing approach 2]
|
||||
- [Testing approach 3]
|
||||
|
||||
**Example test:**
|
||||
```[language]
|
||||
[Test code example]
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **[Aspect 1]:** [Performance implication]
|
||||
- **[Aspect 2]:** [Performance implication]
|
||||
- **[Aspect 3]:** [Performance implication]
|
||||
|
||||
## Related Patterns
|
||||
|
||||
- [Pattern Name](./pattern-file.md) - [Relationship description]
|
||||
- [Pattern Name](./pattern-file.md) - [Relationship description]
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Domain:** [Domain Doc](../domain/doc.md) - [Relevance]
|
||||
- **Interfaces:** [Interface Doc](../interfaces/doc.md) - [Relevance]
|
||||
- **Specifications:** [Spec](../specs/NNN-name/SDD.md) - [Relevance]
|
||||
|
||||
## References
|
||||
|
||||
- [External resource 1]
|
||||
- [External resource 2]
|
||||
- [Internal decision doc or RFC]
|
||||
|
||||
## Version History
|
||||
|
||||
| Date | Change | Author |
|
||||
|------|--------|--------|
|
||||
| [Date] | Initial documentation | [Name/Tool] |
|
||||
Reference in New Issue
Block a user