syntaur 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {
@@ -28,13 +28,11 @@
     "bin",
     ".agents",
     "platforms",
+    "skills",
+    ".claude-plugin",
     "examples",
     "dashboard/dist",
-    "statusline",
-    "scripts/postinstall-submodules.mjs",
-    "vendor/syntaur-skills/skills/**",
-    "vendor/syntaur-skills/LICENSE",
-    "vendor/syntaur-skills/README.md"
+    "statusline"
   ],
   "scripts": {
     "build": "tsup",
@@ -45,9 +43,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepack": "node scripts/verify-vendored-skills.mjs",
+    "mirror-skills": "node scripts/mirror-skills-to-platforms.mjs",
+    "prepack": "node scripts/mirror-skills-to-platforms.mjs",
     "prepublishOnly": "npm run build && npm ci --prefix dashboard && npm run build --prefix dashboard",
-    "postinstall": "node scripts/postinstall-submodules.mjs",
     "try": "node scripts/try.mjs",
     "untry": "npm unlink -g syntaur && npm install -g syntaur@latest && echo '\\n✓ global syntaur restored to latest published version'"
   },

package/platforms/claude-code/.claude-plugin/plugin.json

@@ -1,9 +1,22 @@
 {
   "name": "syntaur",
-  "description": "Syntaur protocol adapter for Claude Code. Provides skills for grabbing, planning, and completing assignments, plus write boundary enforcement via hooks.",
+  "description": "Syntaur protocol adapter for Claude Code. Provides skills for grabbing, planning, and completing assignments, project management, session/server tracking, save-session-summary continuity, plus write boundary enforcement via hooks.",
   "author": {
     "name": "Brennen",
     "email": ""
   },
-  "version": "0.1.8"
+  "version": "0.8.0",
+  "skills": [
+    "./skills/syntaur-protocol",
+    "./skills/grab-assignment",
+    "./skills/plan-assignment",
+    "./skills/complete-assignment",
+    "./skills/create-assignment",
+    "./skills/create-project",
+    "./skills/manage-statuses",
+    "./skills/clear-assignment",
+    "./skills/save-session-summary",
+    "./skills/track-session",
+    "./skills/track-server"
+  ]
 }

package/{vendor/syntaur-skills → platforms/claude-code}/skills/complete-assignment/SKILL.md

@@ -63,8 +63,6 @@ Do NOT add a `## Progress` section to `assignment.md` — progress entries live
 
 ## Step 4: Write Handoff Entry
 
-`handoff.md` is the **assignment-level cross-ticket outbound** doc — written here, at completion, for the next ticket / agent / human reviewer. It is NOT the mid-assignment session continuity artifact; that lives at `<assignmentDir>/sessions/<sid>/summary.md` and is written by `/save-session-summary`. Any `sessions/*/summary.md` files are reference-only at completion time and MUST NOT be deleted — they remain as immutable historical context.
-
 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:

package/{vendor/syntaur-skills → platforms/claude-code}/skills/grab-assignment/SKILL.md

@@ -69,11 +69,7 @@ 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. (`handoff.md` is the **cross-ticket outbound** doc — distinct from session continuity.)
-
-If `<assignmentDir>/sessions/` exists, also read the most recent `<assignmentDir>/sessions/<sid>/summary.md` (selected by `summary.md` file mtime). This is the **mid-assignment session continuity** artifact written by `/save-session-summary` at the end of a prior session of the same assignment. Treat its `What's Next` and `Load-Bearing Context` sections as resume context. (Note: in Claude Code, the SessionStart hook also stashes this path into context.json as `latestSessionSummaryPath` — same semantics; either source is fine.)
+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`.
 
@@ -159,5 +155,4 @@ Summarize:
 - Active todos from `## Todos`, including any linked plan files.
 - The workspace path.
 - Any inherited comments/questions from `comments.md`.
-- **Resume context** (if Step 4 found a `sessions/<sid>/summary.md`): a short block citing the session id and the timestamp of that summary's `updated` frontmatter, followed by its `What's Next` bullets. This is mid-assignment continuity — distinct from any cross-ticket handoff.
-- Suggested next step: `plan-assignment` to create an implementation plan, or — if a session summary's `What's Next` is concrete — proceed directly with the next step it names.
+- Suggested next step: `plan-assignment` to create an implementation plan.

