commit 995d97df60b2e9aa2ce166b4548e237931162e8d Author: Zhongwei Li Date: Sat Nov 29 18:28:57 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..b706740 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "agent-orchestration", + "description": "Multi-agent orchestration with context management, workflow composition, and agent coordination. Enables complex multi-step tasks through systematic agent delegation, context handoff, and workflow automation.", + "version": "1.0.0", + "author": { + "name": "Grey Haven Studio", + "url": "https://github.com/greyhaven-ai/claude-code-config" + }, + "skills": [ + "./skills/context-management" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..2b81c79 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# agent-orchestration + +Multi-agent orchestration with context management, workflow composition, and agent coordination. Enables complex multi-step tasks through systematic agent delegation, context handoff, and workflow automation. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..e9461a5 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,73 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:greyhaven-ai/claude-code-config:grey-haven-plugins/agent-orchestration", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "449cf1b9c7b91308ec3a4182a4c3a6b94c0d5a44", + "treeHash": "f1eadde37c331fe3b8aa5cfe78ca1611fed3b55e62dd892c78bde760d518a399", + "generatedAt": "2025-11-28T10:17:05.427291Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "agent-orchestration", + "description": "Multi-agent orchestration with context management, workflow composition, and agent coordination. Enables complex multi-step tasks through systematic agent delegation, context handoff, and workflow automation.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "23a161be3f328da22b2fec98ba0a2e00aeea94f42c0ef791660bd97ec18c7164" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "2b723cca140c1e809af234b59f303bc6215d120c6c16e2901d8187a76406da69" + }, + { + "path": "skills/context-management/SKILL.md", + "sha256": "3e11f56dfce7728eb46ac5d150c3c10af3e99b538bed1f45ec110bb359f7e946" + }, + { + "path": "skills/context-management/checklists/context-verification-checklist.md", + "sha256": "90cc8ec97684e2f8f3105c83eaec817311bdfce9e078bcee97f01d9b36e6375f" + }, + { + "path": "skills/context-management/examples/feature-development-handoff.md", + "sha256": "6891477e4cd5ce5d79dd90a3cd5cdaf8a869b13041139437685509c6c3265eab" + }, + { + "path": "skills/context-management/examples/INDEX.md", + "sha256": "52d09ee02431ce86082602fe131db5e5db9977df06f9eed6808be322ea90e993" + }, + { + "path": "skills/context-management/examples/parallel-workflow-example.md", + "sha256": "2a4747ad2cfae1810ea4569efc98328620b5fc6884b193ed25b8f34e80b336f9" + }, + { + "path": "skills/context-management/templates/context-schema-template.json", + "sha256": "493d0c0dbf4e7bd33d2920ed9a3e9fafcc7d2d6d868f531271aaa6aeccd45d3c" + }, + { + "path": "skills/context-management/reference/workflow-best-practices.md", + "sha256": "3e88d7842dc968a05375f36d2f2a9953fe3f16213496162c9e3ef5c35f7a1629" + }, + { + "path": "skills/context-management/reference/INDEX.md", + "sha256": "70febe5b509ded70cba1b261a8cd0cbb0b633ea4ba8bf68bf7f2efe4f558a46d" + } + ], + "dirSha256": "f1eadde37c331fe3b8aa5cfe78ca1611fed3b55e62dd892c78bde760d518a399" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/context-management/SKILL.md b/skills/context-management/SKILL.md new file mode 100644 index 0000000..8fdbb29 --- /dev/null +++ b/skills/context-management/SKILL.md @@ -0,0 +1,85 @@ +# Context Management Skill + +Multi-agent workflow orchestration with state persistence, handoff patterns, and resumable workflows. + +## Description + +This skill enables sophisticated multi-agent workflows through context save/restore operations, supporting sequential handoffs, parallel execution, conditional routing, and long-running resumable workflows. + +## What's Included + +### Examples (`examples/`) +- **Sequential handoff** - Linear 4-phase workflow (Design → Implement → Test → Deploy) +- **Parallel execution** - Full-stack feature with frontend + backend + tests (2.25x speedup) +- **Conditional routing** - Dynamic agent selection based on results +- **Resumable workflows** - Checkpoint-based long-running tasks + +### Reference Guides (`reference/`) +- **Complete reference** - Save/restore operations, workflow patterns, performance optimization +- **Troubleshooting guide** - 6 issue categories with solutions (save failures, restore failures, performance, corruption) +- **Best practices** - Context design, handoff patterns, error handling, security + +### Templates (`templates/`) +- **JSON Schema** - Context structure validation with required/optional fields +- **Context templates** - Ready-to-use structures for different workflow types + +### Checklists (`checklists/`) +- **100-point verification** - Comprehensive validation across 10 categories with weighted scoring + +## Workflow Patterns + +1. **Sequential Handoff** - Agent A → Context Save → Agent B → Context Save → Agent C +2. **Parallel Execution** - Parent spawns 3 agents → Merge results → Integration +3. **Conditional Routing** - Analyze → Route based on conditions → Targeted agent +4. **Resumable Long-Running** - Checkpoints enable resume after interruption + +## Performance Metrics + +- **Context Size**: Target <100KB for 80% of workflows +- **Serialization**: <200ms (P99) +- **Restore**: <500ms (P99) +- **Speedup**: 2-3x faster with parallel execution + +## Use This Skill When + +- Building multi-agent workflows +- Need state persistence across sessions +- Coordinating multiple agents on complex tasks +- Implementing resumable long-running processes +- Optimizing workflow execution time + +## Related Agents + +- `context-manager` - Automated context save/restore with validation +- `tdd-orchestrator` - Multi-agent TDD workflows +- `incident-responder` - Multi-phase incident response + +## Quick Start + +```bash +# View workflow examples +cat examples/feature-development-handoff.md +cat examples/parallel-workflow-example.md + +# Check reference guides +cat reference/INDEX.md +cat reference/workflow-best-practices.md + +# Use context schema +cat templates/context-schema-template.json + +# Validate context +cat checklists/context-verification-checklist.md +``` + +## Security + +- ✅ Never save secrets in context (use secret references) +- ✅ Implement access control for context files +- ✅ Sanitize before saving (remove API keys, passwords) +- ✅ Use relative file paths (not absolute) + +--- + +**Skill Version**: 1.0 +**Last Updated**: 2025-01-15 diff --git a/skills/context-management/checklists/context-verification-checklist.md b/skills/context-management/checklists/context-verification-checklist.md new file mode 100644 index 0000000..43af68a --- /dev/null +++ b/skills/context-management/checklists/context-verification-checklist.md @@ -0,0 +1,396 @@ +# Context Verification Checklist + +Comprehensive checklist for validating context save/restore operations. + +**Workflow**: _______________ +**Date**: _______________ +**Verifier**: _______________ + +--- + +## Pre-Save Validation + +### Required Fields Present +- [ ] `version` - Schema version number (e.g., "1.0") +- [ ] `workflow_id` - Unique identifier +- [ ] `timestamp` - ISO 8601 format +- [ ] `current_agent` - Agent saving context +- [ ] `phase` - Current workflow phase + +**Score**: ___/5 required fields + +### Essential Content +- [ ] `files_modified` - All changed files listed +- [ ] `decisions` - Key decisions documented +- [ ] `pending_actions` - Next steps clear +- [ ] `context_summary` - Human-readable summary (≤500 chars) + +**Score**: ___/4 essential fields + +### Data Quality +- [ ] No sensitive data (API keys, passwords) +- [ ] File paths are relative (not absolute) +- [ ] Timestamp is current (within last hour) +- [ ] Workflow ID follows naming convention +- [ ] All JSON is valid and parseable + +**Score**: ___/5 quality checks + +--- + +## Context Size Optimization + +### Size Metrics +- **Target**: < 100KB for 80% of workflows +- **Actual Size**: _____ KB + +- [ ] Size is reasonable for workflow complexity +- [ ] No redundant data included +- [ ] Large data compressed or externalized +- [ ] Conversation history pruned if > 50 messages + +### Compression Opportunities +- [ ] Remove completed `pending_actions` +- [ ] Prune old `conversation_history` entries +- [ ] Externalize large file contents +- [ ] Compress checkpoint snapshots + +**Optimization Score**: ___/8 + +--- + +## Serialization Validation + +### JSON Validation +- [ ] Valid JSON syntax (no trailing commas) +- [ ] All strings properly escaped +- [ ] No circular references +- [ ] Dates in ISO 8601 format +- [ ] Schema validation passes + +### Schema Compliance +- [ ] Matches context-schema-template.json +- [ ] All required fields present +- [ ] Field types correct (string, array, object) +- [ ] Enum values valid +- [ ] No extra unknown fields (or documented as custom) + +**Serialization Score**: ___/10 + +--- + +## Handoff Readiness + +### Next Agent Preparation +- [ ] `next_agent` specified (or null if complete) +- [ ] `pending_actions` are clear and actionable +- [ ] Required files are accessible +- [ ] Dependencies are documented +- [ ] Constraints are explicit + +### Context Clarity +- [ ] `context_summary` accurately describes state +- [ ] `decisions` explain rationale +- [ ] No ambiguous pending actions +- [ ] Next steps prioritized +- [ ] Exit criteria defined + +**Handoff Score**: ___/10 + +--- + +## Restore Validation + +### Pre-Restore Checks +- [ ] Context file exists and is readable +- [ ] JSON is valid and parseable +- [ ] Version is compatible with current schema +- [ ] Workflow ID matches expected pattern +- [ ] Timestamp is reasonable (not too old) + +### Context Loading +- [ ] All required fields successfully loaded +- [ ] No parsing errors or exceptions +- [ ] Type conversion successful +- [ ] No data loss during deserialization +- [ ] Context object fully initialized + +### State Reconstruction +- [ ] `files_modified` paths resolve correctly +- [ ] Referenced files still exist +- [ ] Dependencies are satisfied +- [ ] Agent can resume from this state +- [ ] No missing critical information + +**Restore Score**: ___/15 + +--- + +## Workflow Continuity + +### State Consistency +- [ ] Previous agent's output available +- [ ] Current phase matches workflow progression +- [ ] No gaps in decision chain +- [ ] File modifications trackable +- [ ] Error log is complete + +### Resume Capability +- [ ] Agent can determine next action from context +- [ ] All tools/resources available +- [ ] No manual intervention needed +- [ ] Progress is measurable +- [ ] Completion criteria clear + +**Continuity Score**: ___/10 + +--- + +## Error Handling + +### Error Resilience +- [ ] Handles missing optional fields gracefully +- [ ] Validates required fields before proceeding +- [ ] Provides clear error messages +- [ ] Suggests fixes for common issues +- [ ] Has rollback mechanism + +### Error Logging +- [ ] `error_log` array present (if errors occurred) +- [ ] Errors include timestamp and agent +- [ ] Resolution status tracked +- [ ] Stack traces captured (if applicable) +- [ ] Impact assessment documented + +**Error Handling Score**: ___/10 + +--- + +## Security & Privacy + +### Sensitive Data +- [ ] No API keys in context +- [ ] No passwords or tokens +- [ ] No personal identifiable information (PII) +- [ ] No internal URLs or IPs (if sensitive) +- [ ] Secrets referenced by ID, not value + +### Access Control +- [ ] Context stored in secure location +- [ ] File permissions appropriate +- [ ] Encrypted if contains sensitive references +- [ ] Access logged for audit trail +- [ ] Retention policy defined + +**Security Score**: ___/10 + +--- + +## Performance Metrics + +### Save Performance +- **Target**: < 200ms for save operation +- **Actual**: _____ ms + +- [ ] Save time within target +- [ ] No blocking operations +- [ ] Async save if large context +- [ ] Compression applied if needed + +### Restore Performance +- **Target**: < 500ms for restore operation +- **Actual**: _____ ms + +- [ ] Restore time within target +- [ ] Lazy loading for large history +- [ ] Cached if frequently accessed +- [ ] Progress indicator for slow loads + +**Performance Score**: ___/8 + +--- + +## Version Compatibility + +### Schema Version +- [ ] Current version documented +- [ ] Migration path from older versions +- [ ] Backward compatibility maintained +- [ ] Breaking changes documented +- [ ] Version upgrade tested + +### Agent Compatibility +- [ ] Context works with current agent versions +- [ ] Deprecated fields handled +- [ ] New fields have defaults +- [ ] Agent can skip unknown fields +- [ ] Compatibility matrix documented + +**Compatibility Score**: ___/10 + +--- + +## Total Score Calculation + +| Category | Score | Weight | Weighted | +|----------|-------|--------|----------| +| Pre-Save Validation | ___/14 | 10% | ___ | +| Size Optimization | ___/8 | 5% | ___ | +| Serialization | ___/10 | 15% | ___ | +| Handoff Readiness | ___/10 | 15% | ___ | +| Restore Validation | ___/15 | 20% | ___ | +| Continuity | ___/10 | 15% | ___ | +| Error Handling | ___/10 | 10% | ___ | +| Security | ___/10 | 5% | ___ | +| Performance | ___/8 | 3% | ___ | +| Compatibility | ___/10 | 2% | ___ | + +**Total Score**: ___/100 + +--- + +## Quality Gates + +### Must Pass (Blocking) +- [ ] Total score ≥ 85 +- [ ] No critical security issues +- [ ] All required fields present +- [ ] Restore test successful +- [ ] Next agent can load context + +### Should Pass (Important) +- [ ] Size < 100KB +- [ ] Performance within targets +- [ ] Schema validation passes +- [ ] No errors in log + +### Nice to Have +- [ ] Total score ≥ 95 +- [ ] Full conversation history +- [ ] Comprehensive checkpoints +- [ ] Automated testing in place + +**Gates Passed**: ___/13 + +--- + +## Checklist Results + +**Context Status**: [ ] ✅ Valid / [ ] ⚠️ Needs Fixes / [ ] ❌ Invalid + +**Critical Issues**: ___ +**Important Issues**: ___ +**Minor Issues**: ___ + +**Recommendation**: +[ ] Ready for handoff +[ ] Fix issues before handoff +[ ] Recreate context from scratch + +--- + +## Common Issues & Fixes + +### Issue: Context Too Large +**Symptom**: Size > 100KB +**Fix**: +- [ ] Remove completed actions +- [ ] Prune conversation history +- [ ] Externalize file contents +- [ ] Compress checkpoints + +### Issue: Missing Required Fields +**Symptom**: Restore fails +**Fix**: +- [ ] Add all required fields from template +- [ ] Validate against schema +- [ ] Use context builder helper + +### Issue: Sensitive Data Detected +**Symptom**: Security scan finds secrets +**Fix**: +- [ ] Remove API keys +- [ ] Redact passwords +- [ ] Reference secrets by ID +- [ ] Apply encryption if needed + +### Issue: Stale Context +**Symptom**: Timestamp > 7 days old +**Fix**: +- [ ] Verify files still exist +- [ ] Validate dependencies current +- [ ] Update timestamp if still valid +- [ ] Archive if no longer needed + +### Issue: Version Incompatibility +**Symptom**: Old version can't load +**Fix**: +- [ ] Run migration script +- [ ] Update to current schema +- [ ] Test with both versions +- [ ] Document breaking changes + +--- + +## Action Items + +### Immediate Fixes (if issues found) +1. [ ] Issue: _______________ + - Priority: Critical/High/Medium/Low + - Fix: _______________ + - Owner: _______________ + +2. [ ] Issue: _______________ + - Priority: Critical/High/Medium/Low + - Fix: _______________ + - Owner: _______________ + +### Process Improvements +- [ ] Update context template +- [ ] Add validation scripts +- [ ] Improve documentation +- [ ] Create migration tools + +--- + +## Sign-off + +**Verified By**: ___________ +**Date**: ___________ +**Status**: [ ] Approved / [ ] Conditionally Approved / [ ] Rejected + +**Notes**: +_____________________________________________ +_____________________________________________ + +--- + +## Quick Reference + +**Minimum Valid Context:** +```json +{ + "version": "1.0", + "workflow_id": "workflow-name", + "timestamp": "2025-01-15T10:00:00Z", + "current_agent": "agent-name", + "phase": "phase-name" +} +``` + +**Typical Size Ranges:** +- Small: 5-20 KB +- Medium: 20-100 KB +- Large: 100-500 KB +- Very Large: 500KB+ (needs optimization) + +**Critical Fields:** +- ✅ version, workflow_id, timestamp +- ✅ current_agent, phase +- ⚠️ next_agent, pending_actions +- ℹ️ context_summary + +--- + +**Checklist Version**: 1.0 +**Last Updated**: 2025-01-15 diff --git a/skills/context-management/examples/INDEX.md b/skills/context-management/examples/INDEX.md new file mode 100644 index 0000000..51158bc --- /dev/null +++ b/skills/context-management/examples/INDEX.md @@ -0,0 +1,199 @@ +# Context Manager Examples + +Real-world examples of multi-agent workflow context management and state persistence. + +## Quick Navigation + +| Example | Workflow Type | Agents Involved | Context Size | Complexity | +|---------|---------------|-----------------|--------------|------------| +| [Feature Development Handoff](feature-development-handoff.md) | Sequential | 4 agents | Medium | Moderate | +| [Incident Response Workflow](incident-response-workflow.md) | Parallel + Sequential | 6 agents | Large | High | +| [Code Review Pipeline](code-review-pipeline.md) | Conditional | 3 agents | Small | Low | +| [Multi-Session Refactoring](multi-session-refactoring.md) | Resumable | 5 agents | Large | Very High | + +## Context Management Patterns + +### Pattern 1: Sequential Handoff +**Use Case:** Linear workflow where each agent completes before next begins + +**Example**: Design → Implement → Test → Deploy +``` +Agent A (Designer) → Context Save → Agent B (Developer) + → Context Save → Agent C (Tester) + → Context Save → Agent D (DevOps) +``` + +**Context Contains:** +- Decisions made by previous agents +- Modified files +- Pending actions for next agent +- Constraints and requirements + +### Pattern 2: Parallel Execution +**Use Case:** Multiple agents work concurrently on independent tasks + +**Example**: Frontend + Backend + Database development in parallel +``` +Context Fork → Agent A (Frontend) → Context Merge + → Agent B (Backend) → + → Agent C (Database) → +``` + +**Challenges:** +- Conflict resolution when merging +- Dependency coordination +- Partial failure handling + +### Pattern 3: Conditional Routing +**Use Case:** Next agent determined by previous agent's outcome + +**Example**: Code review → (Pass: Deploy) | (Fail: Fix) → Re-review +``` +Agent A (Reviewer) → Decision Point → (if pass) Agent B (Deploy) + → (if fail) Agent C (Fix) → back to Agent A +``` + +**Context Needs:** +- Decision criteria +- Route history +- Loop detection + +### Pattern 4: Long-Running Resumable +**Use Case:** Workflow spans multiple sessions/days + +**Example**: Large codebase refactoring over 3 days +``` +Day 1: Agent A → Save checkpoint +Day 2: Restore → Agent A continues → Save checkpoint +Day 3: Restore → Agent B (testing) → Complete +``` + +**Critical Features:** +- Robust serialization +- Version compatibility +- Progress tracking +- Partial completion handling + +## Context Size Benchmarks + +| Workflow Type | Avg Context Size | Serialization Time | Restore Time | +|---------------|------------------|-------------------|--------------| +| Simple (1-2 agents) | 5-10 KB | < 10ms | < 10ms | +| Moderate (3-5 agents) | 20-50 KB | 20-50ms | 20-50ms | +| Complex (6+ agents) | 100-200 KB | 100-200ms | 100-200ms | +| Large (multi-session) | 500KB-2MB | 500ms-1s | 500ms-1s | + +**Optimization Target:** < 100KB for 80% of workflows + +## State Management Strategies + +### Minimal State +**Principle:** Only save essential context + +**Includes:** +- File paths (not file contents) +- Decision summaries (not full reasoning) +- Pending actions (not completed tasks) + +**Benefits:** +- Faster serialization +- Lower storage +- Easier debugging + +### Comprehensive State +**Principle:** Save everything for full resumption + +**Includes:** +- Complete conversation history +- All file modifications +- Full reasoning chains +- Error logs + +**Benefits:** +- Perfect restoration +- Complete audit trail +- Advanced debugging + +### Hybrid Approach +**Principle:** Essential + compression + +**Strategy:** +- Essential context in JSON +- Full history compressed separately +- Load essential first, decompress on demand + +## Common Pitfalls + +### Pitfall 1: Context Bloat +**Symptom:** Context grows unbounded +**Solution:** Pruning strategy - remove completed tasks, compress history + +### Pitfall 2: Version Incompatibility +**Symptom:** Can't restore old contexts after updates +**Solution:** Context versioning with migration scripts + +### Pitfall 3: Missing Dependencies +**Symptom:** Context refers to external state that changed +**Solution:** Capture or validate external dependencies + +### Pitfall 4: Concurrent Modification +**Symptom:** Two agents modify same context simultaneously +**Solution:** Locking or optimistic concurrency + +### Pitfall 5: Sensitive Data in Context +**Symptom:** API keys, passwords in saved context +**Solution:** Redaction and encryption + +## Success Metrics + +**Context Quality Indicators:** +- Restoration success rate: Target > 99% +- Context size vs workflow complexity: Linear relationship +- Time to restore: Target < 1 second +- Agent resume success: Target > 95% + +**Workflow Efficiency:** +- Reduced re-work: 70% reduction +- Faster handoffs: < 30 seconds +- Session continuity: Seamless multi-day workflows + +## Quick Reference: Context Schema + +**Minimal Required Fields:** +```json +{ + "version": "1.0", + "workflow_id": "unique-id", + "timestamp": "ISO-8601", + "current_agent": "agent-name", + "next_agent": "agent-name", + "phase": "current-phase", + "files_modified": ["paths"], + "decisions": ["summaries"], + "pending_actions": ["tasks"] +} +``` + +**Extended Optional Fields:** +```json +{ + "conversation_history": [...], + "error_log": [...], + "checkpoints": [...], + "metadata": {...} +} +``` + +## Navigation Tips + +- **New to context management?** Start with [Code Review Pipeline](code-review-pipeline.md) +- **Complex workflows?** See [Feature Development Handoff](feature-development-handoff.md) +- **Multi-session work?** Check [Multi-Session Refactoring](multi-session-refactoring.md) +- **Parallel agents?** Review [Incident Response Workflow](incident-response-workflow.md) + +--- + +**Total Examples**: 4 comprehensive workflow scenarios +**Patterns Covered**: Sequential, Parallel, Conditional, Resumable +**Context Sizes**: 5KB to 2MB +**Success Rate**: 99%+ restoration across all patterns diff --git a/skills/context-management/examples/feature-development-handoff.md b/skills/context-management/examples/feature-development-handoff.md new file mode 100644 index 0000000..9d2be42 --- /dev/null +++ b/skills/context-management/examples/feature-development-handoff.md @@ -0,0 +1,501 @@ +# Feature Development Handoff Example + +Complete multi-agent workflow for feature development with context handoffs. + +**Workflow**: Design → Implement → Test → Deploy +**Duration**: 4-6 hours +**Agents**: 4 (backend-architect, tdd-typescript, test-generator, devops-troubleshooter) +**Context Handoffs**: 3 + +--- + +## Workflow Overview + +``` +User Request → Backend Architect → TDD TypeScript → Test Generator → DevOps Deploy + ↓ save ↓ save ↓ save ↓ + context-1 context-2 context-3 ✅ Complete +``` + +--- + +## Phase 1: Architecture Design + +**Agent**: `backend-architect` +**Goal**: Design API endpoints and data model + +**User Input**: +"Add user preferences feature: users can save theme (light/dark), language (en/es/fr), and notification settings (email, push)." + +**Agent Work**: +1. Analyzes requirements +2. Designs database schema +3. Plans API endpoints +4. Creates OpenAPI spec + +**Output**: +```typescript +// Designed schema +interface UserPreferences { + user_id: string; + theme: 'light' | 'dark'; + language: 'en' | 'es' | 'fr'; + notifications: { + email: boolean; + push: boolean; + }; + updated_at: Date; +} + +// Planned endpoints +GET /api/v1/users/:id/preferences +PUT /api/v1/users/:id/preferences +PATCH /api/v1/users/:id/preferences +``` + +**Decisions Made**: +- Use JSONB column in PostgreSQL for preferences (flexibility) +- PUT for full replace, PATCH for partial update +- Include updated_at for conflict resolution +- Rate limit: 10 requests/minute per user + +**Context Save** (`context-001-design.json`): +```json +{ + "version": "1.0", + "workflow_id": "feature-user-prefs-20250115", + "timestamp": "2025-01-15T10:30:00Z", + "current_agent": "backend-architect", + "next_agent": "tdd-typescript", + "phase": "design-complete", + + "files_modified": [ + "docs/api/user-preferences.md", + "docs/architecture/decisions/adr-012-user-prefs-storage.md" + ], + + "decisions": [ + "Use JSONB for flexibility in preferences structure", + "Implement both PUT (full) and PATCH (partial) updates", + "Rate limit to 10 req/min per user to prevent abuse", + "Include updated_at for optimistic locking" + ], + + "data_model": { + "table": "user_preferences", + "columns": { + "id": "UUID PRIMARY KEY", + "user_id": "UUID REFERENCES users(id)", + "preferences": "JSONB NOT NULL", + "created_at": "TIMESTAMP DEFAULT NOW()", + "updated_at": "TIMESTAMP DEFAULT NOW()" + }, + "indexes": [ + "user_id (unique)", + "updated_at" + ] + }, + + "api_spec": { + "endpoints": [ + { + "method": "GET", + "path": "/api/v1/users/:id/preferences", + "auth_required": true, + "rate_limit": "10/minute", + "response": "UserPreferences" + }, + { + "method": "PUT", + "path": "/api/v1/users/:id/preferences", + "auth_required": true, + "body": "UserPreferencesUpdate", + "response": "UserPreferences" + }, + { + "method": "PATCH", + "path": "/api/v1/users/:id/preferences", + "auth_required": true, + "body": "Partial", + "response": "UserPreferences" + } + ] + }, + + "pending_actions": [ + "Implement API endpoints with TDD approach", + "Create database migration", + "Add validation for preference values", + "Implement rate limiting middleware" + ], + + "constraints": [ + "Must maintain backward compatibility", + "Performance: GET should be < 50ms", + "Must handle concurrent updates (optimistic locking)" + ] +} +``` + +**Handoff Message**: +"Design complete. Data model uses JSONB for flexibility. Three endpoints designed (GET/PUT/PATCH). Ready for TDD implementation. Key constraints: < 50ms response, handle concurrency, rate limiting." + +--- + +## Phase 2: TDD Implementation + +**Agent**: `tdd-typescript-implementer` +**Goal**: Implement API endpoints following TDD + +**Context Restore**: +```typescript +// Agent loads context-001-design.json +const context = await loadContext('feature-user-prefs-20250115'); + +console.log('Previous agent:', context.current_agent); +console.log('Decisions:', context.decisions); +console.log('Next steps:', context.pending_actions); +console.log('Constraints:', context.constraints); +``` + +**Agent Work**: +Following RED-GREEN-REFACTOR cycle: + +**Cycle 1**: GET /preferences endpoint +```typescript +// RED: Write failing test +describe('GET /api/v1/users/:id/preferences', () => { + it('returns user preferences', async () => { + const response = await request(app) + .get('/api/v1/users/user-123/preferences') + .set('Authorization', 'Bearer token'); + + expect(response.status).toBe(200); + expect(response.body).toMatchObject({ + user_id: 'user-123', + theme: 'light', + language: 'en' + }); + }); +}); +// ❌ Test fails - endpoint doesn't exist + +// GREEN: Minimal implementation +router.get('/users/:id/preferences', authenticate, async (req, res) => { + const prefs = await db.getUserPreferences(req.params.id); + res.json(prefs); +}); +// ✅ Test passes + +// REFACTOR: Add caching, validation +router.get('/users/:id/preferences', + authenticate, + validateUserId, + cacheMiddleware({ ttl: 300 }), + async (req, res) => { + const prefs = await db.getUserPreferences(req.params.id); + res.json(prefs); + } +); +// ✅ All tests still pass +``` + +**Cycle 2-4**: PUT and PATCH endpoints (similar process) + +**Context Save** (`context-002-implementation.json`): +```json +{ + "version": "1.0", + "workflow_id": "feature-user-prefs-20250115", + "timestamp": "2025-01-15T14:45:00Z", + "current_agent": "tdd-typescript", + "next_agent": "test-generator", + "phase": "implementation-complete", + + "files_modified": [ + "src/api/routes/user-preferences.ts", + "src/api/middleware/rate-limit.ts", + "src/db/repositories/preferences.ts", + "src/types/user-preferences.ts", + "migrations/2025-01-15-user-preferences.sql" + ], + + "test_results": { + "total": 18, + "passing": 18, + "failing": 0, + "coverage": { + "line": 96, + "branch": 94, + "function": 100 + } + }, + + "decisions": [ + "Added caching (5min TTL) for GET endpoint", + "Implemented optimistic locking with updated_at", + "Used Zod for runtime validation", + "Rate limiting uses Redis for distributed systems" + ], + + "pending_actions": [ + "Generate comprehensive integration tests", + "Add E2E tests for full user flows", + "Test edge cases (concurrent updates, invalid data)", + "Performance testing under load" + ], + + "metrics": { + "implementation_time": "3.5 hours", + "test_count": 18, + "code_loc": 420, + "test_loc": 580 + } +} +``` + +**Handoff Message**: +"Implementation complete with 18 passing tests, 96% coverage. All three endpoints functional. Caching, validation, rate limiting implemented. Ready for comprehensive testing." + +--- + +## Phase 3: Test Generation + +**Agent**: `test-generator` +**Goal**: Create comprehensive test suite + +**Context Restore**: +```typescript +const context = await loadContext('feature-user-prefs-20250115'); +const implementedFiles = context.files_modified; +const coverageGaps = identifyGaps(context.test_results.coverage); +``` + +**Agent Work**: +1. Analyzes implementation +2. Identifies uncovered branches +3. Generates integration tests +4. Creates E2E test scenarios + +**Generated Tests**: + +**Integration Test**: +```typescript +describe('User Preferences Integration', () => { + it('handles concurrent updates correctly', async () => { + const userId = 'user-123'; + + // Simulate two clients updating simultaneously + const [update1, update2] = await Promise.allSettled([ + api.updatePreferences(userId, { theme: 'dark' }), + api.updatePreferences(userId, { language: 'es' }) + ]); + + // One should succeed, one should get conflict (409) + const statuses = [update1.status, update2.status].sort(); + expect(statuses).toEqual([200, 409]); + + // Final state should be consistent + const final = await api.getPreferences(userId); + expect(final.theme === 'dark' || final.language === 'es').toBe(true); + }); + + it('respects rate limits', async () => { + const requests = Array(15).fill(null).map(() => + api.updatePreferences('user-123', { theme: 'dark' }) + ); + + const results = await Promise.allSettled(requests); + const rateLimited = results.filter(r => r.status === 429); + + expect(rateLimited.length).toBeGreaterThan(0); // Some rejected + }); +}); +``` + +**Context Save** (`context-003-testing.json`): +```json +{ + "version": "1.0", + "workflow_id": "feature-user-prefs-20250115", + "timestamp": "2025-01-15T16:30:00Z", + "current_agent": "test-generator", + "next_agent": "devops-troubleshooter", + "phase": "testing-complete", + + "files_modified": [ + "tests/integration/user-preferences.test.ts", + "tests/e2e/preferences-flow.test.ts", + "tests/performance/preferences-load.test.ts" + ], + + "test_results": { + "unit": { "total": 18, "passing": 18 }, + "integration": { "total": 12, "passing": 12 }, + "e2e": { "total": 5, "passing": 5 }, + "performance": { + "avg_response_time": "42ms", + "p95_response_time": "68ms", + "p99_response_time": "95ms", + "throughput": "450 req/sec" + } + }, + + "final_coverage": { + "line": 98, + "branch": 97, + "function": 100 + }, + + "pending_actions": [ + "Deploy to staging environment", + "Run smoke tests in staging", + "Monitor error rates and performance", + "Deploy to production with canary" + ], + + "quality_gates_passed": { + "coverage": true, + "performance": true, + "security": true, + "accessibility": true + } +} +``` + +**Handoff Message**: +"Testing complete. 35 tests total, all passing. 98% coverage. Performance within targets (< 50ms avg). Ready for deployment." + +--- + +## Phase 4: Deployment + +**Agent**: `devops-troubleshooter` +**Goal**: Deploy to staging and production + +**Context Restore**: +```typescript +const context = await loadContext('feature-user-prefs-20250115'); +const performanceMetrics = context.test_results.performance; +const qualityGates = context.quality_gates_passed; + +// Verify all gates passed +if (!Object.values(qualityGates).every(passed => passed)) { + throw new Error('Quality gates not met - cannot deploy'); +} +``` + +**Agent Work**: +1. Creates deployment pipeline +2. Deploys to staging +3. Runs smoke tests +4. Deploys to production (canary) +5. Monitors rollout + +**Deployment Steps**: +```yaml +# .github/workflows/deploy-user-prefs.yml +name: Deploy User Preferences Feature + +on: + workflow_dispatch: + inputs: + environment: + description: 'Environment' + required: true + type: choice + options: + - staging + - production + +jobs: + deploy: + steps: + - name: Run tests + run: npm test + + - name: Check coverage + run: npm run coverage -- --threshold=95 + + - name: Deploy to staging + if: inputs.environment == 'staging' + run: | + npx wrangler deploy --env staging + npm run smoke-test:staging + + - name: Deploy to production (canary) + if: inputs.environment == 'production' + run: | + npx wrangler deploy --env production --percentage 10 + npm run monitor:canary + + - name: Full rollout + if: inputs.environment == 'production' + run: npx wrangler deploy --env production --percentage 100 +``` + +**Final Context** (`context-004-complete.json`): +```json +{ + "version": "1.0", + "workflow_id": "feature-user-prefs-20250115", + "timestamp": "2025-01-15T18:00:00Z", + "current_agent": "devops-troubleshooter", + "next_agent": null, + "phase": "deployed", + + "deployment": { + "staging": { + "deployed_at": "2025-01-15T17:15:00Z", + "smoke_tests": "passed", + "url": "https://staging.example.com" + }, + "production": { + "canary_started": "2025-01-15T17:45:00Z", + "canary_percentage": 10, + "full_rollout": "2025-01-15T17:55:00Z", + "url": "https://api.example.com" + } + }, + + "monitoring": { + "error_rate": "0.02%", + "avg_latency": "38ms", + "p99_latency": "89ms", + "requests_served": 12500 + }, + + "status": "complete", + "total_duration": "7.5 hours", + "agents_involved": 4, + "context_handoffs": 3 +} +``` + +--- + +## Lessons Learned + +**What Went Well**: +- Clear context handoffs prevented re-work +- Performance targets met from design phase +- TDD approach caught issues early +- Automated deployment smooth + +**Improvements for Next Time**: +- Could have parallelized testing and deployment prep +- Context size grew large - could compress history +- Should add rollback procedure to context + +**Metrics**: +- **Time saved** vs starting fresh each phase: ~40% +- **Context restore success**: 100% +- **Quality maintained** across all handoffs: Yes + +--- + +**Total Workflow Time**: 7.5 hours +**Agents Involved**: 4 +**Context Saves**: 4 +**Handoff Success Rate**: 100% +**Final Quality**: Production-ready diff --git a/skills/context-management/examples/parallel-workflow-example.md b/skills/context-management/examples/parallel-workflow-example.md new file mode 100644 index 0000000..286246c --- /dev/null +++ b/skills/context-management/examples/parallel-workflow-example.md @@ -0,0 +1,873 @@ +# Parallel Workflow Example: Full-Stack Feature Implementation + +Complete example of parallel agent execution with context merge. + +**Scenario**: Implement user profile feature with frontend, backend, and tests developed concurrently. + +**Workflow Pattern**: Parallel Execution → Merge → Integration + +--- + +## Overview + +**Timeline**: ~2 hours (vs 6 hours sequential) + +**Agents Involved**: +1. **Parent Orchestrator** - Coordinates parallel work +2. **Frontend Developer** - React components (parallel) +3. **Backend Developer** - API endpoints (parallel) +4. **Test Generator** - E2E tests (parallel) +5. **Integration Verifier** - Merge and verify (sequential) + +**Speedup**: 3x faster than sequential execution + +--- + +## Phase 1: Parent Context Initialization + +**Agent**: Orchestrator +**Duration**: 5 minutes +**Purpose**: Define overall feature and spawn parallel tasks + +### Parent Context Save + +```json +{ + "version": "1.0", + "workflow_id": "user-profile-feature-20250115", + "timestamp": "2025-01-15T09:00:00Z", + "current_agent": "orchestrator", + "next_agent": null, + "phase": "parallel-execution", + + "feature_spec": { + "name": "User Profile Management", + "description": "Allow users to view and edit their profile information", + "requirements": [ + "View profile (name, email, avatar, bio)", + "Edit profile fields", + "Upload avatar image", + "Validate email format", + "Real-time validation feedback" + ] + }, + + "parallel_tasks": [ + { + "task_id": "frontend-impl", + "agent": "react-tanstack-developer", + "scope": "Build React components for profile view and edit", + "context_ref": ".claude/context/user-profile-feature-20250115-frontend.json", + "status": "in_progress", + "started_at": "2025-01-15T09:05:00Z" + }, + { + "task_id": "backend-impl", + "agent": "tdd-python-developer", + "scope": "Implement profile API endpoints with TDD", + "context_ref": ".claude/context/user-profile-feature-20250115-backend.json", + "status": "in_progress", + "started_at": "2025-01-15T09:05:00Z" + }, + { + "task_id": "test-impl", + "agent": "playwright-tester", + "scope": "Create E2E tests for profile feature", + "context_ref": ".claude/context/user-profile-feature-20250115-tests.json", + "status": "in_progress", + "started_at": "2025-01-15T09:05:00Z" + } + ], + + "shared_constraints": [ + "Must use existing auth system", + "Profile data stored in PostgreSQL users table", + "Avatar images stored in Cloudflare R2", + "Real-time updates via WebSocket optional (nice-to-have)" + ], + + "integration_requirements": [ + "Frontend calls backend API", + "API returns expected data format", + "E2E tests validate full flow", + "All tests pass in CI" + ], + + "success_criteria": { + "backend": [ + "API endpoints: GET /api/profile, PUT /api/profile", + "Test coverage >90%", + "Response time <100ms" + ], + "frontend": [ + "ProfileView and ProfileEdit components", + "Form validation with Zod", + "Avatar upload with preview", + "Component tests >85% coverage" + ], + "e2e": [ + "Complete user flow tested", + "Error cases covered", + "All tests passing" + ] + }, + + "context_summary": "Initialized parallel development of user profile feature with 3 concurrent tracks: frontend (React), backend (Python), and E2E tests (Playwright)." +} +``` + +**File**: `.claude/context/user-profile-feature-20250115.json` + +--- + +## Phase 2A: Frontend Implementation (Parallel) + +**Agent**: React-TanStack Developer +**Duration**: 45 minutes (runs in parallel with backend and tests) + +### Frontend Context Save + +```json +{ + "version": "1.0", + "workflow_id": "user-profile-feature-20250115-frontend", + "parent_workflow_id": "user-profile-feature-20250115", + "task_id": "frontend-impl", + "timestamp": "2025-01-15T09:50:00Z", + "current_agent": "react-tanstack-developer", + "next_agent": null, + "phase": "frontend-complete", + + "files_modified": [ + "src/routes/profile/index.tsx", + "src/routes/profile/edit.tsx", + "src/components/ProfileView.tsx", + "src/components/ProfileEdit.tsx", + "src/components/AvatarUpload.tsx", + "src/lib/validation/profile-schema.ts", + "tests/components/ProfileView.test.tsx", + "tests/components/ProfileEdit.test.tsx" + ], + + "decisions": [ + "Use TanStack Query for profile data fetching", + "Use TanStack Form for profile edit form", + "Zod schema for client-side validation", + "Optimistic updates for better UX", + "Avatar preview before upload using FileReader API" + ], + + "pending_actions": [ + "Integrate with backend API endpoints (waiting for backend-impl)", + "Update API base URL in production config", + "Add loading states and error handling", + "Accessibility audit (WCAG 2.1 AA)" + ], + + "implementation_details": { + "components": { + "ProfileView": { + "path": "src/components/ProfileView.tsx", + "props": "{ userId: string }", + "key_features": [ + "Fetches profile with TanStack Query", + "Displays avatar, name, email, bio", + "Edit button navigates to /profile/edit", + "Loading skeleton", + "Error boundary" + ] + }, + "ProfileEdit": { + "path": "src/components/ProfileEdit.tsx", + "props": "{ userId: string, onSuccess: () => void }", + "key_features": [ + "TanStack Form with Zod validation", + "Real-time validation feedback", + "Avatar upload with preview", + "Optimistic updates", + "Cancel discards changes" + ] + }, + "AvatarUpload": { + "path": "src/components/AvatarUpload.tsx", + "props": "{ currentAvatar?: string, onUpload: (file: File) => void }", + "key_features": [ + "Drag-and-drop or click to upload", + "Image preview before upload", + "Client-side validation (max 5MB, jpg/png only)", + "Crop modal (optional enhancement)" + ] + } + }, + + "validation_schema": { + "path": "src/lib/validation/profile-schema.ts", + "schema": "z.object({ name: z.string().min(1).max(100), email: z.string().email(), bio: z.string().max(500).optional(), avatar: z.instanceof(File).optional() })", + "shared_with_backend": false + }, + + "test_coverage": { + "total": "87%", + "files": { + "ProfileView.test.tsx": "92% - tests loading, error, success states", + "ProfileEdit.test.tsx": "85% - tests validation, submission, cancel" + } + } + }, + + "api_contract_assumptions": { + "GET /api/profile/:userId": { + "response": "{ id: string, name: string, email: string, bio?: string, avatar_url?: string }", + "error_codes": [401, 404] + }, + "PUT /api/profile/:userId": { + "request": "{ name: string, email: string, bio?: string }", + "response": "{ id: string, name: string, email: string, bio?: string, avatar_url?: string }", + "error_codes": [400, 401, 404] + }, + "POST /api/profile/:userId/avatar": { + "request": "multipart/form-data with 'avatar' field", + "response": "{ avatar_url: string }", + "error_codes": [400, 413] + } + }, + + "context_summary": "Implemented React components for user profile (view and edit) with TanStack Query/Form, Zod validation, and avatar upload. 87% test coverage. Ready for backend API integration." +} +``` + +**File**: `.claude/context/user-profile-feature-20250115-frontend.json` +**Execution Time**: 45 minutes + +--- + +## Phase 2B: Backend Implementation (Parallel) + +**Agent**: TDD-Python Developer +**Duration**: 60 minutes (runs in parallel with frontend and tests) + +### Backend Context Save + +```json +{ + "version": "1.0", + "workflow_id": "user-profile-feature-20250115-backend", + "parent_workflow_id": "user-profile-feature-20250115", + "task_id": "backend-impl", + "timestamp": "2025-01-15T10:05:00Z", + "current_agent": "tdd-python-developer", + "next_agent": null, + "phase": "backend-complete", + + "files_modified": [ + "src/api/routes/profile.py", + "src/models/user.py", + "src/schemas/profile.py", + "tests/api/test_profile.py", + "tests/integration/test_profile_flow.py", + "alembic/versions/003_add_bio_to_users.py" + ], + + "decisions": [ + "Use FastAPI for REST endpoints", + "Pydantic v2 for request/response schemas", + "SQLModel for database ORM", + "Cloudflare R2 for avatar storage via presigned URLs", + "JWT authentication (existing auth system)", + "Rate limiting: 10 profile updates per hour per user" + ], + + "pending_actions": [ + "Configure R2 bucket in production (cloudflare-r2-avatars)", + "Set environment variables: R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY", + "Run database migration: alembic upgrade head", + "Add CORS configuration for frontend domain" + ], + + "implementation_details": { + "endpoints": { + "GET /api/profile/{user_id}": { + "auth": "Required (JWT)", + "permissions": "User can only view own profile or public profiles", + "response_model": "ProfileResponse", + "cache": "60 seconds", + "performance": "Avg 45ms, P99 85ms" + }, + "PUT /api/profile/{user_id}": { + "auth": "Required (JWT)", + "permissions": "User can only edit own profile", + "request_model": "ProfileUpdateRequest", + "response_model": "ProfileResponse", + "validation": "Email uniqueness, name min 1 char, bio max 500 chars", + "performance": "Avg 120ms, P99 200ms" + }, + "POST /api/profile/{user_id}/avatar": { + "auth": "Required (JWT)", + "permissions": "User can only upload to own profile", + "request": "multipart/form-data", + "validation": "Max 5MB, jpg/png/gif only", + "response_model": "AvatarUploadResponse", + "storage": "Cloudflare R2 with public URL", + "performance": "Avg 850ms, P99 1500ms" + } + }, + + "schemas": { + "ProfileResponse": { + "fields": "id: UUID, name: str, email: EmailStr, bio: Optional[str], avatar_url: Optional[str], created_at: datetime, updated_at: datetime" + }, + "ProfileUpdateRequest": { + "fields": "name: str (min 1, max 100), email: EmailStr, bio: Optional[str] (max 500)", + "validators": "Email uniqueness check, name not empty" + }, + "AvatarUploadResponse": { + "fields": "avatar_url: str" + } + }, + + "database_changes": { + "migration": "003_add_bio_to_users", + "changes": [ + "Add 'bio' column to users table (TEXT, nullable)", + "Add 'avatar_url' column to users table (VARCHAR(500), nullable)", + "Add index on users.email for uniqueness check" + ] + }, + + "test_coverage": { + "total": "94%", + "files": { + "test_profile.py": "Unit tests for endpoints - 95% coverage", + "test_profile_flow.py": "Integration tests for full flow - 92% coverage" + }, + "test_count": { + "total": 28, + "unit": 18, + "integration": 10 + } + } + }, + + "security_measures": [ + "JWT authentication on all endpoints", + "Permission check: user can only modify own profile", + "Email validation and sanitization", + "SQL injection prevention via SQLModel ORM", + "File upload validation (type, size)", + "Rate limiting on profile updates", + "CORS restricted to frontend domain only" + ], + + "context_summary": "Implemented FastAPI profile endpoints (GET, PUT, POST /avatar) with TDD approach. 94% test coverage (28 tests). Database migration ready. Avatar storage on Cloudflare R2. JWT auth and rate limiting implemented." +} +``` + +**File**: `.claude/context/user-profile-feature-20250115-backend.json` +**Execution Time**: 60 minutes + +--- + +## Phase 2C: E2E Test Implementation (Parallel) + +**Agent**: Playwright Tester +**Duration**: 50 minutes (runs in parallel with frontend and backend) + +### E2E Tests Context Save + +```json +{ + "version": "1.0", + "workflow_id": "user-profile-feature-20250115-tests", + "parent_workflow_id": "user-profile-feature-20250115", + "task_id": "test-impl", + "timestamp": "2025-01-15T09:55:00Z", + "current_agent": "playwright-tester", + "next_agent": null, + "phase": "e2e-tests-complete", + + "files_modified": [ + "e2e/profile/view-profile.spec.ts", + "e2e/profile/edit-profile.spec.ts", + "e2e/profile/upload-avatar.spec.ts", + "e2e/fixtures/test-users.json", + "e2e/utils/profile-helpers.ts" + ], + + "decisions": [ + "Use Playwright for E2E testing", + "Test against local development server", + "Create dedicated test user accounts", + "Use Page Object Model pattern", + "Visual regression testing for avatar uploads" + ], + + "pending_actions": [ + "Configure E2E tests in CI pipeline", + "Set up test database seeding", + "Add visual regression baseline images", + "Run tests against staging before merge" + ], + + "implementation_details": { + "test_files": { + "view-profile.spec.ts": { + "tests": 5, + "scenarios": [ + "View own profile - displays correct data", + "View profile when not logged in - redirects to login", + "View non-existent profile - shows 404", + "Profile loads with avatar - image displayed", + "Profile loads without avatar - shows default" + ] + }, + "edit-profile.spec.ts": { + "tests": 8, + "scenarios": [ + "Edit profile with valid data - saves successfully", + "Edit name to empty string - shows validation error", + "Edit email to invalid format - shows validation error", + "Edit email to existing email - shows uniqueness error", + "Bio exceeds 500 chars - shows validation error", + "Cancel edit - discards changes", + "Edit profile when not logged in - redirects", + "Optimistic update - UI updates immediately" + ] + }, + "upload-avatar.spec.ts": { + "tests": 6, + "scenarios": [ + "Upload valid image (jpg) - succeeds and displays", + "Upload valid image (png) - succeeds and displays", + "Upload file >5MB - shows error", + "Upload non-image file - shows error", + "Upload image then cancel - reverts to previous", + "Visual regression - avatar displays correctly" + ] + } + }, + + "page_objects": { + "ProfileViewPage": { + "selectors": { + "avatar": "[data-testid='profile-avatar']", + "name": "[data-testid='profile-name']", + "email": "[data-testid='profile-email']", + "bio": "[data-testid='profile-bio']", + "editButton": "[data-testid='edit-profile-btn']" + }, + "methods": [ + "isDisplayed()", + "getDisplayedName()", + "clickEditButton()" + ] + }, + "ProfileEditPage": { + "selectors": { + "nameInput": "[data-testid='input-name']", + "emailInput": "[data-testid='input-email']", + "bioInput": "[data-testid='input-bio']", + "avatarUpload": "[data-testid='avatar-upload']", + "saveButton": "[data-testid='save-profile-btn']", + "cancelButton": "[data-testid='cancel-btn']" + }, + "methods": [ + "fillName(name: string)", + "fillEmail(email: string)", + "fillBio(bio: string)", + "uploadAvatar(filePath: string)", + "clickSave()", + "clickCancel()" + ] + } + }, + + "test_coverage": { + "total_scenarios": 19, + "happy_path": 7, + "error_cases": 10, + "edge_cases": 2 + } + }, + + "test_data": { + "test_users": [ + { + "id": "test-user-1", + "name": "Alice Johnson", + "email": "alice@example.com", + "bio": "Software engineer and coffee enthusiast", + "avatar_url": null + }, + { + "id": "test-user-2", + "name": "Bob Smith", + "email": "bob@example.com", + "bio": null, + "avatar_url": "https://example.com/avatars/bob.jpg" + } + ] + }, + + "assumptions": { + "frontend": "React components render expected data-testid attributes", + "backend": "API returns expected error codes (400, 401, 404)", + "auth": "Test users can authenticate with JWT tokens" + }, + + "context_summary": "Created 19 E2E test scenarios with Playwright covering profile view, edit, and avatar upload. Page Object Model pattern for maintainability. Tests ready to run once frontend and backend integrated." +} +``` + +**File**: `.claude/context/user-profile-feature-20250115-tests.json` +**Execution Time**: 50 minutes + +--- + +## Phase 3: Merge Parallel Results + +**Agent**: Orchestrator +**Duration**: 5 minutes +**Purpose**: Merge contexts from 3 parallel tasks + +### Merged Context + +```json +{ + "version": "1.0", + "workflow_id": "user-profile-feature-20250115", + "timestamp": "2025-01-15T10:10:00Z", + "current_agent": "orchestrator", + "next_agent": "integration-verifier", + "phase": "parallel-complete-merge", + + "feature_spec": { + "name": "User Profile Management", + "status": "implementation-complete" + }, + + "parallel_execution_summary": { + "started_at": "2025-01-15T09:05:00Z", + "completed_at": "2025-01-15T10:05:00Z", + "total_duration_minutes": 60, + "tasks": [ + { + "task_id": "frontend-impl", + "agent": "react-tanstack-developer", + "duration_minutes": 45, + "status": "completed", + "files_count": 8, + "test_coverage": "87%" + }, + { + "task_id": "backend-impl", + "agent": "tdd-python-developer", + "duration_minutes": 60, + "status": "completed", + "files_count": 6, + "test_coverage": "94%" + }, + { + "task_id": "test-impl", + "agent": "playwright-tester", + "duration_minutes": 50, + "status": "completed", + "files_count": 5, + "test_coverage": "100% (all scenarios covered)" + } + ] + }, + + "files_modified": [ + "src/routes/profile/index.tsx", + "src/routes/profile/edit.tsx", + "src/components/ProfileView.tsx", + "src/components/ProfileEdit.tsx", + "src/components/AvatarUpload.tsx", + "src/lib/validation/profile-schema.ts", + "tests/components/ProfileView.test.tsx", + "tests/components/ProfileEdit.test.tsx", + "src/api/routes/profile.py", + "src/models/user.py", + "src/schemas/profile.py", + "tests/api/test_profile.py", + "tests/integration/test_profile_flow.py", + "alembic/versions/003_add_bio_to_users.py", + "e2e/profile/view-profile.spec.ts", + "e2e/profile/edit-profile.spec.ts", + "e2e/profile/upload-avatar.spec.ts", + "e2e/fixtures/test-users.json", + "e2e/utils/profile-helpers.ts" + ], + + "decisions": [ + "Frontend: TanStack Query + Form, Zod validation, optimistic updates", + "Backend: FastAPI, Pydantic v2, SQLModel ORM, JWT auth", + "Storage: Cloudflare R2 for avatars with presigned URLs", + "Testing: Playwright E2E with Page Object Model", + "Rate limiting: 10 profile updates per hour per user" + ], + + "pending_actions": [ + "Integration verification (API contract alignment)", + "Run full test suite (unit + integration + E2E)", + "Configure R2 bucket in production", + "Run database migration in staging", + "Update API base URL in frontend production config", + "Add CORS configuration for frontend domain", + "Deploy to staging for final validation" + ], + + "integration_concerns": [ + { + "concern": "API contract alignment", + "frontend_expects": "GET /api/profile/:userId returns { id, name, email, bio?, avatar_url? }", + "backend_provides": "ProfileResponse with matching fields", + "status": "aligned" + }, + { + "concern": "Error code handling", + "frontend_expects": "400, 401, 404 error codes", + "backend_provides": "400, 401, 404 as documented", + "status": "aligned" + }, + { + "concern": "Avatar upload flow", + "frontend_expects": "POST /api/profile/:userId/avatar with multipart form", + "backend_provides": "Endpoint with multipart form support", + "status": "aligned" + } + ], + + "metrics": { + "total_files_modified": 19, + "total_test_coverage": "91% average", + "development_time": "60 minutes parallel (vs 155 minutes sequential)", + "speedup": "2.6x faster" + }, + + "context_summary": "Successfully merged 3 parallel development tracks (frontend, backend, E2E tests). All implementations complete with 91% average test coverage. API contracts aligned. Ready for integration verification and deployment to staging." +} +``` + +**File**: `.claude/context/user-profile-feature-20250115.json` (updated) + +--- + +## Phase 4: Integration Verification + +**Agent**: Integration Verifier +**Duration**: 15 minutes +**Purpose**: Verify all pieces work together + +### Final Context Save + +```json +{ + "version": "1.0", + "workflow_id": "user-profile-feature-20250115", + "timestamp": "2025-01-15T10:25:00Z", + "current_agent": "integration-verifier", + "next_agent": null, + "phase": "integration-verified-ready-for-deployment", + + "verification_results": { + "api_contract_alignment": { + "status": "passed", + "checks": [ + "✅ GET /api/profile/:userId response matches frontend expectations", + "✅ PUT /api/profile/:userId request/response aligned", + "✅ POST /api/profile/:userId/avatar matches frontend upload", + "✅ Error codes (400, 401, 404) handled correctly" + ] + }, + + "test_execution": { + "status": "passed", + "results": { + "unit_tests": "46/46 passed (100%)", + "integration_tests": "10/10 passed (100%)", + "e2e_tests": "19/19 passed (100%)" + }, + "total": "75/75 tests passed (100%)" + }, + + "performance": { + "status": "passed", + "measurements": { + "GET /api/profile": "P50: 42ms, P95: 78ms, P99: 95ms ✅ (target <100ms)", + "PUT /api/profile": "P50: 105ms, P95: 185ms, P99: 220ms ✅ (target <200ms)", + "POST /api/profile/avatar": "P50: 780ms, P95: 1350ms, P99: 1680ms ✅ (target <2000ms)" + } + }, + + "security": { + "status": "passed", + "checks": [ + "✅ JWT authentication on all endpoints", + "✅ Permission checks prevent cross-user access", + "✅ Email validation and sanitization", + "✅ File upload validation (type, size)", + "✅ Rate limiting configured", + "✅ CORS restricted to allowed origins", + "✅ No secrets in frontend code" + ] + }, + + "database_migration": { + "status": "completed", + "migration": "003_add_bio_to_users", + "applied_to": ["development", "staging"], + "pending": ["production"] + } + }, + + "deployment_readiness": { + "staging": { + "status": "deployed", + "url": "https://staging.example.com/profile", + "deployed_at": "2025-01-15T10:20:00Z", + "validation": "All E2E tests passed on staging" + }, + "production": { + "status": "ready", + "prerequisites": [ + "✅ All tests passing", + "✅ Code reviewed and approved", + "✅ Security audit completed", + "✅ Performance benchmarks met", + "⏳ Run database migration (manual step)", + "⏳ Configure R2 bucket (manual step)", + "⏳ Deploy to production (manual step)" + ] + } + }, + + "pending_actions": [ + "Run production database migration: alembic upgrade head", + "Configure Cloudflare R2 bucket: cloudflare-r2-avatars", + "Set production environment variables (R2 credentials, CORS origin)", + "Deploy backend to production", + "Deploy frontend to production", + "Monitor production metrics for 24 hours", + "Create user documentation for profile feature" + ], + + "context_summary": "Integration verified successfully. All 75 tests passing. Performance targets met. Security audit passed. Deployed to staging and validated. Ready for production deployment after manual configuration steps (database migration, R2 bucket setup)." +} +``` + +**File**: `.claude/context/user-profile-feature-20250115.json` (final) + +--- + +## Workflow Metrics + +### Time Comparison + +| Phase | Sequential | Parallel | Speedup | +|-------|-----------|----------|---------| +| Design & Planning | 5 min | 5 min | 1.0x | +| Frontend Implementation | 45 min | 45 min | 1.0x (parallel) | +| Backend Implementation | 60 min | 60 min | 1.0x (parallel) | +| E2E Test Implementation | 50 min | 50 min | 1.0x (parallel) | +| **Development Total** | **160 min** | **60 min** | **2.7x** | +| Integration & Verification | 15 min | 15 min | 1.0x | +| **Overall Total** | **180 min** | **80 min** | **2.25x** | + +**Savings**: 100 minutes (1 hour 40 minutes) + +--- + +### Context Size Progression + +| Phase | Context Size | Files Modified | +|-------|-------------|----------------| +| Initial (Parent) | 2.1 KB | 0 | +| Frontend (Child) | 4.8 KB | 8 | +| Backend (Child) | 6.2 KB | 6 | +| E2E Tests (Child) | 5.1 KB | 5 | +| **Merged** | **12.5 KB** | **19** | +| Final (Verified) | 8.9 KB | 19 | + +**Optimization**: Merged context pruned conversation history and redundant data, reducing from 12.5 KB to 8.9 KB (29% reduction). + +--- + +### Test Coverage + +| Track | Unit Tests | Integration Tests | E2E Tests | Coverage | +|-------|-----------|------------------|-----------|----------| +| Frontend | 2 suites | - | - | 87% | +| Backend | 18 tests | 10 tests | - | 94% | +| E2E Tests | - | - | 19 scenarios | 100% | +| **Total** | **20** | **10** | **19** | **91% avg** | + +--- + +## Key Takeaways + +### Parallel Execution Benefits + +✅ **2.25x faster** than sequential execution +✅ **Independent work streams** - no blocking between frontend, backend, tests +✅ **Early issue detection** - E2E tests identified API contract assumptions early +✅ **Higher quality** - Each agent focused deeply on their domain + +### Context Management Insights + +**Context Size**: Parallel contexts were larger overall (total ~16 KB vs sequential ~8 KB), but merge reduced redundancy to 8.9 KB. + +**Context Merge Strategy**: +- Union of `files_modified` (no duplicates) +- Concatenate `decisions` from all tasks +- Merge `pending_actions` with deduplication +- Aggregate `error_log` from all tasks + +**Handoff Points**: +1. Parent → 3 parallel children (split) +2. 3 parallel children → parent (merge) +3. Parent → integration verifier (sequential) + +### Challenges and Solutions + +**Challenge 1**: API contract alignment between frontend and backend +**Solution**: Defined explicit API contract assumptions in parent context. Integration verifier validated alignment. + +**Challenge 2**: Test data coordination across E2E tests and backend +**Solution**: Shared test user fixtures in parent context. Backend seeded database with test data. + +**Challenge 3**: Avatar upload implementation depends on R2 configuration +**Solution**: Documented R2 setup as prerequisite in parent context. Used local file storage for development. + +--- + +## Usage Guide + +### When to Use Parallel Execution + +✅ **Use parallel when**: +- Tasks are independent (minimal dependencies) +- Different agents/skill sets required +- Time-critical delivery +- Multiple subsystems (frontend, backend, database, tests) + +❌ **Don't use parallel when**: +- Tasks have sequential dependencies +- Shared resources with locking concerns +- Single agent can handle all work efficiently +- Coordination overhead > time savings + +### Scaling to More Tasks + +This example showed 3 parallel tasks. Practical limits: +- **3-5 tasks**: Optimal parallelism (diminishing returns after) +- **6-10 tasks**: Requires careful orchestration, higher merge complexity +- **10+ tasks**: Consider hierarchical parallelism (parent spawns sub-parents) + +--- + +**Example Complexity**: Medium-High +**Lines of Code**: ~2000 across 19 files +**Total Tests**: 75 (20 unit, 10 integration, 19 E2E) +**Success Rate**: 100% (all tests passing) +**Production Ready**: Yes (after manual config steps) diff --git a/skills/context-management/reference/INDEX.md b/skills/context-management/reference/INDEX.md new file mode 100644 index 0000000..8c6bda8 --- /dev/null +++ b/skills/context-management/reference/INDEX.md @@ -0,0 +1,623 @@ +# Context Management Reference Guide + +Complete reference for multi-agent workflow context management. + +**Quick Navigation:** +- [Context Management Guide](#context-management-guide) - Save/restore operations +- [Workflow Patterns](#workflow-patterns) - Sequential, Parallel, Conditional, Resumable +- [State Persistence](#state-persistence) - Serialization, compression, versioning +- [Performance](#performance) - Optimization strategies + +--- + +## Overview + +Context management enables multi-agent workflows by preserving state across agent transitions. + +**Core Capabilities:** +- Save agent state at any workflow phase +- Restore state to resume or handoff work +- Validate context integrity +- Optimize context size +- Handle version compatibility + +**Key Metrics:** +- Average context size: 5-100 KB +- Serialization time: <200ms (99th percentile) +- Restore success rate: 99.8% +- Context retention: 30 days default + +--- + +## Context Management Guide + +### Save Operation + +**When to Save:** +- Phase completion (design done, implementation done) +- Agent handoff (passing work to next agent) +- Checkpoint creation (before risky operations) +- Long-running workflows (every 30 minutes) +- User-requested pause + +**What to Save:** +```json +{ + "version": "1.0", + "workflow_id": "unique-identifier", + "timestamp": "2025-01-15T10:30:00Z", + "current_agent": "agent-saving-context", + "next_agent": "agent-to-receive-context", + "phase": "current-workflow-phase", + + "files_modified": ["src/api.ts", "tests/api.test.ts"], + "decisions": ["Use REST API", "PostgreSQL for storage"], + "pending_actions": ["Write tests", "Deploy to staging"], + + "context_summary": "Implemented user API endpoints", + "constraints": ["Must support v1 API", "< 200ms response"], + + "conversation_history": [...], + "checkpoints": {...}, + "error_log": [...] +} +``` + +**Save Best Practices:** +- ✅ Include all decisions with rationale +- ✅ List pending actions in priority order +- ✅ Document constraints explicitly +- ✅ Keep context summary under 500 chars +- ✅ Use relative file paths +- ❌ Don't include sensitive data (API keys, passwords) +- ❌ Don't use absolute file paths +- ❌ Don't save redundant conversation history + +### Restore Operation + +**When to Restore:** +- Starting new session on existing workflow +- Agent handoff receiving work +- Rollback after error +- Resuming paused workflow +- Debugging previous decisions + +**Restore Process:** +```python +# 1. Load context file +with open('.claude/context/workflow-id.json') as f: + context = json.load(f) + +# 2. Validate schema +validate_context_schema(context) + +# 3. Check version compatibility +if context['version'] != CURRENT_VERSION: + context = migrate_context(context) + +# 4. Verify files exist +for file_path in context['files_modified']: + if not os.path.exists(file_path): + log_warning(f"Missing file: {file_path}") + +# 5. Reconstruct state +workflow.load_state(context) + +# 6. Resume from phase +workflow.resume(context['phase']) +``` + +**Restore Validation:** +- [ ] Schema validation passes +- [ ] Required fields present +- [ ] Version compatible +- [ ] Referenced files exist +- [ ] No data corruption + +### Context Size Optimization + +**Target Sizes:** +- **Simple workflows (1-2 agents):** 5-20 KB +- **Medium workflows (3-5 agents):** 20-100 KB +- **Complex workflows (6+ agents):** 100-500 KB +- **Very large (requires optimization):** >500 KB + +**Optimization Strategies:** + +1. **Conversation History Pruning** +```javascript +// Keep only critical messages +function pruneHistory(history, maxMessages = 50) { + // Keep first 5 (initial context) + const start = history.slice(0, 5); + + // Keep last 20 (recent context) + const recent = history.slice(-20); + + // Keep decision points in middle + const decisions = history.filter(msg => + msg.content.includes('DECISION:') || + msg.content.includes('ERROR:') + ); + + return [...start, ...decisions, ...recent]; +} +``` + +2. **Checkpoint Compression** +```python +import json +import gzip + +def compress_checkpoint(checkpoint): + """Compress checkpoint data.""" + json_str = json.dumps(checkpoint) + compressed = gzip.compress(json_str.encode('utf-8')) + return base64.b64encode(compressed).decode('utf-8') + +def decompress_checkpoint(compressed_data): + """Decompress checkpoint data.""" + compressed = base64.b64decode(compressed_data) + json_str = gzip.decompress(compressed).decode('utf-8') + return json.loads(json_str) +``` + +3. **External Large Data** +```json +{ + "files_modified": ["src/api.ts"], + "large_file_refs": { + "src/api.ts": { + "size": 15000, + "hash": "sha256:abc123...", + "storage": ".claude/context/files/api-ts-snapshot.txt" + } + } +} +``` + +**Size Reduction Checklist:** +- [ ] Remove completed pending_actions +- [ ] Prune conversation_history (keep <50 messages) +- [ ] Compress checkpoints (use gzip) +- [ ] Externalize large file contents +- [ ] Remove redundant decision descriptions +- [ ] Deduplicate error_log entries + +--- + +## Workflow Patterns + +### Pattern 1: Sequential Handoff + +**Use Case:** Linear workflow where each agent completes before next starts. + +``` +Agent A (Design) → Context Save → Agent B (Implement) + → Context Save → Agent C (Test) + → Context Save → Agent D (Deploy) +``` + +**Context Flow:** +```json +// Agent A saves +{ + "current_agent": "architect", + "next_agent": "tdd-typescript", + "phase": "design-complete", + "decisions": ["Use REST API", "PostgreSQL"], + "pending_actions": ["Implement endpoints", "Write tests"] +} + +// Agent B loads, works, saves +{ + "current_agent": "tdd-typescript", + "next_agent": "test-generator", + "phase": "implementation-complete", + "decisions": [...previous, "FastAPI framework", "Pydantic validation"], + "pending_actions": ["Generate integration tests", "Test error cases"] +} +``` + +**Benefits:** +- Simple to understand and debug +- Clear responsibility handoff +- Easy to track progress +- Supports different agent types + +**When to Use:** +- Feature development pipelines +- Code review workflows +- Deployment processes + +### Pattern 2: Parallel Execution + +**Use Case:** Multiple agents work concurrently on independent tasks. + +``` + ┌─ Agent B (Frontend) ─┐ +Agent A (Design) ──┼─ Agent C (Backend) ──┼─→ Agent D (Integration) + └─ Agent D (Tests) ─┘ +``` + +**Context Management:** +```json +// Parent context spawns 3 parallel contexts +{ + "workflow_id": "feature-xyz", + "phase": "parallel-execution", + "parallel_tasks": [ + { + "task_id": "frontend-impl", + "agent": "react-developer", + "context_ref": ".claude/context/feature-xyz-frontend.json", + "status": "in_progress" + }, + { + "task_id": "backend-impl", + "agent": "api-developer", + "context_ref": ".claude/context/feature-xyz-backend.json", + "status": "in_progress" + }, + { + "task_id": "test-impl", + "agent": "test-generator", + "context_ref": ".claude/context/feature-xyz-tests.json", + "status": "completed" + } + ] +} +``` + +**Merge Strategy:** +```javascript +async function mergeParallelContexts(parentContext) { + const results = await Promise.all( + parentContext.parallel_tasks.map(task => + loadContext(task.context_ref) + ) + ); + + return { + ...parentContext, + phase: "parallel-complete", + files_modified: results.flatMap(r => r.files_modified), + decisions: results.flatMap(r => r.decisions), + errors: results.flatMap(r => r.error_log) + }; +} +``` + +### Pattern 3: Conditional Routing + +**Use Case:** Workflow branches based on conditions or results. + +``` +Agent A (Analysis) → Context Save → Condition Check + ├─ If security issue → Security Agent + ├─ If performance issue → Perf Agent + └─ If quality issue → Code Review Agent +``` + +**Conditional Logic:** +```json +{ + "workflow_id": "code-analysis", + "phase": "analysis-complete", + "current_agent": "code-analyzer", + "next_agent": null, // Determined by routing logic + + "routing_conditions": { + "has_security_issues": true, + "has_performance_issues": false, + "code_quality_score": 85 + }, + + "routing_rules": [ + { + "condition": "has_security_issues == true", + "next_agent": "security-analyzer", + "priority": 1 + }, + { + "condition": "has_performance_issues == true", + "next_agent": "performance-optimizer", + "priority": 2 + }, + { + "condition": "code_quality_score < 80", + "next_agent": "code-quality-analyzer", + "priority": 3 + } + ] +} +``` + +### Pattern 4: Resumable Long-Running + +**Use Case:** Workflows that span multiple sessions or require human approval. + +**Checkpoint Strategy:** +```json +{ + "workflow_id": "migration-v2-to-v3", + "phase": "migration-in-progress", + "current_agent": "migration-orchestrator", + + "checkpoints": [ + { + "id": "checkpoint-1", + "timestamp": "2025-01-15T10:00:00Z", + "phase": "schema-migrated", + "files_modified": ["db/migrations/001_v3_schema.sql"], + "rollback_cmd": "npm run migrate:rollback 001" + }, + { + "id": "checkpoint-2", + "timestamp": "2025-01-15T10:30:00Z", + "phase": "data-migrated", + "files_modified": ["db/migrations/002_data_transform.sql"], + "rollback_cmd": "npm run migrate:rollback 002" + } + ], + + "resume_from": "checkpoint-2", + "pending_actions": [ + "Migrate user preferences (50% complete)", + "Update API endpoints", + "Deploy to staging" + ] +} +``` + +--- + +## State Persistence + +### Serialization Formats + +**JSON (Default)** +```json +{ + "version": "1.0", + "workflow_id": "example", + "timestamp": "2025-01-15T10:30:00Z" +} +``` +- ✅ Human-readable +- ✅ Wide tool support +- ✅ Schema validation available +- ❌ Larger file size +- **Use for:** Most workflows + +**Compressed JSON (Large Contexts)** +```python +import gzip +import json + +context_json = json.dumps(context) +compressed = gzip.compress(context_json.encode()) +# Reduces size by 60-80% +``` +- ✅ 60-80% size reduction +- ✅ Still JSON underneath +- ❌ Not human-readable without decompression +- **Use for:** Contexts >100KB + +### Version Management + +**Schema Versions:** +```json +{ + "version": "1.0", // Breaking changes increment major + "schema_version": "1.2" // Non-breaking changes increment minor +} +``` + +**Migration Example:** +```javascript +function migrateContext(context) { + const migrations = { + '1.0': migrateFrom1_0, + '1.1': migrateFrom1_1, + '2.0': migrateFrom2_0 + }; + + let current = context; + const currentVersion = current.version; + const targetVersion = CURRENT_VERSION; + + // Apply migrations sequentially + for (const [version, migrateFn] of Object.entries(migrations)) { + if (compareVersions(currentVersion, version) < 0) { + current = migrateFn(current); + } + } + + return current; +} + +function migrateFrom1_0(context) { + // v1.0 → v1.1: Add 'constraints' field + return { + ...context, + version: '1.1', + constraints: [] + }; +} +``` + +### Error Recovery + +**Corrupted Context Detection:** +```python +def validate_context_integrity(context_path): + """Validate context file integrity.""" + try: + with open(context_path) as f: + context = json.load(f) + + # Check required fields + required = ['version', 'workflow_id', 'timestamp'] + for field in required: + if field not in context: + raise ValueError(f"Missing required field: {field}") + + # Validate timestamp format + datetime.fromisoformat(context['timestamp']) + + # Check file references + for file_path in context.get('files_modified', []): + if not os.path.exists(file_path): + log_warning(f"Referenced file missing: {file_path}") + + return True + + except json.JSONDecodeError as e: + log_error(f"Invalid JSON: {e}") + return False + except Exception as e: + log_error(f"Validation failed: {e}") + return False +``` + +**Rollback Strategies:** +```json +{ + "workflow_id": "example", + "checkpoints": [ + { + "id": "checkpoint-1", + "timestamp": "2025-01-15T10:00:00Z", + "context_snapshot": ".claude/context/example-cp1.json", + "git_commit": "abc123" + } + ], + + "rollback_to_checkpoint": function(checkpoint_id) { + const checkpoint = this.checkpoints.find(cp => cp.id === checkpoint_id); + + // Restore context + const snapshot = loadContext(checkpoint.context_snapshot); + + // Restore code (optional) + if (checkpoint.git_commit) { + execSync(`git reset --hard ${checkpoint.git_commit}`); + } + + return snapshot; + } +} +``` + +--- + +## Performance + +### Optimization Benchmarks + +| Operation | Target | P50 | P95 | P99 | +|-----------|--------|-----|-----|-----| +| Save (small <20KB) | <50ms | 12ms | 45ms | 80ms | +| Save (large >100KB) | <200ms | 85ms | 180ms | 250ms | +| Restore (small) | <100ms | 35ms | 90ms | 150ms | +| Restore (large) | <500ms | 220ms | 480ms | 600ms | +| Validate | <50ms | 18ms | 40ms | 65ms | + +### Optimization Techniques + +**1. Lazy Loading** +```javascript +class WorkflowContext { + constructor(contextPath) { + this.metadata = this.loadMetadata(contextPath); + this._fullContext = null; // Load only when needed + } + + loadMetadata(path) { + // Load only essential fields + const context = JSON.parse(fs.readFileSync(path)); + return { + version: context.version, + workflow_id: context.workflow_id, + phase: context.phase, + current_agent: context.current_agent + }; + } + + get conversationHistory() { + if (!this._fullContext) { + this._fullContext = this.loadFullContext(); + } + return this._fullContext.conversation_history; + } +} +``` + +**2. Incremental Updates** +```javascript +// Instead of saving entire context every time +function updateContext(workflow_id, updates) { + const contextPath = `.claude/context/${workflow_id}.json`; + const context = JSON.parse(fs.readFileSync(contextPath)); + + // Apply updates + Object.assign(context, updates); + context.timestamp = new Date().toISOString(); + + // Atomic write with temp file + const tempPath = `${contextPath}.tmp`; + fs.writeFileSync(tempPath, JSON.stringify(context, null, 2)); + fs.renameSync(tempPath, contextPath); +} +``` + +**3. Caching** +```python +from functools import lru_cache + +@lru_cache(maxsize=10) +def load_context(workflow_id): + """Cache recently loaded contexts.""" + context_path = f".claude/context/{workflow_id}.json" + with open(context_path) as f: + return json.load(f) + +# Invalidate cache on updates +def save_context(workflow_id, context): + load_context.cache_clear() # Invalidate cache + with open(f".claude/context/{workflow_id}.json", 'w') as f: + json.dump(context, f, indent=2) +``` + +--- + +## Quick Reference + +**Essential Context Fields:** +- ✅ `version`, `workflow_id`, `timestamp` (required) +- ✅ `current_agent`, `phase` (required) +- ⚠️ `next_agent`, `pending_actions` (important) +- ℹ️ `context_summary`, `decisions` (helpful) + +**Size Targets:** +- Simple: 5-20 KB +- Medium: 20-100 KB +- Complex: 100-500 KB +- Optimize if: >500 KB + +**Performance Targets:** +- Save: <200ms (P99) +- Restore: <500ms (P99) +- Validate: <50ms (P99) + +**Common Patterns:** +1. Sequential handoff (linear workflows) +2. Parallel execution (independent tasks) +3. Conditional routing (branching logic) +4. Resumable long-running (multi-session) + +--- + +**Reference Version**: 1.0 +**Last Updated**: 2025-01-15 diff --git a/skills/context-management/reference/workflow-best-practices.md b/skills/context-management/reference/workflow-best-practices.md new file mode 100644 index 0000000..654e60d --- /dev/null +++ b/skills/context-management/reference/workflow-best-practices.md @@ -0,0 +1,880 @@ +# Workflow Best Practices + +Production-ready patterns and practices for multi-agent workflows. + +**Quick Navigation:** +- [Context Design](#context-design) +- [Handoff Patterns](#handoff-patterns) +- [Error Handling](#error-handling) +- [Performance](#performance) +- [Security](#security) +- [Testing](#testing) + +--- + +## Context Design + +### Principle 1: Minimal Context Size + +**Why:** Smaller contexts = faster operations, lower memory, easier debugging. + +**Practice:** +```javascript +// ❌ BAD: Include everything +const context = { + workflow_id: 'feature-123', + // ... required fields ... + + all_git_commits: gitLog(), // Huge! + full_codebase: readAllFiles(), // Unnecessary! + raw_logs: getSystemLogs() // Too much! +}; + +// ✅ GOOD: Only essential information +const context = { + workflow_id: 'feature-123', + version: '1.0', + timestamp: new Date().toISOString(), + current_agent: 'backend-architect', + phase: 'design-complete', + + // Only modified files + files_modified: ['src/api/users.ts', 'tests/api.test.ts'], + + // Only key decisions + decisions: [ + 'Use PostgreSQL for user data', + 'Implement JWT authentication', + 'Rate limit: 100 req/min per user' + ], + + // Only next actions + pending_actions: [ + 'Implement user endpoints', + 'Add authentication middleware', + 'Write integration tests' + ] +}; +``` + +**Guidelines:** +- Target <100KB for 80% of workflows +- Include only information next agent needs +- Reference external data instead of embedding +- Prune completed actions regularly + +--- + +### Principle 2: Explicit Over Implicit + +**Why:** Clear intent prevents misunderstandings and errors. + +**Practice:** +```javascript +// ❌ BAD: Implicit assumptions +const context = { + files_modified: ['api.ts'], + next_agent: 'test-generator' + // Unclear: What should test-generator do? + // Unclear: Are there constraints? +}; + +// ✅ GOOD: Explicit requirements +const context = { + files_modified: ['src/api/users.ts'], + next_agent: 'test-generator', + + pending_actions: [ + { + action: 'generate_integration_tests', + target: 'src/api/users.ts', + requirements: [ + 'Test all CRUD operations', + 'Test authentication', + 'Test error cases (401, 403, 404, 500)', + 'Test rate limiting' + ], + constraints: [ + 'Use Vitest framework', + 'Coverage must be >90%', + 'Tests must be idempotent' + ] + } + ], + + context_summary: 'User API implemented with JWT auth. Need comprehensive tests before deployment.' +}; +``` + +**Checklist:** +- [ ] Next agent explicitly stated +- [ ] Actions clearly described +- [ ] Requirements enumerated +- [ ] Constraints documented +- [ ] Success criteria defined + +--- + +### Principle 3: Versioned Evolution + +**Why:** Workflows evolve. Version tracking enables migration and compatibility. + +**Practice:** +```json +{ + "version": "2.1", + "schema_version": "2.1.0", + + "version_history": [ + { + "version": "1.0", + "timestamp": "2025-01-10T10:00:00Z", + "changes": "Initial context structure" + }, + { + "version": "2.0", + "timestamp": "2025-01-12T14:30:00Z", + "changes": "Added metadata and constraints fields" + }, + { + "version": "2.1", + "timestamp": "2025-01-15T09:00:00Z", + "changes": "Added parallel task support" + } + ], + + "migration_path": { + "1.0_to_2.0": "Add metadata and constraints with defaults", + "2.0_to_2.1": "Add parallel_tasks array if missing" + } +} +``` + +**Guidelines:** +- Increment major version for breaking changes +- Increment minor version for new fields +- Document migration path +- Maintain backward compatibility for 2 versions + +--- + +## Handoff Patterns + +### Pattern 1: Clean Handoff + +**When:** Sequential workflow where each agent completes fully before handoff. + +**Implementation:** +```javascript +class WorkflowOrchestrator { + async executeCleanHandoff(agents) { + let context = this.initializeContext(); + + for (const agent of agents) { + console.log(`Starting agent: ${agent.name}`); + + // Load previous context + const agentContext = { + ...context, + current_agent: agent.name, + next_agent: agents[agents.indexOf(agent) + 1]?.name || null + }; + + // Execute agent + const result = await agent.execute(agentContext); + + // Validate completion + if (result.status !== 'completed') { + throw new Error(`Agent ${agent.name} did not complete successfully`); + } + + // Update context with results + context = { + ...context, + phase: result.phase, + files_modified: [ + ...context.files_modified, + ...result.files_modified + ], + decisions: [ + ...context.decisions, + ...result.decisions + ], + pending_actions: result.pending_actions + }; + + // Save checkpoint + await this.saveContext(context); + + console.log(`✅ Completed agent: ${agent.name}`); + } + + return context; + } +} +``` + +**Best Practices:** +- Save context after each agent +- Validate agent completion +- Accumulate decisions and files +- Clear completed actions + +--- + +### Pattern 2: Conditional Handoff + +**When:** Next agent depends on results or conditions. + +**Implementation:** +```javascript +class ConditionalRouter { + async routeBasedOnResults(context, analysisResults) { + // Define routing rules + const rules = [ + { + condition: () => analysisResults.security_score < 70, + next_agent: 'security-analyzer', + priority: 1, + reason: 'Security vulnerabilities detected' + }, + { + condition: () => analysisResults.performance_score < 80, + next_agent: 'performance-optimizer', + priority: 2, + reason: 'Performance issues detected' + }, + { + condition: () => analysisResults.test_coverage < 85, + next_agent: 'test-generator', + priority: 3, + reason: 'Insufficient test coverage' + } + ]; + + // Find highest priority match + const match = rules + .filter(rule => rule.condition()) + .sort((a, b) => a.priority - b.priority)[0]; + + if (match) { + // Update context for routing + return { + ...context, + next_agent: match.next_agent, + routing_reason: match.reason, + routing_data: analysisResults + }; + } + + // No issues - proceed to deployment + return { + ...context, + next_agent: 'deployment-agent', + routing_reason: 'All checks passed' + }; + } +} +``` + +--- + +### Pattern 3: Parallel Handoff with Merge + +**When:** Multiple agents can work concurrently, then merge results. + +**Implementation:** +```javascript +class ParallelOrchestrator { + async executeParallel(parentContext, tasks) { + // Spawn parallel contexts + const parallelContexts = tasks.map(task => ({ + ...parentContext, + workflow_id: `${parentContext.workflow_id}-${task.id}`, + current_agent: task.agent, + task_id: task.id, + task_scope: task.scope + })); + + // Execute all tasks in parallel + const results = await Promise.allSettled( + parallelContexts.map((ctx, i) => + this.executeTask(tasks[i], ctx) + ) + ); + + // Check for failures + const failures = results.filter(r => r.status === 'rejected'); + if (failures.length > 0) { + throw new Error( + `${failures.length} parallel tasks failed:\n` + + failures.map(f => f.reason).join('\n') + ); + } + + // Merge successful results + return this.mergeResults( + parentContext, + results.map(r => r.value) + ); + } + + mergeResults(parent, childContexts) { + return { + ...parent, + phase: 'parallel-complete', + + // Union of all modified files + files_modified: [ + ...new Set( + childContexts.flatMap(ctx => ctx.files_modified) + ) + ], + + // Concatenate all decisions + decisions: childContexts.flatMap(ctx => ctx.decisions), + + // Merge pending actions + pending_actions: childContexts.flatMap(ctx => + ctx.pending_actions + ), + + // Collect errors from all tasks + error_log: childContexts.flatMap(ctx => + ctx.error_log || [] + ), + + // Track parallel execution + parallel_execution: { + tasks: childContexts.map(ctx => ({ + task_id: ctx.task_id, + agent: ctx.current_agent, + duration_ms: ctx.execution_time, + status: 'completed' + })) + } + }; + } +} +``` + +--- + +## Error Handling + +### Pattern 1: Graceful Degradation + +**Practice:** +```javascript +async function executeWithGracefulDegradation(agent, context) { + try { + // Attempt full execution + return await agent.execute(context); + + } catch (error) { + console.error(`Agent ${agent.name} failed:`, error); + + // Try to save partial progress + const partialContext = { + ...context, + phase: `${context.phase}-failed`, + error_log: [ + ...(context.error_log || []), + { + timestamp: new Date().toISOString(), + agent: agent.name, + error: error.message, + stack: error.stack, + context_at_failure: { + phase: context.phase, + files_modified: context.files_modified + } + } + ] + }; + + // Save failure context + await saveContext(partialContext); + + // Determine if recoverable + if (error.code === 'RECOVERABLE') { + // Suggest recovery action + partialContext.pending_actions.unshift({ + action: 'recover_from_error', + error_id: partialContext.error_log.length - 1, + recovery_strategy: error.recoveryStrategy + }); + + return partialContext; + } + + // Unrecoverable - rethrow + throw error; + } +} +``` + +--- + +### Pattern 2: Checkpoint-Based Rollback + +**Practice:** +```javascript +class CheckpointManager { + async createCheckpoint(context, label) { + const checkpoint = { + id: `checkpoint-${Date.now()}`, + label: label, + timestamp: new Date().toISOString(), + context_snapshot: JSON.parse(JSON.stringify(context)), + git_commit: execSync('git rev-parse HEAD').toString().trim() + }; + + // Save checkpoint + const checkpointPath = `.claude/context/checkpoints/${context.workflow_id}/${checkpoint.id}.json`; + await fs.promises.mkdir(path.dirname(checkpointPath), { recursive: true }); + await fs.promises.writeFile( + checkpointPath, + JSON.stringify(checkpoint, null, 2) + ); + + // Add to context + context.checkpoints = context.checkpoints || []; + context.checkpoints.push({ + id: checkpoint.id, + label: label, + timestamp: checkpoint.timestamp + }); + + return checkpoint.id; + } + + async rollbackToCheckpoint(context, checkpointId) { + // Load checkpoint + const checkpointPath = `.claude/context/checkpoints/${context.workflow_id}/${checkpointId}.json`; + const checkpoint = JSON.parse( + await fs.promises.readFile(checkpointPath, 'utf-8') + ); + + // Restore code state + if (checkpoint.git_commit) { + execSync(`git reset --hard ${checkpoint.git_commit}`); + console.log(`✅ Rolled back code to ${checkpoint.git_commit}`); + } + + // Restore context state + const restoredContext = checkpoint.context_snapshot; + + // Add rollback metadata + restoredContext.rollback_history = restoredContext.rollback_history || []; + restoredContext.rollback_history.push({ + timestamp: new Date().toISOString(), + from_phase: context.phase, + to_checkpoint: checkpointId, + reason: 'manual_rollback' + }); + + return restoredContext; + } +} + +// Usage +const checkpointMgr = new CheckpointManager(); + +// Before risky operation +const checkpointId = await checkpointMgr.createCheckpoint( + context, + 'before-database-migration' +); + +try { + await performDatabaseMigration(); +} catch (error) { + // Rollback on failure + context = await checkpointMgr.rollbackToCheckpoint(context, checkpointId); +} +``` + +--- + +## Performance + +### Optimization 1: Lazy Context Loading + +**Practice:** +```typescript +interface ContextMetadata { + version: string; + workflow_id: string; + phase: string; + timestamp: string; + current_agent: string; +} + +class LazyWorkflowContext { + private _metadata: ContextMetadata | null = null; + private _fullContext: any = null; + + constructor(private contextPath: string) {} + + // Fast metadata access (doesn't load full context) + async getMetadata(): Promise { + if (!this._metadata) { + const json = await fs.promises.readFile(this.contextPath, 'utf-8'); + const context = JSON.parse(json); + + this._metadata = { + version: context.version, + workflow_id: context.workflow_id, + phase: context.phase, + timestamp: context.timestamp, + current_agent: context.current_agent + }; + } + + return this._metadata; + } + + // Load full context only when needed + async getFullContext() { + if (!this._fullContext) { + const json = await fs.promises.readFile(this.contextPath, 'utf-8'); + this._fullContext = JSON.parse(json); + } + + return this._fullContext; + } + + // Access specific fields without full load + async getField(fieldName: string): Promise { + const metadata = await this.getMetadata(); + if (fieldName in metadata) { + return (metadata as any)[fieldName]; + } + + // Need full context for this field + const full = await this.getFullContext(); + return full[fieldName]; + } +} + +// Usage - very fast for metadata-only operations +const ctx = new LazyWorkflowContext('.claude/context/workflow-123.json'); +const phase = await ctx.getMetadata(); // Fast - only loads 5 fields +console.log(phase.phase); // 'implementation-complete' + +// Only load full context when actually needed +if (needFullHistory) { + const full = await ctx.getFullContext(); // Slower + processHistory(full.conversation_history); +} +``` + +--- + +### Optimization 2: Incremental Updates + +**Practice:** +```javascript +class IncrementalContextManager { + async updateContextField(workflowId, fieldName, value) { + const contextPath = `.claude/context/${workflowId}.json`; + + // Read current context + const json = await fs.promises.readFile(contextPath, 'utf-8'); + const context = JSON.parse(json); + + // Update only changed field + context[fieldName] = value; + context.timestamp = new Date().toISOString(); + + // Atomic write + const tempPath = `${contextPath}.tmp`; + await fs.promises.writeFile(tempPath, JSON.stringify(context, null, 2)); + await fs.promises.rename(tempPath, contextPath); + } + + async appendToArrayField(workflowId, fieldName, item) { + const contextPath = `.claude/context/${workflowId}.json`; + const json = await fs.promises.readFile(contextPath, 'utf-8'); + const context = JSON.parse(json); + + // Append to array + if (!Array.isArray(context[fieldName])) { + context[fieldName] = []; + } + context[fieldName].push(item); + context.timestamp = new Date().toISOString(); + + // Save + const tempPath = `${contextPath}.tmp`; + await fs.promises.writeFile(tempPath, JSON.stringify(context, null, 2)); + await fs.promises.rename(tempPath, contextPath); + } +} + +// Usage - faster than loading/saving entire context +const mgr = new IncrementalContextManager(); + +await mgr.updateContextField('workflow-123', 'phase', 'testing-complete'); + +await mgr.appendToArrayField('workflow-123', 'decisions', + 'Use Playwright for E2E tests' +); +``` + +--- + +## Security + +### Practice 1: No Secrets in Context + +**Rule:** Never save API keys, passwords, tokens, or sensitive data in context. + +**Implementation:** +```javascript +// ❌ BAD: Secrets in context +const context = { + workflow_id: 'deploy-prod', + database_url: 'postgresql://user:password@host:5432/db', // LEAKED! + api_key: 'sk_live_abc123...', // LEAKED! + aws_secret: 'wJalrXUtnFEMI/K7MDENG...' // LEAKED! +}; + +// ✅ GOOD: Reference secrets by ID +const context = { + workflow_id: 'deploy-prod', + secrets: { + database_url: { ref: 'env:DATABASE_URL' }, + api_key: { ref: 'doppler:STRIPE_API_KEY' }, + aws_secret: { ref: 'vault:aws/secret_key' } + } +}; + +// Agent resolves secrets at runtime +function resolveSecrets(context) { + return Object.entries(context.secrets || {}).reduce((acc, [key, value]) => { + const [provider, secretId] = value.ref.split(':'); + + switch (provider) { + case 'env': + acc[key] = process.env[secretId]; + break; + case 'doppler': + acc[key] = fetchFromDoppler(secretId); + break; + case 'vault': + acc[key] = fetchFromVault(secretId); + break; + } + + return acc; + }, {}); +} +``` + +--- + +### Practice 2: Context Access Control + +**Implementation:** +```javascript +class SecureContextManager { + constructor(workflowId, userId) { + this.workflowId = workflowId; + this.userId = userId; + } + + async saveContext(context) { + // Check write permission + if (!await this.canWrite(this.userId, this.workflowId)) { + throw new Error('Permission denied: cannot save context'); + } + + // Sanitize before saving + const sanitized = this.sanitizeContext(context); + + // Save with restricted permissions + const contextPath = this.getContextPath(); + await fs.promises.writeFile( + contextPath, + JSON.stringify(sanitized, null, 2), + { mode: 0o600 } // Owner read/write only + ); + + // Log access + await this.logAccess('write', contextPath); + } + + async loadContext() { + // Check read permission + if (!await this.canRead(this.userId, this.workflowId)) { + throw new Error('Permission denied: cannot read context'); + } + + const contextPath = this.getContextPath(); + const json = await fs.promises.readFile(contextPath, 'utf-8'); + + // Log access + await this.logAccess('read', contextPath); + + return JSON.parse(json); + } + + sanitizeContext(context) { + // Remove sensitive fields + const { password, token, secret, ...safe } = context; + + // Redact sensitive patterns + const sanitized = JSON.stringify(safe); + const redacted = sanitized + .replace(/sk_live_[a-zA-Z0-9]+/g, 'sk_live_REDACTED') + .replace(/password":\s*"[^"]+"/g, 'password": "REDACTED"'); + + return JSON.parse(redacted); + } +} +``` + +--- + +## Testing + +### Practice 1: Context Validation Tests + +**Implementation:** +```typescript +import { describe, test, expect } from 'vitest'; + +describe('Context Validation', () => { + test('should have all required fields', () => { + const context = createTestContext(); + + expect(context).toHaveProperty('version'); + expect(context).toHaveProperty('workflow_id'); + expect(context).toHaveProperty('timestamp'); + expect(context).toHaveProperty('current_agent'); + expect(context).toHaveProperty('phase'); + }); + + test('should have valid timestamp format', () => { + const context = createTestContext(); + + // Should be ISO 8601 + expect(() => { + new Date(context.timestamp); + }).not.toThrow(); + + // Should be recent (within 1 hour) + const timestamp = new Date(context.timestamp); + const now = new Date(); + const diffMs = now.getTime() - timestamp.getTime(); + expect(diffMs).toBeLessThan(3600000); // 1 hour + }); + + test('should not contain secrets', () => { + const context = createTestContext(); + const json = JSON.stringify(context); + + // Check for common secret patterns + expect(json).not.toMatch(/sk_live_[a-zA-Z0-9]+/); // Stripe + expect(json).not.toMatch(/password/i); + expect(json).not.toMatch(/api[_-]?key/i); + }); + + test('should be under size limit', () => { + const context = createTestContext(); + const size = JSON.stringify(context).length; + + expect(size).toBeLessThan(500 * 1024); // 500KB + }); +}); +``` + +--- + +### Practice 2: Workflow Integration Tests + +**Implementation:** +```typescript +describe('Workflow Integration', () => { + test('should complete sequential workflow', async () => { + const workflow = new WorkflowOrchestrator(); + + const agents = [ + new DesignAgent(), + new ImplementAgent(), + new TestAgent(), + new DeployAgent() + ]; + + const result = await workflow.executeSequential(agents); + + expect(result.phase).toBe('deployed'); + expect(result.files_modified.length).toBeGreaterThan(0); + expect(result.decisions.length).toBeGreaterThan(0); + }); + + test('should handle agent failure gracefully', async () => { + const workflow = new WorkflowOrchestrator(); + + const agents = [ + new DesignAgent(), + new FailingAgent(), // Will throw error + new TestAgent() + ]; + + await expect( + workflow.executeSequential(agents) + ).rejects.toThrow(); + + // Context should be saved up to failure point + const context = await loadContext(workflow.workflowId); + expect(context.phase).toBe('design-complete'); + expect(context.error_log).toHaveLength(1); + }); +}); +``` + +--- + +## Quick Reference + +**Context Design:** +- ✅ Keep contexts <100KB +- ✅ Be explicit, avoid assumptions +- ✅ Version your schema +- ❌ Don't embed large files +- ❌ Don't include secrets + +**Handoff Patterns:** +- Sequential: Clean, linear progression +- Parallel: Concurrent tasks with merge +- Conditional: Route based on results + +**Error Handling:** +- Save partial progress +- Create checkpoints before risky operations +- Implement rollback strategies + +**Performance:** +- Use lazy loading for metadata +- Implement incremental updates +- Cache frequently accessed contexts + +**Security:** +- Never save secrets in context +- Use secret references instead +- Implement access control +- Sanitize before saving + +**Testing:** +- Validate required fields +- Check for secrets +- Verify size limits +- Test workflow integration + +--- + +**Best Practices Version**: 1.0 +**Last Updated**: 2025-01-15 diff --git a/skills/context-management/templates/context-schema-template.json b/skills/context-management/templates/context-schema-template.json new file mode 100644 index 0000000..01391ca --- /dev/null +++ b/skills/context-management/templates/context-schema-template.json @@ -0,0 +1,332 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Multi-Agent Workflow Context Schema", + "description": "Standard schema for context persistence across agent handoffs", + "type": "object", + "required": [ + "version", + "workflow_id", + "timestamp", + "current_agent", + "phase" + ], + "properties": { + "version": { + "type": "string", + "description": "Context schema version for migration compatibility", + "pattern": "^\\d+\\.\\d+$", + "examples": ["1.0", "2.1"] + }, + + "workflow_id": { + "type": "string", + "description": "Unique identifier for this workflow instance", + "pattern": "^[a-z0-9-]+$", + "examples": ["feature-auth-api-20250115", "incident-db-crash-20250115"] + }, + + "timestamp": { + "type": "string", + "format": "date-time", + "description": "When this context was saved (ISO 8601)", + "examples": ["2025-01-15T10:30:00Z"] + }, + + "current_agent": { + "type": "string", + "description": "Agent that saved this context", + "examples": ["backend-architect", "tdd-typescript", "security-analyzer"] + }, + + "next_agent": { + "type": ["string", "null"], + "description": "Agent that should load this context next (null if workflow complete)", + "examples": ["test-generator", "devops-troubleshooter", null] + }, + + "phase": { + "type": "string", + "description": "Current phase of the workflow", + "examples": ["design", "implementation", "testing", "deployment", "complete"] + }, + + "files_modified": { + "type": "array", + "description": "List of files created or modified in this workflow", + "items": { + "type": "string", + "description": "Relative file path from project root", + "examples": ["src/api/routes/auth.ts", "docs/api/authentication.md"] + } + }, + + "decisions": { + "type": "array", + "description": "Key decisions made during workflow", + "items": { + "type": "string", + "description": "Decision with rationale", + "examples": [ + "Use JWT with 15min expiry for security", + "PostgreSQL for ACID guarantees and reliability" + ] + } + }, + + "pending_actions": { + "type": "array", + "description": "Tasks remaining for next agent or phase", + "items": { + "type": "string", + "description": "Actionable task", + "examples": [ + "Implement rate limiting on login endpoint", + "Add integration tests for OAuth flow" + ] + } + }, + + "constraints": { + "type": "array", + "description": "Requirements and limitations to respect", + "items": { + "type": "string", + "examples": [ + "Must maintain backward compatibility with v1 API", + "Response time must be < 100ms", + "Must work with existing PostgreSQL schema" + ] + } + }, + + "context_summary": { + "type": "string", + "description": "Human-readable summary of workflow state (max 500 chars)", + "maxLength": 500, + "examples": [ + "Completed API design for authentication service. JWT-based with refresh tokens. Ready for TDD implementation." + ] + }, + + "metadata": { + "type": "object", + "description": "Additional workflow-specific data", + "properties": { + "priority": { + "type": "string", + "enum": ["low", "medium", "high", "critical"], + "description": "Workflow priority level" + }, + "estimated_completion": { + "type": "string", + "format": "date-time", + "description": "Expected completion time" + }, + "owner": { + "type": "string", + "description": "Team or person responsible" + }, + "tags": { + "type": "array", + "items": { "type": "string" }, + "description": "Categorization tags", + "examples": [["backend", "authentication", "security"]] + } + } + }, + + "error_log": { + "type": "array", + "description": "Errors encountered during workflow", + "items": { + "type": "object", + "required": ["timestamp", "agent", "error"], + "properties": { + "timestamp": { + "type": "string", + "format": "date-time" + }, + "agent": { + "type": "string", + "description": "Agent that encountered error" + }, + "error": { + "type": "string", + "description": "Error message" + }, + "resolved": { + "type": "boolean", + "description": "Whether error was resolved" + } + } + } + }, + + "checkpoints": { + "type": "array", + "description": "Workflow checkpoints for rollback", + "items": { + "type": "object", + "required": ["id", "timestamp", "phase"], + "properties": { + "id": { + "type": "string", + "description": "Checkpoint identifier", + "examples": ["checkpoint-001", "pre-deployment"] + }, + "timestamp": { + "type": "string", + "format": "date-time" + }, + "phase": { + "type": "string", + "description": "Phase when checkpoint created" + }, + "context_snapshot": { + "type": "object", + "description": "Minimal context state at checkpoint" + } + } + } + }, + + "conversation_history": { + "type": "array", + "description": "Optional: Full agent conversation history (can be large)", + "items": { + "type": "object", + "required": ["timestamp", "agent", "message"], + "properties": { + "timestamp": { "type": "string", "format": "date-time" }, + "agent": { "type": "string" }, + "message": { "type": "string" }, + "message_type": { + "type": "string", + "enum": ["user_input", "agent_response", "system_message"] + } + } + } + }, + + "test_results": { + "type": "object", + "description": "Test execution results (if applicable)", + "properties": { + "total": { "type": "integer", "minimum": 0 }, + "passing": { "type": "integer", "minimum": 0 }, + "failing": { "type": "integer", "minimum": 0 }, + "coverage": { + "type": "object", + "properties": { + "line": { "type": "number", "minimum": 0, "maximum": 100 }, + "branch": { "type": "number", "minimum": 0, "maximum": 100 }, + "function": { "type": "number", "minimum": 0, "maximum": 100 } + } + } + } + }, + + "deployment_info": { + "type": "object", + "description": "Deployment details (if applicable)", + "properties": { + "environment": { + "type": "string", + "enum": ["development", "staging", "production"] + }, + "deployed_at": { + "type": "string", + "format": "date-time" + }, + "deployment_url": { + "type": "string", + "format": "uri" + }, + "rollback_available": { + "type": "boolean" + } + } + } + }, + + "examples": [ + { + "version": "1.0", + "workflow_id": "feature-user-prefs-20250115", + "timestamp": "2025-01-15T10:30:00Z", + "current_agent": "backend-architect", + "next_agent": "tdd-typescript", + "phase": "design-complete", + + "files_modified": [ + "docs/api/user-preferences.md", + "docs/architecture/decisions/adr-012.md" + ], + + "decisions": [ + "Use JSONB for flexible preferences storage", + "Implement both PUT and PATCH for updates" + ], + + "pending_actions": [ + "Implement API endpoints with TDD", + "Create database migration", + "Add input validation" + ], + + "constraints": [ + "Must maintain backward compatibility", + "Performance: GET < 50ms" + ], + + "context_summary": "API design complete. Data model uses JSONB. Three endpoints planned (GET/PUT/PATCH). Ready for implementation.", + + "metadata": { + "priority": "high", + "owner": "backend-team", + "tags": ["api", "user-preferences", "backend"] + } + }, + + { + "version": "1.0", + "workflow_id": "incident-db-crash-20250115", + "timestamp": "2025-01-15T03:15:00Z", + "current_agent": "incident-responder", + "next_agent": "devops-troubleshooter", + "phase": "investigation-complete", + + "files_modified": [ + "runbooks/database-recovery.md", + "incidents/2025-01-15-db-crash.md" + ], + + "decisions": [ + "Root cause: Out of memory due to connection leak", + "Immediate fix: Restart with connection pool limit", + "Long-term: Implement connection timeout monitoring" + ], + + "pending_actions": [ + "Deploy connection pool fix", + "Set up monitoring alerts", + "Schedule postmortem meeting" + ], + + "error_log": [ + { + "timestamp": "2025-01-15T03:00:00Z", + "agent": "incident-responder", + "error": "Database connection pool exhausted", + "resolved": true + } + ], + + "metadata": { + "priority": "critical", + "owner": "sre-team", + "tags": ["incident", "database", "production"] + } + } + ] +}