Existing repository with Day Shift

Existing Repository With Day Shift

Use this workflow when you are adding Day Shift to a repository that already has code, documents, planning notes, or a .day-shift/ tree, or when you are resuming Day Shift work in a repository whose current workspace state is uncertain.

If read-only discovery identifies a legacy planning shape, continue through Migrate an existing workspace before any structural write. That workflow names the supported compatibility layouts, exact plan digest, canonical destinations, lock and staging paths, and recovery proof required after interruption.

Primary audience: human operators. Responsibility: establish the effective workspace root, gather read-only evidence, decide how source intent should enter the spec registry, and choose the next safe workflow without mixing discovery with write-capable scaffold or migration apply steps.

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.

Outcome

At the end of this workflow, you should have:

a verified <day-shift-cli> command for this session
the effective Day Shift workspace root or a clear finding that no compatible workspace exists yet
read-only inventory, gap, workflow, and validation evidence for the current state
a source-spec decision: reuse a registered spec, register a new spec, or capture a missing source spec before planning
either a normal planning next step, a migration preview next step, or a blocked finding that needs operator review

Next action: after discovery is complete, continue through .day-shift/workflows/02-plan-from-spec.md, .day-shift/workflows/03-implement-from-task.md, or .day-shift/workflows/04-summarize-and-reconcile.md according to the active artifact and evidence.

Agent Doctor Anytime

At any point while adopting or resuming an existing repository, you can ask an agent to run Day Shift doctor and resolve any reported errors. This keeps compatibility and workspace-health issues separate from planning or migration decisions before or during discovery.

Copy this prompt:

Use `.day-shift/workflows/00-existing-repository-with-day-shift.md`.

Run `<day-shift-cli> doctor` for this repository. Report the doctor findings first. If doctor reports errors, resolve only those errors with the narrowest safe changes, preserve unrelated user content, rerun doctor, and stop when doctor passes or when a blocker needs my decision. Keep discovery read-only until doctor is clean, and do not run migration apply or planning scaffold commands unless I explicitly approve that next step.

Command the prompt tells the agent to use:

<day-shift-cli> doctor

Why: doctor is the read-only baseline workspace-health check. It can be run before or during discovery so unsupported, malformed, or partially upgraded workspace state is handled intentionally before write-capable scaffold, update, migration apply, or artifact-creation commands.

1. Resolve The CLI Command

Use the installed command in a normal target repository:

command -v day-shift
day-shift --help

If the installed command is unavailable, install or configure the Day Shift CLI before continuing.

In this guide, <day-shift-cli> means whichever command you verified for this session. Use .day-shift/references/commands.md for command-family boundaries and help discovery.

2. Resolve The Workspace Root

Start from the directory where you intend to work and inspect upward toward the repository root for a valid Day Shift workspace marker:

find .. -name config.toml -path "*/.day-shift/config.toml" -print

Expected output: one repository-local .day-shift/config.toml that owns the current workflow state, or no marker if Day Shift has not been initialized for this repository yet.

Keep .day-shift/ references relative to the effective workspace root selected for this invocation. Do not assume the workspace must be at repository root; supported repositories may use a workspace under an in-repository subdirectory when that directory contains the valid .day-shift/config.toml marker.

If multiple candidate workspaces appear, stop and choose the intended workspace before running write-capable commands. If a workspace looks malformed, partially upgraded, or unsupported, keep the next step read-only and move to migration preview rather than manually moving .day-shift/ files.

3. Run Read-Only Discovery

Use read-only commands first so existing work is not changed during orientation:

<day-shift-cli> doctor
<day-shift-cli> spec list
<day-shift-cli> planning inventory
<day-shift-cli> planning gap-report

If you already know the active artifact, scope discovery to it:

<day-shift-cli> workflow explain --artifact <path>
<day-shift-cli> planning next-action --artifact <path>
<day-shift-cli> validation links-check --scope planning --artifact <path>
<day-shift-cli> validation smoke --scope planning --artifact <path>

