---
artifact_schema_version: 1
artifact_type: workflow
workflow_id: workflows-readme
---

# Day Shift Workflows

These workflow notes help human operators choose the next Day Shift document or command. Start here when you know the kind of work you are doing but need the correct workflow path.

Primary audience: human operators. Responsibility: route people to the right workflow, expected output, and next action; route agent execution to `.day-shift/agents.md` and the layer-specific `.agent-lifecycle-guide.md` files; route reusable command, planning-layer, prompt/template, metadata, validation, review, registry, and structural-pressure detail to `.day-shift/references/`.

Agent priority order:

1. Read `.day-shift/agents.md` first for the repository-level agent contract.
2. Use the matching `.agent-lifecycle-guide.md` when executing a task, milestone, phase, or slice lifecycle.
3. Use numbered workflows `01`-`04` for operating rules; use `workflow-guide.md` only to compose human-facing prompts.
4. Use `.day-shift/references/small-model-agent-operations.md` for the compact, selected-artifact loop shared by every lifecycle.

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

## Command Placeholder

Resolve `<day-shift-cli>` to the command invocation that is valid for the current session. In installed/user mode, verify the packaged CLI with `day-shift --help` and use `day-shift`. In repository development mode, use `node dist/cli/index.js` when compiled `dist` output is current.

Installed user-facing examples should continue to render `day-shift`, not the repository development invocation. See `.day-shift/references/commands.md` for command-family boundaries and exact help discovery.

## Human Entry Paths

Use this routing table before reading a full workflow file.

| Entry path | Use when | Expected output | Next action |
| --- | --- | --- | --- |
| First-time project setup | You are creating a Day Shift workspace in a new or unplanned project. | A baseline `.day-shift/` workspace, a first source spec, and the first planning path. | Read `00-your-first-project-with-day-shift.md`, then use `<day-shift-cli> init` and the spec or planning commands named there. |
| Existing-repository adoption | You are adding or resuming Day Shift in a repository that may already contain work, docs, or a `.day-shift/` tree. | A verified workspace root, read-only inventory, source-spec decision, and migration or planning next step. | Read `00-existing-repository-with-day-shift.md`, then return to `01-start-here.md` or the selected planning workflow after discovery. |
| Planning from an active spec | A registered source spec is selected and needs slice, phase, milestone, or task artifacts. | Planning artifacts under `.day-shift/planning/` with explicit traceability and declared next children. | Use `02-plan-from-spec.md` and the relevant `slice new`, `phase new`, `milestone new`, or `task new` command. |
| Task implementation | A task definition exists and is ready to implement. | Scoped repository changes plus a completed paired `implementation-summary.md`. | Use `03-implement-from-task.md`; agents should use `.day-shift/workflows/task.agent-lifecycle-guide.md` for the full task lifecycle. |
| Reconciliation follow-up | Task implementation summaries are completed and the milestone needs review. | A milestone `reconciliation.md` that reviews acceptance criteria, validation, discovered work, and follow-up. | Use `04-summarize-and-reconcile.md`; agents coordinating a whole milestone should use `.day-shift/workflows/milestone.agent-lifecycle-guide.md`. |

If you do not know which row applies, read `01-start-here.md` and run read-only navigation commands such as `<day-shift-cli> planning inventory`, `<day-shift-cli> planning gap-report`, `<day-shift-cli> workflow explain`, or `<day-shift-cli> planning next-action`.

## Workflow Files

Use these files as operating guidance, not as generated planning artifacts:

- `00-your-first-project-with-day-shift.md`: first-time onboarding walkthrough with a sample root spec and end-to-end CLI flow.
- `00-existing-repository-with-day-shift.md`: existing-repository adoption and resume workflow for workspace-root detection, read-only discovery, source-spec decisions, validation, and migration preview boundaries.
- `01-start-here.md`: session startup, CLI resolution, workspace-root discovery, read-only navigation, and collaboration boundaries.
- `02-plan-from-spec.md`: turning registered specs into slice, phase, milestone, and task artifacts.
- `03-implement-from-task.md`: implementing from a ready task definition and preparing task evidence.
- `04-summarize-and-reconcile.md`: recording task summaries after implementation and reconciling the milestone after all task summaries are complete.
- `lightweight-workflow-guide.md`: hard boundary for when lightweight planning is allowed and when work must use or promote to standard planning.
- `version-management-guide.md`: installing, selecting, pinning, diagnosing, uninstalling, and syncing local Day Shift CLI versions.
- `agent-workflow-guide.md`: compatibility entry point that routes agents to the layer-specific lifecycle guides.
- `task.agent-lifecycle-guide.md`: agent full-cycle task execution from startup through handoff.
- `milestone.agent-lifecycle-guide.md`: agent full-cycle milestone coordination from task scaffolding through reconciliation.
- `phase.agent-lifecycle-guide.md`: agent phase coordination.
- `slice.agent-lifecycle-guide.md`: agent slice coordination.
- `workflow-guide.md`: prompt patterns, review guidance, and practical conventions for working through the workflow.

## Reference Homes

Reference homes for reusable responsibilities:

- `.day-shift/references/commands.md`: command families, write boundaries, read-only review and validation, and help discovery.
- `.day-shift/references/planning-layers.md`: producers, consumers, dependencies, expected outputs, and evidence handoffs for each planning layer.
- `.day-shift/references/prompts-and-templates.md`: prompt and template responsibilities without copying prompt instructions into human workflows.
- `.day-shift/references/metadata.md`: metadata families, status fields, parent links, and mutation boundaries.
- `.day-shift/references/validation-and-review.md`: validation, review, implementation-summary, reconciliation, and structural-pressure policy.
- `.day-shift/references/spec-registry.md`: source-spec registry behavior and linked planning metadata.
- `.day-shift/references/small-model-agent-operations.md`: bounded output, selection, scoped context and health, executable recovery, freshness, trust, constrained profiles, and evaluation guidance.

Trace-link lifecycle note: disposition CRUD and migrated-link apply are explicit write-capable command surfaces. `validation links-check`, validation smoke, planning navigation, review commands, and `link disposition preview` may report lifecycle evidence and recommend preview/apply follow-up, but they do not repair links, infer migrated targets, rewrite unsupported body references, or mutate disposition storage.

## Emergent Work

Emergent work uses the same planning flow after intake, but it should be captured and named distinctly:

- capture repo-local emergent specs under `.day-shift/specs/00-emergent/` when the issue is being recorded in this workspace
- use `00-emergent-<slug>` for emergent planning slice directories unless the user chooses a different explicit convention
- keep emergent origin separate from planning depth, discovered work, backlog work, and scope creep

## Default Flow

For normal planning and implementation work:

1. Read `01-start-here.md`.
2. Resolve `<day-shift-cli>` and the effective workspace root.
3. Use `<day-shift-cli> spec list` or `<day-shift-cli> spec search <query>` to select a spec before reading `.day-shift/specs/index.json` directly.
4. Use `02-plan-from-spec.md` and the available planning scaffold commands to create or complete planning artifacts.
5. Use `03-implement-from-task.md` only after a task is ready.
6. Use `04-summarize-and-reconcile.md` after implementation summaries are complete.

Implementation invariant: when work starts from an existing `task-definition.md`, treat that file as the source of truth for the active task directory, update the existing paired `implementation-summary.md` in that same directory, and prefer the repository tree over conflicting chat summaries before creating any new planning artifact.

Agent handoff: when asking an agent to execute a task, milestone, phase, or slice lifecycle, point it at `.day-shift/agents.md` plus the matching `.agent-lifecycle-guide.md` file. Human workflow files orient the session but do not replace agent lifecycle guides.

## Prompt References In Chat

When asking an agent to continue the workflow in chat:

- Reference the relevant workflow file when you want the collaboration pattern to stay explicit.
- Prefer `<day-shift-cli> ...` for deterministic discovery, scaffolding, trace-link validation, promotion, readiness review, config, and workspace-health operations before asking the agent to inspect raw planning files.
- Reference the matching prompt path when you want to force a specific build, next, review, or recertify behavior.
- Reference the matching template path when the agent is expected to create or update an artifact.
- Use `.day-shift/workflows/workflow-guide.md` for examples of concise prompt references in natural language.
