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

Flag	Description
--local	Skip Linear ticket creation; create local YAML ticket files in docs/tickets/local/ and route directly to implementation

---

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:

CI/Mergeability State	Classification	Action
PENDING / checks still running	PENDING	Poll up to 3 times (30s interval). If still pending after 90s, report status and proceed -- do not block indefinitely.
BEHIND (mergeable but needs rebase)	ACTIONABLE	Note in plan review; proceed. Rebase will happen during execution.
CLEAN / UNSTABLE (mergeable, checks pass/flaky)	READY	Proceed normally.
CONFLICTING (merge conflicts)	STOP	Stop and report: "PR #N has merge conflicts. Plan assumes it is mergeable. Please resolve conflicts or update the plan."
Checks FAILURE (required checks failing)	STOP	Stop and report: "PR #N has failing required checks. Plan assumes CI is green. Please fix CI or update the plan."
MERGED	STOP	Stop and report: "PR #N is already merged. Plan assumes it is open. Please update the plan to reflect current state."
CLOSED (not merged)	STOP	Stop and report: "PR #N is closed without merge. Plan assumes it is open. Please update the plan."

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:

Condition	Route	Why
Multiple repos touched	onex:epic-team	Cross-repo needs orchestration
Migrations or deploy steps present	onex:epic-team	Infrastructure changes need coordination
3+ distinct subsystems affected	onex:epic-team	Broad blast radius
3+ tickets (fallback)	onex:epic-team	Parallel execution needed
1-2 tickets, single repo, no migrations	onex:ticket-pipeline	Lightweight

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.