Execute "open task" until the environment is ready. Worktrunk orchestrates project initialization, service startup, and Git status; Herdr hosts the agent. Reuse project commands; do not maintain a second task database.
Choose entry point
| User intent | Execution result |
|---|---|
| Integrate work automation | Identify project commands, configure .config/wt.toml, verify initialization, services, and recovery |
| Open task and start work | Create or reuse a checkout, complete necessary preparation, verify services, then dispatch the task |
| Open directory only | Only prepare the checkout and Herdr layout, skipping hooks, services, and the agent |
| Resume task | Recheck status, fill in only missing steps, preserve uncommitted content |
| View status | Jointly report Git, environment, agent, and delivery status without performing repairs |
| Verify delivery | Run project verification commands, check current code and existing PR evidence |
Input is a repository, task branch, or checkout path, plus optional base, title, agent type, and task content. Infer known values from context; for new tasks, choose a stable branch name according to repository conventions. When multiple existing tasks match, list the candidates and confirm. Do not repeatedly ask about initialization already covered by existing authorization.
Identify tasks by target host, Git common directory, and exact branch, and match Herdr by the actual checkout path. Resume detached checkouts by explicit path. Titles and pane numbers cannot substitute for identity.
Preflight checks
- Read the target repository's
AGENTS.md, check branch, worktree, dirty state, and existing task ownership. - Use
wt --versionto confirm Worktrunk. On Windows,wtmay be Windows Terminal; in that case check and usegit-wt. The installed version'sswitch -h、hook -h、config -his authoritative. - All commands run on the host where the target repository resides. Confirm
HERDR_ENV=1before querying or controlling any Herdr session. When not in Herdr, you may continue configuring and verifying Worktrunk, but report that the terminal is not yet integrated and do not connect to external focused sessions. - Load the installed
herdr/SKILL.md; if missing, readherdr --skill. Confirmherdr worktree open --helpis available. This Skill does not require installing shell integration.
In command blocks, repo、branch、base、checkout、workspace_id and title are parsed inputs, passed explicitly on every tool call and kept quoted. The task body is passed through a separate parameter of the agent prompt and is not concatenated into shell commands.
Integrate project automation
On first integration or when preparation is incomplete, read project automation configuration. Complete the following before claiming the project is integrated:
- From
justfile, the package manager, lockfile, development documentation, and existing container configuration, identify the preparation, preparation status check, development service, health check, and verification commands. When a documentation task has no service requirement, record it as "not applicable". .config/wt.tomlis the project's source of truth for Worktrunk orchestration. Hooks and aliases call existing project commands; when a command is missing, add a minimal entry point within the scope of project authorization. Do not write a separate duplicate installation script or global hooks.pre-starthosts the blocking preparation required by the agent, andpost-starthosts background services. Put dependency ordering in a pipeline from the same source; do not assume that commands in the same table or between user and project hooks will run serially.- Configure ports, URLs, and health checks for the service derived from the repository and branch. Hashed ports may still collide; verify port ownership before startup, and do not treat another service's HTTP 200 as this task being ready.
- Verify that a new setup works, that reopening does not repeat preparation or startup, that a failed preparation does not dispatch, and that a service exit can be recovered individually. Keep real command results, not just a TOML syntax check.
When automation already exists, reuse it directly. First check the effective definitions of wt config show and wt hook show , and also check the configuration on the target baseline. The configuration may contain private values; the report should retain only command names and status. Uncommitted configuration in the main checkout will not automatically appear in a new worktree; you must confirm that the target checkout has the configuration and invocation files; do not implicitly commit on the user's behalf.
Open the working environment
The same task is opened sequentially by one controller; this Skill does not provide a concurrent scheduling lock. A checkout that already has an orchestrator job continues to be managed by that job.
-
First run "View Status". When a checkout already exists, directly check the preparation and service status, and do not execute
wt switchagain, to avoid repeating hooks. -
When there is no checkout, distinguish between an existing branch and a new branch. For a new branch, the base takes the user-specified value first, then the repository default branch; verify that the ref exists first. Fetch according to authorization when the latest baseline is needed; a ref that has not been refreshed is not called latest.
-
For a normal working environment, first review the effective
pre-switch、pre-start、post-start、post-switchand invocation files for this run. When everything complies with authorization and the invocation directory matches the target baseline configuration, let Worktrunk execute hooks natively:wt -C "$repo" switch --create "$branch" --base "$base" --no-cd --format=json --yesFor an existing branch, remove
--createand--base. The--yeshere applies only to the reviewed command for this run and does not approve future hook changes. -
When only opening the directory, or when the target configuration has not been reviewed or contains hooks beyond authorization, use
--no-hooksand do not pass--yes. When a working environment is needed, review the configuration in the target checkout and execute the named preparation and service hooks that comply with authorization, then complete the acceptance in the next section. Do not skip hooks and still report the environment as ready. -
Read the path from
pathin the switch JSON and verify the Git registration information. After an error or timeout, recheck first; the branch or directory may already have been created. When the path is occupied, the repository is wrong, there are prunable entries, or the branch does not match, preserve the scene; do not use force, clobber, or prune to fix the conflict. -
Verify dependencies and services according to "Environment Preparation and Recovery". If it fails, report the stage, exit code, and relevant logs, and do not start implementation tasks that depend on that environment.
-
Use
herdr worktree list --cwd "$repo"in.result.worktreesto findopen_workspace_idby path. If an ID already exists, reuse it and verify the checkout with workspace get; if not, execute:herdr worktree open --cwd "$repo" --path "$checkout" --label "$title" --no-focus -
Get the IDs from
.result.workspace、.result.tab、.result.root_pane. Herdr may open the parent repository workspace at the same time; record the newly created object. The checkout is always created by Worktrunk; Herdr is only responsible for opening it. -
When the user asks to start work, start the selected agent in the verified idle shell pane according to the Herdr Skill, passing in the task, checkout, service URL, and verification command. Follow the project's or current task's agent selection. When an agent already exists, check its identity; do not dispatch again when it is working, check the blockage when it is blocked, and check the scene when it is unknown.
By default, one implementation pane. When the service is already managed by a hook, do not start a second copy of the service in Herdr; you may add a log or verification pane. Another writing agent uses an independent checkout. Use --no-focusin the background, and focus only when the user explicitly requests switching.
Environment preparation and recovery
First run the project's read-only preparation check to verify dependencies, lockfile, runtime version, and generated configuration. An empty marker or the existence of a directory is not sufficient to prove preparation is complete.
| Actual state | Next step |
|---|---|
| Both preparation and service are ready | Reuse; do not rerun hooks or restart processes |
| Preparation is missing or stale, and there is no active writer | Execute the named pre-start hook, and rerun the preparation check after success |
| Preparation is stale and an agent is working | Report the conflict and coordinate a pause; do not concurrently rewrite dependencies |
| Required preparation failed | Keep the checkout, record the failure, and block subsequent service and task dispatch |
| Service is not running, preparation is ready | Execute only the corresponding post-start hook, then wait for the health check |
| Port is occupied by another checkout or an unknown process | Do not take over or kill the process; use a port override supported by the project, and synchronize startup, URL, and checks |
| workspace is closed | Reopen the same checkout, and first check whether the hook service is still running |
| checkout is missing, branch still exists | Report the missing checkout; create it only if there is intent to rebuild, and old uncommitted content cannot be recovered from the branch |
Recovery command examples are wt -C "$checkout" hook pre-start project:prepare --yes and wt -C "$checkout" hook post-start project:dev --yes. Names are based on the actual configuration; first review all commands matched by that name, and execute only the needed stages.
post-start returning only means startup has been scheduled. Accept it with a health probe that has a deadline, waiting up to 60 seconds by default; if the project has an explicit startup budget, use the project value. Confirm that the response and the process or instance identity belong to the target checkout. After a timeout, check wt config state logs get --format=json for this task's logs, distinguish between still starting, already exited, and an erroneous service, and do not blindly start it again.
Combined status and delivery verification
For each status query, first check the valid list.full, summary, custom columns, and related command configuration. Use the Worktrunk query below only when the display configuration has been reviewed and its external commands, network, and LLM calls match the intent of this query. When the configuration is unknown or contains unauthorized calls, use Git's read-only commands such as worktree, status, and log instead of wt list, record remote and summary fields as not queried, and do not modify the global configuration.
When the above conditions are met, use:
git -C "$repo" worktree list --porcelain
wt -C "$repo" list --format=json
herdr worktree list --cwd "$repo"
Worktrunk schema 1 is an array, with the path in path; schema 2 uses items, with the path in worktree.path. Check the structure first; branch rows may not have a checkout. Do not modify the global configuration in order to read status. When strictly offline and read-only, use Git instead of display columns that may execute configuration commands, and record PR and CI as not queried.
Associate Herdr by path, and read only this task's pane and agent. The table reports branch, dirty, ahead/behind, preparation status, service URL and health result, agent status, verification result, and PR/CI. Express unknown, not applicable, and failed separately. Status operations do not repair the environment, start processes, or run expensive tests.
When the user requests delivery verification, execute the project's existing checks or the configured wt verify alias. Record the command, exit code, HEAD, and dirty state. New changes make old checks stale; for a dirty workspace, recording only HEAD is insufficient to bind evidence, and a file content digest or diff is also needed. When remote status is needed, query according to the user's intent wt list --full Or forge CLI, verify the PR head SHA against the local HEAD.
Herdr's done, a successful hook startup and port listening are not proof of completion. After dispatch, verify the visible task, actual artifacts, and verification results. If it returns settled but there are no artifacts, first check agent get, the terminal, and files; only retry after confirming the previous round did not execute and there is no active work. Do not repeatedly send at a fixed delay.
Closing the workspace, stopping services, deleting the checkout, deleting the branch, commit, push, and merge each follow the user's existing authorization. Closing Herdr does not necessarily stop the hook service.wt merge may squash, rebase, and clean up; it is not an implicit acceptance button. Queue or batch dispatch loads herdr-orchestrator, and a checkout cannot be created for the same task at the same time.
Verify Skill changes
Run the platform Skill validator. Use an isolated temporary repository to execute automated acceptance scenarios, and save the real command results. Clearly list agent, remote, and concurrency scenarios that were not executed; do not substitute documentation checks for runtime evidence.