Start here

Start Here

Use this workflow at the beginning of a planning or implementation session, especially when you are adopting an existing repository or resuming work and need to confirm the correct workspace, command, artifact, and handoff path.

Primary audience: human operators starting or resuming a Day Shift session. Responsibility: establish startup procedure, CLI resolution, workspace-root discovery, read-only navigation, and collaboration boundaries; keep .day-shift/agents.md as the agent entrypoint and use .day-shift/references/ for reusable command, metadata, validation, review, registry, prompt/template, planning-layer, and structural-pressure detail.

Agent Orientation Command

<day-shift-cli> agent is the read-only agent orientation command. Use it at the start of an automation-agent session to show the repository contract, entrypoint guidance, and command envelope before the agent chooses workflow-specific commands.

agent orient is the full-orientation alias, and agent remind is the shorter correction-focused reminder for sessions that have drifted from the repository contract.

Startup Procedure

Follow these steps before any write-capable Day Shift command.

Resolve the command invocation. Expected output: a working <day-shift-cli> value for this session. Next action: for installed/user mode, run command -v day-shift, then day-shift --help. For repository development mode, use node dist/cli/index.js --help when compiled dist output is current. Install or configure the CLI before continuing only when neither the installed command nor the repository development invocation is valid for the session.
Confirm the effective workspace root. Expected output: the repository-local .day-shift/config.toml that owns the current workflow state. Next action: inspect from the current working directory toward the repository root, then keep .day-shift/ references relative to the selected workspace root.
Choose read-only navigation when the active artifact or next step is unclear. Expected output: inventory, gap, workflow, validation, or next-action evidence without file writes. Next action: run the narrowest useful command, such as <day-shift-cli> planning inventory, <day-shift-cli> planning gap-report, <day-shift-cli> workflow explain, <day-shift-cli> planning next-action, <day-shift-cli> validation links-check --scope planning --artifact <path>, or <day-shift-cli> commands inventory --format json when command availability or posture evidence is the decision input.
Select the active source spec or planning artifact. Expected output: one source spec, planning overview, task definition, implementation summary, or reconciliation artifact that owns the current work. Next action: use <day-shift-cli> spec list or <day-shift-cli> spec search <query> for spec selection, or use the repository path supplied by the operator when resuming a known artifact.
Pick the workflow that matches the active artifact. Expected output: a concrete workflow file and, when useful, a prompt or template reference for the next handoff. Next action: use .day-shift/workflows/README.md for routing, then continue into the selected workflow.
Hand off agent execution explicitly. Expected output: a prompt or request that names the active artifact, mode, and lifecycle guide. Next action: send agents to .day-shift/agents.md plus the matching .agent-lifecycle-guide.md; keep human workflow files as orientation, not as a replacement for agent lifecycle procedure.

Common Session Routes

New project: read 00-your-first-project-with-day-shift.md, initialize the workspace, capture or register the first source spec, then plan from the selected spec.
Existing repository: use .day-shift/workflows/00-existing-repository-with-day-shift.md to resolve the workspace root, run read-only inventory and validation first, decide whether migration preview or planning continuation is needed, then return to this startup route or the selected workflow.
Active spec planning: select the spec with spec list or spec search, then use 02-plan-from-spec.md.
Ready task implementation: open the existing task-definition.md, confirm readiness, then use 03-implement-from-task.md.
Completed task summaries: use 04-summarize-and-reconcile.md only after the relevant implementation summaries are complete and non-placeholder.

Working Agreement

Treat <day-shift-cli> as the resolved session invocation for command-supported Day Shift operations. Use day-shift after verifying the installed CLI in installed/user mode, and use node dist/cli/index.js in repository development mode when compiled dist output is current.
Keep .day-shift/ references relative to the effective workspace root selected for the current invocation.
Use .day-shift/ files directly when a workflow step still requires human authoring, unsupported artifact edits, or deeper file inspection than the current CLI provides.
If compatibility findings show that the resolved workspace is unsupported, malformed, or partially upgraded, keep the diagnosis read-only and move to the explicit workspace migration flow rather than performing undocumented manual file moves.
Keep the registered source spec reference for the selected planning slice as the source of truth.
Use prompts in .day-shift/prompts/user/ as handoff instructions and templates in .day-shift/templates/ as artifact shapes; do not interpret prompt front matter as human workflow procedure.
When implementation starts from an existing task, treat the selected task-definition.md as the source of truth for the active task directory and update the existing paired task artifacts in that same directory.
If repository state and conversational context disagree about which artifact is active, trust the repository tree, re-resolve the path from the user’s supplied artifact, and do not create alternate planning files until the mismatch is resolved.
Keep planning depth proportional to risk and uncertainty, preserve user-authored content, and record manual updates clearly in summaries.
If .day-shift/state/structural-pressure.json exists, treat it as a current-state index for active structural pressure rather than as the source of truth; planning and reconciliation artifacts remain canonical.

