syntaur 0.2.0 → 0.3.3

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

@@ -9,9 +9,10 @@ Your job is to work fluently within the Syntaur protocol without breaking owners
 
 ## Primary Responsibilities
 
-- Create projects and assignments with the `syntaur` CLI
+- Create projects and assignments (project-nested or standalone) with the `syntaur` CLI
 - Claim assignments and establish local assignment context
-- Keep `assignment.md`, active plan files (`plan.md`, `plan-v2.md`, ...), and `handoff.md` accurate during execution
+- Keep `assignment.md`, active plan files (`plan.md`, `plan-v2.md`, ...), `progress.md`, and `handoff.md` accurate during execution
+- Record questions/notes/feedback via `syntaur comment` and route cross-assignment work via `syntaur request`
 - Track Codex sessions for the Syntaur dashboard
 - Set up Codex adapter instructions in the active workspace
 - Enforce Syntaur write boundaries and lifecycle rules
@@ -20,34 +21,35 @@ Your job is to work fluently within the Syntaur protocol without breaking owners
 
 When a task involves Syntaur:
 
-1. Determine whether the user needs project creation, assignment creation, assignment execution, completion/handoff, or session tracking.
+1. Determine whether the user needs project creation, assignment creation (project-nested or `--one-off` standalone), assignment execution, completion/handoff, or session tracking.
 2. If `.syntaur/context.json` exists in the current working directory, read it first.
 3. If working on a specific assignment, read these in order:
-   - `<projectDir>/manifest.md`
-   - `<projectDir>/agent.md`
-   - `<projectDir>/project.md`
-   - `<projectDir>/claude.md` if it exists
-   - `<assignmentDir>/assignment.md`
+   - `<projectDir>/manifest.md` (project-nested assignments only)
+   - `<projectDir>/project.md` (project-nested assignments only)
+   - `<assignmentDir>/assignment.md` — frontmatter now includes `project: <slug> | null` and `type: <classification> | null`
    - any `<assignmentDir>/plan*.md` files linked from active todos in the `## Todos` section
+   - `<assignmentDir>/progress.md` (if present) — reverse-chron progress log
+   - `<assignmentDir>/comments.md` (if present) — threaded questions/notes/feedback
    - `<assignmentDir>/handoff.md`
 4. Resolve the workspace boundary from `.syntaur/context.json` or `assignment.md` frontmatter before editing code.
 
+Project-nested assignments live at `~/.syntaur/projects/<slug>/assignments/<aslug>/`. Standalone assignments live at `~/.syntaur/assignments/<uuid>/` — folder named by UUID, `project: null`, `slug` display-only.
+
 ## File Ownership
 
 ### Never write
 
 - `project.md`
-- `agent.md`
-- `claude.md`
 - `manifest.md`
 - any underscore-prefixed derived file such as `_index-assignments.md`, `_status.md`, `resources/_index.md`, or `memories/_index.md`
-- other agents' assignment folders
+- other agents' assignment folders, except via CLI-mediated channels
 
-### You may write
+### You may write directly
 
 - the current assignment folder only:
   - `assignment.md`
   - `plan*.md` (0 or more versioned plan files, e.g., `plan.md`, `plan-v2.md`)
+  - `progress.md` (append timestamped entries, newest first — replaces the old `## Progress` section)
   - `scratchpad.md`
   - `handoff.md`
   - `decision-record.md`
@@ -56,23 +58,30 @@ When a task involves Syntaur:
 - `.syntaur/context.json` in the current working directory
 - source files inside the assignment workspace boundary
 
+### Write only via CLI (never edit directly)
+
+- `comments.md` (any assignment) — use `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`. Never edit directly. Questions carry a `resolved` flag toggled in the dashboard.
+- Another assignment's `## Todos` section — use `syntaur request <source> <target> "text"` to append a todo annotated `(from: <source>)`.
+
 ## Protocol Rules
 
-- Assignment frontmatter is the single source of truth for assignment state.
-- Slugs are lowercase and hyphen-separated.
+- Assignment frontmatter is the single source of truth for assignment state. `project` is the containing project slug (`null` for standalone); `type` is a classification validated against `config.md` `types.definitions` when present.
+- Slugs are lowercase and hyphen-separated. Standalone assignment folders are named by UUID; `slug` is display-only in that case.
 - `pending` with unmet `dependsOn` means structural waiting. `blocked` means a real runtime obstacle and requires a `blockedReason`.
