syntaur 0.8.0 → 0.12.0

package/skills/add-resource/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: add-resource
+description: >-
+  Register a project-level resource (link to a dashboard, doc, ticket, or
+  external system) under a Syntaur project. Use when the user wants to "add a
+  resource", "save this link to the project", "track this dashboard", "add a
+  reference doc", or otherwise capture a pointer to an external system the
+  project depends on.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Add Resource
+
+Add a resource entry to a Syntaur project. Writes
+`<projectDir>/resources/<slug>.md` and regenerates `<projectDir>/resources/_index.md`
+via the CLI — the agent never edits `_index.md` directly (it is a
+CLI-managed file per the file-ownership protocol).
+
+## When NOT to use this skill
+
+- The information is **session-scoped knowledge**, not a pointer to an
+  external system — use `add-memory` instead.
+- The link is specific to a single assignment (assignment-level scratch) —
+  put it in that assignment's `scratchpad.md`.
+- The resource already exists. Read `<projectDir>/resources/_index.md` first
+  to check; pass `--force` only if you intend to overwrite.
+
+## Step 1: Resolve project
+
+If `.syntaur/context.json` is present and has `projectSlug`, default to that.
+Otherwise ask the user which project to add the resource to.
+
+## Step 2: Gather inputs
+
+Required:
+
+- `--name <human readable>` — display name for the resource.
+- `--source <url-or-path>` — the link or path to the resource itself.
+
+Optional:
+
+- `--category <name>` — short category tag (e.g. `dashboard`, `doc`,
+  `ticket`, `runbook`, `repo`).
+- `--related-assignments <slug,slug,...>` — comma-separated assignment slugs
+  this resource is relevant to.
+- `--slug <slug>` — override the auto-generated kebab-case slug.
+
+## Step 3: Run `syntaur resource add`
+
+```bash
+syntaur resource add \
+  --project <project-slug> \
+  --name "<name>" \
+  --source <url-or-path> \
+  [--category <name>] \
+  [--related-assignments <slug,slug>] \
+  [--slug <slug>] \
+  [--force]
+```
+
+The CLI:
+
+1. Validates the project exists.
+2. Writes `<projectDir>/resources/<slug>.md` with the canonical frontmatter
+   (`name`, `category`, `source`, `relatedAssignments`, `created`,
+   `updated`).
+3. Regenerates `<projectDir>/resources/_index.md` from the directory contents.
+4. Refuses to overwrite an existing resource without `--force`.
+
+## Step 4: Verify
+
+The CLI prints the slug file path and the new index size. Read both back if
+the user asked for confirmation.
+
+## Step 5: Report to User
+
+Summarize:
+
+- Resource slug and absolute path.
+- Project that received the resource.
+- Index regenerated (with the new total).
+- Suggested next step: open the dashboard or `_index.md` to see the new entry.

