goal-flight AGENTS.md

Agent Notes

Goal Flight is installed in this repo. Check active state FIRST with python3 scripts/goalflight_session_status.py --text — definitive verdict. If active, follow the Goal Flight load order below. If no active session, do NOT auto-load the skill end-to-end — only when the user invokes /goal-flight <command>. Reading repository SKILL.md end-to-end is the load-order step that follows; do not skip it.

Companion tools (defined for non-Claude orchestrators loading this file)

• gstack — Garry Tan's skill pack (/review, /challenge, /office-hours, /plan-eng-review, /cso, /investigate, etc.). Installs at ~/.gstack/repos/gstack/.agents/skills/ and is registered per-host (Claude Code: ~/.claude/skills/; Codex: ~/.codex/skills/; Cursor: ~/.cursor/skills/). Goal Flight invokes gstack /review as the canonical chunk-level pre-commit reviewer and gstack /challenge for adversarial framing. When gstack is absent, fall back to the bundled prompt skeletons at prompts/gstack-claude-review.md and prompts/gstack-codex-challenge.md — do not hand-roll a custom review prompt.
• context-mode — MCP plugin that offloads large command outputs (diffs, integration test runs, codex tail files, large greps) to an FTS5 sandbox queried by pattern. Lets the orchestrator analyze big artifacts without consuming its own context window. Installs per-host (Claude Code: ~/.claude/plugins/cache/context-mode/...; Codex: registered via scripts/register-context-mode-codex.py).

Goal Flight Routing

• When a user invokes goal-flight or asks for durable planning, dispatch, review flights, worker orchestration, recovery, resume notes, or long-running repository work, load the Goal Flight skill wrapper first.
• Codex plugin skill path: ~/.codex/plugins/cache/goal-flight/goal-flight/<version>/skills/goal-flight/SKILL.md.
• Repository canonical workflow path: SKILL.md.
• Load order: this agent instruction file, then the installed host wrapper when available, then repository SKILL.md, then only the commands/*.md and protocols/*.md files referenced by the invoked command.
• Remote / multi-node workers (fleet). To dispatch a worker on another machine over SSH — including a remote Claude worker via claude-acp — see docs/fleet.md: node registration, the per-worker install/auth recipe, and goalflight_fleet.py dispatch. Remote Claude needs a headless subscription token on the node (claude setup-token → CLAUDE_CODE_OAUTH_TOKEN in the node env, ferried to the detached worker); full recipe: docs/fleet.md "Remote Claude worker (claude-acp) end-to-end". Local Claude worker surfaces (loop / one-shot): protocols/dispatch-routing.md "Claude worker surfaces".
• For tests of orchestrator generalization, use a nondestructive task: run doctor, make a compact plan, check capacity, launch one read-only worker, and summarize status/ledger evidence without writing to the repository.
• During an active goal-flight run, keep advancing the queue and accumulating commits per chunk until decomposition/execute is done; do not stall on engagement prompts. See repository root SKILL.md §Autonomous throughput.
• Active run + compaction: if goal-flight was already in play (verdict active per goalflight_session_status.py --text, OR open queue/ledger, OR docs-private/RESUME-NOTES-<YYYY-MM-DD>.md), run /goal-flight resume (load order above; fresh disk read of SKILL.md, not compacted snapshot), then continue in-skill: dispatch workers, review before commit, one explicit-pathspec commit per chunk. Do not fall back to default assistant mode: inline edits, abandoning current task on new ask, or hand-rolled review. Canonical sequence: SKILL.md §State → commands/resume.md → protocols/state-handoff.md.