orchestrate-workflow-from-brief

name	orchestrate-workflow-from-brief
description	Orchestrate the reusable workflow from a brief through producer, gate, and rework stages. Use when Codex must decide the current stage, missing inputs, next producer skill, gate profile, and whether rework is required. Do not use to replace the producer or gate skills themselves.

Orchestrate Workflow From Brief

Goal

Be the workflow controller for the reusable skill system. Hold stage state, decide whether the workflow is blocked or ready to advance, and coordinate the producer -> gate -> rework loop without redesigning artifacts directly. When the active stage is iterative implementation, keep slice-level progress explicit and do not declare the workflow complete until every approved slice has either passed its gate or is explicitly deferred by policy.

Read Shared Contract Reference before orchestrating. Use repo-backed stage policies from ../../stage-policies and gate profiles from ../../gate-profiles when available.

Treat only repo-backed policy stages as valid current_stage values. Specialized review skills can still be requested, but they should be scheduled as ad hoc checks through next_action, not modeled as the resumable mainline workflow stage unless they are explicitly added to stage policy.

Trigger boundary

• Use when the user wants the full workflow managed from brief to approved artifacts.
• Use when an existing workflow state must be resumed after a producer or gate step.
• Do not use to produce domain, architecture, contracts, slices, or code artifacts directly.

Required input

• Required: brief unless a resumable workflow_state already carries the current stage, approved artifacts, and resolved stack context
• Optional: workflow_state
• Optional: project_constraints
• Optional: critical_use_cases
• Optional: technology_choices
• Optional: programming_language
• Optional: stack_profile_ref
• Optional: approved_artifacts
• Optional: latest_gate_report
• Optional: approved slice-plan
• Optional: slice-specific implementation reports and gate reports
• Optional: git branch inventory or repository branch context

Refusal and blocked policy

• Return BLOCKED when the current stage cannot proceed because required inputs are missing.
• Do not skip a stage that requires approval.
• Do not override a gate decision with personal judgment.
• Do not rewrite a producer artifact directly; issue a rework brief or next-step instruction instead.
• Do not mark the workflow complete while an approved iterative implementation stage still has remaining slices without passing gate reports.
• Return BLOCKED for iterative implementation when the required integration branch policy is known but the branch does not exist in the repository context.

Workflow

1. Identify the current workflow stage from workflow_state, approved artifacts, and the latest gate report.
2. Resolve stack context from workflow_state, explicit inputs, approved artifacts, and repo-backed stack profiles before selecting the next implementation-facing step.
3. Resolve git workflow context from workflow_state, explicit project constraints, and repository branch context before selecting an implementation slice.
4. Check whether the current stage has the required inputs to run.
5. If inputs are missing, return BLOCKED with missing_inputs and questions_to_user.
6. If no current artifact exists for the stage, select the correct producer skill and expected output artifact.
7. If a producer artifact exists but is not approved, select run-quality-gate with the right repo-backed gate profile and stage policy.
8. If the latest gate failed, issue a rework brief tied to required fixes and keep the workflow on the same stage.
9. If the active repo-backed stage policy declares an iterative implementation mode, derive the full SLICE-* inventory from the approved slice plan and from slice-specific implementation reports and gate reports.
10. For iterative implementation stages, assign one dedicated work branch per slice, record the selected branch name, and require merge back into the configured integration branch before a slice can be marked approved.
11. For iterative implementation stages, keep current_stage on implement-slice-from-contract after each passing slice gate unless the stage policy completion rule says that all planned slices are finished.
12. For iterative implementation stages, choose the next unimplemented or changes-required SLICE-* as the next producer target and record it explicitly in workflow state.
13. If an implementation artifact records failing validation, missing merge evidence, or the implementation gate fails, issue rework for the same SLICE-* and do not advance to another slice.
14. If the latest gate passed, mark the artifact approved and advance according to the active stage policy, including same-stage advancement for iterative implementation.

Output contract

Write workflow-state.yaml or return equivalent YAML using this structure:

artifact_metadata:
  artifact_id: ""
  artifact_type: workflow-state
  artifact_status: current | superseded
  approval_status: pending_review | approved | changes_required | rejected
  approved_by_gate_profile: none
  gate_report_ref: none | <ref>
  upstream_artifact_refs:
    - ""
current_stage: critique-problem-framing | extract-domain-model | design-clean-architecture | derive-interface-contracts | plan-implementation-slices | implement-slice-from-contract
decision: READY | BLOCKED | NEEDS_GATE | NEEDS_REWORK | ADVANCE
workflow_status: active | blocked | waiting_for_review | rework_in_progress | complete
resolved_stack_context:
  programming_language: ""
  technology_choices:
    - ""
  stack_profile_ref: none | <ref>
  configuration_mechanism: ""
  context_sources:
    - workflow_state | brief | approved_artifact | existing_codebase | repo-backed_stack_profile
missing_inputs:
  - ""
questions_to_user:
  - ""
approved_artifacts:
  - artifact_ref: ""
    artifact_type: ""
    approval_status: approved
last_gate_report: ""
current_artifact_ref: ""
git_workflow:
  branching_mode: none | dedicated-slice-branch
  integration_branch: ""
  branch_prefix: ""
  merge_required_before_approval: true
  repository_branches:
    - ""
implementation_progress:
  slice_plan_ref: none | <ref>
  selected_slice_id: none | SLICE-*
  selected_slice_branch: none | <branch>
  completed_slice_ids:
    - ""
  remaining_slice_ids:
    - ""
  deferred_slice_ids:
    - ""
  slice_statuses:
    - slice_id: SLICE-*
      work_branch: none | <branch>
      merge_target_branch: none | <branch>
      implementation_artifact_ref: none | <ref>
      gate_report_ref: none | <ref>
      merge_status: pending | merged | blocked
      status: ready | in_progress | changes_required | approved | blocked | deferred
producer_skill_to_run: ""
gate_profile_to_run: ""
gate_profile_ref: ""
stage_policy_ref: ""
required_upstream_artifacts:
  - ""
optional_review_skill_to_run: none | review-cross-artifact-consistency | review-architecture-boundaries
optional_review_reason: ""
rework_required: true
rework_brief:
  stage: ""
  artifact_ref: ""
  required_fixes:
    - ""
  upstream_artifacts_required:
    - ""
next_stage: critique-problem-framing | extract-domain-model | design-clean-architecture | derive-interface-contracts | plan-implementation-slices | implement-slice-from-contract | complete | none
next_action: ""

Quality bar

• Keep the orchestrator boring and procedural.
• Never advance past a stage that lacks approval.
• Use missing inputs and required fixes to drive the next action precisely.
• Keep the workflow state stable enough to resume in a later turn without operator memory.
• Prefer repo-backed stage policies and gate profiles over implicit operator choices.
• Persist the resolved stack context in workflow state before implementation planning or code generation begins.
• Do not emit a current_stage that is not present in the active stage policy.
• For iterative implementation stages, keep slice progress inspectable in workflow-state.yaml and use slice-specific implementation and gate artifact refs instead of overwriting one generic implementation artifact.
• Do not treat “one passing slice” as equivalent to “workflow complete” unless the active stage policy explicitly says the slice plan contains no remaining approved slices.
• For iterative implementation stages with branch-per-slice policy, keep integration-branch and merge status explicit in workflow state and block the workflow if the required integration branch is absent.