package/{vendor/syntaur-skills → platforms/claude-code}/skills/plan-assignment/SKILL.md

@@ -50,9 +50,7 @@ Read these files to understand the assignment:
 
 Per-project `agent.md` / `claude.md` were removed in protocol v2.0. Agent-level conventions now live at the repo root (`CLAUDE.md` / `AGENTS.md`) and in `~/.syntaur/playbooks/` (already loaded in Step 2).
 
-If the assignment has dependencies (`dependsOn` in frontmatter), read each dependency's `handoff.md` AND `decision-record.md` for integration context and upstream decisions. (`handoff.md` is cross-ticket outbound — distinct from session continuity.)
-
-If `<assignmentDir>/sessions/` exists, also read the most recent `sessions/<sid>/summary.md` (selected by `summary.md` file mtime). This is mid-assignment continuity from a prior session of the same assignment — its `What's Next`, `Open Questions`, and `Load-Bearing Context` sections are direct planning inputs when resuming work that was already in flight.
+If the assignment has dependencies (`dependsOn` in frontmatter), read each dependency's `handoff.md` AND `decision-record.md` for integration context and upstream decisions.
 
 ## Step 4: Explore Workspace (if set)
 

package/{vendor/syntaur-skills → platforms/claude-code}/skills/syntaur-protocol/SKILL.md

@@ -26,9 +26,8 @@ Respect file ownership boundaries. The Claude Code and Codex plugins enforce the
    - `plan*.md` (versioned — `plan.md`, `plan-v2.md`, etc.)
    - `progress.md` (append-only, timestamped)
    - `scratchpad.md`
-   - `handoff.md` (append-only — **assignment-level cross-ticket outbound**)
+   - `handoff.md` (append-only)
    - `decision-record.md` (append-only)
-   - `sessions/<sessionId>/summary.md` (**session-scoped mid-assignment continuity** — single document per session id, overwritten on save)
 2. **Project-level shared files:**
    - `~/.syntaur/projects/<project>/resources/<slug>.md`
    - `~/.syntaur/projects/<project>/memories/<slug>.md`
@@ -50,22 +49,6 @@ Respect file ownership boundaries. The Claude Code and Codex plugins enforce the
 
 Per-project `agent.md` / `claude.md` do NOT exist in protocol v2.0. Agent-level conventions now live at the repo root (`CLAUDE.md` / `AGENTS.md`) and in `~/.syntaur/playbooks/`.
 
-## Session Continuity vs Cross-Ticket Handoff
-
-Two related but distinct artifacts. Conflating them is a recurring mistake.
-
-| Artifact | Scope | When written | Audience | Written by |
-|---|---|---|---|---|
-| `handoff.md` | Assignment-level | At completion | The next ticket / agent / human reviewer | `complete-assignment` skill |
-| `sessions/<sessionId>/summary.md` | Session-scoped | Mid-assignment, before compaction or at session end | A future session of the same agent on the same assignment | `save-session-summary` skill |
-
-Rules:
-- One `summary.md` per session id directory; overwrite on every save.
-- Older `sessions/<sid>/summary.md` files accumulate as immutable history — never delete them, even at completion.
-- Resume picks the latest by `summary.md` file mtime. The Claude Code SessionStart hook also stashes that absolute path into `.syntaur/context.json` as `latestSessionSummaryPath` for convenience; either source is fine.
-- Codex has no `PreCompact` hook — Codex agents invoke `/save-session-summary` manually before compaction or session end.
-- `syntaur doctor` intentionally does NOT validate `sessions/` — sessions are optional and absence is not anomalous.
-
 ## Current Assignment Context
 
 If `.syntaur/context.json` exists in the current working directory, read it before making changes. Fields you will see:
@@ -77,7 +60,6 @@ If `.syntaur/context.json` exists in the current working directory, read it befo
 - `workspaceRoot` — absolute path to the code workspace
 - `sessionId` — real agent-runtime session id (never a synthesized UUID)
 - `transcriptPath` — absolute path to the agent's rollout/transcript file, if known