+- `dependsOn` is only valid between assignments within the same project — standalone assignments cannot declare dependencies.
 - Update acceptance criteria and `## Todos` checkboxes as work lands.
+- Append timestamped entries to `progress.md` (not to `assignment.md`) after meaningful milestones.
 - When requirements shift, supersede the prior plan todo instead of rewriting the old plan file.
-- Keep the `## Progress` section in `assignment.md` current after meaningful milestones.
 - Append handoffs instead of replacing previous handoff entries.
+- Record questions via `syntaur comment ... --type question` — they roll up into `_status.md`'s `openQuestions` counter.
 
 ## CLI Reference
 
 Use these commands directly when needed:
 
 - `syntaur create-project "<title>" [--slug <slug>] [--dir <path>]`
-- `syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--dir <path>]`
-- `syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--dir <path>]`
+- `syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--type <type>] [--dir <path>]`
+- `syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--type <type>] [--dir <path>]` — creates standalone at `~/.syntaur/assignments/<uuid>/`
 - `syntaur setup [--yes] [--claude] [--codex] [--claude-dir <path>] [--codex-dir <path>] [--codex-marketplace-path <path>] [--dashboard]`
 - `syntaur assign <assignment-slug> --agent codex --project <project-slug>`
 - `syntaur start <assignment-slug> --project <project-slug>`
@@ -81,8 +90,10 @@ Use these commands directly when needed:
 - `syntaur block <assignment-slug> --project <project-slug> --reason <text>`
 - `syntaur unblock <assignment-slug> --project <project-slug>`
 - `syntaur fail <assignment-slug> --project <project-slug>`
+- `syntaur comment <assignment-slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>] [--project <slug>]` — append to `comments.md`
+- `syntaur request <target-slug-or-uuid> "text" [--from <source>] [--project <slug>]` — append to target's `## Todos`, annotated `(from: <source>)`
 - `syntaur uninstall [--all] [--yes]`
-- `syntaur track-session --project <project-slug> --assignment <assignment-slug> --agent codex --session-id <id> --path <cwd>`
+- `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>`
 
 ## Standard Workflows
@@ -92,9 +103,11 @@ Use these commands directly when needed:
 1. Discover the project and pending assignments.
 2. Run `syntaur assign ... --agent codex`.
 3. Run `syntaur start ...`.
-4. Create `.syntaur/context.json` in the working directory.
-5. Register the session with `syntaur track-session`.
-6. If needed, run `syntaur setup-adapter codex --project <slug> --assignment <slug>`.
+4. Create (or merge into) `.syntaur/context.json` in the working directory. If a prior context file exists, preserve its fields.
+5. Resolve the real Codex session id and rollout path: `bash ./scripts/resolve-session.sh "$(pwd)"` (relative to the plugin root). Parse `session_id=<id>` and `transcript_path=<abs path>`. If the helper exits non-zero, there is no matching Codex rollout in this cwd — start the Codex session first, then retry. Never `uuidgen`.
+6. Merge `sessionId` + `transcriptPath` into `.syntaur/context.json`.
+7. Register the session: `syntaur track-session --project <slug> --assignment <slug> --agent codex --session-id <id> --transcript-path <path> --path "$(pwd)"`.
+8. If needed, run `syntaur setup-adapter codex --project <slug> --assignment <slug>`.
 
 ### Plan an assignment
 
@@ -109,10 +122,11 @@ Use these commands directly when needed:
 
 1. Re-check every acceptance criterion.
 2. Update any missing checkboxes in `assignment.md`.
-3. Append a new structured handoff entry to `handoff.md`.
-4. Mark the dashboard session completed if `sessionId` exists.
-5. Transition the assignment with `syntaur review` or `syntaur complete`.
-6. Remove `.syntaur/context.json` when the assignment is no longer active.
+3. Append a final timestamped entry to `progress.md` summarizing the work.
+4. Append a new structured handoff entry to `handoff.md`.
+5. Mark the dashboard session completed if `sessionId` exists.
+6. Transition the assignment with `syntaur review` or `syntaur complete`.
+7. Remove `.syntaur/context.json` when the assignment is no longer active.
 
 ## Decision Rules
 

