# GPT Orchestrator Skill

status: ACTIVE
task IDs: session tasks #6–#10; owner correction task #9; agent task #10; descriptive-title task #13; fail-closed theme-title correction #14
source request: Owner requested global `/gpt-orchestrator` reproducing this session's end-to-end ask-gpt workflow: split broad work into independent tasks; package mandatory rules/specs/current source; dispatch ask-gpt Pro with account-wide rate control; track live conversations; verify real downloadable artifacts; resume same conversations with precise corrections; apply/test in isolated worktrees; land verified results sequentially; preserve durable receipts. Owner corrected deployment scope: source MUST live in `~/Projects/overdeck/modules/workstation/.claude/skills`. Repository layout maps deployed Claude skills from `modules/workstation/claude/skills`; use repository manifest/deployment contract rather than creating an untracked parallel tree. Owner then requested independent grading of six saved RED/GREEN responses against eleven executable behavior criteria, writing exact-schema `grading.json` files beside each run while leaving source and skill untouched; final comparison MUST identify every baseline and with-skill failure. Owner correction task #9 requires hidden legacy UI-selection options and human-only `--visible`. On 2026-08-11 owner added a discoverability correction: every new or resumed ask-gpt prompt MUST begin with a concise human-readable task description because ChatGPT derives conversation titles from the first line. Generic attachment-reading first lines produce repeated titles. This applies only to future sends; NEVER rerun active tasks.

## Outcome

A tested global `/gpt-orchestrator` coordinates many slower, stronger ask-gpt Pro workers without duplicate dispatch, prose-as-artifact mistakes, unsafe package/application behavior, or premature completion claims. Repository source, live installation, and landed Overdeck `main` remain identical.

## Acceptance criteria

- Source exists under Overdeck workstation Claude skills and deploys to `~/.claude/skills/gpt-orchestrator/SKILL.md`.
- Skill accepts a broad objective, task list, or existing conversation set and creates/updates one durable execution ledger.
- Skill distinguishes queued, dispatching, generating, artifact-ready, validating, correction-required, applying, verifying, landed, blocked, and failed states.
- Dispatch uses `ask-gpt --effort pro`, mandatory attached context, task-slug package names, short operational prompts, and real ZIP/script deliverables.
- Aggregate sends across new and resumed conversations remain 55–75 seconds apart unless current `ask-gpt --help` exposes a stronger built-in scheduler contract.
- Existing active conversations are never redispatched. Corrections resume the same conversation.
- Completion requires downloaded non-empty artifacts, archive safety validation, scope review, current-source comparison, isolated application, project-native clean gates, landing, deployment when applicable, and owner-visible receipt.
- Generated prose never proves a file exists. Generated patches/files never overwrite current work blindly.
- Independent tasks may generate concurrently; application, integration, and landing remain sequential when overlap exists.
- External latency never stalls all work: continue another executable lane and rely on tracked completion notifications; never poll rapidly.
- RED baseline scenarios are captured before source creation; GREEN scenarios prove the skill closes observed failures.
- Installed entrypoint is invoked/read from live path immediately after guarded landing/deploy; installed source is byte-verified against landed source.
- Every future new/resumed ask-gpt prompt starts with one concise task-description title line before operational instructions; deterministic contract tests reject generic attachment-reading first lines.
- Theme prompt line 1 MUST begin exactly `Create <theme-name> WordPress theme` and MAY append concise outcome language. Line 1 MUST NOT begin attachment-reading instructions or mention `TASK.md`/`PROMPT.md`; attachment-reading starts on line 2.
- Dispatcher MUST validate title contract before send, fail closed on mismatch, and record exact validated title in durable ledger.
- `gpt-orchestrator/SKILL.md` contains neither UI-selection option literal.
- Legacy ask-gpt UI-selection option accepts any value, including `show`, but always selects virtual mode; default also selects virtual mode.
- `ask-gpt --visible` alone selects show mode. Help marks it human-only and says agents MUST NOT choose it.
- Explicit environment safety gate remains enforced. Deterministic tests never launch a browser.

## Preserved WIP

- Prior isolated branch: `wt/gpt-orchestrator-skill`.
- Prior isolated worktree: `/home/user/Projects/overdeck/.worktrees/gpt-orchestrator-skill`.
- Preserved incoming agent ref: `worktree-agent-abb20bdaf6556eab3` at `4f408e6c27b7760e549ee3669a068e62893fa81e`.
- Preserved incoming agent path: `/home/user/Projects/overdeck/.claude/worktrees/agent-abb20bdaf6556eab3`.
- Active correction branch: `wt/gpt-orchestrator-visible-correction`.
- Active correction worktree: `/home/user/Projects/overdeck/.worktrees/gpt-orchestrator-visible-correction`.
- Existing ask-gpt conversation/artifact work remains untouched.
- Shared Overdeck checkout remains untouched.

