Skip to content

[AISOS-2496] Test Forge bug workflow: correct stale draft-attachment documentation #338

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
forgeSmith-bot wants to merge 1 commit into from
Closed

[AISOS-2496] Test Forge bug workflow: correct stale draft-attachment documentation #338

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/developer-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <ID>` | Remove a draft item by local sequential ID | `plan_approval_gate`, `task_approval_gate` |
| `/forge exclude <ID>` | Toggle the exclusion flag of a draft item | `plan_approval_gate`, `task_approval_gate` |
| `/forge update <ID> key=val` | Update fields (`summary`, `description`, `repo`) of a draft item | `plan_approval_gate`, `task_approval_gate` |
Expand Down
16 changes: 8 additions & 8 deletions docs/guide/feature-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,18 +67,18 @@ 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`.

**Human action:** Review the epic plan draft. You have several options at this stage:

| 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.

Expand All @@ -103,18 +103,18 @@ 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`.

**Human action:** Review the task draft. You have several options at this stage:

| 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.

Expand Down
10 changes: 5 additions & 5 deletions docs/guide/labels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:<owner>/<repo>` | Identifies repositories selected for planning and implementation. |

## How to Use Labels
Expand All @@ -55,26 +55,26 @@ 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

For stages using the draft-based review flow (Epic Plan and Tasks), you can post comments on the parent ticket with the following commands:

| 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 <ID>` | Remove a draft item by its local sequential ID. Remaining items are automatically re-sequenced. | `/forge remove 3` |
| `/forge exclude <ID>` | Toggle the exclusion flag of a draft item. Excluded items are skipped during ticket provisioning. | `/forge exclude 2` |
| `/forge update <ID> key=val` | Update fields of a draft item (supported keys: `summary`, `description`, `repo`). | `/forge update 1 repo="my-org/custom-repo"` |
| `/forge add key=val` | Add a new proposed item to the draft. | `/forge add summary="New Story" repo="my-org/repo"` |

*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.

Expand Down
Loading