package/platforms/codex/references/file-ownership.md

@@ -7,8 +7,6 @@ Agents must never modify these files:
 | File | Location |
 |------|----------|
 | `project.md` | `<project>/project.md` |
-| `agent.md` | `<project>/agent.md` |
-| `claude.md` | `<project>/claude.md` |
 
 ## Agent-Writable (Your Assignment Folder Only)
 
@@ -18,11 +16,24 @@ You may only write to files inside your assigned assignment folder:
 |------|---------|
 | `assignment.md` | Assignment record and source of truth for state (includes `## Todos` checklist) |
 | `plan*.md` | Versioned implementation plans (optional, 0 or more: `plan.md`, `plan-v2.md`, ...) — each linked from a todo in `assignment.md` |
+| `progress.md` | Append-only timestamped progress log (newest first). Replaces the old `## Progress` body section. |
 | `scratchpad.md` | Working notes |
 | `handoff.md` | Append-only handoff log |
 | `decision-record.md` | Append-only decision log |
 
-Path pattern: `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+Path pattern (project-nested): `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+Path pattern (standalone): `~/.syntaur/assignments/<your-assignment-uuid>/`
+
+## CLI-Mediated Shared-Writable
+
+Do not edit these files directly. Use the listed CLI commands:
+
+| File | Mediator |
+|------|----------|
+| `comments.md` (any assignment) | `syntaur comment <slug-or-uuid> "body" [--type question\|note\|feedback] [--reply-to <id>]` |
+| `## Todos` in another assignment's `assignment.md` (cross-assignment request) | `syntaur request <source> <target> "text"` |
+
+These are bounded exceptions to the single-writer rule.
 
 ## Shared-Writable
 

package/platforms/codex/references/protocol-summary.md

@@ -1,5 +1,7 @@
 # Syntaur Protocol Summary
 
+Protocol version: **2.0**
+
 ## Directory Structure
 
 ```
@@ -13,12 +15,12 @@
       _index-plans.md        # Derived (read-only)
       _index-decisions.md    # Derived (read-only)
       _status.md             # Derived (read-only)
-      claude.md              # Human-authored: Claude-specific instructions (read-only)
-      agent.md               # Human-authored: universal agent instructions (read-only)
       assignments/
         <assignment-slug>/
           assignment.md      # Agent-writable: source of truth for state (includes ## Todos checklist)
           plan*.md           # Agent-writable: versioned implementation plans (optional, 0 or more: plan.md, plan-v2.md, ...)
+          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 handoff log
           decision-record.md # Agent-writable: append-only decision log
@@ -28,6 +30,15 @@
       memories/
         _index.md            # Derived (read-only)
         <memory-slug>.md     # Shared-writable
+  assignments/
+    <assignment-id>/         # Standalone assignments — folder named by UUID, `project: null`
+      assignment.md          # Same schema as project-nested, `slug` is display-only
+      plan*.md
+      progress.md
+      comments.md
+      scratchpad.md
+      handoff.md
+      decision-record.md
   playbooks/
     manifest.md              # Derived: playbook listing (read-only)
     <slug>.md                # User-authored: behavioral rules for agents
@@ -62,10 +73,13 @@
 ## Key Rules
 
 1. Assignment frontmatter is the single source of truth for assignment state.
-2. One folder per project and one subfolder per assignment.
+2. Project-nested assignments live at `projects/<slug>/assignments/<aslug>/` (folder = slug). Standalone assignments live at `assignments/<uuid>/` (folder = UUID, `project: null`, slug display-only).
 3. Derived files are never edited manually.
 4. Slugs are lowercase and hyphen-separated.
-5. Dependencies are declared via `dependsOn` in assignment frontmatter.
+5. Dependencies are declared via `dependsOn` in assignment frontmatter. Only valid within the same project.
 6. An assignment cannot transition from `pending` to `in_progress` while any dependency is not `completed`.
-7. The `## Todos` section in `assignment.md` is an informal markdown checklist. Items may be simple tasks or link to plan files. When a plan is superseded, mark the old todo: `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete it.
+7. The `## Todos` section in `assignment.md` is an informal markdown checklist. Items may be simple tasks or link to plan files. When a plan is superseded, mark the old todo: `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete it. `## Todos` also receives cross-assignment requests via `syntaur request`.
 8. Playbooks in `~/.syntaur/playbooks/` define behavioral rules agents must follow. Read `manifest.md` for a summary, then read each referenced playbook before starting work.
