syntaur 0.8.0 → 0.12.0

package/platforms/claude-code/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/platforms/claude-code/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/platforms/claude-code/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/platforms/claude-code/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.

package/platforms/claude-code/skills/set-workspace/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: set-workspace
+description: >-
+  Populate the four `workspace.*` fields (repository, worktreePath, branch,
+  parentBranch) in the active assignment's `assignment.md` frontmatter
+  before any implementation code is written. Use after creating a worktree,
+  picking a branch, or any time the user wants to "set the workspace",
+  "wire the assignment to a branch", or per the Workspace Before Code
+  playbook. Validates frontmatter via `syntaur doctor --assignment --json`
+  before writing — refuses to touch a malformed file.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Set Workspace
+
+Write the four canonical `workspace.*` fields in `assignment.md` frontmatter
+so that the PreToolUse write-boundary hook will allow implementation work.
+Validates the file first via `syntaur doctor --assignment --json` and
+refuses to write on errors.
+
+This skill implements the **Workspace Before Code** playbook: never write
+implementation code until workspace fields are set.
+
+## When NOT to use this skill
+
+- The workspace fields are already set correctly. Read the assignment.md
+  first; if all four fields match the intended values, do nothing.
+- You want to create the worktree itself — use `/syntaur-worktree`, which
+  composes worktree creation AND workspace field updates in one move.
+- The assignment is in a terminal status (`completed`, `failed`,
+  `cancelled`). Reopen it first if you really need to change workspace.
+
+## Step 1: Resolve the assignment file
+
+Read `.syntaur/context.json` from the current working directory. Extract
+`assignmentDir`. The target file is `<assignmentDir>/assignment.md`.
+
+If no context, abort with: "No active assignment. Run `grab-assignment`
+first."
+
+## Step 2: Pre-write validation
+
+```bash
+syntaur doctor --assignment <assignmentDir>/assignment.md --json
+```
+
+Parse the JSON output. If `ok: false`, refuse to proceed. Report the
+`errors[]` to the user verbatim and recommend they fix the underlying
+frontmatter (or run `syntaur doctor` for the broader project context).
+**Do not write any changes if the file is malformed.**
+
+## Step 3: Gather inputs
+
+Required (one or more — at minimum the user must specify enough to fill
+all four fields):
+
+- `--repository <path>` — repo root (typically `git rev-parse --show-toplevel`).
+- `--worktree-path <path>` — usually `<repository>/.worktrees/<branch>`
+  per the repo-local convention.
+- `--branch <name>` — current branch (`git rev-parse --abbrev-ref HEAD`).
+- `--parent-branch <name>` — typically `main`.
+
+Defaults the skill should auto-detect when not supplied:
+
+- `repository` ← `git -C $(pwd) rev-parse --show-toplevel`.
+- `branch` ← `git -C $(pwd) rev-parse --abbrev-ref HEAD`.
+- `worktreePath` ← `$(pwd)` (when invoked from the worktree itself).
+- `parentBranch` ← prompt the user; do not invent.
+
+## Step 4: Read assignment.md
+
+Locate the `workspace:` block in the frontmatter. It must look like:
+
+```yaml
+workspace:
+  repository: <value-or-null>
+  worktreePath: <value-or-null>
+  branch: <value-or-null>
+  parentBranch: <value-or-null>
+```
+
+If the block is missing entirely, refuse to write — `doctor --assignment`
+should have caught it; this is a defensive check.
+
+## Step 5: Write the four fields
+
+Replace the four lines in place. Quote string values containing special
+characters; use `null` literal for unset fields. Preserve the rest of the
+frontmatter and body bit-for-bit.
+
+Bump the top-level `updated` timestamp in the frontmatter.
+
+## Step 6: Re-validate
+
+Re-run `syntaur doctor --assignment <path> --json`. Expect `ok: true`. If
+the post-write validation fails, restore the prior file content and report
+the error — do not leave the file in a half-written state.
+
+## Step 7: Report to User
+
+Summarize:
+
+- Path of the modified assignment.md.
+- The four field values that were written.
+- Confirmation that post-write `doctor --assignment` passed.
+- Reminder: implementation work is now unblocked by the write-boundary hook.

package/platforms/claude-code/skills/syntaur-protocol/SKILL.md

