Implement from task

Implement From Task

Use this workflow only after a task definition exists.

Primary audience: human operators and agents implementing one ready task. Responsibility: define the task implementation handoff and evidence procedure; route full-cycle agent orchestration to .day-shift/workflows/task.agent-lifecycle-guide.md and reusable command, validation, review, metadata, prompt/template, and structural-pressure detail to .day-shift/references/commands.md, .day-shift/references/validation-and-review.md, .day-shift/references/metadata.md, and .day-shift/references/prompts-and-templates.md.

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.

Routine agent runs should follow .day-shift/references/small-model-agent-operations.md: prefer compact JSON, one explicit task selection, agent context, and artifact/action-scoped health; recover omitted evidence deliberately and preserve freshness, preconditions, trust lanes, and typed recovery.

Inputs

Task definition
Upstream slice, phase, milestone, and spec context
.day-shift/prompts/user/task.next.md
<day-shift-cli> task readiness-review --task-definition <path>, when readiness evidence needs a low-token precheck
Repository code
.day-shift/references/small-model-agent-operations.md

Use the task definition, paired implementation summary, task-scoped repository diff, validation output, and read-only review findings as the implementation evidence trail. Do not replace those surfaces with a dashboard, aggregate status page, or prose-only completion summary.

The selected task-definition.md is the scope source of truth: it names target paths, dependencies, acceptance criteria, validation commands, constraints, and closeout expectations.
The paired implementation-summary.md in the same task directory is the durable execution evidence after implementation. It should record changed paths, acceptance results, validation performed, deviations, discovered work, follow-ups, and open questions without replacing the task definition.
Task-scoped repository changes are supporting evidence. Use targeted git diff --stat, git diff --numstat, and line-count checks when required by the task lifecycle, and record any path deviation from the task definition before closeout.
Validation output and review findings are evidence lanes. <day-shift-cli> validation links-check --scope planning --artifact <path> reports selected-artifact trace-link and hierarchy evidence, <day-shift-cli> validation smoke --scope planning --artifact <path> reports focused planning readiness and gap evidence, and <day-shift-cli> task review plus <day-shift-cli> implementation-summary review report findings over task evidence. These commands do not repair artifacts, mutate metadata, advance status, or authorize scope expansion unless a separate write-capable command or task edit explicitly does so.
Downstream readers should inspect the completed implementation-summary.md and any recorded validation or review output before milestone reconciliation. Task completion should not be reduced to a status token without the supporting evidence artifact.

Input handoff:

Required evidence before implementation: the selected task-definition.md, its paired implementation-summary.md path, upstream planning artifacts named in task metadata, target repository paths, and readiness-review output when readiness is uncertain.
Execution surface: .day-shift/prompts/user/task.next.md is the prompt handoff for task execution; .day-shift/workflows/task.agent-lifecycle-guide.md owns full agent lifecycle orchestration.
Expected output after implementation: scoped repository changes, validation results, an updated paired implementation-summary.md, and completion-oriented task-definition metadata.
Next consumer: .day-shift/workflows/04-summarize-and-reconcile.md, .day-shift/prompts/user/implementation.next.md, and <day-shift-cli> implementation-summary review --task-definition <path> consume the completed task evidence.

Starting Point

Start from the task definition you intend to implement.
Prefer repository-relative paths throughout task and implementation artifacts.
Treat <day-shift-cli> as the resolved session invocation. Use day-shift for installed/user mode after verification, and use node dist/cli/index.js in repository development mode when compiled dist output is current.
Prefer <day-shift-cli> task readiness-review --task-definition <path> before a manual readiness audit when the request is readiness-only or readiness evidence may still be incomplete.
Use .day-shift/prompts/user/task.next.md when you want the standard implementation handoff behavior.
If .day-shift/state/structural-pressure.json exists and the task touches a hotspot candidate, read it as current-state context before implementation.
If the current user request is readiness-only, use this workflow only through the readiness check and stop before changing code or updating implementation artifacts.
For example prompt wording that separates readiness review from implementation handoff, see .day-shift/workflows/workflow-guide.md.
Treat lightweight handling as an exception path only; when task evidence shows lightweight-entry conditions no longer hold, route to promotion or standard-task planning rather than continuing lightweight implementation.

Implementation Recipes

Use these patterns when applying this workflow:

Implement one specific task from its task-definition.md.
Do a readiness check first if implementation evidence may still be incomplete, preferably with <day-shift-cli> task readiness-review --task-definition <path>.
Implement the next ready task in a milestone when the user wants milestone-driven execution.
Keep changes inside declared implementation target paths unless discovered work requires a documented deviation.
Update implementation-summary.md in the same task directory as implementation progresses.
Keep <day-shift-cli> implementation-summary build and <day-shift-cli> implementation-summary review contract boundaries explicit: build refreshes the paired task-level summary at the canonical task path with template-shape preservation, while review remains read-only evidence reporting and does not auto-close task metadata.
Keep <day-shift-cli> reconciliation build and <day-shift-cli> reconciliation review contract boundaries explicit for downstream handoff: build refreshes the paired milestone reconciliation at the canonical milestone path with template-shape preservation, while review remains read-only findings that do not auto-accept or auto-transition status.
Keep adjacent command families distinct in implementation guidance: metadata and artifact-specific ... update commands are direct write surfaces, review commands remain read-only, and planning-navigation plus validation helpers, including validation links-check, remain advisory-only HAC guidance.
When implementation or guidance work needs command-surface evidence, use <day-shift-cli> commands inventory --format json before inferring command availability, write posture, selected-artifact requirements, registry-only entries, or mixed-posture family behavior; then use command help for exact flags.
Treat CLI-supported lifecycle metadata transitions as command-owned. After implementation-summary evidence is complete, use <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 instead of hand-editing task-definition front matter.
Use <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> as the read-only CLI validation surfaces when a task needs planning metadata, trace-link, or aggregate validation evidence. Preserve selected-artifact versus directory/root intent explicitly, and treat findings as evidence instead of guessing repairs.

Prompt Handoff Examples

To review a task definition for readiness and stop before implementation:

Prompt: .day-shift/prompts/user/task.review.md
Task definition: [Relative Path To Task Definition]

Review for implementation readiness. Run the Day Shift CLI readiness-review command for this task-definition path and include its result. Stop after the readiness review; do not implement yet.

To recertify a task definition before implementation:

Prompt: .day-shift/prompts/user/task.recertify.md
Task definition: [Relative Path To Task Definition]

Recertify this task against its parent milestone, sibling task evidence, current implementation behavior, paired summary evidence if present, and workflow direction. Recommend whether it should remain active, be updated, deferred, completed, superseded, or removed from active implementation input. Stop after recertification; do not implement yet.

To implement one specific task from its task definition:

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 to close the originating task definition so completed work no longer remains in a ready state.

To implement the next ready task in a milestone:

Workflow: .day-shift/workflows/03-implement-from-task.md
Prompt: .day-shift/prompts/user/task.next.md
Milestone directory: [Relative Path To Milestone Directory]

Find the next task marked ready to implement, implement it from its `task-definition.md`, update its `implementation-summary.md` with changed paths, validation results, and any discovered work, and use the supported metadata sync/update command for originating task definition metadata after completion.

To implement a task when validation cannot be fully run:

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. If any validation command cannot be run, say why, describe the residual risk, recommend the next validation command, still update `implementation-summary.md` with what was and was not verified, and use the supported metadata sync/update command for originating task definition metadata when implementation closes out.

Readiness Check

Before changing code, confirm the task definition includes:

objective
upstream references
implementation target paths
current behavior
desired behavior
acceptance criteria
validation commands
rollback or recovery notes
risks
dependencies
constraints
no implementation-blocking open questions
no dependency on a later-numbered sibling task or on a producer artifact that the current milestone has not created yet
only concrete repository-relative paths in Dependencies; prose dependency explanation, contract context, and behavioral notes belong in Upstream Context, Risks, or Assumptions
if lightweight handling is in play, the lightweight-entry boundary still holds (clear target paths, resolved dependency/sequencing blockers, low implementation risk, and low cross-artifact coordination pressure)
if promotion-path contract work is in scope, one canonical destination is explicit, content-preservation expectations are explicit, path-bearing metadata update expectations are explicit, and dry-run/no-write expectations are explicit
readiness and status metadata stay within canonical values, including ready to implement as the implementation-handoff readiness token

If evidence is missing, update the task definition or ask the user before implementation. If the task depends on a later-numbered sibling task, reorder the task sequence or mark the task blocked before implementation. If Dependencies contains prose wrappers instead of repository-relative artifact paths, move the explanation into Upstream Context, Risks, or Assumptions, or replace it with concrete dependency paths before implementation. If lightweight-entry conditions no longer hold, stop and route the work to standard-task planning or promotion before implementation. If promotion-contract evidence is underspecified, stop and update the task definition before implementation. If the user requested a readiness review only, stop here after reporting one of the following outcomes:

