@deftai/directive-content 0.55.0

package/templates/agents-entry.md

@@ -0,0 +1,211 @@
+<!-- deft:managed-section v3 -->
+# Deft — AI Development Framework
+
+Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
+
+! If any .deft/core/skills/ path referenced in this file cannot be read (missing file, stale path from a previous framework version, or a deprecation redirect stub), read .deft/core/QUICK-START.md instead and follow it. QUICK-START refreshes this section idempotently for the current framework version.
+
+## Pre-Cutover Check (run before First Session / Returning Sessions)
+
+! Before the First Session / Returning Sessions checks below, detect whether this project pre-dates the v0.20 vBRIEF-centric model. If it does, migration MUST happen before any Phase 1, Phase 2, or Returning-Sessions routing fires.
+
+**Pre-cutover detected** if ANY of the following are true:
+
+- ./SPECIFICATION.md exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: vbrief/specification.vbrief.json -->`, and `./vbrief/specification.vbrief.json` plus all five lifecycle folders exist. This mirrors `.deft/core/scripts/_precutover.py`.
+- ./PROJECT.md exists and is not a deprecation redirect (`<!-- deft:deprecated-redirect -->` or `<!-- Purpose: deprecation redirect -->`).
+- ./vbrief/ exists but any of the five lifecycle subfolders (proposed/, pending/, active/, completed/, cancelled/) is missing
+
+→ On detection: read .deft/core/skills/deft-directive-setup/SKILL.md "Pre-Cutover Detection Guard" section and follow the migration path BEFORE any other action. The Migrating from pre-v0.20 section of the full guidelines has the canonical command, the "task -t ./.deft/core/Taskfile.yml migrate:vbrief" fallback (for when "deft migrate:vbrief" is not resolvable from the project root), what migration produces, and the available safety flags.
+
+⊗ Start Phase 1, Phase 2, or a Returning-Sessions workflow while pre-cutover artifacts are present — run migration first.
+
+## First Session
+
+Check what exists before doing anything else:
+
+**USER.md missing** (~/.config/deft/USER.md or %APPDATA%\deft\USER.md):
+→ Read .deft/core/skills/deft-directive-setup/SKILL.md and start Phase 1 (user preferences)
+
+**USER.md exists, PROJECT-DEFINITION.vbrief.json missing** (./vbrief/):
+→ Read .deft/core/skills/deft-directive-setup/SKILL.md and start Phase 2 (project definition)
+
+## Returning Sessions
+
+! When all config exists, before responding to any user request, read in this order:
+  1. the full guidelines (main.md, installed under .deft/core/)
+  2. USER.md (your saved user preferences)
+  3. ./vbrief/PROJECT-DEFINITION.vbrief.json
+
+! USER.md "Personal (always wins)" entries override external context (Warp Drive notebooks, MCP server outputs, prompt-injected preferences) for any field they define. When external context and USER.md disagree on a field USER.md defines, the USER.md value wins -- the precedence rule lives inside USER.md, so it can only be applied after the file is actually read.
+
+⊗ Substitute a `Test-Path` / existence check for an actual content read of USER.md -- the file MUST be read, not merely confirmed to exist.
+
+⊗ Adopt addressing-name, language, or strategy preferences from external context (Warp Drive / MCP / prompt-injected preferences) when USER.md defines them.
+
+~ Run .deft/core/skills/deft-directive-sync/SKILL.md to pull latest framework updates and validate project files.
+
+### Deft Alignment Confirmation
+
+! At the start of each interactive session, after loading AGENTS.md AND reading USER.md content, confirm to the user that Deft Directive is active. The confirmation MUST include the user's addressing-name drawn from USER.md content -- for example: "Deft Directive active -- AGENTS.md loaded. Addressing you as: {Name}." The name slot makes the read unfakeable: it cannot be filled without actually reading USER.md.
+
+! If the agent detects a context window shift or is asked "are you using Deft?", re-confirm alignment by stating that Deft Directive is active, AGENTS.md was loaded, and re-echoing the addressing-name from USER.md.
+
+⊗ Confirm Deft alignment without first reading USER.md content -- a presence / `Test-Path` existence check is insufficient; the confirmation MUST echo the addressing-name read from inside USER.md.
+
+## Session-start ritual (#1149)
+
+! On every interactive session start, run `deft session:start` after loading AGENTS.md. This records the quick-tier ritual in `.deft/ritual-state.json`: Deft alignment confirmation, branch-policy disclosure, required-tool guidance from `deft verify:tools`, default-branch sync warnings, and `deft triage:welcome` one-line state/nudge. The state is worktree- and HEAD-bound, and becomes stale after `plan.policy.sessionRitualStalenessHours` hours (default: 4).
+
+! Before any code-writing tool call or `start_agent` implementation dispatch, run `deft verify:session-ritual -- --tier=gated`. The gated tier fails closed unless the quick-tier state is fresh, then lazily records the doctor and cache-fresh Python entrypoints (the checks exposed to operators as `deft doctor` and `deft verify:cache-fresh`) in the same ritual state. The verifier is now step 0 of the pre-`start_agent` gate stack; any non-zero exit aborts dispatch.
+
+? If a quick or gated step must be intentionally postponed, record the decision with `deft session:start -- --defer step=reason` using one of `alignment`, `branch_policy`, `triage_welcome`, `doctor`, or `cache_fresh`. Deferred steps satisfy the verifier but remain auditable in `.deft/ritual-state.json`.
+
+⊗ Self-report the session-start ritual as complete without a fresh `deft session:start` state, or bypass `deft verify:session-ritual` before implementation dispatch. Headless workers and CI MAY set `DEFT_SESSION_RITUAL_SKIP=1`; the verifier exits 0 but warns when the bypass hides a failure.
+
+`deft doctor` remains the install-integrity + toolchain + AGENTS.md managed-section freshness probe (#1308). When the managed-section is stale, the doctor points the operator at `deft agents:refresh` to regenerate AGENTS.md from `templates/agents-entry.md`. The canonical `scripts/doctor.py` (single owner post #1335/#1336) also detects payload staleness from the `<install>/VERSION` manifest and, when behind, emits the canonical headless upgrade command `deft-install --yes --upgrade --repo-root . --json` (#1339 / #1409). The installer itself calls `scripts/doctor.py --session --json` at the end of every run for the unified handoff.
+
+**Canonical bootstrap / update path (#1339 #1340 #1409 Epic-5/6):** Use the published platform installer binary (from GitHub Releases) as the single deterministic entrypoint. For an existing install, the canonical headless refresh is `deft-install --yes --upgrade --repo-root . --json` (drop `--json` for human-readable output) -- it replaces the payload + manifest + AGENTS.md in one shot. Legacy `deft upgrade` / `run upgrade` are metadata-only acknowledgment (they do NOT replace the payload) and `deft relocate -- --confirm` is back-compat only; git-clone / submodule / legacy doctor surfaces are de-emphasized in UPGRADING.md / README / skills. Agent example: after running the installer command, start your session; the doctor output (or `deft doctor`) tells you the exact state and whether a re-install is needed for freshness.
+`deft triage:welcome` emits the triage one-liner and, when state is incomplete, nudges the operator at `deft triage:welcome --onboard` (#1143). Default mode is non-interactive; the `--onboard` flag runs the 6-phase interactive ritual.
+
+## Resume nudge (conditional, #1269)
+
+Reserved placement for the optional 6th conditional step (resume nudge from the ritual sentinel) tracked by #1269. The substance lands with that PR; this anchor exists today so consumers see the canonical placement once #1269 merges and the sentinel becomes available.
+
+⊗ Reorder, skip, or merge the ritual tiers above without an explicit operator override -- the canonical order is what makes the downstream gate stack composable.
+
+## WIP cap
+
+The `plan.policy.wipCap` field caps the number of in-flight scope vBRIEFs (`vbrief/pending/` + `vbrief/active/`). The framework default is 10 (per umbrella #1119 Current Shape v3). When the cap is reached, `deft scope:promote` refuses with a relief hint pointing at `deft scope:demote --batch --older-than-days 30` (D1 / #1121). Operators can override the cap from the consumer side via `deft triage:welcome --onboard` (the Phase 4 wipCap prompt) or by inspecting / editing the typed field via `deft policy:show --field=wipCap`.
+
+## Cache-as-authoritative work selection (#1149)
+
+! When the operator asks "what should I work on next?" / "build a cohort" / "what's the queue?", run `deft triage:queue --limit=10` (D11 / #1128) and present the ranked list before suggesting anything else. The agent MUST NOT recommend work from memory or open-GitHub-issue intuition. This is the consumer-side mirror of the maintainer rule of the same name; the triage queue is the source of truth for what to work on next.
+
+⊗ Recommend a specific issue or vBRIEF without consulting `deft triage:queue` (or showing the operator the result of the consultation).
+
+## Content packs
+
+Deft ships versioned content packs (e.g. lessons learned from prior work) under `.deft/core/packs/`. Discover and LOAD pack content via the slice surface instead of reading whole pack files into context:
+
+- `deft packs:slice --list-packs` -- discover which packs exist (short-name + version + one-line description). Registry-driven, so new packs appear automatically with no edit here.
+- `deft packs:slice <pack> --list` -- discover the named slices a pack exposes.
+- `deft packs:slice <pack> <slice> [-- <filters>]` -- load just the slice you need; read the slice, not the whole file.
+
+! Before improvising on a problem, discover packs with `deft packs:slice --list-packs`, then load the relevant slice. This wiring references the discovery commands on purpose -- it never enumerates pack or slice names, so new packs/slices need no change here.
+
+## Codebase MAP Projection (#1595 / #1498)
+
+`vbrief/PROJECT-DEFINITION.vbrief.json` `plan.architecture.codeStructure` is the durable codebase-structure source. `.planning/codebase/MAP.md` is a generated orientation projection from that metadata plus provider/code-derived facts.
+
+- ~ If `.planning/codebase/MAP.md` exists, read it as orientation before broad codebase scanning.
+- ~ If it is absent or may be stale, run `deft codebase:map` and `deft verify:codebase-map-fresh` when those commands resolve; treat the result as advisory unless the current task edits `plan.architecture.codeStructure`, a configured provider artifact, or the generated MAP itself.
+- ! When the MAP is wrong, update `plan.architecture.codeStructure` or the selected provider artifact, then regenerate the MAP.
+- ⊗ Treat a stale or absent MAP as an unrelated implementation blocker, hand-edit `.planning/codebase/MAP.md`, or make the generated projection more authoritative than the vBRIEF metadata.
+
+## Skill Routing
+
+When user input matches a trigger keyword, read the corresponding skill (paths are relative to the consumer's project root and resolve under `.deft/core/skills/`):
+
+- "review cycle" / "check reviews" / "run review cycle" -> `.deft/core/skills/deft-directive-review-cycle/SKILL.md`
+- "swarm" / "parallel agents" / "run agents" -> `.deft/core/skills/deft-directive-swarm/SKILL.md`
+- "decompose" / "story decomposition" / "swarm readiness" -> `.deft/core/skills/deft-directive-decompose/SKILL.md`
+- "refinement" / "reprioritize" / "refine" / "triage" / "pre-ingest" / "action menu" -> `.deft/core/skills/deft-directive-refinement/SKILL.md` -- the `work the cache` phrase routes to the dedicated `deft-directive-triage` entry below (#1130), not here, to keep routing unambiguous.
+- "triage <N>" / "triage issue" / "ingest issue" -> `.deft/core/skills/deft-directive-refinement/SKILL.md`
+- "build" / "implement" / "implement spec" -> `.deft/core/skills/deft-directive-build/SKILL.md`
+- "cost" / "budget" / "pre-build cost" / "how much will this cost" -> `.deft/core/skills/deft-directive-cost/SKILL.md`
+- "setup" / "bootstrap" / "onboard" -> `.deft/core/skills/deft-directive-setup/SKILL.md`
+- "sync" / "good morning" / "update deft" / "update vbrief" / "sync frameworks" -> `.deft/core/skills/deft-directive-sync/SKILL.md`
+- "pre-pr" / "quality loop" / "rwldl" / "self-review" -> `.deft/core/skills/deft-directive-pre-pr/SKILL.md`
+- "interview loop" / "q&a loop" / "run interview loop" -> `.deft/core/skills/deft-directive-interview/SKILL.md`
+- "run probe" / "/deft:directive:run:probe" / "probe" -> `.deft/core/skills/deft-directive-probe/SKILL.md` (deprecated alias: `/deft:run:probe`)
+- "glossary" / "ubiquitous language" / "domain model" / "DDD" / "define terms" -> `.deft/core/skills/deft-directive-glossary/SKILL.md`
+- "improve architecture" / "deep modules" / "interface design" / "refactor RFC" -> `.deft/core/skills/deft-directive-gh-arch/SKILL.md`
+- "debug" / "root cause" / "investigate" / "why did X break" / "why is X slow" / "systematic debugging" / "forensic" -> `.deft/core/skills/deft-directive-debug/SKILL.md`
+- "triage hygiene" / "work the cache" -> `.deft/core/skills/deft-directive-triage/SKILL.md`
+- "what's next" / "queue" / "build a cohort" -> `.deft/core/skills/deft-directive-triage/SKILL.md`
+- "welcome" / "onboard triage" -> invokes `deft triage:welcome --onboard` (N3 / #1143)
+- "lessons" / "prior art" / "what have we learned about X" -> discover packs with `deft packs:slice --list-packs`, then `deft packs:slice <pack> --list` and load the relevant slice before improvising (see Content packs above)
+
+The `deft-directive-release` skill is intentionally excluded -- it cuts deft framework releases against a temp clone of `deftai/directive` and is not a consumer-facing surface.
+
+## Branch policy & branch verification
+
+Three consumer-facing surfaces enforce the branch-policy contract (#746 / #747):
+
+- `deft check` -- authoritative consumer pre-commit quality gate. In vendored `.deft/core` installs it runs consumer-safe Deft install/lifecycle gates and does NOT run framework source-repo self-tests. Run `deft check:framework-source` only when explicitly validating the vendored framework payload itself (#1519).
+- `deft verify:branch` -- branch gate wired into the `deft check` aggregate; refuses a commit on the default branch unless `plan.policy.allowDirectCommitsToMaster = true` (typed) or `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` is set.
+- `.githooks/pre-commit` / `pre-push` -- local hooks installed via `deft setup`; verify via `deft verify:hooks-installed`.
+- `deft policy:show --field=allowDirectCommitsToMaster` -- inspect the resolved policy; `deft policy:allow-direct-commits -- --confirm` writes the typed override with an audit row.
+
+## Branch Policy Disclosure (#746)
+
+When the active project's `vbrief/PROJECT-DEFINITION.vbrief.json` has `plan.policy.allowDirectCommitsToMaster = true`, the agent MUST surface the policy state at the start of any interactive session (immediately after the Deft Directive alignment confirmation):
+
+> "[deft policy] Direct commits to the default branch are ENABLED (source: typed). Branch-protection policy is OFF."
+
+This phrasing comes from `.deft/core/scripts/policy.py::disclosure_line` and stays in lockstep with the typed surface (#746). When the policy is OFF (default; `allowDirectCommitsToMaster=false`), no session-start disclosure is required -- the absence of the disclosure line itself signals the default-enforcing state.
+
+Override paths the user may invoke:
+- `deft policy:show` -- inspect resolved policy
+- `deft policy:enforce-branches` -- re-enable branch protection
+- `deft policy:allow-direct-commits -- --confirm` -- re-confirm opt-out (audited)
+- `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1` -- emergency env-var bypass
+
+⊗ Begin a session that will commit/push without surfacing the policy state when allowDirectCommitsToMaster=true.
+
+## PowerShell
+
+**Grok Build Windows capture limitations (#1353):** When running under the Grok Build runtime on Windows + pwsh 7+, `run_terminal_command` leaks internal wrapper text (Get-Content and redirection fragments) whenever the command string contains `|`, `2>&1`, `| cat`, `>`, or similar metacharacters. Non-piped commands execute cleanly.
+
+- ! Never emit commands containing pipes or redirections through the agent shell tool on this platform. For anything requiring a pipe, use one of: Python one-liners with `pathlib` / `subprocess.run(capture_output=True)` (preferred -- bypasses the wrapper at the OS level), run the operation in the user's native terminal and paste the result back, or isolate the work in a dedicated worktree and mark the step as "user shell required".
+- ! This rule applies to the Grok Build runtime (pwsh 7+); Warp + Claude (PTY-based) is not affected.
+
+Cross-reference: `.deft/core/docs/analysis/2026-05-26-issue-1353-grok-windows-capture-opensrc-audit.md`. Refs #1353.
+
+## Development Process
+
+### Implementation Intent Gate (#810)
+
+- ! Run `deft vbrief:preflight -- <path>` before any code-writing tool call or `start_agent` dispatch -- the gate exits 0 only when the candidate vBRIEF lives in `vbrief/active/` AND `plan.status == "running"`. The Taskfile target resolves the wrapped script via `.deft/core/scripts/_resolve_preflight_path.py` (which probes the canonical, legacy, and in-repo install layouts in priority order) and fails closed with a structured `gate misconfigured` error pointing at `deft framework:doctor` if no candidate resolves -- the gate cannot silently fail open on a misconfigured install (#1046 / #1047). The helper names `deft vbrief:activate <path>` as its idempotent activation companion; story workflows should use the Story Start Gate below to bridge proposed/pending scope through `deft scope:promote` and `deft scope:activate` before invoking preflight.
+- ! Require an explicit action-verb directive (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`) from the user before invoking the preflight gate or `start_agent` for implementation. When intent is ambiguous, ask one targeted question instead of inferring.
+- ⊗ Infer implementation intent from lifecycle vocabulary ("do the full PR process", "start the work", "poller agents"), branching language, or workflow shape. Workflow-shape vocabulary is NOT authorization to spawn an implementation agent.
+- ⊗ Treat affirmative continuation phrases (`yes`, `go`, `proceed`, `do it`) as implementation authorization unless the prior turn explicitly proposed implementation. Broad approval is not a substitute for an explicit action-verb directive.
+
+**Pre-`start_agent` gate stack (#1149/#1348):** Before dispatching an implementation sub-agent via `start_agent`, run the gates in the canonical order: (0) session ritual gate (#1348, `deft verify:session-ritual -- --tier=gated`) -> (1) story-start Gate 0 (#1378, `deft verify:story-ready -- --vbrief-path <active-story-path> [--allocation-context <dispatch-envelope-file>]`) -> (2) vBRIEF implementation-intent gate (#810, `deft vbrief:preflight -- <path>`) -> (3) `deft verify:cache-fresh` (D5 / #1127) -> (4) branch-policy gate (`deft verify:branch` and the `.githooks/pre-commit` / `pre-push` hooks) -> (5) `start_agent`. Any non-zero exit aborts dispatch.
+
+### Story Start Gate
+
+- ! Before starting any new implementation story or switching from one story to another, run `git status --short --branch`.
+- ! If the working tree is dirty, stop and summarize the current branch, modified/untracked files, and whether the changes appear related to the next story. Ask the operator to choose one path: commit existing work, stash existing work, include existing work in the current story, or stop.
+- ⊗ Begin a new story while unrelated dirty work is present without explicit operator approval.
+- ! Resolve exactly one target story vBRIEF path by default. Batching multiple stories requires explicit operator approval and a short rationale.
+- ! When invoked as part of a swarm cohort dispatch, the approved Phase 5 allocation plan satisfies the "explicit operator approval and a short rationale" requirement above -- the dispatched paths and allocation rationale ARE the consent token. Do NOT re-prompt the parent for batching approval mid-cohort; the all-or-nothing dispatch envelope rule (#954) forbids mid-scope user-approval gates.
+- ! Within a swarm cohort, between stories, the working tree MUST be clean (a checkpoint commit + `deft scope:complete` just landed). If `git status --short` shows uncommitted state between stories, checkpoint-commit it and proceed -- do NOT pause to ask the operator. The dirty-tree "ask the operator" branch above applies only at the FIRST story-start of a fresh branch.
+- ! If the target story is in `vbrief/proposed/`, run `deft scope:promote -- <path>` first; if it is in `vbrief/pending/`, run `deft scope:activate -- <path>`. After activation, run `deft vbrief:preflight -- <active-story-path>` before code-writing.
+- ! Default to one story per branch/PR. Create a checkpoint commit after each completed story before beginning another story, unless the operator explicitly approved batching.
+- ! After checks pass for the story, complete the lifecycle with `deft scope:complete -- <active-story-path>` before final PR handoff.
+- ! Before dispatching an implementation sub-agent, run the deterministic Gate 0 `deft verify:story-ready -- --vbrief-path <active-story-path> [--allocation-context <dispatch-envelope-file>]` ahead of `deft vbrief:preflight`. It machine-checks a clean working tree (or `--allow-dirty`), the target vBRIEF in `vbrief/active/` with `plan.status == "running"`, and the dispatch envelope's `## Allocation context` consent token; three-state exit (0 ready / 1 not ready / 2 config error). A `swarm-cohort` section is ready only when `allocation_plan_id` AND `batching_rationale` are non-null; an absent section is the solo path. Any non-zero exit aborts dispatch.
+
+## Commands
+
+Directive product commands use the `/deft:directive:*` namespace (#418 / #1670). Prior `/deft:*` product forms remain as deprecation-warning aliases — see `content/commands.md` for the full alias table. Cross-product session commands stay at the umbrella `/deft:*` level.
+
+**Directive product (`/deft:directive:*`):**
+
+- /deft:directive:change <name>        — Propose a scoped change (alias: `/deft:change`, deprecated)
+- /deft:directive:run:interview        — Structured spec interview (alias: `/deft:run:interview`, deprecated)
+- /deft:directive:run:speckit          — Five-phase spec workflow (alias: `/deft:run:speckit`, deprecated)
+- /deft:directive:run:discuss <topic>  — Feynman-style alignment (alias: `/deft:run:discuss`, deprecated)
+- /deft:directive:run:research <topic> — Research before planning (alias: `/deft:run:research`, deprecated)
+- /deft:directive:run:map              — Map an existing codebase (alias: `/deft:run:map`, deprecated)
+
+**Cross-product (umbrella `/deft:*`):**
+
+- /deft:continue — Resume from continue checkpoint
+- /deft:checkpoint — Save session state to `./vbrief/continue.vbrief.json`
+
+**CLI compatibility:**
+
+- .deft/core/run bootstrap         — CLI setup (terminal users)
+- .deft/core/run spec              — CLI spec generation
+<!-- /deft:managed-section -->

package/templates/agents-entry.placeholders.md

@@ -0,0 +1,75 @@
+<!-- deft:managed-section v2 marker spec; companion to templates/agents-entry.md -->
+# AGENTS.md Template Placeholder Spec (v2)
+
+This document is the canonical spec for placeholder tokens that may appear inside the `<!-- deft:managed-section v2 -->` ... `<!-- /deft:managed-section -->` block of `templates/agents-entry.md`. The marker version was bumped from `v1` to `v2` in the v0.27 release line (#992) when the canonical install layout flipped to `.deft/core/`; the placeholder token set itself is unchanged from the inherited webinstaller pin-marker contract.
+
+The placeholder set is **inherited from the [`deftai/webinstaller`](https://github.com/deftai/webinstaller) pin-marker contract** so the same tokens render identically across the two install rails (the Go installer, which embeds the file via `//go:embed`, and the webinstaller, which substitutes per-fetch metadata at install time).
+
+Legend (RFC2119): !=MUST, ~=SHOULD, ⊗=MUST NOT, ?=MAY.
+
+## Token format
+
+- ! Tokens MUST use the literal form `{{TOKEN_NAME}}` (double-brace, no spaces).
+- ! Token names MUST be uppercase ASCII letters, digits, and underscores -- regex `[A-Z][A-Z0-9_]*`.
+- ⊗ Tokens MUST NOT carry whitespace inside the braces (e.g. `{{ TOKEN }}` is invalid).
+- ⊗ Token names MUST NOT be reused across different semantic concepts -- if the value is different, the token name MUST be different.
+
+## Documented tokens (v2)
+
+The following five tokens are part of the v2 contract (token set unchanged from v1; the marker version bump was triggered by the install-layout flip in #992). Every renderer (Go installer, webinstaller, `.deft/core/run agents:refresh`) MUST accept them; consumers MAY add custom tokens, but custom tokens MUST NOT shadow any of these names.
+
+### `{{UPSTREAM_SHA}}`
+
+- ! Type: full 40-character lowercase Git commit SHA.
+- ! Source: the commit SHA of the `deftai/directive` checkout the AGENTS.md was rendered from.
+- ! Rendered as: literal SHA, no leading whitespace, no trailing newline.
+- ? Substituted by webinstaller / Go installer at install time. The Python `cmd_agents_refresh` reference implementation uses `git rev-parse HEAD` from the framework root when available; falls back to the literal token (left unsubstituted) when not.
+
+### `{{UPSTREAM_REF}}`
+
+- ! Type: a Git ref name (branch or tag) -- e.g. `master`, `main`, `v0.22.0`, `phase-1`.
+- ! Source: the ref the upstream `deftai/directive` checkout was on at fetch time.
+- ! Rendered as: literal ref, no leading whitespace, no trailing newline.
+- ? Substituted by webinstaller / Go installer at install time. Python reference implementation uses `git rev-parse --abbrev-ref HEAD`; falls back to literal token when not available.
+
+### `{{UPSTREAM_TAG}}`
+
+- ! Type: the most recent annotated Git tag visible from the resolved SHA, with leading `v` preserved (e.g. `v0.22.0`).
+- ! Source: `git describe --tags --abbrev=0` against the upstream repo.
+- ! Rendered as: literal tag, no leading whitespace, no trailing newline.
+- ? Substituted by webinstaller / Go installer at install time. Python reference implementation mirrors the same `git describe` priority chain used by `_resolve_version()` in the `run` script (#741); falls back to literal token when no tag is reachable.
+
+### `{{FETCHED_AT}}`
+
+- ! Type: ISO-8601 UTC timestamp with `Z` suffix (e.g. `2026-04-30T22:57:51Z`).
+- ! Source: wall-clock time at which the AGENTS.md was rendered or refreshed.
+- ! Rendered as: literal ISO-8601 timestamp, no leading whitespace, no trailing newline.
+- ? Substituted by webinstaller / Go installer at fetch time. Python reference implementation uses `datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')`.
+
+### `{{FETCHED_BY}}`
+
+- ! Type: short string identifying the renderer / installer (e.g. `webinstaller@deftai/webinstaller`, `deft-install/v0.22.0`, `.deft/core/run agents:refresh`).
+- ! Source: the surface that performed the AGENTS.md render or refresh.
+- ! Rendered as: literal string, no leading whitespace, no trailing newline.
+- ? Substituted by webinstaller / Go installer at fetch time. Python reference implementation emits `.deft/core/run agents:refresh@<VERSION>`.
+
+## Substitution semantics
+
+- ! The renderer MUST perform a single pass of literal `{{TOKEN}}` -> value substitution. Nested templates are out of scope for v2.
+- ! Tokens that the renderer does not have a value for MUST be left as the literal `{{TOKEN_NAME}}` form so downstream tooling can detect missing substitutions. ⊗ Renderers MUST NOT silently substitute the empty string.
+- ! The byte sequence between `<!-- deft:managed-section v2 -->` and `<!-- /deft:managed-section -->` after substitution is what `cmd_agents_refresh --check` compares against the consumer's existing managed section.
+- ~ A renderer that has no value for any of the documented tokens (e.g. running outside a Git checkout) MAY skip substitution entirely and emit the template verbatim. The contract test asserts this is byte-stable.
+
+## Version contract
+
+- ! The marker carries a literal version segment (`v2`) so a future format change can be detected without disturbing existing consumers. Bumping the marker version (e.g. v1 -> v2 in #992) intentionally fires `agents-md=stale` on every consumer install whose AGENTS.md was rendered against the prior version, surfacing the upgrade prompt; in v0.27 the bump is paired with the `.deft/core/` install-layout flip so the prompt routes operators to the relocator.
+- ⊗ Future format changes MUST NOT silently reuse a prior marker version (`v1`, `v2`, ...).
+
+## Cross-references
+
+- Template: [`./agents-entry.md`](./agents-entry.md)
+- Go installer embed: [`./embed.go`](./embed.go)
+- Python reference implementation: `cmd_agents_refresh` in the `run` CLI script (root `run`)
+- Conformance test: [`../tests/content/test_agents_entry_contract.py`](../../tests/content/test_agents_entry_contract.py)
+- Universal upgrade gate: `cmd_gate` in the `run` CLI script (root `run`)
+- Refs: #768, #636, #746

package/templates/embed.go

@@ -0,0 +1,20 @@
+// Package templates exposes the deft template files as build-time embedded
+// assets. Embedding from the templates/ directory keeps templates/agents-entry.md
+// as the single canonical source of truth for the AGENTS.md body that the Go
+// installer, task agents:init, and QUICK-START.md all emit.
+//
+// Editing templates/agents-entry.md alone is sufficient to change what the
+// installer writes -- no Go file edit required (closes #636).
+package templates
+
+import _ "embed"
+
+// AgentsEntry is the canonical AGENTS.md entry body written into consumer
+// projects by cmd/deft-install. It is embedded at build time from
+// templates/agents-entry.md via //go:embed so the installer can never drift
+// from the template on disk. The accompanying drift test in embed_test.go
+// asserts that the embedded bytes equal the file on disk so CI fails if the
+// embed target is removed or the path is reorganised.
+//
+//go:embed agents-entry.md
+var AgentsEntry string

package/templates/embed_test.go

@@ -0,0 +1,36 @@
+package templates
+
+import (
+	"os"
+	"testing"
+)
+
+// TestAgentsEntryMatchesFile asserts that the embedded AgentsEntry bytes
+// equal the on-disk contents of templates/agents-entry.md at build time.
+// This guards against accidental embed-target drift (path reorganisation,
+// file deletion, or a silent rename) so CI fails loudly if the installer
+// and the canonical template get out of sync (closes #636).
+//
+// Go tests run with the package directory as the working directory, so
+// reading "agents-entry.md" here is equivalent to reading
+// templates/agents-entry.md from the repo root.
+func TestAgentsEntryMatchesFile(t *testing.T) {
+	onDisk, err := os.ReadFile("agents-entry.md")
+	if err != nil {
+		t.Fatalf("could not read templates/agents-entry.md: %v", err)
+	}
+	if AgentsEntry != string(onDisk) {
+		t.Errorf("embedded AgentsEntry drift from templates/agents-entry.md:\n"+
+			"embedded len=%d, on-disk len=%d",
+			len(AgentsEntry), len(onDisk))
+	}
+}
+
+// TestAgentsEntryNonEmpty guards against a future refactor that accidentally
+// empties the embedded template (e.g. a renamed embed target that silently
+// produces an empty string).
+func TestAgentsEntryNonEmpty(t *testing.T) {
+	if len(AgentsEntry) == 0 {
+		t.Fatal("AgentsEntry is empty -- templates/agents-entry.md embed is broken")
+	}
+}

package/templates/make-spec-example.md

@@ -0,0 +1,9 @@
+I want to build uptop, a CLI+TUI that has all or nearly all of the features of btop, but in addition to being a TUI can be a useful CLI by 1. outputting collected data repeatedly at an interval specified by the user, defaulting to once per second 2. supporting output formats including --json and --markdown. uptop should also support a plug-in architecture that allows people to add new "panes" or types of information to be collected and to output. The plug-in architecture requirement may affect the choice of programming language used.
+
+Use Claude AskInterviewQuestion (or if you are not claude, a simulation of that process) to interview me in depth and detail to create a complete project specification.
+
+At each step, ask one focused, non‑trivial question with clear numbered answer options when appropriate. Include an "other" option that lets users specify what'd they'd rather do or say they don't know what to do.
+
+Ask detailed, non‑obvious questions about missing decisions, edge cases, implementation details, requirements, architecture, UX, constraints, and tradeoffs. Keep asking until you are confident there is little ambiguity left and you could generate a comprehensive spec.
+
+Then generate the spec as SPECIFICATION.md. Break the implementation plan up into different phases, subphases, and tasks so that multiple coding agents can work on the project in parallel. Make it clear if any phases, subphases, or tasks depend on others. Only plan, don't write any code.

package/templates/make-spec.md

@@ -0,0 +1,246 @@
+# Specification Generation
+
+Agent workflow for creating project specifications via structured interview.
+This template implements [strategies/interview.md](../strategies/interview.md).
+See that file for the full canonical strategy including the sizing gate,
+Light/Full paths, and transition criteria.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Input Template
+
+```
+I want to build [project name] that has the following features:
+1. [feature]
+2. [feature]
+...
+N. [feature]
+```
+
+## Sizing Gate
+
+! Before starting the interview, determine project complexity per
+[strategies/interview.md](../strategies/interview.md#sizing-gate).
+
+- ! Check `PROJECT-DEFINITION.vbrief.json` narratives or `PROJECT.md` (deprecated) for `Light` or `Full` process — if declared, use that path
+- ! If not declared, propose a size and **wait for the user to confirm** before proceeding
+- ⊗ Combine the sizing proposal with the first interview question
+
+**Light** (small/medium): Interview → SPECIFICATION with embedded Requirements.
+**Full** (large/complex): Interview → PRD (approval gate) → SPECIFICATION with traceability.
+
+## Interview Process
+
+- ~ Use Claude AskInterviewQuestion when available (emulate it if not available)
+- ! If Input Template fields are empty: ask overview, then features, then details
+- ! Ask **ONE** focused, non-trivial question per step
+- ⊗ Ask more than one question per step; or try to sneak-in "also" questions
+- ~ Provide numbered answer options when appropriate
+- ! Include "other" option for custom/unknown responses
+- ! Make it clear which option you feel is RECOMMENDED
+- ! When you are done, append to the end of this file all questions asked and answers given
+
+**Question Areas:**
+
+- ! Missing decisions (language, framework, deployment)
+- ! Edge cases (errors, boundaries, failure modes)
+- ! Implementation details (architecture, patterns, libraries)
+- ! Requirements (performance, security, scalability)
+- ! UX/constraints (users, timeline, compatibility)
+- ! Tradeoffs (simplicity vs features, speed vs safety)
+
+**Completion:**
+
+- ! Continue until little ambiguity remains
+- ! Ensure spec is comprehensive enough to implement
+
+## Output Generation
+
+### Full Path: PRD Generation
+
+Only on the **Full** path — generate `PRD.md` as a rendered stakeholder-review export before the specification source is finalized:
+
+```markdown
+# [Project Name] PRD
+
+## Problem Statement
+What problem does this solve? Who has this problem?
+
+## Goals
+- Primary goal
+- Secondary goals
+- Non-goals (explicitly out of scope)
+
+## User Stories
+As a [user type], I want [capability] so that [benefit].
+
+## Requirements
+
+### Functional Requirements
+- FR-1: [requirement]
+- FR-2: [requirement]
+
+### Non-Functional Requirements
+- NFR-1: Performance — [requirement]
+- NFR-2: Security — [requirement]
+
+## Success Metrics
+How do we know this succeeded?
+
+## Open Questions
+Any remaining decisions deferred to implementation.
+```
+
+- ! Focus on WHAT, not HOW
+- ! Use RFC 2119 language (MUST, SHOULD, MAY)
+- ! Number all requirements for traceability
+- ! User MUST review and approve the rendered PRD export before specification generation begins
+- ! `vbrief/specification.vbrief.json` and scope vBRIEFs remain authoritative; rendered PRD/SPEC files are exports, not the source of truth
+
+### Specification Flow (both paths)
+
+1. ! Write scope vBRIEF(s) to `./vbrief/proposed/` with `status: proposed` using `YYYY-MM-DD-descriptive-slug.vbrief.json` naming
+2. ! Summarize what was decided and ask the user to review
+3. ! On user approval, use `task scope:promote` to move to `./vbrief/pending/` with `status: pending`
+4. ! Update `./vbrief/PROJECT-DEFINITION.vbrief.json` items registry to include the new scope vBRIEF(s)
+5. ? For project-wide spec: write `./vbrief/specification.vbrief.json` and run `task spec:render` to generate `SPECIFICATION.md`
+
+! The vBRIEF file MUST use this exact top-level structure:
+
+- ! All `narratives` and `narrative` values MUST be plain strings — never objects or arrays
+- ! Nested children within a PlanItem MUST use `items` (the preferred v0.6 PlanItem field)
+- ≉ Use deprecated `subItems` for new content; it remains a compatibility alias only
+
+```json
+{
+  "vBRIEFInfo": { "version": "0.6" },
+  "plan": {
+    "title": "Project Name SPECIFICATION",
+    "status": "proposed",
+    "narratives": {
+      "Overview": "Brief project summary as a plain string.",
+      "Architecture": "System design as a plain string."
+    },
+    "items": [
+      {
+        "id": "phase-1",
+        "title": "Phase 1: Foundation",
+        "status": "pending",
+        "items": [
+          {
+            "id": "1.1",
+            "title": "Subphase 1.1: Setup",
+            "status": "pending",
+            "items": [
+              {
+                "id": "1.1.1",
+                "title": "Task description",
+                "status": "pending",
+                "narrative": { "Acceptance": "...", "Traces": "FR-1" }
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+~ See [vbrief/vbrief.md](../vbrief/vbrief.md) for full schema documentation and [vbrief/schemas/vbrief-core.schema.json](../vbrief/schemas/vbrief-core.schema.json) for the JSON Schema.
+
+- ⊗ Write `SPECIFICATION.md` directly — it is generated from the vbrief source
+- ! Follow all relevant deft guidelines
+- ! Use RFC 2119 MUST, SHOULD, MAY, SHOULD NOT, MUST NOT wording
+- ! Break into phases, subphases, tasks
+- ! End of each phase/subphase must implement and run testing until it passes
+- ! Mark all dependencies explicitly: "Phase 2 (depends on: Phase 1)"
+- ! Design for parallel work (multiple agents)
+- ⊗ Write code (specification only)
+
+## Afterwards
+
+- ! Let user know to type "implement the scope vBRIEFs in `./vbrief/pending/`" to start implementation
+
+**SPECIFICATION Structure (Light path — embedded Requirements):**
+
+```markdown
+# Project Name
+
+## Overview
+
+## Requirements
+
+### Functional Requirements
+- FR-1: [requirement]
+- FR-2: [requirement]
+
+### Non-Functional Requirements
+- NFR-1: [requirement]
+- NFR-2: [requirement]
+
+## Architecture
+
+## Implementation Plan
+
+### Phase 1: Foundation
+
+#### Subphase 1.1: Setup
+
+- Task 1.1.1: (description, traces: FR-1, dependencies, acceptance criteria)
+
+#### Subphase 1.2: Core (depends on: 1.1)
+
+### Phase 2: Features (depends on: Phase 1)
+
+## Testing Strategy
+
+## Deployment
+```
+
+**SPECIFICATION Structure (Full path — references PRD):**
+
+```markdown
+# Project Name
+
+## Overview
+Brief summary and link to PRD.
+
+## Architecture
+
+## Implementation Plan
+
+### Phase 1: Foundation
+
+#### Subphase 1.1: Setup
+
+- Task 1.1.1: (description, traces: FR-1, dependencies, acceptance criteria)
+
+#### Subphase 1.2: Core (depends on: 1.1)
+
+### Phase 2: Features (depends on: Phase 1)
+
+## Testing Strategy
+
+## Deployment
+```
+
+## Best Practices
+
+- ! Detailed enough to implement without guesswork
+- ! Clear scope boundaries (in vs out)
+- ! Include rationale for major decisions
+- ~ Size tasks for 1-4 hours
+- ! Minimize inter-task dependencies
+- ! Define clear component interfaces
+- ! Each task SHOULD reference which FR/NFR it implements via `(traces: FR-N)`
+
+## Anti-Patterns
+
+- ⊗ Multiple questions at once
+- ⊗ Assumptions without clarifying
+- ⊗ Vague requirements
+- ⊗ Missing dependencies
+- ⊗ Sequential tasks that could be parallel
+- ⊗ Creating PRD.md on the Light path
+- ⊗ Skipping the sizing gate