Kaola Workflow Next

---
name: kaola-workflow-next
description: Use when starting, resuming, or running Kaola-Workflow for Codex work, also called kaola-workflow — claims the issue, writes the run's mission list, and runs it from that one file.
---
# Kaola-Workflow Next

This skill is the whole workflow: it claims the work, writes the run's mission list, and runs it.
Everything the run needs in order to survive an interruption lives in
`kaola-workflow/{project}/mission-list.md`, so a successor with no context at all resumes by
reading one file.

<!-- KW-COMPACT-RECOVERY-START -->
## Workflow Next operation authority

Recovery marker: `KW-COMPACT-RECOVERY-V2`. This complete prompt owns Workflow Next procedure.
After compact, the native V2 carrier restores global contract and dispatch, rereads durable state,
then completely reloads this prompt; no tool-use hook injects it. Read project `AGENTS.md`; it
supplements verified local facts and constraints. A project exception must state its scope and
must not weaken higher-priority instructions or host safety boundaries. Resume the recorded
frontier, and transition to Kaola-Workflow Finalization only when every mission is done.

<!-- KW-RUNTIME-DISPATCH-START -->
## Delegation

**Runtime dispatch contract (always loaded).**

Choose dispatch or inline per item: re-evaluate the choice for every mission item; one item's
choice never establishes a run-wide default. The absence of an exact named role is not proof that
all native subagent dispatch is unavailable. Keep one owner for the current cohesive production
surface when handoff and integration cost exceed the benefit, but that scope does not absorb
independent research, test authorship, documentation, or review items. Dispatch when it materially
reduces main-context residue, lets a clean context check what your own cannot, or enables genuinely
independent parallel work. Both modes are first-class; width follows the true work frontier. No
dispatch count, cap, disjointness proof, justification, approval, or fallback stigma attaches to the
judgment.

A subagent is an executor in a clean context, not a judge; where Kaola installs profiles it runs the
subagent default binding. Its handback is evidence. You hold the verdict, and you reach it by reading
the candidate — the diff, the findings, the command output — never the `result` prose alone. The
subagent burns its own narrow context, which is cheap; what you read back burns the main context,
which is the most expensive one there is and the one compaction eats. So ask for small, structured
handbacks rather than fanning out and reading everything. Fan out where breadth pays and every
handback stays small: exploring, measuring, refuting one stated claim, reviewing the same frozen
diff along different cuts (correctness, test custody, trust boundary), or producing candidates you
then choose between. Do not fan out to write the same production surface in parallel, and do not
ask the same question again expecting a different answer; more dispatch changes the cut, not the
count. When the cheaper child keeps failing an item, take it over and finish it inline; there is no
escalation ladder.

Treat the active runtime adapter below as fact authority. Inspect its effective profile discovery
and precedence, live call schema and verified fields, the subagent default binding,
model/effort/thought carrier or inheritance, tool and custody boundaries, and native background,
parallel, resume, nesting, reload, and session limits. Unknown fields stay unknown; live schema wins.

Use named, built-in, and generic routes only under their real identities. The subagent default
binding guides selection but never disables a task-sensitive override the host actually exposes. If
an exact role is absent, inspect adequate native routes; use one only when it satisfies custody,
evidence, and stop boundaries. Otherwise work inline, record the specific `capability_gap`, and
re-evaluate the next item. Never let a generic route claim a named role's identity. On a runtime
that installs no Kaola role profiles, the absence of a named role is design, not a capability gap;
choose a native route or work inline per item.

Before dispatch, write the mission's `dispatched` locator. Send a bounded, self-sufficient brief
naming the outcome, evidence, worktree or commit, custody, and stop condition. Reconcile the
promised output, not the worker.

<!-- KW-RUNTIME-DELEGATION-START -->
## Runtime adapter facts

Host: Codex. If the running host is not Codex, ignore this adapter section entirely and use the Kaola adapter installed for the actual host; if none is installed, record `capability_gap: no Kaola adapter for host <name>` and work inline.

Find the effective project or user `.codex/config.toml`, inspect its managed `[agents.<role>]` registration, then inspect the referenced `.codex/agents/kaola-workflow/<role>.toml` profile; `agents.toml` is installer source, not an installed lookup path.
Dispatch with the `spawn_agent` schema exposed by this Codex host and `agent_type: "<role>"`; omit per-call `model` and `reasoning_effort` because the TOML profile pins `gpt-5.6-luna` / `max` and file values take precedence, while preserving supported `fork_turns` and service-tier choices.