ready to implement
blocked, with the missing evidence listed

For readiness-only requests, do not change repository code, do not update implementation-summary.md, and do not run implementation validation unless the user explicitly asks for it. Readiness-only output may include advisory next-step recommendations (for example, implement next or reconcile later), but these recommendations must remain read-only guidance and must not mutate artifacts, statuses, or workflow policy. When the CLI readiness review surfaces the needed answer, prefer its structured findings over re-reading the same task metadata manually.

Implementation Rules

Enter this section only when the current user request explicitly asks for implementation, execution, or the standard implementation handoff after human review.
Keep changes within declared scope.
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 affected task scope, blocked validation, or created a concrete review risk.
Prefer small, traceable edits.
Record any discovered work.
Update planning artifacts if implementation reveals meaningful scope changes.
Do not claim validation passed unless it was actually run.
If implementation or review evidence shows the task should not stay in the default runtime mode, update the task-definition and paired implementation-summary metadata intentionally: use contract only for contract-only evidence work with no runtime behavior change, and hybrid only when both runtime implementation evidence and contract or handoff evidence are required for task or milestone completion.
When the task is guidance-alignment only, keep edits focused on wording and examples that reflect settled contract behavior; do not introduce new lightweight, promotion, or CLI semantics.
For metadata-update utility integration tasks, keep one canonical caller-to-helper seam in wording: caller identifies metadata family, passes direct intended-value updates, delegates mutation execution to shared helpers, and treats helper rejection as a blocking no-write outcome with no command-local fallback rewrites.
For generic metadata-update command-contract tasks, keep one canonical command contract in wording: <day-shift-cli> metadata update and <day-shift-cli> metadata validate-update share one direct intended-value input shape (--artifact <path> plus one or more --field <key>=<value> assignments), route by metadata family through shared helpers, and keep validate-update strictly read-only with no writes.
For active-artifact handoff tasks, keep one stateless guard contract in wording: update commands may accept --active-artifact <path> only as an explicit handoff check, the value must match the selected artifact argument after repository-relative normalization, mismatches are blocking no-write failures, and the flag does not create persistent context or replace required selected-artifact arguments.
For unsafe-update detection/reporting tasks, keep one canonical failure/reporting seam in wording: wrong-family, ambiguous, inconsistent, under-specified, and lossy mutation requests are blocking no-write failures; no partial-write fallback is allowed; reporting remains aligned with existing RuntimeError and finding-oriented validation surfaces; and surfaced failures are evidence of why the write stopped, not permission to continue through narrowed or guessed rewrites.
For narrow metadata-update tasks, preserve unaffected metadata fields, identity-bearing coordinates, repository-relative traceability paths, and unaffected body content unless the task explicitly authorizes a broader rewrite.
For parent-link metadata-update tasks, mutate only explicit applicable parent-link fields (upstream.slice_overview, upstream.phase_overview, upstream.milestone_overview, upstream.task_definition) in coordinated repository-relative writes; reject partial stale-link outcomes.
For status-transition metadata-update tasks, keep shared status and family-specific status fields independent, enforce artifact-family applicability for readiness, implementation_status, and reconciliation_status, and reject cross-family or unsupported-token updates rather than rewriting them into other fields.
For planning-coordinate metadata-update tasks, update planning-layer identity fields (slice, phase, milestone, task) and planning_depth only in explicit coherent transition scenarios; require coordinated updates across applicable identity-bearing fields (plus affected parent-link paths) and reject partial or contradictory coordinate rewrites.
For task-adjacent update command-contract tasks, document one explicit contract for <day-shift-cli> task update, <day-shift-cli> implementation-summary update, and <day-shift-cli> reconciliation update: keep family-specific status applicability strict, keep planning-coordinate and applicable parent-link updates coherent, reject cross-family or unsupported field requests as blocking no-write failures, and keep direct update semantics separate from promote/build/review automation.
For template-front-matter and manifest metadata-update tasks, keep template Markdown front matter and manifest JSON as separate mutation surfaces, apply direct intended-value updates to explicit in-scope keys, preserve unaffected fields and file identity (path, kind, artifact_type, and template_ref/template_refs shape where applicable), and reject invalid cross-family field application or lossy partial rewrites.
Treat broad rewrites or lossy normalization as out of scope for narrow-update tasks unless the task definition explicitly includes them.
Use existing preservation-oriented seams and tests as alignment references when documenting this behavior (preserveArchiveTraceabilityFields, buildNonDestructiveUpdatedDocument, tests/lib/spec-registry/archive.test.js, and tests/lib/spec-registry/add-safety.test.js).

