From 257a295e0bd5516c16aaac48fbeaee58b4c5e710 Mon Sep 17 00:00:00 2001 From: Eran Kuris Date: Mon, 13 Jul 2026 17:23:50 +0300 Subject: [PATCH 1/6] docs: add architecture diagram Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/architecture.md | 140 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/architecture.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000..7245d491 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,140 @@ +# Forge Architecture + +## System Overview + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ External Systems │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌────────────────┐ │ +│ │ Jira │ │ GitHub │ │ Deep │ │ Langfuse │ │ +│ │ │ │ │ │ Agents │ │ (Observability)│ │ +│ └────┬─────┘ └────┬─────┘ └───────────┘ └────────────────┘ │ +│ │ │ │ +└────────┼───────────────┼────────────────────────────────────────────────┘ + │ webhooks │ webhooks + ▼ ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ FastAPI Server (:8000) │ +│ │ +│ POST /api/v1/webhooks/jira POST /api/v1/webhooks/github │ +│ GET /api/v1/health GET /api/v1/metrics │ +│ │ +└────────────────────────────┬────────────────────────────────────────────┘ + │ enqueue events + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ Redis Streams ("forge:events") │ +│ │ +│ Consumer group: forge-workers State: AsyncRedisSaver │ +│ Per-ticket thread IDs (AISOS-123) LangGraph checkpointing │ +│ │ +└────────────────────────────┬────────────────────────────────────────────┘ + │ dequeue + dispatch + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ LangGraph Orchestrator │ +│ │ +│ Orchestrator.resume(event) → StateGraph(WorkflowState) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ Workflow Nodes │ │ +│ │ │ │ +│ │ CLASSIFY ─┬─► [Bug] TRIAGE → RCA_OPTIONS → RCA_GATE → RCA │ │ +│ │ │ │ │ │ +│ │ └─► [Feature] ──────────────────────────┤ │ │ +│ │ ▼ │ │ +│ │ PRD → PRD_GATE ─► SPEC → SPEC_GATE │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ PLAN → PLAN_GATE ─► TASKS → TASK_GATE │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ IMPLEMENT ─► PR_CREATE ─► CI_GATE ◄─┐ │ │ +│ │ │ │ │ │ +│ │ CI_EVALUATOR┤ CI_FIX (retry) │ │ +│ │ │ │ │ │ +│ │ ▼ │ │ │ +│ │ HUMAN_REVIEW_GATE───┘ │ │ +│ │ │ │ │ +│ │ MERGE → DONE │ │ +│ │ │ │ +│ │ ⏸ Gates = human checkpoints (skipped with forge:yolo label) │ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +│ │ +└───────────────┬─────────────────────────────┬───────────────────────────┘ + │ │ + ▼ ▼ +┌──────────────────────────┐ ┌──────────────────────────────────────────┐ +│ Claude LLM │ │ Podman Container (ephemeral) │ +│ │ │ │ +│ Anthropic API │ │ ┌─────────────────────────────────┐ │ +│ or Vertex AI │ │ │ Deep Agents + MCP tools │ │ +│ │ │ │ .forge/task.json │ │ +│ Used by: classify, │ │ │ workspace mounted │ │ +│ triage, RCA, PRD, │ │ │ commits changes locally │ │ +│ spec, plan, CI eval │ │ └─────────────────────────────────┘ │ +│ │ │ │ +└──────────────────────────┘ └──────────────────────────────────────────┘ +``` + +## Ticket Lifecycle + +``` +Jira ticket created + labeled "forge:managed" + │ + ▼ +CLASSIFY ── Claude determines: bug or feature? + │ + ├── Bug ────► TRIAGE → RCA_OPTIONS → ⏸ RCA_OPTION_GATE → RCA_DEEP_DIVE + │ (user picks ">option N") + │ + └── Feature ─────────────────────────────────────┐ + │ + ◄─────────────────────────────────────────────────┘ + │ + ▼ +PRD ── generate requirements ── ⏸ PRD_GATE (Jira or proposals PR) + │ + ▼ +SPEC ── generate tech design ── ⏸ SPEC_GATE + │ + ▼ +PLAN ── generate impl plan ──── ⏸ PLAN_GATE + │ + ▼ +TASKS ── break into work items ─ ⏸ TASK_GATE + │ + ▼ +IMPLEMENT ── Podman container + Deep Agents executes code + │ + ▼ +PR_CREATE ── open GitHub PR + │ + ▼ +CI_GATE ── wait for checks ──► CI_EVALUATOR + │ │ + │ ┌── pass ────────┤ + │ │ └── fail ──► ATTEMPT_CI_FIX ─┐ + │ │ (retry ≤N) │ + │ │ ◄────────────────────────────┘ + ▼ ▼ +HUMAN_REVIEW_GATE ── ⏸ wait for PR approval + │ + ▼ +MERGE ── merge PR ──► DONE ✓ + +⏸ = human checkpoint (auto-approved when forge:yolo label is set) +``` + +## Data Flow Summary + +``` +Inbound events: Jira/GitHub webhooks → FastAPI → Redis Streams +State persistence: Redis (LangGraph AsyncRedisSaver, keyed by ticket) +LLM calls: Orchestrator nodes → Claude (Anthropic API / Vertex AI) +Code execution: IMPLEMENT node → Podman container → Deep Agents +Outbound actions: Jira (comments, labels, transitions) + GitHub (PRs, branches, reviews) +Observability: Langfuse (LLM traces, workflow spans, costs) +``` From 4530c3a9719b809da063c4d1c4e13251c6d3b871 Mon Sep 17 00:00:00 2001 From: Eran Kuris Date: Mon, 13 Jul 2026 19:10:10 +0300 Subject: [PATCH 2/6] docs: fix architecture diagram inaccuracies Verified against actual source code and corrected: - Remove fictional CLASSIFY node (routing is done by WorkflowRouter) - Show Feature and Bug as separate graphs with correct node names - Fix Redis stream names (forge:events:jira, forge:events:github) - Fix metrics endpoint path (/metrics, not /api/v1/metrics) - Fix container task path (/task.json, not .forge/task.json) - Add Gemini as a supported LLM backend - Add missing nodes: local_review, update_documentation, setup/teardown_workspace, task_router, completion/aggregation Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/architecture.md | 187 ++++++++++++++++++++++++++++--------------- 1 file changed, 124 insertions(+), 63 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 7245d491..149f94b4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -18,122 +18,183 @@ │ FastAPI Server (:8000) │ │ │ │ POST /api/v1/webhooks/jira POST /api/v1/webhooks/github │ -│ GET /api/v1/health GET /api/v1/metrics │ +│ GET /api/v1/health GET /metrics │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ enqueue events ▼ ┌─────────────────────────────────────────────────────────────────────────┐ -│ Redis Streams ("forge:events") │ +│ Redis │ │ │ -│ Consumer group: forge-workers State: AsyncRedisSaver │ -│ Per-ticket thread IDs (AISOS-123) LangGraph checkpointing │ +│ Streams: forge:events:jira State: AsyncRedisSaver │ +│ forge:events:github LangGraph checkpointing │ +│ Consumer group: forge-workers Per-ticket thread IDs (AISOS-123) │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ dequeue + dispatch ▼ ┌─────────────────────────────────────────────────────────────────────────┐ -│ LangGraph Orchestrator │ +│ WorkflowRouter │ │ │ -│ Orchestrator.resume(event) → StateGraph(WorkflowState) │ +│ Selects graph based on Jira issue type: │ +│ Feature/Story → FeatureWorkflow (StateGraph) │ +│ Bug → BugWorkflow (StateGraph) │ │ │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ Workflow Nodes │ │ -│ │ │ │ -│ │ CLASSIFY ─┬─► [Bug] TRIAGE → RCA_OPTIONS → RCA_GATE → RCA │ │ -│ │ │ │ │ │ -│ │ └─► [Feature] ──────────────────────────┤ │ │ -│ │ ▼ │ │ -│ │ PRD → PRD_GATE ─► SPEC → SPEC_GATE │ │ -│ │ │ │ │ -│ │ ▼ │ │ -│ │ PLAN → PLAN_GATE ─► TASKS → TASK_GATE │ │ -│ │ │ │ │ -│ │ ▼ │ │ -│ │ IMPLEMENT ─► PR_CREATE ─► CI_GATE ◄─┐ │ │ -│ │ │ │ │ │ -│ │ CI_EVALUATOR┤ CI_FIX (retry) │ │ -│ │ │ │ │ │ -│ │ ▼ │ │ │ -│ │ HUMAN_REVIEW_GATE───┘ │ │ -│ │ │ │ │ -│ │ MERGE → DONE │ │ -│ │ │ │ -│ │ ⏸ Gates = human checkpoints (skipped with forge:yolo label) │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ +│ ┌──────────────────────────────┐ ┌────────────────────────────────┐ │ +│ │ Feature Workflow │ │ Bug Workflow │ │ +│ │ │ │ │ │ +│ │ generate_prd │ │ triage_check │ │ +│ │ → ⏸ prd_approval_gate │ │ → ⏸ triage_gate │ │ +│ │ generate_spec │ │ analyze_bug ◄─┐ │ │ +│ │ → ⏸ spec_approval_gate │ │ → reflect_rca ─┘ (≤3x) │ │ +│ │ decompose_epics │ │ → ⏸ rca_option_gate │ │ +│ │ → ⏸ plan_approval_gate │ │ plan_bug_fix │ │ +│ │ generate_tasks │ │ → ⏸ plan_approval_gate │ │ +│ │ → ⏸ task_approval_gate │ │ decompose_plan │ │ +│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ +│ │ task_router (per-repo) │ │ Shared implementation path: │ │ +│ │ setup_workspace │ │ (same nodes as Feature) │ │ +│ │ implement_task │ │ │ │ +│ │ local_review │ │ Post-merge: │ │ +│ │ update_documentation │ │ post_merge_summary → END │ │ +│ │ create_pr │ │ │ │ +│ │ teardown_workspace │ └────────────────────────────────┘ │ +│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ +│ │ wait_for_ci_gate │ │ +│ │ ci_evaluator ◄── ci_fix │ │ +│ │ ⏸ human_review_gate │ │ +│ │ complete_tasks │ │ +│ │ aggregate_epic_status │ │ +│ │ aggregate_feature_status │ │ +│ │ → END │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ⏸ = human checkpoint (auto-approved with forge:yolo label) │ │ │ └───────────────┬─────────────────────────────┬───────────────────────────┘ │ │ ▼ ▼ ┌──────────────────────────┐ ┌──────────────────────────────────────────┐ -│ Claude LLM │ │ Podman Container (ephemeral) │ -│ │ │ │ -│ Anthropic API │ │ ┌─────────────────────────────────┐ │ -│ or Vertex AI │ │ │ Deep Agents + MCP tools │ │ -│ │ │ │ .forge/task.json │ │ -│ Used by: classify, │ │ │ workspace mounted │ │ -│ triage, RCA, PRD, │ │ │ commits changes locally │ │ -│ spec, plan, CI eval │ │ └─────────────────────────────────┘ │ +│ LLM Backends │ │ Podman Container (ephemeral) │ │ │ │ │ +│ Anthropic API (Claude) │ │ ┌─────────────────────────────────┐ │ +│ Vertex AI (Claude) │ │ │ Deep Agents + MCP tools │ │ +│ Vertex AI (Gemini) │ │ │ /task.json (task description) │ │ +│ │ │ │ /workspace (repo mounted) │ │ +│ Used by: PRD, spec, │ │ │ commits changes locally │ │ +│ plan, RCA, triage, │ │ └─────────────────────────────────┘ │ +│ code review, CI eval │ │ │ └──────────────────────────┘ └──────────────────────────────────────────┘ ``` -## Ticket Lifecycle +## Feature Ticket Lifecycle ``` -Jira ticket created + labeled "forge:managed" +Jira ticket created + labeled "forge:managed" (type: Feature or Story) + │ + ▼ +generate_prd ── AI drafts Product Requirements Document + │ + ▼ +⏸ prd_approval_gate ── wait for approval (Jira comment or proposals PR) + │ + ▼ +generate_spec ── AI drafts Technical Specification + │ + ▼ +⏸ spec_approval_gate │ ▼ -CLASSIFY ── Claude determines: bug or feature? +decompose_epics ── AI breaks spec into Jira Epics │ - ├── Bug ────► TRIAGE → RCA_OPTIONS → ⏸ RCA_OPTION_GATE → RCA_DEEP_DIVE - │ (user picks ">option N") + ▼ +⏸ plan_approval_gate + │ + ▼ +generate_tasks ── AI creates implementation Tasks under Epics + │ + ▼ +⏸ task_approval_gate │ - └── Feature ─────────────────────────────────────┐ - │ - ◄─────────────────────────────────────────────────┘ + ▼ +task_router ── group tasks by target repo + │ + ▼ (per repo) +setup_workspace ── clone repo, create branch │ ▼ -PRD ── generate requirements ── ⏸ PRD_GATE (Jira or proposals PR) +implement_task ── Podman container + Deep Agents writes code │ ▼ -SPEC ── generate tech design ── ⏸ SPEC_GATE +local_review ── AI reviews diff, fixes issues (≤2 passes) │ ▼ -PLAN ── generate impl plan ──── ⏸ PLAN_GATE +update_documentation ── update stale docs │ ▼ -TASKS ── break into work items ─ ⏸ TASK_GATE +create_pr ── open GitHub PR │ ▼ -IMPLEMENT ── Podman container + Deep Agents executes code +teardown_workspace ── cleanup (loop back if more repos) │ ▼ -PR_CREATE ── open GitHub PR +wait_for_ci_gate ── wait for CI checks │ ▼ -CI_GATE ── wait for checks ──► CI_EVALUATOR - │ │ - │ ┌── pass ────────┤ - │ │ └── fail ──► ATTEMPT_CI_FIX ─┐ - │ │ (retry ≤N) │ - │ │ ◄────────────────────────────┘ - ▼ ▼ -HUMAN_REVIEW_GATE ── ⏸ wait for PR approval +ci_evaluator ─┬─ pass ──────────────────────────┐ + └─ fail → attempt_ci_fix (≤5x) ───┘ │ ▼ -MERGE ── merge PR ──► DONE ✓ +⏸ human_review_gate ── wait for PR approval + │ (changes_requested → implement_review → CI loop) + ▼ +complete_tasks → aggregate_epic_status → aggregate_feature_status → END ⏸ = human checkpoint (auto-approved when forge:yolo label is set) ``` +## Bug Ticket Lifecycle + +``` +Jira ticket created + labeled "forge:managed" (type: Bug) + │ + ▼ +triage_check ── validate bug report has required fields + │ + ▼ +⏸ triage_gate ── wait for reporter update if incomplete + │ + ▼ +analyze_bug ◄──┐ + │ │ reflect_rca (up to 3 reflection cycles) + └────────────┘ + │ + ▼ +⏸ rca_option_gate ── present fix options, user selects ">option N" + │ + ▼ +plan_bug_fix ── AI generates fix plan + │ + ▼ +⏸ plan_approval_gate + │ + ▼ +decompose_plan ── break into tasks + │ + ▼ +setup_workspace → implement → local_review → create_pr → CI → review + │ + ▼ +post_merge_summary → END +``` + ## Data Flow Summary ``` Inbound events: Jira/GitHub webhooks → FastAPI → Redis Streams State persistence: Redis (LangGraph AsyncRedisSaver, keyed by ticket) -LLM calls: Orchestrator nodes → Claude (Anthropic API / Vertex AI) -Code execution: IMPLEMENT node → Podman container → Deep Agents +LLM calls: Orchestrator nodes → Claude/Gemini (Anthropic API / Vertex AI) +Code execution: implement_task → Podman container → Deep Agents Outbound actions: Jira (comments, labels, transitions) GitHub (PRs, branches, reviews) Observability: Langfuse (LLM traces, workflow spans, costs) From a38f15c4525679b5f2681bc9c5f75ec22d105963 Mon Sep 17 00:00:00 2001 From: Eran Kuris Date: Mon, 13 Jul 2026 21:13:15 +0300 Subject: [PATCH 3/6] =?UTF-8?q?docs:=20fix=20diagram=20alignment=20?= =?UTF-8?q?=E2=80=94=20all=20box=20lines=20at=20width=2075?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/architecture.md | 311 ++++++++++++++++++++++--------------------- 1 file changed, 158 insertions(+), 153 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 149f94b4..a6469fc2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,195 +6,200 @@ ┌─────────────────────────────────────────────────────────────────────────┐ │ External Systems │ │ │ -│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌────────────────┐ │ -│ │ Jira │ │ GitHub │ │ Deep │ │ Langfuse │ │ -│ │ │ │ │ │ Agents │ │ (Observability)│ │ -│ └────┬─────┘ └────┬─────┘ └───────────┘ └────────────────┘ │ -│ │ │ │ -└────────┼───────────────┼────────────────────────────────────────────────┘ - │ webhooks │ webhooks - ▼ ▼ +│ ┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────────────┐ │ +│ │ Jira │ │ GitHub │ │ Deep Agents │ │ Langfuse │ │ +│ │ │ │ │ │ │ │ (Observability) │ │ +│ └────┬─────┘ └────┬─────┘ └─────────────┘ └──────────────────┘ │ +│ │ │ │ +└────────┼──────────────┼─────────────────────────────────────────────────┘ + │ webhooks │ webhooks + v v ┌─────────────────────────────────────────────────────────────────────────┐ -│ FastAPI Server (:8000) │ +│ FastAPI Server (:8000) │ │ │ -│ POST /api/v1/webhooks/jira POST /api/v1/webhooks/github │ -│ GET /api/v1/health GET /metrics │ +│ POST /api/v1/webhooks/jira POST /api/v1/webhooks/github │ +│ GET /api/v1/health GET /metrics │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ enqueue events - ▼ + v ┌─────────────────────────────────────────────────────────────────────────┐ -│ Redis │ +│ Redis │ │ │ -│ Streams: forge:events:jira State: AsyncRedisSaver │ -│ forge:events:github LangGraph checkpointing │ -│ Consumer group: forge-workers Per-ticket thread IDs (AISOS-123) │ +│ Streams: forge:events:jira State: AsyncRedisSaver │ +│ forge:events:github LangGraph checkpointing │ +│ Consumer group: forge-workers Per-ticket thread IDs (AISOS-123) │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ │ dequeue + dispatch - ▼ + v ┌─────────────────────────────────────────────────────────────────────────┐ -│ WorkflowRouter │ +│ WorkflowRouter │ │ │ -│ Selects graph based on Jira issue type: │ -│ Feature/Story → FeatureWorkflow (StateGraph) │ -│ Bug → BugWorkflow (StateGraph) │ +│ Routes by Jira issue type: │ +│ Feature/Story --> FeatureWorkflow (StateGraph) │ +│ Bug --> BugWorkflow (StateGraph) │ │ │ -│ ┌──────────────────────────────┐ ┌────────────────────────────────┐ │ -│ │ Feature Workflow │ │ Bug Workflow │ │ -│ │ │ │ │ │ -│ │ generate_prd │ │ triage_check │ │ -│ │ → ⏸ prd_approval_gate │ │ → ⏸ triage_gate │ │ -│ │ generate_spec │ │ analyze_bug ◄─┐ │ │ -│ │ → ⏸ spec_approval_gate │ │ → reflect_rca ─┘ (≤3x) │ │ -│ │ decompose_epics │ │ → ⏸ rca_option_gate │ │ -│ │ → ⏸ plan_approval_gate │ │ plan_bug_fix │ │ -│ │ generate_tasks │ │ → ⏸ plan_approval_gate │ │ -│ │ → ⏸ task_approval_gate │ │ decompose_plan │ │ -│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ -│ │ task_router (per-repo) │ │ Shared implementation path: │ │ -│ │ setup_workspace │ │ (same nodes as Feature) │ │ -│ │ implement_task │ │ │ │ -│ │ local_review │ │ Post-merge: │ │ -│ │ update_documentation │ │ post_merge_summary → END │ │ -│ │ create_pr │ │ │ │ -│ │ teardown_workspace │ └────────────────────────────────┘ │ -│ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │ -│ │ wait_for_ci_gate │ │ -│ │ ci_evaluator ◄── ci_fix │ │ -│ │ ⏸ human_review_gate │ │ -│ │ complete_tasks │ │ -│ │ aggregate_epic_status │ │ -│ │ aggregate_feature_status │ │ -│ │ → END │ │ -│ └──────────────────────────────┘ │ +│ ┌──────────────────────────────┐ ┌──────────────────────────────┐ │ +│ │ Feature Workflow │ │ Bug Workflow │ │ +│ │ │ │ │ │ +│ │ generate_prd │ │ triage_check │ │ +│ │ >> prd_approval_gate │ │ >> triage_gate │ │ +│ │ generate_spec │ │ analyze_bug │ │ +│ │ >> spec_approval_gate │ │ <> reflect_rca (up to 3x) │ │ +│ │ decompose_epics │ │ >> rca_option_gate │ │ +│ │ >> plan_approval_gate │ │ plan_bug_fix │ │ +│ │ generate_tasks │ │ >> plan_approval_gate │ │ +│ │ >> task_approval_gate │ │ decompose_plan │ │ +│ │──────────────────────────────│ │──────────────────────────────│ │ +│ │ task_router (per-repo) │ │ Shared impl path: │ │ +│ │ setup_workspace │ │ (same nodes as Feature) │ │ +│ │ implement_task │ │ │ │ +│ │ local_review │ │ Post-merge: │ │ +│ │ update_documentation │ │ post_merge_summary --> END│ │ +│ │ create_pr │ │ │ │ +│ │ teardown_workspace │ └──────────────────────────────┘ │ +│ │──────────────────────────────│ │ +│ │ wait_for_ci_gate │ │ +│ │ ci_evaluator <-- ci_fix │ │ +│ │ >> human_review_gate │ │ +│ │ complete_tasks │ │ +│ │ aggregate_epic_status │ │ +│ │ aggregate_feature_status │ │ +│ │ --> END │ │ +│ └──────────────────────────────┘ │ │ │ -│ ⏸ = human checkpoint (auto-approved with forge:yolo label) │ +│ >> = human checkpoint (auto-approved with forge:yolo label) │ │ │ └───────────────┬─────────────────────────────┬───────────────────────────┘ │ │ - ▼ ▼ -┌──────────────────────────┐ ┌──────────────────────────────────────────┐ -│ LLM Backends │ │ Podman Container (ephemeral) │ -│ │ │ │ -│ Anthropic API (Claude) │ │ ┌─────────────────────────────────┐ │ -│ Vertex AI (Claude) │ │ │ Deep Agents + MCP tools │ │ -│ Vertex AI (Gemini) │ │ │ /task.json (task description) │ │ -│ │ │ │ /workspace (repo mounted) │ │ -│ Used by: PRD, spec, │ │ │ commits changes locally │ │ -│ plan, RCA, triage, │ │ └─────────────────────────────────┘ │ -│ code review, CI eval │ │ │ -└──────────────────────────┘ └──────────────────────────────────────────┘ + v v +┌────────────────────────────┐ ┌────────────────────────────────────────┐ +│ LLM Backends │ │ Podman Container (ephemeral) │ +│ │ │ │ +│ Anthropic API (Claude) │ │ ┌──────────────────────────────────┐ │ +│ Vertex AI (Claude) │ │ │ Deep Agents + MCP tools │ │ +│ Vertex AI (Gemini) │ │ │ /task.json (task description) │ │ +│ │ │ │ /workspace (repo mounted) │ │ +│ Used by: PRD, spec, │ │ │ commits changes locally │ │ +│ plan, RCA, triage, │ │ └──────────────────────────────────┘ │ +│ code review, CI eval │ │ │ +└────────────────────────────┘ └────────────────────────────────────────┘ ``` ## Feature Ticket Lifecycle ``` Jira ticket created + labeled "forge:managed" (type: Feature or Story) - │ - ▼ -generate_prd ── AI drafts Product Requirements Document - │ - ▼ -⏸ prd_approval_gate ── wait for approval (Jira comment or proposals PR) - │ - ▼ -generate_spec ── AI drafts Technical Specification - │ - ▼ -⏸ spec_approval_gate - │ - ▼ -decompose_epics ── AI breaks spec into Jira Epics - │ - ▼ -⏸ plan_approval_gate - │ - ▼ -generate_tasks ── AI creates implementation Tasks under Epics - │ - ▼ -⏸ task_approval_gate - │ - ▼ -task_router ── group tasks by target repo - │ - ▼ (per repo) -setup_workspace ── clone repo, create branch - │ - ▼ -implement_task ── Podman container + Deep Agents writes code - │ - ▼ -local_review ── AI reviews diff, fixes issues (≤2 passes) - │ - ▼ -update_documentation ── update stale docs - │ - ▼ -create_pr ── open GitHub PR - │ - ▼ -teardown_workspace ── cleanup (loop back if more repos) - │ - ▼ -wait_for_ci_gate ── wait for CI checks - │ - ▼ -ci_evaluator ─┬─ pass ──────────────────────────┐ - └─ fail → attempt_ci_fix (≤5x) ───┘ - │ - ▼ -⏸ human_review_gate ── wait for PR approval - │ (changes_requested → implement_review → CI loop) - ▼ -complete_tasks → aggregate_epic_status → aggregate_feature_status → END + | + v +generate_prd -- AI drafts Product Requirements Document + | + v +>> prd_approval_gate -- wait for approval (Jira comment or proposals PR) + | + v +generate_spec -- AI drafts Technical Specification + | + v +>> spec_approval_gate + | + v +decompose_epics -- AI breaks spec into Jira Epics + | + v +>> plan_approval_gate + | + v +generate_tasks -- AI creates implementation Tasks under Epics + | + v +>> task_approval_gate + | + v +task_router -- group tasks by target repo + | + v (per repo) +setup_workspace -- clone repo, create branch + | + v +implement_task -- Podman container + Deep Agents writes code + | + v +local_review -- AI reviews diff, fixes issues (up to 2 passes) + | + v +update_documentation -- update stale docs + | + v +create_pr -- open GitHub PR + | + v +teardown_workspace -- cleanup (loop back if more repos) + | + v +wait_for_ci_gate -- wait for CI checks + | + v +ci_evaluator --+-- pass ------+ + +-- fail ---+ | + | | + attempt_ci_fix | + (up to 5x) | + | | + +-----------+ | + | | + v v +>> human_review_gate -- wait for PR approval + | (changes_requested --> implement_review --> CI loop) + v +complete_tasks --> aggregate_epic_status --> aggregate_feature_status --> END -⏸ = human checkpoint (auto-approved when forge:yolo label is set) +>> = human checkpoint (auto-approved when forge:yolo label is set) ``` ## Bug Ticket Lifecycle ``` Jira ticket created + labeled "forge:managed" (type: Bug) - │ - ▼ -triage_check ── validate bug report has required fields - │ - ▼ -⏸ triage_gate ── wait for reporter update if incomplete - │ - ▼ -analyze_bug ◄──┐ - │ │ reflect_rca (up to 3 reflection cycles) - └────────────┘ - │ - ▼ -⏸ rca_option_gate ── present fix options, user selects ">option N" - │ - ▼ -plan_bug_fix ── AI generates fix plan - │ - ▼ -⏸ plan_approval_gate - │ - ▼ -decompose_plan ── break into tasks - │ - ▼ -setup_workspace → implement → local_review → create_pr → CI → review - │ - ▼ -post_merge_summary → END + | + v +triage_check -- validate bug report has required fields + | + v +>> triage_gate -- wait for reporter update if incomplete + | + v +analyze_bug <--+ + | | + +--- reflect_rca (up to 3 reflection cycles) + | + v +>> rca_option_gate -- present fix options, user selects ">option N" + | + v +plan_bug_fix -- AI generates fix plan + | + v +>> plan_approval_gate + | + v +decompose_plan -- break into tasks + | + v +setup_workspace --> implement --> local_review --> create_pr --> CI --> review + | + v +post_merge_summary --> END ``` ## Data Flow Summary ``` -Inbound events: Jira/GitHub webhooks → FastAPI → Redis Streams +Inbound events: Jira/GitHub webhooks --> FastAPI --> Redis Streams State persistence: Redis (LangGraph AsyncRedisSaver, keyed by ticket) -LLM calls: Orchestrator nodes → Claude/Gemini (Anthropic API / Vertex AI) -Code execution: implement_task → Podman container → Deep Agents +LLM calls: Orchestrator nodes --> Claude/Gemini (Anthropic / Vertex AI) +Code execution: implement_task --> Podman container --> Deep Agents Outbound actions: Jira (comments, labels, transitions) GitHub (PRs, branches, reviews) Observability: Langfuse (LLM traces, workflow spans, costs) From 9ce53bf2fea639ac30807f7fc698efc284d53e07 Mon Sep 17 00:00:00 2001 From: Eran Kuris Date: Tue, 14 Jul 2026 11:33:57 +0300 Subject: [PATCH 4/6] docs: address review feedback on architecture diagram - Remove Deep Agents from External Systems (it's a library, not a service) - Show LLM Backends connected to both orchestrator and container - Clarify Deep Agents runs inside Podman containers - Add bidirectional LLM call arrows Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/architecture.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index a6469fc2..4cb46a32 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -6,10 +6,9 @@ ┌─────────────────────────────────────────────────────────────────────────┐ │ External Systems │ │ │ -│ ┌──────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────────────┐ │ -│ │ Jira │ │ GitHub │ │ Deep Agents │ │ Langfuse │ │ -│ │ │ │ │ │ │ │ (Observability) │ │ -│ └────┬─────┘ └────┬─────┘ └─────────────┘ └──────────────────┘ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────────────────────────────┐ │ +│ │ Jira │ │ GitHub │ │ Langfuse (Observability) │ │ +│ └────┬─────┘ └────┬─────┘ └──────────────────────────────────┘ │ │ │ │ │ └────────┼──────────────┼─────────────────────────────────────────────────┘ │ webhooks │ webhooks @@ -71,19 +70,21 @@ │ │ │ >> = human checkpoint (auto-approved with forge:yolo label) │ │ │ -└───────────────┬─────────────────────────────┬───────────────────────────┘ - │ │ - v v +└────────────────────────────┬────────────────────────────────────────────┘ + │ + ┌──────────────┼──────────────┐ + │ LLM calls │ │ LLM calls + v v v ┌────────────────────────────┐ ┌────────────────────────────────────────┐ │ LLM Backends │ │ Podman Container (ephemeral) │ │ │ │ │ │ Anthropic API (Claude) │ │ ┌──────────────────────────────────┐ │ -│ Vertex AI (Claude) │ │ │ Deep Agents + MCP tools │ │ +│ Vertex AI (Claude) │ │ │ Deep Agents (library) + MCP │ │ │ Vertex AI (Gemini) │ │ │ /task.json (task description) │ │ │ │ │ │ /workspace (repo mounted) │ │ -│ Used by: PRD, spec, │ │ │ commits changes locally │ │ -│ plan, RCA, triage, │ │ └──────────────────────────────────┘ │ -│ code review, CI eval │ │ │ +│ Called by orchestrator │ │ │ commits changes locally │ │ +│ nodes and container │ │ └──────────────────────────────────┘ │ +│ agents (bidirectional) │ │ │ └────────────────────────────┘ └────────────────────────────────────────┘ ``` @@ -199,7 +200,8 @@ post_merge_summary --> END Inbound events: Jira/GitHub webhooks --> FastAPI --> Redis Streams State persistence: Redis (LangGraph AsyncRedisSaver, keyed by ticket) LLM calls: Orchestrator nodes --> Claude/Gemini (Anthropic / Vertex AI) -Code execution: implement_task --> Podman container --> Deep Agents + Container agents --> Claude/Gemini (same backends) +Code execution: implement_task --> Podman container --> Deep Agents (library) Outbound actions: Jira (comments, labels, transitions) GitHub (PRs, branches, reviews) Observability: Langfuse (LLM traces, workflow spans, costs) From 537c3d91de821720c25fdf1795c784bc2c6fdced Mon Sep 17 00:00:00 2001 From: Eran Kuris Date: Tue, 14 Jul 2026 12:06:26 +0300 Subject: [PATCH 5/6] cosmetic changes Co-authored-by: Lukas Svaty --- docs/architecture.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 4cb46a32..8f6c9469 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -71,17 +71,17 @@ │ >> = human checkpoint (auto-approved with forge:yolo label) │ │ │ └────────────────────────────┬────────────────────────────────────────────┘ - │ + v ┌──────────────┼──────────────┐ - │ LLM calls │ │ LLM calls - v v v + │ LLM calls │ LLM calls + v v ┌────────────────────────────┐ ┌────────────────────────────────────────┐ │ LLM Backends │ │ Podman Container (ephemeral) │ │ │ │ │ │ Anthropic API (Claude) │ │ ┌──────────────────────────────────┐ │ │ Vertex AI (Claude) │ │ │ Deep Agents (library) + MCP │ │ │ Vertex AI (Gemini) │ │ │ /task.json (task description) │ │ -│ │ │ │ /workspace (repo mounted) │ │ +│ │<->│ │ /workspace (repo mounted) │ │ │ Called by orchestrator │ │ │ commits changes locally │ │ │ nodes and container │ │ └──────────────────────────────────┘ │ │ agents (bidirectional) │ │ │ From 2150db90a1fb897df9ca05bb7e76753fac41fb42 Mon Sep 17 00:00:00 2001 From: Eran Kuris Date: Thu, 16 Jul 2026 17:12:39 +0300 Subject: [PATCH 6/6] Fix architecture diagram per PR review feedback - Convert all diagrams from ASCII art to mermaid (eshulman2) - Move Deep Agents inside Podman Container, not External Systems (StLuke) - Add bidirectional LLM arrows to both Router and Container (StLuke) - Add TaskTakeoverWorkflow (Task/Epic) to system overview and lifecycle (danchild) - Expand Bug workflow implementation path with correct node names - Data Flow Summary as markdown list instead of code block Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/architecture.md | 336 +++++++++++++++++++------------------------ 1 file changed, 145 insertions(+), 191 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 8f6c9469..c5c03059 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,207 +2,161 @@ ## System Overview -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ External Systems │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────────────────────────────┐ │ -│ │ Jira │ │ GitHub │ │ Langfuse (Observability) │ │ -│ └────┬─────┘ └────┬─────┘ └──────────────────────────────────┘ │ -│ │ │ │ -└────────┼──────────────┼─────────────────────────────────────────────────┘ - │ webhooks │ webhooks - v v -┌─────────────────────────────────────────────────────────────────────────┐ -│ FastAPI Server (:8000) │ -│ │ -│ POST /api/v1/webhooks/jira POST /api/v1/webhooks/github │ -│ GET /api/v1/health GET /metrics │ -│ │ -└────────────────────────────┬────────────────────────────────────────────┘ - │ enqueue events - v -┌─────────────────────────────────────────────────────────────────────────┐ -│ Redis │ -│ │ -│ Streams: forge:events:jira State: AsyncRedisSaver │ -│ forge:events:github LangGraph checkpointing │ -│ Consumer group: forge-workers Per-ticket thread IDs (AISOS-123) │ -│ │ -└────────────────────────────┬────────────────────────────────────────────┘ - │ dequeue + dispatch - v -┌─────────────────────────────────────────────────────────────────────────┐ -│ WorkflowRouter │ -│ │ -│ Routes by Jira issue type: │ -│ Feature/Story --> FeatureWorkflow (StateGraph) │ -│ Bug --> BugWorkflow (StateGraph) │ -│ │ -│ ┌──────────────────────────────┐ ┌──────────────────────────────┐ │ -│ │ Feature Workflow │ │ Bug Workflow │ │ -│ │ │ │ │ │ -│ │ generate_prd │ │ triage_check │ │ -│ │ >> prd_approval_gate │ │ >> triage_gate │ │ -│ │ generate_spec │ │ analyze_bug │ │ -│ │ >> spec_approval_gate │ │ <> reflect_rca (up to 3x) │ │ -│ │ decompose_epics │ │ >> rca_option_gate │ │ -│ │ >> plan_approval_gate │ │ plan_bug_fix │ │ -│ │ generate_tasks │ │ >> plan_approval_gate │ │ -│ │ >> task_approval_gate │ │ decompose_plan │ │ -│ │──────────────────────────────│ │──────────────────────────────│ │ -│ │ task_router (per-repo) │ │ Shared impl path: │ │ -│ │ setup_workspace │ │ (same nodes as Feature) │ │ -│ │ implement_task │ │ │ │ -│ │ local_review │ │ Post-merge: │ │ -│ │ update_documentation │ │ post_merge_summary --> END│ │ -│ │ create_pr │ │ │ │ -│ │ teardown_workspace │ └──────────────────────────────┘ │ -│ │──────────────────────────────│ │ -│ │ wait_for_ci_gate │ │ -│ │ ci_evaluator <-- ci_fix │ │ -│ │ >> human_review_gate │ │ -│ │ complete_tasks │ │ -│ │ aggregate_epic_status │ │ -│ │ aggregate_feature_status │ │ -│ │ --> END │ │ -│ └──────────────────────────────┘ │ -│ │ -│ >> = human checkpoint (auto-approved with forge:yolo label) │ -│ │ -└────────────────────────────┬────────────────────────────────────────────┘ - v - ┌──────────────┼──────────────┐ - │ LLM calls │ LLM calls - v v -┌────────────────────────────┐ ┌────────────────────────────────────────┐ -│ LLM Backends │ │ Podman Container (ephemeral) │ -│ │ │ │ -│ Anthropic API (Claude) │ │ ┌──────────────────────────────────┐ │ -│ Vertex AI (Claude) │ │ │ Deep Agents (library) + MCP │ │ -│ Vertex AI (Gemini) │ │ │ /task.json (task description) │ │ -│ │<->│ │ /workspace (repo mounted) │ │ -│ Called by orchestrator │ │ │ commits changes locally │ │ -│ nodes and container │ │ └──────────────────────────────────┘ │ -│ agents (bidirectional) │ │ │ -└────────────────────────────┘ └────────────────────────────────────────┘ +```mermaid +flowchart TD + subgraph External["External Systems"] + Jira + GitHub + Langfuse["Langfuse (Observability)"] + end + + subgraph API["FastAPI Server (:8000)"] + JiraWH["POST /webhooks/jira"] + GitHubWH["POST /webhooks/github"] + end + + subgraph Queue["Redis"] + Streams["Streams: forge:events:jira\nforge:events:github"] + State["AsyncRedisSaver\nLangGraph checkpointing"] + end + + subgraph Router["WorkflowRouter"] + Route{"Route by\nissue type"} + Feature["FeatureWorkflow\n(Feature/Story)"] + Bug["BugWorkflow\n(Bug)"] + Task["TaskTakeoverWorkflow\n(Task/Epic)"] + end + + subgraph Container["Podman Container (ephemeral)"] + Agent["Deep Agents + MCP\n/workspace (repo mounted)"] + end + + LLM["LLM Backends\nAnthropic API (Claude)\nVertex AI (Claude/Gemini)"] + + Jira -- webhooks --> JiraWH + GitHub -- webhooks --> GitHubWH + JiraWH --> Streams + GitHubWH --> Streams + Streams --> Route + Route --> Feature + Route --> Bug + Route --> Task + Feature --> Container + Bug --> Container + Task --> Container + Router <--> LLM + Container <--> LLM + Router --> Jira + Router --> GitHub + Router --> Langfuse ``` ## Feature Ticket Lifecycle -``` -Jira ticket created + labeled "forge:managed" (type: Feature or Story) - | - v -generate_prd -- AI drafts Product Requirements Document - | - v ->> prd_approval_gate -- wait for approval (Jira comment or proposals PR) - | - v -generate_spec -- AI drafts Technical Specification - | - v ->> spec_approval_gate - | - v -decompose_epics -- AI breaks spec into Jira Epics - | - v ->> plan_approval_gate - | - v -generate_tasks -- AI creates implementation Tasks under Epics - | - v ->> task_approval_gate - | - v -task_router -- group tasks by target repo - | - v (per repo) -setup_workspace -- clone repo, create branch - | - v -implement_task -- Podman container + Deep Agents writes code - | - v -local_review -- AI reviews diff, fixes issues (up to 2 passes) - | - v -update_documentation -- update stale docs - | - v -create_pr -- open GitHub PR - | - v -teardown_workspace -- cleanup (loop back if more repos) - | - v -wait_for_ci_gate -- wait for CI checks - | - v -ci_evaluator --+-- pass ------+ - +-- fail ---+ | - | | - attempt_ci_fix | - (up to 5x) | - | | - +-----------+ | - | | - v v ->> human_review_gate -- wait for PR approval - | (changes_requested --> implement_review --> CI loop) - v -complete_tasks --> aggregate_epic_status --> aggregate_feature_status --> END - ->> = human checkpoint (auto-approved when forge:yolo label is set) +```mermaid +flowchart TD + A["Jira ticket created\nforge:managed (Feature/Story)"] --> B[generate_prd] + B --> C[">> prd_approval_gate"] + C --> D[generate_spec] + D --> E[">> spec_approval_gate"] + E --> F[decompose_epics] + F --> G[">> plan_approval_gate"] + G --> H[generate_tasks] + H --> I[">> task_approval_gate"] + I --> J["task_router (per-repo)"] + + J --> K[setup_workspace] + K --> L["implement_task\n(Podman + Deep Agents)"] + L --> M[local_review] + M -->|"needs work (up to 2x)"| L + M --> N[update_documentation] + N --> O[create_pr] + O --> P["teardown_workspace"] + P -->|more repos| K + + P --> Q[wait_for_ci_gate] + Q --> R{ci_evaluator} + R -->|fail| S["attempt_ci_fix\n(up to 5x)"] + S --> Q + R -->|pass| T[">> human_review_gate"] + T -->|changes_requested| U[implement_review] + U --> Q + T -->|approved| V["complete_tasks\naggregate_epic_status\naggregate_feature_status\nEND"] ``` +`>>` = human checkpoint (auto-approved when `forge:yolo` label is set) + ## Bug Ticket Lifecycle +```mermaid +flowchart TD + A["Jira ticket created\nforge:managed (Bug)"] --> B[triage_check] + B -->|missing fields| C[">> triage_gate"] + C --> B + B -->|sufficient| D[analyze_bug] + D --> E["reflect_rca\n(up to 3 cycles)"] + E --> D + D --> F[">> rca_option_gate\nuser selects >option N"] + F --> G[plan_bug_fix] + G --> H[">> plan_approval_gate"] + H --> I[decompose_plan] + + I --> J[setup_workspace] + J --> K["implement_bug_fix\n(Podman + Deep Agents)"] + K --> L[local_review] + L -->|"needs work"| K + L --> M[update_documentation] + M --> N[create_pr] + N --> O[teardown_workspace] + O -->|more repos| J + + O --> P[wait_for_ci_gate] + P --> Q{ci_evaluator} + Q -->|fail| R["attempt_ci_fix"] + R --> P + Q -->|pass| S[">> human_review_gate"] + S -->|changes_requested| T[implement_review] + T --> P + S -->|merged| U[post_merge_summary] + U --> V[END] ``` -Jira ticket created + labeled "forge:managed" (type: Bug) - | - v -triage_check -- validate bug report has required fields - | - v ->> triage_gate -- wait for reporter update if incomplete - | - v -analyze_bug <--+ - | | - +--- reflect_rca (up to 3 reflection cycles) - | - v ->> rca_option_gate -- present fix options, user selects ">option N" - | - v -plan_bug_fix -- AI generates fix plan - | - v ->> plan_approval_gate - | - v -decompose_plan -- break into tasks - | - v -setup_workspace --> implement --> local_review --> create_pr --> CI --> review - | - v -post_merge_summary --> END + +## Task Ticket Lifecycle + +```mermaid +flowchart TD + A["Jira ticket created\nforge:managed (Task/Epic)"] --> B[triage_check] + B -->|missing context| C[">> triage_gate\nforge:task-triage-pending"] + C --> B + B -->|sufficient| D[generate_plan] + D --> E[">> task_plan_approval_gate\nforge:plan-pending"] + E -->|"? question"| F[answer_question] + F --> E + E -->|"! feedback"| D + E -->|approved| G[setup_workspace] + + G --> H["execute_task_changes\n(Podman + Deep Agents)"] + H --> I[qualitative_review] + I -->|"needs work (up to 2x)"| H + I -->|adequate| J[create_pr] + J --> K[teardown_workspace] + K -->|more repos| G + + K --> L[wait_for_ci_gate] + L --> M{ci_evaluator} + M -->|fail| N["attempt_ci_fix"] + N --> L + M -->|pass| O[">> human_review_gate"] + O -->|changes_requested| P[implement_review] + P --> L + O -->|merged| Q[complete_task_takeover] ``` ## Data Flow Summary -``` -Inbound events: Jira/GitHub webhooks --> FastAPI --> Redis Streams -State persistence: Redis (LangGraph AsyncRedisSaver, keyed by ticket) -LLM calls: Orchestrator nodes --> Claude/Gemini (Anthropic / Vertex AI) - Container agents --> Claude/Gemini (same backends) -Code execution: implement_task --> Podman container --> Deep Agents (library) -Outbound actions: Jira (comments, labels, transitions) - GitHub (PRs, branches, reviews) -Observability: Langfuse (LLM traces, workflow spans, costs) -``` +- **Inbound events:** Jira/GitHub webhooks --> FastAPI --> Redis Streams +- **State persistence:** Redis (LangGraph AsyncRedisSaver, keyed by ticket) +- **LLM calls:** Orchestrator nodes and container agents --> Claude/Gemini (Anthropic / Vertex AI), bidirectional +- **Code execution:** implement_task --> Podman container --> Deep Agents (library) +- **Outbound actions:** Jira (comments, labels, transitions), GitHub (PRs, branches, reviews) +- **Observability:** Langfuse (LLM traces, workflow spans, costs)