Your first project with Day Shift

Use this walkthrough to start a fresh repository and choose the smallest useful workflow. A browser and inference provider are optional. The complete Basic task evaluation is the fastest terminal exercise; Structured planning is the normal path for a specification-backed feature.

1. Verify the installation

Install the exact release using Installation, then verify the executable and runtime:

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

Current repository builds require Node.js >=24.0.0. Use the selected release’s manifest for historical requirements.

2. Create and initialize a repository

For a disposable evaluation in a POSIX shell:

mkdir day-shift-evaluation
cd day-shift-evaluation
git init
day-shift init --dry-run --format json
day-shift init --format json
day-shift agent --format json --detail compact
day-shift config get --format json

Inspect the initialization preview before the write. Init creates workspace configuration, the registered root specification, and managed starting assets; it does not create implementation tasks. Review workspace initialization for nested workspace selection, optional ignore installation, and preservation of existing files. Use the existing-repository workflow when the repository already contains work.

3. Choose a browser or terminal session

For the browser, run day-shift serve --open and keep that terminal open. Use Project Brief for project intent and Specs for one change. Configure an AI provider only if you want chat assistance. GUI planning workflows explains refinement, review, and next-layer creation.

For terminal-only work, continue with the commands in the workflow selected below. Edit Markdown in your preferred editor and use your own coding agent for implementation. No running GUI server is required. Choose the GUI or CLI maps the equivalent operations.

4. Select the planning level

Work	Workflow	New planning location
One independent, scoped change	Basic task evaluation	.day-shift/planning/basic/tasks/<NN>-<task-id>/
A feature with shared requirements and direct tasks	Structured feature walkthrough	.day-shift/planning/structured/<NN>-<work-id>/
Staged work requiring formal hierarchy and reconciliation	Governed walkthrough	.day-shift/planning/governed/<NN>-<slice-slug>/

Basic does not require a specification. For specification-backed work, author and register the requirement, run spec review, and separately record planning readiness through spec disposition. Then preview work create with your chosen level before creating its first artifact. Structured is the default when valid specification input has no explicit level or parent override.

The linked walkthroughs include exact inputs and examples. Governed adds slice, phase, and milestone layers; it is unnecessary for the Basic exercise. Do not use legacy top-level numbered planning directories or planning_depth to select a new workflow.

5. Prepare, implement, and review one task

Complete the selected task’s objective, targets, acceptance criteria, validation commands, dependencies, and recovery instructions. Review readiness, authorize the current result, open an attempt, and capture the applicable baseline before source edits. Give the task and .day-shift/agents.md to your implementation agent, or perform the implementation yourself.

Record actual validation through task validation-set or the selected-command task validation-record contract. Complete the paired implementation summary, record implementation completion, review the evidence, and make acceptance and closure separate explicit decisions. The Basic walkthrough supplies the complete terminal sequence; evidence review covers the broader process.

Structured work finishes with work review and separately recorded project review and closeout. Governed work additionally reconciles each completed milestone. A generated scaffold, chat answer, review result, or delivery handoff alone cannot complete those gates.

6. Resume or recover

day-shift work current --session default --format json
day-shift planning next-action --artifact <existing-artifact> --format json
day-shift doctor --artifact <existing-planning-artifact> --format json

Substitute a real selected artifact. Preserve the task pair, recorded evidence, and any transaction journal if a write is partial or uncertain. Use resume and trace guidance and troubleshooting before retrying. Terminal and GUI users follow the same current-revision and evidence requirements.