Executing Plans

Executing Plans

Backing Status () — NON-RUNNABLE via canonical event-bus dispatch

This skill has no deterministic node backing and is de-listed from event-bus / node-routed dispatch — deliberately, by design. Its generated orchestrator shell (node_skill_executing_plans_orchestrator) is a Polly-passthrough (maturity: stub in its contract.yaml), and no CLI or platform-service implementation exists elsewhere. Reviewing a plan, verifying live PR state, and routing to epic_team/ticket_pipeline is a Claude-session-native decision today.

The ticket-count routing decision (>=3 tickets → epic_team, else ticket_pipeline) is a plausible future COMPUTE-node extraction — tracked in — but the plan review and downstream dispatch stay session-native regardless.

Dispatch Surface

Target: Agent Teams

Overview

Load a plan file, review it critically, create Linear tickets from it, then route to the appropriate execution skill based on ticket count.

Core principle: Linear-native routing. Plans become tickets; tickets drive execution.

Announce at start: "I'm using the executing-plans skill to implement this plan."

Arguments

Execution Flow

Plan Review

Load the plan file and review it critically before taking any action.

Plan file: If a plan path was passed as a positional argument (e.g., from design-to-plan Phase 3), use it directly. Do not re-discover or re-summarize the plan.

1. Read the plan file in full
2. Identify any concerns:
   • Missing acceptance criteria or definition of done
   • Ambiguous or contradictory requirements
   • Unclear dependencies between phases
   • Missing repo label (required for architecture validation)
   • Steps that reference external systems or secrets not yet available
3. If concerns exist: raise them with your human partner and wait for resolution before proceeding
4. If no concerns: proceed to live state verification

Do not proceed to ticket creation if the plan has unresolved questions.

Live State Verification

If the plan references existing PRs or branches, verify their live state before proceeding. Plans often assume a PR is open and mergeable, but reality may have changed since the plan was written.

Delegate PR-state lookup to the repository lifecycle node or the session's approved repository tool surface. The skill records the outcome only; it does not embed direct GitHub CLI calls or PR iteration logic.

Classification and action:

Rules:

• Only poll for PENDING state; all other states are immediately actionable or blocking.
• Never wait more than 90 seconds total for pending checks.
• If the plan does not reference any PRs or branches, skip this check entirely.
• After verification, proceed to dry-run preview.

Linear Availability Check

Before ticket creation, verify Linear MCP availability (see _shared/linear-availability-check.md):

1. Call tracker.list_teams
2. If unavailable (or --local flag is set):
   • Log: "Linear MCP unavailable — entering local ticket mode"
   • Still run plan structure validation (task parsing, dependency check). Skip only the Linear-specific dry-run preview.
   • Skip ticket creation entirely.
   • At routing time: parse the plan directly and dispatch bounded implementation work by task section. Do NOT dispatch onex:ticket-work or onex:ticket-pipeline — they require Linear ticket_id.
   • Create local ticket YAML files per _shared/linear-availability-check.md
3. If available: proceed with normal ticket creation and routing.

Dry-Run Preview

Call onex:plan-to-tickets with --dry-run to preview what tickets would be created.

/plan-to-tickets <plan-file> --dry-run [--repo <repo-label>] [--project <project>]

Review the dry-run output:

• Confirm the detected structure — expect task_sections for plans produced by design-to-plan (## Task N: headers); other valid types: phase_sections (legacy ## Phase N:), numbered_h2, step_sections, milestone_table, priority_labels. If dry-run reports task_sections, that is correct — do NOT ask the user to reformat.
• Confirm the epic title that would be used
• Confirm the list of tickets that would be created
• Check that dependencies are correctly detected

If the preview looks wrong, stop and discuss with your partner before creating tickets.

Ticket Creation

Call onex:plan-to-tickets (without --dry-run) to create the Linear tickets under the epic.

/plan-to-tickets <plan-file> [--repo <repo-label>] [--project <project>] [--skip-existing]

After creation, record:

• The epic identifier (e.g., OMN-XXXX)
• The list of created ticket identifiers
• The total ticket count

Common flags:

• --repo <label> — enables architecture dependency validation (recommended)
• --project <name> — assigns tickets to a Linear project
• --skip-existing — skip tickets that already exist instead of prompting
• --no-create-epic — fail if the epic does not already exist

Execution Routing

Compute routing from the plan file content, not just ticket count:

Log the routing decision: "Routing to {skill} because: {reason}"

epic-team route

/epic-team <epic-id>

epic-team orchestrates a team of parallel worker agents, one per repo. It handles ticket assignment, worktree creation, and lifecycle notifications automatically.

ticket-pipeline route

/ticket-pipeline <ticket-id>

Run onex:ticket-pipeline on the selected ticket sequence. Each pipeline handles the full implement → review → PR → CI → merge workflow autonomously.

Verification Commands

After routing, verify progress:

# Check epic status in Linear
# (use Linear MCP or Linear UI to view the epic and child tickets)

# If routed to epic-team — resume after session disconnect:
/epic-team <epic-id> --resume

# If routed to ticket-pipeline — check pipeline state:
cat $ONEX_STATE_DIR/pipelines/<ticket-id>/state.yaml

Execution Rules

Execute end-to-end without stopping between tasks. If blocked on one task, record a skip note and continue to the next. Only pause for: (a) credentials not available in the session, (b) a destructive action not explicitly covered by the plan, or (c) an explicit user gate in the plan. Do not exit plan mode or stop to "await direction" in any other circumstance.

When to Stop and Ask for Help

STOP executing immediately when:

• Plan has critical gaps or missing context (before live state verification)
• A referenced PR is CONFLICTING, FAILING, MERGED, or CLOSED (during live state verification)
• Dry-run output reveals structural problems (before ticket creation)
• plan-to-tickets fails with an architecture violation (before routing)
• A ticket-pipeline run fails and cannot self-recover

Ask for clarification rather than guessing.

Post-Completion

When all tickets/tasks close:

1. Discover open PRs: gh pr list --head <branch> --json number,title,state
2. If PRs have review comments: offer pr-polish
3. Offer: "All work complete. Run onex:finishing-a-development-branch? [Y/n]"
4. If Y: invoke finishing-a-development-branch

This is an offer only — user must approve before dispatch.

Remember

• Review plan critically before creating any tickets
• Verify live PR state before dry-run if the plan references existing PRs
• Always dry-run first to preview ticket structure
• Routing threshold is 3 tickets: use epic-team at that threshold, otherwise use ticket-pipeline
• Stop and ask if any step surfaces unexpected errors

Container / Degraded Environment

When running without the full omniclaude plugin (e.g., container-based Claude Code sessions):

• general-purpose silently falls back to general-purpose. ONEX intelligence integration, action logging, and observability will be inactive. Skill instructions still execute correctly — only metadata and telemetry are affected.
• Cross-skill dispatch (Skill(skill="onex:...")) requires the plugin's skill registry. If skills are not registered, dispatch calls will fail. Verify: check if the skill appears in the system-reminder skills list.
• Hook enforcement (poly_enforcer, authorization_shim, bash_guard) will not be active.
• Linear MCP may not be available. See --local mode (if applicable) for offline ticket management.