Hotspot-Safe Refactor Checks

When the task touches a structural hotspot, splits a large file, or changes local-versus-shared helper boundaries, apply these checks during implementation and record the results in implementation-summary.md.

Required Checks

behavior: touched command or runtime behavior remains unchanged for intended success and failure paths
contract: exported module surfaces and caller-visible contracts remain stable unless a planned contract change is explicitly in scope
validation-semantics: validation meanings, finding codes, severities, and failure semantics remain stable for touched checks
user-facing-output: CLI output shape and message semantics remain stable unless intentionally planned elsewhere
scope-control: the task stayed inside declared seams and did not absorb opportunistic cleanup from unrelated families
shared-helper-guardrail: helper extraction stayed local-first unless a reused shared contract was already justified

How To Use Them

Use the full set whenever the task is primarily a refactor or file-boundary change.
Use the relevant subset when the task is product-facing but also restructures a hotspot file.
If any check fails, either repair the drift before closing the task or record the deviation and route it into explicit follow-up planning.
Do not treat lower line count alone as success; the module boundary should read more clearly after the change.

Dedupe And Transition-Only Reporting

When the same slice touches the same file multiple times, keep task-level structural reporting focused on deltas rather than repeating the full file history.

Task-Level Rule

In implementation-summary.md, report a touched hotspot file only when at least one of the following is true:

the task introduces a new structural concern
the task materially reduces structural pressure
the task intentionally leaves a residual boundary or size concern in place
the task changes the file’s residual classification or follow-up posture

If the task touches the file again without materially changing its structural status, reference the existing context briefly instead of restating the full rationale.

Preferred Task Language

Describe what changed in this task.
Avoid repeating the full hotspot history already captured by earlier tasks or milestone review artifacts.
If the file remains structurally unchanged from the prior task’s classification, say so in one short note rather than reopening the full analysis.

`structural-pressure.json` Read / Write Rules

Use .day-shift/state/structural-pressure.json as read-only context during task implementation.

Read It When

the task definition or upstream artifacts indicate a touched hotspot file
the task is expected to change a file’s structural-pressure classification
the task is revisiting a previously deferred or follow-up-candidate file

Do Not Write It During Task Implementation

Do not update the JSON file during ordinary task implementation.
Do not write one entry per touched file event.
Record task-local deltas in implementation-summary.md instead.
Leave any current-state update for milestone reconciliation, after dedupe and classification are settled.

Implementation Handoff

