whitebox

name	whitebox
description	File-based control plane that observes, explains, and controls the AI coding process. /whitebox is the sole product boundary — launch|status|explain|health|approvals expose run start, current state, intervention triggers, linked DEC evidence, approval control, and execution environment health. Use this to see what is running, why something is blocked, and to approve or reject gates.
trigger	/whitebox, /whitebox launch, /whitebox status, /whitebox explain, /whitebox health, /whitebox approvals, "화이트박스", "왜 막혔어", "상태 보여줘", "승인해", "거절해", "health check"
version	1.0.0
updated	"2026-03-07T00:00:00.000Z"

Whitebox

File-based control plane that exposes AI execution, decisions, and gates in an observable form

Purpose

• Quickly understand the current run and gate state.
• Explain why a task/REQ/gate is blocked, backed by evidence (artifacts).
• Pin the operator-intent/control artifact contract for approval gates to the /whitebox surface.
• Interpret the pending approval queue as an intervention queue and surface intervention reasons such as user_confirmation, agent_conflict, and risk_acknowledgement.
• For agent_conflict cases, surface linked DEC-* ruling metadata and required actions on the explain/TUI surface.
• Check the health of subscription-based CLI executors (claude/codex/gemini) and core artifacts.

Non-goals

• Do not assume hook UX inside Claude Code alone is sufficient for control.
• Does not support API-key-first provider integrations.
• Does not log raw prompts, raw file contents, or secrets.

Input Artifacts (MVP)

Whitebox is a product boundary that reads file-based artifacts; any mutations are performed exclusively via the canonical CLI path.

• TASKS.md
• .claude/orchestrate-state.json
• .claude/collab/events.ndjson (canonical facts log)
• .claude/collab/control.ndjson (canonical operator-intent log)
• .claude/collab/board-state.json (derived renderer state)
• .claude/collab/control-state.json (derived control query state)
• .claude/collab/derived-meta.json (derived stale markers)

Single Surface Contract

• /whitebox is the only product boundary.
• The TUI is /whitebox's interactive renderer/operator shell.
• The CLI is /whitebox's internal mutation API and headless/scriptable surface.
• The TUI renderer is the exclusive interactive shell for /whitebox.

Control Contract (MVP freeze)

• The canonical control action family is approve / reject only.
• .claude/collab/control.ndjson is an append-only operator-intent log; only the Node writer may write to it.
• The TUI sends control commands via subprocess delegation only.
• .claude/collab/control-state.json is disposable derived state and must not be edited directly.
• Duplicate command handling is fixed via idempotency_key and correlation-aware filtering.

Commands

/whitebox launch — UI-first supervisor entrypoint

Intent: Bring up Whitebox first, then start the actual executor CLI as a child process.

• Canonical script: node skills/whitebox/scripts/whitebox-launcher.js
• Inputs:
  • .claude/collab/* artifacts (auto-init capable)
  • executor command (default: claude)
• Outputs:
  • Human: dashboard URL + spawned command + run/session summary
  • JSON (--json): { ok, project_dir, dashboard, session, command }
• Side effects:
  • May run collab-init
  • Opens the whitebox dashboard
  • Records supervisor.session.* lifecycle events
  • Spawns child CLI / forwards signals

Principle:

• If the UI is not visible, surface that fact explicitly.
• Hooks are auxiliary signals; the supervisor owns execution.

/whitebox status — Current state/summary

Intent: See at a glance what is currently running and the key state (gates/blocked).

• Inputs: TASKS.md, .claude/orchestrate-state.json, .claude/collab/board-state.json, .claude/collab/derived-meta.json
• Outputs:
  • Human: summary (active run, blocked count, key gate state, pending approval/decision count) + board/TUI link
  • JSON (--json): { ok, run_id, blocked_count, gate_status, pending_approval_count, pending_decision_count, stale_artifacts }
• Side effects:
  • If stale derived artifacts are detected, automatically attempts rebuild via the authoritative projector
  • In TTY mode, can enter the whitebox TUI operator shell to render the approval shell

Relationship: /whitebox status exposes the whitebox-perspective summary/header/warnings (derived stale, etc.).

/whitebox explain — Why is it blocked? What options are available?

Intent: Explain, with evidence, why a specific task/REQ/gate is blocked or denied.

• Inputs: .claude/collab/events.ndjson, .claude/collab/control-state.json, TASKS.md, .claude/orchestrate-state.json, .claude/collab/requests/*.md, .claude/collab/decisions/*.md
• Outputs:
  • Human: "what / why / where" it is blocked + approve/reject options (if an approval) + trigger/recommendation + linked DEC metadata
  • JSON (--json): { ok, target, reason, options[], trigger, linked_decision, evidence_paths, correlation }
• Side effects: None (inspection only)

Intervention trigger types:

• user_confirmation — Explicit user confirmation is required
• agent_conflict — Agent recommendations conflict and operator choice is needed
• risk_acknowledgement — Continuing the current plan requires explicitly acknowledging a risk

/whitebox approvals — Canonical approval control surface

Intent: Query and approve/reject paused approval gates in a headless/scriptable way.

• Canonical script: node skills/whitebox/scripts/whitebox-control.js
• Verbs:
  • list — Query pending approval queue (control-state.json read only)
  • show --gate-id=<id> — Show details of a specific gate
  • approve --gate-id=<id> — Append approve intent to canonical control.ndjson
  • reject --gate-id=<id> — Append reject intent to canonical control.ndjson
• Stable results: approved, rejected, already_applied, not_found, stale_target, invalid_command, write_failed
• Exit codes:
  • 0 — success (approved, rejected, already_applied, list, show)
  • 3 — not_found
  • 4 — stale_target
  • 5 — invalid_command
  • 6 — write_failed
• Side effects:
  • list/show: None (control-state.json query only)
  • approve/reject: appends to control.ndjson and records an audit event via the shared mutation path

list/show results for pending approvals may include the trigger metadata above; read-only decisions are surfaced in inspect-focused mode via /whitebox explain. approve/reject applies only to mutable approval gates.

/whitebox health — Environment/artifact health check

Intent: Check the health of executors (subscription CLIs), core artifacts, and event log integrity.

• Inputs:
  • CLIs: claude, codex, gemini (subscription-backed)
  • Files: TASKS.md, .claude/orchestrate-state.json, .claude/collab/events.ndjson, .claude/collab/control.ndjson, .claude/collab/board-state.json, .claude/collab/control-state.json
• Outputs:
  • Human: checklist + failure reasons
  • JSON (--json): { ok, executors, artifacts, events_integrity, control_integrity }
• Side effects: None (validation only)

New User Flow

1. Start work with /whitebox launch or /team-orchestrate (which delegates launch).
2. Use /whitebox status to see paused gates / blocked state and pending decision count.
3. Use /whitebox explain to review evidence, trigger, linked DEC, approve/reject options, or inspect-only decisions.
4. Use /whitebox approvals list|show to review mutable pending gates.
5. Use /whitebox approvals approve|reject --gate-id=... to record the canonical control command.
6. When architecture-lead records a FINAL DEC, matching ESCALATED REQs are automatically RESOLVED through the canonical hook/event path.
7. Use /whitebox status again to verify resumed/blocked state.

Rules:

• Report non-interactive auth state via codex auth status and gemini auth status.
• Claude reports host_not_attached when the CLAUDECODE host attachment signal is absent — do not guess.