syntaur 0.1.14 → 0.3.0

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

@@ -1,24 +1,26 @@
 # Syntaur Protocol Summary
 
+Protocol version: **2.0**
+
 ## Directory Structure
 
 ```
 ~/.syntaur/
   config.md
-  missions/
-    <mission-slug>/
+  projects/
+    <project-slug>/
       manifest.md            # Derived: root navigation (read-only)
-      mission.md             # Human-authored: mission overview (read-only)
+      project.md             # Human-authored: project overview (read-only)
       _index-assignments.md  # Derived (read-only)
       _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
-          plan.md            # Agent-writable: implementation plan
+          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,9 +73,13 @@
 ## Key Rules
 
 1. **Assignment frontmatter is the single source of truth** for all assignment state.
-2. **One folder per mission**, one subfolder per assignment.
+2. **Project-nested assignments** live at `projects/<slug>/assignments/<aslug>/` (folder name = slug). **Standalone assignments** live at `assignments/<uuid>/` (folder name = UUID, `project: null`, slug display-only).
 3. **Derived files** (underscore-prefixed) are never edited manually.
 4. **Slugs** are lowercase, 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 — standalone assignments cannot declare `dependsOn`.
 6. An assignment cannot transition from `pending` to `in_progress` while any dependency is not `completed`.
 7. **Playbooks** in `~/.syntaur/playbooks/` define behavioral rules agents must follow. Read `manifest.md` for a summary, then read each referenced playbook before starting work.
+8. **Todos** in the `## Todos` section of `assignment.md` are 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` is also the landing spot for cross-assignment requests via `syntaur request`.
+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. Questions carry a `resolved` flag.
+11. **Cross-assignment work** is requested via `syntaur request <source> <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.

package/platforms/claude-code/skills/complete-assignment/SKILL.md

@@ -17,15 +17,15 @@ Write a handoff for your current assignment and transition it to review (or comp
 
 User provided: $ARGUMENTS
 
-If the user passed `--complete`, transition directly to `completed` instead of `review`. However, `--complete` is ONLY allowed if ALL acceptance criteria are met. If any criteria are unmet, always transition to `review` regardless of the `--complete` flag, and inform the user why.
+If the user passed `--complete`, 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 `--complete` 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 <mission-slug>` first."
+If the file does not exist, tell the user: "No active assignment found. Run `/grab-assignment <project-slug>` first."
 
-Extract: `missionSlug`, `assignmentSlug`, `assignmentDir`, `missionDir`.
+Extract: `projectSlug`, `assignmentSlug`, `assignmentDir`, `projectDir`.
 
 ## Step 1.5: Load Playbooks
 