Use the existing task-definition.md as the source of scope, implementation target paths, validation commands, and acceptance criteria.
Infer the task directory from the selected task-definition.md path and update the existing paired implementation-summary.md there.
Canonical paired path for standard task execution evidence is .day-shift/planning/<implementation-order>-<slice-slug>/phases/<phase-slug>/milestones/<milestone-slug>/tasks/<task-slug>/implementation-summary.md.
Canonical paired path for lightweight task execution evidence is .day-shift/planning/<implementation-order>-<slice-slug>/tasks/<task-slug>/implementation-summary.md.
Do not introduce alternate handoff destinations for either path shape.
Handoff input: a ready task definition with concrete target paths, validation commands, dependencies, constraints, and no implementation-blocking open questions.
Handoff action: implement only the declared task scope, run the task-declared validation or recorded substitutes, and refresh the paired summary with <day-shift-cli> implementation-summary build --task-definition <path> when command-supported.
Handoff output: the changed repository paths plus a non-placeholder implementation summary that records changed paths, validation, acceptance results, deviations, risks, follow-ups, and open questions.
Handoff consumer: implementation-summary review consumes the paired task artifacts as read-only evidence; milestone reconciliation consumes completed non-placeholder summaries only after every declared task under the milestone reaches that state.
The <day-shift-cli> implementation-summary build contract uses the selected task-definition.md as source context and writes only to the canonical paired task-level implementation-summary destination while preserving .day-shift/templates/implementation-summary.md shape for standard tasks or .day-shift/templates/lightweight-implementation-summary.md shape for lightweight tasks.
The <day-shift-cli> implementation-summary review contract is read-only and findings-oriented over the paired task artifacts; it does not write files or auto-advance lifecycle metadata.
If the next workflow step is unclear, <day-shift-cli> workflow explain and <day-shift-cli> planning next-action may be used as read-only guidance surfaces, and <day-shift-cli> validation links-check --scope planning --artifact <path> may be used to inspect local trace-link evidence. These surfaces do not override task scope, readiness blockers, or closeout requirements.
Use <day-shift-cli> validation smoke --scope planning --artifact <task-definition-or-milestone-overview-path> only as a read-only focused validation signal for the selected artifact. With --artifact, planning inventory and gap evidence are scoped to that artifact; without it, repository-wide output may include unrelated historical warnings.
After implementation and validation, close task-definition lifecycle metadata with the supported CLI sync/update command when available. Use direct edits for task-definition body evidence or discovered follow-up notes only when the CLI does not own that body content.
Phased closeout is acceptable during execution (summary remains pending while work is active), but final closeout should leave implementation-summary completion evidence and completion-oriented task-definition metadata aligned for the same task.
If implementation reveals any deviation from the task definition, update task-definition body evidence as needed and use the supported metadata sync/update command for completion fields before closing the handoff. Do not return a finished handoff until metadata and evidence match.
Preserve the milestone reconciliation handoff for standard tasks by keeping task-level implementation summaries accurate and review-ready. For lightweight tasks, keep the paired implementation summary review-ready as the direct closeout artifact unless the lightweight boundary fails and the work is promoted.
Completing one task does not make milestone reconciliation actionable unless every task under the milestone has a truly completed, non-placeholder implementation summary. Treat missing or incomplete milestone reconciliation before that all-complete gate as expected downstream state rather than current-task fix work.
The downstream <day-shift-cli> reconciliation build contract uses milestone-level review inputs and writes only to the canonical milestone reconciliation.md destination while preserving .day-shift/templates/milestone-reconciliation.md shape.
The downstream <day-shift-cli> reconciliation review contract remains a read-only evaluation surface that reports evidence gaps and recommendations without auto-accepting milestone closure or mutating status fields.
If a legacy task-level reconciliation.md already exists, do not treat it as the default next step unless the task needs its own review boundary.
If the CLI path does not exist yet, implement directly in repository code and update planning artifacts manually as needed.
Use the CLI for readiness review, lightweight-task promotion, and CLI-supported metadata closeout transitions. Keep direct artifact editing for implementation-summary body evidence and unsupported closeout work only.
If implementation reveals meaningful discovered work, record it in the implementation summary and reflect it back into planning artifacts when appropriate.

Validation

Run the validation commands from the task definition when feasible.

For metadata validation, preserve the selected input granularity from the task definition. A selected Markdown file should validate only that file; a selected directory should recursively validate Markdown files and keep planning, prompt, unsupported, and ambiguous metadata-family findings separate.

If repository tests execute checked-in dist output, run validation in this order unless the task definition requires otherwise:

pnpm check
pnpm build
pnpm test or pnpm run test:v2 for the default V2 validation lane, pnpm run test:v2:cli when the changed scope is CLI-focused and needs sequential V2 evidence, or node --test <targeted-paths> for file-scoped validation

Do not treat pnpm test -- <targeted-paths> as file-scoped in this repository. The package test runner executes the full V2 suite.

If this order is not followed, call out the sequencing deviation in the task implementation-summary.md.

If validation cannot be run:

say why
describe residual risk
suggest the command that should be run next

Output Notes

Track these while working so the implementation summary is easy to write:

changed paths
validation commands and results
acceptance criteria results
hotspot-safe refactor check results, when applicable
deviations from the task definition
discovered work
follow-up work

Changed paths should identify what this task touched. Unrelated pre-existing dirty worktree files should stay out of the final report unless they changed the task’s scope, validation outcome, or review risk.

Output Expectations

At the end of the workflow, return or leave behind:

updated code within the declared scope
updated implementation-summary.md
task-definition completion metadata applied through the supported CLI sync/update command when available, or an explicit recorded manual exception when the command is unavailable
changed paths
validation results or a clear explanation of what was not run
acceptance-criteria status
hotspot-safe refactor check status when the task touched a structural hotspot
deviations, discovered work, and follow-up work

Output handoff:

The paired implementation-summary.md is the durable task execution evidence for downstream review.
<day-shift-cli> implementation-summary review --task-definition <path> reads that evidence and reports blockers, warnings, or metadata-hygiene follow-ups without mutating task state.
For standard tasks, .day-shift/prompts/user/implementation.next.md and milestone reconciliation consume the completed task summaries only after every task in the milestone has complete non-placeholder evidence.
For lightweight tasks, the paired implementation summary is the direct closeout artifact unless later evidence requires promotion into standard planning.

For readiness-only requests, return instead:

readiness status
missing evidence or blocking questions, if any
any task-definition updates made to reach a ready state
a statement that implementation is intentionally deferred pending explicit human approval or a later implementation prompt