CLI-First Preflight

For any command-supported Day Shift operation, use the CLI before manual file edits. Manual creation or manual recovery is allowed only when one named exception applies:

unsupported by CLI
CLI failed
manual recovery after scaffold verification

Before creating or revising .day-shift planning artifacts, confirm:

which resolved <day-shift-cli> command supports the requested step
whether that command was run
if it was not run, which allowed manual exception applies after the resolved session invocation failed or proved unsupported
whether the effective workspace root is the intended supported workspace rather than an accidental repository-root assumption

Use prompts when the work requires synthesis, implementation, interpretation, or review language that the CLI cannot produce deterministically. Treat CLI output as the default low-token source of truth for command-supported discovery, scaffolding, promotion, readiness review, configuration, validation, and workspace-health operations.

When command-surface evidence matters, use <day-shift-cli> commands inventory --format json before inferring command availability, write posture, selected-artifact requirements, callable versus registry-only state, or mixed-posture family behavior. Use command help afterward for exact flags and examples.

When the CLI was used for command-supported planning work, include short provenance in the response, such as Scaffolded via: <day-shift-cli> task new .... When manual work uses an allowed exception, name both the skipped CLI command and the exception explicitly.

Doctor enforcement note: missing workflow provenance is a blocking error for non-grandfathered command-supported planning artifacts. Legacy artifacts committed before the 2026-06-17 enforcement cutoff are grandfathered and reported as warnings until backfilled.

Use these commands for orientation before any write-capable workflow begins:

<day-shift-cli> planning inventory: input is the workspace or selected planning scope; output is observed hierarchy plus paired task and milestone review-artifact evidence.
<day-shift-cli> planning gap-report: input is the workspace, selected scope, or artifact; output is expected-versus-observed downstream artifact evidence.
<day-shift-cli> workflow explain: input is the selected artifact path or workflow question; output is the matching workflow file, prompt handoff, and contract boundary.
<day-shift-cli> planning next-action: input is the selected artifact path or scope; output is the most likely next valid operator step without treating that suggestion as authorization to write.
<day-shift-cli> validation links-check --scope planning --artifact <path>: verify local planning trace links and hierarchy relationships without repairing or mutating artifacts.
<day-shift-cli> validation smoke --scope planning --artifact <path>: gather focused planning-validation evidence for one selected artifact; use repository-wide smoke only when broad repository context is intended.
<day-shift-cli> commands inventory --format json: gather machine-readable command availability, write posture, artifact-family, selected-artifact, callable, registry-only, and mixed-posture evidence before updating command guidance.
<day-shift-cli> templates list: confirm manifest-backed template inventory before choosing or validating a template-family artifact shape.

Treat discovery output as navigation evidence only. It can point to source specs, planning artifacts, task definitions, implementation summaries, reconciliation artifacts, or a later command, but it does not replace those durable artifacts or authorize scaffold, update, build, sync, materialization, migration-apply, or metadata writes.

Do not treat milestone reconciliation placeholders as fix work during downstream planning. Missing or incomplete milestone reconciliation becomes actionable only after every task under that milestone has a completed, non-placeholder implementation-summary.md.

For existing-repository adoption or resume work, use .day-shift/workflows/00-existing-repository-with-day-shift.md before write-capable scaffold, update, migration apply, or artifact-creation commands. That guide keeps read-only discovery and migration preview separate from normal planning continuation.

Choosing Work

Start with the lowest incomplete implementation_order surfaced by <day-shift-cli> spec list unless the user directs otherwise. Within an implementation order, prefer foundational dependencies before commands that rely on them. For example, repository detection and configuration should exist before commands that read or write workspace files.

Common Commands

Use the narrowest command that matches the current operator intent:

<day-shift-cli> spec list
<day-shift-cli> spec search <query>
<day-shift-cli> spec add --entry-file <path>
<day-shift-cli> spec archive <id>
<day-shift-cli> slice new --spec-id <id>
<day-shift-cli> slice new --slice-id <id>
<day-shift-cli> phase new --slice-overview <path> ...
<day-shift-cli> milestone new --phase-overview <path> ...
<day-shift-cli> task new --milestone-overview <path> --task-slug <slug>
<day-shift-cli> task new --milestone-overview <path> --full-set
<day-shift-cli> task promote ...
<day-shift-cli> task readiness-review --task-definition <path>
<day-shift-cli> doctor
<day-shift-cli> init
<day-shift-cli> ignore install
<day-shift-cli> config get
<day-shift-cli> config set <key> <value>
<day-shift-cli> commands inventory --format json

