Plan Issue

Pipeline Overview

Input (JIRA ticket or text) 
  → Worktree Setup
  → Phase 1: Architect Agent (plan creation)
  → USER APPROVAL GATE
  → Phase 2: Plan Partner Agent (refine + antagonize)
  → USER APPROVAL GATE
  → Phase 3: Write plan in Jira issue "Instructions" field

Phase 0: Input Parsing & Worktree Setup

0.1 Parse the Task Input

Determine the task source:

• JIRA ticket URL or ID: Fetch ticket details using the available MCP tools or ACLI. Extract the ticket number (e.g., TICKET-1234), title, description, and acceptance criteria. Additionally, use the MCP to traverse related context — fetch linked tickets (blockers, related stories, epics), parent tickets, and subtasks. This additional context helps the Architect Agent build a more grounded plan. Don't fetch everything blindly — focus on links that look relevant to understanding scope, dependencies, or prior decisions.
• Text instructions: Use the provided description directly. Generate a short slug from the description (e.g., add-user-auth-flow).

0.1.1 Figma Context Discovery (Required for Jira source)

When the source is a Jira issue:

1. Scan the issue description, comments, and linked context for Figma URLs (figma.com/design/... or figma.com/file/...).
2. If one or more links exist, use Figma MCP to inspect the referenced nodes/screens.
3. Extract planning-relevant signals and pass them to the Architect Agent, including:
   • Intended UI states and user flows
   • Key components and variants
   • Validation/error/empty/loading states visible in design
   • Any obvious copy/interaction constraints
4. Record the Figma links reviewed and a short design-context summary in .orchestra/.pipeline-state.md.

If a Figma link exists but cannot be accessed, continue planning with Jira-only context and explicitly call out the missing design context as a risk/open question.

For either source: If critical information is missing — ambiguous requirements, unclear acceptance criteria, missing technical context, or references to things that aren't explained — prompt the user before proceeding. Ask specific questions and, where possible, suggest where the answer might be found (e.g., "Can you point me to the API spec for the payments service?" or "The ticket references a 'legacy flow' — is there documentation or a file I should look at?"). Do not proceed to Phase 1 with significant ambiguity — it's cheaper to ask now than to replan later.

0.2 Set Up the Worktree

1. Identify the current branch — this becomes the PR target branch.
2. Create the worktree branch name:
   • JIRA source: {ticket-number}-{short-slug} (e.g., TICKET-1234-implement-new-page)
   • Text source: {generated-slug} (e.g., add-user-auth-flow)
3. Create the worktree:

   git worktree add .worktrees/{branch-name} -b {branch-name}
   

4. All subsequent work happens inside .worktrees/{branch-name}/.
5. Create the orchestra directory for agent communication:

   mkdir -p .worktrees/{branch-name}/.orchestra
   

0.3 Initialize Pipeline State

Create .orchestra/.pipeline-state.md to track progress. Read the template from templates/pipeline-state.md and initialize it.

Every time a phase completes, update this file with evidence (command output, file paths, summaries). This is your source of truth — if it's not in the pipeline state, it didn't happen.

Phase 1: Architect Agent

Spawn the Architect Agent using /agents/architect-agent.md.

Inputs to provide the agent:

• The full task description (JIRA details or text instructions)
• The worktree path so it can investigate the codebase
• Figma-derived context summary (if any links were found)
• The path to write its output: .orchestra/plan.md

What the agent must produce:

• A structured implementation plan in .orchestra/plan.md following the plan template in templates/plan.md

After the agent completes:

1. Verify .orchestra/plan.md exists and is non-empty
2. Read the plan yourself to confirm it's coherent
3. Check for "Unresolved Questions" — if the architect flagged any, present them to the user and resolve them before showing the full plan. Update the plan with the answers before proceeding.
4. Present the plan summary to the user

→ USER APPROVAL GATE

Present the plan to the user and ask for their feedback. The user needs to confirm:

• Is the plan aligned with what they want to achieve?
• Is the technical approach correct?
• Are there any missing requirements?

If rejected: Capture the user's feedback, pass it back to a new Architect Agent instance along with the previous plan, and regenerate. Repeat until approved.

If approved: Update .orchestra/.pipeline-state.md with approval timestamp and move to Phase 2.

Phase 2: Plan Partner Agent

Spawn the Plan Partner Agent using /agents/plan-partner-agent.md.

This agent operates in two sub-phases:

Sub-phase 2a: Refinement

The Plan Partner reviews the plan and refines it — filling in gaps, improving clarity, adding missing edge cases, and strengthening the test strategy.

Output: .orchestra/plan-refined.md

Sub-phase 2b: Adversarial Review

The Plan Partner then switches to antagonist mode, actively trying to find flaws, incorrect assumptions, scalability issues, security concerns, and missing edge cases in the refined plan.

Output: .orchestra/plan-antagonist-review.md

Reconciliation Loop (max 3 rounds)

If the adversarial review identifies issues:

1. Spawn a new Architect Agent instance to address the issues raised
2. Spawn a new Plan Partner Agent instance to re-review
3. Track the round number in .orchestra/.pipeline-state.md

If after 3 rounds there are still unresolved issues, escalate to the user with a summary of what remains contentious.

After reconciliation completes or user resolves: Update the final plan at .orchestra/plan-final.md.

→ USER APPROVAL GATE

Present the final plan to the user. Include a summary of what changed during the refinement/adversarial process.

If rejected: Restart from Phase 1 with the user's feedback incorporated. If approved: Update .orchestra/.pipeline-state.md and move to Phase 3.

Phase 3: Write Plan to JIRA

Use the MCP or ACLI to write the final plan from .orchestra/plan-final.md into the "Instructions" field of the JIRA ticket.