package/skills/capture-artifacts/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: capture-artifacts
+description: >-
+  Capture typed proof artifacts (screenshot, video, asciinema, http transcript,
+  text note) for the active Syntaur assignment so a human reviewer can verify
+  the work in seconds without re-running it. Use after a meaningful change is
+  verified, especially when an acceptance criterion is now demonstrably met.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "0.1.0"
+---
+
+# Capture Artifacts
+
+Attach proof to your work. Reviewers should be able to scroll a single page (`proof.html`) and judge "yep that's what I wanted" or "nope that's not right" — without re-executing anything.
+
+## Input
+
+No arguments. Reads `.syntaur/context.json` from the current working directory to identify the active assignment.
+
+## Step 1: Decide whether to capture
+
+Capture an artifact when **any** of these is true:
+- An acceptance criterion is now demonstrably met (most common trigger).
+- A user-facing behavior changed in a way a screenshot, video, transcript, or short text note can show.
+- A bug fix produces a before/after worth showing (capture the after; the diff is the before).
+
+Skip when:
+- The change is purely internal (refactor, type tightening) with no observable effect.
+- The change is already covered by a passing automated test that the reviewer can run trivially.
+
+Linkage to a specific criterion is **optional**. Untagged artifacts are fine — they land in a "Other artifacts" section on the proof page.
+
+## Step 2: Pick the kind by work type
+
+| Work type | Preferred kind | Notes |
+|-----------|---------------|-------|
+| Web UI change | `screenshot` (single state) or `video` (interaction) | Use the smallest medium that conveys the proof. Screenshots beat videos when one frame suffices. |
+| CLI command output | `asciinema` (preferred) or `text` | Asciinema records the actual session; text is fine when output is short and static. |
+| Backend API change | `http` (request/response transcript) | Capture the curl invocation + response body. |
+| Migration / schema / config | `text` with a `--note` describing the before/after | Or `http` for an API verification call. |
+| Anything ambiguous | `text` with `--note` | Always available. Written notes are better than skipped captures. |
+
+## Step 3: Run `syntaur capture`
+
+```bash
+# File-based (screenshot, video, asciinema, http transcript)
+syntaur capture --kind <type> --file <path> [--criterion <index>] [--note <text>] \
+  [--project <slug> <assignment-slug>]
+
+# Text-only (no --file)
+syntaur capture --kind text --note "<what you verified>" [--criterion <index>] \
+  [--project <slug> <assignment-slug>]
+```
+
+Rules:
+- `--kind=text` requires `--note` and forbids `--file`.
+- `--kind=http` accepts either `--file` (a transcript) or `--note` (an inline summary). At least one is required.
+- All other kinds (`screenshot`, `video`, `asciinema`) require `--file`. The CLI rejects nonexistent / non-file paths.
+- `--criterion <index>` is optional — pass the **0-based** index into the `## Acceptance Criteria` checklist when you want to anchor the artifact to a specific criterion.
+- If you have a `.syntaur/context.json` in the cwd, the positional target argument is unnecessary; otherwise pass `--project <slug> <assignment-slug>` or a bare assignment UUID.
+
+The CLI copies the file (if any) under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>` and inserts a row in `~/.syntaur/syntaur.db`. Output prints the artifact id and absolute path.
+
+## Step 4: Optional — refresh the proof page
+
+```bash
+syntaur proof build [--project <slug> <assignment-slug>]
+```
+
+This walks `## Acceptance Criteria` and renders `proof.html` + `proof.md` at the assignment dir, embedding tagged artifacts inline beneath their criteria and untagged/stale ones in a final "Other artifacts" section. Atomic overwrite — safe to re-run after every capture, or once at completion. The rendered page works in any browser; no desktop-app dependency.
+
+The `complete-assignment` skill mentions the proof page path in its final report so the reviewer can open it.
+
+## Step 5: Record the capture (per `keep-records-updated` playbook)
+
+The `keep-records-updated` playbook recommends running `syntaur capture` whenever the change is visually or behaviorally observable. Append a brief mention to `progress.md` if it adds context (e.g. "captured login-flow video against criterion 2"). Skipping a capture is fine — proof is opt-in for v1; there is no completion gate.
+
+## Notes
+
+- Artifacts are local-only in v1. Cloud upload is not available.
+- Stale `criterion_index` (e.g. when a criterion is later deleted or reordered) renders under "Other artifacts" with a "(was tagged criterion N — no longer present)" annotation. The artifact is not lost.
+- Storage stays out of git by default — `~/.syntaur/` is outside any tracked tree.

package/skills/complete-assignment/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 license: MIT
 metadata:
   author: prong-horn
-  version: "1.1.0"
+  version: "1.2.0"
 ---
 
 # Complete Assignment
@@ -143,4 +143,5 @@ Summarize:
 - Assignment slug and title
 - New status (review or completed)
 - Number of acceptance criteria met vs total
+- If `<assignmentDir>/proof.html` exists, include its absolute path so the reviewer can open it directly in a browser. Mention briefly which criteria have artifacts attached. (Proof is opt-in — its absence is not a blocker.)
 - If transitioned to `review`, a human reviewer will check the work. If any criteria were unmet, they may send it back to `in_progress`.