@@ -111,6 +111,10 @@ ls ~/.syntaur/playbooks/*.md 2>/dev/null
 - Write handoffs with enough context for another agent or human to continue cleanly. Record decisions in `decision-record.md` with Status / Context / Decision / Consequences — downstream dependents auto-load these during grab.
 - Commit frequently with messages referencing the assignment slug.
 
+### Proof artifacts (opt-in)
+
+Agents can attach typed evidence so a human reviewer can verify work in seconds without re-running it. Use `syntaur capture` after a meaningful change is verified, then `syntaur proof build` to render `proof.html` at the assignment dir. Artifact kinds at v1: `screenshot`, `video`, `asciinema`, `http`, `text`. Criterion linkage is optional (0-based index into `## Acceptance Criteria`); untagged or stale-out-of-range artifacts render in a final "Other artifacts" section. Files live under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The `complete-assignment` skill mentions the proof page in its final report. **No completion gate** — proof is purely opt-in for v1.
+
 ## References
 
 For the full directory structure, lifecycle state table, and detailed file ownership rules, read:

package/platforms/claude-code/skills/syntaur-protocol/references/protocol-summary.md

@@ -80,3 +80,11 @@ Protocol version: **2.0**
 10. **Comments** are appended to `comments.md` via `syntaur comment <slug> "body" [--type question|note|feedback] [--reply-to <id>]`. Never edit `comments.md` directly. Questions carry a `resolved` flag toggled in the dashboard.
 11. **Cross-assignment work** is requested via `syntaur request <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.
 12. **Agent sessions** in `syntaur.db` must use real agent-runtime session IDs. Synthesized UUIDs are rejected. Plugins for Claude Code / Codex populate `.syntaur/context.json` with the real id via a SessionStart hook; other agents should source it from their runtime and pass `--session-id` explicitly.
+
+## Proof artifacts (opt-in)
+
+Agents can attach typed evidence to an assignment so a human reviewer can verify the work in seconds without re-running it.
+
+- `syntaur capture --kind <screenshot|video|asciinema|http|text> [--file <path>] [--criterion <index>] [--note <text>] [target]` — record an artifact for the active assignment. Criterion linkage is optional (0-based index into the `## Acceptance Criteria` checklist). For `--kind=text`, supply `--note` and omit `--file`. For `--kind=http`, supply `--file` (transcript) or `--note` (inline summary).
+- `syntaur proof build [target]` — render `proof.html` and `proof.md` at the assignment dir, walking the `## Acceptance Criteria` list and embedding tagged artifacts inline beneath each criterion. Untagged or stale (out-of-range) captures land in a final "Other artifacts" section. Atomic overwrite — safe to re-run.
+- Artifacts are stored under `<assignmentDir>/proof/<criterion|untagged>/<id>.<ext>`. The DB row lives in `~/.syntaur/syntaur.db` alongside session tracking. No completion gate — proof is purely opt-in for v1.

package/platforms/claude-code/skills/syntaur-worktree/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: syntaur-worktree
+description: >-
+  Create a git worktree for a Syntaur assignment under
+  `<repo>/.worktrees/<branch>`, claim the assignment, and bind the new
+  workspace to the agent session — all in one move. Use when the user wants
+  to "make a worktree", "branch + worktree for this assignment", "spin up an
+  isolated workspace", or set up parallel work on a different assignment.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Syntaur Worktree
+
+Atomic worktree-and-grab for a Syntaur assignment. Composes four lower-level
+operations:
+
+1. `git worktree add` (via `syntaur worktree create`) — repo-local convention
+   `<repository>/.worktrees/<branch>`.
+2. Update `assignment.md` workspace fields (done by the same CLI verb,
+   transactionally — rolls back the worktree on write failure).
+3. `syntaur assign` + `syntaur start` — claim the assignment for this agent
+   and transition to `in_progress`.
+4. Write `.syntaur/context.json` inside the new worktree so the session is
+   bound there.
+
+## When NOT to use this skill
+
+- You only want to create a git worktree outside of Syntaur — use
+  `git worktree add` directly. This skill assumes a Syntaur assignment exists.
+- The assignment already has a worktree path set in `assignment.md` workspace
+  fields. Check first; reuse the existing path.
+- You want to grab an assignment without creating a worktree — use
+  `/grab-assignment` directly.
+
+## Step 1: Resolve inputs
+
+Required arguments from the user (or interactive prompts):
+
+- `--project <slug>` (omit for standalone assignments — pass `--id <uuid>`)
+- `--assignment <slug-or-uuid>`
+- `--branch <name>` — the new branch name (also the worktree dir name)
+- `--repository <path>` — defaults to current working directory; usually the
+  repo root the assignment lives in
+- `--parent-branch <name>` — defaults to `main`
+
+The computed worktree path is **always**
+`<repository>/.worktrees/<branch>`. Never `.claude/worktrees/`. Never
+`~/.syntaur/worktrees/...`. The repo-local convention is enforced.
+
+## Step 2: Pre-flight
+
+- Confirm `<repository>/.git` exists.
+- Confirm the branch does NOT already exist (otherwise the CLI will fail
+  cleanly — surface that error).
+- Confirm the assignment is not in a terminal status. If it is, suggest
+  `syntaur reopen` first.
+
+## Step 3: Create worktree + record workspace
+
+```bash
+syntaur worktree create \
+  --repository <repository> \
+  --branch <branch> \
+  --parent-branch <parent-branch> \
+  --assignment <slug-or-uuid> \
+  --project <project-slug>
+```
+
+The CLI handles atomicity — on any failure the worktree (if created) and the
+new branch are removed.
+
+## Step 4: Claim the assignment
+
+```bash
+syntaur assign <assignment> --agent <your-agent-name> --project <project-slug>
+syntaur start <assignment> --project <project-slug>   # only if status was pending
+```
+
+Skip `start` for any non-`pending` status — never rewind a `review`,
+`completed`, or `failed` assignment.
+
+## Step 5: Bind the new worktree to your session
+
+`cd` into the new worktree path. Write
+`<worktreePath>/.syntaur/context.json` mirroring the format produced by
+`/grab-assignment` (projectSlug, assignmentSlug, projectDir, assignmentDir,
+workspaceRoot, title, branch, sessionId, transcriptPath, grabbedAt).
+
+If the runtime exposes a real session id (e.g. Claude Code's
+`~/.claude/sessions/`), include it. Otherwise omit `sessionId` entirely; the
+SessionStart hook will populate it on next run.
+
+## Step 6: Register the session with the dashboard
+
+```bash
+syntaur track-session \
+  --project <project-slug> --assignment <assignment-slug> \
+  --agent <your-agent-name> \
+  --session-id <real-id> \
+  --path "$(pwd)"
+```
+
+Skip if no real session id is available. Surface the failure non-fatally.
+
+## Step 7: Report to User
+
+Summarize:
+
+- New worktree path (`<repository>/.worktrees/<branch>`).
+- Branch + parent branch.
+- Assignment slug, project slug, new status.
+- Whether the session was registered with the dashboard.
+- Reminder to `cd` into the new worktree if the parent shell is not already
+  there.

package/platforms/codex/README.md

@@ -4,9 +4,9 @@ Syntaur plugin for OpenAI Codex. Installed automatically during `syntaur setup`.
 
 ## What's included
 
-- **Skills:** syntaur-protocol, create-project, create-assignment, grab-assignment, plan-assignment, complete-assignment, track-session, save-session-summary
+- **Skills:** syntaur-protocol, create-project, create-assignment, grab-assignment, plan-assignment, complete-assignment, track-session, save-session-summary, manage-statuses, clear-assignment, replan, resume-session, syntaur-worktree, add-resource, add-memory, list-assignments, log-progress, set-workspace
 - **Hooks:** write boundary enforcement, session cleanup
-- **Commands:** track-session, save-session-summary (Codex has no `PreCompact` event — invoke manually before compaction or session end)
+- **Commands:** track-session, save-session-summary, replan, resume-session, syntaur-worktree, add-resource, add-memory, list-assignments, log-progress, set-workspace (Codex has no `PreCompact` event — invoke save-session-summary manually before compaction or session end)
 - **Agents:** syntaur-protocol (background)
 - **References:** protocol docs
 

package/platforms/codex/agents/syntaur-operator.md

@@ -97,6 +97,13 @@ Use these commands directly when needed:
 - `syntaur uninstall [--all] [--yes]`
 - `syntaur track-session --project <project-slug> --assignment <assignment-slug> --agent codex --session-id <real-id> --transcript-path <rollout-path> --path <cwd>` (both `--session-id` and `--transcript-path` must come from the matching Codex rollout file — never synthesize)
 - `syntaur setup-adapter codex --project <project-slug> --assignment <assignment-slug>`
+- `syntaur plan version --assignment <slug> [--project <slug>]` — bump to `plan-v<N>.md` per Plan Versioning playbook
+- `syntaur session resume [--json]` — re-orient on the active assignment from latest session summary + context.json + open handoff (idempotent)
+- `syntaur worktree create --branch <name> [--repository <path>] [--parent-branch <name>] [--assignment <slug>] [--project <slug>]` — repo-local `<repository>/.worktrees/<branch>` convention
+- `syntaur resource add --project <slug> --name <name> --source <url> [--category <name>] [--related-assignments <slug,slug>]` — writes resource file + regenerates `_index.md`
+- `syntaur memory add --project <slug> --name <name> --source <text> [--scope <scope>] [--source-assignment <slug>] [--related-assignments <slug,slug>]` — writes memory file + regenerates `_index.md`
+- `syntaur ls [--status <list>] [--project <slug>] [--tag <list>] [--age <duration>] [--json]` — cross-project filtered listing (non-interactive; for the TUI use `syntaur browse`)
+- `syntaur doctor --assignment <path> --json` — validate a single assignment.md frontmatter and emit `{ok, errors[], warnings[]}` (used by the `set-workspace` skill before writing)
 
 ## Standard Workflows