@@ -37,18 +37,34 @@ ls ~/.syntaur/playbooks/*.md 2>/dev/null
 
 For each file found, read it and check that your work follows its directives. If any playbook has completion-related rules (e.g., "run tests before done"), follow them before proceeding.
 
-## Step 2: Verify Acceptance Criteria
+## Step 2: Verify Acceptance Criteria and Todos
 
-Read `<assignmentDir>/assignment.md` and find the `## Acceptance Criteria` section.
+Read `<assignmentDir>/assignment.md` and find the `## Acceptance Criteria` and `## Todos` sections.
 
-Review each criterion (checkbox item). For each:
-- If you believe it is met, note why (what was implemented, where)
-- If it is NOT met, flag it clearly
+Review each acceptance criterion (checkbox item) and each todo. 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 criteria are not met, warn the user: "The following acceptance criteria are not yet met: [list]. Do you want to proceed with the handoff anyway?"
+Superseded todos (marked `- [x] ~~...~~ (superseded by ...)`) count as resolved — they do not need to be done again.
+
+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?"
 
 If the user says no, stop.
 
+## Step 2.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-chron order) under a new `## <RFC 3339 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.>
+```
+
+Update `progress.md`'s frontmatter: bump `entryCount` and set `updated` to the current timestamp.
+
+Do NOT add a `## Progress` section to `assignment.md` — progress entries live exclusively in `progress.md` as of protocol v2.0.
+
 ## Step 3: Write Handoff Entry
 
 Read `<assignmentDir>/handoff.md` to see its current content and frontmatter.
@@ -82,20 +98,22 @@ Use the Edit tool to append this entry to handoff.md (do not overwrite existing
 
 Also update the handoff.md frontmatter: set `updated` to the current timestamp and increment the `handoffCount` by 1.
 
-## Step 4: Update Acceptance Criteria Checkboxes
+## Step 4: Update Checkboxes (Criteria + Todos)
+
+In `<assignmentDir>/assignment.md`, update checkboxes in both the `## Acceptance Criteria` and `## Todos` sections to reflect the current state. Use the Edit tool to check off items that were completed (change `- [ ]` to `- [x]`).
 
-In `<assignmentDir>/assignment.md`, update the acceptance criteria checkboxes to reflect the current state. Use the Edit tool to check off criteria that were met (change `- [ ]` to `- [x]`).
+**Note:** 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 with a note in the handoff about which were verified at completion time vs. during development.
 
-**Note:** Ideally, criteria 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 with a note in the handoff about which were verified at completion time vs. during development.
+Do NOT uncheck or rewrite superseded todo lines (those matching `- [x] ~~...~~ (superseded by ...)`) — leave that history intact.
 
 ## Step 4.5: Close Session
 
-Read the context file (`.syntaur/context.json`) to get the `sessionId` and `missionSlug`. Then mark the session as completed via the dashboard API:
+Read the context file (`.syntaur/context.json`) to get the `sessionId` and `projectSlug`. Then mark the session as completed via the dashboard API:
 
 ```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", "missionSlug": "<mission-slug>"}'
+  -d '{"status": "completed", "projectSlug": "<project-slug>"}'
 ```
 
 If the API call fails (e.g., dashboard not running), this is non-critical — the session will be reconciled automatically on the next dashboard load.
@@ -105,20 +123,20 @@ If the API call fails (e.g., dashboard not running), this is non-critical — th
 If the user passed `--complete`:
 
 ```bash
-syntaur complete <assignment-slug> --mission <mission-slug>
+syntaur complete <assignment-slug> --project <project-slug>
 ```
 
 Otherwise, transition to review:
 
 ```bash
-syntaur review <assignment-slug> --mission <mission-slug>
+syntaur review <assignment-slug> --project <project-slug>
 ```
 
 Use `dangerouslyDisableSandbox: true` since the CLI writes to `~/.syntaur/`.
 
 If the command fails, report the error. Common failures:
 - Assignment is not in `in_progress` status (cannot transition)
-- Mission not found
+- Project not found
 
 ## Step 6: Clean Up Context
 

package/platforms/claude-code/skills/create-assignment/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: create-assignment
-description: Create a new Syntaur assignment within a mission (or as a one-off)
-argument-hint: <title> --mission <slug> [--priority <level>] [--depends-on <slugs>] [--one-off]
+description: Create a new Syntaur assignment within a project (or as a one-off)
+argument-hint: <title> --project <slug> [--priority <level>] [--depends-on <slugs>] [--type <type>] [--one-off]
 allowed-tools:
   - Bash
   - Read
@@ -9,7 +9,7 @@ allowed-tools:
 
 # Create Assignment
 
-Create a new assignment within a Syntaur mission from Claude Code.
+Create a new assignment within a Syntaur project from Claude Code.
 
 ## Arguments
 
@@ -17,48 +17,51 @@ The user provided: $ARGUMENTS
 
 Parse the arguments:
 - First argument (required): the assignment title (e.g., `"Add login endpoint"`)
-- `--mission <slug>` (required unless `--one-off`): the mission to add the assignment to
-- `--one-off` (optional): create a standalone mission+assignment in one step
+- `--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`. Folder is named by UUID; `slug` is display-only. `--depends-on` is not permitted for standalone assignments.
 - `--slug` (optional): override the auto-generated assignment slug
 - `--priority` (optional): `low`, `medium` (default), `high`, or `critical`
-- `--depends-on` (optional): comma-separated list of assignment slugs this depends on
-- `--dir` (optional): override the default mission directory
+- `--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` (optional, project-nested only): comma-separated list of assignment slugs this depends on
+- `--dir` (optional): override the default project directory
 
 If no title was provided, ask the user what the assignment should be called.
 
-If neither `--mission` nor `--one-off` was provided, check if there is an active assignment context in `.syntaur/context.json`. If so, default `--mission` to that context's `missionSlug` and confirm with the user: "Add this assignment to mission `<missionSlug>`?"
+If neither `--project` nor `--one-off` was provided, check if there is an active assignment context in `.syntaur/context.json`. If so, default `--project` to that context's `projectSlug` and confirm with the user: "Add this assignment to project `<projectSlug>`?"
 
-If there is no active context and no mission flag, ask the user which mission to add it to, or whether it should be a one-off.
+If there is 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. Use `dangerouslyDisableSandbox: true` since the CLI writes to `~/.syntaur/` which is outside the project sandbox.
 
 ```bash
-syntaur create-assignment "<title>" --mission <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--dir <path>]
+syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--type <type>] [--dir <path>]
 ```
 
-Or for one-off:
+Or for one-off (standalone at `~/.syntaur/assignments/<uuid>/`):
 
 ```bash
-syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--dir <path>]
+syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--type <type>] [--dir <path>]
 ```
 
-If the command fails (e.g., mission not found, slug collision), report the error and suggest fixes.
+If the command fails (e.g., project not found, slug collision), report the error and suggest fixes.
 
 ## Step 2: Read the Created Assignment
 
 After successful creation, extract the assignment slug and directory from the CLI output. Read the generated `assignment.md`:
 
 ```bash
-cat ~/.syntaur/missions/<mission-slug>/assignments/<assignment-slug>/assignment.md
+cat ~/.syntaur/projects/<project-slug>/assignments/<assignment-slug>/assignment.md
 ```
 
 ## Step 3: Guide Next Steps
 
 Tell the user:
-- The assignment was created with its slug, priority, and location
-- List the files created (assignment.md, plan.md, scratchpad.md, handoff.md, decision-record.md)
-- Suggest they edit `assignment.md` to fill in the objective, acceptance criteria, and context
-- If dependencies were set, note them
-- Suggest running `/grab-assignment <mission-slug> <assignment-slug>` to claim and start working on it
+- The assignment was created with its slug, priority, type, and location. For standalone assignments, the location is `~/.syntaur/assignments/<uuid>/` — note the UUID (not slug) is the folder name.
+- List the 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 `/plan-assignment`.
+- Remind the user: `progress.md` is where timestamped progress entries go (not `assignment.md`), and `comments.md` is written only via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback`.
+- Suggest they edit `assignment.md` to fill in the objective, acceptance criteria, context, and any initial todos. The `## Todos` section accepts simple tasks or markdown links to plan files.
+- Or suggest running `/plan-assignment` after grabbing — it creates a plan file and auto-appends a linked todo to `## Todos`.
+- If dependencies were set, note them. (Standalone assignments cannot declare dependencies.)
+- Suggest running `/grab-assignment <project-slug> <assignment-slug>` (or `/grab-assignment --id <uuid>` for standalone) to claim and start working on it.

package/platforms/claude-code/skills/grab-assignment/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: grab-assignment
-description: Discover and claim a pending Syntaur assignment from a mission
-argument-hint: <mission-slug> [assignment-slug]
+description: Load a Syntaur assignment into the current working context
+argument-hint: <project-slug> [assignment-slug]
 allowed-tools:
   - Bash
   - Read
@@ -12,86 +12,79 @@ allowed-tools:
 
 # Grab Assignment
 
-Claim a pending assignment from a Syntaur mission and set up your working context.
+Load a Syntaur assignment into the current working context so you can work on it.
+
+**Grabbing is non-destructive.** It never fails because of status. An assignment in `pending`, `in_progress`, `blocked`, `review`, `completed`, or `failed` can all be grabbed — grabbing just sets up context (`.syntaur/context.json`), registers the session, and reads the assignment. Only a `pending` assignment will additionally be transitioned to `in_progress`; any other status is left untouched.
 
 ## Arguments
 
 The user provided: $ARGUMENTS
 
 Parse the arguments:
-- First argument (required): the mission slug (e.g., `build-auth-system`)
-- Second argument (optional): a specific assignment slug to grab. If omitted, you will list pending assignments and pick one.
+- First argument (required): the project slug (e.g., `build-auth-system`)
+- Second argument (optional): a specific assignment slug to grab. If omitted, you will list the project's assignments and pick one (preferring `pending` when multiple exist).
 
 ## Pre-flight Check
 
 1. Check if `.syntaur/context.json` already exists in the current working directory.
-   - If it exists, read it and warn the user: "You already have an active assignment: `<assignmentSlug>` in mission `<missionSlug>`. Grabbing a new assignment will replace this context. Proceed?"
+   - If it exists, read it and warn the user: "You already have an active assignment: `<assignmentSlug>` in project `<projectSlug>`. Grabbing a new assignment will replace this context. Proceed?"
    - If the user says no, stop.
 
-## Step 1: Discover the Mission
+## Step 1: Discover the Project
 
-Read the mission directory to understand what is available:
+Read the project directory to understand what is available:
 
 ```bash
-ls ~/.syntaur/missions/<mission-slug>/
+ls ~/.syntaur/projects/<project-slug>/
 ```
 
-Read the mission files, starting with the manifest (the protocol-defined entry point):
-- Read `~/.syntaur/missions/<mission-slug>/manifest.md` first (root navigation file per protocol spec)
-- Read `~/.syntaur/missions/<mission-slug>/mission.md` for goal and context
-- Read `~/.syntaur/missions/<mission-slug>/agent.md` for agent instructions
-- Read `~/.syntaur/missions/<mission-slug>/claude.md` if it exists for Claude-specific instructions
-
-Note the `workspace` field in `mission.md` frontmatter if present. This indicates which project/codebase grouping the mission belongs to. When writing context to `.syntaur/context.json` (Step 5), include `"workspace": "<value>"` if the mission has a workspace.
+Read the project files, starting with the manifest (the protocol-defined entry point):
+- Read `~/.syntaur/projects/<project-slug>/manifest.md` first (root navigation file per protocol spec)
+- Read `~/.syntaur/projects/<project-slug>/project.md` for goal and context
+- Read `~/.syntaur/projects/<project-slug>/agent.md` for agent instructions
+- Read `~/.syntaur/projects/<project-slug>/claude.md` if it exists for Claude-specific instructions
 
-## Step 2: Find Pending Assignments
+Note the `workspace` field in `project.md` frontmatter if present. This indicates which project/codebase grouping the project belongs to. When writing context to `.syntaur/context.json` (Step 5), include `"workspace": "<value>"` if the project has a workspace.
 
-List assignment directories and check their status:
-
-```bash
-ls ~/.syntaur/missions/<mission-slug>/assignments/
-```
+## Step 2: Find Assignments
 
-For each assignment directory, read the `assignment.md` frontmatter and look for `status: pending`. You can use grep:
+List assignment directories:
 
 ```bash
-grep -l "status: pending" ~/.syntaur/missions/<mission-slug>/assignments/*/assignment.md
+ls ~/.syntaur/projects/<project-slug>/assignments/
 ```
 
-If no pending assignments exist, tell the user and stop.
-
-If the user specified an assignment slug as the second argument, verify it exists and is pending. If it is not pending, report its current status and stop.
+If the user specified an assignment slug as the second argument, verify that directory exists. Its status does **not** matter — grab it regardless. If it doesn't exist, report that and stop.
 
-If no specific assignment was requested, present the list of pending assignments with their titles and priorities, and ask the user which one to grab. If there is only one pending assignment, grab it automatically.
+If no specific assignment was requested, read each `assignment.md` frontmatter and present the list with title, priority, and current status. Prefer `pending` assignments when presenting options (they're the most likely default), but show non-terminal assignments too so the user can pick one to resume. Ask the user which to grab unless there is exactly one obvious candidate (single `pending` assignment).
 
 ## Step 3: Claim the Assignment
 
-Run the Syntaur CLI commands to assign and start the assignment. Use `dangerouslyDisableSandbox: true` for these bash commands since the CLI writes to `~/.syntaur/` which is outside the project sandbox.
+Read the assignment frontmatter first to learn its current `status`:
 
 ```bash