These commands provide evidence only. They do not create planning artifacts, repair trace links, migrate a workspace, or authorize later writes by themselves.

4. Decide How Source Intent Enters The Registry

Use the spec registry before creating planning artifacts:

<day-shift-cli> spec list
<day-shift-cli> spec search <query>

If the repository already has a registered active spec that matches the work, continue from that spec or its linked planning artifact. If the source intent exists in a repository file or external document but is not registered, capture the source spec decision before planning from it. If the source intent is missing or stale, write or recertify that source intent before creating downstream planning artifacts.

Use .day-shift/references/spec-registry.md for registry field meanings, source references, and linked planning metadata. Do not inspect .day-shift/specs/index.json directly until spec list or spec search has shown that lower-level inspection is needed.

5. Separate Discovery From Writes

Read-only discovery commands include:

<day-shift-cli> spec list
<day-shift-cli> spec search <query>
<day-shift-cli> planning inventory
<day-shift-cli> planning gap-report
<day-shift-cli> planning next-action
<day-shift-cli> workflow explain
<day-shift-cli> validation links-check --scope planning --artifact <path>
<day-shift-cli> validation smoke --scope planning --artifact <path>

Write-capable commands require an explicit workflow step and selected target. Examples include init, ignore install, spec create, spec add, work create, work task create, slice new, phase new, milestone new, task new, promotion apply, metadata update commands, implementation-summary build, reconciliation build, template materialization, structural-pressure sync, and workspace migration apply.

Do not run write-capable scaffold, update, build, sync, materialize, or migration apply commands because a read-only command suggested a next action. Treat suggestions as evidence, then choose the matching workflow explicitly.

6. Preview Migration Before Apply

workspace migrate has two distinct modes. If discovery reports unsupported or partially upgraded workspace metadata, preview the schema transition:

<day-shift-cli> workspace migrate --dry-run --target-schema-version 1

Review the preview output before any apply operation. Apply migration only after the operator intentionally chooses it:

<day-shift-cli> workspace migrate --target-schema-version 1 --confirm apply-workspace-migration

If discovery reports legacy planning organization, inspect structural actionability and the complete deterministic plan:

<day-shift-cli> workspace migrate --check
<day-shift-cli> workspace migrate --plan --mapping <work-unit-id=level> --root-order <work-unit-id=NN> --task-sequence <work-unit-id:task-id=sequence>

Resolve every ambiguous work unit with --mapping <work-unit-id=basic|structured|governed>. Apply only the exact authorized plan:

<day-shift-cli> workspace migrate --apply --expected-plan-digest <digest> --confirm apply-workspace-migration

Schema preview, structural check, and structural plan are read-only. Structural planning reports deterministic or explicit Basic/Structured root order, parent-local direct Structured task sequence, every numbered move, metadata insertion, reference rewrite, revision rebinding, retirement, and recovery action. Structural apply may create canonical parents, move planning artifacts beneath basic/, structured/, or governed/, retire legacy sources, and record transaction/mapping evidence. A stale digest, path collision, ambiguous mapping, sequence conflict, unsupported artifact, or incomplete transaction blocks success and returns typed recovery guidance. Do not perform undocumented manual moves of .day-shift/ files as a substitute for migration preview, apply, or recovery.

If apply returns incomplete or reports cleanup errors, stop normal writes and preserve its transactionId, recoveryPath, and recoveryFingerprint. Reinspect the reported targets, then use only the exact offered roll-forward or restore action through workspace migrate --recover with actor, reason, current fingerprint, and --confirm recover-workspace-migration. Live locks, changed fingerprints, diverged targets, missing staged evidence, and unsafe restoration reject without recovery mutation. See Transaction and operational recovery.

7. Legacy Runtime-Acceptance Metadata

Older planning artifacts can omit the nested runtime_acceptance metadata block. Its absence alone is supported legacy state: it is not a workspace-schema incompatibility and should not block normal milestone or task scaffolding.

