Getting Started

First-use guides

• Workspace initialization explains effective-root selection, generated assets, repeat-run ownership, and safe recovery.
• Configuration and first health checks covers configuration provenance, shell completion, diagnostics, and the first authorized planning action.
• Agent prompting tips and verb discipline distinguishes implementation, documentation, durable-contract, review, and validation requests.
• How to steer an agent effectively makes scope, authority, evidence, and handoff expectations explicit.

Basic is the fastest path for one scoped, independent task. It creates one parentless numbered task pair and does not require a specification, overview, slice, phase, milestone, reconciliation, or Basic-specific index.

Basic is the first workflow shown because it is the smallest useful evaluation path; it is not the default for specification-backed work. Use Structured as the normal path for planned feature work, coordinated tasks, shared acceptance criteria, or work that begins from a specification. Use Governed when staged hierarchy and formal reconciliation are required. Confirm day-shift --help works before evaluation.

Run day-shift agent inside the initialized workspace before planning or editing.

What will happen

You will initialize a disposable Git repository, preview and create one Basic task, authorize its revision-bound readiness review, open an implementation attempt, capture a Runtime baseline, make a tiny change, record validation evidence, and keep review, disposition, and closeout as separate steps. A second session will be able to recover the current state without the original chat.

Day Shift records the work agreement and evidence. Your existing coding assistant—or you—performs the implementation. Agent mode describes collaboration policy for compatible agents; it does not force an external tool to obey that policy.

Requirements and installation

You need Git, Node.js >=20.0.0, and an installed Day Shift release. Follow Installation and verify the selected executable before continuing:

command day-shift --version
command day-shift about
command day-shift doctor --runtime-only --format json

Downloads, purchases, delivery, and recovery remain on tnsds.tech. The examples below assume a POSIX-compatible shell and use replaceable timestamps in ISO-8601 form.

Create or select a disposable repository

The safest evaluation is a new disposable Git repository. If you use an existing repository, first read Add Day Shift to an existing repository, run git status --short, and identify the exact files that already belong to you.

mkdir day-shift-basic-evaluation
cd day-shift-basic-evaluation
git init
git status --short

Run commands from the intended repository root. A nearer .day-shift/config.toml selects a nested effective workspace, so confirm the root before writing. Do not aim evaluation work through a symlink that resolves outside the repository or across a nested Git repository boundary.

Initialize Day Shift

Preview initialization first. The preview is no-write evidence; the second command is the explicit workspace write.

command day-shift init --dry-run --format json
command day-shift init --format json
command day-shift agent --format json --detail compact
command day-shift doctor --artifact .day-shift/agents.md --format json

Initialization creates the managed .day-shift/ workspace at the effective root. It does not clean unrelated edits. Use --directory <path> only when a supported in-repository subdirectory should own the workspace.

Define one complete Basic task

Create basic-task.json in the disposable repository. Keep the stable taskId unnumbered; --implementation-order next owns the minimum-two-digit path prefix.

{
  "taskId": "basic-evaluation",
  "objective": "Produce one verified Basic evaluation result.",
  "targetPaths": [
    "src/basic-evaluation-result.mjs",
    "tests/basic-evaluation.test.mjs"
  ],
  "currentBehavior": "The repository has no Basic evaluation result.",
  "desiredBehavior": "The repository exposes a tested Basic evaluation result.",
  "acceptanceCriteria": [
    "The result reports the Basic evaluation as complete.",
    "The result is covered by the selected Node test command."
  ],
  "validationCommands": [
    "node --test tests/basic-evaluation.test.mjs"
  ],
  "rollbackRecovery": "Remove the runtime result and focused test.",
  "dependencies": [],
  "constraints": [
    "Keep this task independent and inside the two declared target paths."
  ]
}

Explicitly select Basic, an implementation order, agent mode, and evidence profile. Preview before applying:

command day-shift work create --level basic --implementation-order next --agent-mode guided --evidence-profile runtime --input-file basic-task.json --dry-run --format json
command day-shift work create --level basic --implementation-order next --agent-mode guided --evidence-profile runtime --input-file basic-task.json --format json

The result reports paths like these while retaining semantic task id basic-evaluation:

.day-shift/planning/basic/tasks/01-basic-evaluation/task-definition.md
.day-shift/planning/basic/tasks/01-basic-evaluation/implementation-summary.md

Set shell variables from the paths and identities returned by your command; do not copy identifiers from this page:

TASK=.day-shift/planning/basic/tasks/01-basic-evaluation/task-definition.md
SUMMARY=.day-shift/planning/basic/tasks/01-basic-evaluation/implementation-summary.md
ATTEMPT=basic-evaluation-attempt-001
mkdir -p .day-shift/runs/run-basic-evaluation