**Subagent default:** every installed Kaola TOML profile pins `model = "gpt-5.6-luna"` and `model_reasoning_effort = "max"`; file values take precedence over spawn parameters and the parent session, so omit per-call `model` and `reasoning_effort`.
**Roles:** `code-explorer`, `code-reviewer`, `doc-updater`, `implementer`, `investigator`, `knowledge-lookup`, `tdd-guide`.

The Codex host policy owns the actual tool boundary; the generated TOML profile owns the role behavior, not a duplicated tool list.
Native alternatives include the general `default`, implementation-owning `worker`, read-heavy `explorer`, and any other type the host reports; use each only under its real contract.
Honor the current session's multi-agent exposure, V1/V2 call schema, type catalog, history-fork choices, and host-owned nesting/concurrency limits; a missing custom `agent_type` does not hide other `spawn_agent` routes.
<!-- KW-RUNTIME-DELEGATION-END -->

<!-- KW-RUNTIME-DISPATCH-END -->

**First Principles.** When nothing already settles a situation, break the tie by the numbered First
Principles in the loaded machine-global workflow contract, applied in priority order. Project
`AGENTS.md` adds only local facts and constraints; a project exception must state its scope and
must not weaken higher-priority instructions or host safety boundaries. Recording a derivation is
useful and never required.

<!-- PIN: consent-in-conversation -->
**Consent.** Irreversible and value-laden calls belong to the user — ask, in conversation, before
taking one.
State the proposed destructive Git, deploy, credential, schema/public-API, capability deletion, or
forge-reorganization action and why; wait. Everything checkable remains yours to execute.
<!-- /PIN -->

## Intake, freshness, claim, and resume

- **The user named an issue**: select it exactly. Never substitute another, and never adopt an active folder's issue in its place.
- **The user described a task but named no issue**: resolve or file its issue; priority never outranks the requested work.
- If neither is named, rank the open issue list ordered by its `P0`–`P3` priority tier (`list-open`,
  below), then apply `.roadmap/_rules.md`, active folders, and archived summaries. Rank by that
  priority tier, then by scope. A shared contract/schema runs alone; otherwise prefer a closeable three-to-five issue
  set when the frontier offers it.

State the selection aloud before you claim it, including any skipped frontier item. **Everything
before the claim is free**: perform read-only measurement or ask when the pick is genuinely ambiguous.

**Task clarity.** When the intended outcome and its acceptance basis are already clear and
authorized, continue: do not demand a fixed requirement format or rewrite the issue to restate it.
When a fact is missing, read the code, reproduce, or look it up first; implementation detail inside
an authorized scope is your own judgment. Ask the user only about an unresolved choice that would
change scope, authorization, or the meaning of acceptance, and keep doing the investigation that
does not depend on the answer. When authorized to maintain the issue, express the observable outcome
and its verification basis in plain language, and cite what is already sufficient instead of
restating it. A research or design request authorizes research or design only; it does not
authorize product implementation, forge writes, or a claim.

<!-- PIN: forge-is-the-backlog -->
Establish freshness with status, fetch/prune, and upstream divergence. Continue when synchronized,
ahead-only, or no-remote; fast-forward only a clean behind-only checkout. Ask before merge, rebase,
stash, reset, or moving user dirt. Before claim, read each shortlisted candidate's own body and comments.
Comments are current state: where a comment contradicts the body, the comment wins.
<!-- /PIN -->

Observe the backlog and claim through the existing forge-specific script:

```bash
git status --short --branch
git fetch --prune
git rev-list --left-right --count @{u}...HEAD
kaola_script(){ _n="$1"; _p="plugins/kaola-workflow-gitlab/scripts/$_n"; [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; _p="$(find "$HOME/.codex/plugins/cache" -path "*/kaola-workflow-gitlab/*/scripts/$_n" -print -quit 2>/dev/null)"; [ -n "$_p" ] && [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; return 1; }
CLAIM_JS="$(kaola_script kaola-gitlab-workflow-claim.js)"; KAOLA_SCRIPTS="$(dirname "$CLAIM_JS")"
node "$CLAIM_JS" list-open
node "$CLAIM_JS" watch-mr >/dev/null 2>&1 || true
```

If a GitLab remote and an authenticated `glab` are available, read the open issues:

```bash
glab issue view {N} --comments -F json
```