## Constraints

- Follow `/home/user/Projects/overdeck/CLAUDE.md`.
- Follow skill-creator RED → GREEN → REFACTOR. NEVER write skill source before observing baseline failure.
- Write agent-facing docs through `agent-doc-authoring` rules.
- Use current `ask-gpt --help` as CLI source of truth; never preserve stale flags from one historical session.
- Never package secrets, credentials, private conversation indexes, dependencies, caches, logs, or unrelated repository content.
- Never trust model claims without local evidence.
- Never mutate shared/default checkouts.
- Use Overdeck guarded landing/deployment contract. The live-deploy-clone guard forbids pre-landing writes; NEVER bypass it.

## Execution steps

1. Capture durable plan and session task chain.
2. Read current ask-gpt CLI contract, workstation skill/deployment conventions, and existing orchestration patterns.
3. Create pressure scenarios; run without skill; record exact baseline failures.
4. Author minimal `gpt-orchestrator` skill from owner contract and observed failures.
5. Run same scenarios with skill; grade behavior; close loopholes; rerun.
6. Add deterministic structural/contract checks where repository convention permits.
7. Deploy through Overdeck; verify live `/gpt-orchestrator` source and behavior.
8. Commit; refresh from `origin/main`; use repository ship workflow; redeploy; verify installed source equals landed source.
9. Mark plan DONE with hashes, test counts, deployment receipt, and any explicitly justified unavailable checks.

## Current receipt

2026-08-11: Original skill remains landed/deployed at `32441c13c7ca44d7d1590eec24834afb81de6e45`; prior RED/GREEN and deployment receipts remain valid. Current owner correction is implemented in isolated worktree `/home/user/Projects/overdeck/.worktrees/gpt-orchestrator-prompt-title`, branch `wt/gpt-orchestrator-prompt-title`: `SKILL.md` now requires every new/resumed prompt to start with a concise task-description title line, places operational attachment instructions on line 2+, includes good new/correction examples and a generic-title reject example, and updates both CLI shapes. Deterministic contract test passes. Existing Factory ask-gpt task was NOT rerun. Runtime-first `packaging/deploy-local.sh` completed successfully; installed `~/.claude/skills/gpt-orchestrator/SKILL.md` byte-matches source and deterministic contract test passes. Deploy reported pre-existing shim-drift hazards in unrelated worktrees; this change does not touch shims. Landing is next.

2026-08-12 correction receipt: Plan reopened before implementation on `wt/gpt-orchestrator-visible-correction` from `origin/main` at `4f408e6c27b7760e549ee3669a068e62893fa81e`. Deterministic implementation is present but uncommitted in this worktree: `ask_gpt.py`, routing tests, skill contract test, plan, and index. A separate agent worktree contains the same five modified paths and reports 24 focused routing tests, skill contract green, full gptbridge `278 passed, 1 skipped`, and installed help/byte proof; verify these receipts directly before relying on them. Owner ordered all subagents and work stopped; child agents and guarded Factory landing retry were stopped. No worker is executing.

2026-08-12 fail-closed title correction receipt: Source and deterministic contract test updated in `/home/user/Projects/overdeck/.worktrees/fix-gpt-title-contract`. Theme line 1 MUST begin `Create <theme-name> WordPress theme`, MAY append outcome, MUST NOT begin attachment instructions or mention `TASK.md`/`PROMPT.md`; line 2 onward reads attachments. TARGET/DO NOT examples, dispatcher pre-send blocking validation, and exact title ledger recording are explicit. `gpt-orchestrator-skill.test.py`, `gpt-workflow-skill.test.py`, and `git diff --check` pass. Runtime-first `deckctl sync apply claude skills` completed; installed `~/.claude/skills/gpt-orchestrator/SKILL.md` resolves to this worktree, byte-matches source, passes focused test, and contains exact prefix/blocking/ledger rules. Sync created expected backup `/home/user/.local/state/overdeck/backups/20260812T122725Z/.claude/skills`. Commit and canonical ship pending.

## Next executable action

Commit intended four-file change, land through canonical `/ship`, deploy landed `origin/main`, then verify installed source and rule against landed bytes.
