Qatomic-run

Qatomic-run — Haiku Wave Execution Engine

Role

A coordination skill that orchestrates multiple Haiku Teammates to execute atomic checklist items in parallel. It acts as the "Lead" session that partitions work and merges results.

Workflow

Step 1: Atomic Partitioning

Read the TASK_REQUEST and identify items suitable for parallel execution:

• No inter-dependencies (or dependencies are already met).
• Low complexity (single file edits, text changes, simple logic).
• Non-overlapping file ownership.

Step 2: Wave Initiation

Create an Agent Team using the Agent tool:

• Assign one Haiku Teammate per atomic item.
• Atomic Commits: Teammates MUST perform a git commit immediately after completing their specific item.
• Technical Summary: Teammates MUST create SUMMARY_{Item#}.md under the active plan's phase directory — resolve the slug via .qe/state/current-session.json → .qe/planning/.sessions/{session_id}.json → .qe/planning/ACTIVE_PLAN, then write to .qe/planning/plans/{slug}/phases/{X}/SUMMARY_{Item#}.md. Legacy projects with no slug resolvable write to .qe/planning/phases/{X}/SUMMARY_{Item#}.md.
• Set teammates to haiku model for maximum speed and efficiency.

Step 3: Result Synthesis

As Haiku teammates complete their tasks:

• Lead session (Opus/Sonnet) reads all SUMMARY_*.md files.
• Synthesize changes without re-reading entire files unless a merge conflict occurs.
• Aggregate all changes into the main working branch.

Step 4: Post-Execution Gate

After all atomic items are done, determine the next step based on task type:

• type: code → trigger /Qcode-run-task for test → review → fix quality loop.
• type: docs / type: analysis / deletion-heavy tasks → run SIVS Loop verification (VERIFY_CHECKLIST check + supervision) directly, skip /Qcode-run-task.

Execution Rules

• Wave: Group independent items from TASK_REQUEST into execution waves. Wave N+1 starts only after Wave N is verified.
• File Ownership: No two teammates can modify the same file within the same wave. Lead (Sonnet) must partition files before spawning.
• Haiku-First: Always use haiku for teammates. If an item requires Sonnet, it's not "Atomic" and should be handled by standard /Qrt.
• Context Integrity: Use ContextMemo to ensure teammates have current state without redundant I/O.

SIVS Engine Routing

Before spawning Haiku teammates, check SIVS engine configuration:

1. Read .qe/sivs-config.json from the project root (via scripts/lib/codex_bridge.mjs → loadSivsConfig()).
2. Check implement.engine value:
   • "claude" (default): Proceed with the standard Haiku swarm execution. No changes.
   • "codex": Delegate implementation to Codex via codex-plugin-cc instead of Haiku swarm:
     1. Call resolveEngine("implement", config) to check availability.
     2. If available: invoke /codex:rescue with the full TASK_REQUEST checklist as a single task. Codex handles all items internally (no wave splitting needed).
     3. If NOT available: show warning and fallback to standard Haiku swarm execution.
3. Check for legacy config: call detectLegacyConfig(). If non-null, display migration warning.

Note: When using Codex engine, wave-based parallelism is not used — Codex handles task partitioning internally. The Verify stage (validation) and quality loop (/Qcode-run-task) still run after Codex completes.

Codex Materialization Check (Mandatory after Codex Done): Codex may return Done before files are actually written (async companion pattern). The notification hook (notification.mjs) handles initial detection and writes state to unified-state.json under the codex_materialization key.

After every Codex Done, execute this sequence:

1. Read unified state — check .qe/state/unified-state.json → codex_materialization field:

   • status: "completed" → files written. Run git diff --stat, proceed to Verify.
   • status: "failed" → report error, offer retry or Claude fallback.
   • status: "running" → poll watcher active, proceed to step 2.
   • Field missing → proceed to step 2.

2. Read signal file — cat .qe/agent-results/codex-ready.signal 2>/dev/null:

   • "detected": true → files written. Run git diff --stat, proceed to Verify.
   • File not found → watcher still polling. Wait 30s, re-read. Repeat up to 120 times (1h).
   • "timeout": true → no changes after 1h. Go to step 3.

3. Fallback — use AskUserQuestion:

   • "Codex companion did not produce file changes after 1 hour."
   • (a) Keep waiting +1h (b) Retry with Codex (c) Implement with Claude (d) Check Codex process

Results are logged to .qe/agent-results/codex-materialization.md automatically.

Fallback guarantee: Missing .qe/sivs-config.json → all stages default to Claude. Zero impact on existing workflows.

Will

• Orchestrate parallel execution via Agent Teams
• Monitor Haiku teammate performance
• Synthesize results and handle merges

Handoff

After all Wave items are complete, resolve the active plan's ROADMAP (session binding → .qe/planning/ACTIVE_PLAN → flat fallback) and display execution summary + handoff. Read .qe/planning/plans/{slug}/ROADMAP.md when a slug resolves; fall back to flat .qe/planning/ROADMAP.md for legacy projects. Use the standard handoff format from QE_CONVENTIONS.md (vertical table, [x]/[>]/[ ] markers, single code block, lines under 60 chars).

Execution Summary (always show before handoff)

Execution Complete: {TaskName}
  Type: {code / docs / analysis}
  Waves: {N}
  Items: {X}/{Y} completed
  Teammates: {Z}

When type: code

{slug} · Phase {X}: {PhaseName} — Implementation complete

Roadmap
  [x] Phase 1: {Name1}
  [>] Phase {X}: {PhaseName}
  [ ] Phase {X+1}: {NextName}

PSE: [x] Plan [x] Spec [x] Execute [>] Verify

{TaskDescription — 다음 작업 내용 한 줄 요약}
Next: /Qcode-run-task {UUID}

When type: docs / type: analysis / deletion-heavy

After performing SIVS verification inline (VERIFY_CHECKLIST check + supervision gate):

{slug} · Phase {X}: {PhaseName} — Complete

Roadmap
  [x] Phase 1: {Name1}
  [>] Phase {X+1}: {NextName}
  [ ] Phase {X+2}: {FutureName}

PSE: [x] Plan [x] Spec [x] Execute [x] Complete

{NextPhaseDescription — 다음 Phase 작업 내용 한 줄 요약}
{Next label — 사용자 입력 언어로, 예: "다음:" / "Next:"}: /Qgs {slug}: {짧은 별칭, 최대 6단어}

(Fallback line 금지 — /Qgs는 /Qgenerate-spec의 alias이므로 중복이다. Legacy flat-file projects drop the {slug} · prefix and use /Qgs Phase {X+1}: {짧은 별칭}.) When all Phases are complete:

All phases done. Finalize with /Qcommit

Will Not

• Implement complex architectural changes (handle via standard Etask-executor)
• Bypass the quality loop
• Skip the handoff