Test
25a4787022
Task 1.1 COMPLETE ✅ Core type definitions for routing workflows: - WorkflowSpec: One-time workflow specification - CronWorkflowSpec: Scheduled workflow specification - State: Individual step in workflow (Task/Pass/Fail) - RetryPolicy: Retry configuration with backoff - CatchClause: Error handling - ExecutionContext: Tracks state during execution - ActivityMetadata: Describes activity capabilities - Supporting types: PollParams, Heartbeat, Result All types support JSON marshaling/unmarshaling. 8 unit tests covering complex scenarios (9/9 PASS). Acceptance criteria met: ✅ All types compile without errors ✅ JSON marshaling/unmarshaling works correctly ✅ Unit tests pass (complex workflow examples) ✅ Ready for next phase (Knowledge Base) Effort: 2 hours Files: internal/routing/types.go (159 lines) internal/routing/types_test.go (286 lines)
279 lines
9.6 KiB
Plaintext
279 lines
9.6 KiB
Plaintext
================================================================================
|
|
POIMEN ROUTING WORKFLOW - COMPLETE SPECIFICATION SUMMARY
|
|
================================================================================
|
|
|
|
STATUS: ✅ READY FOR IMPLEMENTATION
|
|
|
|
Created: August 31, 2025
|
|
Total Documentation: 3,856 lines across 5 files
|
|
Implementation Effort: 60-70 hours (3-4 weeks, 1-2 engineers)
|
|
|
|
================================================================================
|
|
📚 DOCUMENTATION CREATED
|
|
================================================================================
|
|
|
|
1. ROUTING_WORKFLOW_SPEC.md (1,198 lines, 32KB)
|
|
├─ Architecture overview
|
|
├─ ActivityKnowledgeBase.json format
|
|
├─ llm-router Activity (intelligent generator)
|
|
├─ RoutingWorkflow (generic executor)
|
|
├─ Go type definitions (copy-paste ready)
|
|
├─ 7 implementation architecture sections
|
|
├─ CronWorkflowSpec (scheduled workflows)
|
|
├─ Execution flow with examples
|
|
├─ Validation rules
|
|
└─ Complete reference
|
|
|
|
2. IMPLEMENTATION_TASKS.md (1,158 lines, 27KB)
|
|
├─ Phase 1: Foundation (8-10 hours, 4 tasks)
|
|
├─ Phase 2: LLM-Router (12-15 hours, 5 tasks)
|
|
├─ Phase 3: RoutingWorkflow (15-18 hours, 6 tasks)
|
|
├─ Phase 4: API/CLI (12-15 hours, 4 tasks)
|
|
├─ Phase 5: Testing (8-12 hours, 4 tasks)
|
|
├─ Phase 6: Documentation (5-8 hours, 4 tasks)
|
|
├─ Total: 27 specific, actionable tasks
|
|
├─ Each with: effort estimate, acceptance criteria, dependencies
|
|
├─ Timeline: 3-4 weeks
|
|
├─ Resource allocation: 1-2 engineers
|
|
├─ Blockers to watch
|
|
└─ Success criteria per phase
|
|
|
|
3. CRON_JOBS_QUICK_REFERENCE.md (252 lines, 5.7KB)
|
|
├─ Cron syntax examples (daily, hourly, weekly, etc)
|
|
├─ How llm-router detects scheduled jobs
|
|
├─ Execution tracking
|
|
├─ Proposed API endpoints
|
|
├─ One-time vs Cron comparison table
|
|
└─ Quick lookup reference
|
|
|
|
4. DESIGN_MASTER_REVIEW.md (888 lines, 25KB)
|
|
├─ Executive summary for stakeholders
|
|
├─ Problem/solution statement
|
|
├─ 3 patterns (Sequential, Await-Task-Complete, Retry)
|
|
├─ 3 entry points (CLI, API, Legacy)
|
|
├─ Before/after comparison
|
|
├─ Implementation timeline
|
|
├─ KMSvc questions (Q1-Q6)
|
|
├─ Risks & mitigations
|
|
├─ Success criteria
|
|
├─ Approval checklist
|
|
└─ Complete example workflows
|
|
|
|
5. README_IMPLEMENTATION.md (360 lines, 9KB)
|
|
├─ Quick start guide
|
|
├─ Documentation structure explanation
|
|
├─ Week-by-week breakdown
|
|
├─ How to start today
|
|
├─ Success criteria per phase
|
|
├─ Effort summary table
|
|
├─ Key features matrix
|
|
├─ Tips for success
|
|
├─ Learning resources
|
|
└─ Decision maker's checklist
|
|
|
|
================================================================================
|
|
🎯 THE SYSTEM ARCHITECTURE
|
|
================================================================================
|
|
|
|
User Input (one-time or scheduled):
|
|
"Analyze repo for security and quality"
|
|
or
|
|
"Scan all repos daily at 2 AM"
|
|
|
|
↓
|
|
|
|
[llm-router Activity] - Intelligent Workflow Generator
|
|
├─ Reads: ActivityKnowledgeBase.json (metadata about activities)
|
|
├─ Uses LLM to understand intent
|
|
├─ Selects activities: Clone → Analyze → SecurityScan → Combine → Notify
|
|
├─ Orders by dependencies
|
|
├─ Decides timeout for each (from knowledge base)
|
|
├─ Decides retry policy (from isFlaky flag)
|
|
├─ Chains parameters (JSONPath: ${Clone.output.path})
|
|
├─ Detects if scheduled (cron)
|
|
└─ Generates: WorkflowSpec or CronWorkflowSpec (JSON)
|
|
|
|
↓
|
|
|
|
[RoutingWorkflow] - Generic Executor
|
|
├─ Takes JSON spec from llm-router
|
|
├─ Executes states in order
|
|
├─ Respects timeout/retry for each activity
|
|
├─ Handles errors with catch blocks
|
|
└─ Returns results
|
|
|
|
↓
|
|
|
|
[Temporal] - Distributed Workflow Engine
|
|
├─ For one-time: Executes immediately
|
|
├─ For cron: Schedules and runs on schedule
|
|
├─ Provides durability (replay guarantee)
|
|
├─ Tracks execution history
|
|
└─ Handles retries automatically
|
|
|
|
↓
|
|
|
|
[Results] - Final Output
|
|
├─ Execution history
|
|
├─ Step-by-step results
|
|
├─ Performance metrics
|
|
└─ Status updates
|
|
|
|
================================================================================
|
|
✨ KEY FEATURES
|
|
================================================================================
|
|
|
|
✅ One-time workflows (instant execution via API/CLI)
|
|
✅ Scheduled workflows (cron jobs with full history)
|
|
✅ Intelligent routing (LLM decides what to run)
|
|
✅ Smart timeouts (from ActivityKnowledgeBase.json)
|
|
✅ Smart retries (3x for flaky, 1x for stable)
|
|
✅ Error handling (catch blocks for graceful failures)
|
|
✅ Parameter chaining (JSONPath: ${step.output.field})
|
|
✅ Parallel execution (multiple branches)
|
|
✅ Temporal durability (automatic replay on failure)
|
|
✅ HTTP API (for programmatic access)
|
|
✅ CLI (for command-line access)
|
|
✅ Execution tracking (full history)
|
|
✅ Backward compatible (legacy CLI still works)
|
|
|
|
================================================================================
|
|
📊 IMPLEMENTATION BREAKDOWN
|
|
================================================================================
|
|
|
|
PHASE 1: Foundation (8-10 hours)
|
|
Task 1.1: Go types (2h)
|
|
Task 1.2: ActivityKnowledgeBase.json (3h)
|
|
Task 1.3: KB loader (2h)
|
|
Task 1.4: Validator (3h)
|
|
→ Deliverable: Core data structures
|
|
|
|
PHASE 2: LLM-Router (12-15 hours)
|
|
Task 2.1: JSONPath resolver (3h)
|
|
Task 2.2: Activity skeleton (2h)
|
|
Task 2.3: LLM intent analysis (5h) ⚠️ HIGHEST RISK
|
|
Task 2.4: Spec builder (4h)
|
|
Task 2.5: Cron builder (2h)
|
|
→ Deliverable: Intelligent workflow generation
|
|
|
|
PHASE 3: RoutingWorkflow (15-18 hours)
|
|
Task 3.1: Executor dispatcher (1h)
|
|
Task 3.2: Task executor (2h)
|
|
Task 3.3: Pass/Fail executors (1h)
|
|
Task 3.4: Main workflow engine (4h)
|
|
Task 3.5: Register in worker (1h)
|
|
Task 3.6: Helper functions (2h)
|
|
→ Deliverable: Generic workflow executor
|
|
|
|
PHASE 4: API/CLI (12-15 hours)
|
|
Task 4.1: API handlers (4h)
|
|
Task 4.2: CLI commands (5h)
|
|
Task 4.3: Server bootstrap (2h)
|
|
Task 4.4: Validation (2h)
|
|
→ Deliverable: HTTP API + CLI
|
|
|
|
PHASE 5: Testing (8-12 hours)
|
|
Task 5.1: Unit tests (3h)
|
|
Task 5.2: Integration tests (4h)
|
|
Task 5.3: E2E tests (4h)
|
|
Task 5.4: Load tests (2h)
|
|
→ Deliverable: >90% coverage, all scenarios pass
|
|
|
|
PHASE 6: Documentation (5-8 hours)
|
|
Task 6.1: API documentation (2h)
|
|
Task 6.2: CLI documentation (1h)
|
|
Task 6.3: Deployment guide (2h)
|
|
Task 6.4: User guide & examples (2h)
|
|
→ Deliverable: Complete documentation
|
|
|
|
TOTAL: 60-70 hours (3-4 weeks, 1-2 engineers)
|
|
|
|
================================================================================
|
|
🚀 HOW TO START TODAY
|
|
================================================================================
|
|
|
|
Step 1: Review Documentation (1-2 hours)
|
|
→ Read ROUTING_WORKFLOW_SPEC.md (understand design)
|
|
→ Read IMPLEMENTATION_TASKS.md (understand tasks)
|
|
→ Read README_IMPLEMENTATION.md (quick start)
|
|
|
|
Step 2: Assign Tasks (30 minutes)
|
|
→ Engineer 1: Tasks 1.1-1.4, 2.1-2.5, 3.1-3.6
|
|
→ Engineer 2: Tasks 4.1-4.4, 5.1-5.4, 6.1-6.4
|
|
|
|
Step 3: Begin Implementation (immediately)
|
|
→ Start with Task 1.1: Create Go types (types.go)
|
|
→ 2 hours to completion
|
|
→ Then proceed to Task 1.2 (ActivityKnowledgeBase.json)
|
|
|
|
Step 4: Daily Sync
|
|
→ Report progress
|
|
→ Unblock dependencies
|
|
→ Adjust timeline if needed
|
|
|
|
================================================================================
|
|
✅ SUCCESS CRITERIA
|
|
================================================================================
|
|
|
|
Phase 1: All types compile, KB loads, validator works
|
|
Phase 2: llm-router generates valid specs, detects cron
|
|
Phase 3: RoutingWorkflow executes any spec, handles errors
|
|
Phase 4: HTTP API + CLI fully functional
|
|
Phase 5: >90% code coverage, all tests pass
|
|
Phase 6: Complete documentation, ready to ship
|
|
|
|
✅ DONE WHEN:
|
|
- All code compiles without warnings
|
|
- All tests pass (unit, integration, E2E, load)
|
|
- Documentation complete
|
|
- Can deploy to Kubernetes
|
|
- Can submit workflows from API/CLI
|
|
- Can create cron jobs
|
|
- Performance targets met (<200ms submit, <100ms poll)
|
|
|
|
================================================================================
|
|
📁 FILE LOCATIONS
|
|
================================================================================
|
|
|
|
Core Specification:
|
|
~/workplace/Poimen/workflows/ROUTING_WORKFLOW_SPEC.md
|
|
|
|
Task Breakdown:
|
|
~/workplace/Poimen/workflows/IMPLEMENTATION_TASKS.md
|
|
|
|
Cron Reference:
|
|
~/workplace/Poimen/workflows/CRON_JOBS_QUICK_REFERENCE.md
|
|
|
|
Stakeholder Review:
|
|
~/workplace/Poimen/workflows/DESIGN_MASTER_REVIEW.md
|
|
|
|
Quick Start Guide:
|
|
~/workplace/Poimen/workflows/README_IMPLEMENTATION.md
|
|
|
|
This Summary:
|
|
~/workplace/Poimen/workflows/COMPLETE_SPECIFICATION_SUMMARY.txt
|
|
|
|
================================================================================
|
|
🎓 RECOMMENDATION
|
|
================================================================================
|
|
|
|
This specification is:
|
|
✅ Complete - covers all aspects of the system
|
|
✅ Implementable - all code patterns shown
|
|
✅ Testable - success criteria clearly defined
|
|
✅ Maintainable - well-documented
|
|
✅ Scalable - designed for production use
|
|
|
|
NEXT STEPS:
|
|
1. Get stakeholder approval (use DESIGN_MASTER_REVIEW.md)
|
|
2. Assign engineers (use IMPLEMENTATION_TASKS.md)
|
|
3. Start Phase 1, Task 1.1 today
|
|
4. Daily standup on progress
|
|
5. Gate each phase before moving to next
|
|
|
|
TIMELINE: 3-4 weeks to complete implementation ⏱️
|
|
|
|
STATUS: 🟢 READY TO BUILD
|
|
|
|
================================================================================
|