-syntaur assign <assignment-slug> --agent claude --mission <mission-slug>
+cat ~/.syntaur/projects/<project-slug>/assignments/<assignment-slug>/assignment.md
 ```
 
-Then:
+Then run the Syntaur CLI to set the assignee. This is safe at any status and does not transition state. Use `dangerouslyDisableSandbox: true` for these bash commands since the CLI writes to `~/.syntaur/` which is outside the project sandbox.
 
 ```bash
-syntaur start <assignment-slug> --mission <mission-slug>
+syntaur assign <assignment-slug> --agent claude --project <project-slug>
 ```
 
-If either command fails, report the error and stop. Common failures:
-- Assignment has unmet dependencies (cannot start until dependencies are `completed`)
-- Assignment is not in `pending` status
-- Mission not found
-
-## Step 4: Read Assignment Context and Set Workspace
-
-After successfully starting the assignment, read the full assignment details:
+**Only if the current status is `pending`**, also run `syntaur start` to transition it to `in_progress`:
 
 ```bash
-cat ~/.syntaur/missions/<mission-slug>/assignments/<assignment-slug>/assignment.md
+syntaur start <assignment-slug> --project <project-slug>
 ```
 
-Extract from the frontmatter:
+For any other status (`in_progress`, `blocked`, `review`, `completed`, `failed`), **skip `syntaur start`** — the assignment has already been advanced past pending and grabbing should not rewind it. Tell the user which status the assignment is in and continue with context setup.
+
+If `syntaur assign` fails (e.g., project not found, invalid slug), report the error and stop. Do not treat a non-pending status as a failure.
+
+## Step 4: Read Assignment Context and Set Workspace
+
+You have already read the assignment file in Step 3. Extract from the frontmatter:
 - `title` -- the assignment title
 - `workspace.repository` -- the code repository path (may be null)
 - `workspace.worktreePath` -- the worktree path (may be null)
@@ -99,7 +92,15 @@ Extract from the frontmatter:
 - `dependsOn` -- list of dependency slugs
 - `priority` -- priority level
 
-Read the objective and acceptance criteria from the markdown body.
+Read the objective, acceptance criteria, and the `## Todos` section (if present) from the markdown body. Active (unchecked) todos indicate outstanding work and may link to plan files to execute.
+
+### Auto-load upstream decision records
+
+If `dependsOn` is non-empty, for each dependency slug `<dep>`, read:
+- `<projectDir>/assignments/<dep>/handoff.md` (if it exists) for integration context
+- `<projectDir>/assignments/<dep>/decision-record.md` (if it exists) for upstream decisions
+
+Surface those upstream decisions in the Step 6 report — downstream work should inherit prior decisions without the user having to ask.
 
 ### Set workspace if not configured
 