Do not use workspace migrate, metadata update, phase update, or milestone update to repair a missing block. Neither schema-mode nor structural-mode migration authors nested runtime-acceptance structures, and the metadata update commands do not author them either. More importantly, deciding whether runtime acceptance is required and which stable criterion IDs apply is planning judgment that the CLI cannot infer safely.

If the existing parent has no executable runtime evidence, continue the normal lifecycle without adding the block. If its acceptance criteria or Runtime Delta make runtime behavior in scope, pause for that explicit classification and authorization for a reviewed planning edit; then rerun the selected lifecycle command. Do not label this decision as an upgrade failure.

8. Choose The Next Workflow

After read-only discovery:

If no Day Shift workspace exists and this is a new Day Shift setup, use .day-shift/workflows/00-your-first-project-with-day-shift.md.
If a registered source spec is selected and planning needs to be created or extended, use .day-shift/workflows/02-plan-from-spec.md.
If an existing task definition is ready to implement, use .day-shift/workflows/03-implement-from-task.md.
If every task summary under a milestone is completed and non-placeholder, use .day-shift/workflows/04-summarize-and-reconcile.md; run reconciliation build/review and verify the milestone reconciliation.md is populated instead of leaving the scaffold placeholder behind.
If the next action is unclear, rerun the narrowest workflow explain, planning next-action, or artifact-scoped validation command.

Agent execution handoff stays separate from this human workflow. When you want an agent to execute a lifecycle, point it at .day-shift/agents.md plus the matching .agent-lifecycle-guide.md file.

9. Prompt And Command Handoffs

Use this section when discovery shows that normal Day Shift planning or implementation should continue. Each handoff has two parts: the prompt you give the agent, and the command that prompt tells the agent to use first so the repository state stays deterministic.

Specification To Planning Work

Workflow-guide prompt form:

Workflow: .day-shift/workflows/02-plan-from-spec.md
Prompt: .day-shift/prompts/user/specification.next.md
Spec source: [Relative Path To Spec File Or Spec Directory]

Preview the selected Basic, Structured, or Governed planning work from the specification.

Custom prompt to use:

Use `.day-shift/workflows/02-plan-from-spec.md`.
Also use `.day-shift/prompts/user/specification.next.md`.

Spec: <registered-spec-id-or-spec-path>

Choose Basic only for one independent task. Choose Structured for normal planned-feature work, or Governed when staged slice/phase/milestone/reconciliation review is required. Preserve source traceability and stop after the selected work creation is previewed and validated.

Command the prompt tells the agent to use:

<day-shift-cli> work create --spec <canonical-spec-path> --level structured --implementation-order <NN|next> --dry-run

Why: Structured is the normal planned-feature default and previews .day-shift/planning/structured/<NN>-<work-id>/overview.md before direct tasks at tasks/<NN>-<task-id>/. Basic previews one direct pair at .day-shift/planning/basic/tasks/<NN>-<task-id>/, and Governed previews the direct numbered slice root at .day-shift/planning/governed/<NN>-<slice-slug>/slice-overview.md. Basic/Structured root implementation_order and direct Structured task sequence supply path prefixes without changing semantic identities. Specifications remain under .day-shift/specs; planning and promotion never move them. Existing unnumbered Basic/Structured paths remain compatibility inputs until an explicit migration is reviewed and applied.

Slice To Phase

Workflow-guide prompt form:

Workflow: .day-shift/workflows/02-plan-from-spec.md
Prompt: .day-shift/prompts/user/slice.next.md
Slice overview: [Relative Path To Slice Overview]
Phase overview: [Relative Path To Phase Overview]

Create the next phase from the slice overview.

Custom prompt to use:

Use `.day-shift/workflows/02-plan-from-spec.md`.
Also use `.day-shift/prompts/user/slice.next.md`.

Slice overview: <path-to-slice-overview>

Create the next declared phase overview, or create the full declared phase set when explicitly requested. Do not create milestones or tasks in this step.

Command the prompt tells the agent to use:

<day-shift-cli> phase new --slice-overview <path-to-slice-overview> --phase-slug <phase-slug>

