Skip to content

delivery.md

Latest commit

 

History

History
169 lines (119 loc) · 6.94 KB

delivery.md

File metadata and controls

169 lines (119 loc) · 6.94 KB

Delivery Pipeline

Overview

When all beads pass review — and goal-level review passes, if configured — the delivery phase runs. This is the final stage of a goal's lifecycle: the moment working code becomes a PR, a ticket update, or whatever your team's definition of "done" looks like.

Delivery is a configurable lifecycle hook. Describe your pipeline in natural language and orc executes it. When unconfigured, the goal branch is simply presented for your manual inspection.

Two Modes

Configured delivery

When on_completion_instructions is set, the goal orchestrator executes your delivery pipeline automatically after the final review passes.

[delivery.goal]
on_completion_instructions = "Push the goal branch and create a PR targeting main."

The goal orchestrator interprets your instructions and runs the appropriate commands (git push, gh pr create, ticket API calls, etc.). You describe the outcome; orc figures out the mechanics.

Manual review (default)

When on_completion_instructions is empty (the default), the goal branch is presented for your inspection in the tmux session. You review the branch, provide feedback, or merge manually. This is the safest starting point — nothing leaves the local machine until you say so.

Configuring Your Pipeline

The on_completion_instructions field accepts natural language. Describe as little or as much as your workflow requires.

Simple PR:

[delivery.goal]
on_completion_instructions = "Push the goal branch and create a PR targeting main."

PR with ticket update:

[delivery.goal]
on_completion_instructions = """
  Push the goal branch and create a PR targeting develop.
  Move the Jira ticket to In Code Review.
"""

Full pipeline:

[delivery.goal]
on_completion_instructions = """
  Push the goal branch and create a PR targeting develop.
  Move the Jira ticket to In Code Review.
  Archive the openspec change directory.
  Post a summary to the #engineering Slack channel.
"""

Each step is executed in order. If a step requires a tool the project does not have (e.g., a Slack MCP), the goal orchestrator skips it and reports what it could not do.

User Involvement

The when_to_involve_user_in_delivery field is a gate --- it controls when orc pauses for your approval before executing the delivery pipeline. It is not an action field. Do not put post-delivery behavior here (like "notify the user with the PR URL") --- that belongs in on_completion_instructions.

[delivery.goal]
when_to_involve_user_in_delivery = "when the PR targets main or involves breaking changes"
Value Behavior
"" (empty) Default. Always pause for approval before delivery.
"never" Full autonomy. Delivery executes without confirmation.
Natural language condition Orc evaluates the condition and pauses only when it applies.

Examples:

  • "always" — explicit version of the default behavior.
  • "when the goal touches more than 5 files"
  • "when the PR targets main or a release branch"
  • "never" — combine with YOLO mode for full automation.

Notifying the User

If you want the goal orchestrator to notify the user after delivery completes (for example, with a PR URL), include that as the last step of on_completion_instructions:

[delivery.goal]
on_completion_instructions = """
  Push the goal branch and create a PR targeting develop.
  Notify the user with the PR URL.
"""

This keeps all delivery actions in one place. The when_to_involve_user_in_delivery gate controls whether to pause before delivery runs --- it does not handle post-delivery notifications.

Branching

The [branching] strategy field controls how goal branches are named. Branch names are derived from the goal description, filtered through your strategy.

[branching]
strategy = "use Jira ticket prefix like PROJ-123, then kebab-case summary"

When empty, orc uses sensible defaults: feat/, fix/, or task/ prefixes with a kebab-case summary.

Pattern Config value
Default prefixes "" (empty)
Jira tickets "use Jira ticket prefix like PROJ-123, then kebab-case summary"
Team namespacing "always prefix with team name: platform/"
Gitflow "gitflow: feature branches from develop"
Linear issues "prefix with Linear issue ID like ENG-42"

Ticket Integration

The [tickets] strategy field keeps external issue trackers in sync with orc's lifecycle. This is a project-level concern — set it in {project}/.orc/config.toml, not globally.

[tickets]
strategy = "Move Jira tickets to In Progress when goals start, Done when complete"

When configured, orchestrators automatically update linked tickets at lifecycle moments:

Event What happens
Goal created Ticket moved to In Progress (or equivalent).
Progress made Comment added with branch name and status.
Goal delivered Ticket moved to Done / closed with PR link.
Blocker hit Ticket flagged or comment added with blocker details.

Ticket integration requires the project to have a skill or MCP for the ticketing system (Jira, Linear, GitHub Issues, etc.). Without one, the strategy is ignored.

Examples:

strategy = "Move Jira tickets to In Progress when goals start, Done when complete"
strategy = "Add a comment to Linear issues with the goal branch name and progress updates"
strategy = "Update GitHub issues: In Progress on start, close with PR link on delivery"

Combining with YOLO Mode

For a fully hands-off pipeline, combine configured delivery with --yolo mode:

orc myapp --yolo
# Goals are planned, engineers are dispatched, reviews run automatically,
# and PRs are created — all without confirmation prompts.
# You come back to open PRs ready for your review.

YOLO mode skips all confirmation prompts. Paired with on_completion_instructions and when_to_involve_user_in_delivery = "never", you get end-to-end automation from request to PR. See YOLO Mode for details and safeguards.

Common Patterns

Pattern Config Result
Manual review on_completion_instructions = "" Goal branch presented in tmux for inspection.
Simple PR "Push and create a PR targeting main" Branch pushed, PR opened.
PR + tickets "Push, create PR to develop, move Jira ticket to Code Review" Branch pushed, PR opened, ticket updated.
Full pipeline "Push, PR to develop, update Jira, archive specs, notify Slack" Complete CI/CD-adjacent automation.
YOLO + PR Above + --yolo + when_to_involve_user_in_delivery = "never" Fully autonomous from request to PR.

See also: Configuration for all delivery and branching fields, Review for the review loop that gates delivery, YOLO Mode for hands-off operation, Planning for what happens before engineers are dispatched.