Goalflow
Use when a project needs recoverable task execution records or a multi-Goal workflow with ordered Stages, bounded Runs, exact writer ownership, independent validation, fail-closed recovery or migration, and deduplicated tiered parent-context projections. For document or image artifacts, route every direct content operation to a bounded leaf agent while the parent retains only locators, immutable identities, and the selected bounded Result projection.From its SKILL.md
npx -y skills add xunishere/goalflow --skill goalflowAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
11.6 KB, as published. Nobody here has run it
GoalFlow
GoalFlow is one orchestration product, not a scheduler. It uses the deterministic standard-library CLI at ../../scripts/goalflow.py: Goal/Stage/Run authority remains beneath the selected project's .codex-runtime, while every delegated task has its own state.json, artifacts/, and safe lock in a host-resolved task store. Host adapters share the same core; package/plugin installation never edits a project, installs agents, or creates hooks.
Respond concisely
- Answer only the questions the user explicitly asks.
- Add explanation only when the user requests it or when it is necessary for correctness, safety, or resolving a critical ambiguity.
- Do not volunteer background, alternatives, roadmaps, extra suggestions, or repeated known information.
- After executing a task, report only the necessary results, verification results, and blockers.
- Ask a question only when a critical ambiguity prevents safe execution; otherwise proceed within the explicit scope.
Start safely
- Resolve and trust the intended project root. Never infer it from an arbitrary writable directory.
- Run
python3 <plugin-root>/scripts/goalflow.py --project-root <root> inspect. - If the runtime is absent and no recognized legacy authority exists, offer
init plan; apply only the exact returned plan hash withinit apply --plan <file> --confirm-sha <hash>. Ifplan/orchestration/state.jsonexists, do not create a second control plane; use the explicit migration flow. - Name a Goal explicitly.
selected_goal_idis only a UI cursor and may be used only when it is unambiguous. - Before each mutation, pass the current
--expected-revision. Treat revision, hash, lock, containment, and identity failures as blockers.
Protect the parent context
Read parent-context.md for every workflow. Keep one deduplicated control capsule in the parent; send every leaf only a fresh bounded Run/Manifest packet, never the full parent transcript. Choose the Result profile before dispatch: control by default, decision when the parent must compare findings, or explicit evidence for one bounded verification need. Store full text and tool output in task/Run artifacts. Use compact cursor/status waits and never fetch a completed full agent report twice.
Record one recoverable task
Use goalflow task init|heartbeat|update|step|artifact|status|doctor|migrate (invoke the Python script directly when no shell wrapper named goalflow is installed). Pi defaults to the nearest Git root's .pi-tasks; Codex uses .codex-runtime/tasks only after verifying a valid runtime index and project identity, otherwise it safely falls back to project .pi-tasks. Prefer explicit --task-root for automation and every migration apply. GOALFLOW_TASK_ROOT, then GOALFLOW_HOME/tasks, override host discovery.
Bind a task at creation with --goal-id, optional --stage-id, and optional --run-id. GoalFlow validates the referenced runtime graph and records the project/runtime identity; legacy-v1 binding requires global --compatibility-mode legacy-v1. A task becoming done requires all declared steps in done|skipped|canceled and is execution bookkeeping only: it never creates a Run Result, passes validation, succeeds a Stage, completes a Goal, or supplies assessment/approval. Use the GoalFlow acceptance flow below for those decisions.
Each task directory and every state/lock/artifact path component must be a normal non-reparse entry, and non-migration commands require directory/state identity equality. Treat task state as a compact control record, not transcript or memory storage. Never reopen a terminal task or regress a terminal step; create a new task ID. Use doctor for stale heartbeat, schema, association, resource, artifact drift/orphan, and held/malformed/unsafe lock findings; never auto-delete a lock. Existing schema-v2 task records remain readable; use dry-run task migrate and review its exact-byte-guarded durable backup before apply.
Orchestrate one bounded Run
Read contract.md, runtime-layout.md, roles.md, and assurance.md. Prepare one Run with one observable objective, a bounded manifest, exact inputs and outputs, authority, constraints, checks, a leaf role, and --result-profile control|decision|evidence. Omission safely selects control; evidence is never implicit. Consolidate homogeneous micro-fixes that share that objective, writer, target set, and checks into the same Executor Run before validation. Use an available host-native agent whose capability matches the profile and create it from the bounded Run packet; GoalFlow does not auto-install or dispatch custom agents.
Select a host-native candidate
If another deterministic router selects a model, reasoning effort, role, or agent identity, its request and RoutePlan are not a GoalFlow capacity request. Never pass that router's request or RoutePlan to goalflow route. Keep the protocols and their immutable outputs distinct, then use this order at the parent's final pre-spawn branch:
- Obtain any separate model/role proposal without creating an agent.
- From fresh host-observed state, build a separate
goalflow_route_requestwhose candidate IDs map one-to-one to identities the native creation tool can address. - Invoke exactly
goalflow route --request <file>and validate the returned decision identity, exact schema, status/reason pair, and selected-candidate membership. - For a proposed decision, immediately re-observe host admission state. If compatibility, capacity, health, circuit, or cooldown changed, discard that proposal and route a fresh snapshot.
- Only after the recheck may the parent create the host-native leaf agent using exactly
selected_candidate_id, together with any independently selected model/effort/role settings. If the native tool cannot address that candidate ID, fail closed and keep the work with the parent; never substitute another candidate or claim GoalFlow controlled the launch.
When there are two or more compatible candidates, the parent must build a bounded route request from a fresh host-observed snapshot and invoke exactly goalflow route --request <file> before creating the host-native leaf agent. Launch only the returned selected_candidate_id. Treat NO_ELIGIBLE_CAPACITY as a blocker; do not guess a candidate or claim that work is queued. Because the proposal does not reserve capacity, refresh the snapshot and re-route if capacity changes before host admission or launch.
The parent must obtain and understand each candidate's active and pending work, optional max_concurrency, positive routing weight, and enabled, healthy, circuit_open, and optional cooldown_until state. active + pending is the admitted load, max_concurrency is the optional admission ceiling, weight scales capacity, enabled and healthy must both be true, circuit_open must be false, and cooldown_until must be absent or reached at the decision time. The parent must also verify required agent and Result-profile compatibility. A single compatible candidate may be used directly only after these same eligibility and immediate host-admission checks.
Routing is a pure deterministic proposal over caller-supplied data. It does not reserve capacity, discover telemetry, mutate health, queue, schedule, or dispatch. See capacity-aware load routing for the strict request and decision contract, selection rules, and admission-race limits.
For every direct document or image content operation, including one small read or edit, also read artifact-context.md. The parent routes by locator and identity; the bounded leaf performs the content operation and returns references.
For a writer, acquire the repository writer slot with the same Goal/Stage/Run identity and exact sorted targets before starting. New Goals are always assurance format 2. Legacy Goals exist only through explicit compatibility/migration and retain the distinct Validator Run and accept record path.
Do not use Executor status as the final-review trigger. After the subject Result exists, use assurance validation-run for required checks; manual validation-record is self-attested and does not satisfy the default gate. Create the complete policy-derived snapshot, then record advisory assessment and final human self-attestation against that exact snapshot. Do not invoke a model automatically. Latest same-category decisions supersede older ones. Rebuild and reassess after scoped drift; never carry approval forward. Treat every actor/separation label as self_attested_unverified, not authenticated identity.
Never claim that a prepared Run is queued or scheduled. Never let a leaf re-delegate or modify the Goal graph. Never read secrets or broaden a manifest silently.
Recover
Use recover --goal-id <id> after interruption. The default canonical view is capped at 8 KiB and retains Goal/runtime revisions, current Stage, actionable Run IDs, one current Run only when unambiguous, bounded blockers, and one next action. It follows only .codex-runtime/state.json and named immutable objects; it never scans by directory or timestamp and never resumes a cross-session running Run. Multiple actionable Runs are reported as an ambiguity instead of being guessed. --compact remains a no-op alias; request the pre-0.4 projection only with explicit --legacy-full compatibility.
A terminal compact recovery returns a bounded handoff capsule recommending a new host task or session before the next Goal. Use outputs --goal-id <id> [--offset N --limit N --view-digest <sha256>] for the human-facing deliverable view. Assurance-v2 revalidates the current policy-accepted snapshot and returns only entries whose role includes project_deliverable; legacy-v1 requires its explicit independent acceptance. Follow has_more and next_offset until complete, passing the returned view_digest on every page after offset 0. A changed view fails closed. Every page is capped at 32 KiB and excludes inputs, run artifacts, claimed evidence, logs, and immutable-object paths.
Migrate
Read migration.md before any legacy operation. Migration requires a bounded caller-supplied authority plan, explicit quiescence attestation, exact write permission for the legacy checkpoint/routing paths, and two matching snapshot hashes. Active, uncertain, incomplete, locked, or drifting inputs fail closed.
Boundaries
- No daemon, queue, dispatcher, watchdog, MCP server, invented hook, second workflow product, or alternate branded CLI.
- No automatic writes to
AGENTS.md,.codex/agents, or business files. - No mutation outside
.codex-runtimeexcept exact paths in a separately confirmed migration or Executor Run. - No payload, transcript, raw tool output, or repeated report in the parent; retain one bounded deduplicated control capsule and only the preselected Result projection.
- No direct document or image content operation in the parent; apply the artifact protocol even for one small operation.
- Detailed evidence belongs in the Run artifact root; bounded control records remain small.
- Keep active authority, accepted output projections, and archived evidence as distinct planes.