Engineering Workflow

Human-only overview. Not a runtime contract for agents.

Canonical runtime source of truth:

• SKILL.md
• orchestrator/ENTRY.md
• implementation-prompt-gen/ENTRY.md
• implementation-agent/ENTRY.md
• review-agent/ENTRY.md

If this README conflicts with runtime docs, runtime docs win.

Migration Note

This skill's naming history is:

• pfc → cortex → orchestrator

For this skill, treat any legacy pfc or cortex reference as orchestrator.

Contract Alignment

This README is aligned to:

• .skills/.contracts/agent-identity-routing-contract.md
• .skills/.contracts/handoff-contract.md
• .skills/.contracts/execution-boundary-contract.md

Canonical Actors (This Skill Scope)

Invariants Applied

• Worker::* handoffs route only to Orchestrator::engineer-workflow.
• Orchestrator::engineer-workflow is the only control endpoint in this skill.
• No worker lane may bypass the orchestrator lane.
• Repository mutation operations (cleanup/commit/push/merge) run only in dispatched worker lanes; Orchestrator governs by packeted dispatch/completion.
• Every consumed handoff requires a disposition packet plus prose summary before the next dispatch.
• The six-artifact sub-phase model remains mandatory:
  • Goals
  • SDS
  • Implementation Plan
  • Completion Report
  • User Documentation
  • Review

Entry Points

Entrypoint Step Paths

EP-001 — Role Router

EP-002 — Task Orchestrator

EP-003 — Phase Planning Exec

EP-004 — Phase Decomposition

EP-005 — Preflight Cleanup Exec

EP-006 — Subphase Close Exec

EP-007 — Phase Close Exec

EP-008 — Implementation Prompt Gen

EP-009 — Implementation Agent

EP-010 — Review Agent

Detailed Path (Step + Handoff)

Flow Diagram

Sequence Diagram

Handoff Visibility Points

Example Handoff Packet

Every handoff between agents is a structured YAML-frontmatter packet followed by a body. Here's what a real handoff_disposition packet looks like — this is the Orchestrator recording its gate decision after reviewing a completion report:

---
nous:
  v: 2
  route:
    emitter:
      class: Orchestrator
      node: engineer-workflow
      id: Orchestrator::engineer-workflow
    target:
      class: Orchestrator
      node: engineer-workflow
      id: Orchestrator::engineer-workflow
  envelope:
    direction: internal
    type: response_packet
    workflow: engineer-workflow-sop
    action: handoff_disposition
  correlation:
    handoff_id: HF-DISPOSITION-001
    correlation_id: phase-1.2-completion-report-cycle-1
    cycle: 1
    emitted_at_utc: 2026-02-23T19:49:06.250Z
    emitted_at_unix_ms: 1771876146250
    sequence_in_run: 7
  payload:
    schema: handoff-disposition.v1
    artifact_type: completion-report
  retry:
    policy: value-proportional
    depth: iterative
    importance_tier: high
    expected_quality_gain: 0.25
    estimated_tokens: 1800
    estimated_compute_minutes: 1.0
    token_price_ref: .worklog/benchmarks/pricing-rates-stub.mdx
    compute_price_ref: .worklog/benchmarks/pricing-rates-stub.mdx
    decision: accept
    decision_log_ref: .worklog/phase-1/phase-1.2/reviews/completion-report.mdx
    benchmark_tier: nightly
    self_repair:
      required_on_fail_close: true
      orchestration_state: deferred
      approval_role: Cortex:System
      implementation_mode: dispatch-team
      plan_ref: .worklog/benchmarks/self-repair/full-plan-todo.mdx
---

source_handoff_id: HF-008
disposition_status: accepted
decision_ref: .worklog/phase-1/phase-1.2/reviews/completion-report.mdx
next_action: advance_to_next_gate
next_dispatch_ref: n/a

Key things to notice:

• nous.v: 2 — protocol version for packet schema
• route — who emitted and who receives (both Orchestrator here, since dispositions are internal state events)
• envelope — packet type, workflow, and action name
• correlation — links this packet to a specific artifact review cycle with timestamps and sequence number
• payload.schema — declares which schema validates the body
• retry — cost-aware decision metadata: token estimates, quality gain, and whether to accept/revise
• retry.self_repair — if the gate fails closed, the system can attempt automated repair via the dispatch team
• Body — the actual disposition: accepted, with a ref to the review log and what happens next

This packet structure is what makes the multi-agent workflow auditable — every decision, every handoff, every gate verdict is a durable, traceable record.

Optional External Boundary Packets

These templates remain available for external principal-bridge integrations, but they are outside this skill's internal orchestrator/worker lane model:

• orchestrator/responses/principal-e2e-handoff-request.md
• orchestrator/responses/principal-e2e-execution-report.md
• orchestrator/responses/principal-carry-forward-approval.md
• orchestrator/responses/principal-creative-direction-signoff.md

Maintenance

• Update runtime contracts first (SKILL.md, role ENTRY.md, templates/procedures).
• Keep mirrored templates synchronized with scripts/check-template-sync.ps1.
• Re-run validators:
  • python .skills/.system/skill-creator/scripts/quick_validate.py .skills/engineer-workflow-sop
  • pwsh -File .skills/engineer-workflow-sop/scripts/check-reinforcement-contract.ps1
  • pwsh -File .skills/engineer-workflow-sop/scripts/check-template-sync.ps1
• Refresh this README after runtime changes.