Software Delivery Workflows

Software Delivery Workflows

Overview

Use this umbrella for the lifecycle of software work: understand, plan, validate with spikes/tests, implement, debug, review, and deliver. Pick the subsection that matches the current phase; do not skip verification.

When to Use

• Writing or following implementation plans.
• Plan-only mode where no execution should occur.
• Throwaway spikes to validate feasibility.
• Test-driven development and red/green/refactor loops.
• Systematic root-cause debugging.
• Python debugpy/pdb or Node inspector debugging.
• Subagent-driven implementation plans.
• Pre-commit code review and quality gates.

Phase Playbooks

Planning

Inspect the repository and write bite-sized tasks with paths, acceptance criteria, and verification commands. In plan-only mode, stop after writing the plan and do not execute implementation.

When the user asks to brainstorm or discuss next direction rather than execute, keep the response at workflow level: describe the core product/workflow path, current state, and one or two strategic next moves in connected prose. Do not fragment the answer into long inventories of implementation details unless the user explicitly asks for a task breakdown.

If the user says not to invent a direction and points at an upstream product/repo as the reference, stop ideating and inspect that upstream implementation first. Report concrete mechanisms with file/line evidence, then map only the smallest relevant lessons back to the local project. Keep product-direction discussion concrete and short; avoid long catalogues unless the user asks for a breakdown. For Codex-style code-change and worktree behavior, use references/codex-change-worktree-patterns.md, including its SkyTurn note that current branch is the default session target and new worktree is explicit opt-in.

Spikes

Use disposable experiments to answer one uncertainty. Keep them isolated, document the result, and delete or quarantine throwaway code unless the user wants it retained.

TDD

Start with a failing test that captures the behavior, implement the minimal fix, then refactor while keeping tests green. Report real test output.

Systematic debugging

Reproduce, inspect, hypothesize, fix narrowly, and verify. Avoid speculative edits before understanding the failure. Capture logs, stack traces, and minimal repros.

For browser smoke tests in monorepos, verify the live served artifact before trusting the result: inspect the host app import path and package exports/main, because the dev server may import a workspace package from dist rather than src. If so, rebuild that package and clear persisted browser state before re-smoking. See references/workspace-browser-smoke.md.