@@ -124,10 +125,10 @@ Then write the JSON file with this structure:
 
 ```json
 {
-  "missionSlug": "<mission-slug>",
+  "projectSlug": "<project-slug>",
   "assignmentSlug": "<assignment-slug>",
-  "missionDir": "/Users/<username>/.syntaur/missions/<mission-slug>",
-  "assignmentDir": "/Users/<username>/.syntaur/missions/<mission-slug>/assignments/<assignment-slug>",
+  "projectDir": "/Users/<username>/.syntaur/projects/<project-slug>",
+  "assignmentDir": "/Users/<username>/.syntaur/projects/<project-slug>/assignments/<assignment-slug>",
   "workspaceRoot": "<workspace.worktreePath if set, else workspace.repository if it is a local path, else current working directory>",
   "title": "<assignment title>",
   "branch": "<workspace.branch or null>",
@@ -141,7 +142,7 @@ Use absolute paths (expand `~` to the actual home directory). Note: `workspace.r
 
 ## Step 5.5: Register Agent Session
 
-After creating the context file, register this session in the mission's agent session log so it appears in the dashboard.
+After creating the context file, register this session in the project's agent session log so it appears in the dashboard.
 
 1. Find the current Claude Code session ID by reading from `~/.claude/sessions/`. These are JSON files keyed by PID containing `sessionId`, `cwd`, etc. Find the most recently modified file whose `cwd` matches the current working directory:
 ```bash
@@ -153,7 +154,7 @@ If you cannot find a matching session file (e.g., no file matches the cwd, or th
 
 2. Run the track-session command (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
 ```bash
