syntaur 0.3.0 → 0.4.0

package/statusline/statusline.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Syntaur statusline for Claude Code.
+#
+# Reads JSON from stdin per Claude Code's statusLine contract and prints a
+# single line containing:
+#   [optional: output from a wrapped user script]
+#   <git repo:branch>
+#   <active syntaur assignment>
+#   <sessionId suffix>
+#
+# Wrapping: if SYNTAUR_STATUSLINE_WRAP names an executable, or the first
+# non-empty line of $HOME/.syntaur/statusline.conf is a path to an executable,
+# that script is invoked first with the same stdin; its stdout becomes the
+# leading segment. This lets users who already had a custom statusline keep
+# it while composing syntaur's extra info on the right.
+#
+# Never fails the terminal — always exits 0.
+
+set -o pipefail 2>/dev/null || true
+
+INPUT=$(cat)
+
+# Degrade cleanly if jq is unavailable. Emit just the marker so users notice.
+if ! command -v jq >/dev/null 2>&1; then
+  printf '%s' '(syntaur: jq missing)'
+  exit 0
+fi
+
+SESSION_ID=""
+CWD=""
+
+if [ -n "$INPUT" ]; then
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+  CWD=$(printf '%s' "$INPUT" | jq -r '.workspace.current_dir // .cwd // empty' 2>/dev/null)
+fi
+
+[ -z "$CWD" ] && CWD="$PWD"
+
+# --- Optional wrap: compose with an existing user script ---
+WRAP_PATH="${SYNTAUR_STATUSLINE_WRAP:-}"
+if [ -z "$WRAP_PATH" ] && [ -f "$HOME/.syntaur/statusline.conf" ]; then
+  # First non-empty, non-comment line is the wrap path.
+  WRAP_PATH=$(awk 'NF && !/^#/{print; exit}' "$HOME/.syntaur/statusline.conf" 2>/dev/null)
+fi
+WRAPPED_OUT=""
+if [ -n "$WRAP_PATH" ] && [ -r "$WRAP_PATH" ]; then
+  # Run the wrapped script with the same stdin and a 2-second timeout (best-effort).
+  if command -v timeout >/dev/null 2>&1; then
+    WRAPPED_OUT=$(printf '%s' "$INPUT" | timeout 2 bash "$WRAP_PATH" 2>/dev/null)
+  else
+    WRAPPED_OUT=$(printf '%s' "$INPUT" | bash "$WRAP_PATH" 2>/dev/null)
+  fi
+  # Collapse any trailing newlines so the composed line stays single-row.
+  WRAPPED_OUT=$(printf '%s' "$WRAPPED_OUT" | tr -d '\r' | awk 'NF{line=$0} END{print line}' 2>/dev/null)
+fi
+
+# --- Segment: git repo:branch ---
+GIT_SEG=""
+if [ -n "$CWD" ] && [ -d "$CWD" ]; then
+  GIT_ROOT=$(git --no-optional-locks -C "$CWD" rev-parse --show-toplevel 2>/dev/null)
+  if [ -n "$GIT_ROOT" ]; then
+    REPO=$(basename "$GIT_ROOT")
+    BRANCH=$(git --no-optional-locks -C "$CWD" symbolic-ref --short HEAD 2>/dev/null)
+    if [ -z "$BRANCH" ]; then
+      SHORT=$(git --no-optional-locks -C "$CWD" rev-parse --short HEAD 2>/dev/null)
+      [ -n "$SHORT" ] && BRANCH="detached@$SHORT"
+    fi
+    if [ -n "$BRANCH" ]; then
+      GIT_SEG="$REPO:$BRANCH"
+    else
+      GIT_SEG="$REPO"
+    fi
+  fi
+fi
+
+# --- Segment: active syntaur assignment ---
+ASSIGNMENT_SEG=""
+CONTEXT_FILE="$CWD/.syntaur/context.json"
+if [ -f "$CONTEXT_FILE" ]; then
+  PROJECT_SLUG=$(jq -r '.projectSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+  ASSIGNMENT_SLUG=$(jq -r '.assignmentSlug // empty' "$CONTEXT_FILE" 2>/dev/null)
+  ASSIGNMENT_DIR=$(jq -r '.assignmentDir // empty' "$CONTEXT_FILE" 2>/dev/null)
+
+  TITLE=""
+  if [ -n "$ASSIGNMENT_DIR" ] && [ -f "$ASSIGNMENT_DIR/assignment.md" ]; then
+    TITLE=$(awk '/^title:/{sub(/^title:[[:space:]]*"?/,""); sub(/"?[[:space:]]*$/,""); print; exit}' "$ASSIGNMENT_DIR/assignment.md" 2>/dev/null)
+  fi
+
+  LABEL=""
+  if [ -n "$PROJECT_SLUG" ] && [ -n "$ASSIGNMENT_SLUG" ]; then
+    LABEL="$PROJECT_SLUG/$ASSIGNMENT_SLUG"
+  elif [ -n "$ASSIGNMENT_SLUG" ]; then
+    LABEL="standalone/${ASSIGNMENT_SLUG:0:8}"
+  fi
+
+  if [ -n "$LABEL" ] && [ -n "$TITLE" ]; then
+    ASSIGNMENT_SEG="$LABEL — $TITLE"
+  elif [ -n "$LABEL" ]; then
+    ASSIGNMENT_SEG="$LABEL"
+  fi
+fi
+
+# --- Segment: session id suffix ---
+SESSION_SEG=""
+if [ -n "$SESSION_ID" ]; then
+  LEN=${#SESSION_ID}
+  if [ "$LEN" -gt 8 ]; then
+    SESSION_SEG="…${SESSION_ID: -8}"
+  else
+    SESSION_SEG="$SESSION_ID"
+  fi
+fi
+
+# --- Compose. Wrapped output (if any) leads; syntaur segments trail. ---
+SYNTAUR_PARTS=""
+for seg in "$GIT_SEG" "$ASSIGNMENT_SEG" "$SESSION_SEG"; do
+  if [ -n "$seg" ]; then
+    if [ -z "$SYNTAUR_PARTS" ]; then
+      SYNTAUR_PARTS="$seg"
+    else
+      SYNTAUR_PARTS="$SYNTAUR_PARTS · $seg"
+    fi
+  fi
+done
+
+if [ -n "$WRAPPED_OUT" ] && [ -n "$SYNTAUR_PARTS" ]; then
+  printf '%s · %s' "$WRAPPED_OUT" "$SYNTAUR_PARTS"
+elif [ -n "$WRAPPED_OUT" ]; then
+  printf '%s' "$WRAPPED_OUT"
+else
+  printf '%s' "$SYNTAUR_PARTS"
+fi
+exit 0

package/vendor/syntaur-skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Prong Horn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/syntaur-skills/README.md

@@ -0,0 +1,43 @@
+# syntaur-skills
+
+Agent-agnostic skills for the [Syntaur](https://github.com/prong-horn/syntaur) coordination protocol. Works with any AI coding agent — Claude Code, Cursor, Codex, OpenCode, and more.
+
+## Prerequisites
+
+Install the Syntaur CLI:
+
+```bash
+npm install -g syntaur
+syntaur setup
+```
+
+## Install
+
+```bash
+npx skills add prong-horn/syntaur-skills
+```
+
+Or install a specific skill:
+
+```bash
+npx skills add prong-horn/syntaur-skills --skill syntaur-protocol
+```
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `syntaur-protocol` | Core protocol knowledge — write boundaries, lifecycle states, conventions. Auto-activates when working with Syntaur files. |
+| `grab-assignment` | Discover and claim a pending assignment from a project. Sets up working context. |
+| `plan-assignment` | Create a detailed implementation plan for the current assignment. |
+| `complete-assignment` | Write a handoff and transition an assignment to review or completed. |
+| `create-project` | Create a new project with full scaffolding (manifest + indexes + resources + memories). |
+| `create-assignment` | Create a new assignment within a project (or as a standalone one-off at `~/.syntaur/assignments/<uuid>/`). |
+
+## How it works
+
+Syntaur is a coordination protocol for AI agents built on markdown files. Projects contain assignments, assignments have lifecycle states, and agents follow write boundary rules about which files they can modify. Everything lives under `~/.syntaur/` and is managed via the `syntaur` CLI.
+
+These skills teach your agent the protocol so it can participate in Syntaur-coordinated work — regardless of which coding agent you use.
+
+For platform-specific integrations (hooks, commands, sandbox enforcement), see the [Syntaur plugin system](https://github.com/prong-horn/syntaur).

package/vendor/syntaur-skills/skills/complete-assignment/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: complete-assignment
+description: >-
+  Write a handoff and transition the current Syntaur assignment to review or completed.
+  Use when the user wants to finish an assignment, write a handoff, or submit work for review.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Complete Assignment
+
+Write a handoff for your current Syntaur assignment and transition it to `review` or `completed`.
+
+## Input
+
+Optional: the user may pass `--complete` to transition directly to `completed` instead of `review`. However, `--complete` is only allowed if ALL acceptance criteria are met AND every `## Todos` item is either checked or marked superseded. If any criterion or todo is unresolved, always transition to `review` regardless of the flag, and inform the user why.
+
+## Step 1: Load Context
+
+Read `.syntaur/context.json` from the current working directory.
+
+If the file does not exist, tell the user: "No active assignment found. Run `grab-assignment` first."
+
+Extract: `projectSlug`, `assignmentSlug`, `assignmentDir`, `projectDir`.
+
+## Step 2: Load Playbooks
+
+Read all playbook files from `~/.syntaur/playbooks/`:
+
+```bash
+ls ~/.syntaur/playbooks/*.md 2>/dev/null
+```
+
+Verify your work complies with their rules. If any playbook has completion-related rules (e.g., "run tests before done"), follow them before proceeding.
+
+## Step 3: Verify Acceptance Criteria and Todos
+
+Read `<assignmentDir>/assignment.md` and find the `## Acceptance Criteria` and `## Todos` sections.
+
+Review each acceptance criterion (checkbox item) AND each todo. Superseded todos marked `- [x] ~~Execute [...](./plan-v<N>.md)~~ (superseded by plan-v<N>)` count as resolved — they do not need to be done again.
+
+For each:
+- If you believe it is met / done, note why (what was implemented, where).
+- If it is NOT met / done, flag it clearly.
+
+If any acceptance criteria are unmet OR any todo is still `- [ ]` and not superseded, warn the user: "The following are not yet done: [list]. Do you want to proceed with the handoff anyway?" — stop if the user says no.
+
+## Step 3.5: Append a Final Progress Entry
+
+Before writing the handoff, append a final entry to `<assignmentDir>/progress.md` summarizing what was completed. The entry goes at the **top** of the body (reverse-chronological) under a new `## <ISO 8601 timestamp>` heading:
+
+```markdown
+## <ISO 8601 timestamp>
+
+<One paragraph summarizing the final state of work: what was implemented, what verifications passed, and any deliberate scope exclusions.>
+```
+
+Bump `entryCount` and set `updated` to the current timestamp in `progress.md`'s frontmatter.
+
+Do NOT add a `## Progress` section to `assignment.md` — progress entries live exclusively in `progress.md` as of protocol v2.0.
+
+## Step 4: Write Handoff Entry
+
+Read `<assignmentDir>/handoff.md` to see its current content and frontmatter.
+
+Append a new handoff entry to the markdown body. Read the current `handoffCount` from the frontmatter and use `handoffCount + 1` as the entry number. The entry must follow this format:
+
+```markdown
+## Handoff <N>: <ISO 8601 timestamp>
+
+**From:** <your-agent-name>
+**To:** human
+**Reason:** <Why this handoff is happening, e.g., "Assignment complete, handing off for review.">
+
+### Summary
+<One paragraph summarizing what was accomplished and what remains>
+
+### Current State
+- <What is working>
+- <What is not working or partially done>
+- <Acceptance criteria status: N of M met>
+
+### Next Steps
+- <Recommended next actions for the reviewer or next agent>
+
+### Important Context
+- <Anything the next agent/human needs that is not in the assignment or plan>
+```
+
+Also update the handoff.md frontmatter: set `updated` to the current timestamp and increment the `handoffCount` by 1.
+
+## Step 5: Update Checkboxes (Criteria + Todos)
+
+In `<assignmentDir>/assignment.md`, update checkboxes in both the `## Acceptance Criteria` and `## Todos` sections to reflect the current state. Check off items that were completed (change `- [ ]` to `- [x]`).
+
+Ideally, these should have been checked off incrementally during implementation. If they are already checked, verify they are still accurate. If some were missed, check them off now and note which were verified at completion time vs. during development in the handoff.
+
+Do NOT uncheck or rewrite superseded todo lines matching `- [x] ~~...~~ (superseded by ...)` — preserve that history intact.
+
+## Step 6: Close Session (optional)
+
+If `.syntaur/context.json` includes a `sessionId` and the Syntaur dashboard is running, mark the session as completed:
+
+```bash
+curl -s -X PATCH "http://localhost:$(cat ~/.syntaur/dashboard-port 2>/dev/null || echo 4800)/api/agent-sessions/<session-id>/status" \
+  -H "Content-Type: application/json" \
+  -d '{"status":"completed","projectSlug":"<project-slug>"}'
+```
+
+If this fails (e.g., dashboard not running), it is non-critical — the session will be reconciled automatically.
+
+## Step 7: Transition Assignment State
+
+If the user requested `--complete` and all criteria are met:
+
+```bash
+syntaur complete <assignment-slug> --project <project-slug>
+```
+
+Otherwise, transition to review:
+
+```bash
+syntaur review <assignment-slug> --project <project-slug>
+```
+
+If the command fails, report the error. Common failures:
+- Assignment is not in `in_progress` status
+- Project not found
+
+## Step 8: Clean Up Context
+
+Delete the context file:
+
+```bash
+rm .syntaur/context.json
+```
+
+## Step 9: Report to User
+
+Summarize:
+- Assignment slug and title
+- New status (review or completed)
+- Number of acceptance criteria met vs total
+- 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/vendor/syntaur-skills/skills/create-assignment/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: create-assignment
+description: >-
+  Create a new Syntaur assignment within a project (or as a standalone one-off).
+  Use when the user wants to add a task, create an assignment, or break down
+  work within a Syntaur project.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Create Assignment
+
+Create a new assignment — project-nested or standalone.
+
+## Input
+
+Expects arguments from the user:
+
+- First (required): the assignment title (e.g., `"Add login endpoint"`)
+- `--project <slug>` (required unless `--one-off`): the project to add the assignment to
+- `--one-off` (optional): create a **standalone** assignment at `~/.syntaur/assignments/<uuid>/` with `project: null`. The folder is named by UUID; `slug` is display-only. `--depends-on` is not permitted for standalone assignments.
+- `--slug <slug>` (optional): override the auto-generated assignment slug
+- `--priority <level>` (optional): `low`, `medium` (default), `high`, or `critical`
+- `--type <type>` (optional): classification such as `feature`, `bug`, `refactor`, `research`, `chore`. Defaults to `feature`. When `~/.syntaur/config.md` defines `types.definitions`, the CLI validates against that list.
+- `--depends-on <slug[,slug...]>` (optional, project-nested only): comma-separated list of assignment slugs this depends on
+- `--dir <path>` (optional): override the default project directory
+
+If no title was provided, ask the user what the assignment should be called.
+
+If neither `--project` nor `--one-off` was provided, check `.syntaur/context.json` for an active assignment. If present, default `--project` to that context's `projectSlug` and confirm with the user: "Add this assignment to project `<projectSlug>`?"
+
+If no active context and no project flag, ask the user which project to add it to, or whether it should be a one-off.
+
+## Step 1: Run the CLI
+
+Build the command from the parsed arguments:
+
+```bash
+syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--type <type>] [--depends-on <slugs>] [--dir <path>]
+```
+
+Or for a one-off (standalone at `~/.syntaur/assignments/<uuid>/`):
+
+```bash
+syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--type <type>] [--dir <path>]
+```
+
+If the command fails (e.g., project not found, slug collision, invalid type), report the error and suggest fixes.
+
+## Step 2: Read the Created Assignment
+
+After successful creation, extract the assignment slug (and for standalone, the UUID) and directory from the CLI output. Read the generated `assignment.md`:
+
+```bash
+# Project-nested:
+cat ~/.syntaur/projects/<project-slug>/assignments/<assignment-slug>/assignment.md
+
+# Standalone:
+cat ~/.syntaur/assignments/<uuid>/assignment.md
+```
+
+## Step 3: Guide Next Steps
+
+Tell the user:
+- The assignment was created with its slug, priority, type, and location. For standalone assignments, note that the folder is named by UUID (not slug) — `slug` is display-only.
+- Files created: `assignment.md`, `progress.md`, `comments.md`, `scratchpad.md`, `handoff.md`, `decision-record.md`. **`plan.md` is NOT scaffolded** — plan files are optional and created on demand by the `plan-assignment` skill.
+- Remind the user: `progress.md` is where timestamped progress entries go (NOT `assignment.md`), and `comments.md` is CLI-mediated — write only via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`.
+- Suggest editing `assignment.md` to fill in the objective, acceptance criteria, context, and any initial todos. The `## Todos` section accepts simple tasks or markdown links to plan files.
+- If dependencies were set, note them. Standalone assignments cannot declare `dependsOn`.
+- Suggest `grab-assignment <project-slug> <assignment-slug>` (or `grab-assignment --id <uuid>` for standalone) to claim and start working on it.

package/vendor/syntaur-skills/skills/create-project/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: create-project
+description: >-
+  Create a new Syntaur project with full scaffolding (manifest, indexes,
+  resources, memories). Use when the user wants to start a new project or
+  initiative in Syntaur.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Create Project
+
+Create a new Syntaur project with full scaffolding.
+
+## Input
+
+Expects arguments from the user:
+
+- First (required): the project title (e.g., `"Build Auth System"`)
+- `--slug <slug>` (optional): override the auto-generated slug
+- `--dir <path>` (optional): override the default project directory
+- `--workspace <workspace>` (optional): workspace grouping label (e.g., `syntaur`, `reeva`)
+
+If no title was provided, ask the user what the project should be called.
+
+## Step 1: Run the CLI
+
+```bash
+syntaur create-project "<title>" [--slug <slug>] [--dir <path>] [--workspace <workspace>]
+```
+
+If the command fails (e.g., slug collision, empty title), report the error and suggest fixes.
+
+## Step 2: Read the Created Project
+
+Extract the project slug and directory from the CLI output. Read the generated `project.md` to confirm structure:
+
+```bash
+cat ~/.syntaur/projects/<slug>/project.md
+```
+
+## Step 3: Guide Next Steps
+
+Tell the user:
+
+- The project was created with its slug and location (`~/.syntaur/projects/<slug>/`).
+- Key files scaffolded:
+  - `project.md` — human-authored goal and context (edit this).
+  - `manifest.md` — derived root navigation (do not edit directly).
+  - `_index-assignments.md`, `_index-plans.md`, `_index-decisions.md`, `_status.md` — derived indexes.
+  - `resources/_index.md` and `memories/_index.md` — shared-writable area scaffolding.
+- Per-project `agent.md` / `claude.md` are NOT created — protocol v2.0 removed them. Agent-level conventions live at the repo root in `CLAUDE.md` / `AGENTS.md`, and user-defined behavioral rules live in `~/.syntaur/playbooks/<slug>.md`.
+- Suggest they edit `project.md` to fill in the goal, scope, and context sections.
+- Suggest running `create-assignment "<title>" --project <slug>` to add assignments to this project. Or `create-assignment "<title>" --one-off` for standalone work at `~/.syntaur/assignments/<uuid>/`.

package/vendor/syntaur-skills/skills/grab-assignment/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: grab-assignment
+description: >-
+  Discover and claim a pending Syntaur assignment from a project (or a
+  standalone one-off). Use when the user wants to start working on a Syntaur
+  assignment, claim a task, or set up their working context.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Grab Assignment
+
+Claim a pending Syntaur assignment and set up the current workspace.
+
+## Input
+
+Expects up to two arguments from the user:
+
+- First (required): the project slug (e.g., `build-auth-system`), OR `--id <uuid>` to claim a standalone assignment at `~/.syntaur/assignments/<uuid>/`.
+- Second (optional, project-nested only): a specific assignment slug to grab. If omitted, list available pending assignments and pick one.
+
+## Pre-flight Check
+
+Check if `.syntaur/context.json` already exists in the current working directory.
+
+- If it exists AND contains BOTH `projectSlug` and `assignmentSlug`, it represents an active assignment. Warn the user: "You already have an active assignment: `<assignmentSlug>` in project `<projectSlug>`. Grabbing a new one will replace this context. Proceed?" — stop if the user says no.
+- If it exists but only has session fields (`sessionId`, `transcriptPath`) and no project/assignment, it was populated by the platform's SessionStart hook (Claude Code, etc.) and does NOT represent an active assignment. Proceed silently and merge assignment fields on top in Step 5.
+
+## Step 1: Discover the Project (project-nested path)
+
+For a project-nested grab, read the project entry files:
+
+- `~/.syntaur/projects/<project-slug>/manifest.md`
+- `~/.syntaur/projects/<project-slug>/project.md`
+
+Note the `workspace` field in `project.md` frontmatter if present. Per-project `agent.md` / `claude.md` were removed in protocol v2.0 — repo-level `CLAUDE.md` / `AGENTS.md` and user playbooks under `~/.syntaur/playbooks/` take their place. Step 7 loads playbooks.
+
+For a standalone grab (`--id <uuid>`), skip this step — there is no parent project.
+
+## Step 2: Find Assignments
+
+List assignment directories:
+
+- Project-nested: `~/.syntaur/projects/<project-slug>/assignments/`
+- Standalone: the single directory at `~/.syntaur/assignments/<uuid>/`
+
+Do NOT filter by status — every assignment is grabbable. If a slug was provided, verify the directory exists. If no specific assignment was requested, read each `assignment.md` frontmatter and present the list with title, priority, and current status (highlighting `pending` as the likely default). Ask the user to choose unless there is exactly one obvious candidate.
+
+## Step 3: Claim the Assignment
+
+```bash
+# Always safe at any status; does not transition state:
+syntaur assign <assignment-slug> --agent <your-agent-name> --project <project-slug>
+```
+
+If the current status is `pending`, also run:
+
+```bash
+syntaur start <assignment-slug> --project <project-slug>
+```
+
+Skip `start` for any non-`pending` status — grabbing must never rewind a `review`, `completed`, or `failed` assignment.
+
+> **Agent identity:** Use an identifier for your agent platform — e.g., `claude`, `cursor`, `codex`, `opencode`.
+
+If either command fails, report the error and stop.
+
+## Step 4: Read Assignment Context and Backfill Workspace
+
+Read the full assignment file. Also read `comments.md` if present (inherited questions / notes). For each `dependsOn` entry, read the dependency's `handoff.md` AND `decision-record.md` so upstream decisions carry forward.
+
+From the assignment frontmatter extract: `title`, `workspace.repository`, `workspace.worktreePath`, `workspace.branch`, `dependsOn`, `priority`.
+
+If `workspace.repository` and `workspace.worktreePath` are both null, set them to the current working directory. Write boundaries use this path, so it must never be null while an agent is writing code.
+
+## Step 5: Create or Merge Context File
+
+Merge assignment context into `.syntaur/context.json`. Never overwrite — if the file already exists (e.g., platform SessionStart hook populated `sessionId` / `transcriptPath`), preserve those fields.
+
+```bash
+mkdir -p .syntaur
+```
+
+Prepare the assignment payload:
+
+```json
+{
+  "projectSlug": "<project-slug or null for standalone>",
+  "assignmentSlug": "<assignment-slug>",
+  "projectDir": "/absolute/path/to/project or null",
+  "assignmentDir": "/absolute/path/to/assignment",
+  "workspaceRoot": "<workspace path or current working directory>",
+  "title": "<assignment title>",
+  "branch": "<workspace.branch or null>",
+  "grabbedAt": "<ISO 8601 timestamp>"
+}
+```
+
+Merge it on top of whatever context.json already contains:
+
+```bash
+if [ -f .syntaur/context.json ]; then
+  jq --slurpfile new <(echo "$NEW_CONTEXT_JSON") '. + $new[0]' .syntaur/context.json > .syntaur/context.json.tmp \
+    && mv .syntaur/context.json.tmp .syntaur/context.json
+else
+  echo "$NEW_CONTEXT_JSON" > .syntaur/context.json
+fi
+```
+
+Use absolute paths (expand `~` to the home directory). If `workspace.repository` is a remote URL (e.g. `https://github.com/...`), set `workspaceRoot` to the current working directory instead.
+
+## Step 6: Register Agent Session (real IDs only — no UUIDs)
+
+`syntaur track-session` requires a `--session-id` from the agent runtime. Synthetic UUIDs are rejected. Source the real id in this order:
+
+1. If `.syntaur/context.json` already has `sessionId` (platform SessionStart hook populated it), use it and the companion `transcriptPath` if present.
+2. Otherwise, fall back to the per-agent lookup:
+   - **Claude Code**: the most-recently-modified `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` — read its `sessionId`. The transcript path is `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` (omit if the file is absent).
+   - **Codex**: the most-recently-modified file under `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` whose first-line `session_meta.payload.cwd` matches `$(pwd)`. Use `payload.id` as the session id and the full rollout path as the transcript path.
+   - **Other agents**: use whatever real session identifier the runtime exposes. Do not invent one.
+3. If no real id can be resolved, stop and tell the user to restart the session so the platform hook can populate it, or to run `/rename <assignment-slug>` (Claude Code) and retry.
+
+After resolving, merge `sessionId` + `transcriptPath` back into context.json. Then register:
+
+```bash
+syntaur track-session \
+  --project <project-slug> --assignment <assignment-slug> \
+  --agent <your-agent-name> \
+  --session-id <real-id> \
+  --transcript-path <path-if-known> \
+  --path $(pwd)
+```
+
+Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path was resolved.
+
+## Step 7: Load Playbooks
+
+Read all playbook files from `~/.syntaur/playbooks/` and treat their content as active behavioral rules:
+
+```bash
+ls ~/.syntaur/playbooks/*.md 2>/dev/null
+```
+
+For each file, read it and follow its directives. Playbooks take precedence over default conventions when they conflict.
+
+## Step 8: Report to User
+
+Summarize:
+- Which assignment was grabbed (slug + title). Note if it was standalone (folder is the UUID, `slug` display-only).
+- Current status (call it out explicitly if the assignment was already past `pending`).
+- The objective (first paragraph from assignment.md body).
+- The acceptance criteria (checkbox list).
+- Active todos from `## Todos`, including any linked plan files.
+- The workspace path.
+- Any inherited comments/questions from `comments.md`.
+- Suggested next step: `plan-assignment` to create an implementation plan.