# Prompts And Templates Reference

This reference is the compact responsibility map for prompt and template surfaces. It is documentation-only and does not change prompt rendering, template schema, scaffold destinations, or manifest behavior.

## Prompt Family Identity

Prompt identity lives in `.day-shift/prompts/user/manifest.json` and prompt Markdown front matter.

Prompt manifest entries preserve:

- `path`: the identity-bearing prompt source path.
- `version`: the source-version record for that prompt path.
- `layer`: the canonical workflow layer for the prompt.
- `action`: the canonical action for that layer.
- `template_ref` or `template_refs`: source-template and output-shape references when the prompt produces or updates artifacts.

Prompt Markdown front matter preserves the prompt-family fields `prompt_version`, `layer`, and `action`. These fields are prompt-family metadata only; they are not planning-artifact status fields, template manifest routing fields, or command-family mutation instructions.

Canonical prompt actions are `build`, `next`, `review`, and `recertify`. `recertify` is the read-only lifecycle-hygiene action: it compares the selected artifact against current upstream intent, downstream evidence, workflow direction, repository behavior, metadata, and traceability before recommending whether active scope should stay current, update, collapse, split, defer, close, supersede, or leave active input.

Use prompt files for reusable agent-facing instructions. Do not treat prompt files as human workflow procedures, artifact templates, template schema owners, or scaffold routing owners.

## Prompt Rendered Instruction Boundary

Prompt-facing output that includes generated context should preserve separate visible lanes in this order:

- generated context
- agent entrypoint guidance
- warnings
- prompt instructions

`.day-shift/agents.md` remains the agent-entrypoint source when prompt rendering includes agent guidance. A missing required agent entrypoint is prompt-rendering evidence, not permission to merge warnings into instructions or silently downgrade the rendered prompt.

## Prompt Template Relationship

Prompt `template_ref` and `template_refs` metadata identify source templates and output-shape relationships. They tell a human, agent, or render surface which template shape is relevant to a prompt-driven artifact.

Prompt template references do not:

- inline template bodies automatically
- define packaged-default template membership
- authorize prompt-family writes into template manifests
- authorize template-family writes into prompt manifests
- infer scaffold destinations
- install or overwrite files outside the artifact path selected by the workflow or command

When a prompt entry includes `template_refs`, that array is the authoritative source-template list for that prompt entry. Do not normalize it into a single template reference, template manifest route, or scaffold destination.

## Template Family Identity

Template identity lives in `.day-shift/templates/manifest.json` and template Markdown front matter.

Template manifest entries preserve:

- `path`: the identity-bearing template or support asset source path.
- `version`: the source-version record for that entry.
- `kind`: the entry role, such as artifact or scaffold.
- `artifact_type`: the artifact or support asset type.
- `destination`: explicit installed-output routing only for scaffold/support entries whose contract allows it.
- `usage`: explanatory context when an entry needs it.

Overview template source filenames such as `.day-shift/templates/slice-overview.md`, `.day-shift/templates/phase-overview.md`, and `.day-shift/templates/milestone-overview.md` remain template identities and artifact shapes. They do not serve as manifest `destination` routing and do not imply that template inventory or read-only validation will rename supported legacy planning artifacts. New generated overview destinations are chosen by scaffold policy, while existing `overview.md` planning artifacts remain supported legacy inputs until an explicit migration workflow is selected.

Template files define artifact shape and placeholder expectations. They are not prompt instructions, human onboarding pages, workflow procedures, command references, or validation schemas.

## Artifact Shape And Cleanup

Templates provide output shape. Prompt and workflow instructions decide when an artifact is created or updated.

Generated artifacts should not retain unresolved `{{token_name}}` placeholders, template notes, parser-sensitive instructions, or scaffold prose after authoring is complete. The saved artifact should preserve the template's intended heading and metadata shape while replacing placeholder content with task-specific or layer-specific evidence.

Artifact-template membership is role-based. The packaged-default artifact-template family is limited to the planning artifact shapes recorded in the template manifest, while repository-local exceptions and support/scaffold assets remain separate roles even when their source files live under `.day-shift/templates/`.

## Scaffold And Support Routing

Scaffold or support templates may declare explicit destination routing in the template manifest. A template path alone is not permission to install or overwrite another repository path.

Destination routing belongs to template manifest entries that explicitly carry `destination` and whose role allows installed-output routing. Usage-only support assets may be present in `.day-shift/templates/` without authorizing a second write elsewhere.

Prompt `template_ref` and `template_refs` fields are not scaffold-routing inputs. Keep prompt source-template relationships separate from template manifest destination routing.

Write-capable template or manifest commands should preserve entry identity fields and unaffected entry data. Read-only prompt, template, diff, list, show, or validation surfaces may report adjacent family findings, but those findings remain evidence only and do not authorize guessed repairs or cross-family rewrites.

## Prompt And Template Command Surfaces

Use `templates list` as the read-only template inventory surface. Use `prompt init`, `prompt edit`, `prompt update`, `template materialize`, `template update`, and `manifest update` only for explicit prompt-family, template-family, or manifest writes. A prompt `template_ref` or `template_refs` value is source-template evidence; it is not permission to materialize, update, or route template outputs without the matching command or workflow step.

When prompt or template guidance needs one command, use `<day-shift-cli> commands search` followed by `commands describe`; use `commands validate` for drift/input-coverage evidence and `commands inventory` only for whole-surface audits. Do not duplicate descriptor or inventory payloads in prompt prose.

Prompt and template guidance should keep installed examples on `day-shift` while allowing `node dist/cli/index.js` only as a repository-development invocation placeholder. If no prompt/template command owns a requested body edit, record the manual exception instead of inventing prompt or template command behavior.

## Related References

- Use `.day-shift/references/validation-and-review.md` for read-only validation, review, evidence-only findings, and structural-pressure policy.
- Use `.day-shift/references/commands.md` for command-family behavior.
- Use `.day-shift/references/metadata.md` for artifact-family metadata mutation boundaries.

## Canonical Sources

- `.day-shift/prompts/user/manifest.json`
- `.day-shift/templates/manifest.json`
- `.day-shift/prompts/user/`
- `.day-shift/templates/`
- `.day-shift/workflows/02-plan-from-spec.md`
- `.day-shift/workflows/01-start-here.md`