Review readiness, then explicitly authorize it

Readiness review is read-only. Save its complete JSON result unchanged because readiness authorization binds to its exact task revision, reviewer, time, protocol, and findings.

command day-shift --format json --detail full task readiness-review --task-definition "$TASK" --reviewed-by evaluator --reviewed-at 2026-08-01T00:10:00Z > .day-shift/runs/run-basic-evaluation/readiness-review.json
command day-shift task readiness-authorize --task-definition "$TASK" --review-result .day-shift/runs/run-basic-evaluation/readiness-review.json --dry-run --format json
command day-shift task readiness-authorize --task-definition "$TASK" --review-result .day-shift/runs/run-basic-evaluation/readiness-review.json --format json

A stale or edited review result writes nothing. Rerun the read-only review against the current task and deliberately authorize that new result; do not hand-edit readiness metadata.

Open an attempt and capture the pre-write baseline

Authorization does not open an implementation attempt. Open one explicitly:

command day-shift task attempt-open --task-definition "$TASK" --attempt-id "$ATTEMPT" --opened-at 2026-08-01T00:11:00Z --dry-run --format json
command day-shift task attempt-open --task-definition "$TASK" --attempt-id "$ATTEMPT" --opened-at 2026-08-01T00:11:00Z --format json

For Runtime or Hybrid evidence, copy the readinessReviewId from the saved readiness result and capture the baseline after attempt opening but before implementation writes:

READINESS_REVIEW_ID=task-readiness-review-from-your-result
command day-shift task baseline --task-definition "$TASK" --task-cycle-id "$ATTEMPT" --checkpoint-id "$READINESS_REVIEW_ID" --captured-by evaluator --captured-at 2026-08-01T00:12:00Z --dry-run --format json
command day-shift task baseline --task-definition "$TASK" --task-cycle-id "$ATTEMPT" --checkpoint-id "$READINESS_REVIEW_ID" --captured-by evaluator --captured-at 2026-08-01T00:12:00Z --format json

A dirty worktree is allowed, but attribution stays explicit. The baseline classifies every declared target. If a declared target already has an intentional edit, rerun with one exact --adopt 'path::concrete rationale' per target. Unrelated dirty paths remain visible and must not be attributed to this task. Ambiguous or unobservable ownership remains uncertain evidence; Day Shift does not promise perfect changed-path attribution.

For Contract evidence—or an explicit runtime_attribution_required: false posture—do not fabricate a Runtime baseline. Contract evidence can establish documentation or agreement truth, but it cannot claim unobserved runtime implementation.

Implement with your existing coding assistant or manually

Create only the declared runtime files. The implementation actor is you or your coding assistant, not Day Shift:

src/basic-evaluation-result.mjs

export const basicEvaluationResult = "complete";

tests/basic-evaluation.test.mjs

import assert from "node:assert/strict";
import test from "node:test";
import { basicEvaluationResult } from "../src/basic-evaluation-result.mjs";

test("Basic evaluation reaches a useful result", () => {
  assert.equal(basicEvaluationResult, "complete");
});

Build the canonical paired summary, then fill its changed paths, acceptance results, validation, runtime boundary, deviations, and follow-ups with observed evidence:

command day-shift implementation-summary build --task-definition "$TASK" --format json

Record validation without confusing the executor

Declaring validation commands does not run them. validation smoke, validation rollup, and validation links-check are read-only Day Shift checks; they do not execute arbitrary task commands. Choose one explicit posture.

Let Day Shift execute one selected declared command

This invocation asks the Day Shift child process to execute exactly the argv after --. Command-owned --dry-run must still execute the selected argv to derive an observed result, but it writes no validation record. Use that preview only when the command is safe to run twice. To execute once, check the task and attempt first, then invoke the write-capable form once; it executes and records the observed exit code and output.

command day-shift task validation-record --task-definition "$TASK" --validation-id basic-evaluation-test-001 --attempt-id "$ATTEMPT" --name "Basic evaluation test" --required true --summary "Run the one selected declared test." --dependency-mode declared --scope-path tests/basic-evaluation.test.mjs -- node --test tests/basic-evaluation.test.mjs

Day Shift does not automatically sweep every declared validation and does not execute arbitrary undeclared commands.

Record evidence from a command you ran

Here the operator is the executor and supplies the observed result. Day Shift records it without running the command:

node --test tests/basic-evaluation.test.mjs
command day-shift task validation-record --task-definition "$TASK" --validation-id basic-evaluation-manual-001 --attempt-id "$ATTEMPT" --name "Operator-run Basic test" --command "node --test tests/basic-evaluation.test.mjs" --required true --status passed --exit-code 0 --summary "The operator ran the selected declared test." --recorded-at 2026-08-01T00:13:00Z --source manual --dependency-mode declared --scope-path tests/basic-evaluation.test.mjs --dry-run --format json
command day-shift task validation-record --task-definition "$TASK" --validation-id basic-evaluation-manual-001 --attempt-id "$ATTEMPT" --name "Operator-run Basic test" --command "node --test tests/basic-evaluation.test.mjs" --required true --status passed --exit-code 0 --summary "The operator ran the selected declared test." --recorded-at 2026-08-01T00:13:00Z --source manual --dependency-mode declared --scope-path tests/basic-evaluation.test.mjs --format json

Import verified external or CI evidence

For a passed imported result, --output-reference must name a repository-relative schemaVersion: 1, mode: verified-result JSON contract whose validation id, attempt id, command, argv, source revision, status, and exit code match the record. CI or the external system is the executor; Day Shift verifies and imports the artifact.

command day-shift task validation-record --task-definition "$TASK" --validation-id basic-evaluation-ci-001 --attempt-id "$ATTEMPT" --name "CI Basic evaluation test" --command "node --test tests/basic-evaluation.test.mjs" --required true --status passed --exit-code 0 --summary "Import the verified CI result." --recorded-at 2026-08-01T00:13:00Z --source imported --source-reference ci://run/123 --output-reference evidence/basic-evaluation-verified-result.json --dependency-mode declared --scope-path tests/basic-evaluation.test.mjs --dry-run --format json
command day-shift task validation-record --task-definition "$TASK" --validation-id basic-evaluation-ci-001 --attempt-id "$ATTEMPT" --name "CI Basic evaluation test" --command "node --test tests/basic-evaluation.test.mjs" --required true --status passed --exit-code 0 --summary "Import the verified CI result." --recorded-at 2026-08-01T00:13:00Z --source imported --source-reference ci://run/123 --output-reference evidence/basic-evaluation-verified-result.json --dependency-mode declared --scope-path tests/basic-evaluation.test.mjs --format json

Use only one identity for each result; a rerun needs a new --validation-id and --supersedes-validation-id <old-id>.

Complete implementation, review, disposition, and closeout separately

After the summary body and required validation evidence are complete, calculate the current task file revision and apply implementation completion. This transition completes implementation evidence only; it does not accept review or close the task.

TASK_REVISION="$(node -e 'const c=require("node:crypto"),f=require("node:fs");process.stdout.write(c.createHash("sha256").update(f.readFileSync(process.argv[1])).digest("hex"))' "$TASK")"
command day-shift task implementation-complete --task-definition "$TASK" --attempt-id "$ATTEMPT" --task-revision "$TASK_REVISION" --completed-by evaluator --completed-at 2026-08-01T00:14:00Z --dry-run --format json
command day-shift task implementation-complete --task-definition "$TASK" --attempt-id "$ATTEMPT" --task-revision "$TASK_REVISION" --completed-by evaluator --completed-at 2026-08-01T00:14:00Z --format json

Review is read-only. Save the complete implementation-summary review because accepted disposition and closeout bind to its fresh receipt:

command day-shift implementation-summary review --task-definition "$TASK" --format json --detail full > .day-shift/runs/run-basic-evaluation/implementation-summary-review.json
command day-shift task review --task-definition "$TASK" --format json

Acceptance is a separate mutation:

command day-shift task disposition --task-definition "$TASK" --disposition accepted --review-result .day-shift/runs/run-basic-evaluation/implementation-summary-review.json --recorded-by evaluator --recorded-at 2026-08-01T00:15:00Z --dry-run --format json
command day-shift task disposition --task-definition "$TASK" --disposition accepted --review-result .day-shift/runs/run-basic-evaluation/implementation-summary-review.json --recorded-by evaluator --recorded-at 2026-08-01T00:15:00Z --format json

Accepted disposition still does not close the task. Close it explicitly with the same fresh review evidence:

command day-shift task close --task-definition "$TASK" --review-result .day-shift/runs/run-basic-evaluation/implementation-summary-review.json --dry-run --format json
command day-shift task close --task-definition "$TASK" --review-result .day-shift/runs/run-basic-evaluation/implementation-summary-review.json --format json