-syntaur track-session --mission <missionSlug> --assignment <assignmentSlug> --agent claude --session-id <claude-session-id> --path $(pwd)
+syntaur track-session --project <projectSlug> --assignment <assignmentSlug> --agent claude --session-id <claude-session-id> --path $(pwd)
 ```
 
 3. Update the `.syntaur/context.json` context file to include the session ID. Add `"sessionId": "<claude-session-id>"` to the JSON object you wrote in Step 5.
@@ -174,7 +175,13 @@ If no playbook files exist, skip this step.
 
 Summarize what was done:
 - Which assignment was grabbed
+- Its current status (note if it was already past `pending` — e.g., "already in `review`, status unchanged")
 - The objective (first paragraph from assignment.md body)
 - The acceptance criteria (the checkbox list)
+- Active todos from the `## Todos` section (if any), with links to any referenced plan files
 - The workspace path (if set)
-- Suggest next step: "Run `/plan-assignment` to create an implementation plan."
+- Suggest an appropriate next step based on status:
+  - `pending` / `in_progress`: `/plan-assignment` to plan implementation
+  - `blocked`: investigate the blocker recorded in `blockedReason`
+  - `review`: inspect the implementation and help verify acceptance criteria
+  - `completed` / `failed`: read the handoff; grab is probably for reference or reopen

