feat(examples): add multi-agent-workflow — deterministic 10-phase issue resolver

[Dev4LifeV]

feat(examples): add multi-agent-workflow — deterministic 10-phase issue resolver

A self-contained example workflow that resolves a single GitHub or Linear
issue end-to-end through a deterministic, gate-driven pipeline. Reads the
issue, plans adversarially, implements with TDD, runs lint/CI/E2E gates,
audits the work, and opens a PR — with three human-approval gates along
the way.

Run:

bun codex-workflow run examples/multi-agent-workflow/workflow.js \
  --config examples/codex-workflow.config.ts \
  --args '{"tracker":"gh","issueId":123}'

What's in this PR

• workflow.js (~250 lines): 10 phases + 3 gates, using the same meta/agent/parallel/pipeline/phase/args primitives as hello.js and complex-chain.js. Original code — no structure derived from the reverse-engineered deep-research.js / code-review.js research notes.
• README.md: phase table, when-to-use, subagent inventory.
• SETUP.md: first-time setup (Bun, codex-workflow, pi-coding-agent, MiniMax provider block). Documents the env:envVar resolution order.
• ORCA.md: end-to-end Orca Tasks UI flow (single-issue + parallel multi-issue), HITL gate dual-mode (Orca gate UI vs TUI chat fallback), monitoring commands, common errors.
• setup.sh: idempotent bash installer that checks for required tools, installs what is missing, prompts for MINIMAX_API_KEY, persists LINEAR_API_KEY, and validates the workflow parses + dry-runs.
• agents/: seven vendored subagents in codex-workflow-compatible markdown (4 reused from the four-lens pattern — arch/product/sec/test, 2 planning-specific — scope/dod-coverage, 1 dedicated auditor).

The 10 phases

#	Phase	Capability / lens
1	Debrief	(inline)
G0	Human approval	—
2	Plan Issue	(inline)
3	Review Plan	rgi-lens-scope + rgi-lens-dod-coverage
4	Plan Implementation	(inline)
5	Review Impl Plan	rgi-lens-arch + rgi-lens-product
6	Implement + Unit Tests	TDD loop, worktree isolation
7	E2E Tests	Playwright specs, push + watch CI
8	Lint + CI	execute-only (pnpm check:*)
9	Auditor	multi-agent-auditor (dedicated)
G1	Auditor verdict review	—
10	Commit + PR	(inline)
G2	HITL pre-PR	—

Pairs with the agentskit-os monorepo

The workflow consumes an IssueTrackerPort per ADR-0182 in the AgentsKit-io/agentskit-os monorepo. The port + GitHub (gh CLI) + Linear (GraphQL) + in-memory adapters ship in a new package @agentskit/os-issue-tracker (separate PR). This example references that contract — when the monorepo PR lands first, the workflow's tracker calls land against the new port; when this PR lands first, the workflow ships with gh issue view calls directly via its inline Agent 1.

A MiniMax provider (HTTP, OpenAI-compatible via https://api.minimax.io/v1) is wired in the consumer monorepo (os-coding-agents + os-runtime-agentskit + os-core enum + os-headless integration-setup). This PR is vendor-neutral: it does NOT touch examples/codex-workflow.config.ts (a separate change if MiniMax is blessed upstream).

Validated locally

$ node dist/cli.js validate examples/multi-agent-workflow/workflow.js
✓ valid workflow: multi-agent-workflow
  End-to-end issue resolution: plan, adversarial review, implement, tests, audit, PR. Includes three human-approval gates.
  phases: Debrief → Plan Issue → Review Plan → Plan Implementation → Review Implementation Plan → Implement + Unit Tests → E2E Tests → Lint + CI → Audit → Commit + PR

$ node dist/cli.js doctor
✓ Bun runtime (1.4.0)
✗ provider config   (expected — users bring their own)
✓ Codex auth        (irrelevant but checked)
! Gemini CLI        (optional)
! pi CLI            (install via setup.sh)
✓ data dir: C:\Users\vctud\.codex-workflow

Note on npm test

npm test hangs in this repo on a pre-existing test (tests/deep-research-compat.test.ts that boots the in-process viewer). It is not caused by this PR — the example itself parses and validates cleanly. The maintainer may want to investigate the hang separately; CI (npm ci && npm run typecheck && npm test) will surface this if it pre-existed on main.

Risk for reviewers

• Low: the example is in its own subdirectory and changes zero existing files except one README bullet.
• Medium: the subdirectory convention (examples/multi-agent-workflow/) is new — all 7 other examples live flat. I'm proposing this because the workflow ships with 7 subagent files + 4 docs + workflow.js + setup.sh, which would clutter a flat layout. Happy to split if the maintainer prefers flat per-example.
• No new runtime deps: the example reuses only what codex-workflow already provides (meta/agent/parallel/pipeline/phase/log/args/budget). The MiniMax provider is documented in SETUP.md and wired by the user, not by this PR.