For accepted_with_follow_up, also supply --reason <concrete-follow-up>. For changes_requested, supply the reason, actor, and time without --review-result; then revise the task, run a fresh readiness review, and use task retry-authorize --task-definition "$TASK" --review-result <fresh-result.json> --attempt-id <successor-id> --opened-at <timestamp>. The current public CLI does not expose a readiness-reset command, so the reviewed task revision must minimally restore readiness: needs_more_evidence and remove the stale readiness_review_* authorization envelope before that fresh review; record this manual lifecycle recovery in the task body. Earlier attempts remain history. Use task block --dimension implementation|review --reason <reason> --next-decision <decision> --recorded-by <actor> --recorded-at <timestamp> for a real blocker, or task cancel --reason <reason> --recorded-by <actor> --recorded-at <timestamp> for deliberate cancellation.

Continue in a second session

A later session can use repository evidence instead of the original chat:

command day-shift work current --session default --format json
command day-shift planning next-action --artifact "$TASK" --format json
command day-shift resume create --artifact "$TASK" --session basic-evaluation --evidence "$SUMMARY" --expires-in-hours 24 --format json
command day-shift resume inspect --artifact "$TASK" --session basic-evaluation --format json
command day-shift resume resume --artifact "$TASK" --session basic-evaluation --format json

resume inspect and resume resume are read-only freshness checks. If you elected to open a repository-local lifecycle run, use command day-shift resume run status --run-directory .day-shift/runs/run-<run-id> --artifact "$TASK" --format json to revalidate its manifest. A run manifest is bounded continuation evidence, not a substitute for the canonical task pair.

An incomplete validation remains attached to its attempt. Inspect current state and use a new validation identity—or an explicit superseding identity—rather than silently overwriting the earlier result.

Existing-repository safety and recovery

Keep these boundaries visible when the evaluation is not disposable:

• init --dry-run, work create --dry-run, and every lifecycle --dry-run are previews; no write should be inferred from them.
• Direct mutations bind to exact current revisions or complete review results. Stale evidence, path collisions, symlink escapes, nested-repository ambiguity, and changed preconditions fail closed.
• Multi-file writes may report intendedPaths, changedPaths, a transactionId, and a retained recoveryPath. If the outcome is partial or uncertain, stop. Preserve the JSON result, inspect the exact reported recovery action, and roll forward or restore from that evidence; do not move .day-shift/ files manually or retry blindly.
• A mutation-plan receipt is still no-write evidence. Apply only the exact fresh receipt with command day-shift apply --receipt <.day-shift/runs/run-path.json> --expect-command <command-identity>; altered, stale, mismatched, or replayed receipts write nothing.
• Baselines separate clean, adopted pre-existing, unrelated dirty, and uncertain paths. Do not use Day Shift as a worktree cleaner and do not attribute another contributor’s edits to the evaluation task.
• Keep git status --short, the preview JSON, task pair, summary, and validation evidence available until review and closeout finish.

Remove or retain the evaluation

In a disposable repository, retain the task pair as a worked example or remove the entire disposable repository from outside its directory after confirming its path. In an existing repository, inspect git status --short and revert or remove only the two Basic target files and numbered task pair you deliberately created. Never use a broad git clean or delete the whole .day-shift/ workspace to undo one task.

If you installed a managed Day Shift version only for evaluation, inspect selection first and use command day-shift version uninstall <exact-version> --replace-with <installed-version> when another installed version should remain selected. Repository workspace customization and user-local state are separate from the executable; back them up before any manual removal. Avoid committing evaluation artifacts by reviewing the exact staged set rather than adding the repository wholesale.

A second task or Structured promotion

A second independent Basic task requires a fresh task contract and explicit --confirm-independent:

command day-shift work create --level basic --implementation-order next --agent-mode guided --evidence-profile runtime --input-file second-independent-task.json --confirm-independent --dry-run --format json

Do not use that flag for dependent tasks, shared acceptance criteria, a specification-backed feature, or coordinated work. Structured is the normal path for those cases. After creating and registering a planning-ready specification, preview Basic-to-Structured promotion:

command day-shift task promote --task-definition "$TASK" --to structured --work-id basic-evaluation-follow-up --implementation-order next --spec .day-shift/specs/basic-evaluation-follow-up.md --dry-run --format json

Verify the numbered destination, preserved unprefixed task identity, task pair, attempts, validation evidence, source references, and returned planId. Apply only the exact preview after explicit authorization:

command day-shift task promote --task-definition "$TASK" --to structured --work-id basic-evaluation-follow-up --implementation-order next --spec .day-shift/specs/basic-evaluation-follow-up.md --apply --plan-id <returned-plan-id> --actor evaluator --reason "Coordinate specification-backed follow-up work." --format json

If promotion reports an incomplete transaction, use its exact transactionId and evidenceFingerprint with the reported --recover roll-forward|restore action; do not reconstruct the move manually. Continue with Plan a feature with Structured work.