Why: slice.next.md is the slice-to-phase handoff. The command creates the phase overview under the selected slice and keeps phase creation separate from downstream milestone or task scaffolding.

Phase To Milestone

Workflow-guide prompt form:

Workflow: .day-shift/workflows/02-plan-from-spec.md
Prompt: .day-shift/prompts/user/phase.next.md
Phase overview: [Relative Path To Phase Overview]

Create the next milestone from the phase overview, keep it focused on acceptance-checkpoint scope rather than task execution detail, initialize the milestone `reconciliation.md` placeholder, and preserve traceability back to the phase and upstream planning artifacts.

Custom prompt to use:

Use `.day-shift/workflows/02-plan-from-spec.md`.
Also use `.day-shift/prompts/user/phase.next.md`.

Phase overview: <path-to-phase-overview>

Create the next declared milestone overview and its pending milestone reconciliation artifact. Do not create task directories in this step.

Command the prompt tells the agent to use:

<day-shift-cli> milestone new --phase-overview <path-to-phase-overview> --milestone-slug <milestone-slug>

Why: phase.next.md advances only into milestone planning. The command creates the milestone milestone-overview.md plus the pending reconciliation.md that will later roll up completed task summaries.

Milestone To Task

Workflow-guide prompt form:

Workflow: .day-shift/workflows/02-plan-from-spec.md
Prompt: .day-shift/prompts/user/milestone.next.md
Milestone overview: [Relative Path To Milestone Overview]

Create the next task directory from the milestone overview, keep the task implementation-sized, initialize both `task-definition.md` and `implementation-summary.md`, and preserve traceability back to the milestone and upstream planning artifacts.

Custom prompt to use:

Use `.day-shift/workflows/02-plan-from-spec.md`.
Also use `.day-shift/prompts/user/milestone.next.md`.

Milestone overview: <path-to-milestone-overview>

Create the next declared task directory, or create the full declared task set when explicitly requested. Create only task definitions and paired implementation-summary placeholders.

Command the prompt tells the agent to use:

<day-shift-cli> task new --milestone-overview <path-to-milestone-overview> --task-slug <task-slug>

Why: milestone.next.md creates implementation-sized task artifacts from a milestone. The command keeps scaffolding limited to declared tasks and leaves implementation plus reconciliation for later lifecycle steps.

Task To Implementation

Workflow-guide prompt form:

Workflow: .day-shift/workflows/03-implement-from-task.md
Prompt: .day-shift/prompts/user/task.next.md
Task definition: [Relative Path To Task Definition]

Implement the task, keep changes within scope, run the listed validation when feasible, update `implementation-summary.md` in the same task directory, and use the supported metadata sync/update command for the originating task definition so completed work no longer remains in a ready state.

Custom prompt to use:

Use `.day-shift/workflows/03-implement-from-task.md`.
Also use `.day-shift/prompts/user/task.next.md`.

Task definition: <path-to-task-definition>
Mode: implement

Confirm readiness, implement within scope, run validation, update the paired implementation summary, and close the task artifacts.

Command the prompt tells the agent to use:

<day-shift-cli> task readiness-review --task-definition <path-to-task-definition>

Why: task.next.md starts implementation only after the task is ready. The readiness review is read-only and catches missing evidence, dependency blockers, and sequencing problems before code or documentation changes begin.

Implementation Summaries To Milestone Reconciliation

Workflow-guide prompt form:

Workflow: .day-shift/workflows/04-summarize-and-reconcile.md
Prompt: .day-shift/prompts/user/implementation.next.md
Milestone directory: [Relative Path To Milestone Directory]

Review the milestone, use the completed task `implementation-summary.md` files under that milestone as the implementation source of truth, and update milestone-level `reconciliation.md` with acceptance-criteria review, validation review, discovered work, and follow-up tasks.

Custom prompt to use:

Use `.day-shift/workflows/04-summarize-and-reconcile.md`.
Also use `.day-shift/prompts/user/implementation.next.md`.

Milestone overview: <path-to-milestone-overview>

