hmbown--codewhale/docs/AGENT_WORKFLOWS_0868.md

CodeWhale v0.8.68 — Agent Workflow Playbook

Status (2026-07-12): Historical. v0.8.68 shipped on 2026-07-10; this playbook's waves are complete. Two things in it remain live and should be carried forward, not re-derived: the settled product vocabulary (Fleet = who · Workflow = what order · Lane = running instance · Runtime = where/how) and the still-open dogfood residuals (#4175, #4177, #4178, #4179 — blocked on a completed live tmux stopship run with child receipts and a verifier gate).

This document tells autonomous agents how to systematically complete the v0.8.68 release. It pairs with:

• Milestone: v0.8.68 (GitHub milestone #53)
• Architecture tracker: issue #4175 (Fleet / Workflow / Lane / Runtime)
• Triage packet: issue #4092
• Master checklist: CODEWHALE_0_8_68.md (harness workspace) or tracker in repo root after merge
• Workflow files: workflows/v0868_*.workflow.js

Architecture phases (post-stopship product work)

Phase	Issue	Scope
1	#4176	Lane CLI + Runtime (tmux, worktrees, logs)
2	#4177	Workflow steps → Fleet roles
3	#4179	Gates and handoffs between roles
Dogfood	#4178	Stopship as fleet-backed lane

Vocabulary: Fleet = who · Workflow = what order · Lane = running instance · Runtime = where/how (tmux, VM, CI).

Source of truth

• Implementation base: main — all v0.8.68 fix branches start here. PR #4099 merged the quick-win cutover; do not use work/v0.9.0-cutover or .cw-worktrees/v0867-pr4047.
• codex/0868-next: stale reference only. Cherry-pick from it only when a specific issue needs a specific commit — never treat it as the active dev branch.
• Playbook/workflow definitions: merged in PR #4163 on main; implementation PRs branch from main.

Defer policy (v0.8.69 / architecture refactors)

Defer v0.8.69 refactors and broad feature lanes unless they directly unblock a stopship issue (#4090, #4093, #4094).

Category	When	Notes
Stopship (#4090, #4093, #4094)	Now	Wave 1 — release-blocking
Dogfood regressions (#3986, #3990)	After stopship	Same lane, lower priority
Catalog lane (Wave 2)	After stopship green	#4109, #4114–#4119, #4139–#4141, #4184–#4188
Workflow UI lane (Wave 3)	After stopship green	#4038, #4110, #4120–#4135
TUI copy lane (Wave 4)	After stopship green	#4112, #4142–#4148
v0.8.69 refactors / 0.9.0 architecture	Deferred	Unless required to fix #4090/#4093/#4094

Issues labeled v0.8.69 still in milestone v0.8.68 should be reclassified to DEFER (0.9.0) during sweep unless tied to a stopship fix.

Quick start

# 1. Sync and verify branch (implementation always from main)
cd CodeWhale
git fetch origin
git checkout main && git pull origin main
git checkout -b codex/v0868-fix-<issue>   # e.g. codex/v0868-fix-4090
git status -sb

# 2. Board truth
gh issue list -R Hmbown/CodeWhale --milestone "v0.8.68" --state open --limit 200
gh pr list -R Hmbown/CodeWhale --state open --limit 50 \
  --json number,title,isDraft,mergeable,milestone

# 3. Read the triage packet (do not skip)
gh issue view 4092 -R Hmbown/CodeWhale

# 4. Run verification gate before and after changes
cargo fmt --all --check
cargo clippy --workspace --all-features --locked -D warnings \
  -A clippy::uninlined_format_args -A clippy::too_many_arguments \
  -A clippy::unnecessary_map_or -A clippy::collapsible_if -A clippy::assertions_on_constants
cargo test --workspace --locked
cargo build --release -p codewhale-tui

Execution order (waves)

Work top-to-bottom. Do not start Waves 2–4 or v0.8.69 refactors until stopship is green (#4090, #4093, #4094 closed or verified fixed on main).

Wave	Workflow file	Theme	GitHub issues	Status
0	v0868_issue_sweep.workflow.js	Triage + release plan	all milestone	On demand
1	v0868_stopship_lane.workflow.js	Release blockers + dogfood regressions	#4090, #4093, #4094, #3986, #3990	Active
2	v0868_catalog_lane.workflow.js	Model catalog + Models.dev live catalog	#4109, #4114–#4119, #4139–#4141, #4184–#4188	Deferred
3	v0868_workflow_ui_lane.workflow.js	Workflow orchestration UI	#4038, #4110, #4120–#4135	Deferred
4	v0868_tui_copy_lane.workflow.js	Transcript/copy polish	#4112, #4142–#4148	Deferred
5	v0868_release_gate.workflow.js	Final verification + handoff	milestone closeout	After Waves 1–4

Models.dev live catalog chain (Wave 2)

Execute sequentially after stopship is green:

#4184 → #4185 → #4186 → #4187 → #4188

Issue	Scope
#4184	Models.dev as source of truth for provider/model metadata
#4185	Accept current live Models.dev schema in catalog parser
#4186	Normalize Models.dev provider IDs onto CodeWhale provider kinds
#4187	Fetch and cache live Models.dev catalog into ProviderLake
#4188	Demote curated bundled model data after live catalog lands

Parent tracker: #4109.

How to launch a workflow

Branch from main before starting implementation agents:

git checkout main && git pull origin main
git checkout -b codex/v0868-stopship-<issue>

Fleet-backed stopship lane (dogfood #4178)

Named fleet file: fleets/v0868-stopship.toml (roles: scout, implementer, reviewer, verifier, release_lead). Workflow: workflows/v0868_stopship_lane.workflow.js (steps bind fleet role — not raw provider/model identity).

Target shape (Phase 1 Lane CLI #4176 + Phase 2 role resolution #4177):

# Create a durable tmux-backed lane bound to stopship + fleet and launch Workflow
codewhale workflow run stopship \
  --issue 4090 \
  --fleet v0868-stopship \
  --runtime tmux \
  --goal "Fix #4090, #4093, #4094. Branch implementation from main."

codewhale lane list
codewhale lane status <lane-id>          # reconciles a finished tmux process
codewhale lane attach <lane-id>          # or: codewhale lane attach <lane-id> --print
codewhale lane logs <lane-id>
codewhale lane stop <lane-id>

workflow run validates the checked-in Workflow source and named Fleet roster, creates the Lane record, and invokes the existing Workflow tool directly via the selected Runtime backend. It does not spend an operator-model turn asking a model to choose the tool. The Workflow driver resolves each task({ role }) through the named fleet before spawning sub-agents and emits live workflow_event NDJSON receipts for run, phase, task, gate, and terminal state. Inline writes each receipt to the Lane journal as it arrives. The tmux backend launches a hidden Rust supervisor that frames arbitrary or binary child output as valid NDJSON, removes its private 0600 JSON environment sidecar before the child starts, and atomically publishes a separate bounded exit receipt. lane status and lane list reconcile that receipt to completed or failed, and fail a Lane closed when its tmux session vanished without a receipt. Start, stop, and reconciliation transitions share a per-Lane lock; a failed or unverifiable tmux kill leaves the Lane active and never triggers worktree cleanup. Every tmux Lane also persists an explicit registry-owned server socket and uses it for start, attach, liveness, and kill operations, so later changes to TMUX_TMPDIR cannot redirect lifecycle commands to the wrong server. Missing tmux and the not-yet-implemented VM/CI backends fail terminally instead of reporting a fictional Running Lane.

The public workflow run command is the explicit approval of the Workflow plan envelope and records approved_explicit_cli_command in the durable plan receipt. That approval does not silently grant child shell or full-disk authority: the host runner preserves the resolved profile/provider/model, configured allow_shell, sandbox, external sandbox, network, and MCP posture. Only a global --yolo request selects bypass/full-authority behavior. Runtime secrets are bridged outside persisted Lane argv, and an isolated worktree run resolves its workspace from the Runtime-owned worktree cwd rather than the original checkout.

Validate fleet role resolution without launching agents:

# Pure unit path (CI-safe)
cargo test -p codewhale-workflow --lib named_fleet

Direct tool paths

From CodeWhale TUI or the direct headless Workflow entrypoint:

# Headless stopship lane (deterministic host dispatch)
codewhale workflow run stopship \
  --fleet v0868-stopship \
  --runtime inline \
  --goal "Fix #4090, #4093, #4094. Branch implementation from main."

# Per-issue headless (single stopship issue)
codewhale exec --auto --output-format stream-json \
  "Run workflows/v0868_issue_implement.workflow.js for issue #4090. Branch from main."

# TUI explicit path
/workflow start workflows/v0868_stopship_lane.workflow.js

Workflows use read-only scouts first, then implementation agents in sequence. workflow run is an explicit execution command and approves that checked-in plan envelope; its children still inherit the configured durable-task permission and sandbox posture. Interactive /workflow runs retain their normal approval surfaces. Do not close #4090/#4093/#4094 until human-verified on main.

Per-issue implementation (single issue)

For one agent-ready issue:

1. gh issue view <N> -R Hmbown/CodeWhale
2. Confirm issue is in milestone v0.8.68 and has label v0.8.68
3. Run workflows/v0868_issue_implement.workflow.js with the issue number in the goal
4. Or use headless: codewhale exec --auto with the issue body as prompt
5. Open PR referencing Fixes #<N>; do not close issues until merged

Label hygiene for agent execution:

gh issue edit <N> --add-label agent-in-progress --remove-label agent-ready
# after PR merged:
gh issue close <N> --comment "Fixed in PR #<PR>"

PR harvest lane (parallel to waves)

Review community PRs without squashing authorship. Order from #4092:

PR	Issue	Notes
#4088	#4026	Mergeable; terminal selection highlight
#4087	#4082	Draft refactor; finish review
#4084	#4065	Fleet alias cleanup
#3761	#3757	Conflicting; cherry-pick if needed
#3969	#3965	Conflicting; align with #4065 first

Skills to load

Copy or reference these maintainer skills from docs/skills/:

• gh-compile-issues — classify done/quick-fix/design/defer with evidence
• codew-release-qa-sweep — release gate commands
• gh-find-prs — locate related PRs before implementing

Agent constraints

• Do not push to main, tag, release, or close issues without explicit approval
• Do not force-push or amend pushed commits
• Do cite path:line evidence for every "done" claim
• Do run the verification gate after each wave
• Do update issue #4092 with handoff notes when switching agents

Milestone status (2026-07-07)

• Source of truth: main (PR #4099 merged — quick-win cutover landed)
• Milestone v0.8.68 (#53): ~70 open / ~105 total
• Labels: v0.8.68 synced with milestone membership
• Release blockers: #4093, #4094
• Top dogfood regression: #4090 (Ctrl+C re-prompt)
• Deferred: v0.8.69 refactors and Waves 2–4 until stopship green
• Stale reference only: codex/0868-next — cherry-pick per-commit when needed