pattern-orchestration-complex

Quick Reference

Flow: Plan → Approve → Execute → Verify → Summarize

Rules:

• Get explicit user approval before modifying files, unless approval was already given.
• Work one task at a time unless the tasks are read-only and independent.
• Keep the final summary in chat. Do not create summary files unless asked.
• Commit per task only when the user asked for commits, or the task carried write permission. Never commit unprompted.

Use when 2+ of these hold: 4+ files, more than 60 minutes, multiple sequential phases, cross-cutting or security-critical changes, data migration, breaking API changes, unclear approach, architectural decisions.

Do not use for: 1 to 3 files under 30 minutes with a clear approach. Delegate those directly.

Host tools: Before delegating in Pi, read the Pi tool mapping and use its native task forms instead of the OpenCode-style Task examples in the templates. If store tools are unavailable, keep the approved plan in TODO descriptions or the conversation and omit store calls. Do not create a substitute plan file unless the user requests one.

1. Plan

Load pattern-task-breakdown and produce the plan. It must include:

• Goal, assumptions, non-goals, and risks with mitigations.
• Ordered tasks with dependencies and a runnable verification each.
• Files and components likely to change.
• The skills or specialists each task needs.

Read the plan delegation template when delegating the planning pass rather than doing it directly.

For durable plans, load tool-store and persist the plan when the work will exceed 4 hours, when architectural decisions were made, when multiple phases or agents are involved, or when the plan must survive compaction. Store plain task prompts and TODO descriptions, not client-specific tool blocks. pattern-task-breakdown defines the data.prompt_drafts shape; do not improvise it here. See plan persistence for when this applies.

Persisting the plan means that if context is compacted between planning and execution, the agent loads the store item and resumes delegating immediately, with no reconstruction from memory.

2. Approve

Present the plan compactly and wait for explicit approval before modifying any file. If the user already said to proceed, continue and note that the approval was given.

The user may approve as-is, request modifications, change scope, or reject. Revise and re-present rather than proceeding on a partial yes.

3. Execute

For each task:

1. Mark the TODO item in_progress.
2. Do the work directly, or delegate using role-orchestrator guidance. Read the task execution delegation template for the call shape.
3. Keep read-write delegation serial. Parallelize only read-only investigation.
4. Run the task's verification.
5. Commit the task atomically, staging only the files this task changed, if the user asked for commits or the task carried write permission. Otherwise leave the change uncommitted and say so. Each commit should represent a working state, which is what makes the history bisect-friendly and any single task revertible.
6. Mark the TODO done, or record the blocker.

Prefer atomic, reviewable changes. Do not mix unrelated cleanup into a task, because it destroys the ability to roll that task back on its own.

Quality gate after each task:

• Requirements and success criteria are satisfied
• Applicable standards were followed
• Tests are included and passing
• No obvious errors or security issues
• Referenced store items were loaded

When the gate fails: re-delegate with targeted feedback once, escalate to a more capable agent once, then split the task or ask the user. Do not advance to the next task on a failed gate.

Between phases: confirm the phase goal was met, update progress, and brief the user.

4. Verify

Run the strongest practical checks for the changed scope:

• The project's test, build, lint, and docs commands. Check the repo's Taskfile, Makefile, or package.json scripts first rather than guessing the runner.
• A targeted review pass for security, data, or operational risk.
• A regression check against the original request, not just against the plan.

Delegate an independent verification pass with role-code-review and role-qa-engineer when the breadth justifies it. Read the final verification delegation template for the call shape.

Final verification catches what per-task gates miss: integration issues, inconsistency across changes, and documentation gaps. Passing tests are not the same as a complete feature.

If checks cannot run, state why and what should be run instead.

5. Summarize

Report in chat:

• What changed, and the key decisions.
• Files touched, grouped by area.
• Verification results.
• Known limitations, follow-ups, and skipped checks.

Checklist

Before closing complex work:

• The user-approved scope is satisfied, or the differences are explained
• TODO items reflect the current state
• Every delegated result passed its quality gate
• Full test, lint, and build checks ran, or the gaps are stated
• Verification evidence is in the final response
• Follow-up items are documented
• No summary or planning file was created unless requested

Common Patterns

Read common orchestration patterns when adapting the workflow to a feature, refactor, or security-hardening project.

Troubleshooting

Read orchestration troubleshooting when planning is repeatedly rejected, estimates drift, quality gates fail, or progress context is lost.

Integration with Other Skills

With role-orchestrator: usually loaded from its routing rules when two or more complexity indicators are present. Delegations use the same envelope, so load it directly if this skill is used standalone.

With pattern-task-breakdown: it creates the plan, this skill executes it.

With role-code-review and role-qa-engineer: supply the independent verification pass in step 4.