+9. Progress is appended to `progress.md` as timestamped entries (newest first). Do not add a `## Progress` section to `assignment.md`.
+10. Comments are appended to `comments.md` via `syntaur comment <slug> "body" [--type question|note|feedback] [--reply-to <id>]`. Never edit `comments.md` directly.
+11. Cross-assignment work is requested via `syntaur request <source> <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.

package/platforms/codex/scripts/resolve-session.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Syntaur Codex resolve-session helper
+# Finds the most-recent Codex rollout file whose session_meta.payload.cwd
+# matches $1 (default $PWD) and emits two lines to stdout:
+#   session_id=<id>
+#   transcript_path=<absolute path>
+# Exits non-zero with nothing on stdout if no match.
+#
+# Override the search root via CODEX_SESSIONS_DIR (default: $HOME/.codex/sessions).
+# Known limitation: if multiple concurrent Codex sessions share the same cwd,
+# this picks the newest-by-mtime. Users can bypass by passing --session-id and
+# --transcript-path explicitly to `syntaur track-session`.
+
+set -o pipefail 2>/dev/null || true
+
+command -v jq >/dev/null 2>&1 || { exit 1; }
+
+TARGET_CWD="${1:-$PWD}"
+SESSIONS_ROOT="${CODEX_SESSIONS_DIR:-$HOME/.codex/sessions}"
+
+shopt -s nullglob 2>/dev/null || true
+
+# Expand the glob explicitly via bash. If no files match, `files` stays empty
+# and we exit without invoking ls — guards against `ls -1t` falling back to
+# listing the current directory when the glob strips to zero operands.
+files=("$SESSIONS_ROOT"/*/*/*/rollout-*.jsonl)
+[ "${#files[@]}" -eq 0 ] && exit 1
+
+MATCHED_FILE=""
+MATCHED_ID=""
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  FIRST=$(head -n 1 "$f" 2>/dev/null)
+  [ -z "$FIRST" ] && continue
+  SESSION_CWD=$(printf '%s' "$FIRST" | jq -r 'select(.type=="session_meta") | .payload.cwd // empty' 2>/dev/null)
+  SESSION_ID=$(printf '%s' "$FIRST" | jq -r 'select(.type=="session_meta") | .payload.id // empty' 2>/dev/null)
+  if [ "$SESSION_CWD" = "$TARGET_CWD" ] && [ -n "$SESSION_ID" ]; then
+    MATCHED_FILE="$f"
+    MATCHED_ID="$SESSION_ID"
+    break
+  fi
+done < <(ls -1t "${files[@]}" 2>/dev/null)
+
+[ -z "$MATCHED_FILE" ] && exit 1
+
+printf 'session_id=%s\n' "$MATCHED_ID"
+printf 'transcript_path=%s\n' "$MATCHED_FILE"
+exit 0

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

@@ -17,6 +17,7 @@ If the user passed `--complete`, transition directly to `completed` only when al
 
 1. Read `.syntaur/context.json`. If it does not exist, tell the user there is no active assignment.
 2. Read `<assignmentDir>/assignment.md` and evaluate every item in the `## Acceptance Criteria` section AND every item in the `## Todos` section. Superseded todos (marked `- [x] ~~...~~ (superseded by ...)`) count as resolved. If any acceptance criterion is unmet OR any todo is still `- [ ]` and not superseded, warn the user before proceeding.
