deft-directive-tutorial · diff

git:20261013.41f3278 to git:20261018.b35d8ff

1 added, 1 removed. Audit A to A.

---

name: deft-directive-tutorial

description: >-

Runs the Directive Tutorial inside the current session. Use after the person

first saves their Name, or when they ask to start, skip, resume, or re-run

the tutorial (Signal, Postcard, or Echo). Do NOT trigger on session:start

ceremony alone, triage:welcome, or a real product build.

---

# Directive Tutorial

The first sitting inside the session that is already running. The person picks Signal, Postcard, or Echo.

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

## When to Use

- The person first saved their Name in user preferences, or asks for the Directive Tutorial

- A later session needs to resume the tutorial

- An explicit re-run after skip or complete

Do NOT trigger on `session:start` ceremony alone, `triage:welcome`, the longer training course, or a real product build.

## Goal

The person finishes one menu option, or has a recorded skip. The agent reads each step and follows it.

## Offer

! Offer only when `deft tutorial:offer --json` prints `"offerNow": true` (status `not_started`).

! Offer after Name is first persisted. ⊗ Wait for project definition or the specification interview.

⊗ Ask the name and preference questions again.

! Skip for now runs `deft tutorial:skip` before the tutorial has started.

! An explicit `deft tutorial:start` still works after skip or complete (complete needs reset first when status is completed).

⊗ Offer again when `offerNow` is false.

## Menu

! After start, the person picks from a numbered menu: **1 Signal**, **2 Postcard**, **3 Echo**, **4 Leave**, **5 Discuss**, **6 Back**.

! Record a project pick with `deft tutorial:advance --project signal|postcard|echo` (or `1|2|3`).

! Leave runs `deft tutorial:leave` (also `--project 4` / `--project leave` on advance).

! Discuss (`--project discuss` / menu Discuss) pauses and asks what to discuss; do not advance.

! Back (`--project back` / menu Back) moves one wired step earlier; on step 1 refuse Leave or Discuss. Back refuses when status is `completed` so finished progress cannot reopen.

! Every project option uses the same seven steps. Only the toy changes.

! Practice work runs in `repoPath`, a disposable local Git repository.

! On every later step the person may still leave (`deft tutorial:leave`).

⊗ Use the person's real project as the sandbox.

⊗ `git push`. ⊗ Open a pull request.

## Each step

## Numbered choices

! Whenever the person must pick, show a numbered menu (1, 2, 3…). Accept the number or the option label.

! Include Leave on every choice menu where leaving is allowed.

! End every structured menu with **Discuss** then **Back**, in that order (`contracts/deterministic-questions.md`).

⊗ Ask for free yes/no/go prose when a numbered menu is defined on the step.

⊗ Strip Discuss/Back from the rendered `beatText` menus.

! Run `deft tutorial:inspect --json` or `deft tutorial:resume --json`.

! Say `beatText` as written.

⊗ Paraphrase it or invent a step.

⊗ Paste the JSON `command` block into what the person sees.

! When JSON `command` is non-null, run those commands in `repoPath` yourself after the person's next action.

⊗ Run promote/activate/complete (or any lifecycle commands) when `command` is null — that means start or close already ran (for example after Back).

! Record progress with `deft tutorial:advance` and the matching flags.

⊗ Move on when advance refuses.

- Step 1 choose: `--project signal|postcard|echo` (or `1|2|3`); Leave → `deft tutorial:leave`; Discuss / Back as above

- Step 2 write: first `--content "..."` (or `--project 1` / Use the example), then `--confirm` (Plan/Done; menu 1 Yes / 2 No — change the plan / 3 Leave / 4 Discuss / 5 Back), then `--work-item <path>` (may combine with confirm). After Plan/Done is accepted without a path, show the work-file prompt — do not re-ask for content.

- Step 3 start: `--confirm` (menu: 1 Yes / 2 Leave / 3 Discuss / 4 Back). Commands promote and activate the proposed work file, then create the branch. After `startLifecycleDone` (Back to start), JSON `command` is null — do not re-run them.

- Step 4 change: `--content-seen` (menu: 1 Go / 2 Leave / 3 Discuss / 4 Back)

- Step 5 prove: menu 1 Go (run check), then record `--check pass|fail` (fail stays; pass stays on Continue). Menu after pass: 1 Continue / 2 Leave / 3 Discuss / 4 Back. After fail: 1 Try again / 2 Leave / 3 Discuss / 4 Back. A combined `--project 1 --check pass` on a failed prove step records the new result.

- - Step 6 close: stamp acceptance proof then complete (`--complete`; menu: 1 Go / 2 Leave / 3 Discuss / 4 Back; only after a pass + Continue). Commands run `scope:stamp-evidence` then `scope:complete --non-delivery experiment_archived`. After `closeLifecycleDone` (Back to close), JSON `command` is null — do not re-run stamp-evidence or complete.

+ - Step 6 close: record Findings on the work file, stamp acceptance proof, then complete (`--complete`; menu: 1 Go / 2 Leave / 3 Discuss / 4 Back; only after a pass + Continue). Commands write `plan.narratives.Findings`, run `scope:stamp-evidence`, then `scope:complete --non-delivery experiment_archived`. After `closeLifecycleDone` (Back to close), JSON `command` is null — do not re-run Findings write, stamp-evidence, or complete.

- Step 7 leave: `advance` with no extra flags (only after close); otherwise `deft tutorial:leave`

## Progress

! `deft tutorial:leave` records skipped and clears the sitting; explicit start still works.

! Progress is stored in user preferences (`tutorial-state.json` next to USER.md), not in the product project.

! `deft tutorial:reset` clears progress and does not re-fire the automatic offer by itself.

! Mid-tutorial `deft tutorial:skip` moves one step and does not mark the work done.

! Completed status requires reset before another start; a fresh start does not reuse prior content, work-file path, or check results.

## Exit

! Say whether the sitting is paused, skipped, or finished, and which step is current.

⊗ Claim the work is done before step 6 has closed it.