package/platforms/claude-code/skills/plan-assignment/SKILL.md

@@ -23,13 +23,13 @@ Optional notes from the user: $ARGUMENTS
 
 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 <mission-slug>` first to claim an assignment."
+If the file does not exist, tell the user: "No active assignment found. Run `/grab-assignment <project-slug>` first to claim an assignment."
 
 Extract from the context file:
-- `missionSlug` -- the mission slug
+- `projectSlug` -- the project slug
 - `assignmentSlug` -- the assignment slug
 - `assignmentDir` -- absolute path to the assignment folder
-- `missionDir` -- absolute path to the mission folder
+- `projectDir` -- absolute path to the project folder
 - `workspaceRoot` -- absolute path to the workspace (may be null)
 
 ## Step 1.5: Load Playbooks
@@ -47,12 +47,12 @@ For each file found, read it and follow its directives. Playbooks may contain ru
 Read the following files to understand the assignment:
 
 1. Read `<assignmentDir>/assignment.md` -- extract the objective, acceptance criteria, context section, and any Q&A
-2. Read `<missionDir>/agent.md` -- extract conventions and boundaries
-3. Read `<missionDir>/claude.md` if it exists -- extract Claude-specific instructions
-4. Read `<missionDir>/mission.md` -- extract the mission goal for broader context
+2. Read `<projectDir>/agent.md` -- extract conventions and boundaries
+3. Read `<projectDir>/claude.md` if it exists -- extract Claude-specific instructions
+4. Read `<projectDir>/project.md` -- extract the project goal for broader context
 
 If the assignment has dependencies (`dependsOn` in frontmatter), read the handoff.md from each dependency's assignment folder for integration context:
-- `<missionDir>/assignments/<dep-slug>/handoff.md`
+- `<projectDir>/assignments/<dep-slug>/handoff.md`
 
 ## Step 3: Explore Workspace (if set)
 
@@ -72,9 +72,32 @@ If `workspaceRoot` is null, skip this step and note in the plan that no workspac
 
 ## Step 4: Write the Plan
 
-Read the existing `<assignmentDir>/plan.md` to see its current frontmatter structure. Preserve the YAML frontmatter fields (`assignment`, `status`, `created`, `updated`) and update the `updated` timestamp. Change the `status` field from `draft` to `in_progress` if it is still `draft`.
+Plans are versioned. The first plan for an assignment is `plan.md`; subsequent plans are `plan-v2.md`, `plan-v3.md`, etc. Each plan gets a linked entry in the `## Todos` section of `assignment.md`, and any prior active plan todo is marked superseded (never deleted).
 
