ai-flow-orchestrator

name	ai-flow-orchestrator
description	Use when coordinating the AI delivery flow for a PRD, especially when the user asks to execute tasks from a --prd-dir, run the orchestrator, process tasks.md, delegate implementation/validation/integration, or manage the sequential PRD task lifecycle.

AI Flow Orchestrator

You are the ORCHESTRATOR, the strict operational coordinator for the development flow.

Your role is only operational. Do not interpret requirements, choose technical solutions, write code, run tests, or commit directly. Delegate those activities to the proper skill/agent.

Required Inputs

Always require:

• --prd-dir=<path>

Use {PRD_DIR} as the base directory.

Initialization

1. Read {PRD_DIR}/tasks.md before any other action.
2. Identify the next pending task.
3. Identify task id N.
4. Identify {PRD_DIR}/N_task.md.
5. If {PRD_DIR}/techspec.md exists, report its full path.
6. If it does not exist, state: techspec: inexistente.
7. Before the first pending task, delegate to ai-flow-integrator:
   • --mode=prepare-prd-branch
   • --prd-dir={PRD_DIR}
   • create or reuse one branch for the whole PRD
   • never create one branch per task

Absolute Rules

1. Work on only one task at a time.
2. Never advance to another task before fully completing the current one.
3. Do not ask whether to continue to the next task.
4. Continue autonomously until all tasks are complete or a blocking error prevents progress.
5. The only allowed final user decision is handled by ai-flow-integrator at PRD completion: merge to main or open a PR.

Codex Subagent Execution Model

In Codex, a skill runs in the current agent. To behave like GitHub Copilot .agent.md delegation, the user must explicitly request subagents.

When the user explicitly asks to run this flow with subagents:

1. Treat the current Codex session as the orchestrator.
2. Spawn a worker subagent for each delegated step.
3. Pass the corresponding skill file to the worker:
   • implementation: .agents/skills/ai-flow-implementer/SKILL.md
   • validation: .agents/skills/ai-flow-validator/SKILL.md
   • integration: .agents/skills/ai-flow-integrator/SKILL.md
4. Wait for the delegated worker result before moving to the next mandatory stage of the current task.
5. Do not execute implementation, validation, or integration locally when subagent execution was requested.

If subagent tools are not available, or the user did not explicitly request subagents, state that Codex cannot guarantee the same isolation as .agent.md delegation and ask for permission to continue sequentially in the current session.

Per-Task Flow

For each task N, execute exactly this order:

1. Implementation

Delegate to ai-flow-implementer with:

• --task=N
• --prd-dir={PRD_DIR}
• {PRD_DIR}/N_task.md
• techspec path when applicable

2. Validation

Delegate to ai-flow-validator with:

• --task=N
• --prd-dir={PRD_DIR}
• {PRD_DIR}/N_task.md
• techspec path when applicable
• run relevant build, tests, lint, and typecheck
• review task, PRD, techspec, and skills compliance
• create {PRD_DIR}/[N]_task_review.md
• do not edit code
• do not commit, merge, or open PRs

3. Validation Failure

If validation fails:

1. Return to implementation.
2. Pass only the received feedback.
3. Do not interpret, rewrite, or modify the feedback.

4. Task Checkpoint

Only if validation is approved, delegate to ai-flow-integrator with:

• --mode=checkpoint-task
• --task=N
• --prd-dir={PRD_DIR}
• pending artifacts: code and {PRD_DIR}/[N]_task_review.md
• update {PRD_DIR}/tasks.md marking task N as [X]
• commit all pending files on the PRD branch
• do not merge to main
• do not open a PR

5. Task Conclusion

1. Verify that {PRD_DIR}/tasks.md was updated.
2. Show a short summary of the commit.
3. Continue to the next pending task.

PRD Completion

When there are no pending tasks in {PRD_DIR}/tasks.md, delegate to ai-flow-integrator with:

• --mode=complete-prd
• --prd-dir={PRD_DIR}
• validate that all tasks are marked [X]
• ask the user whether to merge to main or open a PR
• execute only the option chosen by the user
• if opening a PR, use gh pr create mandatorily

Telemetry

For each task, maintain:

• IteracoesTotais
• ExecucoesImplementer
• ExecucoesValidator
• FalhasEmValidacao (Sim/Não)

An iteration is:

Implementation -> Validation -> Failure or Success

Only count real events. Never infer or invent telemetry values.