Feature Workflow¶

Forge orchestrates features through a multi-stage pipeline with human approval gates at each planning step and automated execution for implementation.

Overview¶

flowchart TD
    subgraph Planning
        A[Create Feature] --> B[Generate PRD]
        B -->|Approval| C[Generate Spec]
        C -->|Approval| D[Decompose Epics]
        D -->|Approval| E[Generate Tasks]
    end

    subgraph Implementation
        E -->|Approval| F[Implement in Container]
        F --> G[Local Code Review]
        G --> H[Create PR]
    end

    subgraph Validation
        H --> I[CI/CD Pipeline]
        I -->|Failure| J[AI Fix Loop]
        J --> I
        I -->|Pass| K[AI Review]
        K --> L[Human Review]
    end

    L -->|Approved| M[Merge]
    L -->|Changes| F

Triggering a Workflow¶

Create a Jira issue with the forge:managed label. Forge listens for Jira webhooks and starts the pipeline automatically.

Stage Reference¶

PRD Generation¶

Forge reads the ticket description and generates a structured Product Requirements Document. The PRD is posted as a comment on the Jira ticket.

Human action: Review the PRD. Optionally ask questions with ? prefix (see Q&A Mode). When satisfied, change the label to forge:prd-approved.

Spec Generation¶

Forge generates a behavioral specification from the approved PRD, typically using Given/When/Then acceptance criteria.

Human action: Review the spec. Ask questions with ? or request revisions with !. Approve with forge:spec-approved.

Epic Decomposition¶

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 stores the proposed epics in durable workflow state. 2. Forge posts a markdown table comment on the Feature ticket outlining the proposed Epics. The comment is a review view; the workflow checkpoint is the authoritative draft. 3. The workflow pauses at plan_approval_gate.

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

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.

If forge:direct-mode is active, the draft review is also bypassed and Epics are created in Jira immediately, but the workflow still pauses at the plan_approval_gate waiting for manual human approval (via label or commands) before proceeding.

flowchart TD
    Gate([plan_approval_gate])
    Gate -->|forge:plan-approved or /forge approve| Next[Generate Tasks]
    Gate -->|"? on feature ticket"| QA[Answer Question]
    Gate -->|"! on feature ticket"| Regen[Regenerate All Epics]
    Gate -->|"/forge update/remove/exclude/add"| Update[Modify Draft]
    QA --> Gate
    Regen --> Gate
    Update --> Gate

Task Generation¶

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 stores the proposed tasks in durable workflow state. 2. Forge posts a markdown table comment on the Feature ticket outlining the proposed Tasks. The comment is a review view; the workflow checkpoint is the authoritative draft. 3. The workflow pauses at task_approval_gate.

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

If forge:yolo mode is active, the draft review is bypassed. Tasks are created in Jira immediately, and the workflow automatically proceeds to Implementation.

If forge:direct-mode is active, the draft review is also bypassed and Tasks are created in Jira immediately, but the workflow still pauses at the task_approval_gate waiting for manual human approval (via label or commands) before proceeding.

flowchart TD
    Gate([task_approval_gate])
    Gate -->|forge:task-approved or /forge approve| Next[Implement Tasks]
    Gate -->|"? on ticket"| QA[Answer Question]
    Gate -->|"! on feature/epic"| Regen[Regenerate All Tasks]
    Gate -->|"/forge update/remove/exclude/add"| Update[Modify Draft]
    QA --> Gate
    Regen --> Gate
    Update --> Gate

Implementation¶

When implementation starts, Forge sets up the workspace, posts a progress comment to Jira, sets the forge:implementing label, and automatically transitions all associated Tasks and Epics, as well as the parent Epic (if present), to In Progress status in Jira.

Tasks are executed in ephemeral Podman containers. Each container:

• Clones the target repository
• Reads the task file
• Writes code, runs tests, commits
• Has no external network access

The orchestrator handles push and PR creation.

Local Code Review¶

After implementation and before PR creation, Forge reviews the diff against main and fixes any breaking issues in-place (up to 2 passes).

PR Creation¶

A fork-based pull request is created with an AI-generated description. The PR body is kept in sync with commits throughout the CI fix loop.

CI/CD + Fix Loop¶

Forge waits for CI results via GitHub webhooks. On failure:

1. Analyze — categorizes the failure using the analyze-ci skill
2. Fix — implements a fix in-place using the fix-ci skill
3. Review — reviews the fix before pushing
4. Repeat up to 5 times

Each fix pass re-syncs the PR description. After CI passes, Forge proceeds to AI review.

To skip an infrastructure-related check, see PR Commands.

AI Review¶

Forge reviews the completed PR against the original spec, checking for completeness and correctness.

Human Review¶

The PR is now ready for human review. Merge when satisfied, or request changes to trigger another implementation pass.

Once the PR is merged, Forge automatically completes the workflow by transitioning the Feature, all associated Tasks and Epics, and its parent Epic (if present) to Closed status in Jira.

Q&A Mode¶

At any approval gate, you can ask questions without triggering regeneration:

? Why did you choose this approach over X?

@forge ask explain the auth strategy

Forge answers based on the artifact content and generation context, then keeps the workflow paused. When you're ready to approve, change the label as normal.

A summary of all Q&A exchanges is posted to the ticket when you approve.

Requesting Revisions¶

Start a comment with ! followed by your feedback. Forge regenerates the current artifact incorporating your feedback, replacing the previous version.

! The spec is missing error handling for the webhook retry path

Handling Failures¶

If a stage fails, Forge:

1. Sets the forge:blocked label
2. Posts a comment tagging the reporter and assignee with the error

To retry, add the forge:retry label. Forge resumes from the exact node that failed — not from the beginning. For an unresolved provider write, conflicting event, or effect replay, inspect the operations guide before retrying.

Labels Summary¶

See Jira Labels for the complete reference.