-- `latestSessionSummaryPath` — absolute path to the most recent `sessions/<sid>/summary.md` (Claude Code SessionStart hook resolves this; `null` if none)
 
 ## Required Reading Order
 
@@ -89,9 +71,8 @@ When starting work on an existing assignment, read these in order:
 4. `<assignmentDir>/assignment.md`
 5. `<assignmentDir>/comments.md` if present — inherited questions / notes
 6. Latest `<assignmentDir>/plan*.md` (pick the newest)
-7. `<assignmentDir>/handoff.md` — cross-ticket outbound history (entries from prior agents/humans handing this assignment off)
-8. The latest `<assignmentDir>/sessions/<sid>/summary.md` if present (mid-assignment resume context from a prior session of this assignment) — selected by `summary.md` file mtime, or via `latestSessionSummaryPath` in context.json on Claude Code
-9. For each `dependsOn` entry: the dependency's `handoff.md` AND `decision-record.md` — upstream integration context and accepted decisions carry forward
+7. `<assignmentDir>/handoff.md` — history
+8. For each `dependsOn` entry: the dependency's `handoff.md` AND `decision-record.md` — upstream integration context and accepted decisions carry forward
 
 ## Lifecycle Commands
 
@@ -127,7 +108,7 @@ ls ~/.syntaur/playbooks/*.md 2>/dev/null
 - Append milestones to `progress.md` — do NOT add a `## Progress` section to `assignment.md` (v2.0 moved progress to its own file).
 - `## Todos` in `assignment.md` is an informal markdown checklist. Items may be simple tasks or markdown links to plan files. When a plan is superseded, mark the old todo as `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete. `## Todos` is also the landing spot for cross-assignment `syntaur request` entries.
 - Record questions / notes / feedback via `syntaur comment` — never edit `comments.md` directly. Do NOT set status to `blocked` just because there is an open question; block only for a real external dependency with a `--reason`.
-- Write `handoff.md` entries (via `complete-assignment`) with enough context for another agent or human to continue cleanly **across tickets**. Write `sessions/<sid>/summary.md` (via `/save-session-summary`) for mid-assignment continuity within the same assignment across sessions of the same agent. Do not mix the two. Record decisions in `decision-record.md` with Status / Context / Decision / Consequences — downstream dependents auto-load these during grab.
+- 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.
 
 ## References

package/{vendor/syntaur-skills → platforms/claude-code}/skills/syntaur-protocol/references/file-ownership.md

@@ -22,9 +22,8 @@ You may only write to files inside your currently-claimed assignment folder:
 | `plan*.md` | Versioned implementation plans (`plan.md`, `plan-v2.md`, ...). When superseded, the old plan's todo is marked superseded but the file itself is never deleted. |
 | `progress.md` | Append-only, timestamped progress log (newest first). |
 | `scratchpad.md` | Working notes. |
-| `handoff.md` | Append-only **assignment-level cross-ticket outbound** at completion (written by `complete-assignment`). |
+| `handoff.md` | Append-only handoff log. |
 | `decision-record.md` | Append-only decision log (Status / Context / Decision / Consequences). |
-| `sessions/<session-id>/summary.md` | **Per-session continuity** for resume across sessions of the same agent on this assignment. Single document per session id, overwritten on every save (written by `/save-session-summary`). Not the same as `handoff.md`. |
 
 Path patterns:
 - Project-nested: `~/.syntaur/projects/<project>/assignments/<your-assignment-slug>/`

package/{vendor/syntaur-skills → platforms/claude-code}/skills/syntaur-protocol/references/protocol-summary.md

@@ -22,11 +22,8 @@ Protocol version: **2.0**
           progress.md        # Agent-writable, append-only: timestamped progress log
           comments.md        # CLI-mediated: threaded questions/notes/feedback (via `syntaur comment`)
           scratchpad.md      # Agent-writable: working notes
-          handoff.md         # Agent-writable, append-only: cross-ticket outbound at completion
+          handoff.md         # Agent-writable, append-only: handoff log
           decision-record.md # Agent-writable, append-only: decision log
-          sessions/
-            <session-id>/
-              summary.md     # Agent-writable: per-session continuity (single doc, overwritten)
       resources/
         _index.md            # Derived (read-only)
         <resource-slug>.md   # Shared-writable
@@ -37,7 +34,6 @@ Protocol version: **2.0**
     <assignment-uuid>/       # Standalone assignments: folder = UUID, `project: null`, slug display-only
       assignment.md          # Same schema as project-nested
       plan*.md, progress.md, comments.md, scratchpad.md, handoff.md, decision-record.md
-      sessions/<session-id>/summary.md  # Same per-session continuity as project-nested
   playbooks/
     manifest.md              # Derived: playbook listing (read-only)
     <slug>.md                # User-authored: behavioral rules for agents
@@ -84,4 +80,3 @@ 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.
-13. **Session continuity** (mid-assignment) lives at `sessions/<session-id>/summary.md` inside the assignment dir — one document per session id, overwritten on every save (via `/save-session-summary`). On resume, pick the latest by `summary.md` file mtime; on Claude Code, the SessionStart hook also stashes the absolute path in `.syntaur/context.json` as `latestSessionSummaryPath`. Older summaries accumulate as immutable history; never delete them. This is **distinct from** `handoff.md`, which is the assignment-level cross-ticket outbound at completion. `syntaur doctor` intentionally ignores `sessions/` — sessions are optional. Codex has no `PreCompact` hook event; Codex agents invoke `/save-session-summary` manually before compaction or session end.

package/platforms/claude-code/skills/track-server/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: track-server
+description: Use when the user wants to register, refresh, remove, or list tracked tmux dev-server sessions for the Syntaur dashboard. Triggers on "/track-server", "track this server", "register this dev server", or similar — distinct from /track-session which registers Claude Code agent sessions.
+---
+
+# Track Server
+
+Track tmux sessions so their development servers show up in the Syntaur dashboard. Distinct from `/track-session`, which registers Claude Code agent sessions.
+
+## Arguments
+
+User arguments: `$ARGUMENTS`
+
+Supported forms:
+
+- `<session-name>`
+- `--refresh [session-name]`
+- `--remove <session-name>`
+- `--list`
+
+## Workflow
+
+### Register
+
+1. Verify the tmux session exists with `tmux has-session -t <name>`.
+2. If it does not exist, list available sessions with `tmux list-sessions -F '#{session_name}'`.
+3. Create `~/.syntaur/servers/<sanitized-name>.md` with frontmatter:
+
+```yaml
+---
+session: <original-name>
+registered: <ISO timestamp>
+last_refreshed: <ISO timestamp>
+---
+```
+
+4. Tell the user the session is now tracked.
+
+### Refresh
+
+1. Update `last_refreshed` for the named session, or for every file in `~/.syntaur/servers/` when no name was provided.
+
+### Remove
+
+1. Delete `~/.syntaur/servers/<sanitized-name>.md`.
+
+### List
+
+1. List all tracked session markdown files and show the `session` field from each.

package/platforms/codex/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "syntaur",
-  "version": "0.1.8",
-  "description": "Run Syntaur project and assignment workflows from Codex, including claiming work, planning, completing handoffs, session tracking, and write-boundary enforcement.",
+  "version": "0.8.0",
+  "description": "Run Syntaur project and assignment workflows from Codex, including claiming work, planning, completing handoffs, session/server tracking, save-session-summary continuity, and write-boundary enforcement.",
   "author": {
     "name": "Brennen"
   },

package/platforms/codex/skills/clear-assignment/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: clear-assignment
+description: >-
+  Clear the active Syntaur assignment from the current session without
+  transitioning lifecycle state. Use when the user wants to drop, release,
+  unclaim, abandon, or clear assignment context — e.g., "clear my assignment",
+  "drop this assignment", "release context", "unclaim this", "I'm not actually
+  working on this anymore". Does not mark the assignment complete or failed.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Clear Assignment
+
+Drop the active assignment binding from the current workspace. The assignment itself is left untouched in `~/.syntaur/projects/.../assignments/` — only the local `.syntaur/context.json` pointer is cleared so the session is no longer scoped to it.
+
+This is the inverse of `grab-assignment`. Unlike `complete-assignment`, it does **not** transition lifecycle state, write a handoff, or close out the work. Use it when:
+
+- The user grabbed the wrong assignment.
+- The user wants to switch focus without finishing or formally reviewing the current one.
+- Session context was set up earlier and is now stale.
+
+If the assignment is actually done, use `complete-assignment` instead so a handoff is recorded and the lifecycle state advances.
+
+## Input
+
+Optional flags from the user:
+
+- `--keep-session` — preserve `sessionId` / `transcriptPath` fields in `context.json` (just strip the assignment fields). Default: full delete.
+- `--unassign` — also run `syntaur unassign <slug> --project <project>` so the assignment is no longer claimed by this agent. Default: leave the claim in place (only the local context is cleared). Skip this flag if the CLI does not support `unassign` in the installed version — fall back to leaving the claim alone and tell the user.
+
+## 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 context to clear." and stop.
+- If the file exists but contains only session fields (`sessionId`, `transcriptPath`) and no `projectSlug` / `assignmentSlug`, tell the user: "No active assignment is bound — only a platform session record exists. Nothing to clear." and stop (unless they explicitly ask to wipe the session record too).
+
+Otherwise extract: `projectSlug`, `assignmentSlug`, `assignmentDir`, `title`.
+
+## Step 2: Confirm with the User
+
+Show the user what is about to be cleared and confirm before touching anything:
+
+> About to clear active assignment context:
+> - Assignment: `<assignmentSlug>` — <title>
+> - Project: `<projectSlug>` (or "standalone" if null)
+> - The assignment itself will NOT be transitioned. Its lifecycle status stays as-is.
+> - Proceed?
+
+Stop if the user says no.
+
+If lifecycle status is `in_progress` and the user has not passed `--complete-instead`, also note:
+
+> Note: this assignment is currently `in_progress`. Clearing context does not change that. If you actually finished it, run `complete-assignment` instead so a handoff is recorded.
+
+## Step 3 (optional): Unassign
+
+If the user passed `--unassign`, run:
+
+```bash
+syntaur unassign <assignment-slug> --project <project-slug>
+```
+
+For standalone assignments use the UUID (the folder name) in place of the slug, and omit `--project`.
+
+If the CLI rejects the command (older versions may not implement `unassign`), report the error and continue — the local context clear in Step 4 still happens.
+
+## Step 4: Clear the Context File
+
+Default behavior — delete the file entirely:
+
+```bash
+rm .syntaur/context.json
+```
+
+If the user passed `--keep-session`, preserve session fields and strip everything else instead:
+
+```bash
+jq '{sessionId, transcriptPath} | with_entries(select(.value != null))' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+If the resulting file would be empty (`{}`), delete it instead of leaving an empty stub.
+
+Do not delete the `.syntaur/` directory itself — other tooling may use it.
+
+## Step 5: Close Session (optional)
+
+If the original `context.json` included a `sessionId` and the Syntaur dashboard is running, mark the session as cleared so the dashboard does not keep showing it as active:
+
+```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":"cleared","projectSlug":"<project-slug>"}'
+```
+
+If this fails (e.g., dashboard not running, endpoint not present in the installed version), it is non-critical — silently continue.
+
+Skip this step entirely when `--keep-session` is set.
+
+## Step 6: Report to User
+
+Summarize:
+- Which assignment was cleared (slug + title).
+- That its lifecycle status is unchanged (and what that status currently is, if known from frontmatter).
+- Whether the assignment was unassigned via the CLI or the claim was left in place.
+- Suggested next step: `grab-assignment` to claim a different one, or `complete-assignment` if the previous one was actually finished.

package/platforms/codex/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/platforms/codex/skills/create-assignment/SKILL.md

@@ -0,0 +1,73 @@
+---
+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.2.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
+- `--with-todos` (optional): scaffold a `## Todos` section in `assignment.md`. **Omit unless the user explicitly asks for it.** Todos are normally a plan (added by `plan-assignment`) or populated during planning — not something to pre-create at assignment time. Pass this flag only if the user explicitly says something like "include todos", "with a todo list", "scaffold todos", etc.
+
+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>] [--with-todos]
+```
+
+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>] [--with-todos]
+```
+
+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, and context. A `## Todos` section is **not** scaffolded by default — it is added automatically by `plan-assignment` (linking the new plan file) or by `syntaur request` (cross-assignment requests). Only the `--with-todos` flag pre-scaffolds an empty `## Todos` section.
+- 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.