poimen-workflows/README_IMPLEMENTATION.md

Poimen Routing Workflow - Complete Implementation Guide

📚 DOCUMENTATION STRUCTURE

You now have 4 complete documents that form a complete specification:

1. ROUTING_WORKFLOW_SPEC.md (30+ KB)

The Technical Specification - Everything about the system design

Contains:

• ActivityKnowledgeBase.json format
• llm-router Activity (intelligent workflow generator)
• RoutingWorkflow (generic executor)
• Go type definitions (copy-paste ready)
• Implementation architecture
• State types (Task, Pass, Fail)
• CronWorkflowSpec (scheduled workflows)
• Execution flow examples
• Cron syntax reference

When to use: Building the system, understanding architecture

---

2. CRON_JOBS_QUICK_REFERENCE.md (4 KB)

Quick Reference for Cron Jobs

Contains:

• Cron syntax examples
• How llm-router detects scheduled jobs
• Execution tracking
• API endpoints for cron
• One-time vs Cron comparison

When to use: Testing cron features, quick lookup

---

3. IMPLEMENTATION_TASKS.md (30+ KB)

The Complete Task Breakdown - What to build, in what order

Contains:

• 27 specific, actionable tasks
• Effort estimates per task (2-5 hours each)
• Acceptance criteria for each task
• Dependencies between tasks
• Timeline (3 weeks, 1-2 engineers)
• Resource allocation
• Blockers to watch
• Success criteria

Structure:

Phase 1: Foundation (8-10 hours)
  ├─ Task 1.1: Types
  ├─ Task 1.2: Knowledge Base
  ├─ Task 1.3: KB Loader
  └─ Task 1.4: Validator

Phase 2: LLM-Router (12-15 hours)
  ├─ Task 2.1: JSONPath Resolver
  ├─ Task 2.2: Activity Skeleton
  ├─ Task 2.3: Intent Analysis
  ├─ Task 2.4: Spec Builder
  └─ Task 2.5: Cron Builder

Phase 3: RoutingWorkflow (15-18 hours)
  ├─ Task 3.1-3.6: Executors & State Machine

Phase 4: API/CLI (12-15 hours)
  ├─ Task 4.1-4.4: Handlers, Commands, Validation

Phase 5: Testing (8-12 hours)
  ├─ Task 5.1-5.4: Unit, Integration, E2E, Load tests

Phase 6: Docs & Deployment (5-8 hours)
  ├─ Task 6.1-6.4: API.md, CLI.md, Deployment.md, User Guide

When to use: Planning sprints, assigning work, tracking progress

---

4. DESIGN_MASTER_REVIEW.md (25+ KB)

Executive Summary for Stakeholders

Contains:

• Problem/solution
• 3 patterns (Sequential, Await-Task-Complete, Retry)
• 3 entry points (CLI, API, Legacy)
• Phases 1-5 (52-58 hours)
• KMSvc questions (Q1-Q6)
• Risks & mitigations
• Success criteria
• Approval checklist

When to use: Stakeholder review, getting buy-in, architecture approval

---

🎯 THE ARCHITECTURE AT A GLANCE

User Message: "Analyze repo for security and quality every day at 2 AM"
  ↓
[llm-router Activity]
  Reads: ActivityKnowledgeBase.json
  Uses LLM to understand intent
  Decides: Clone → AnalyzeCode → SecurityScan → Combine → Notify
  Decides timeouts, retries from knowledge base
  Detects schedule: "0 2 * * *"
  Generates: CronWorkflowSpec
  ↓
[RoutingWorkflow] (Generic Executor)
  Registers with Temporal cron: "0 2 * * *"
  Every day at 2 AM:
    1. Clone repo
    2. Analyze code (timeout 10m, retry 3x if flaky)
    3. Security scan (timeout 15m, retry 2x)
    4. Combine results
    5. Send notification
  Tracks each execution
  ↓
[Results]
  Full execution history
  Can check status anytime

---

✨ KEY FEATURES

Feature	Status	Docs	Tasks
One-time workflows	✅	ROUTING_WORKFLOW_SPEC.md	2.1-2.4, 3.x, 4.x
Scheduled workflows (cron)	✅	CRON_JOBS_QUICK_REFERENCE.md	2.5, 3.4, 5.x
Intelligent routing (LLM)	✅	ROUTING_WORKFLOW_SPEC.md Part 2	2.x
Smart timeouts	✅	ROUTING_WORKFLOW_SPEC.md	1.2, 2.4
Smart retries	✅	ROUTING_WORKFLOW_SPEC.md	1.2, 2.4
Error handling	✅	ROUTING_WORKFLOW_SPEC.md	3.4
Parameter chaining	✅	ROUTING_WORKFLOW_SPEC.md	2.1
Temporal durability	✅	ROUTING_WORKFLOW_SPEC.md	3.4
HTTP API	✅	ROUTING_WORKFLOW_SPEC.md	4.1-4.4
CLI	✅	CRON_JOBS_QUICK_REFERENCE.md	4.2
Execution tracking	✅	CRON_JOBS_QUICK_REFERENCE.md	5.x

---

📋 QUICK START FOR IMPLEMENTATION

Week 1: Foundation + LLM-Router

Day 1-2 (Mon-Tue):
  Task 1.1: Go types (2h)
  Task 1.2: Knowledge base JSON (3h)
  Task 1.3: KB loader (2h)
  Task 1.4: Validator (3h)
  → Deliverable: Core data structures working