+2.5. Append a final entry to `<assignmentDir>/progress.md` (reverse-chron, newest first) under a new `## <ISO 8601 timestamp>` heading summarizing the final state of the work. Bump `entryCount` and `updated` in the frontmatter. Do NOT add a `## Progress` section to `assignment.md` — progress entries live exclusively in `progress.md` as of protocol v2.0.
 3. Read `<assignmentDir>/handoff.md` and append a new handoff entry using the protocol format:
 
 ```markdown

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

@@ -15,10 +15,11 @@ Parse:
 
 - First positional argument: assignment title
 - `--project <slug>` required unless `--one-off`
-- `--one-off` optional
+- `--one-off` optional — creates a **standalone** assignment at `~/.syntaur/assignments/<uuid>/` with `project: null`. Folder named by UUID; `slug` is display-only. `--depends-on` is not permitted for standalone assignments.
 - `--slug <slug>` optional
 - `--priority <level>` optional, default `medium`
-- `--depends-on <slug[,slug...]>` optional
+- `--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)
 - `--dir <path>` optional
 
 If no title was provided, ask the user for it.
@@ -28,17 +29,21 @@ If neither `--project` nor `--one-off` was provided, look for `.syntaur/context.
 ## Workflow
 
 1. Run one of:
-   - `syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--dir <path>]`
-   - `syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--dir <path>]`
+   - `syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--type <type>] [--dir <path>]`
+   - `syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--type <type>] [--dir <path>]`
 2. If the command fails, report the error and stop.
 3. Read the generated `assignment.md`.
 4. Summarize:
-   - assignment slug
-   - project slug
+   - assignment slug (for standalone assignments, also report the UUID — the folder is named by UUID, not slug)
+   - project slug (or `null` for standalone)
    - priority
+   - type
    - location
-   - created files: `assignment.md`, `scratchpad.md`, `handoff.md`, `decision-record.md` (plan files are NOT scaffolded — they are created on demand by `plan-assignment`)
-5. Suggest next steps:
+   - created files: `assignment.md`, `progress.md`, `comments.md`, `scratchpad.md`, `handoff.md`, `decision-record.md` (plan files are NOT scaffolded — they are created on demand by `plan-assignment`)
+5. Remind the user:
+   - Progress entries go into `progress.md` via direct appends (not into `assignment.md`).
+   - Comments are appended via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback` — never edit `comments.md` directly.
+6. Suggest next steps:
    - fill in the objective, context, acceptance criteria, and any initial todos in the `## Todos` section
    - or run `plan-assignment` to create a plan file and auto-append a linked todo to `## Todos`
    - run `grab-assignment` to claim it if work should begin now

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

@@ -38,7 +38,7 @@ Parse:
    - **Only if current status is `pending`**: `syntaur start <assignment-slug> --project <project-slug>` to transition it to `in_progress`. Skip this command for any other status — grabbing must not rewind a `review`, `completed`, or `failed` assignment.
    If `syntaur assign` fails (e.g., project not found, invalid slug), report and stop. Do not treat a non-pending status as a failure.
 7. If the assignment has no workspace configured, set `workspace.repository` and `workspace.worktreePath` to the current working directory so write boundaries are meaningful.
-8. Create `.syntaur/context.json` in the current working directory with:
+8. Create or merge `.syntaur/context.json` in the current working directory. If the file already exists, preserve its contents and layer the new assignment fields on top (never overwrite):
 
 ```json
 {
@@ -50,13 +50,15 @@ Parse:
   "title": "<assignment title>",
   "branch": "<workspace.branch or null>",
   "grabbedAt": "<ISO 8601 timestamp>",
-  "sessionId": "<uuid>"
+  "sessionId": "<real-codex-session-id>",
+  "transcriptPath": "<absolute path to the matching rollout jsonl>"
 }
 ```
 
-9. Register the agent session:
-   - generate a UUID
-   - run `syntaur track-session --project <project-slug> --assignment <assignment-slug> --agent codex --session-id <uuid> --path <cwd>`
+9. Register the agent session using the REAL Codex session id and rollout path — never synthesize a UUID:
+   - Resolve both by running the plugin-shipped helper: `bash ./scripts/resolve-session.sh "$(pwd)"` (script lives at `platforms/codex/scripts/resolve-session.sh`; referenced via the same relative path used by other Codex hooks in `hooks.json`). Parse the two output lines: `session_id=<id>` and `transcript_path=<abs path>`. If the helper exits non-zero, stop and report "no matching Codex rollout for this cwd — aborting registration. Start a Codex session in this cwd first."
+   - Merge `sessionId` + `transcriptPath` into `.syntaur/context.json` (use `jq '. + {sessionId:$sid, transcriptPath:$tp}'` to preserve existing fields).
+   - Run: `syntaur track-session --project <project-slug> --assignment <assignment-slug> --agent codex --session-id <id> --transcript-path <path> --path <cwd>`
 10. Summarize:
    - assignment slug and title
    - current status (call it out if the assignment was already past `pending` — e.g., "already in `review`, status unchanged")

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