Repeat the detail read for each shortlisted `{N}`. Set `KAOLA_TARGET_ISSUES` to the selected
comma-separated set, then claim it (use `--target-issue N` for a singleton):

```bash
kaola_script(){ _n="$1"; _p="plugins/kaola-workflow-gitlab/scripts/$_n"; [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; _p="$(find "$HOME/.codex/plugins/cache" -path "*/kaola-workflow-gitlab/*/scripts/$_n" -print -quit 2>/dev/null)"; [ -n "$_p" ] && [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; return 1; }
CLAIM_JS="$(kaola_script kaola-gitlab-workflow-claim.js)"; KAOLA_SCRIPTS="$(dirname "$CLAIM_JS")"
node "$CLAIM_JS" startup --runtime codex --target-issues "$KAOLA_TARGET_ISSUES"
```

The claim is bookkeeping: `workflow-state.md` records issues, branch, and worktree. Its typed output
reports a fact about the target rather than a verdict. `owned`/`acquired` continues; an existing active folder resumes; user
dirt or an irreversible choice goes back to the user. Never adopt an unrelated active folder.

## Resume

On resume, read `mission-list.md` top to bottom. Done results are known, todo items are the frontier,
and in-flight locators must be reconciled. Look for the work, not for the worker. Check the locator:
if the output the dispatch promised has landed, close it; otherwise re-dispatch, unless you can
positively show the dispatch is alive.

## Write the mission list

Create `kaola-workflow/{project}/mission-list.md` immediately after claim: one H1 goal and ordered
entries. Items are positional; nothing depends on a stable ID, and absent fields are simply absent.

| field | content | written |
|---|---|---|
| `item` | the mission — one line of prose, hints and facts | at creation |
| `status` | `todo` \| `in-flight` \| `done` | on change |
| `dispatched` | what went out and to whom, and **where the output was to land** | at dispatch |
| `result` | where the outcome landed — a path, or a few lines inline | at close |

Three writes only: create with `status: todo`; before the work goes out, set `in-flight` and write
the locator; close with `done` and result. Inline work uses `dispatched: self`. A completed item and
its result are immutable; one dispatch has one result, including FAIL/BLOCKED.

An item is a mission, not a specification, selector, assertion, command, review round, role,
model, dependency edge, or write set. A failed command, intermediate finding, repair attempt,
or review round does not by itself create a mission. Keep working within the current promised
outcome while custody and causal boundary remain unchanged. Append a mission only for a new
recoverable outcome that changes custody or for a newly discovered independent causal class. Do
not return `BLOCKED` merely because work remains;
`BLOCKED` means the current owner cannot safely or legitimately continue.

## Run it

Read list minus done minus in-flight and choose one frontier item. The orchestrator holds issue
selection and decomposition, design, the reading of acceptance meaning, the final verdict on a
candidate it has read (diff and findings, not the `result` prose), and finalization; subagents
execute and report. Custody answers who may decide meaning. Failure frontier, then freeze: focused
acceptance, affected inventory, causal repair, exact-candidate review; any mutation invalidates prior
PASS evidence for changed bytes. When a `tdd-guide` holds the acceptance tests, the implementer does
not delete, weaken, or reinterpret them to pass; when you wrote the tests yourself, you hold that
meaning. Writing the tests, implementing, and reviewing yourself are all legitimate paths; an
independent review is an optional clean-context check on a frozen candidate whose findings come back
to you for the verdict. Decide how much to explain by what communication needs, and how much to
verify by behavioral impact and the existing requirements; a short explanation or a small change
never lowers acceptance, and sufficient existing evidence may be cited rather than reproduced.
Finalization, closure, archive, and sink are never mission items. No dispatch count, cap,
disjointness proof, justification, approval, or fallback stigma attaches to the judgment. Subagents
and worktrees are tools, offered and declinable.

When all items are done, transition explicitly to:

```text
kaola-workflow-finalize
```

Before continuing or stopping print:

```text
Workflow project: {project}
Issue: {issue or set}
Branch: {branch from workflow-state.md, or TBD if not yet claimed}
Mission list: {n done / n in-flight / n todo}
Next: {the next skill, or the frontier item you are opening}
```

## Co-active Folders

Distinct active folders have separate state, branches, and worktrees. Keep their commits separate,
and never touch another session's branch, worktree, folder, or issues.

After finalization closes the whole set and archives the folder, stop and await explicit
redirection; never auto-route. Multi-issue closure is all-or-nothing.

<!-- KW-COMPACT-RECOVERY-END -->