Discovery and specification
Work starts from current code and accepted intent, not from a blank page. The host communicates with the user while workers gather facts, and Jev selects between proceeding, researching, focused grilling or brainstorming based on an actual gap. Questions go out in small rounds and only when their prerequisites are ready, each with a recommendation and its consequences. Answers are preserved as run decisions and reopened only when invalidated, so settled answers persist across sessions.
Small, known work records just the objective, affected behavior, checks and one cohesive task — no separate specification or interview is required. Larger work is synthesized into an HTML specification covering problem, solution, acceptance criteria, user stories, interfaces, implementation decisions, testing and exclusions. Newly co-designed intent is reflected back for confirmation before dependent implementation starts; there are no repeated artifact-approval stages.
Planning and task decomposition
Phase outcomes and contracts are maintained for the whole feature before tasks are detailed. Dependencies are actual prerequisites, not phase numbering: edits that must evolve together are grouped, ownership and resources are allocated, and work whose inputs are already stable is identified as a parallel candidate. The graph expands as real facts emerge while retaining task ancestry and completed evidence — and a phase is not declared complete just because its plan is written.
The rule is one task per independently deliverable outcome. plan rejects a single task that carries three or more run outcomes or four or more of its own criteria, because nothing in it can run in parallel and one worker would receive the whole feature. Split it, or pass singleChunk with the reason the work genuinely cannot be divided; that reason is recorded and surfaces in diagnose.
A task carries its own binding guidance. skills names installed skills and references names design contracts or specification files; the runtime reads them at launch and inlines them into the worker’s prompt, so the coordinator names guidance instead of retyping it. An unreadable entry fails the launch and names every path it tried, so guidance is never silently missing.
Later work on an existing outcome continues that run rather than starting a fresh one. start with continues inherits the prior run’s acceptance criteria and every settled requirement decision, so an accepted contract or interface is not re-decided from zero. Without it, start refuses an intent that substantially repeats an existing run and names it; unrelated with a reason overrides when the overlap is coincidental. Before it opens a run, start fetches the project’s remote and requires the checkout’s HEAD to contain its freshly fetched default branch, unless base.userInstruction quotes the user naming another base; create the run branch from that default branch.
Delegation
The coordinator inspects next, then hands each ready chunk to delegate. One invocation runs the whole chunk loop autonomously: it routes and launches a worker, assembles the brief from the task contract, runs the registered checks, obtains independent other-family review, and drives repair cycles Flash → Kimi → host until acceptance or escalation. The coordinator handles only escalations, integration and feature-level verification. A worker or reviewer call stops at its configured wall-clock limit, and failed and timed-out calls still count in model-speed accounting; a reviewer call that fails without a verdict is replaced by a fresh review on another model, bounded by providerFailovers. A stopped worker call that changed nothing is routed to another family from the same budget. A check that fails beside other checks is run once more alone, and a pass there sends the chunk to review with no repair cycle spent.
{ "id": "charge", "workspace": "/abs/task-workspace" }| Outcome | Meaning |
|---|---|
| accepted | The chunk passed its checks and review, or, for host work, its checks alone. Integrate next. |
| escalated | Repair exhausted, host takeover, failed host checks, a scope question or review evidence needed — the coordinator’s turn to diagnose, answer or supply evidence. |
| route-pending | A named prerequisite must be resolved before dispatch. |
| failed | An infrastructure error; task state is preserved. |
Uncertain choices inside the chunk are made by workers themselves, through the bundled Jev helper; the coordinator reserves decide-batch for run-level questions. Task size never authorizes direct implementation — the invoking host stays the coordinator, and direct worker calls remain a legacy granular flow. Before any catalog or Jev call, worker routing checks dependency integration, worker capacity and live workspace conflicts: dispatch-blocked names the prerequisite to reconcile, and the claim rechecks the same constraints transactionally.
Parallel execution
When next.parallel.ready lists more than one candidate, delegate-batch takes every ready task id and drives them through a pool bounded by maxWorkers, starting the next id the moment a slot frees. A sequence of single delegate calls leaves configured capacity idle. One chunk failing never stops the others, and the batch returns when every chunk has an outcome — the skill runs no background scheduler.
Each batched task needs its own isolated checkout, created before the batch with the worktree operation under .amaleh/worktrees/<run-id>/<task-id>, on its own branch from the run workspace HEAD. The operation installs no dependencies, so install the project’s dependencies in that checkout when the task’s checks need them. Two tasks pointing at one checkout are refused before any worker starts, because concurrent work in one checkout serializes into ownership conflicts rather than parallel progress. Two tasks whose resources overlap, globs included, never run at once: the batch holds the later one and starts it the moment the earlier one finishes. The runtime accepts the prepared absolute workspace and merges nothing automatically; before opening the run, start verifies the checkout against the freshly fetched remote default branch, with base.userInstruction as the only override. Never give independent workers the main writable checkout concurrently, and on non-Git projects use host-controlled isolation with serialized work.
| next.parallel field | What it exposes |
|---|---|
| ready | Dependency-ready implementation candidates. Prepare a separate workspace per candidate, then hand the whole list to delegate-batch. |
| actions | Per-task verification, repair, recovery and integration actions, including tasks beyond the focus. |
| independent | A conservative batch of checks and reviews in distinct, nonconflicting workspaces, within available capacity. |
| running / available | Current execution ownership and remaining shared slots. A suggested batch is not a reservation. |
Within a single task, its registered checks run sequentially — builds and tests may share generated files. Across independent isolated checkouts, the same lint or build command can overlap, and a check that fails while they overlap is run once more alone before it counts. Checks and pi reviews hold durable activity leases: duplicate verification of one task, conflicting workspace access and capacity overflow are rejected, and interrupted ownership is reconciled through resume.
After a task passes review and its checks, accept and integrate its actual changes, then refresh next. Newly unlocked dependents need not wait for unrelated slow tasks. Integration writes to the run’s integration worktree, never the checkout the skill itself runs from, and remains a host-controlled serial boundary, and feature-wide integration checks are serialized too.
Verified delivery
Acceptance requires the task’s current checks and independent review to pass. The host then integrates the actual changes with host tools, inspecting merge conflicts and cross-task interactions, recording integration evidence and running full integration checks against the final result — task-level review cannot establish that independently correct changes compose correctly.
finish requires every task integrated, all required checks passing, and a concise claim/evidence explanation recorded per acceptance criterion, with Jev asked whether each outcome claim is supported by the actual referenced evidence. The host owns this semantic acceptance judgment; CLI check success alone cannot prove the product is correct.
finish also refuses while the health section reports delegation warnings, listing each one; an override acknowledges them with a recorded reason. The reopen warning counts only defect reopens that report a defect, not amend reopens that only change a task contract. A run that did the work by hand cannot close silently. finish additionally refuses while merging the freshly fetched remote default branch into the run’s checkout would conflict, naming the conflicting files.
The review and repair side of that acceptance gate — cross-family reviewers, coverage contracts and the Flash → Kimi → host escalation — is covered on review and recovery, and every CLI operation named here is listed in the command reference.
The whole loop is also drawn as the standalone interactive workflow graph, shipped with this build from the repository's design artifact.