@@ -16,10 +16,14 @@ Optional notes from the user: `$ARGUMENTS`
 1. Read `.syntaur/context.json` from the current working directory. If it does not exist, tell the user to claim an assignment first.
 2. Read:
    - `<assignmentDir>/assignment.md`
-   - `<projectDir>/agent.md`
-   - `<projectDir>/claude.md` if it exists
+   - `<assignmentDir>/comments.md` (if it exists — inherited questions / notes)
    - `<projectDir>/project.md`
-3. If the assignment depends on other assignments, read each dependency handoff for integration context.
+   - `<projectDir>/manifest.md`
+
+   Per-project `agent.md` / `claude.md` were removed in v0.2.0. Repo-level
+   `CLAUDE.md` / `AGENTS.md` and `~/.syntaur/playbooks/` take their place;
+   read playbooks via `ls ~/.syntaur/playbooks/*.md`.
+3. If the assignment depends on other assignments, read each dependency's `handoff.md` AND `decision-record.md` for upstream integration context and accepted decisions.
 4. Explore `workspaceRoot` when it exists:
    - inspect project structure
    - find likely implementation files
@@ -54,4 +58,4 @@ After writing the plan:
 - summarize the number of tasks and key decisions
 - call out open questions or risks
 - note which plan filename was written and which prior plan (if any) was superseded
-- remind yourself to keep `assignment.md` progress, acceptance criteria, and todos current during implementation
+- remind yourself to keep `assignment.md` acceptance criteria + todos current during implementation, append milestones to `progress.md` (not `assignment.md`), and record comments via `syntaur comment <slug-or-uuid> "body" --type note|question|feedback`

package/platforms/codex/skills/syntaur-protocol/SKILL.md

@@ -11,26 +11,34 @@ You are working within the Syntaur protocol. Follow these rules at all times.
 
 Respect file ownership boundaries.
 
-### Files you may write
+### Files you may write directly
 
 1. Your assignment folder only:
    - `assignment.md`
    - `plan*.md` (0 or more versioned plan files, e.g., `plan.md`, `plan-v2.md`)
+   - `progress.md` (append timestamped entries, newest first; replaces the old `## Progress` body section)
    - `scratchpad.md`
    - `handoff.md`
    - `decision-record.md`
+   - Path (project-nested): `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+   - Path (standalone): `~/.syntaur/assignments/<your-assignment-uuid>/` — folder named by UUID, `project: null`, `slug` display-only
 2. Project-level shared files:
    - `~/.syntaur/projects/<project>/resources/<slug>.md`
    - `~/.syntaur/projects/<project>/memories/<slug>.md`
 3. Workspace files inside the assignment's configured workspace root
 4. `.syntaur/context.json` in the current working directory
 
+### Files written only via CLI
+
+- `comments.md` (any assignment) — use `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`. Never edit directly.
+- Another assignment's `## Todos` section — use `syntaur request <target> "text"` to append a todo annotated `(from: <source>)`.
+
 ### Files you must never write
 
-1. `project.md`, `agent.md`, `claude.md`
+1. `project.md`
 2. `manifest.md`
 3. Any file prefixed with `_`
-4. Other agents' assignment folders
+4. Other agents' assignment folders (except via the CLI-mediated channels above)
 5. Anything outside the current workspace boundary
 
 ## Current Assignment Context
@@ -48,17 +56,17 @@ If `.syntaur/context.json` exists in the current working directory, read it befo
 
 When you are working on an existing assignment, read these in order:
 
