This guide is for ordinary WebCodex coding/review work. It describes the model-facing workflow, not the internal continuity, audit, or transport protocols used to implement it.
The ordinary WebCodex coding loop is intentionally small:
work_on_project
→ inspect / search / read
→ edit
→ focused validation
→ review changes
→ finish_coding_task
work_on_project is the canonical bootstrap for normal coding and review. Give it the current task instruction and then follow the project instructions and tools returned by the connected Server.
By default it also returns a small bounded extensions catalog for selection: Skill metadata comes from the canonical project/configured/managed Skill union, and Plugin metadata is restricted to ready providers whose configured working directory matches the Project root. This metadata grants no authority and does not load Skill bodies or create Plugin bindings; use skill_read_file for Skill text, run_skill_resource only for trusted Runner-configured live scripts/ resources guarded by expected_definition_revision or Runner-installed managed resources additionally fenced by expected_package_revision, or plugin_tool describe -> call after selecting a relevant entry. Configured resource bytes remain live until execution rather than being package-revision-pinned. Set include_extension_catalog=false only when the current model context already retains that discovery metadata.
Use work_on_project for both a new coding task and an explicit continuation. WebCodex keeps bounded Workflow Session evidence so validation, review, and handoff can refer to the same unit of work, but that Session is not an authentication credential and does not widen project access.
For ordinary use you do not need to reason about WebCodex's internal continuity or audit fields. Those are implementation/maintainer contracts.
The built-in default guidance is the ordinary implementation workflow. A normal “implement/fix/refactor” task needs no role name: carry authorized work to a concrete, reviewable completion, map cross-layer changes end to end, keep the design minimal, validate proportionally, and report evidence honestly. Use only tools and protocol fields supported by the current exposed schemas.
independent_review is the only optional named role because it changes behavior.
Use it only when the task explicitly asks for an independent review pass:
Use the independent_review guidance. Review <change or commit> independently,
report concrete findings with file/line evidence and impact, and do not edit.
To request corrections as well, explicitly add “fix concrete findings and run focused regression validation.” Naming a review role alone does not authorize edits, and no role ever grants authority.
Guidance is delivered in tool results; it is not the client's system prompt and
does not grant execution authority. Host instructions, the user's task,
applicable project rules, authentication, and runtime safety policy still apply.
Delivery is not proof that a model read, retained, or followed the guidance.
work_on_project keeps its primary result compact: request static model-facing
material only when the current model context needs it, using
context_request=["project.instructions"] and/or
context_request=["webcodex.workflow"]. Workflow Session identity never proves
that the current model retained either material.
When bootstrap or discovery returns project_ref, reuse it as the project selector on ordinary Project-scoped calls. The canonical agent:<client_id>:<project_id> identity remains visible for diagnostics and explicit addressing, but the model does not need to mechanically repeat it. A short ref is Server-owned, durable and principal-scoped, carries no authority, and is reauthorized against its pinned canonical Project/root identity on every call.
work_on_project accepts guidance_profile, defaulting to direct. Workflow
contract v14 returns shared guidance, model_protocol and review roles, plus
only the selected tool_strategy: {profile, guidance}, when explicitly requested
through context_request=["webcodex.workflow"]. The selection is request-local:
choose again on exact resume without changing Session identity or business state.
It is never inferred from a Window, Session or past tool use, and grants no tools,
admission, authority or execution semantics. Builds without Experimental Code Mode
reject explicit code_mode as an invalid profile. On a work_on_project call the
workflow sidecar uses that call's guidance_profile; unrelated tools that request
webcodex.workflow use the canonical default direct profile.
direct: use the simplest sufficient primitive; batch predetermined independent observations and let the model inspect results before adaptive follow-up calls.code_mode: still use a direct primitive for one simple observation. Prefer read-only orchestration when related search/read work, cross-file investigation or synthesis saves outer model turns. Keep dependent follow-ups sequential inside one cell; parallelize only independent observations. Keep raw child results in the cell, filter and synthesize them, then emit compact decision evidence throughtext(...). Avoidtext(results)dumps and project before reaching output limits.
Both strategies retain bounded targeted reads, narrow discovery, first-class native commands/structured tools, and the same recovery, authority, review and closeout. Canonical edits and structured validators remain the default. Effectful composition is useful only when related validations save outer turns; guarded mutation composition is useful only when adaptive read -> one guarded edit benefits. Nested canonical permissions, effects, validation evidence, Jobs and retry certainty remain unchanged.
Choose the simplest sufficient inspection primitive. If the symbol, test, or implementation region is already known, prefer bounded targeted ranges and batch several related ranges when they are predetermined. For broad discovery, first request a narrow projection such as files-with-matches, count, or a small bounded match set with little context, then read the relevant ranges. A small predictable known-scope native rg via run_process/run_shell is first-class.
The bootstrap reads a fixed set of instruction entry points; it does not scan every subdirectory for rules. Before changing a path, inspect applicable nested instructions and recover any relevant missing or truncated rule content.
For branch/PR review, start with the bounded review/change-summary tools exposed by the current Server, then narrow to targeted reads or diff hunks when needed.
Use apply_text_edits as the canonical default model-generated editing path after read_files. read_revision is the model-facing snapshot handle: use it as expected_read_revision when a whole-file stale-context fence is required. Globally unique exact local edits may omit the revision; positional line_scope/occurrence, delete, and rename require it. ToolRuntime resolves the revision to the Runner's exact SHA guard internally, so the model does not copy digests. This remains the normal path even when many lines change; line count alone is not a reason to choose apply_patch. Use apply_patch only when contextual patching is materially more natural, a large/multi-hunk rewrite is awkward to express as guarded exact edits, or patch-style context itself expresses the change relationship more clearly. For repetitive code, each patch chunk needs stable, unique surrounding context such as the containing function, impl, type, test, or module; do not use a repeated single line or short fragment as the mutation anchor. Keep the requested matching guard; never weaken an explicit stale-context/concurrency fence. Use apply_unified_diff only when the input is already a standard unified diff.
Guard failures are zero-write conflicts, not reasons to weaken the guard. Re-read the current source and regenerate the intended edit against that state.
For matching_mode_rejected, keep the matching guard and do not switch to first_match. Re-read the current source. If the intended change is easy to express as exact edits, prefer apply_text_edits and use the current read_revision when a positional or stronger whole-file fence is needed. If patch form is still materially clearer, consume the bounded parser-ready read_files recovery call and preserve the requested patch guard. Never downgrade an explicit stale-context/concurrency fence.
For deterministic context_mismatch, consume the bounded read_files recovery and regenerate against current source; do not blindly repeat the same patch. If the result is outcome_unknown, inspect the workspace before deciding whether any write should be retried.
The exact matching metadata and transactional protocol are maintainer details; see the tool contract/tests when developing WebCodex itself.
Formatting is finalization, not per-edit validation. The normal loop is edit → focused validation → further edits if needed → source stabilizes → format once → final review/validation. For Rust, run formatting after relevant source stabilizes and before final diff/closeout; rerun only after later Rust edits that can change formatting. Use cargo_fmt(check=false) for intentional final formatting and check=true when read-only final formatting proof is needed. CI and release formatting gates remain unchanged.
Prefer structured validation such as cargo_test, cargo_check, or go_test when available. Use the smallest check that can detect the regression, and broaden only when the affected boundary requires it.
When a required validation is likely to outlast its synchronous grace and independent read-only inspection remains, set a short sync_wait_secs (often 1) so that already-started validation hands off as the same execution Job. Continue only independent reads, search, diff/architecture inspection, or review, then observe that Job. Do not start extra CPU-heavy validations merely for parallelism. If source covered by the running validation changes afterward, its result is stale/cache-warmup evidence rather than proof of the final workspace; run task-appropriate validation again on the final source.
When a test invocation must prove that tests actually ran, use require_tests: true or min_tests: N. These are request-scoped evidence assertions, not persistent Workflow Session requirements. If validator execution succeeds but the requested count cannot be satisfied or proven, closeout retains that invocation as an evidence gap rather than a code/test correctness failure. Otherwise, an exit-zero command that legitimately runs zero tests remains an execution result rather than proof of test coverage.
Treat validation failures as evidence, not queue-cleanliness work. If a failure invalidates the current implementation direction or blocks dependent work, diagnose and fix it before continuing that dependent work. Otherwise keep the evidence visible and continue useful independent work; resolve or revalidate when a dependency or closeout requires it. Reuse the same assertion_name when intentionally rerunning the same logical assertion. Mutation makes relevant earlier evidence stale, and outcome_unknown remains fail-closed.
Use shell/process escape hatches only when the structured validation surface cannot express the check.
Review the actual workspace/diff after editing and validation. Passing tests do not replace diff review, and a clean diff does not replace focused validation when behavior changed.
finish_coding_task returns a bounded evidence summary for closeout. Treat it as advisory evidence, not as a decision that the work is correct or complete. The model still makes the final engineering judgment and reports the result to the user.
A command or validation that outlives the synchronous grace period continues as the same WebCodex Job. Keep its exact Job identity and parser-ready continuation. If useful independent work remains, continue that work and observe the Job later; do not repeatedly poll a running Job merely to keep it visible. When the next useful action actually depends on the terminal result, use the provided host-safe wait_secs=55, wake_on=terminal continuation. The Runtime still accepts explicit observation waits up to 100 seconds, but longer model-facing waits can exceed an outer MCP Host deadline. For one Job or when any terminal result unblocks progress, use terminal; when every Job in a predetermined set is required before progress, use all_terminal. Recovery/continuation hints never authorize a retry of an uncertain effect.
Multi-window coordination is an advanced maintainer workflow, not part of the ordinary coding loop. Keep independent writers in separate worktrees/Projects and keep their Workflow Sessions separate. Use the assignment/completion tools returned by the current Server rather than copying another window's execution history.
The exact concurrency, retry, provenance, and cross-Session authorization rules are documented in Manual Multi-Window Collaboration. Their protocol fields are intentionally omitted here.
Runtime tests check that guidance is delivered consistently, remains bounded,
matches its schema, and never becomes authority. The scripted
scripts/eval_coding_loop.sh checks tool-loop mechanics; it does not run a model
or measure instruction following.
To measure behavioral benefit, compare the same model, tools, settings, and task fixtures with and without guidance over repeated runs. Include a small fix, a review-only task, existing unrelated changes, nested instructions, and an uncertain long-running effect. Compare correctness and scope preservation first, then unnecessary clarification, duplicate execution, validation quality, tool calls, and token cost. Do not infer a success-rate improvement from schema tests.
When developing WebCodex itself, use the maintainer contracts rather than expanding this user guide:
- Session model — Workflow Session continuity, messages, and evidence semantics.
- Authority model — execution authority and hard-safety layering.
- Job reliability and concurrency — Job recovery/observation contracts.
- Architecture decisions — standing implementation decisions.
Ordinary coding clients should not need those documents to complete normal repository work.