---
artifact_schema_version: 1
artifact_type: workflow
workflow_id: task-agent-lifecycle-guide
---

# Task Agent Lifecycle Guide

Use this guide when the user wants an agent to execute one task as a full cycle: start cleanly, work inside task scope, close the task with evidence, and hand off clearly.

Agent entrypoint route: read `.day-shift/agents.md` first, then use this guide for one-task execution. Human workflow files may orient the session, but this guide owns the full agent task lifecycle.

This guide is task-oriented orchestration. It complements `.day-shift/workflows/03-implement-from-task.md` by adding the full before, during, and after operating loop for agents. The selected `task-definition.md` remains the source of truth for allowed work, target paths, acceptance criteria, validation, and closeout expectations.

Use the Day Shift stack deliberately during this lifecycle:

- CLI commands are the first choice for command-supported discovery, readiness checks, review, and paired-artifact build/update behavior.
- Workflow files specify the operating rules, sequencing, and guardrails around the task.
- Prompts specify the canonical layer/action handoffs when the work requires prompt-driven authoring or review language.

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

## Purpose

Point the agent at one task definition and have it drive:

- startup and repository-state checks
- task readiness confirmation
- upstream context gathering
- scoped implementation
- validation and evidence capture
- task closeout
- milestone handoff readiness
- final reporting of completed, blocked, deferred, and discovered work

## Inputs

Require these inputs before starting:

- task definition path
- run mode: `readiness-only` or `implement`
- whether the agent may update only paired task artifacts or also perform approved task-scope code/doc edits

Prefer repository-relative paths in all artifact references and outputs.

## Canonical Surfaces

Use these surfaces intentionally rather than mixing ad hoc alternatives.

### CLI

- `<day-shift-cli> workflow explain`
- `<day-shift-cli> planning next-action`
- `<day-shift-cli> planning inventory`
- `<day-shift-cli> planning gap-report`
- `<day-shift-cli> validation links-check --scope planning --artifact <path>` when local planning trace-link evidence is needed
- `<day-shift-cli> link materialize --dry-run --artifact <path>` after task planning-artifact writes when newly resolvable body links may exist
- `<day-shift-cli> link materialize --write --artifact <path>` only after a safe matching dry-run and only when planning-artifact writes are authorized
- `<day-shift-cli> task readiness-review --task-definition <path>`
- `<day-shift-cli> task review --task-definition <path>` when read-only task evidence review is needed
- `<day-shift-cli> implementation-summary build --task-definition <path>`
- `<day-shift-cli> implementation-summary review --task-definition <path>`
- `<day-shift-cli> reconciliation build --milestone-overview <path>` when the next handoff is milestone rollup
- `<day-shift-cli> reconciliation review --milestone-overview <path>` when milestone closeout evidence needs a read-only check
- `<day-shift-cli> validation smoke --scope planning --artifact <path>` when the current task needs focused planning-validation evidence for the selected artifact
- `<day-shift-cli> validation smoke` only when the current task intentionally needs repository-wide validation-smoke context
- `<day-shift-cli> validation checkpoint --scope planning` only when the user explicitly chooses to preserve existing repo-wide planning smoke findings as a forward-only baseline
- `<day-shift-cli> metadata update ...` and `<day-shift-cli> metadata validate-update ...` only when the task explicitly includes metadata-family mutation or review work

### Workflow Files