-1. `<projectDir>/manifest.md`
-2. `<projectDir>/agent.md`
-3. `<projectDir>/project.md`
-4. `<projectDir>/claude.md` if it exists
-5. `<assignmentDir>/assignment.md`
-6. any `<assignmentDir>/plan*.md` files linked from active todos in the `## Todos` section
+1. `<projectDir>/manifest.md` (project-nested assignments only)
+2. `<projectDir>/project.md` (project-nested assignments only)
+3. `<assignmentDir>/assignment.md` — frontmatter now includes `project: <slug> | null` and `type: <classification> | null`
+4. any `<assignmentDir>/plan*.md` files linked from active todos in the `## Todos` section
+5. `<assignmentDir>/progress.md` (if present)
+6. `<assignmentDir>/comments.md` (if present)
 7. `<assignmentDir>/handoff.md`
 
 ## Lifecycle Commands
 
-Use the `syntaur` CLI for state transitions:
+Use the `syntaur` CLI for state transitions and coordination:
 
 - `syntaur assign <slug> --agent <name> --project <project>`
 - `syntaur start <slug> --project <project>`
@@ -67,6 +75,9 @@ Use the `syntaur` CLI for state transitions:
 - `syntaur block <slug> --project <project> --reason <text>`
 - `syntaur unblock <slug> --project <project>`
 - `syntaur fail <slug> --project <project>`
+- `syntaur create-assignment "<title>" [--type <type>] [--project <slug> | --one-off]`
+- `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`
+- `syntaur request <target> "text" [--from <source>]`
 
 ## Troubleshooting
 
@@ -74,12 +85,14 @@ If Syntaur state looks inconsistent (missing files, stale manifests, unexpected
 
 ## Conventions
 
-- Assignment frontmatter is the single source of truth.
-- Slugs are lowercase and hyphen-separated.
+- Assignment frontmatter is the single source of truth. `project` is the containing project slug (`null` for standalone); `type` is a classification validated against `config.md` `types.definitions` when present.
+- Slugs are lowercase and hyphen-separated. For standalone assignments the folder is named by UUID; `slug` is display-only.
 - Update acceptance criteria and `## Todos` checkboxes as work lands, not only at the end.
-- Keep the `## Progress` section in `assignment.md` current after meaningful milestones.
+- Append timestamped entries to `progress.md` after meaningful milestones. Do NOT add a `## Progress` section to `assignment.md`.
+- Record questions/notes/feedback via `syntaur comment` — never edit `comments.md` directly. Do NOT set status to blocked for questions.
 - When requirements shift, supersede the prior plan todo (`- [x] ~~...~~ (superseded by plan-v<N>)`) instead of rewriting the old plan file.
 - Write handoffs with enough context for another agent or human to continue cleanly.
+- Use `syntaur request` to route work to another assignment.
 
 ## References
 

package/dashboard/dist/assets/channel-DdltvFFH.js

@@ -1 +0,0 @@
-import{aq as o,ar as n}from"./mermaid.core-C9pF_oFQ.js";const t=(r,a)=>o.lang.round(n.parse(r)[a]);export{t as c};

package/dashboard/dist/assets/classDiagram-VBA2DB6C-BHqdFE-8.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-WL4C6EOR-C7jE3-cR.js";import{_ as i}from"./mermaid.core-C9pF_oFQ.js";import"./chunk-FMBD7UC4-CLuJnd1b.js";import"./chunk-JSJVCQXG-B4d62qWV.js";import"./chunk-55IACEB6-6HmWguiO.js";import"./chunk-KX2RTZJC-AsEKRPq2.js";import"./index-yyAIuzrP.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dashboard/dist/assets/classDiagram-v2-RAHNMMFH-BHqdFE-8.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-WL4C6EOR-C7jE3-cR.js";import{_ as i}from"./mermaid.core-C9pF_oFQ.js";import"./chunk-FMBD7UC4-CLuJnd1b.js";import"./chunk-JSJVCQXG-B4d62qWV.js";import"./chunk-55IACEB6-6HmWguiO.js";import"./chunk-KX2RTZJC-AsEKRPq2.js";import"./index-yyAIuzrP.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dashboard/dist/assets/clone-CBJOOeOm.js

@@ -1 +0,0 @@
-import{b as r}from"./_baseUniq-CTxTc4MS.js";var e=4;function a(o){return r(o,e)}export{a as c};