v8-runner

Use this skill to operate v8-runner as the automation layer for local 1C development projects.

Keep this file as the decision entrypoint. Load only the reference file that matches the task:

• references/command-selection.md for choosing the right command sequence.
• references/config-and-backends.md for v8project.yaml, source sets, formats, builders, and backend limits.
• references/project-workflows.md for common build, syntax, dump, launch, and source sync workflows across Designer and EDT projects.
• references/file-and-artifact-workflows.md for dump, convert, load, make/artifacts, and staged publication.
• references/testing.md for YaXUnit, Vanessa Automation, syntax checks, and artifacts.
• references/troubleshooting.md for setup failures, stale state, and environment diagnostics.

Command Form

Use the available v8-runner binary directly. If it is not on PATH, ask for the binary path or use a project-provided wrapper script.

v8project.yaml is the default project config name. A sibling v8project.local.yaml is loaded automatically for machine-local paths, credentials, tools, tests, and MCP settings. Do not pass --config v8project.yaml unless the user explicitly wants a non-default command shape or the active config path differs from the default; never pass v8project.local.yaml as --config.

Generated v8project.yaml files include a yaml-language-server modeline that points to the published master JSON Schema artifact. config init and bootstrap also create sibling v8project.local.yaml with the local overlay schema modeline and add it to .gitignore when needed.

Use JSON output only when another tool, script, or final answer needs structured results:

v8-runner --json-message build

Use text output for direct human diagnostics.

Use v8-runner version or v8-runner --version to check the installed application version; it does not require v8project.yaml.

Useful global flags:

• --version to print the application version and exit.
• --config <CONFIG> when the active config is not ./v8project.yaml.
• --json-message for machine-readable CLI envelopes.
• --workdir <WORKDIR> to override workPath; it wins over v8project.local.yaml.
• --clean-before-execution to clear logs before execution.
• --log-level <error|warn|info|debug|trace> for diagnostics.
• --no-color for plain text output.

First Pass

1. Check whether v8project.yaml exists in the 1C project root.
2. If it is missing and source files already exist, run the narrowest v8-runner config init ... command that fits the project shape.
3. If it is missing and the current source of truth is an existing infobase, run v8-runner bootstrap --connection <CONNECTION> --platform-version <VERSION>.
4. Inspect generated v8project.yaml and keep machine-local overrides in generated v8project.local.yaml.
5. Run v8-runner init only when the file infobase or EDT workspace needs to be created.
6. Run the narrowest validation command that answers the user's goal.

Useful bootstrap commands:

v8-runner config init
v8-runner config init --connection "File=build/ib"
v8-runner config init --format edt
v8-runner config init --builder IBCMD
v8-runner bootstrap --connection "File=/path/to/ib" --platform-version 8.3.27
v8-runner tools download yaxunit --sources
v8-runner tools download vanessa
v8-runner tools download client-mcp --sources
v8-runner init

Default Use-Case Routing

• Source files changed and infobase may be stale: run v8-runner build.
• Only one source-set changed: use commands that accept --source-set <NAME> instead of rebuilding or materializing everything.
• Branch switch, rebase, large object moves, stale source-backed tool extension state, or suspicious incremental state: run v8-runner build --full-rebuild.
• Syntax check: inspect format and builder, then choose syntax designer-modules, syntax designer-config, or syntax edt.
• Behavior validation: run the relevant v8-runner test ... command; tests build first unless the caller explicitly requests --no-build for an already prepared infobase.
• Missing local YAxUnit, Vanessa Automation, or onec-client-mcp-devkit setup: run v8-runner tools download yaxunit --sources, v8-runner tools download vanessa, and v8-runner tools download client-mcp --sources for source-backed setup. Omit --sources on yaxunit or client-mcp to download .cfe artifacts when builder=DESIGNER.
• Vanessa Automation debugging or scenario authoring: use v8-runner launch mcp va --wait-ready ... to start the client MCP server with VA loaded and verify the VA MCP tools before driving .feature workflows.
• Extension properties need synchronization: use v8-runner extensions or extensions --name <SOURCE_SET>.
• Infobase changes need to become Git-visible files: check git status, then run the relevant v8-runner dump ... command.
• Source files need conversion between Designer and EDT: use v8-runner convert; this is CLI-only and does not use the infobase.
• Existing .cf or .cfe artifacts need to be applied to an infobase: use v8-runner load ....
• Release artifacts need to be exported or external artifacts published: use v8-runner make ... or the artifacts alias.
• Need a 1C UI session: use v8-runner launch designer, launch thin, launch thick, or launch ordinary.
• Need an observable local external EPF runtime gate: use launch thin --execute <file.epf> --output <out> --stderr-output <stderr> --wait-for-exit --wait-timeout-ms <ms>. This opt-in mode is limited to explicit .epf files, reports PID/exit-or-timeout/artifacts, treats timeout as a CLI failure after terminating the client group, and rejects raw or configured /C, /Execute, and /Out aliases; callers must inspect the reported exit code because non-zero EPF exit is observational rather than a CLI failure; plain launch remains asynchronous.
• Need onec-client-mcp-devkit launched inside 1C without VA authoring: use v8-runner launch mcp --wait-ready ... when the caller needs a ready MCP endpoint; tune readiness with tools.client_mcp.wait_ready_timeout_ms when the project needs a shorter or longer wait, raise execution_timeout too when extending beyond the global command budget, and use bare launch mcp only for fire-and-forget startup.

Guardrails

• Do not delete or recreate an infobase, workspace, temp directory, or generated state unless the user explicitly asks or the command itself is the documented recovery path.
• Do not invent raw 1cv8, ibcmd, or 1cedtcli flags; prefer the v8-runner command surface.
• Check git status before dump when the result may overwrite or mix with existing source changes.
• Preserve failed test artifacts under workPath/temp/<runner-id>/runs/<run-id>/ for diagnosis instead of cleaning them immediately.
• Report missing local 1C utilities as environment/setup issues, not as project source failures.
• Keep final answers concrete: command run, result, relevant artifact path, and any follow-up command.

Output Discipline

When reporting results, distinguish:

• project source failures;
• v8-runner command/config failures;
• local 1C platform, EDT, IBCMD, or tool discovery failures;
• test failures and their artifact paths.