- `.day-shift/workflows/README.md`
- `.day-shift/workflows/01-start-here.md`
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/workflows/04-summarize-and-reconcile.md`
- `.day-shift/workflows/workflow-guide.md`
- `.day-shift/workflows/02-plan-from-spec.md` only when execution reveals missing planning artifacts or the task must route back into planning

### Prompts

- `.day-shift/prompts/user/task.next.md`: canonical task-to-implementation handoff prompt
- `.day-shift/prompts/user/task.review.md`: canonical task-layer review prompt
- `.day-shift/prompts/user/task.recertify.md`: canonical task-layer lifecycle hygiene prompt
- `.day-shift/prompts/user/implementation.build.md`: canonical implementation-summary build prompt when prompt-driven authoring is required
- `.day-shift/prompts/user/implementation.next.md`: canonical implementation-to-reconciliation handoff prompt
- `.day-shift/prompts/user/implementation.review.md`: canonical implementation-summary review prompt
- `.day-shift/prompts/user/implementation.recertify.md`: canonical implementation-summary lifecycle hygiene prompt
- `.day-shift/prompts/user/reconciliation.build.md`: canonical reconciliation build prompt for downstream milestone rollup work
- `.day-shift/prompts/user/reconciliation.review.md`: canonical reconciliation review prompt
- `.day-shift/prompts/user/reconciliation.recertify.md`: canonical reconciliation lifecycle hygiene prompt
- `.day-shift/prompts/user/reconciliation.next.md`: canonical reconciliation-to-follow-up prompt

The task lifecycle should use task-layer prompts first, then implementation-layer prompts as evidence accumulates, and only then reconciliation-layer prompts for downstream handoff. Use recertify prompts when an existing task, summary, or reconciliation artifact may be stale before implementation, review, closeout, or follow-up planning; recertification remains read-only unless a separate explicit write request follows.

Mode-aware runtime evidence gate: preserve the originating `execution_mode` through task execution and implementation-summary closeout. New task scaffolds default to `execution_mode: runtime`. Switch a task to `contract` only when completion is contract-only evidence or planning work with no runtime behavior change. Switch a task to `hybrid` only when completion requires both runtime implementation evidence and contract or handoff evidence. Contract tasks can close on frozen contract evidence without runtime file changes, but must not claim runtime implementation. Runtime and hybrid tasks must keep Runtime Delta targets visible, list runtime changed paths, record executable validation evidence, and use a structured validation exception only for a blocked validation command; validation exceptions cannot substitute for missing runtime code changes.

## Starting

Start with the minimum context required to execute the selected task safely:

- the selected `task-definition.md`
- the paired `implementation-summary.md` if it already exists
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/prompts/user/task.next.md`
- upstream specs, workflows, manifests, prompts, templates, and dependency artifacts named by the task when they specify contract truth, validation semantics, or scope boundaries for the work

Read these broader surfaces only when they materially affect the current task or when startup evidence is unclear:

- `.day-shift/agents.md`
- `.day-shift/workflows/README.md`
- `.day-shift/workflows/01-start-here.md`
- `.day-shift/workflows/workflow-guide.md`
- the parent milestone overview path (`milestone-overview.md` for new canonical artifacts, or supported legacy `overview.md`)
- `.day-shift/prompts/user/task.review.md` when the request is review-heavy or readiness-first
- `.day-shift/prompts/user/task.recertify.md` when the selected task may be stale, already satisfied, duplicated by sibling work, or superseded before implementation starts
- `<day-shift-cli> workflow explain`, `planning next-action`, `planning inventory`, `planning gap-report`, or `validation links-check --scope planning --artifact <path>` when task context, trace links, or the directory shape is suspect

Use the selected task definition to establish:

- objective
- target paths
- current behavior
- desired behavior
- acceptance criteria
- validation commands
- dependencies
- constraints
- closure expectations

Before implementation, confirm the task path is the active source of truth.

- Infer the task directory from the selected `task-definition.md`.
- Use the existing paired `implementation-summary.md` in that same directory if present.
- If chat context or prior summaries disagree with the repository tree, trust the repository tree and re-resolve from the task path before editing anything.
- If the task depends on a later-numbered sibling or on a producer artifact that does not yet exist, stop and report the sequencing blocker instead of silently reordering the milestone.
- If the correct workflow or prompt pairing is unclear, use `<day-shift-cli> workflow explain` and `<day-shift-cli> planning next-action` as read-only guidance before proceeding. Use `<day-shift-cli> validation links-check --scope planning --artifact <path>` when the uncertainty is about local parent or trace links.

## Full-Cycle Algorithm

Run this loop for the selected task.

For normal `implement` runs, use this minimum command spine unless the task definition gives a stronger task-specific sequence:

1. `<day-shift-cli> task readiness-review --task-definition <path>`
2. implement scoped changes
3. run `pnpm build` when validation uses compiled `dist` artifacts or TypeScript changed; run it before any test or command that imports `dist/**`
4. run the task-declared validation commands, preserving their intent when shell quoting or source-path substitution is needed
5. `<day-shift-cli> implementation-summary build --task-definition <path>`
6. manually complete or correct the paired `implementation-summary.md` body evidence when the build command cannot supply final evidence by itself; apply task-definition lifecycle metadata with `<day-shift-cli> metadata sync-status-from-review --task-definition <path> --active-artifact <path>` or `<day-shift-cli> task update --task-definition <path> --active-artifact <path> --field readiness=completed --field status=completed` when supported
7. run metadata validation for touched Markdown task artifacts or the touched planning subtree when task artifacts changed, preserving selected-file versus directory intent; when the task definition or paired summary body changed, also run the selected artifact's `validation links-check` plus `link materialize --dry-run`, and apply `link materialize --write` when the dry-run reports `candidateCount > 0`, `previewChangedPaths` stays inside the selected artifact scope, and the current task authorizes planning-artifact writes
8. `<day-shift-cli> implementation-summary review --task-definition <path>`

If `pnpm build` is required for TypeScript or `dist` validation but fails during `check:metadata` because of unrelated historical planning findings, record the build blocker, run `pnpm exec tsc -p tsconfig.json` to refresh compiled runtime artifacts, and then run the focused validation commands that exercise the task scope.

Link validation and link materialization are task-closeout evidence when task artifacts are created or updated. Validation remains read-only evidence; `link materialize --write` is the explicit selected-artifact body-link writer and must be preceded by the matching `--dry-run`. Treat dry-run `candidateCount > 0` as the signal to run the matching `--write` command when writes are authorized; use `previewChangedPaths` to verify the selected-artifact scope because dry-run `changedPaths` remains empty by design. Do not use links-check output alone to rewrite metadata, repair hierarchy, create artifacts, or infer migrated targets.

### 1. Startup Preflight

Confirm the local session is safe to begin.

- inspect current repository state before editing, using scoped changed-path accounting rather than broad unrelated-dirty-state narration
- preserve unrelated user changes
- Treat changed paths as the task-scope accounting surface. Do not add a separate final-report note about unrelated pre-existing dirty worktree files unless they affect task scope, block validation, or create a concrete review risk.
- verify the task's implementation target paths exist or are intentionally creatable within task scope
- if a task names a generated, built, renamed, or stale implementation path but the repository has an obvious editable source equivalent for the same component, use the editable source, keep the change inside the intended implementation seam, and record the path substitution as a deviation in `implementation-summary.md`
- verify the task does not require missing planning artifacts before implementation can proceed
- verify `Dependencies` contains only concrete repository-relative paths; prose wrappers such as "Existing behavior in `path`" belong in `Upstream Context`, `Risks`, or `Assumptions` because readiness review treats dependency bullets as artifact references
- if the request is command-supported and the CLI provides a read-only readiness check, prefer that first
- use `<day-shift-cli> planning inventory`, `planning gap-report`, or `validation links-check --scope planning --artifact <path>` when task context, trace links, or the directory shape is suspect
- if missing planning structure is the real blocker, route back to `.day-shift/workflows/02-plan-from-spec.md` instead of improvising task-local replacements
- when metadata or planning validation is in scope, use the CLI validation surfaces with the narrowest meaningful target: `<day-shift-cli> validation smoke --scope planning --artifact <path>`, `<day-shift-cli> validation links-check --scope planning --artifact <path>`, and `<day-shift-cli> validation rollup --scope planning --artifact <path>` for selected artifacts; use `.day-shift/references/validation-and-review.md` for broader no-write and findings semantics.
- when no suitable command owns a needed task-scope edit, record the manual exception as `unsupported by CLI`, `CLI failed`, or `manual recovery after scaffold verification` before relying on direct artifact edits.

If startup evidence is contradictory or incomplete, stop before editing.

### 2. Check Readiness