-Replace the markdown body with a detailed implementation plan. The plan should include:
+### 4a. Determine the next plan filename
+
+Use Glob to list `<assignmentDir>/plan*.md`. Then:
+
+- If no plan files exist, the target is `plan.md` and the version label is "plan".
+- If `plan.md` exists but no `plan-v<N>.md`, the target is `plan-v2.md` and the version label is "plan v2".
+- Otherwise, pick the smallest `N >= 2` such that `plan-v<N>.md` does not exist. The version label is `plan v<N>`.
+
+Remember this `planFilename` and `versionLabel` for the remaining substeps.
+
+### 4b. Write the plan file
+
+Write `<assignmentDir>/<planFilename>` with standard plan frontmatter:
+
+```yaml
+---
+assignment: <assignmentSlug>
+status: draft
+created: "<nowTimestamp>"
+updated: "<nowTimestamp>"
+---
+```
+
+Then the markdown body should include:
 
 1. **Overview** -- one paragraph summarizing the approach
 2. **Tasks** -- numbered list of implementation tasks, each with:
@@ -86,7 +109,31 @@ Replace the markdown body with a detailed implementation plan. The plan should i
 4. **Risks and Open Questions** -- anything that might block or complicate implementation
 5. **Testing Strategy** -- how to verify the implementation works
 
-Write the plan using the Edit tool to update `<assignmentDir>/plan.md`. Preserve the existing frontmatter and replace only the body content.
+**Decision capture:** While planning, note any meaningful choices you make (library picks, schema design, architectural calls, rejected alternatives). Record each as a numbered entry in `<assignmentDir>/decision-record.md` with the format `## Decision N: <short title>` — fields: Status (proposed/accepted), Context, Decision, Consequences. Downstream assignments that depend on this one auto-load these decisions during `/grab-assignment`, so they pay off over time.
+
+If the target file already exists (only possible for `plan.md` on first re-run against a scaffolded-but-empty plan), preserve the frontmatter and replace only the body, flipping `status` from `draft` to `in_progress` and updating `updated`.
+
+### 4c. Update assignment.md Todos
+
+Read `<assignmentDir>/assignment.md` and locate the `## Todos` section.
+
+1. **Supersede prior plan todos.** Scan unchecked todo lines for any that match the pattern `- [ ] Execute [<label>](./plan.md)` or `- [ ] Execute [<label>](./plan-v<N>.md)`. For each match, rewrite the line as:
+
+   ```
+   - [x] ~~Execute [<label>](./<old-plan-filename>)~~ (superseded by <versionLabel>)
+   ```
+
+   Never delete the old line — preserve history.
+
+2. **Append the new plan todo.** Append a new line to the end of the `## Todos` section:
+
+   ```
+   - [ ] Execute [<versionLabel>](./<planFilename>)
+   ```
+
+3. **Missing section fallback.** If the `## Todos` section does not exist (legacy assignment predating this convention), insert it immediately after `## Acceptance Criteria` with a short guidance HTML comment followed by the new todo line. Match the template used by `/create-assignment`.
+
+Also update the assignment frontmatter `updated` timestamp.
 
 ## Step 5: Report to User