From 2481c449a5697fa00c4d64f4d79281b03fa77969 Mon Sep 17 00:00:00 2001 From: Forge Date: Tue, 14 Jul 2026 14:28:26 +0000 Subject: [PATCH 1/6] [AISOS-2161] Update documentation homepage to support all workflows equally Detailed description: - Updated the Forge documentation home page (docs/index.md) to clearly highlight all three supported workflows (Feature, Bug, and Task workflows) with equal prominence. - Replaced the single-workflow diagram with a comprehensive diagram representing all three entrypoints and processing paths leading to implementation and delivery. - Added a dedicated 'Supported Workflows' section with clear 'When to use' descriptions and relative links to their respective detailed guide markdown files. - Preserved a prominent path for first-time users to get started. - Created and executed a new test file tests/unit/test_docs_homepage.py to verify structure and links. Closes: AISOS-2161 --- docs/index.md | 64 ++++++++++++++++++++++++++------ tests/unit/test_docs_homepage.py | 31 ++++++++++++++++ 2 files changed, 84 insertions(+), 11 deletions(-) create mode 100644 tests/unit/test_docs_homepage.py diff --git a/docs/index.md b/docs/index.md index 80480903..893b8c50 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,21 +1,43 @@ # Forge -Forge automates the software development lifecycle from feature ideation through code delivery using AI-powered planning and execution. It connects Jira, GitHub, and Claude to transform tickets into shipped code with human approval gates at each stage. +Forge automates the software development lifecycle from ticket creation through code delivery using AI-powered planning and execution. It connects Jira, GitHub, and Claude to transform tickets into shipped code with human approval gates at each stage. + +Forge supports three distinct, user-facing workflows depending on your ticket type and project requirements. ## How It Works ```mermaid graph TD - A[Create Feature] --> B[Generate PRD] - B -->|Approval| C[Generate Spec] - C -->|Approval| D[Decompose Epics] - D -->|Approval| E[Generate Tasks] - E -->|Approval| F[Implement Code] - F --> G[Local Review] - G --> H[Create PR] - H --> I[CI/CD + Fix] - I --> J[AI Review] - J --> K[Human Review] + %% Workflow entrypoints + subgraph "1. Choose Your Workflow" + Feature[Jira Epic/Story
Feature Workflow] + Bug[Jira Bug
Bug Workflow] + Task[Jira Task
Task Workflow] + end + + %% Workflow processing paths + subgraph "2. Automated Planning & Diagnosis" + PRD[Generate PRD & Spec] + RCA[Generate Root Cause Analysis & Plan] + Takeover[Triage & Task Takeover Planning] + end + + %% Common implementation & delivery path + subgraph "3. Execution & Delivery" + Code[Autonomous Containerized Implementation] + Review[CI & AI/Human Code Review] + end + + %% Connections + Feature --> PRD + Bug --> RCA + Task --> Takeover + + PRD --> Code + RCA --> Code + Takeover --> Code + + Code --> Review ``` ## Quick Links @@ -28,6 +50,26 @@ graph TD - [Skills System](skills/index.md) — Customize Forge for your stack - [Contributing](dev/contributing.md) — How to contribute +## Supported Workflows + +### 🚀 Feature Workflow +Used for long-term or large-scale product changes where requirements need detailed definition and structural design before writing code. +* **Process**: Progresses from initial Jira Feature to automated PRD generation, Technical Spec creation, Epic decomposition, and task implementation with rigorous human review gates at every planning step. +* **When to use**: Choose this workflow for net-new features, substantial architectural modifications, or projects requiring collaborative product/engineering alignment on requirements before any code is touched. +* **More Info**: Read the [Feature Workflow Guide](guide/feature-workflow.md). + +### 🐛 Bug Workflow +Designed specifically for triaging, diagnosing, and resolving software defects efficiently. +* **Process**: Forge reproduces the issue inside an isolated sandbox, automatically drafts a detailed Root Cause Analysis (RCA) presenting alternative fix options, generates a concrete fix plan upon option selection, and implements the verified fix. +* **When to use**: Choose this workflow for reported bugs, unexpected crashes, test regressions, or any ticket where the root cause is unknown or multiple fix strategies need to be evaluated first. +* **More Info**: Read the [Bug Workflow Guide](guide/bug-workflow.md). + +### 🛠️ Task Workflow +Tailored for already-scoped, standalone tickets or task takeovers that bypass the extended feature planning and decomposition phases. +* **Process**: Forge takes existing, clear engineering instructions directly from a Jira Task or Epic, generates a direct implementation plan, executes the changes in a sandbox, repairs CI, and opens a review-ready Pull Request. +* **When to use**: Choose this workflow for well-defined engineering chores, minor refactors, simple library upgrades, or whenever the technical implementation steps are already pre-determined and agreed upon. +* **More Info**: Read the [Task Workflow Guide](guide/task-workflow.md). + ## Key Features **AI-Powered Planning** diff --git a/tests/unit/test_docs_homepage.py b/tests/unit/test_docs_homepage.py new file mode 100644 index 00000000..6b42c8eb --- /dev/null +++ b/tests/unit/test_docs_homepage.py @@ -0,0 +1,31 @@ +import os +import re + +def test_docs_homepage_structure_and_links(): + """Verify the docs/index.md structure, content, and the presence of critical workflow links.""" + index_path = "/workspace/docs/index.md" + assert os.path.exists(index_path), "docs/index.md does not exist" + + with open(index_path, "r", encoding="utf-8") as f: + content = f.read() + + # Verify each workflow is mentioned with its specific emoji and header structure + assert "### 🚀 Feature Workflow" in content, "Feature Workflow section missing" + assert "### 🐛 Bug Workflow" in content, "Bug Workflow section missing" + assert "### 🛠️ Task Workflow" in content, "Task Workflow section missing" + + # Verify that the correct guide links are present in the Supported Workflows description + assert "guide/feature-workflow.md" in content, "Link to guide/feature-workflow.md is missing" + assert "guide/bug-workflow.md" in content, "Link to guide/bug-workflow.md is missing" + assert "guide/task-workflow.md" in content, "Link to guide/task-workflow.md is missing" + assert "getting-started.md" in content, "Getting started link is missing" + + # Verify all references exist on filesystem + links = re.findall(r"\]\(([^)]+)\)", content) + for link in links: + # Ignore external links if any, only check local relative markdown files + if not link.startswith("http") and link.endswith(".md"): + # Clean anchors + link_clean = link.split("#")[0] + target_path = os.path.join("/workspace/docs", link_clean) + assert os.path.exists(target_path), f"Linked file does not exist: {target_path}" From 49f2cf0d4509b72173be23427bd8293f746c8cad Mon Sep 17 00:00:00 2001 From: Forge Date: Tue, 14 Jul 2026 14:30:04 +0000 Subject: [PATCH 2/6] [AISOS-2161-review] Review task takeover changes for AISOS-2161 Auto-committed by Forge container fallback. --- Pipfile | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 Pipfile diff --git a/Pipfile b/Pipfile new file mode 100644 index 00000000..a9fe832a --- /dev/null +++ b/Pipfile @@ -0,0 +1,11 @@ +[[source]] +url = "https://pypi.org/simple" +verify_ssl = true +name = "pypi" + +[packages] + +[dev-packages] + +[requires] +python_version = "3.14" From dc961c919fa316052596ae9d45253438b6d45df4 Mon Sep 17 00:00:00 2001 From: Forge Date: Tue, 14 Jul 2026 14:38:16 +0000 Subject: [PATCH 3/6] [AISOS-2161-ci-fix] Resolve docs homepage test hardcoded paths Detailed description: - Replaced the hardcoded absolute path '/workspace/docs/index.md' in tests/unit/test_docs_homepage.py with a dynamically resolved absolute path based on the directory location of the test file. - Ensures the test correctly locates documentation files relative to the project root in diverse virtualized/local environment setups. Closes: AISOS-2161-ci-fix --- tests/unit/test_docs_homepage.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tests/unit/test_docs_homepage.py b/tests/unit/test_docs_homepage.py index 6b42c8eb..31f8aa32 100644 --- a/tests/unit/test_docs_homepage.py +++ b/tests/unit/test_docs_homepage.py @@ -3,8 +3,9 @@ def test_docs_homepage_structure_and_links(): """Verify the docs/index.md structure, content, and the presence of critical workflow links.""" - index_path = "/workspace/docs/index.md" - assert os.path.exists(index_path), "docs/index.md does not exist" + base_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) + index_path = os.path.join(base_dir, "docs", "index.md") + assert os.path.exists(index_path), f"docs/index.md does not exist at {index_path}" with open(index_path, "r", encoding="utf-8") as f: content = f.read() @@ -27,5 +28,5 @@ def test_docs_homepage_structure_and_links(): if not link.startswith("http") and link.endswith(".md"): # Clean anchors link_clean = link.split("#")[0] - target_path = os.path.join("/workspace/docs", link_clean) + target_path = os.path.join(base_dir, "docs", link_clean) assert os.path.exists(target_path), f"Linked file does not exist: {target_path}" From 91cc88b7e54b2de2b732a3b2639483b8a0c2b9e1 Mon Sep 17 00:00:00 2001 From: Forge Date: Tue, 14 Jul 2026 14:41:38 +0000 Subject: [PATCH 4/6] [AISOS-2161-review-ci-fix-1] Post-ci-fix-1 code review and formatting Detailed description: - Added explicit type annotations to tests/unit/test_docs_homepage.py to fully satisfy Mypy type-checking requirements. - Addressed code style issues identified by Ruff, including unused modes in file opens, trailing spaces, and sorted imports. - Performed verification using local test execution. Closes: AISOS-2161-review-ci-fix-1 --- tests/unit/test_docs_homepage.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tests/unit/test_docs_homepage.py b/tests/unit/test_docs_homepage.py index 31f8aa32..93e957bc 100644 --- a/tests/unit/test_docs_homepage.py +++ b/tests/unit/test_docs_homepage.py @@ -1,13 +1,14 @@ import os import re -def test_docs_homepage_structure_and_links(): + +def test_docs_homepage_structure_and_links() -> None: """Verify the docs/index.md structure, content, and the presence of critical workflow links.""" base_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) index_path = os.path.join(base_dir, "docs", "index.md") assert os.path.exists(index_path), f"docs/index.md does not exist at {index_path}" - - with open(index_path, "r", encoding="utf-8") as f: + + with open(index_path, encoding="utf-8") as f: content = f.read() # Verify each workflow is mentioned with its specific emoji and header structure From cdb140d3c31b653668fd75373db221b35778a578 Mon Sep 17 00:00:00 2001 From: Forge Date: Wed, 15 Jul 2026 08:52:00 +0000 Subject: [PATCH 5/6] [AISOS-2161] review: address PR feedback --- docs/index.md | 2 +- tests/unit/test_docs_homepage.py | 33 -------------------------------- 2 files changed, 1 insertion(+), 34 deletions(-) delete mode 100644 tests/unit/test_docs_homepage.py diff --git a/docs/index.md b/docs/index.md index 893b8c50..fcac42a1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,7 @@ Forge supports three distinct, user-facing workflows depending on your ticket ty graph TD %% Workflow entrypoints subgraph "1. Choose Your Workflow" - Feature[Jira Epic/Story
Feature Workflow] + Feature[Jira Feature/Story
Feature Workflow] Bug[Jira Bug
Bug Workflow] Task[Jira Task
Task Workflow] end diff --git a/tests/unit/test_docs_homepage.py b/tests/unit/test_docs_homepage.py deleted file mode 100644 index 93e957bc..00000000 --- a/tests/unit/test_docs_homepage.py +++ /dev/null @@ -1,33 +0,0 @@ -import os -import re - - -def test_docs_homepage_structure_and_links() -> None: - """Verify the docs/index.md structure, content, and the presence of critical workflow links.""" - base_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..")) - index_path = os.path.join(base_dir, "docs", "index.md") - assert os.path.exists(index_path), f"docs/index.md does not exist at {index_path}" - - with open(index_path, encoding="utf-8") as f: - content = f.read() - - # Verify each workflow is mentioned with its specific emoji and header structure - assert "### 🚀 Feature Workflow" in content, "Feature Workflow section missing" - assert "### 🐛 Bug Workflow" in content, "Bug Workflow section missing" - assert "### 🛠️ Task Workflow" in content, "Task Workflow section missing" - - # Verify that the correct guide links are present in the Supported Workflows description - assert "guide/feature-workflow.md" in content, "Link to guide/feature-workflow.md is missing" - assert "guide/bug-workflow.md" in content, "Link to guide/bug-workflow.md is missing" - assert "guide/task-workflow.md" in content, "Link to guide/task-workflow.md is missing" - assert "getting-started.md" in content, "Getting started link is missing" - - # Verify all references exist on filesystem - links = re.findall(r"\]\(([^)]+)\)", content) - for link in links: - # Ignore external links if any, only check local relative markdown files - if not link.startswith("http") and link.endswith(".md"): - # Clean anchors - link_clean = link.split("#")[0] - target_path = os.path.join(base_dir, "docs", link_clean) - assert os.path.exists(target_path), f"Linked file does not exist: {target_path}" From 8399e92324d22dfa80e487cf6ca0e428b10591be Mon Sep 17 00:00:00 2001 From: Forge Date: Wed, 15 Jul 2026 10:05:57 +0000 Subject: [PATCH 6/6] [AISOS-2161] review: address PR feedback --- Pipfile | 11 ----------- docs/index.md | 4 ++-- 2 files changed, 2 insertions(+), 13 deletions(-) delete mode 100644 Pipfile diff --git a/Pipfile b/Pipfile deleted file mode 100644 index a9fe832a..00000000 --- a/Pipfile +++ /dev/null @@ -1,11 +0,0 @@ -[[source]] -url = "https://pypi.org/simple" -verify_ssl = true -name = "pypi" - -[packages] - -[dev-packages] - -[requires] -python_version = "3.14" diff --git a/docs/index.md b/docs/index.md index fcac42a1..65c6d56e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,8 +17,8 @@ graph TD %% Workflow processing paths subgraph "2. Automated Planning & Diagnosis" - PRD[Generate PRD & Spec] - RCA[Generate Root Cause Analysis & Plan] + PRD[Generate PRD & Spec
with Epic & Task Decomposition] + RCA[Generate Root Cause Analysis
& Option Selection / Fix Plan] Takeover[Triage & Task Takeover Planning] end