Reference Links

Use these references for detail that does not belong inline in startup procedure:

.day-shift/references/commands.md
.day-shift/references/spec-registry.md
.day-shift/references/prompts-and-templates.md
.day-shift/references/metadata.md
.day-shift/references/validation-and-review.md
.day-shift/references/planning-layers.md

Command Family Boundaries

Keep command-family detail in .day-shift/references/commands.md. The startup rule is to choose the narrowest command that matches operator intent:

Use write-capable commands only when the workflow step explicitly calls for a scaffold, update, build, sync, install, materialize, migration apply, or other mutation.
Use review, validation, inventory, and navigation commands as no-write evidence surfaces; their findings do not authorize a write by themselves.
Review and validation helpers such as metadata validate-update, task readiness-review, task review, milestone review, phase review, implementation-summary review, reconciliation review, validation links-check, and validation smoke are read-only findings or evidence surfaces.
Trace-link disposition findings are evidence only: validation may report retired, deleted, migrated, malformed-storage, or applied-migration state and recommend link disposition preview or migrated-only link disposition apply, but it must not repair links, infer replacement targets, rewrite unsupported body references, or mutate disposition storage.
Their findings and next-step guidance are advisory only and do not authorize writes.
When a write-capable update follows an explicit workflow handoff that names the active artifact, pass the same repository-relative path through --active-artifact <path> on the update command. Treat a mismatch as a no-write active-artifact conflict and re-resolve the selected artifact before writing.
Keep workspace migration explicit: dry-run or preview evidence is separate from confirmed apply.
When the intended .gitignore change is limited to the canonical Day Shift local-only entries, prefer <day-shift-cli> ignore install over ad hoc manual ignore-rule edits.
If a repository-wide validation command reports unrelated legacy planning warnings, do not repair them as part of the current workflow unless the selected artifact, task scope, or user request explicitly makes them relevant. Prefer the artifact-scoped validation command for current-step decisions.
For mixed-posture families such as release, version, completion, workspace migration, and link disposition, choose and name the subcommand that owns the requested behavior instead of describing the whole family as read-only or write-capable.
Prefer commands inventory --format json as the current machine-readable source for mixed-posture and registry-only command evidence; do not hard-code stale command snapshots into guidance.

When To Ask For Help

Ask the user before proceeding when:

the selected spec conflicts with its registered source spec reference
a task is not ready but implementation is requested anyway
a change would expand scope across unrelated specs
a file has user-authored content that would need to be replaced
validation cannot be run and the risk is meaningful

Stop Or Ask

Use this table before turning a finding into a write or continuing across uncertainty.

Situation	Agent action	Human guidance needed?
Active artifact path is unclear or chat context conflicts with repository state.	Stop write-capable work, re-resolve with read-only navigation, and report the artifact candidates. When a later update command should check a resolved handoff, pass `--active-artifact <path>` and require it to match the selected artifact argument.	Yes, if read-only evidence still leaves multiple plausible active artifacts.
CLI or validation reports an unsupported, malformed, or partially upgraded workspace.	Keep diagnosis read-only and route to migration preview or doctor guidance.	Yes, before migration apply or undocumented file moves.
Requested write is command-supported but the CLI is unavailable or fails.	Name the skipped command and allowed manual exception before any manual edit.	Not needed if the exception is clear and scope is narrow; ask if the recovery would replace user-authored content.
Task readiness is blocked by missing evidence, unresolved questions, or later-numbered dependencies.	Stop implementation and report the first blocker plus the artifact or decision needed to resume.	Yes, unless the workflow explicitly authorizes updating the task definition to resolve the evidence gap.
Review, validation, inventory, or next-action output recommends a write.	Treat the recommendation as evidence only and choose the separately named workflow or command that owns the write.	Ask if the write would expand scope beyond the selected artifact or task.
Reconciliation is requested before all task summaries are completed and non-placeholder.	Stop reconciliation and report the next task or summary closeout step.	Not needed unless the user wants partial reconciliation despite incomplete evidence.
Lightweight work crosses target-path, dependency, risk, or coordination boundaries.	Stop lightweight execution and recommend promotion to standard planning.	Yes, before continuing implementation under the promoted scope.
Implementation or closeout finds unintended code drift, missing edits, or validation risk.	Stop final closeout, record the gap, and fix within task scope or report the blocker.	Ask when fixing would exceed task scope or touch unrelated user-authored changes.

End Of Session

Before finishing:

summarize files changed
mention validation performed or not run
call out open questions or blockers
update planning artifacts when the work changed their meaning
confirm that task implementation updates stayed within the selected task directory and that any implementation-summary.md changes were applied to the existing paired artifact rather than to a duplicate file elsewhere