Confirm the task definition includes or establishes:

- objective
- upstream references
- implementation target paths
- current behavior
- desired behavior
- acceptance criteria
- validation commands
- rollback or recovery notes
- risks
- dependencies
- constraints
- assumptions
- no implementation-blocking open questions

Before treating the task as ready, also confirm:

- the upstream artifacts named by the task are present and readable when they specify behavior that implementation or validation must preserve
- the task's validation commands are concrete enough to run as written or with only path-local substitution
- the task does not rely on inferred contract rules that exist only in prior agent summaries instead of source artifacts
- the task is not blocked by later-numbered sibling work, missing producer artifacts, or unresolved planning drift
- the task's `Dependencies` section uses concrete repository-relative artifact paths only; dependency explanation, contract context, and behavioral notes belong in `Upstream Context`, `Risks`, or `Assumptions`
- prefer `<day-shift-cli> task readiness-review --task-definition <path>` as the canonical low-token readiness check before doing a longer manual audit

If the task is not ready:

- in `readiness-only` mode, stop and report `blocked` with the missing evidence
- in `implement` mode, stop before changing repository code or summaries and report the blocker

Do not update `implementation-summary.md` for readiness-only runs.
Use `.day-shift/prompts/user/task.review.md` when the readiness result needs to be expressed through the canonical task review lens rather than only as CLI findings.

### 3. Work During Execution

Enter implementation only when:

- run mode is `implement`
- the task is ready
- no unresolved blocker prevents safe execution

Implementation rules:

- keep changes within declared implementation target paths unless the task definition is updated to reflect a justified deviation
- preserve unrelated user changes
- prefer small, traceable edits
- do not invent new acceptance criteria or broaden task scope silently
- record discovered work when implementation reveals it
- preserve validation/reporting boundaries declared by the task, including separate evidence lanes or artifact-family distinctions when those boundaries are part of the contract
- treat review and validation commands as read-only unless the task explicitly authorizes a mutating command or artifact-creation step
- do not let advisory findings, adjacent evidence, or partial drift reports collapse one artifact family or reporting lane into another
- preserve execution-mode closeout semantics: contract work records frozen contract evidence, while runtime and hybrid work must preserve Runtime Delta evidence, runtime changed paths, executable validation, or a structured validation exception for the blocked validation command only

While work is in progress:

- keep the task definition open as the active contract
- use `.day-shift/prompts/user/task.next.md` as the canonical prompt surface when the implementation handoff needs reusable prompt wording
- re-check governing upstream artifacts before making alignment or closeout claims on contract-oriented tasks
- prefer task-declared validation commands over ad hoc substitute checks
- if a substitute check is necessary, record why the declared command was not the authoritative closeout command
- when a task-declared command is repo-wide and returns unrelated existing findings, record whether the command executed successfully, summarize only findings relevant to the current task, and treat unrelated findings as non-blocking unless they affect this task's validation or review risk
- when `pnpm build` is blocked by unrelated historical `check:metadata` findings but the task still needs compiled `dist` artifacts, use `pnpm exec tsc -p tsconfig.json` as the narrow compile fallback, then run focused task validation and record the substitution plus the original build blocker
- when validation smoke is needed for the current task, prefer `<day-shift-cli> validation smoke --scope planning --artifact <task-or-milestone-path>` so inventory and gap evidence stay scoped to the selected artifact; use repository-wide smoke only when broad context is intentionally in scope
- when a command can emit a large JSON payload, redirect it to a `/tmp/*.json` file before parsing or summarizing exact JSON evidence; do not rely on shell pipes for large validation-smoke payloads when parse correctness matters
- if a declared combined `node --test` command is inconclusive because individual test files mutate process cwd, environment variables, or other process-global state, rerun the affected files separately; record the combined command as inconclusive and the separated runs as the validation evidence
- when updating command-family help or regression coverage, prefer assertions for command presence, option surfaces, posture wording, and explicit no-write/write-capable boundaries; keep absence assertions only when the missing command, option, or output is the product behavior being tested
- update planning artifacts that own scope truth if implementation reveals a real scope, dependency, or contract change
- use `<day-shift-cli> metadata update ...` only when the task explicitly authorizes metadata-family writes, and use `.day-shift/references/metadata.md` for the write versus validate-update boundary
- when applying a metadata or artifact-specific update from a task handoff that names the selected artifact, include `--active-artifact <same-repository-relative-path>` so mismatched handoff context and selected command target fail before writing; omit it only when no explicit active-artifact handoff is being checked
- when a lifecycle metadata transition is CLI-supported, use the relevant update or sync command instead of hand-editing front matter; manual metadata edits require an explicit recorded exception naming the command that was unavailable, failed, or did not own the transition
- keep `<day-shift-cli> task review --task-definition <path>` available as a read-only spot check when implementation drift is suspected but closeout is premature