For SkyTurn natural-flow runtime validation, treat pnpm --filter @skyturn/desktop run demo:mvp as a long-running real Hermes→Codex acceptance path. Use managed background execution rather than a foreground command capped at 600s, inspect demo .devflow/runs/*/events.ndjson for lane progress, and only report full acceptance from the final JSON (ok, graph status, screenshot bytes, commit count/git status, and run evidence). If a foreground demo times out, inspect the temp skyturn-react-demo-* repo before calling it failed; a timeout can kill a nearly successful commit lane or leave a review/commit lane with only progress and no terminal RunEvidence. Make demo agent watchdogs expire before the harness wait timeout so timeout/cancel paths emit evidence instead of being killed externally. Rebuild Electron native dependencies before real desktop validation and restore better-sqlite3 to the Node ABI afterward before trusting Node/Vitest persistence checks. If ok is false while all lanes exited 0, diagnose the failed acceptance predicate before changing product code; commit-lane prompt classification and dirty temp repos are common causes. See references/skyturn-demo-mvp-validation.md, references/skyturn-demo-mvp-runtime-closeout.md, and references/skyturn-agent-workflow-demo-watchdogs.md. When the user specifically asks whether a complete build can start from the desktop New Session input, do not substitute demo:mvp: run or design a real Electron UI acceptance that drives the New Session textarea and Create button, uses isolated userData plus a real temporary git project, and reports partial success separately from full screenshot/review/commit closure; see references/skyturn-new-session-ui-acceptance.md. For SkyTurn main-path product optimization delivery, run Hermes as the parent scheduler across independent worktrees/branches/PRs, require final JSON and structured evidence for real New Session acceptance, guard against agents modifying validation/screenshot contracts, split artifact data capture from UI display when existing RunEvidence.artifacts supports it, and keep failed-node repair/variant/rollback guidance inside existing selected-node composer/Node Modal surfaces; see references/skyturn-main-path-product-optimization-delivery.md. For multi-slice delivery lifecycle closeout, merge slices in dependency order, resolve UI/backend contract drift by keeping formal IPC names, run full gates before acceptance, and handle disposable GitHub smoke as explicit opt-in audit evidence; see references/skyturn-delivery-lifecycle-closeout.md.

For SkyTurn Loop Engineering waves, plan the product as a long-lived engineering harness, not a demo shell: user need → Hermes planning → agent execution → evidence writeback → validation/CI/PR gate → delivery → rollback/repair/variant → replay and continue. Delivery lifecycle and rollback/checkpoint work can advance in parallel, but start with a small shared contract/projection root and then split backend/runtime/UI/acceptance slices with explicit parent validation. See references/skyturn-loop-engineering-wave.md.

For SkyTurn Plan-mode UX, treat Requirements, Design, and Tasks as gated Kiro-style pages, not simultaneous markdown sections: each page requires explicit approval before the next unlocks, edits invalidate downstream approvals, and Convert to Canvas stays disabled until all three are approved. Watch React state timing when approve-and-advance occurs in one click. See references/skyturn-kiro-plan-pages.md.

For SkyTurn real desktop workflow blockers involving Electron ABI/native modules, planner-root run:start rejection, blank desktop dev renderer, or terminal run events not reaching SQLite workflow facts, keep Node/Electron ABI state explicit, verify the exact Electron import command from its real cwd, preserve the projection guard with only a narrow SQLite planner-root fallback, check Vite React-refresh preamble handling for workspace dist modules, and verify final RunEvidence triggers workflow persistence/scheduling. See references/skyturn-electron-native-workflow.md.

For SkyTurn embedded agent-terminal / PTY work, treat PTY as an inspect/takeover transport, not completion truth: keep Hermes planner PTY as the long-lived session candidate, keep Codex exec --json as the default structured automation path, gate UI by default, and split delivery into contracts, bridge runtime, Electron IPC, Hermes transport, hidden inspector UI, integration, and acceptance/docs slices. See references/skyturn-agent-pty-session-delivery.md.

For SkyTurn worktree-flow stacked delivery, match review scope to artifact state, stack slices that share public contract files, validate new_worktree run-path binding through runtime, Electron session persistence, and adapter cwd, and treat adopt/clean as safety-sensitive git operations with failure-event audit coverage. See references/skyturn-worktree-flow-stacked-delivery.md.

For SkyTurn node selection, node-level repair/variant flows, and rollback design, keep the user-visible checkpoint at the node/run boundary, not the tool-call boundary. Separate workflow graph rollback, agent thread rollback/fork, filesystem/worktree restore, and remote delivery rollback. Remote side effects such as push/PR/merge are a rollback stop; route those to repair/revert PR flows. See references/skyturn-node-checkpoint-rollback-design.md. For renderer wiring of selected-node composer actions to workflow IPC, recover interrupted child-agent red-test states deliberately, keep the renderer on typed preload APIs, hydrate action availability from workflow events/projection plus backend eligibility, and do not tunnel typed node actions through generic text input; see references/skyturn-node-action-ui-wiring.md. For selected-node composer async safety, guard stale repair/variant/rollback completions with both sessionId:nodeId scope and a monotonic action generation token; scope-only guards fail when users switch away and back to the same node. See references/skyturn-node-action-ui-async-guards.md. For selected-node composer layout or React Flow selection changes, keep app composer-target state separate from React Flow internal selection, stop node-card click propagation, verify merge helpers return unchanged node arrays when nothing semantically changed, and run real browser geometry/white-screen checks; see references/skyturn-selected-node-composer-validation.md. For contract/kernel slices in this area, stop downstream branches until review-only approves; preserve stable UI/backend status contracts, model rollback as orthogonal state, merge lifecycle events with prior request state, and persist rollback tombstones for late-declared lanes. See references/skyturn-contract-kernel-review-hardening.md. For contract/kernel implementation and review hardening, keep status unions stable, require explicit checkpoint authority for rollback eligibility, make successor scheduling order-safe, and use references/skyturn-checkpoint-contract-review-hardening.md. For Electron/backend rollback ledger and IPC slices, harden durable event ordering, crash-window idempotency, exact managed-worktree branch safety, remote mutation blockers, and successor identity validation; use references/skyturn-rollback-ledger-ipc-hardening.md. For Electron/persistence rollback ledger and IPC slices, harden durable ordering around destructive reset and remote side effects: write rollback/remote intents before mutation, keep ambiguous remote failures as blockers after replay, write rollback request evidence before local reset, recheck blockers after awaits, and validate full-SHA/exact-worktree commit proof; see references/skyturn-rollback-ledger-ipc-hardening.md. For backend ledger/IPC rollback safety, persist remote-side-effect blockers before remote mutations, keep ambiguous remote failures blocking after replay, write rollback request evidence before local reset, recheck blockers after awaits, and validate full-SHA/exact-worktree commit proof; see references/skyturn-rollback-ledger-safety.md.

For SkyTurn delivery lifecycle closeout, rerun final review after every post-review edit, keep renderer-safe ledger facts compatible with UI hydration, validate semantic lane kinds end to end across project-core and workflow-kernel, and enforce merge/sync/cleanup gates in Electron IPC as well as UI. See references/skyturn-delivery-lifecycle-closeout.md. For final multi-slice integration acceptance, review both committed and uncommitted integration diff, keep merge review gating consistent across UI/Electron/git-worktree/workflow-kernel, handle Electron-vs-Node native ABI sequencing deliberately, and keep Hermes in parent/operator mode when the user says coding agents should write code; see references/skyturn-integration-acceptance-hardening.md. For UI-slice integration PR closeout after several validated sibling PRs touch overlapping canvas/planner files, create a fresh integration worktree from origin/main, merge slice heads with audit-preserving commits, run root gates plus real browser smoke on the combined branch, and keep absorbed slice PRs open until the integration PR merges; see references/skyturn-ui-slice-integration-closeout.md.

Debuggers

For Python, use pdb/debugpy when stepping through runtime state matters. For Node, use --inspect and Chrome DevTools Protocol tooling. Verify the inspected process and port.

Subagent delivery

Dispatch independent tasks with complete context and acceptance criteria, then review outputs and run tests in the parent session. For large multi-agent delivery, create scoreable lanes before implementation: each lane needs a slug, likely files, PR split boundary, explicit checklist, fastest validation command, and a size budget. Keep transient progress in Slack/Linear/controller systems; only update durable markdown when product/API/storage/runtime/UI semantics change.

When the user assigns Hermes an architect/operator role and names implementation agents, do not hand-edit code. Stop direct edits, revert any Hermes-authored contamination only with user direction, then sequence child agents by responsibility in the same requested worktree. For SkyTurn-style split delivery, send contracts/runtime/backend/API work to Codex first and UI layout/copy/behavior to Antigravity CLI second; Hermes remains parent reviewer and validator. See references/architect-delegated-delivery.md.

For roadmap or architecture-direction work, prevent single-route stagnation: update the durable direction document to a rolling route table, identify one primary route plus at least two secondary routes per delivery wave, and add exit/rotation rules before launching more implementation agents. Cadence should follow validated agent delivery speed rather than a fixed calendar window. Treat repeated hardening of one subsystem without product-route progress as a delivery smell, even if CI stays green. When a product has a runtime-discovered operating model, do not encode seed fixtures (for example a starter roster) as the product ceiling; call out seed data as fallback and make runtime discovery the architecture target. See references/rolling-architecture-roadmaps.md.

For documentation-state audits and current-capability summaries, split subagents into bounded read-only lanes and have the parent verify exact code/doc lines before editing or reporting. Treat docs as candidate evidence, not truth: reconcile README/design claims against live main, recent merged PRs, key implementation paths, and targeted tests. Check both local branch state and remote default branch; if local is behind, report the delta explicitly and do not silently fast-forward/pull during a read-only capability summary. Separate what the product can do now from what remains experimental, mock-only, or not yet on the local checkout. When docs lag code, report that as documentation debt separately from product gaps. If the user asks for planning after recent PR/code review, do not propose new UI/features until you have audited whether existing surfaces already solve the need; explicitly avoid doing work that is already done. Broad whole-project audit agents can time out or return unactionable summaries. See references/documentation-state-audit.md.

When continuing a previous multi-agent run after context loss or budget exhaustion, do not replay completed work from summaries. First verify live state: main repo HEAD/status, worktree list, branch/remote state, dirty/untracked files, existing commits/PRs, and any external issue/chat status. Then resume at the smallest unfinished lifecycle step: review dirty lanes, commit, push, PR, or sync status. Treat a child-agent summary as a lead, not evidence. Match CI runs to the current PR head SHA, not to stale pre-push runs. If forced to stop by tool-call budget, write a handoff that distinguishes verified PRs, pushed branches with fresh CI pending, parent-validated uncommitted lanes, dirty/not-ready lanes, still-running processes, exact validation commands/results, and external status updates already sent. When cleaning old worktrees during closeout, only remove branches/worktrees that are merged or already absorbed by main; if a worktree is dirty, compare its diff against current main before force-removing, and preserve any not-merged scratch work unless the user explicitly asks to delete it. See references/dense-stack-closeout.md.

For SkyTurn delegated slice PRs where Hermes is parent/operator and Codex or Antigravity CLI implements in separate worktrees, keep the integration branch as the base for slice PRs, verify child diffs yourself, rerun verification after every post-review edit or whitespace cleanup, and read PR state back after push/create because shell commands can print URLs before a later non-zero exit. Use git diff --check HEAD~1..HEAD for committed whitespace evidence and post parent verification as a PR comment without merging. See references/skyturn-delegated-slice-pr-verification.md.

Pre-commit review

Review diff for security, correctness, tests, and maintainability. Auto-fix only safe issues, then re-run quality gates. If a targeted test command reports all tests skipped or zero intended tests run, treat that as no validation; inspect the test names/pattern and rerun until the intended assertion actually executes. Before relying on git diff --check, include new untracked files with intent-to-add (git add -N <new-file>) or stage the intended commit; otherwise whitespace checks can miss newly-created files.

UI label contract migrations

When a UI change introduces shared enum/source/status/role label helpers, separate helper-backed display text from raw provenance/accountability contracts before editing tests. Patch explicit allowlists first, keep unsafe fallback bounded, and update only assertions that observe the helper path; integration files often contain both human labels and intentionally raw proof strings. See references/ui-label-contract-migration.md.

UI canvas visual validation

For interactive canvas/UI work, separate seed/model correctness from live runtime state. A mock runner, interval, or persisted workspace can mutate the exact visual matrix you are trying to inspect. Before claiming a multi-state design is visually verified, freeze or bypass automatic state advancement, or clearly report that browser smoke only proved rendering/mounting. See references/ui-canvas-visual-validation.md for the validation pattern.

Common Pitfalls

1. Planning without repository inspection.
2. Debugging by guesswork rather than reproducing.
3. Treating a subagent report as verified completion.
4. Hand-editing code after the user explicitly assigned Hermes an architect/operator role. In that mode, direct edits are contamination: delegate implementation lanes, then verify child output.
5. Skipping tests because a change looks simple.
6. Mixing plan-only requests with execution.
7. Launching a write-heavy swarm before verifying required status sinks such as Slack, Linear, GitHub PR creation, and issue comments. If external feedback is part of done, prove connectivity first or stop before side effects. When one required sink is missing, do not partially satisfy the requirement silently: run only read-only planning/review, write a blocker to any verified authoritative tracker, and ask for either the missing connection or an explicit fallback authorization.
8. Browser/UI smoke tests in monorepos can silently exercise stale package dist output instead of edited source. Inspect the served module path or package export resolution, rebuild the package if needed, then clear persisted browser state and retry.
9. Long UI integration test files can exceed a single foreground command timeout or appear quiet under dot reporters. Do not infer success from silence. Run the exact failing -t patterns first, then run the full file; if the full file is expected to be slow, run it as a managed background process, poll/log until it exits, and treat any final stale-assertion output as a real contract mismatch to fix before pushing.
10. In agent workflow demos, an outer wait timeout is not a terminal run status. Configure adapter watchdogs to fire before the harness timeout, and inspect persisted run events before calling a timed-out run complete or failed.
11. TypeScript composite builds with a persistent tsBuildInfoFile can return success after generated output has been deleted. For launch-critical artifacts, verify the expected file exists after the build, or use tsc -b <config> --force when stale incremental state would break runtime startup. In pnpm workspaces, after merging or adding a new workspace:* dependency, refresh local links with corepack pnpm install --frozen-lockfile before trusting package-level typechecks; a missing workspace package in node_modules can make the merged code look broken locally even when the lockfile is correct.
12. In SkyTurn/Electron main, static value imports from browser-facing ESM workspace packages can break the CommonJS Electron build. Use dynamic imports inside handlers for ESM workspace values, and also declare any dynamically imported workspace package as a direct dependency of the consuming package so TypeScript/package resolution works. If a type-only import from an ESM workspace package is needed in a CommonJS module: Node16 file, use an import attribute such as import type { X } from "pkg" with { "resolution-mode": "import" }; or avoid the cross-module type import; otherwise desktop typecheck can fail with TS1541.
13. Worktree command scope is a correctness issue. After git worktree add, subsequent shell commands still run in the original directory unless you explicitly change workdir or use git -C <new-worktree> .... Do not chain worktree creation and cherry-pick/rebase/commit in one command during restacks; verify git status --short --branch inside the intended worktree before mutating.
14. Pixi/canvas tests can race React effects: a visible shell caption or ready state may appear before sprites, containers, or motion state exist. Before ticking animation or asserting travel, wait for the rendered object/inspector coordinates that prove the effect under test is populated.
15. For GitHub/Linear/API status checks with nested quotes, prefer writing a short temporary script over inline shell heredocs. Quoting corruption can turn a status probe into a false blocker.

Verification Checklist

• Current phase selected deliberately.
• Repository/context inspected before edits.
• Tests/build/lint/debug output captured where relevant.
• Diff reviewed before delivery.
• Remaining blockers called out honestly.