package/skills/list-assignments/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: list-assignments
+description: >-
+  List Syntaur assignments across all projects with filters by status,
+  project, tag, and age. Use when the user wants to "see all assignments",
+  "list pending work", "show in_progress assignments", "what's open",
+  "find assignments tagged X", or otherwise query the cross-project board
+  non-interactively. Different from the interactive `browse` TUI — emits
+  scriptable output (table or JSON).
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# List Assignments
+
+Cross-project assignment listing using `syntaur ls`. Supports filters by
+status, project, tag, and age. Emits a compact aligned table by default;
+`--json` produces machine-readable output suitable for piping into other
+tools.
+
+## When NOT to use this skill
+
+- The user wants to interactively browse and act on assignments — use
+  `syntaur browse` (the Ink TUI) instead.
+- The user wants details for a single assignment they already know — open
+  its `assignment.md` directly.
+- The user wants project-level rollups (totals, blocked counts) — that's the
+  dashboard, not `ls`.
+
+## Step 1: Map user prose to filters
+
+Common requests → flags:
+
+- "pending assignments" → `--status pending`
+- "in-progress" / "active" → `--status in_progress`
+- "stuff blocked" → `--status blocked`
+- "everything in <project>" → `--project <slug>`
+- "tagged with X" / "labeled X" → `--tag X`
+- "must have all of X and Y" → `--tag X,Y` (AND semantics)
+- "from this week" → `--age 7d`
+- "last 24 hours" → `--age 24h`
+- "this month" → `--age 30d` (or `1m`)
+- "as JSON" / "for piping" → `--json`
+
+Multiple filters compose (intersected).
+
+## Step 2: Run `syntaur ls`
+
+```bash
+syntaur ls [--status <list>] [--project <slug>] [--tag <list>] [--age <duration>] [--json]
+```
+
+Supported `--age` units: `h` (hours), `d` (days), `w` (weeks), `m` (~30 days).
+
+## Step 3: Present results
+
+Default output is a table with columns: PROJECT, SLUG, STATUS, PRIORITY,
+ASSIGNEE, UPDATED, TITLE. If the user asked for a count or a follow-up
+action ("which one is highest priority?"), parse the table or re-run with
+`--json` and pick programmatically.
+
+## Step 4: Report to User
+
+If interactive:
+
+- Summarize the count and any obvious patterns (e.g. "5 pending in
+  syntaur-meta, 3 blocked across other projects").
+- Suggest a next action when applicable (e.g. "want to grab the top-priority
+  pending one?").
+
+If scripted (`--json`), pass the parsed JSON downstream without re-rendering.

package/skills/log-progress/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: log-progress
+description: >-
+  Append a timestamped entry to the active assignment's `progress.md`,
+  bumping `entryCount` and `updated` in its frontmatter. Use after every
+  meaningful action — completing an acceptance criterion, finishing a plan
+  task, hitting a blocker, deciding on an approach — per the Keep Records
+  Updated playbook. Triggers on "log progress", "note progress", "record
+  this in progress", or whenever the playbook says to update records.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Log Progress
+
+Append a structured timestamped entry to the active assignment's
+`<assignmentDir>/progress.md`, and update its frontmatter. Markdown-only —
+no CLI verb. Idempotent in the sense that re-running with the same body
+produces a duplicate entry, which is intentional (timestamps differ).
+
+This skill implements the **Keep Records Updated** playbook: agents must keep
+records current in real-time, especially after every meaningful action.
+
+## When NOT to use this skill
+
+- The action belongs in `decision-record.md` (architecturally significant
+  decisions with rationale) — write to that file, not progress.md.
+- The information is for the next session of the SAME assignment — that's
+  `/save-session-summary`.
+- The information is a question for the user — write to `comments.md` via
+  `syntaur comment` (CLI-mediated).
+- The information is a follow-up assignment idea — open a new assignment
+  via `/create-assignment`.
+
+## Step 1: Verify there is an active assignment
+
+Read `.syntaur/context.json` from the current working directory. Extract
+`assignmentDir`. If missing, abort with: "No active assignment. Run
+`grab-assignment` first."
+
+## Step 2: Compose the entry
+
+The entry should be concise, factual, and link-rich. Suggested structure:
+
+```markdown
+## <ISO 8601 UTC timestamp> — <one-line summary>
+
+- What changed (action verbs).
+- Files touched: `path/to/file.ts:line`, `another.ts`.
+- Commits: `<short-sha>` (one per logical change).
+- Verification: `npm test src/...`, `node dist/index.js x --help`, etc.
+
+Optional notes paragraph.
+```
+
+Use ISO 8601 with `Z` suffix (e.g. `2026-05-08T20:13:00Z`). Use absolute
+file paths or repo-relative paths consistently.
+
+## Step 3: Read existing progress.md
+
+Read `<assignmentDir>/progress.md`. Extract:
+
+- Current `entryCount` from the frontmatter.
+- The full body (everything after the second `---`).
+
+If `progress.md` doesn't exist, abort and tell the user to re-grab the
+assignment (the file should always exist for an in-progress assignment).
+
+## Step 4: Compute new frontmatter
+
+- `entryCount`: increment by 1.
+- `updated`: set to current ISO timestamp.
+- Other fields (`assignment`, `generated`): preserve as-is.
+
+## Step 5: Write the file
+
+Write back the file with the updated frontmatter and the new entry **prepended**
+to the body (newest first), per the Keep Records Updated playbook and
+`skills/syntaur-protocol/references/protocol-summary.md`. Reverse-chronological
+order: the new `## <ISO 8601 timestamp>` heading sits immediately after the
+`# Progress` H1, with one blank line separating it from any prior entry.
+
+Layout:
+
+```markdown
+# Progress
+
+## <new ISO timestamp>
+
+<new entry body>
+
+## <prior ISO timestamp>
+
+<prior entry body>
+
+## <even-older ISO timestamp>
+
+<even-older entry body>
+```
+
+If the existing body is the placeholder text "No progress yet.", replace it
+with the new entry instead of preserving the placeholder.
+
+> **Why prepend:** the dashboard and downstream readers expect the most recent
+> entry first. Appending at the end would silently break the convention
+> documented in `~/.syntaur/playbooks/keep-records-updated.md`.
+
+## Step 6: Verify schema
+
+Confirm by re-reading the file:
+
+- Starts with `---`, then frontmatter, then `---`.
+- `entryCount` is a non-negative integer.
+- `updated` matches the timestamp you wrote.
+- The new entry's `## <timestamp>` heading is present.
+
+If the file fails schema check, restore the prior content and report the
+error — do not leave it partially written.
+
+## Step 7: Report to User
+
+Summarize:
+
+- Path of the modified `progress.md`.
+- New `entryCount`.
+- One-line summary of the entry that was logged.

package/skills/plan-assignment/SKILL.md

@@ -99,28 +99,49 @@ Body sections:
 
 If the target file already exists (only possible for `plan.md` on first re-run against a scaffolded-but-empty plan), preserve the frontmatter and replace only the body, flipping `status` from `draft` to `in_progress` and updating `updated`.
 
-### 5c. Update assignment.md Todos
+### 5c. Update assignment.md Todos (four-todo cycle)
 
-Read `<assignmentDir>/assignment.md` and locate the `## Todos` section.
+Read `<assignmentDir>/assignment.md` and locate the `## Todos` section. Per
+the **Create-and-Plan-Assignment** playbook, every plan version uses a
+four-todo cycle: Create / Review / Implement / Review implementation.
 
-1. **Supersede prior plan todos.** For every unchecked line matching `- [ ] Execute [<label>](./plan.md)` or `- [ ] Execute [<label>](./plan-v<N>.md)`, rewrite as:
+1. **Supersede the prior plan's four-todo cycle.** For every line referencing
+   the prior plan file (`./plan.md` or `./plan-v<N-1>.md`) — both the older
+   single-line `Execute [...]` form AND the four-todo-cycle lines (Create /
+   Review / Implement / Review implementation of) — rewrite as:
 
    ```
-   - [x] ~~Execute [<label>](./<old-plan-filename>)~~ (superseded by <versionLabel>)
+   - [x] ~~<original line body>~~ (superseded by <versionLabel>)
    ```
 
-   Never delete the old line — preserve history.
+   Mark the checkbox `[x]` and wrap the body in `~~...~~`. Never delete any
+   prior todo — preserve history.
 
-2. **Append the new plan todo.** Add a new line to the end of `## Todos`:
+2. **Append the new four-todo cycle.** Add four lines to the end of
+   `## Todos`, replacing `<versionLabel>` with the human label (e.g.
+   `plan v2`) and `<planFilename>` with the new file (e.g. `plan-v2.md`):
 
    ```
-   - [ ] Execute [<versionLabel>](./<planFilename>)
+   - [ ] Create [<versionLabel>](./<planFilename>)
+   - [ ] Review [<versionLabel>](./<planFilename>)
+   - [ ] Implement [<versionLabel>](./<planFilename>)
+   - [ ] Review implementation of [<versionLabel>](./<planFilename>)
    ```
 
-3. **Missing-section fallback.** If `## Todos` does not exist (legacy assignment predating this convention), insert it immediately after `## Acceptance Criteria` with a short guidance HTML comment followed by the new todo line.
+   For the first plan ever (`plan.md`), the label is `plan` and the four todos
+   point at `./plan.md`.
+
+3. **Missing-section fallback.** If `## Todos` does not exist (legacy
+   assignment predating this convention), insert it immediately after
+   `## Acceptance Criteria` with a short guidance HTML comment followed by
+   the new four-todo cycle.
 
 Also refresh the assignment frontmatter `updated` timestamp.
 
+> **Note:** the `syntaur plan version` CLI verb (used by the `replan` skill)
+> applies this exact same four-todo-cycle supersede pattern — `plan-assignment`
+> and `replan` are now in lockstep on this convention.
+
 ## Step 6: Report to User
 
 After writing the plan:

package/skills/replan/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: replan
+description: >-
+  Create a new versioned plan (`plan-v<N>.md`) for the active Syntaur
+  assignment after the current plan has been implemented (or a major scope
+  shift makes editing the existing plan misleading). Use when the user wants to
+  "create plan-v2", "replan", "version the plan", "make a new plan revision",
+  or when work needs another round under the Plan Versioning playbook.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Replan
+
+Bump the active assignment to a new plan version (`plan.md` → `plan-v2.md`,
+`plan-v2.md` → `plan-v3.md`, …). The CLI does the deterministic file ops; this
+skill writes the **body** of the new plan.
+
+This skill follows the **Plan Versioning** and **Create-and-Plan-Assignment**
+playbooks: prior plan-cycle todos are marked done with strikethrough +
+`(superseded by plan-v<N>)`, and a fresh four-todo cycle (Create / Review /
+Implement / Review implementation) is appended for the new plan. **Superseded
+todos are never deleted.**
+
+## When NOT to use this skill
+
+- The current plan has not been implemented yet — per the Plan Versioning
+  playbook, iterate on `plan.md` directly while it is still in draft /
+  in_progress.
+- The assignment is in a terminal status (`completed`, `failed`, `cancelled`).
+  Reopen it first via `syntaur reopen`.
+- You only need to add a new task to an in-flight plan — edit the existing
+  plan; do not bump version.
+- You want to write a fresh plan for a different assignment — switch context
+  via `clear-assignment` + `grab-assignment`, then call `plan-assignment`.
+
+## Step 1: Verify there is an active assignment
+
+Read `.syntaur/context.json` from the current working directory. Extract
+`assignmentSlug`, `projectSlug` (may be null for standalone), and
+`assignmentDir`.
+
+If the file is missing or has no `assignmentSlug`, abort with: "No active
+Syntaur assignment. Run `grab-assignment` first." Do not invent values.
+
+## Step 2: Confirm the prior plan was implemented
+
+Read the current plan file (the highest existing `plan*.md`). If its
+`## Tasks` (or equivalent) section still contains unchecked items AND the user
+has not explicitly said the prior plan is done, ask: "The current plan still
+has N unchecked tasks. Are you sure you want to create plan-v<N>? (Plan
+Versioning playbook recommends iterating on `plan.md` until implementation
+is complete.)" Stop unless the user confirms.
+
+## Step 3: Run `syntaur plan version`
+
+```bash
+syntaur plan version --assignment <assignmentSlug> [--project <projectSlug>]
+```
+
+This is the only file-mutating step the skill performs through the CLI. It:
+
+1. Picks the next available `plan-v<N>.md` filename.
+2. Writes a stub plan with frontmatter and a `## Carried-forward tasks`
+   section pre-populated with any unchecked todos from the prior plan body.
+3. Rewrites the assignment.md `## Todos` section per the four-todo cycle:
+   marks the four prior plan-cycle todos as
+   `- [x] ~~<original>~~ (superseded by plan-v<N>)` and appends a fresh
+   `Create / Review / Implement / Review implementation` cycle pointing at the
+   new file.
+4. Never deletes any prior todo.
+
+If the CLI exits non-zero, surface the error to the user and stop.
+
+## Step 4: Read the prior plan and the new stub
+
+Read the prior `plan*.md` and the freshly created `plan-v<N>.md`. The stub
+already contains:
+
+- Frontmatter (`assignment`, `status: draft`, `created`, `updated`)
+- A heading
+- A `## Objective` section with a placeholder
+- A `## Carried-forward tasks` section
+- Empty `## Tasks` and `## Verification` sections
+
+## Step 5: Write the new plan body
+
+Replace the placeholder content in the stub with a concrete, implementable
+plan for the new revision. Match the structure of the prior plan (Files /
+Tasks / Verification, etc.) but keep the body concise. Document explicitly
+**why** a new revision is needed (e.g., "scope expanded after review",
+"rework after partial implementation").
+
+Do NOT touch `assignment.md` here — the CLI already updated `## Todos`.
+
+## Step 6: Update progress.md
+
+Append a progress entry recording the new plan version, the reason, and a
+pointer to the new plan file.
+
+## Step 7: Report to User
+
+Summarize:
+
+- New plan path (`<assignmentDir>/plan-v<N>.md`).
+- Number of carried-forward unchecked tasks.
+- Number of prior todos rewritten as superseded (should be the four-todo
+  cycle of the previous plan).
+- Reminder: prior plan files are kept on disk as immutable history; do not
+  delete them.
+- Next step: review the new plan and begin the new four-todo cycle.

package/skills/resume-session/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: resume-session
+description: >-
+  Re-orient a fresh Syntaur session on the active assignment without
+  re-reading the full transcript. Loads the latest saved session summary,
+  `.syntaur/context.json`, and any open handoff. Use when the user says
+  "resume", "pick up where we left off", "continue this assignment", or after
+  a compact / new session start. Symmetric counterpart to
+  `/save-session-summary`.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Resume Session
+
+Print a compact orientation block so the agent (and the user) can pick up the
+active assignment cleanly. **Idempotent — does not mutate any state.** Re-run
+freely; nothing on disk changes.
+
+## When NOT to use this skill
+
+- Cross-ticket handoff to a downstream assignment — that's `complete-assignment`
+  (writes `handoff.md`).
+- First-time grab of an assignment — use `/grab-assignment` instead; this skill
+  assumes context already exists.
+- Saving the current session's progress — that's `/save-session-summary` (the
+  symmetric write side).
+
+## Step 1: Verify there is an active context
+
+Run `syntaur session resume`. The CLI:
+
+1. Reads `.syntaur/context.json` from the current working directory.
+2. Aborts (exit 1) with a clear message if missing or if no `assignmentDir`
+   is set — telling the user to run `grab-assignment` first.
+3. Otherwise scans `<assignmentDir>/sessions/<sid>/summary.md` and picks the
+   most recently modified.
+4. Reads `<assignmentDir>/handoff.md` (the canonical single-file handoff per
+   assignment, managed by `complete-assignment`) and reports it if its body
+   has been written beyond the scaffolded placeholder.
+5. Prints a human-readable orientation block (project, assignment, branch,
+   workspace root, latest summary path, open handoff, warnings).
+
+If the CLI prints warnings, surface them — the most common is "no session
+summary on disk", which means a prior session never ran
+`/save-session-summary`.
+
+## Step 2: Read the latest session summary (when present)
+
+Open the path printed in step 1 (`<assignmentDir>/sessions/<sid>/summary.md`)
+and load its `## Snapshot`, `## What Was Done`, `## What's Next`, `## Open
+Questions`, and `## Load-Bearing Context` sections. Use these to seed your
+working knowledge of the assignment without scanning the full transcript.
+
+## Step 3: Read the open handoff (when present)
+
+If the CLI reported an open handoff, read that file too. It is the highest
+priority signal — there is an outstanding baton to consume.
+
+## Step 4: Read assignment.md and progress.md
+
+Always read the current assignment.md (objective, acceptance criteria, todos)
+and the tail of progress.md so you know what has been logged since the last
+summary.
+
+## Step 5: Idempotency check (optional)
+
+Re-run `syntaur session resume --json` if you want machine-readable confirmation
+that nothing on disk changed between runs. The output is deterministic for a
+given on-disk state.
+
+## Step 6: Report to User
+
+Summarize:
+
+- Active project / assignment / branch.
+- Latest session summary timestamp + a one-sentence what's-next pulled from
+  it.
+- Whether there is an open handoff (and a one-line summary if so).
+- Open questions to flag back to the user.
+- Suggested next concrete action.