syntaur 0.3.3 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {
@@ -29,7 +29,11 @@
     ".agents",
     "platforms",
     "examples",
-    "dashboard/dist"
+    "dashboard/dist",
+    "statusline",
+    "vendor/syntaur-skills/skills/**",
+    "vendor/syntaur-skills/LICENSE",
+    "vendor/syntaur-skills/README.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -40,7 +44,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "prepack": "node scripts/verify-vendored-skills.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'"
   },
@@ -48,6 +54,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.4.2",
     "better-sqlite3": "^11.0.0",
     "chokidar": "^4.0.0",
     "commander": "^13.0.0",

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

@@ -5,9 +5,5 @@
     "name": "Brennen",
     "email": ""
   },
-  "version": "0.1.8",
-  "statusLine": {
-    "type": "command",
-    "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/statusline.sh"
-  }
+  "version": "0.1.8"
 }

package/platforms/claude-code/agents/syntaur-expert.md

@@ -12,10 +12,12 @@ When answering questions, read the actual source files rather than relying solel
 
 ## Key Source Files
 
-- **Protocol summary:** `${CLAUDE_PLUGIN_ROOT}/references/protocol-summary.md`
+- **Protocol summary:** `${CLAUDE_PLUGIN_ROOT}/references/protocol-summary.md` (or `~/.claude/skills/syntaur-protocol/references/protocol-summary.md` for the installed skill version)
 - **File ownership:** `${CLAUDE_PLUGIN_ROOT}/references/file-ownership.md`
 - **Plugin manifest:** `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`
-- **Skills:** `${CLAUDE_PLUGIN_ROOT}/skills/`
+- **Protocol skills (installed by `syntaur install-plugin`):** `~/.claude/skills/{syntaur-protocol,grab-assignment,plan-assignment,complete-assignment,create-assignment,create-project}/`
+- **Protocol skills source (vendored via submodule):** `<syntaur-repo>/vendor/syntaur-skills/skills/` — standalone repo at https://github.com/prong-horn/syntaur-skills
+- **Slash commands (ship in plugin):** `${CLAUDE_PLUGIN_ROOT}/commands/` — thin wrappers that invoke the corresponding installed skill
 - **Hooks:** `${CLAUDE_PLUGIN_ROOT}/hooks/`
 
 For the live CLI surface, run `syntaur --help` in the user environment.
@@ -204,28 +206,38 @@ The Syntaur Claude Code plugin is installed by `syntaur install-plugin`, which r
 ```
 plugin/
   .claude-plugin/
-    plugin.json              # Plugin metadata
+    plugin.json                         # Plugin metadata
   agents/
-    syntaur-expert.md        # This agent
-  skills/
-    syntaur-protocol/SKILL.md    # Core protocol rules (background)
-    grab-assignment/SKILL.md     # Claim a pending assignment
-    create-project/SKILL.md      # Create new project
-    create-assignment/SKILL.md   # Create new assignment
-    plan-assignment/SKILL.md     # Write implementation plan
-    complete-assignment/SKILL.md # Handoff and complete
+    syntaur-expert.md                   # This agent
   commands/
-    track-session/track-session.md  # Register tmux sessions
+    grab-assignment/grab-assignment.md         # Slash wrapper for grab-assignment skill
+    plan-assignment/plan-assignment.md         # Slash wrapper for plan-assignment skill
+    complete-assignment/complete-assignment.md # Slash wrapper for complete-assignment skill
+    create-assignment/create-assignment.md     # Slash wrapper for create-assignment skill
+    create-project/create-project.md           # Slash wrapper for create-project skill
+    track-session/track-session.md             # Claude-specific session registration
+    doctor-syntaur/...                         # Diagnose install
+    track-server/...                           # Register a running server
   hooks/
-    hooks.json                   # Hook definitions
-    session-start.sh             # Merge real session_id + transcript_path into existing .syntaur/context.json
-    session-cleanup.sh           # Mark sessions stopped on exit
-    enforce-boundaries.sh        # Write boundary enforcement
+    hooks.json                  # Hook definitions
+    session-start.sh            # Merge real session_id + transcript_path into existing .syntaur/context.json
+    session-cleanup.sh          # Mark sessions stopped on exit
+    enforce-boundaries.sh       # Write boundary enforcement
   references/
-    protocol-summary.md          # One-page protocol quick reference
-    file-ownership.md            # Write boundary rules
+    protocol-summary.md         # One-page protocol quick reference
+    file-ownership.md           # Write boundary rules
+
+~/.claude/skills/               # Installed by `syntaur install-plugin` (vendored from syntaur-skills repo)
+  syntaur-protocol/SKILL.md     # Auto-activates on Syntaur file contexts
+  grab-assignment/SKILL.md
+  plan-assignment/SKILL.md
+  complete-assignment/SKILL.md
+  create-assignment/SKILL.md
+  create-project/SKILL.md
 ```
 
