From 1b4c42ea484b07dc52b03324bb97d62a2aa664bb Mon Sep 17 00:00:00 2001 From: Forge Date: Thu, 3 Sep 2026 11:41:12 +0000 Subject: [PATCH] [AISOS-2497] Correct stale draft-attachment documentation in labels, feature workflow, and developer guide Detailed description: - Replaced references to Jira draft attachments and JSON file serialization/deletion with state-backed durable workflow state in docs/guide/labels.md - Updated docs/guide/feature-workflow.md to align with state-backed draft workflow state tracking for Epic Decomposition and Task Generation stage references, removing draft JSON file references (forge-epics-draft.json/forge-tasks-draft.json) - Updated docs/developer-guide.md to remove the reference to deleting draft attachments from the /forge approve command description - Verified that all draft-attachment documentation is fully up-to-date and accurate Closes: AISOS-2497 --- docs/developer-guide.md | 2 +- docs/guide/feature-workflow.md | 16 ++++++++-------- docs/guide/labels.md | 10 +++++----- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/developer-guide.md b/docs/developer-guide.md index 917f670d..e05d0ab7 100644 --- a/docs/developer-guide.md +++ b/docs/developer-guide.md @@ -879,7 +879,7 @@ These commands are used on the parent Jira ticket during the draft review stages | Command | Effect | Active at | |---------|--------|-----------| -| `/forge approve` | Approve draft, provision sub-tickets, and delete draft attachment | `plan_approval_gate`, `task_approval_gate` | +| `/forge approve` | Approve draft and provision sub-tickets | `plan_approval_gate`, `task_approval_gate` | | `/forge remove ` | Remove a draft item by local sequential ID | `plan_approval_gate`, `task_approval_gate` | | `/forge exclude ` | Toggle the exclusion flag of a draft item | `plan_approval_gate`, `task_approval_gate` | | `/forge update key=val` | Update fields (`summary`, `description`, `repo`) of a draft item | `plan_approval_gate`, `task_approval_gate` | diff --git a/docs/guide/feature-workflow.md b/docs/guide/feature-workflow.md index de0e19f9..8d35d7bc 100644 --- a/docs/guide/feature-workflow.md +++ b/docs/guide/feature-workflow.md @@ -67,7 +67,7 @@ Forge generates a behavioral specification from the approved PRD, typically usin Forge breaks the feature into logical epics — high-level areas of work that map to implementation phases. By default, Forge uses an interactive **Draft Review Flow** at this stage (unless YOLO mode is active): -1. Instead of creating Jira tickets immediately, Forge serializes the proposed epics into `forge-epics-draft.json` and uploads it as an attachment on the Feature ticket. +1. Instead of creating Jira tickets immediately, Forge serializes the proposed epics into state-backed durable workflow state (`plan_draft`). 2. Forge posts a markdown table comment on the Feature ticket outlining the proposed Epics. 3. The workflow pauses at `plan_approval_gate`. @@ -75,10 +75,10 @@ By default, Forge uses an interactive **Draft Review Flow** at this stage (unles | Action | How | Description | |--------|-----|-------------| -| **Approve** | Comment `/forge approve` OR set label to `forge:plan-approved` | Forge provisions the Epic sub-tickets on Jira from the draft, deletes the draft attachment, and advances to Task Generation. | -| **Direct Edit** | Use `/forge` commands (e.g. `/forge update`, `/forge remove`, etc.) | Directly modify the draft attachment and regenerate the proposal comment. See [Jira Labels & Comments](labels.md) for a list of commands. | +| **Approve** | Comment `/forge approve` OR set label to `forge:plan-approved` | Forge provisions the Epic sub-tickets on Jira from the draft, and advances to Task Generation. | +| **Direct Edit** | Use `/forge` commands (e.g. `/forge update`, `/forge remove`, etc.) | Directly modify the draft in durable workflow state and regenerate the proposal comment. See [Jira Labels & Comments](labels.md) for a list of commands. | | **Ask a question** | Comment with `?` prefix or `@forge ask` | Forge answers your question without regenerating the draft. | -| **Request revisions** | Comment with `!` prefix followed by your feedback | Forge uses LLM assistance to revise the entire draft JSON and update the proposal comment with your feedback. | +| **Request revisions** | Comment with `!` prefix followed by your feedback | Forge uses LLM assistance to revise the entire draft in durable workflow state and update the proposal comment with your feedback. | If `forge:yolo` mode is active, the draft review is bypassed. Epics are created in Jira immediately, and the workflow automatically proceeds to Task Generation. @@ -103,7 +103,7 @@ flowchart TD Forge generates granular implementation tasks scoped to individual repositories. Each task is sized to fit in a single container execution pass. By default, Forge uses an interactive **Draft Review Flow** at this stage (unless YOLO mode is active): -1. Instead of creating Jira tickets immediately, Forge serializes the proposed tasks into `forge-tasks-draft.json` and uploads it as an attachment on the Feature ticket. +1. Instead of creating Jira tickets immediately, Forge serializes the proposed tasks into state-backed durable workflow state (`tasks_draft`). 2. Forge posts a markdown table comment on the Feature ticket outlining the proposed Tasks. 3. The workflow pauses at `task_approval_gate`. @@ -111,10 +111,10 @@ By default, Forge uses an interactive **Draft Review Flow** at this stage (unles | Action | How | Description | |--------|-----|-------------| -| **Approve** | Comment `/forge approve` OR set label to `forge:task-approved` | Forge provisions the Task sub-tickets on Jira from the draft, deletes the draft attachment, and advances to Implementation. | -| **Direct Edit** | Use `/forge` commands (e.g. `/forge update`, `/forge remove`, etc.) | Directly modify the draft attachment and regenerate the proposal comment. See [Jira Labels & Comments](labels.md) for a list of commands. | +| **Approve** | Comment `/forge approve` OR set label to `forge:task-approved` | Forge provisions the Task sub-tickets on Jira from the draft, and advances to Implementation. | +| **Direct Edit** | Use `/forge` commands (e.g. `/forge update`, `/forge remove`, etc.) | Directly modify the draft in durable workflow state and regenerate the proposal comment. See [Jira Labels & Comments](labels.md) for a list of commands. | | **Ask a question** | Comment with `?` prefix or `@forge ask` | Forge answers your question without regenerating the draft. | -| **Request revisions** | Comment with `!` prefix followed by your feedback | Forge uses LLM assistance to revise the entire draft JSON and update the proposal comment with your feedback. | +| **Request revisions** | Comment with `!` prefix followed by your feedback | Forge uses LLM assistance to revise the entire draft in durable workflow state and update the proposal comment with your feedback. | If `forge:yolo` mode is active, the draft review is bypassed. Tasks are created in Jira immediately, and the workflow automatically proceeds to Implementation. diff --git a/docs/guide/labels.md b/docs/guide/labels.md index 66f86af6..285004f4 100644 --- a/docs/guide/labels.md +++ b/docs/guide/labels.md @@ -45,7 +45,7 @@ Standalone Tasks and Epics can be processed with the standard `forge:managed` la | `forge:blocked` | Set by Forge when a stage fails. Forge posts a comment with the error. | | `forge:retry` | Add this to resume from the exact node that failed, or to transition from `review_response_gate` back to `human_review_gate` (clearing contested review comments). Forge removes it after resuming. | | `forge:yolo` | Auto-approve supported planning gates. Human PR review still remains a gate. | -| `forge:direct-mode` | Direct ticket creation mode (bypasses draft JSON attachments and creates Epic/Task tickets immediately in Jira), but still pauses for human approval at the planning gates (instead of auto-approving like `forge:yolo`). | +| `forge:direct-mode` | Direct ticket creation mode (bypasses interactive draft review flow and creates Epic/Task tickets immediately in Jira), but still pauses for human approval at the planning gates (instead of auto-approving like `forge:yolo`). | | `repo:/` | Identifies repositories selected for planning and implementation. | ## How to Use Labels @@ -55,10 +55,10 @@ Standalone Tasks and Epics can be processed with the standard `forge:managed` la **Approving a stage:** When Forge posts an artifact (such as a PRD or Spec), it sets the `forge:*-pending` label. You can approve it by changing the label to `forge:*-approved` to advance the workflow. For draft-based stages (Epic Plan and Tasks), you can also approve by commenting `/forge approve` on the ticket. **Interactive Draft Review:** For Epic Decomposition and Task Generation stages, Forge uses a draft-based review flow by default (unless `forge:yolo` or `forge:direct-mode` mode is active). -1. Instead of creating sub-tickets immediately, Forge serializes the proposed items into a JSON draft file (`forge-epics-draft.json` or `forge-tasks-draft.json`) and uploads it as a Jira attachment. +1. Instead of creating sub-tickets immediately, Forge serializes the proposed items into state-backed durable workflow state (`plan_draft` or `tasks_draft`). 2. Forge posts a formatted markdown table comment on the ticket detailing the proposed plan. 3. While the stage is pending, you can modify the draft directly using **Jira comment commands** (see below) or request a natural language revision. -4. Once you approve (via `/forge approve` or setting the approved label), Forge downloads the draft, provisions the actual Jira tickets from it, and deletes the draft attachment. +4. Once you approve (via `/forge approve` or setting the approved label), Forge loads the draft from state, and provisions the actual Jira tickets from it. ### Jira Comment Commands @@ -66,7 +66,7 @@ For stages using the draft-based review flow (Epic Plan and Tasks), you can post | Command | Description | Example | |---------|-------------|---------| -| `/forge approve` | Approve the draft, provision all non-excluded items as Jira tickets, and delete the draft attachment. | `/forge approve` | +| `/forge approve` | Approve the draft, and provision all non-excluded items as Jira tickets. | `/forge approve` | | `/forge remove ` | Remove a draft item by its local sequential ID. Remaining items are automatically re-sequenced. | `/forge remove 3` | | `/forge exclude ` | Toggle the exclusion flag of a draft item. Excluded items are skipped during ticket provisioning. | `/forge exclude 2` | | `/forge update key=val` | Update fields of a draft item (supported keys: `summary`, `description`, `repo`). | `/forge update 1 repo="my-org/custom-repo"` | @@ -74,7 +74,7 @@ For stages using the draft-based review flow (Epic Plan and Tasks), you can post *Note: Successful command/revision comments are automatically edited by Forge to prepend `✅`. If a command or revision fails, Forge posts a comment detailing the error with a leading `❌`.* -**Requesting revisions:** Start a comment with `!` followed by your feedback (e.g., `! update the repositories to use the new service`). For standard artifacts, Forge regenerates them. For drafts, Forge uses LLM assistance to revise the draft JSON attachment and update the proposed plan table. +**Requesting revisions:** Start a comment with `!` followed by your feedback (e.g., `! update the repositories to use the new service`). For standard artifacts, Forge regenerates them. For drafts, Forge uses LLM assistance to revise the draft in state-backed durable workflow state and update the proposed plan table. **Asking questions:** Start a comment with `?` or `@forge ask`. Forge answers without advancing or regenerating/modifying the drafts.