Day 3-5 (Wed-Fri):
  Task 2.1: JSONPath resolver (3h)
  Task 2.2: Activity skeleton (2h)
  Task 2.3: LLM intent analysis (5h)
  Task 2.4: Spec builder (4h)
  Task 2.5: Cron builder (2h)
  → Deliverable: llm-router generates valid specs

Week 2: RoutingWorkflow + API/CLI

Day 1-3 (Mon-Wed):
  Task 3.1-3.6: RoutingWorkflow & executors (15-18h)
  Task 3.5: Register in worker
  → Deliverable: Workflows execute, can submit via API

Day 4-5 (Thu-Fri):
  Task 4.1: API handlers (4h)
  Task 4.2: CLI commands (5h)
  Task 4.3: Server bootstrap (2h)
  Task 4.4: Validation (2h)
  → Deliverable: Full HTTP API + CLI working

Week 3: Testing + Documentation

Day 1-3 (Mon-Wed):
  Task 5.1-5.4: All tests (8-12h)
  → Deliverable: >90% coverage, all tests pass

Day 4-5 (Thu-Fri):
  Task 6.1-6.4: Documentation (5-8h)
  → Deliverable: Complete docs, ready to ship

---

🚀 HOW TO START TODAY

Step 1: Read & Understand (1-2 hours)

1. Read ROUTING_WORKFLOW_SPEC.md (main spec)
2. Read IMPLEMENTATION_TASKS.md (what to build)
3. Scan CRON_JOBS_QUICK_REFERENCE.md (understand cron)

Step 2: Assign Tasks

1. Engineer 1: Tasks 1.1-1.4, 2.1-2.5, 3.1-3.6
2. Engineer 2: Tasks 4.1-4.4, 5.1-5.4, 6.1-6.4

Step 3: Start Building

1. Begin with Task 1.1 (types.go)
2. Follow dependency order
3. Daily sync on blockers

Step 4: Gate Each Phase

• Phase 1 done? → Start Phase 2
• Phase 2 done? → Start Phase 3
• etc.

---

📊 EFFORT SUMMARY

Phase	Hours	Duration	Parallel
Phase 1: Foundation	8-10	Mon-Tue	No
Phase 2: LLM-Router	12-15	Wed-Fri + Mon	No
Phase 3: RoutingWorkflow	15-18	Tue-Thu	Can overlap w/ Phase 4
Phase 4: API/CLI	12-15	Fri-Tue	Can overlap w/ Phase 3
Phase 5: Testing	8-12	Wed-Fri	Sequential
Phase 6: Docs	5-8	Fri-Mon	Parallel w/ Phase 5
TOTAL	60-70	3-4 weeks	2 engineers

---

✅ SUCCESS CRITERIA

Phase 1 Complete:

• All types compile
• Knowledge base loads
• Validator catches errors
• All unit tests pass

Phase 2 Complete:

• llm-router generates valid specs
• JSONPath resolution works
• Cron detection works
• Integration tests pass

Phase 3 Complete:

• RoutingWorkflow executes any spec
• Error handling works
• State machine flow correct
• Registered in worker

Phase 4 Complete:

• HTTP API working (all endpoints)
• CLI working (all commands)
• Input validation
• Can submit and check status

Phase 5 Complete:

• 90% code coverage

• All scenarios pass
• Performance targets met
• No flaky tests

Phase 6 Complete:

• API documentation complete
• CLI documentation complete
• Deployment guide complete
• User guide with examples

---

🔗 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

This README:
  ~/workplace/Poimen/workflows/README_IMPLEMENTATION.md

---

💡 TIPS FOR SUCCESS

1. Start with types (Task 1.1)

   • Everything depends on these
   • Make them flexible
   • Good JSON schema helps

2. Knowledge base is critical (Task 1.2)

   • LLM decisions are based on this
   • Make it comprehensive
   • Document each activity well

3. Test llm-router early (Task 2.3)

   • This is highest risk
   • Test with real LLM calls
   • Validate output quality

4. RoutingWorkflow is the heart (Task 3.4)

   • Make sure state machine is solid
   • Test error paths thoroughly
   • Performance matters

5. API/CLI can be simple (Tasks 4.x)

   • Just thin wrappers
   • Focus on DX (developer experience)
   • Good error messages

6. Test everything (Phase 5)

   • Unit tests catch bugs early
   • Integration tests find edge cases
   • E2E tests validate full flow
   • Load tests validate performance

---

🎓 LEARNING RESOURCES

• Temporal: https://docs.temporal.io/
• Cron syntax: https://crontab.guru/
• JSONPath: https://goessner.net/articles/JsonPath/
• Go workflow patterns: https://golang.org/pkg/workflow

---

📞 DECISION MAKER'S CHECKLIST

Before starting implementation:

• Do we have LLM access? (for llm-router)
• Is Temporal deployed? (task queue "poimen-taskqueue")
• Are activities registered? (CloneRepoActivity, etc)
• Do we have memory service? (for LLM calls)
• Team aligned on architecture?
• Timeline acceptable? (3-4 weeks)
• Resources allocated? (2 engineers)

All yes? → Ready to build! 🚀

---

This is a complete, implementable specification. Start with Phase 1, Task 1.1 today!