Lightweight workflow guide

Lightweight Workflow Guide

Use lightweight planning only as a narrow exception for small, clear, low-risk work. Standard planning remains the default path for Day Shift implementation work.

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.

Hard Boundary

Lightweight planning is allowed only when all of these are true:

The change is implementation-sized and can be completed as one coherent unit.
Target files or command surfaces are already known.
Dependencies and sequencing are already resolved.
Implementation risk is low.
Cross-artifact coordination pressure is low.
The work does not require a phase or milestone review boundary to remain understandable.

If any condition is false, use standard planning.

Standard Planning Required

Use or promote to standard planning before implementation when any of these appear:

Scope grows beyond one implementation-sized change.
Target paths, command ownership, or contract boundaries are unclear.
The work spans several command families, specs, templates, prompts, or workflow guides in a way that needs staged review.
Dependency or sequencing questions remain unresolved.
Risk is medium or high.
The work needs milestone reconciliation or a phase-level decision record to close safely.
The user asks for phase or milestone decomposition.

Do not continue lightweight execution while waiting to see whether these conditions become manageable. Promote first, then implement.

Lightweight Shape

A lightweight slice should skip phase and milestone planning, but it should still use task-level execution artifacts.

Spec metadata may use depth: lightweight.
Slice metadata should use planning_depth: lightweight.
Create implementation-sized task directories directly under the slice when implementation work should proceed.
Use <day-shift-cli> task new --lightweight --slice-overview <path> --task-slug <slug> as the command-supported scaffold for one lightweight task.
Do not create phase, milestone, or milestone reconciliation artifacts unless the work has crossed the standard-planning boundary.
Use the lightweight task artifact pair: task-definition.md from .day-shift/templates/lightweight-task-definition.md and implementation-summary.md from .day-shift/templates/lightweight-implementation-summary.md.
Record why lightweight handling is valid in the slice or task narrative.
Record the promotion triggers that would require standard planning.

The lightweight task directory shape is:

.day-shift/planning/<implementation-order>-<slice-slug>/tasks/<task-slug>/task-definition.md
.day-shift/planning/<implementation-order>-<slice-slug>/tasks/<task-slug>/implementation-summary.md

Lightweight task artifacts should preserve the standard task lifecycle. <day-shift-cli> task new --lightweight --slice-overview <path> --task-slug <slug> scaffolds the direct slice-level task pair from the lightweight templates. Readiness review happens against task-definition.md and reports the paired implementation summary as the lightweight review boundary. <day-shift-cli> implementation-summary build --task-definition <path> refreshes the paired lightweight implementation-summary.md while preserving authored evidence, <day-shift-cli> implementation-summary review --task-definition <path> reviews closeout evidence read-only, and task metadata is updated explicitly as part of closeout. The hardline difference is template shape, parent path, and skipped review layers: lightweight task artifacts link directly to the slice overview and do not carry phase or milestone coordinates or parent links.

Validate lightweight task artifacts with selected-file metadata checks when proving parser safety:

<day-shift-cli> validation smoke --scope planning --artifact .day-shift/planning/<slice-dir>/tasks/<task-slug>/task-definition.md
<day-shift-cli> validation links-check --scope planning --artifact .day-shift/planning/<slice-dir>/tasks/<task-slug>/task-definition.md
<day-shift-cli> implementation-summary review --task-definition .day-shift/planning/<slice-dir>/tasks/<task-slug>/task-definition.md

These checks should accept planning_depth: lightweight, direct upstream.slice_overview, and the paired upstream.task_definition on implementation summaries, while rejecting phase, milestone, upstream.phase_overview, and upstream.milestone_overview on lightweight task artifacts.

Use .day-shift/workflows/task.agent-lifecycle-guide.md for lightweight task execution when an agent should run the full task cycle. Pair it with this guide and .day-shift/workflows/03-implement-from-task.md: the lifecycle guide supplies the startup, readiness, implementation, validation, evidence, and closeout loop, while this guide overrides the hierarchy-specific parts for lightweight work. Treat any lifecycle-guide milestone handoff or reconciliation step as conditional; lightweight tasks close through the paired implementation-summary.md unless the lightweight boundary fails and the work is promoted to standard planning.

Lightweight origin is separate from emergent origin. An emergent spec may be lightweight or standard depending on risk and scope.

Lightweight Task Definition Hygiene

Keep lightweight task definitions parser-friendly and easy to execute.

Use canonical lifecycle tokens. For task definitions, use readiness: needs more evidence, readiness: ready to implement, or readiness: completed; use status: draft or status: completed. For implementation summaries, use implementation_status: pending or implementation_status: completed; use status: draft or status: completed.
Put only concrete repository-relative paths in Dependencies. Avoid prose wrappers such as “Existing behavior in path” because readiness review treats dependency bullets as artifact references.
Put dependency explanation, contract context, and behavioral notes in Upstream Context, Risks, or Assumptions.
Keep Implementation Target Paths focused on files expected to be edited or created.
List read-only source-of-truth files as reference or contract inputs in the task narrative when they specify behavior but are not expected to change.
If implementation reveals that a reference input must be edited, record the reason as a deviation in the paired implementation-summary.md.