### 4. Capture Task Execution Evidence

For each implemented task, update the paired `implementation-summary.md` in the same task directory.

Prefer `<day-shift-cli> implementation-summary build --task-definition <path>` for standard and lightweight task paired-summary refreshes. The command preserves the standard implementation-summary template shape for standard tasks and the lightweight implementation-summary template shape for lightweight tasks. Use `.day-shift/prompts/user/implementation.build.md` when the summary needs prompt-driven drafting or recovery language that the CLI does not supply directly.

Treat `implementation-summary build` as both a write helper and a pairing/handoff check. If it reports that no write was needed because the paired summary already exists, continue with manual closeout updates unless the existing summary already contains complete changed-path, validation, acceptance, deviation, and follow-up evidence.

Record:

- summary of work performed
- changed paths
- validation performed
- validation commands not run and why they were skipped, substituted, blocked, or inconclusive
- acceptance criteria status
- deviations
- discovered work
- follow-up work

Changed paths should communicate what this task touched. If the worktree contains unrelated pre-existing changes, leave them out of the final report unless they affected this task's scope, validation, or risk; preserving them is still required.

When findings are part of the task contract, record them using the task's declared taxonomy and blocking-versus-advisory semantics instead of inventing workflow-local labels.

When a task depends on read-only validation or review behavior, record whether the closeout checks remained no-write and whether any mutating command was intentionally excluded from validation evidence.

Use `<day-shift-cli> implementation-summary review --task-definition <path>` or `.day-shift/prompts/user/implementation.review.md` when a read-only evidence pass is needed over the summary before closing the task.

When the task changes validation smoke, validation links-check, planning inventory, gap reporting, or paired-artifact status behavior, rerun the relevant artifact-scoped validation after task closeout so task-local pending-state findings are not mistaken for residual repository drift.

When capturing diff sanity evidence, prefer targeted `git diff --stat -- <paths>`, `git diff --numstat -- <paths>`, and `wc -l <paths>` over broad repository output. If any task-scoped path is untracked, record scoped `git status --short -- <paths>` and line counts for those files because ordinary `git diff` does not show untracked file contents. Use `git diff --no-index /dev/null <file>` only when content-level diff evidence for a new untracked file is needed; otherwise line counts plus scoped status are sufficient.

### 5. Close The Task

When implementation and evidence capture are complete:

- use the supported CLI sync/update command to set completed task-definition metadata to `readiness: completed` and `status: completed`; do not leave a completed task in `readiness: ready to implement`
- edit the source `task-definition.md` directly only for body evidence, closeout notes, or unsupported metadata transitions with an explicit manual exception
- make sure task-definition status and implementation-summary evidence do not disagree
- leave discovered work and follow-up work explicit rather than burying them in prose
- preserve milestone handoff by keeping the task summary review-ready for downstream reconciliation
- use `.day-shift/prompts/user/implementation.next.md` as the canonical handoff wording when the completed task is being passed into milestone reconciliation
- prefer `<day-shift-cli> reconciliation build --milestone-overview <path>` only after the task evidence is genuinely ready for downstream rollup

Do not mark the task complete unless the acceptance criteria are either met or clearly deferred with an explicit reason the user can evaluate.