+Slash commands (`/grab-assignment` etc.) are thin wrappers that delegate to the installed skills. This lets the same protocol skills work in Claude Code (via slash command + auto-activation) and Codex (via auto-activation only).
+
 ### Skills Summary
 
 | Skill | Trigger | Purpose |

package/platforms/claude-code/commands/complete-assignment/complete-assignment.md

@@ -0,0 +1,20 @@
+---
+name: complete-assignment
+description: Append a progress entry + handoff and transition the current Syntaur assignment to review or completed
+arguments:
+  - name: args
+    description: "Optional — see the complete-assignment skill for supported flags"
+    required: false
+---
+
+# /complete-assignment
+
+Thin wrapper that invokes the `complete-assignment` skill. The skill lives in `~/.claude/skills/complete-assignment/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — verifying acceptance criteria and todos, appending a progress.md entry, writing a handoff.md section, and calling `syntaur review` or `syntaur complete`.
+
+## Instructions
+
+Invoke the `complete-assignment` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/commands/create-assignment/create-assignment.md

@@ -0,0 +1,20 @@
+---
+name: create-assignment
+description: Create a new Syntaur assignment (project-nested or standalone one-off)
+arguments:
+  - name: args
+    description: "Title and flags. See the create-assignment skill for supported forms (e.g. --project <slug>, --one-off, --type <type>)."
+    required: false
+---
+
+# /create-assignment
+
+Thin wrapper that invokes the `create-assignment` skill. The skill lives in `~/.claude/skills/create-assignment/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — picking project-nested or standalone, validating the type, scaffolding assignment.md / progress.md / comments.md.
+
+## Instructions
+
+Invoke the `create-assignment` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/commands/create-project/create-project.md

@@ -0,0 +1,20 @@
+---
+name: create-project
+description: Create a new Syntaur project with full scaffolding
+arguments:
+  - name: args
+    description: "Title and optional flags (--slug, --dir, --workspace). See the create-project skill for full usage."
+    required: false
+---
+
+# /create-project
+
+Thin wrapper that invokes the `create-project` skill. The skill lives in `~/.claude/skills/create-project/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — calling `syntaur create-project`, reading the generated project.md, and guiding next steps.
+
+## Instructions
+
+Invoke the `create-project` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/commands/grab-assignment/grab-assignment.md

@@ -0,0 +1,20 @@
+---
+name: grab-assignment
+description: Claim a Syntaur assignment and load it into the current working context
+arguments:
+  - name: args
+    description: "Project slug and optional assignment slug, or --id <uuid> for standalone. See the grab-assignment skill for full forms."
+    required: false
+---
+
+# /grab-assignment
+
+Thin wrapper that invokes the `grab-assignment` skill. The skill lives in `~/.claude/skills/grab-assignment/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — discovering pending assignments, merging `.syntaur/context.json`, registering the agent session, reading the assignment.
+
+## Instructions
+
+Invoke the `grab-assignment` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/commands/plan-assignment/plan-assignment.md