Lightweight Validation Triage

When a declared validation command fails, classify the failure before closing the task.

Task-caused failures must be fixed before lightweight closeout.
Stale test expectations may be corrected when the fixture or assertion change preserves the current command contract.
Unrelated existing failures should be recorded as residual risk and kept out of acceptance unless they affect this task’s behavior, scope, or review risk.
Contract-expanding fixes should stop lightweight execution and become follow-up planning or promotion candidates.
If a declared validation command is broad enough to expose unrelated failures, rerun the smallest affected command after the task-local fix so closeout evidence stays specific.

Lightweight Closeout Checklist

Before final lightweight handoff:

Run <day-shift-cli> implementation-summary build --task-definition <path>, then manually complete changed paths, acceptance results, validation evidence, deviations, risks, and follow-ups.
Mark task and implementation-summary metadata complete only after validation evidence is captured.
Validate both task artifacts with selected-file metadata checks.
Run <day-shift-cli> implementation-summary review --task-definition <path> as the read-only closeout review.
If TypeScript or CLI command registration changed, run pnpm build before tests or commands that import dist/**.
Confirm no phase, milestone, or reconciliation artifacts were created while the lightweight boundary held.

Post-Closeout Corrections

If a completed lightweight task needs a narrow evidence, fixture, or validation correction:

Keep the correction scoped to the completed task’s implementation surface.
Rerun the affected validation commands.
Update the paired implementation-summary.md when recorded evidence, deviations, or residual risk changes.
Update the task definition only when completion evidence or follow-up status changes.
Rerun selected-file metadata validation and <day-shift-cli> implementation-summary review --task-definition <path>.
Do not create reconciliation or phase-level artifacts unless the correction shows the lightweight boundary failed.

Allowed Work

Lightweight is appropriate for focused fixes such as:

aligning one documented path convention
correcting one registry or metadata validation rule
updating a small set of closely related guidance files
making a bounded command behavior correction with direct tests

Lightweight is not appropriate for broad workflow redesign, multi-phase implementation, or ambiguous architectural work.

Prompt Patterns

Use these intent-first prompt patterns when you need to communicate lightweight handling in chat. Keep paths concrete, state whether the agent should stop after review, continue into implementation, or promote to standard planning, and leave command details to 02-plan-from-spec.md, 03-implement-from-task.md, and 04-summarize-and-reconcile.md.

Build A Lightweight Specification

Use when: new source material should become a lightweight specification.

Prompt: .day-shift/prompts/user/specification.build.md
Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Spec source: [Relative Path To Spec File]

Build this specification as lightweight work only if the hard boundary holds: clear target area, resolved sequencing, low risk, and low cross-artifact coordination pressure. If the work crosses that boundary, recommend standard planning instead.

Revise A Lightweight Specification

Use when: an existing lightweight or emergent spec needs updated scope before planning continues.

Prompt: .day-shift/prompts/user/specification.build.md
Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Spec source: [Relative Path To Existing Spec File]

Revise this specification in place. Preserve only still-valid lightweight scope, keep the boundary evidence explicit, and recommend standard planning if any hard-boundary condition no longer holds.

Review Lightweight Fit

Use when: the question is whether an existing spec or slice can stay lightweight.

Prompt: .day-shift/prompts/user/specification.review.md
Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Spec source: [Relative Path To Spec File]

Review whether this specification qualifies for lightweight planning. Check the hard boundary first. If lightweight still fits, identify the highest useful planning layer and promotion triggers. If it does not fit, recommend standard planning and explain which boundary condition failed.

Recertify Lightweight Scope

Use when: an existing lightweight or emergent spec may have become stale before slice planning.

Prompt: .day-shift/prompts/user/specification.recertify.md
Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Spec source: [Relative Path To Spec File Or Spec Directory]

Recertify this specification against current implementation, workflow direction, and downstream planning evidence. Preserve only still-valid lightweight scope, and recommend whether the spec should remain active, be updated, collapse with related specs, defer, become superseded, or be removed from the active spec registry.

Plan A Lightweight Slice

Use when: a lightweight spec should become the one lightweight slice overview.

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

Create the lightweight slice overview from this specification. Use the command-supported workflow from `02-plan-from-spec.md`, set `planning_depth: lightweight`, preserve upstream traceability, and stop at the slice layer. Do not create phase, milestone, reconciliation, or task artifacts unless the next request explicitly asks for them or lightweight handling fails.

Revise A Lightweight Slice

Use when: an existing lightweight slice overview needs scope or promotion-trigger updates.

Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Prompt: .day-shift/prompts/user/slice.build.md
Slice overview: [Relative Path To Lightweight Slice Overview]

Revise this lightweight slice overview in place. Keep the scope at slice depth, document why lightweight handling is valid, and record promotion triggers. If the work now needs phase or milestone decomposition, stop and recommend promotion.

Recertify A Lightweight Slice

Use when: a lightweight slice may have become stale before direct task planning or after implementation evidence changed the lightweight boundary.

Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Prompt: .day-shift/prompts/user/slice.recertify.md
Slice overview: [Relative Path To Lightweight Slice Overview]

Recertify this lightweight slice against current upstream specs, implementation evidence, workflow direction, and any downstream lightweight task evidence. Preserve only still-valid lightweight scope, identify promotion triggers that now apply, and recommend whether the slice should remain active, be updated, completed, superseded, or promoted to standard planning.

Plan A Lightweight Task

Use when: a lightweight slice should produce direct task artifacts without phase or milestone directories.

Workflow: .day-shift/workflows/02-plan-from-spec.md
Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Prompt: .day-shift/prompts/user/task.build.md
Slice overview: [Relative Path To Lightweight Slice Overview]

Create the lightweight task artifact pair directly under this slice using the command-supported workflow from `02-plan-from-spec.md`, then refine generated task content as needed. Preserve standard task lifecycle expectations and confirm metadata links directly to the slice overview without phase or milestone coordinates.

Implement A Lightweight Task

Use when: a lightweight task artifact exists and the lightweight boundary still holds.

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

Implement this lightweight task directly because the lightweight boundary still holds. Use the task lifecycle guide for startup, readiness, scoped implementation, validation, evidence capture, and closeout. Do not create milestone reconciliation or phase-level handoff artifacts unless implementation shows the lightweight boundary has failed; if it does, stop and recommend promotion.

Recertify A Lightweight Task

Use when: a lightweight task may be stale, already satisfied, duplicated, or no longer lightweight before implementation starts.

Workflow: .day-shift/workflows/task.agent-lifecycle-guide.md
Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Prompt: .day-shift/prompts/user/task.recertify.md
Task definition: [Relative Path To Lightweight Task Definition]

Recertify this lightweight task against the lightweight slice, current implementation behavior, sibling or paired summary evidence, and the lightweight boundary. Recommend whether the task should remain active, be updated, completed, superseded, removed from active implementation input, or promoted into standard planning.

Review Lightweight Completion

Use when: completed lightweight work needs read-only review.

Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Prompt: .day-shift/prompts/user/slice.review.md
Slice overview: [Relative Path To Lightweight Slice Overview]

Review the completed lightweight work against the slice acceptance criteria. Confirm validation evidence, note discovered work separately, and keep review read-only. If status or metadata should change, recommend the explicit update command rather than mutating it as part of review.

Build Or Review Lightweight Evidence

Use when: a lightweight task implementation summary needs evidence completion or closeout review.

Workflow: .day-shift/workflows/04-summarize-and-reconcile.md
Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Prompt: .day-shift/prompts/user/implementation.build.md
Task definition: [Relative Path To Lightweight Task Definition]
Implementation summary: [Relative Path To Implementation Summary]

Refresh and complete the paired lightweight implementation summary using the command-supported workflow from `04-summarize-and-reconcile.md`. Record changed paths, validation evidence, residual risks, and discovered follow-up work. Keep the summary scoped to the lightweight task and do not turn discovered work into implicit in-scope closure.

Recertify Lightweight Evidence

Use when: a lightweight implementation summary may be stale after more code, validation, or follow-up evidence changed.

Workflow: .day-shift/workflows/04-summarize-and-reconcile.md
Workflow: .day-shift/workflows/lightweight-workflow-guide.md
Prompt: .day-shift/prompts/user/implementation.recertify.md
Task definition: [Relative Path To Lightweight Task Definition]
Implementation summary: [Relative Path To Implementation Summary]

Recertify this lightweight implementation summary against current code, validation evidence, the paired task definition, and the lightweight boundary. Recommend whether the summary remains accurate, needs correction, needs revalidation, is superseded, or is closeout-ready.

Promote To Standard Planning

Use when: lightweight handling no longer fits.

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

Promote this work to standard planning. Identify which lightweight boundary condition failed, preserve existing lightweight context, and create or recommend the next standard planning layer needed for safe review. Do not continue implementation until the standard planning boundary is established.

Review And Closeout

Lightweight review still needs evidence.

Confirm the declared scope was completed.
Confirm acceptance criteria are satisfied.
Run the smallest meaningful validation commands.
Record discovered work separately from in-scope closure.
Keep write actions explicit; review output never mutates status or metadata by itself.

If review discovers standard-boundary pressure, stop lightweight closeout and promote the remaining work.