If a direct metadata edit appears necessary where a CLI update or sync command exists, stop before editing and report the exact command considered, why it cannot be used, the manual exception, and the artifact fields that would change.

### 6. Hand Off After The Task

After the task is complete or blocked, report what the next workflow step should be.

- if the task completed cleanly, identify whether milestone reconciliation or the next task is now the correct step
- if the task stopped early, identify the first blocking condition and the exact artifact or decision needed to resume
- if the task surfaced discovered work outside current scope, separate it from the completed task outcome
- if the next step is milestone rollup, use `.day-shift/workflows/04-summarize-and-reconcile.md` plus `.day-shift/prompts/user/reconciliation.build.md` or `.day-shift/prompts/user/reconciliation.review.md` as appropriate
- if the next step is follow-up extraction from reconciliation evidence, use `.day-shift/prompts/user/reconciliation.next.md`

## Stop Conditions

Stop and report instead of improvising when any of these are true:

- the task is not ready
- the task depends on a later-numbered sibling task
- the implementation target paths are missing, contradictory, or too vague to execute safely
- required upstream artifacts or dependencies are absent
- the authoritative validation commands cannot be run or cannot meaningfully confirm the task's acceptance criteria
- the task definition conflicts with the observed repository structure in a way that affects scope
- implementation would require broad opportunistic cleanup outside declared task boundaries
- a requested result would require inventing missing planning structure rather than executing approved planning

When stopping, report the exact task, the blocking condition, and the next explicit artifact or decision needed to resume.

## Artifact Contract

This workflow may update only these artifact classes by default:

- repository code or docs within the task's declared implementation target paths
- the paired task `implementation-summary.md`
- the source `task-definition.md`

Derived state files under `.day-shift/state/` may be written only by explicit state, checkpoint, or sync commands named by the task or explicitly requested by the user. Do not hand-edit derived state as part of ordinary task closeout.

This workflow must not automatically:

- reorder milestone tasks silently
- mark blocked tasks as completed
- invent or rewrite acceptance criteria without updating the task definition
- absorb unrelated cleanup outside task scope
- treat advisory review output as authorization to write
- create alternate task-summary or closeout artifact destinations

When CLI, workflow, and prompt surfaces disagree, prefer them in this order:

1. the selected `task-definition.md` and its upstream contract artifacts
2. the command-specific CLI contract for the exact operation being used
3. the workflow file governing the current stage
4. the matching layer/action prompt
5. prior summaries or conversational assumptions

## Output Contract

For successful full-cycle task completion, keep the final response concise and include:

- completed status or blocked status for the selected task
- changed paths
- validations run and results
- validation commands skipped, substituted, blocked, or inconclusive
- discovered work
- follow-up work

Detailed acceptance-criteria mapping may live in the paired `implementation-summary.md`; summarize only material deviations or unmet criteria in the final response.

Do not include unrelated dirty worktree state as its own final-report note when the changed-path list already communicates the task scope. Mention unrelated dirty state only when it materially affected the task outcome, validation, or review risk.

When relevant to the task contract, also include:

- whether findings were blocking or advisory
- whether artifact-family or evidence-lane boundaries were preserved
- whether validation and review steps remained no-write
- whether the task is ready for milestone reconciliation or for the next sibling task

If the run stopped early, say so explicitly and identify the first blocker.

Name the CLI commands, workflow files, and prompts actually used whenever they materially shaped the lifecycle outcome.

## Promptable Invocation

Use this invocation shape when you want the agent to run the workflow directly:

```md
Use `.day-shift/workflows/task.agent-lifecycle-guide.md`.
Also use:
- `.day-shift/workflows/03-implement-from-task.md`
- `.day-shift/prompts/user/task.next.md`
- `.day-shift/prompts/user/implementation.next.md` when the task completes

Task: <path-to-task-definition.md>
Mode: implement
Constraints:
- stop on readiness blockers
- keep edits within declared target paths
- update the paired implementation summary and task definition closeout metadata
- report blocked or discovered work explicitly
- state the next handoff after the task
```

For review-only passes, change `Mode: implement` to `Mode: readiness-only` and keep the workflow read-only.