Build and complete milestone reconciliation from the completed task implementation summaries. Reconcile only after every task summary is completed and non-placeholder. After build or repair, re-open `reconciliation.md` and verify it contains concrete completed-task summary links, acceptance-criteria review, validation review, final notes, and a stated milestone verdict.

Command the prompt tells the agent to use:

<day-shift-cli> reconciliation build --milestone-overview <path-to-milestone-overview>

Why: implementation.next.md advances from completed task evidence into milestone review. The build command refreshes the milestone reconciliation.md from task summaries before final manual review and reconciliation review; the artifact still must be checked for non-placeholder closeout evidence before the milestone is reported complete.

Reconciliation To Follow-Up Planning

Workflow-guide prompt form:

Prompt: .day-shift/prompts/user/reconciliation.next.md
Reconciliation artifact: [Relative Path To Reconciliation Artifact]

Review the reconciliation artifact and report follow-up tasks, backlog candidates, planning updates, validation actions, and items that still need user decisions. Do not create follow-up artifacts in this pass.

Custom prompt to use:

Use `.day-shift/prompts/user/reconciliation.next.md`.

Reconciliation: <path-to-reconciliation>

Identify any follow-up planning candidates from the completed reconciliation. Report proposed follow-up work only; do not create new artifacts unless explicitly requested.

Command the prompt may tell the agent to use:

<day-shift-cli> planning next-action --artifact <path-to-reconciliation-or-parent-overview>

Why: reconciliation follow-up is read-only by default. planning next-action can suggest the next valid planning or review step from the artifact state, but it does not create follow-up tasks by itself.

Review Back Up To The Specification

After milestone reconciliation, use the review prompts from .day-shift/workflows/workflow-guide.md to check whether each parent artifact was actually satisfied. Use the matching recertify prompts when the question is whether an existing artifact is stale, superseded, duplicated, completed, or no longer active input before relying on it again. These prompts are read-only surfaces; use separate update commands only when the review or recertification result makes a metadata or artifact change explicit.

Workflow-guide prompt forms:

Prompt: .day-shift/prompts/user/milestone.review.md
Milestone overview: [Relative Path To Milestone Overview]

Review against downstream evidence.

Prompt: .day-shift/prompts/user/milestone.recertify.md
Milestone overview: [Relative Path To Milestone Overview]

Recertify against current downstream task, implementation, and reconciliation evidence before additional task planning.

Prompt: .day-shift/prompts/user/phase.review.md
Phase overview: [Relative Path To Phase Overview]

Review against downstream evidence.

Prompt: .day-shift/prompts/user/phase.recertify.md
Phase overview: [Relative Path To Phase Overview]

Recertify against current milestone, task, implementation, and reconciliation evidence before additional milestone planning.

Prompt: .day-shift/prompts/user/slice.review.md
Slice overview: [Relative Path To Slice Overview]

Review against downstream evidence.

Prompt: .day-shift/prompts/user/slice.recertify.md
Slice overview: [Relative Path To Slice Overview]

Recertify against current upstream spec and downstream planning evidence before additional phase planning.

Prompt: .day-shift/prompts/user/specification.review.md
Spec source: [Relative Path To Spec File Or Spec Directory]
Slice overview: [Relative Path To Slice Overview]

Review against downstream evidence.

Prompt: .day-shift/prompts/user/specification.recertify.md
Spec source: [Relative Path To Spec File Or Spec Directory]
Spec index: .day-shift/specs/index.json

Recertify against current implementation, workflow direction, and downstream planning evidence before planning from this spec again.

Command the prompts may tell the agent to use:

<day-shift-cli> milestone review --milestone-overview <path-to-milestone-overview>
<day-shift-cli> phase review --phase-overview <path-to-phase-overview>
<day-shift-cli> validation smoke --scope planning --artifact <path-to-slice-overview>

Why: the review prompts own the judgment about whether the completed work satisfies the hierarchy. The commands provide read-only evidence and closure checks without mutating parent artifacts.

Reference Links

Use these references for reusable detail:

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