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.

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 add, slice new, phase new, milestone new, task new, 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

If discovery reports that the workspace is unsupported, malformed, or partially upgraded, run a migration preview first:

<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

Do not perform undocumented manual moves of .day-shift/ files as a substitute for migration preview or apply. If the preview cannot explain the required change, stop and record the blocker.

7. 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.

8. 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 Slice

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]

Create the next planning layer 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>

Create the next slice overview from this selected specification. Preserve source traceability, use the registered implementation order, and stop after the slice overview is created and validated.

Command the prompt tells the agent to use:

<day-shift-cli> slice new --spec-id <registered-spec-id>

Why: specification.next.md advances only from a selected specification into a slice overview. The CLI command creates the canonical .day-shift/planning/<order>-<slice>/slice-overview.md artifact and preserves workflow provenance before any manual refinement. Existing overview.md slice artifacts remain supported legacy inputs, not new scaffold destinations.

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