@@ -0,0 +1,20 @@
+---
+name: plan-assignment
+description: Create a detailed implementation plan for the current Syntaur assignment
+arguments:
+  - name: args
+    description: "Optional — see the plan-assignment skill for supported flags"
+    required: false
+---
+
+# /plan-assignment
+
+Thin wrapper that invokes the `plan-assignment` skill. The skill lives in `~/.claude/skills/plan-assignment/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — picking the next `plan-v<N>.md`, writing it, appending a `## Todos` entry, marking any prior plan todo superseded, and recording key decisions in `decision-record.md`.
+
+## Instructions
+
+Invoke the `plan-assignment` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/statusline/statusline.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# Syntaur statusline for Claude Code.
+#
+# Reads JSON from stdin per Claude Code's statusLine contract and renders a
+# user-configurable single line composed of the segments listed in
+#   $HOME/.syntaur/statusline.config.json
+# with shape:
+#   { "segments": ["wrap","git","assignment","model","ctx","session"],
+#     "separator": " · ",
+#     "wrap": "/optional/path/to/inner-statusline.sh" }
+#
+# Available segments:
+#   wrap       stdout of an external script (composes another statusline)
+#   git        repo:branch (+ dirty marker + ahead/behind counts)
+#   assignment active syntaur assignment (project/slug or standalone/uuid — title)
+#   session    Claude session id, last 8 chars prefixed by "…"
+#   model      Claude model display name
+#   ctx        context window fill bar, e.g. "ctx:[####------] 42%"
+#   cwd        basename of the current working directory
+#
+# If the config file is absent, falls back to a sensible default set.
+# Never fails the terminal — always exits 0.
+
+set -o pipefail 2>/dev/null || true
+
+INPUT=$(cat)
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf '%s' '(syntaur: jq missing)'
+  exit 0
+fi
+
+CONFIG_FILE="$HOME/.syntaur/statusline.config.json"
+# Fall back to a simple one-line conf file for backward compat with earlier
+# install-statusline versions that only stored a wrap target.
+LEGACY_CONF="$HOME/.syntaur/statusline.conf"
+
+# --- Load config ---
+SEGMENTS_RAW=""
+SEPARATOR=" · "
+WRAP_PATH=""
+
+if [ -f "$CONFIG_FILE" ]; then
+  SEGMENTS_RAW=$(jq -r '(.segments // []) | join(",")' "$CONFIG_FILE" 2>/dev/null)
+  SEP_FROM_CONF=$(jq -r '.separator // empty' "$CONFIG_FILE" 2>/dev/null)
+  [ -n "$SEP_FROM_CONF" ] && SEPARATOR="$SEP_FROM_CONF"
+  WRAP_PATH=$(jq -r '.wrap // empty' "$CONFIG_FILE" 2>/dev/null)
+fi
+
+# Env var always takes precedence for wrap (useful for testing).
+[ -n "$SYNTAUR_STATUSLINE_WRAP" ] && WRAP_PATH="$SYNTAUR_STATUSLINE_WRAP"
+
+# Legacy conf: first non-empty, non-comment line is wrap path.
+if [ -z "$WRAP_PATH" ] && [ -f "$LEGACY_CONF" ]; then
+  WRAP_PATH=$(awk 'NF && !/^#/{print; exit}' "$LEGACY_CONF" 2>/dev/null)
+fi
+
+# Default segment set if none configured.
+if [ -z "$SEGMENTS_RAW" ]; then
+  # Default: include wrap as leading segment only if a wrap path is set.
+  if [ -n "$WRAP_PATH" ]; then
+    SEGMENTS_RAW="wrap,git,assignment,session"
+  else
+    SEGMENTS_RAW="git,assignment,session"
+  fi
+fi
+
+# --- Extract stdin fields ---
+SESSION_ID=""
+CWD=""
+MODEL=""
+USED_PCT=""
+
+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)
+  MODEL=$(printf '%s' "$INPUT" | jq -r '.model.display_name // empty' 2>/dev/null)
+  USED_PCT=$(printf '%s' "$INPUT" | jq -r '.context_window.used_percentage // empty' 2>/dev/null)
+fi
+
+[ -z "$CWD" ] && CWD="$PWD"
+
+# --- Compute each available segment value (cheap, unconditional). ---
+
+# wrap
+WRAP_SEG=""
+if [ -n "$WRAP_PATH" ] && [ -r "$WRAP_PATH" ]; then
+  if command -v timeout >/dev/null 2>&1; then
+    WRAP_SEG=$(printf '%s' "$INPUT" | timeout 2 bash "$WRAP_PATH" 2>/dev/null)
+  else
+    WRAP_SEG=$(printf '%s' "$INPUT" | bash "$WRAP_PATH" 2>/dev/null)
+  fi
+  # Take last non-empty line (collapse to single row).
+  WRAP_SEG=$(printf '%s' "$WRAP_SEG" | tr -d '\r' | awk 'NF{line=$0} END{print line}' 2>/dev/null)
+fi
+
+# git — repo:branch[*] +ahead -behind
+GIT_SEG=""
+if [ -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
+
+    DIRTY=""
+    if ! git --no-optional-locks -C "$CWD" diff --quiet 2>/dev/null \
+       || ! git --no-optional-locks -C "$CWD" diff --cached --quiet 2>/dev/null; then
+      DIRTY="*"
+    fi
+
+    AHEAD_BEHIND=""
+    UPSTREAM=$(git --no-optional-locks -C "$CWD" rev-parse --abbrev-ref --symbolic-full-name "@{u}" 2>/dev/null)
+    if [ -n "$UPSTREAM" ]; then
+      AHEAD=$(git --no-optional-locks -C "$CWD" rev-list --count "$UPSTREAM..HEAD" 2>/dev/null)
+      BEHIND=$(git --no-optional-locks -C "$CWD" rev-list --count "HEAD..$UPSTREAM" 2>/dev/null)
+      [ "${AHEAD:-0}" -gt 0 ] 2>/dev/null  && AHEAD_BEHIND=" +${AHEAD}"
+      [ "${BEHIND:-0}" -gt 0 ] 2>/dev/null && AHEAD_BEHIND="${AHEAD_BEHIND} -${BEHIND}"
+    fi
+
+    if [ -n "$BRANCH" ]; then
+      GIT_SEG="${REPO}:${BRANCH}${DIRTY}${AHEAD_BEHIND}"
+    else
+      GIT_SEG="$REPO"
+    fi
+  fi
+fi
+
+# assignment — project/slug — title  (or standalone/uuid-prefix — title)
+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
+
+# session — last 8 chars
+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
+
+# model
+MODEL_SEG=""
+[ -n "$MODEL" ] && MODEL_SEG="$MODEL"
+
+# ctx — fill bar
+CTX_SEG=""
+if [ -n "$USED_PCT" ]; then
+  USED_INT=$(printf "%.0f" "$USED_PCT" 2>/dev/null || echo "$USED_PCT")
+  if [ -n "$USED_INT" ] && [ "$USED_INT" -ge 0 ] 2>/dev/null; then
+    FILLED=$(( USED_INT / 10 ))
+    [ "$FILLED" -gt 10 ] && FILLED=10
+    EMPTY=$(( 10 - FILLED ))
+    BAR=""
+    i=0
+    while [ "$i" -lt "$FILLED" ]; do BAR="${BAR}#"; i=$((i+1)); done
+    i=0
+    while [ "$i" -lt "$EMPTY" ];  do BAR="${BAR}-"; i=$((i+1)); done
+    CTX_SEG="ctx:[${BAR}] ${USED_INT}%"
+  fi
+fi
+
+# cwd — basename
+CWD_SEG=""
+[ -n "$CWD" ] && CWD_SEG=$(basename "$CWD")
+
+# --- Emit the selected segments in order ---
+OUT=""
+# Split SEGMENTS_RAW on commas using IFS.
+OLD_IFS="$IFS"
+IFS=','
+for name in $SEGMENTS_RAW; do
+  IFS="$OLD_IFS"
+  # Trim whitespace
+  name=$(printf '%s' "$name" | awk '{$1=$1; print}')
+  value=""
+  case "$name" in
+    wrap)       value="$WRAP_SEG" ;;
+    git)        value="$GIT_SEG" ;;
+    assignment) value="$ASSIGNMENT_SEG" ;;
+    session)    value="$SESSION_SEG" ;;
+    model)      value="$MODEL_SEG" ;;
+    ctx)        value="$CTX_SEG" ;;
+    cwd)        value="$CWD_SEG" ;;
+    *)          value="" ;;
+  esac
+  if [ -n "$value" ]; then
+    if [ -z "$OUT" ]; then
+      OUT="$value"
+    else
+      OUT="${OUT}${SEPARATOR}${value}"
+    fi
+  fi
+  IFS=','
+done
+IFS="$OLD_IFS"
+
+printf '%s' "$OUT"
+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`.