Engine functions reference.
A protocol step’s behaviour isn’t hardcoded — every side effect is a named function listed in the step’s pre_funcs or post_funcs. The engine ships 45 of them across eight families; this page is the catalogue. The list is authoritative and re-callable in any session via protocol_available_funcs().
pre_funcs vs post_funcs
pre_funcs run when a step is entered — detecting the task, loading a baseline, injecting a reminder, or resolving which AI providers to launch. post_funcs run when a step tries to advance — creating files, committing, syncing issues, or enforcing a gate.
A post_func only becomes a hard wall when its step sets post_funcs_stop_on_failure: true — that’s what turns require_spec_review_passed, check_completion_evidence, and verify_tests_pass from advisory reminders into structural gates. (Placement in pre_funcs is cosmetic for gating — the advance only checks post_funcs.)
Eight families
| Family | Count | What it covers |
|---|---|---|
| Task lifecycle & state | 5 | Detect, create, and track the task and its state file. |
| Git & branches | 5 | Branch, commit, merge, push, and open the merge request. |
| Gates & verification | 5 | The structural walls — wire as stop-on-failure post_funcs to actually gate. |
| Issue tracking | 2 | Mirror task state to the configured provider. |
| Completion & cleanup | 7 | Wrap the task up — dispatch the finish flow, archive, and reset state. |
| Refactoring test baseline | 3 | Capture a green test baseline as the refactoring safety net. |
| Optimize loop | 11 | The metric-driven autoresearch family — measure, experiment, and gate on gaming. |
| Knowledge & AI providers | 7 | Wiki upkeep and the per-phase parallel-provider launch instructions. |
| total | 45 | across eight families |
Complete function reference
Every function, by family. When is where it typically wires — pre (on step entry) or post (on advance).
| Task lifecycle & state | When | What it does |
|---|---|---|
auto_detect_task | pre | Detect the active task from the current git branch. |
verify_branch_and_task | pre | Check the branch matches task state and the task file exists (warns only). |
create_task_file | post | Write the task markdown from AI-provided content, validating frontmatter. |
set_task_state | post | Set current_task.json and rename the pending protocol log to the task. |
update_task_status_in_progress | post | Flip the task file's status frontmatter to in-progress. |
| Git & branches | When | What it does |
|---|---|---|
git_setup_branch | post | Create and check out the task branch; can carry uncommitted changes across. |
git_commit | post | Stage and commit the working tree with a task-derived message. |
git_merge_main | post | Fetch and merge the default branch, reporting any conflicts. |
git_push | post | Push the current branch to the remote with upstream tracking. |
create_merge_request | post | Open an MR / PR linked to the task's provider issue. |
| Gates & verification | When | What it does |
|---|---|---|
require_spec_review_passed | pre / post | Require a SPEC_REVIEW: PASSED note in the log before leaving code-review. |
check_completion_evidence | post | Block the advance unless the summary carries verification evidence (or the escape hatch). |
verify_tests_pass | post | Run the configured test command; a non-zero exit blocks the advance. |
validate_code_review_in_worklog | post | Confirm the code-review results were appended to the work log. |
validate_no_critical_issues_in_worklog | post | Fail if the latest review block reports any critical issues. |
| Issue tracking | When | What it does |
|---|---|---|
create_issue_if_enabled | post | Create a provider issue when issue tracking is enabled. |
update_issue_status | post | Move the linked issue to completed / closed. |
| Completion & cleanup | When | What it does |
|---|---|---|
present_completion_options | pre | With no issue provider set, offer the merge-local / push-PR / keep / discard menu. |
completion_dispatch | post | Run the completion chain: archive, commit, merge, push, status, cleanup, checkout. |
require_discard_confirmation | post | Two-step typed confirmation before a discard force-deletes the branch. |
archive_task | post | Move the finished task file into tasks/done/. |
cleanup_task_scoped_state | post | Remove the task-scoped state directory. |
clear_task_state | post | Reset current_task.json to the empty state. |
checkout_default_branch | post | Switch back to main / master after completion. |
| Refactoring test baseline | When | What it does |
|---|---|---|
capture_test_baseline | post | Snapshot the test command and result before any change. |
load_test_baseline | pre | Load the saved baseline for regression comparison. |
cleanup_test_baseline | post | Remove the baseline file once refactoring completes. |
| Optimize loop | When | What it does |
|---|---|---|
validate_optimize_setup | post | Validate optimize settings before any durable side effects are created. |
write_optimize_setup | post | Persist the validated optimize settings to state. |
capture_metric_baseline | post | Run the metric once on HEAD and record the baseline. |
validate_metric_script | post | Pre-flight the metric script — run twice, check the parser and stability. |
run_metric | pre / post | Run the metric command N times under a filtered env and aggregate. |
log_experiment_result | post | Measure HEAD and append an experiment row — the engine, not the LLM, owns the value. |
check_cost_estimate | post | Project the wall-clock cost of the run before experimentation starts. |
check_termination | post | After each iteration, test the four stop conditions and end when one matches. |
update_best_commit | post | Record the best commit + metric in the task frontmatter when a run improves. |
batch_checkpoint | post | Pause at each batch boundary for user approval (interactive optimize). |
policy_compliance_audit | post | Heuristic scan for metric-gaming; flags feed the review prompt (never blocks). |
| Knowledge & AI providers | When | What it does |
|---|---|---|
wiki_update_reminder | pre | During documentation, remind Claude to update the LLM wiki (if enabled). |
resolve_ai_providers | pre | Return the parallel AI-provider launch instructions for the code-review gate. |
resolve_ai_providers_for_investigation | pre | …for the task investigation phase. |
resolve_ai_providers_for_implementation | pre | …for the implementation planning phase. |
resolve_ai_providers_for_brainstorm | pre | …for the brainstorm analysis phase. |
resolve_ai_providers_for_exploration | pre | …for the research exploration phase. |
resolve_ai_providers_for_refactoring_planning | pre | …for the refactoring planning phase. |
Discoverable, not hardcoded
Because behaviour lives in these named functions, adding to a step is a JSON edit, not an engine change — wire a function into a step’s pre_funcs / post_funcs and it runs. To build your own workflow, fork a protocol (see customization) and compose the functions above; for the tools that drive the engine itself, see the MCP reference.