jordan/rdev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5ac9af018a
rdev/docs/legal/patent-figures.md
jordan d69da6d627 feat: add structured logging infrastructure and SDLC extensions 
Major changes:
- Add internal/logging package with field constants, context propagation,
  sensitive data auto-redaction, and per-component log levels
- Add worker timeout constants (TimeoutQuickOp, TimeoutHealthCheck, etc.)
- Extend SDLC with callback handlers, generate endpoints, and executor
- Add new cookbook trees for aeries and slackpath progression
- Add skeleton templates for queue, realtime, and microservices
- Add worker component template with async job processing
- Refactor services and handlers to use new logging infrastructure
- Split component.go into component_infra.go and component_listing.go

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-04 22:56:04 -07:00

741 lines
76 KiB
Markdown
Raw Blame History

# rdev Patent Figures
**Subject:** System and Method for Orchestrating AI Agents Through Deterministic Workflow Classification
**Date:** 2026-02-04
These figure descriptions are intended for a patent draftsperson to render as formal patent drawings.
---
## FIG. 1: System Architecture Block Diagram
**Purpose:** High-level view of the invention's components and data flow.
**Elements:**
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌──────────────────┐ │
│ │ External Bot │ │
│ │ (Slack/Discord) │ │
│ └────────┬─────────┘ │
│ │ (1) Feature Request │
│ │ via API │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ rdev ORCHESTRATOR API (102) │ │
│ │ ┌────────────────┐ ┌──────────────┐ │ │
│ │ │ SDLC Service │ │ Work Queue │ │ │
│ │ │ (Library Mode)│ │ Manager │ │ │
│ │ └───────┬────────┘ └──────┬───────┘ │ │
│ └──────────┼─────────────────┼─────────┘ │
│ │ │ │
│ │ (2) Evaluate │ (3) Enqueue │
│ │ Classifier │ Task │
│ ▼ ▼ │
│ ┌──────────────────────────────────────┐ ┌────────────────────────────────┐ │
│ │ DETERMINISTIC CLASSIFIER (104) │ │ WORK QUEUE (106) │ │
│ │ ┌─────────────────────────────┐ │ │ PostgreSQL with Row Locking │ │
│ │ │ Rule 0: invalid_phase │ │ │ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Rule 1: draft_needs_spec │ │ │ │ Task 1 │ │ Task 2 │ ... │ │
│ │ │ Rule 2: spec_awaiting_appr │ │ │ └─────────┘ └─────────┘ │ │
│ │ │ ... │ │ └────────────────┬───────────────┘ │
│ │ │ Rule 23: feature_complete │ │ │ │
│ │ └─────────────────────────────┘ │ │ │
│ └──────────────────┬───────────────────┘ │ │
│ │ │ │
│ │ (4) Action Output │ (5) Dequeue │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ PER-PROJECT WORKER (108) │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ EXECUTOR REGISTRY (110) │ │ │
│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │
│ │ │ │ Build │ │ Verify │ │ SDLC │ │ │ │
│ │ │ │ Executor │ │ Executor │ │ Executor │ │ │ │
│ │ │ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │ │ │
│ │ └──────────┼────────────────┼────────────────┼─────────────────────────┘ │ │
│ └──────────────┼────────────────┼────────────────┼─────────────────────────────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ (6) kubectl exec │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ KUBERNETES POD (112) │ │
│ │ Label: rdev.orchard9.ai/project=true │ │
│ │ │ │
│ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │
│ │ │ AI AGENT (114) │ │ SDLC CLI (116) │ │ │
│ │ │ (Claude Code / │ │ Same classifier │ │ │
│ │ │ OpenCode) │ │ as library mode │ │ │
│ │ └──────────┬──────────┘ └──────────┬──────────┘ │ │
│ │ │ │ │ │
│ │ │ (7) Query │ │ │
│ │ │ Status │ │ │
│ │ └────────────────────────►│ │ │
│ │ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ GIT REPOSITORY (118) │ │ │
│ │ │ .sdlc/ │ │ │
│ │ │ ├── feature.yaml (Phase state) │ │ │
│ │ │ ├── spec.yaml (Specification) │ │ │
│ │ │ ├── plan.yaml (Task breakdown) │ │ │
│ │ │ └── tasks/ (Implementation records) │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
**Reference Numerals:**
- 100: System for orchestrating AI agents through deterministic classification
- 102: rdev orchestrator API
- 104: Deterministic classifier with priority-ordered rules
- 106: Work queue with PostgreSQL row locking
- 108: Per-project worker
- 110: Executor registry (build, verify, SDLC)
- 112: Kubernetes pod (isolated execution environment)
- 114: AI agent (Claude Code, OpenCode)
- 116: SDLC CLI (dual-execution module)
- 118: Git repository with SDLC state
**Description:**
FIG. 1 illustrates a system (100) for orchestrating AI agents through deterministic classification. External bots submit feature requests through the orchestrator API (102). The deterministic classifier (104) evaluates current state using priority-ordered rules and outputs specific actions. Tasks are enqueued in the work queue (106) with PostgreSQL row locking. Per-project workers (108) dequeue tasks and route them to the appropriate executor (110). Executors invoke commands in isolated Kubernetes pods (112) via kubectl exec. Inside the pod, the AI agent (114) queries the SDLC CLI (116) to determine its next action. The CLI uses the same classifier logic as the library mode, ensuring consistent behavior. State is persisted in the git repository (118) as YAML files.
---
## FIG. 2: Phase State Machine
**Purpose:** The 10-phase software development lifecycle with transition requirements.
**Elements:**
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ PHASE STATE MACHINE (200) │
│ │
│ ┌──────────┐ Approved ┌───────────┐ Approved ┌──────────┐ │
│ │ │ Spec │ │ Plan │ │ │
│ │ DRAFT │─────────────────►│ SPECIFIED │─────────────────►│ PLANNED │ │
│ │ (202) │ │ (204) │ │ (206) │ │
│ └──────────┘ └───────────┘ └────┬─────┘ │
│ │ │ │
│ │ Requires: │ │
│ │ - Specification artifact │ All tasks │
│ │ │ approved │
│ │ ▼ │
│ ┌────┴─────────────────────────────────────────────────────────────────┐ │
│ │ ARTIFACT REQUIREMENTS PER PHASE: │ │
│ │ │ │
│ │ DRAFT → SPECIFIED: Approved specification document │ │
│ │ SPECIFIED → PLANNED: Approved plan with task breakdown │ │
│ │ PLANNED → READY: All task approvals │ │
│ │ READY → IMPLEMENTATION: Automatic (no artifacts) │ │
│ │ IMPLEMENTATION → REVIEW: All tasks implemented │ │
│ │ REVIEW → AUDIT: Code review approved │ │
│ │ AUDIT → QA: Security audit passed │ │
│ │ QA → MERGE: QA tests passed │ │
│ │ MERGE → RELEASED: Merge to main complete │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────┐ ┌───────────┐ ┌──────────┐ │
│ │ │ Auto │ │ All tasks │ │ │
│ │ READY │─────────────────►│IMPLEMENTA-│─────────────────►│ REVIEW │ │
│ │ (208) │ │TION (210) │ implemented │ (212) │ │
│ └──────────┘ └───────────┘ └────┬─────┘ │
│ │ │
│ │ Review │
│ │ approved │
│ ▼ │
│ ┌──────────┐ Merge ┌───────────┐ QA ┌──────────┐ │
│ │ │ complete │ │ passed │ │ │
│ │ RELEASED │◄─────────────────│ MERGE │◄─────────────────│ QA │ │
│ │ (218) │ │ (216) │ │ (214) │ │
│ └──────────┘ └───────────┘ └────┬─────┘ │
│ ▲ │ │
│ │ │ Audit │
│ │ │ passed │
│ │ ┌───────────┐ │ │
│ │ │ │◄──────────────────┘ │
│ └──────────────────────────────│ AUDIT │ │
│ │ (220) │ │
│ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
**Reference Numerals:**
- 200: Phase state machine
- 202: Draft phase
- 204: Specified phase
- 206: Planned phase
- 208: Ready phase
- 210: Implementation phase
- 212: Review phase
- 214: QA phase
- 216: Merge phase
- 218: Released phase
- 220: Audit phase
**Description:**
FIG. 2 illustrates the phase state machine (200) comprising ten development phases. Features begin in DRAFT (202) and progress through SPECIFIED (204), PLANNED (206), READY (208), IMPLEMENTATION (210), REVIEW (212), AUDIT (220), QA (214), MERGE (216), and finally RELEASED (218). Each transition has specific artifact requirements. The classifier evaluates which phase transitions are valid based on artifact presence and approval status.
---
## FIG. 3: Deterministic Classifier Architecture
**Purpose:** How the classifier evaluates rules and produces action outputs.
**Elements:**
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ CLASSIFIER INPUT (302): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ FeatureState │ │
│ │ ┌─────────────────┐ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ Phase: "impl" │ │ Artifacts: │ │ │
│ │ │ │ │ spec: {approved: true} │ │ │
│ │ │ │ │ plan: {approved: true} │ │ │
│ │ │ │ │ task_0: {implemented: true} │ │ │
│ │ │ │ │ task_1: {implemented: false} ◄── Not done │ │ │
│ │ │ │ │ task_2: {implemented: false} │ │ │
│ │ └─────────────────┘ └─────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Evaluate │
│ ▼ │
│ CLASSIFIER ENGINE (304): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Rule 0 (Priority 0): invalid_phase │ │ │
│ │ │ Condition: !isValidPhase(state.Phase) │ │ │
│ │ │ Match: NO ──────────────────────────────────────────────────► NEXT │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Rule 1 (Priority 1): draft_needs_spec │ │ │
│ │ │ Condition: phase == "draft" && !hasArtifact("spec") │ │ │
│ │ │ Match: NO ──────────────────────────────────────────────────► NEXT │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ ...rules 2-9 evaluated... │ │ │
│ │ │ Match: NO ──────────────────────────────────────────────────► NEXT │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Rule 10 (Priority 10): implement_next_task ◄────┼───┼─┐ │
│ │ │ Condition: phase == "impl" && hasUnimplementedTasks() │ │ │ │
│ │ │ Match: YES ─────────────────────────────────────────────────────────┼───┼─┘ │
│ │ │ │ │ │
│ │ │ Action Output: │ │ │
│ │ │ Type: IMPLEMENT_TASK │ │ │
│ │ │ Payload: {task_index: 1} │ │ │
│ │ │ Instruction: "Implement task 1: Add API endpoint" │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ (Rules 11-23 NOT evaluated due to early return) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Return first match │
│ ▼ │
│ CLASSIFIER OUTPUT (306): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ Action { │ │
│ │ type: "IMPLEMENT_TASK", │ │
│ │ payload: { task_index: 1 }, │ │
│ │ instruction: "Implement task 1: Add API endpoint" │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Provided to AI agent │
│ ▼ │
│ AI AGENT EXECUTES INSTRUCTION (NOT decides what to do) │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
**Reference Numerals:**
- 302: Classifier input (feature state)
- 304: Classifier engine with priority-ordered rules
- 306: Classifier output (action)
**Description:**
FIG. 3 illustrates the deterministic classifier architecture. The classifier receives feature state as input (302), including current phase and artifact status. The classifier engine (304) evaluates rules in strict priority order. Each rule has a condition; the first matching rule produces the output. In this example, rules 0-9 do not match, but rule 10 (implement_next_task) matches because the phase is "implementation" and task 1 is not yet implemented. The classifier returns the action output (306), which specifies exactly what the AI agent should do next. The agent executes this instruction rather than deciding its own action.
---
## FIG. 4: Dual-Execution Architecture
**Purpose:** How the same SDLC code runs as both CLI and library.
**Elements:**
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ SHARED CORE (402): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ internal/sdlc/ │ │
│ │ ├── classifier.go # Classification rules │ │
│ │ ├── rules.go # 24 priority-ordered rules │ │
│ │ ├── state.go # FeatureState data structure │ │
│ │ └── action.go # Action types and payloads │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────┴─────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────┐ ┌─────────────────────────────────────────────────┐ │
│ │ CLI MODE (404) │ │ LIBRARY MODE (406) │ │
│ │ │ │ │ │
│ │ cmd/sdlc/main.go │ │ internal/service/sdlc_service.go │ │
│ │ │ │ │ │
│ │ ┌───────────────────┐ │ │ ┌───────────────────────────────────────────┐ │ │
│ │ │ Import: │ │ │ │ Import: │ │ │
│ │ │ internal/sdlc │ │ │ │ internal/sdlc │ │ │
│ │ └───────────────────┘ │ │ └───────────────────────────────────────────┘ │ │
│ │ │ │ │ │
│ │ Input: │ │ Input: │ │
│ │ - Read .sdlc/ from │ │ - Read state via kubectl exec │ │
│ │ local filesystem │ │ into project pod │ │
│ │ │ │ │ │
│ │ Output: │ │ Output: │ │
│ │ - JSON to stdout │ │ - Structured response via API │ │
│ │ - Write .sdlc/ to │ │ - Write state via kubectl exec │ │
│ │ local filesystem │ │ │ │
│ └────────────┬────────────┘ └───────────────────────┬─────────────────────────┘ │
│ │ │ │
│ │ │ │
│ ════════════════════════════════════════════════════════════════════════════════ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────┐ ┌─────────────────────────────────────────────────┐ │
│ │ INSIDE POD (408) │ │ OUTSIDE POD (410) │ │
│ │ │ │ │ │
│ │ AI Agent invokes: │ │ Orchestrator API invokes: │ │
│ │ │ │ │ │
│ │ $ sdlc status │ │ sdlcService.GetNextAction(projectID, featureID)│ │
│ │ {"type":"IMPLEMENT_ │ │ → Action{Type: "IMPLEMENT_TASK", ...} │ │
│ │ TASK",...} │ │ │ │
│ │ │ │ sdlcService.ApproveArtifact(projectID, │ │
│ │ $ sdlc record │ │ featureID, "spec") │ │
│ │ --type=task │ │ → Updates state via kubectl exec │ │
│ │ --index=1 │ │ │ │
│ │ --path=handlers.go │ │ │ │
│ └─────────────────────────┘ └─────────────────────────────────────────────────┘ │
│ │
│ KEY INSIGHT: Same classification logic produces same results regardless of │
│ whether invoked inside the pod (by agent) or outside (by orchestrator) │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
**Reference Numerals:**
- 402: Shared core SDLC module
- 404: CLI execution mode
- 406: Library execution mode
- 408: Inside pod (agent invokes CLI)
- 410: Outside pod (orchestrator uses library)
**Description:**
FIG. 4 illustrates the dual-execution architecture. The shared core (402) contains classifier logic, rules, and state structures. The CLI mode (404) is compiled as a binary that runs inside Kubernetes pods, reading and writing state to the local filesystem. The library mode (406) is imported by the orchestrator API, reading and writing state via kubectl exec. Both modes import the same `internal/sdlc` package, ensuring identical classification behavior. The AI agent inside the pod (408) invokes the CLI to query status and record artifacts. The orchestrator outside the pod (410) uses the library to evaluate state and drive transitions (like approving artifacts).
---
## FIG. 5: Composable Template Architecture
**Purpose:** How skeleton + component templates compose into projects.
**Elements:**
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ EMBEDDED TEMPLATES (502): │
│ │
│ ┌─────────────────────────────┐ ┌─────────────────────────────────────────┐ │
│ │ SKELETON TEMPLATE (504) │ │ COMPONENT TEMPLATES (506) │ │
│ │ │ │ │ │
│ │ templates/skeleton/ │ │ templates/components/ │ │
│ │ ├── go.work.tmpl │ │ ├── service/ │ │
│ │ ├── .gitignore │ │ │ ├── cmd/{{.Name}}/main.go.tmpl │ │
│ │ ├── .claude/ │ │ │ ├── internal/handlers/ │ │
│ │ │ ├── CLAUDE.md │ │ │ └── Dockerfile.tmpl │ │
│ │ │ └── skills/ │ │ │ │ │
│ │ ├── pkg/ │ │ ├── worker/ │ │
│ │ │ ├── database/ │ │ │ ├── cmd/{{.Name}}/main.go.tmpl │ │
│ │ │ └── queue/ │ │ │ └── internal/handlers/ │ │
│ │ ├── scripts/ │ │ │ │ │
│ │ └── .woodpecker.yml │ │ ├── app-react/ │ │
│ │ │ │ └── cli/ │ │
│ └─────────────────────────────┘ └─────────────────────────────────────────┘ │
│ │ │ │
│ │ │ │
│ └────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ COMPOSITION ENGINE (508): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Input: │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ CompositionConfig { │ │ │
│ │ │ ProjectName: "my-project", │ │ │
│ │ │ Components: [ │ │ │
│ │ │ {Type: "service", Name: "auth-api", Port: 8080}, │ │ │
│ │ │ {Type: "service", Name: "user-api", Port: 8081}, │ │ │
│ │ │ {Type: "worker", Name: "email-worker"}, │ │ │
│ │ │ ] │ │ │
│ │ │ } │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Process: │ │
│ │ 1. Load skeleton template │ │
│ │ 2. Process skeleton with {{.ProjectName}} │ │
│ │ 3. For each component: │ │
│ │ a. Load component template by type │ │
│ │ b. Process with {{.ComponentName}}, {{.Port}} │ │
│ │ c. Place files in components/{{.ComponentName}}/ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ COMPOSED OUTPUT (510): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ my-project/ │ │
│ │ ├── go.work # From skeleton │ │
│ │ ├── .claude/CLAUDE.md # From skeleton │ │
│ │ ├── pkg/database/ # From skeleton (shared) │ │
│ │ ├── .woodpecker.yml # From skeleton + component steps │ │
│ │ │ │ │
│ │ ├── components/ │ │
│ │ │ ├── auth-api/ # From service template │ │
│ │ │ │ ├── cmd/auth-api/main.go │ │
│ │ │ │ └── Dockerfile │ │
│ │ │ ├── user-api/ # From service template │ │
│ │ │ │ ├── cmd/user-api/main.go │ │
│ │ │ │ └── Dockerfile │ │
│ │ │ └── email-worker/ # From worker template │ │
│ │ │ ├── cmd/email-worker/main.go │ │
│ │ │ └── Dockerfile │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ATOMIC DEPLOYMENT (512): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Single Gitea API Call: │ │
│ │ POST /repos/{owner}/{repo}/contents (bulk operation) │ │
│ │ │ │
│ │ - All files created in ONE commit │ │
│ │ - CI triggers ONCE (not per file) │ │
│ │ - Atomic: all files or none │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
**Reference Numerals:**
- 502: Embedded templates (compile-time embedding)
- 504: Skeleton template (base project structure)
- 506: Component templates (service, worker, app, CLI)
- 508: Composition engine
- 510: Composed output (complete project)
- 512: Atomic deployment via bulk API
**Description:**
FIG. 5 illustrates the composable template architecture. Templates are embedded at compile time (502) and comprise a skeleton (504) providing base structure and multiple component templates (506) for different component types. The composition engine (508) receives a configuration specifying project name and components. It processes the skeleton with project-level variables, then processes each component template with component-specific variables (name, port). The composed output (510) is a complete project with shared packages and multiple components. Atomic deployment (512) uses a bulk API to create all files in a single commit, preventing multiple CI triggers.
---
## FIG. 6: Per-Project Worker Coordination
**Purpose:** How workers coordinate across multiple projects with atomic task acquisition.
**Elements:**
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ COORDINATOR (602): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Discovery Loop (every 30s): │ │
│ │ 1. Query Kubernetes for pods with label rdev.orchard9.ai/project=true │ │
│ │ 2. For each discovered project not in worker registry: │ │
│ │ - Spawn new ProjectWorker goroutine │ │
│ │ 3. For each worker with no matching project: │ │
│ │ - Stop and remove worker │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Worker Registry: │ │ │
│ │ │ project-alpha → Worker-A (goroutine) │ │ │
│ │ │ project-beta → Worker-B (goroutine) │ │ │
│ │ │ project-gamma → Worker-C (goroutine) │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Worker-A (604) │ │ Worker-B (604) │ │ Worker-C (604) │ │
│ │ project-alpha │ │ project-beta │ │ project-gamma │ │
│ │ │ │ │ │ │ │
│ │ Poll loop: │ │ Poll loop: │ │ Poll loop: │ │
│ │ 1. Acquire task │ │ 1. Acquire task │ │ 1. Acquire task │ │
│ │ 2. Execute │ │ 2. Execute │ │ 2. Execute │ │
│ │ 3. Record result │ │ 3. Record result │ │ 3. Record result │ │
│ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ │ │
│ ▼ │
│ WORK QUEUE (606): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ PostgreSQL table: work_queue │ │
│ │ │ │
│ │ ┌───────┬──────────────┬──────────┬────────────┬──────────┐ │ │
│ │ │ id │ project_id │ type │ status │ created │ │ │
│ │ ├───────┼──────────────┼──────────┼────────────┼──────────┤ │ │
│ │ │ 1 │ project-alpha│ build │ pending │ 10:00:01 │ │ │
│ │ │ 2 │ project-alpha│ sdlc │ pending │ 10:00:02 │ │ │
│ │ │ 3 │ project-beta │ verify │ pending │ 10:00:03 │ │ │
│ │ │ 4 │ project-gamma│ build │ processing │ 10:00:04 │ ◄── Locked │ │
│ │ │ 5 │ project-beta │ build │ pending │ 10:00:05 │ │ │
│ │ └───────┴──────────────┴──────────┴────────────┴──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ │
│ ATOMIC TASK ACQUISITION (608): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ BEGIN TRANSACTION; │ │
│ │ │ │
│ │ SELECT * FROM work_queue │ │
│ │ WHERE project_id = 'project-alpha' │ │
│ │ AND status = 'pending' │ │
│ │ ORDER BY created_at │ │
│ │ LIMIT 1 │ │
│ │ FOR UPDATE SKIP LOCKED; ◄── Row-level lock, skip if locked │ │
│ │ │ │
│ │ UPDATE work_queue │ │
│ │ SET status = 'processing', started_at = NOW() │ │
│ │ WHERE id = ?; │ │
│ │ │ │
│ │ COMMIT; │ │
│ │ │ │
│ │ Result: Only ONE worker acquires the task, no race conditions │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
**Reference Numerals:**
- 602: Coordinator (discovers projects, spawns workers)
- 604: Per-project worker (one per project)
- 606: Work queue (PostgreSQL table)
- 608: Atomic task acquisition (SELECT FOR UPDATE SKIP LOCKED)
**Description:**
FIG. 6 illustrates per-project worker coordination. The coordinator (602) discovers projects by querying Kubernetes for pods with specific labels and spawns a worker goroutine for each project. Each per-project worker (604) polls the work queue for tasks matching its assigned project. The work queue (606) is a PostgreSQL table storing tasks with project ID, type, and status. Atomic task acquisition (608) uses `SELECT FOR UPDATE SKIP LOCKED` to ensure only one worker acquires each task without distributed locks or race conditions.
---
## FIG. 7: Action Type Taxonomy
**Purpose:** The defined set of action types the classifier can output.
**Elements:**
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ ACTION TYPES (702): │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ ARTIFACT CREATION ACTIONS: │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ CREATE_SPEC │ │ CREATE_PLAN │ │ CREATE_TESTS │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Output: │ │ Output: │ │ Output: │ │ │
│ │ │ spec.yaml in │ │ plan.yaml with │ │ Test files │ │ │
│ │ │ .sdlc/ │ │ task breakdown │ │ covering impl │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────┐ │ │
│ │ │ IMPLEMENT_TASK │ │ │
│ │ │ │ │ │
│ │ │ Payload: │ │ │
│ │ │ {task_index: N}│ │ │
│ │ │ │ │ │
│ │ │ Output: │ │ │
│ │ │ Code for task │ │ │
│ │ │ N from plan │ │ │
│ │ └────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ WORKFLOW ACTIONS: │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ AWAIT_APPROVAL │ │ TRANSITION │ │ REQUEST_REVIEW │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Payload: │ │ Payload: │ │ Agent cannot │ │ │
│ │ │ {artifact: │ │ {to_phase: │ │ proceed; │ │ │
│ │ │ "spec"} │ │ "specified"} │ │ human review │ │ │
│ │ │ │ │ │ │ required │ │ │
│ │ │ Agent blocked; │ │ State machine │ │ │ │ │
│ │ │ human action │ │ transition │ │ │ │ │
│ │ │ required │ │ │ │ │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ TERMINAL ACTIONS: │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ COMPLETE │ │ ERROR │ │ │
│ │ │ │ │ │ │ │
│ │ │ Feature has │ │ Invalid state │ │ │
│ │ │ reached │ │ detected; │ │ │
│ │ │ RELEASED phase │ │ manual │ │ │
│ │ │ │ │ intervention │ │ │
│ │ │ No more work │ │ required │ │ │
│ │ │ for agent │ │ │ │ │
│ │ └────────────────┘ └────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ KEY INSIGHT: Agent receives ONE of these action types. │
│ Agent does NOT choose what to do - classifier decides. │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
**Reference Numerals:**
- 702: Action types taxonomy
**Description:**
FIG. 7 illustrates the taxonomy of action types the classifier can output. Artifact creation actions (CREATE_SPEC, CREATE_PLAN, CREATE_TESTS, IMPLEMENT_TASK) instruct the agent to produce specific artifacts. Workflow actions (AWAIT_APPROVAL, TRANSITION, REQUEST_REVIEW) indicate state changes or blocking conditions. Terminal actions (COMPLETE, ERROR) indicate the feature has finished or encountered an invalid state. The agent receives exactly one action type and executes that instruction; the agent does not choose its own action.
---
## FIG. 8: Git-Backed State Persistence
**Purpose:** How SDLC state is stored in git for auditability.
**Elements:**
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ REPOSITORY STRUCTURE (802): │
│ │
│ project-repo/ │
│ ├── .sdlc/ ◄── SDLC state directory │
│ │ ├── feature.yaml # Main feature state │
│ │ ├── spec.yaml # Specification artifact │
│ │ ├── plan.yaml # Task breakdown │
│ │ └── tasks/ │
│ │ ├── 0-setup.yaml # Task 0 record │
│ │ ├── 1-api.yaml # Task 1 record │
│ │ └── 2-tests.yaml # Task 2 record │
│ │ │
│ ├── components/ ◄── Actual code │
│ │ └── ... │
│ └── pkg/ │
│ └── ... │
│ │
│ FEATURE.YAML CONTENT (804): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ id: feat-001 │ │
│ │ name: "Add user authentication" │ │
│ │ phase: implementation │ │
│ │ created_at: 2026-02-04T10:00:00Z │ │
│ │ updated_at: 2026-02-04T14:30:00Z │ │
│ │ │ │
│ │ artifacts: │ │
│ │ spec: │ │
│ │ type: specification │ │
│ │ path: .sdlc/spec.yaml │ │
│ │ hash: abc123... │ │
│ │ approved: true │ │
│ │ approved_by: "jordan@orchard9.ai" │ │
│ │ approved_at: 2026-02-04T11:00:00Z │ │
│ │ │ │
│ │ plan: │ │
│ │ type: plan │ │
│ │ path: .sdlc/plan.yaml │ │
│ │ hash: def456... │ │
│ │ approved: true │ │
│ │ approved_by: "jordan@orchard9.ai" │ │
│ │ approved_at: 2026-02-04T12:00:00Z │ │
│ │ │ │
│ │ tasks: │ │
│ │ - index: 0 │ │
│ │ title: "Setup database schema" │ │
│ │ implemented: true │ │
│ │ artifact_path: .sdlc/tasks/0-setup.yaml │ │
│ │ - index: 1 │ │
│ │ title: "Add API endpoint" │ │
│ │ implemented: true │ │
│ │ artifact_path: .sdlc/tasks/1-api.yaml │ │
│ │ - index: 2 │ │
│ │ title: "Add tests" │ │
│ │ implemented: false ◄── Not done yet │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ GIT HISTORY (806): │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ commit 7f8a9b2 sdlc: task 1 implemented │ │
│ │ commit 3d4e5f6 sdlc: task 0 implemented │ │
│ │ commit 1a2b3c4 sdlc: plan approved, transition to planned │ │
│ │ commit 9e8f7a6 sdlc: plan created │ │
│ │ commit 5c6d7e8 sdlc: spec approved, transition to specified │ │
│ │ commit 2b3c4d5 sdlc: spec created │ │
│ │ commit 8a9b0c1 sdlc: feature initialized │ │
│ │ │ │
│ │ Every state change = git commit │ │
│ │ Full audit trail via git log │ │
│ │ Time-travel via git checkout │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
```
**Reference Numerals:**
- 802: Repository structure with .sdlc directory
- 804: feature.yaml content showing state
- 806: Git history showing state change commits
**Description:**
FIG. 8 illustrates git-backed state persistence. SDLC state is stored in the `.sdlc/` directory (802) within the project repository. The `feature.yaml` file (804) contains current phase, artifacts with approval status, and task breakdown. Every state change results in a git commit, creating a complete audit trail (806). Time-travel queries can reconstruct historical state by checking out previous commits. This approach provides version-controlled auditability without requiring a separate database.
---
## Revision History
| Date | Author | Changes |
|------|--------|---------|
| 2026-02-04 | Initial | Complete figure descriptions with 8 figures |
Reference in New Issue View Git Blame Copy Permalink