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!