How to steer an agent effectively

Effective steering is not a long instruction list. It is a clear decision about the next outcome, the authority the agent has, and the evidence that will show the outcome is complete. This keeps an agent from turning a request for review into implementation, treating a broad goal as permission to create extra planning layers, or substituting prose for a required runtime change.

The goal is to be specific about what and why, while leaving the agent room to use the repository’s declared workflow for how.

Give reusable operating instructions to the agent through the dedicated agent orientation and task-instruction pages. This page remains operator guidance for choosing outcomes, authority, evidence, and check-in boundaries. Behavioral compliance depends on the connected agent or integration. The core CLI cannot force an unsupported agent to comply.

Start with the next observable outcome

State one primary outcome in the first sentence. Name the artifact, behavior, or decision that should exist after the work, then choose the verb that matches it.

Instead of	Say
“Take care of the caching work.”	“Implement cache invalidation in the worker and validate restart behavior.”
“Look at the task and fix anything.”	“Review this task’s readiness and report blockers; do not modify artifacts.”
“Define the rollout.”	“Define the rollout decision record that the API and operations work will consume.”
“Make the documentation better.”	“Document the existing recovery procedure in the operator guide; do not change runtime behavior.”

Use Agent prompting tips and verb discipline when choosing the verb. In particular, reserve define for a named durable contract; use implement, document, review, validate, record, or reconcile when one of those describes the actual deliverable.

Include the boundaries that matter

The following compact request shape is usually enough:

1. Outcome: the one change, decision, or assessment wanted now.
2. Scope: selected artifact, behavior, or paths; name what is intentionally out of scope when that prevents a common detour.
3. Authority: whether this is read-only, an authorized implementation, or a selected artifact update. Do not rely on a review result to imply write permission.
4. Evidence: the validation, inspection, or review result needed before completion is claimed.
5. Handoff: whether to stop with findings, update implementation evidence, rebuild reconciliation, or request the next approval.

For example:

Review the selected milestone against its acceptance criteria. Keep this read-only. Report blockers and stale evidence separately; do not create tasks or update lifecycle metadata.

Or:

Implement the ready task through the declared task workflow. Keep changes within its target paths, run the declared validation, record fresh changed-path evidence in the implementation summary, and stop before milestone reconciliation.

These requests are clearer than a blanket “finish this.” They tell the agent when it should stop, which makes the next authorization visible rather than inferred.

Keep evaluation and mutation separate

Day Shift treats review, readiness, doctor, validation, and discovery as evidence surfaces. They can identify a safe next action, but they do not authorize it. Say “review” when you want findings; separately say “implement,” “update,” “build,” or “reconcile” when you want the corresponding write.

When an agent finds a problem, ask it first to state the narrowest supported recovery path. Then authorize that path explicitly. This prevents broad, speculative cleanup and keeps repository changes attributable to a decision you made.

For runtime-sensitive acceptance, do not accept repeated planning or documentation passes as a substitute for executable evidence. Authorize the declared runtime or hybrid breakout, require current-cycle changed paths and executable validation, then rebuild reconciliation and rerun the relevant review. This is the intended recovery route for a documentation-loop blocker.

Ask for fresh, attributable evidence

“The tests passed before” and “the file already exists” are not enough to close a current task. Ask the agent to connect the result to the present work:

• Name the task or milestone being evaluated.
• Run the validation appropriate to the changed behavior.
• Record current changed paths, validation outcomes, and any deviations.
• Require current evidence for runtime or hybrid work; pre-existing dirty paths cannot prove that the current task caused the behavior.
• Treat a missing, stale, incomplete, or incompatible receipt as a reason to rerun the supported validation, not as permission to claim success.

This gives reviews and release handoffs a reliable evidence trail without requiring you to prescribe every command.

Make prompt and workspace ownership explicit

Fresh Day Shift workspaces ship prompts, workflows, templates, references, and agent guidance, but those are workspace-owned starting points. A custom user-layer prompt can intentionally differ from the packaged default. Before relying on a rule, ask the agent to inspect the active repository guidance and report the resolved prompt source when prompt behavior matters.

Use explicit preview and reconciliation paths to adopt prompt/template upgrades. Do not ask an agent to overwrite customizations “to get current”; preservation, drift classification, and selected adoption are separate decisions. Similarly, use day-shift init --dry-run before initialization or recovery writes, and keep local dirty-release work separate from a public publication decision.

A practical session rhythm

At the start of a new session, orient the agent to the repository and then narrow it to the actual work:

day-shift agent --format json --detail compact
day-shift agent context --artifact <path> --format json --detail compact
day-shift doctor --artifact <path> --format json

Use artifact context and an artifact-scoped doctor only when an artifact is known. If it is not, tell the agent to discover the smallest supported work-selection route instead of asking it to scan or expand everything. Full orientation, broad audit, and editor-integration checks are deliberate recovery tools, not default next steps.

What to do when work goes off course

Pause the current action when the agent’s interpretation would materially expand scope, produce conflicting writes, or contradict repository evidence. Ask for the conflict, the relevant source evidence, and the smallest options that would resolve it. Do not ask the agent to continue “as best it can” when the missing choice changes product intent.

For ordinary ambiguity that the declared task, prompt, or workflow already resolves, ask the agent to state the applied contract and continue. This avoids unnecessary back-and-forth while keeping genuinely external decisions with the operator.

The most useful follow-up is often short: “Keep this read-only,” “use the selected task only,” “do not publish,” “stop after validation,” or “record newly discovered work as a follow-up.” Those boundaries make agent behavior safer without micromanaging implementation.

For end-to-end human workflow details, see Plan from a specification, Implement from a task, and Evidence review and reconciliation. Give agents the reusable stop-and-escalate protocol rather than copying system instructions into the operator request.