syntaur 0.3.3 → 0.4.1

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

@@ -1,156 +0,0 @@
----
-name: plan-assignment
-description: Create an implementation plan for the current Syntaur assignment
-argument-hint: "[focus area or notes]"
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
----
-
-# Plan Assignment
-
-Create a detailed implementation plan for your current Syntaur assignment.
-
-## Arguments
-
-Optional notes from the user: $ARGUMENTS
-
-## 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 <project-slug>` first to claim an assignment."
-
-Extract from the context file:
-- `projectSlug` -- the project slug
-- `assignmentSlug` -- the assignment slug
-- `assignmentDir` -- absolute path to the assignment folder
-- `projectDir` -- absolute path to the project folder
-- `workspaceRoot` -- absolute path to the workspace (may be null)
-
-## Step 1.5: Load Playbooks
-
-Read all playbook files from `~/.syntaur/playbooks/` — these contain user-defined behavioral rules you must follow:
-
-```bash
-ls ~/.syntaur/playbooks/*.md 2>/dev/null
-```
-
-For each file found, read it and follow its directives. Playbooks may contain rules about planning conventions, required steps, or quality expectations that apply to this plan.
-
-## Step 2: Read Assignment Details
-
-Read the following files to understand the assignment:
-
-1. Read `<assignmentDir>/assignment.md` -- extract the objective, acceptance criteria, context section, and the `## Todos` list
-2. Read `<assignmentDir>/comments.md` if it exists -- inherited questions, notes, and feedback
-3. Read `<projectDir>/project.md` -- extract the project goal for broader context
-4. Read `<projectDir>/manifest.md` -- navigation index for the project
-
-Per-project `agent.md` and `claude.md` were removed in v0.2.0. The agent-level
-conventions now live in the repo root `CLAUDE.md` / `AGENTS.md` and in
-`~/.syntaur/playbooks/`, which Step 1.5 already loaded.
-
-If the assignment has dependencies (`dependsOn` in frontmatter), read each
-dependency's `handoff.md` and `decision-record.md` for integration context and
-upstream decisions:
-- `<projectDir>/assignments/<dep-slug>/handoff.md`
-- `<projectDir>/assignments/<dep-slug>/decision-record.md`
-
-## Step 3: Explore Workspace (if set)
-
-If `workspaceRoot` is not null:
-
-1. Check if the workspace directory exists:
-   ```bash
-   ls <workspaceRoot>
-   ```
-2. Explore the codebase structure to understand what exists:
-   - Use `Glob` to find key files (e.g., `**/*.ts`, `**/package.json`, `**/*.md`)
-   - Use `Grep` to search for relevant patterns mentioned in the assignment
-   - Read key files like `package.json`, `tsconfig.json`, or entry points
-3. Note any existing patterns, conventions, or architecture you discover
-
-If `workspaceRoot` is null, skip this step and note in the plan that no workspace is configured.
-
-## Step 4: Write the Plan
-
-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).
-
-### 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:
-   - Description of what to do
-   - Files to create or modify (with paths)
-   - Dependencies on other tasks
-   - Estimated complexity (low/medium/high)
-3. **Acceptance Criteria Mapping** -- for each criterion from assignment.md, which task(s) address it
-4. **Risks and Open Questions** -- anything that might block or complicate implementation
-5. **Testing Strategy** -- how to verify the implementation works
-
-**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
-
-After writing the plan:
-1. Summarize the plan (number of tasks, key decisions)
-2. Note any open questions or risks that need human input
-3. Suggest next step: begin implementing the first task, or run `/complete-assignment` when all work is done
-
-**Remind the agent about recordkeeping during implementation:**
-- Check off acceptance criteria in `assignment.md` as each one is completed, not in a batch at the end
-- Append timestamped milestones to `progress.md` (separate append-only file) — not to `assignment.md`
-- Use `syntaur comment <slug-or-uuid> "body" --type note|question|feedback` to add a comment to `comments.md`
-- `assignment.md` is a live document — keep its status, todos, and acceptance checkboxes reflecting current state at all times

package/platforms/claude-code/skills/syntaur-protocol/SKILL.md

@@ -1,86 +0,0 @@
----
-name: syntaur-protocol
-description: This skill should be used when the user mentions "syntaur", "assignment", "project", works with files under ~/.syntaur/, references assignment.md, plan.md, handoff.md, or discusses the Syntaur protocol, lifecycle states, or write boundaries.
-version: 0.1.0
----
-
-# Syntaur Protocol Knowledge
-
-You are working within the Syntaur protocol. Follow these rules at all times.
-
-## Write Boundary Rules (CRITICAL)
-
-You MUST respect file ownership boundaries. Violations will be blocked by the PreToolUse hook.
-
-### Files you may WRITE directly:
-1. **Your assignment folder** -- only the assignment you are currently working on:
-   - `assignment.md`, `plan*.md` (0 or more versioned plan files), `progress.md`, `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. **Shared resources and memories** at the project level:
-   - `~/.syntaur/projects/<project>/resources/<slug>.md`
-   - `~/.syntaur/projects/<project>/memories/<slug>.md`
-3. **Your workspace** -- source code files within the workspace defined in your assignment's frontmatter (`workspace.worktreePath` or `workspace.repository`)
-4. **Context file** -- `.syntaur/context.json` in the current working directory
-
-### Files written 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 <target> "text"` to append a todo annotated `(from: <source>)`.
-
-### Files you must NEVER write:
-1. `project.md` -- human-authored, read-only
-2. `manifest.md` -- derived, rebuilt by tooling
-3. Any file prefixed with `_` (`_index-*.md`, `_status.md`) -- derived
-4. Other agents' assignment folders (except via the CLI-mediated channels above)
-5. Any files outside your workspace boundary
-
-## Current Assignment Context
-
-If `.syntaur/context.json` exists in the current working directory, read it to determine:
-- `projectSlug` -- which project you are working on
-- `assignmentSlug` -- which assignment is yours
-- `projectDir` -- absolute path to the project folder
-- `assignmentDir` -- absolute path to your assignment folder
-- `workspaceRoot` -- absolute path to your code workspace (if set)
-
-## Protocol References
-
-For detailed protocol information, read these files:
-- **Protocol summary:** `${CLAUDE_PLUGIN_ROOT}/references/protocol-summary.md`
-- **File ownership rules:** `${CLAUDE_PLUGIN_ROOT}/references/file-ownership.md`
-
-## Lifecycle Commands
-
-Use the `syntaur` CLI for state transitions and coordination:
-- `syntaur assign <slug> --agent <name> --project <project>` -- set assignee
-- `syntaur start <slug> --project <project>` -- pending -> in_progress
-- `syntaur review <slug> --project <project>` -- in_progress -> review
-- `syntaur complete <slug> --project <project>` -- in_progress/review -> completed
-- `syntaur block <slug> --project <project> --reason <text>` -- block an assignment
-- `syntaur unblock <slug> --project <project>` -- unblock
-- `syntaur fail <slug> --project <project>` -- mark as failed
-- `syntaur create-assignment "<title>" [--type <type>] [--project <slug> | --one-off]` -- create project-nested or standalone assignment
-- `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]` -- append to `comments.md`
-- `syntaur request <target> "text" [--from <source>]` -- append a todo to another assignment's `## Todos`
-
-## Troubleshooting
-
-If Syntaur state looks inconsistent (missing files, stale manifests, unexpected hook blocks), run `syntaur doctor` to diagnose. The `/doctor-syntaur` slash command wraps it and helps interpret results.
-
-## Playbooks
-
-Playbooks are user-defined behavioral rules stored in `~/.syntaur/playbooks/`. Each playbook is a markdown file with imperative rules that agents must follow. When you begin work on any assignment, read all playbook files and follow their directives. Playbooks take precedence over default conventions when they conflict.
-
-```bash
-ls ~/.syntaur/playbooks/*.md 2>/dev/null
-```
-
-## Conventions
-
-- Assignment frontmatter is the single source of truth for 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, hyphen-separated. For standalone assignments, the folder is named by UUID; `slug` is display-only.
-- Always read `project.md` at the project level (when project-nested) before starting work.
-- Append timestamped entries to `progress.md` as work lands — 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.
-- Use `syntaur request` to route work to another assignment.
-- Commit frequently with messages referencing the assignment slug.

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

@@ -1,64 +0,0 @@
----
-name: complete-assignment
-description: Use when the user wants to write a Syntaur handoff, close the current session, and transition the assignment to review or completed.
----
-
-# Complete Assignment
-
-Write a handoff for the current Syntaur assignment and transition it to `review` or `completed`.
-
-## Arguments
-
-User arguments: `$ARGUMENTS`
-
-If the user passed `--complete`, transition directly to `completed` only when all acceptance criteria are met AND all todos are either checked or marked superseded. Otherwise transition to `review`.
-
-## Workflow
-
-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
-## Handoff <N>: <ISO 8601 timestamp>
-
-**From:** codex
-**To:** human
-**Reason:** <Why this handoff is happening>
-
-### Summary
-<One paragraph>
-
-### Current State
-- <What is working>
-- <What is not working or still partial>
-- <Acceptance criteria status: N of M met>
-
-### Next Steps
-- <Recommended follow-up actions>
-
-### Important Context
-- <Anything the next person needs to know>
-```
-
-4. Update the handoff frontmatter:
-   - set `updated` to the current timestamp
-   - increment `handoffCount`
-5. Update acceptance criteria and todo checkboxes in `assignment.md` to match reality. Do NOT modify superseded todo lines (those matching `- [x] ~~...~~ (superseded by ...)`).
-6. If `.syntaur/context.json` includes `sessionId`, mark that session as completed through 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","projectSlug":"<project-slug>"}'
-```
-
-7. Transition the assignment:
-   - `syntaur complete <assignment-slug> --project <project-slug>` when `--complete` is allowed
-   - otherwise `syntaur review <assignment-slug> --project <project-slug>`
-8. Delete `.syntaur/context.json`.
-9. Summarize:
-   - new status
-   - acceptance criteria met vs total
-   - any criteria still unmet or follow-up risk

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

@@ -1,49 +0,0 @@
----
-name: create-assignment
-description: Use when the user wants to create a new Syntaur assignment inside a project or as a one-off project plus assignment.
----
-
-# Create Assignment
-
-Create a new Syntaur assignment from Codex.
-
-## Arguments
-
-User arguments: `$ARGUMENTS`
-
-Parse:
-
-- First positional argument: assignment title
-- `--project <slug>` required unless `--one-off`
-- `--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`
-- `--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.
-
-If neither `--project` nor `--one-off` was provided, look for `.syntaur/context.json` in the current working directory. If present, default the project to that context's `projectSlug` and tell the user you are using it.
-
-## Workflow
-
-1. Run one of:
-   - `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 (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`, `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

@@ -1,73 +0,0 @@
----
-name: grab-assignment
-description: Use when the user wants to load a Syntaur assignment into context, create .syntaur/context.json, and register a Codex session. Works regardless of assignment status.
----
-
-# Grab Assignment
-
-Load a Syntaur assignment into the current working context and register this Codex session.
-
-**Grabbing is non-destructive.** It never fails because of status. Any status (`pending`, `in_progress`, `blocked`, `review`, `completed`, `failed`) can be grabbed — grabbing just sets up context and registers the session. Only a `pending` assignment additionally transitions to `in_progress`; any other status is left untouched.
-
-## Arguments
-
-User arguments: `$ARGUMENTS`
-
-Parse:
-
-- First positional argument: project slug
-- Second positional argument: optional assignment slug
-
-## Workflow
-
-1. If `.syntaur/context.json` already exists in the current working directory, read it and warn that claiming another assignment will replace the active context.
-2. Read the project entry files:
-   - `~/.syntaur/projects/<project-slug>/manifest.md`
-   - `~/.syntaur/projects/<project-slug>/project.md`
-   - `~/.syntaur/projects/<project-slug>/agent.md`
-   - `~/.syntaur/projects/<project-slug>/claude.md` if it exists
-   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 8), include `"workspace": "<value>"` if the project has a workspace.
-3. Discover assignments under `~/.syntaur/projects/<project-slug>/assignments/`. Do **not** filter by status — every assignment is grabbable.
-4. If no assignment slug was provided:
-   - list assignments with title, priority, and current status (highlight `pending` ones as the default candidates)
-   - ask the user to choose unless there is exactly one obvious candidate
-   If a slug *was* provided, verify the directory exists. Its status does not matter; do not block on it.
-5. Read the chosen assignment's `assignment.md` — its frontmatter for `status`, and its markdown body for the objective, acceptance criteria, and `## Todos` section (active todos indicate outstanding work and may link to plan files to execute). If `dependsOn` is non-empty, also read each dep's `handoff.md` AND `decision-record.md` to inherit upstream context and decisions.
-6. Claim the assignment:
-   - Always: `syntaur assign <assignment-slug> --agent codex --project <project-slug>` (safe at any status; does not transition state)
-   - **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 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
-{
-  "projectSlug": "<project-slug>",
-  "assignmentSlug": "<assignment-slug>",
-  "projectDir": "/absolute/path/to/project",
-  "assignmentDir": "/absolute/path/to/assignment",
-  "workspaceRoot": "/absolute/path/to/workspace",
-  "title": "<assignment title>",
-  "branch": "<workspace.branch or null>",
-  "grabbedAt": "<ISO 8601 timestamp>",
-  "sessionId": "<real-codex-session-id>",
-  "transcriptPath": "<absolute path to the matching rollout jsonl>"
-}
-```
-
-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")
-   - objective
-   - acceptance criteria
-   - active todos from the `## Todos` section (if any), including any plan files they link to
-   - workspace path
-11. Suggest a next step appropriate to status:
-   - `pending` / `in_progress`: `plan-assignment`
-   - `blocked`: investigate `blockedReason`
-   - `review`: inspect the implementation and help verify acceptance criteria
-   - `completed` / `failed`: read the handoff; grab is probably for reference or reopen

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

@@ -1,61 +0,0 @@
----
-name: plan-assignment
-description: Use when the user wants a detailed implementation plan written as a versioned plan file for the current Syntaur assignment.
----
-
-# Plan Assignment
-
-Create an implementation plan for the current Syntaur assignment. Plans are versioned files: the first is `plan.md`, later ones 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.
-
-## Arguments
-
-Optional notes from the user: `$ARGUMENTS`
-
-## Workflow
-
-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`
-   - `<assignmentDir>/comments.md` (if it exists — inherited questions / notes)
-   - `<projectDir>/project.md`
-   - `<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
-   - note conventions and architecture
-5. Determine the next plan filename:
-   - List `<assignmentDir>/plan*.md`.
-   - If none exist, target is `plan.md` (version label: "plan").
-   - Otherwise pick the smallest `N >= 2` such that `plan-v<N>.md` does not exist (version label: `plan v<N>`).
-6. Write `<assignmentDir>/<planFilename>` with standard plan frontmatter (`assignment`, `status: draft`, `created`, `updated`) and a body containing the sections below. If the file already exists (only possible for `plan.md` on first re-run), preserve frontmatter, flip `status` from `draft` to `in_progress`, update `updated`, and replace only the body.
-7. Update `<assignmentDir>/assignment.md`:
-   - Find unchecked todos matching `- [ ] Execute [<label>](./plan*.md)`. Rewrite each as `- [x] ~~Execute [<label>](./<old-filename>)~~ (superseded by <versionLabel>)`. Never delete the old line.
-   - Append a new todo: `- [ ] Execute [<versionLabel>](./<planFilename>)`.
-   - If `## Todos` is missing (legacy assignment), insert it right after `## Acceptance Criteria` with a short guidance comment and the new todo line.
-   - Refresh the assignment frontmatter `updated` timestamp.
-
-## Plan Contents
-
-Write these sections:
-
-1. Overview
-2. Tasks
-3. Acceptance Criteria Mapping
-4. Risks and Open Questions
-5. Testing Strategy
-
-**Decision capture:** While planning, record meaningful choices (library picks, schema design, architectural calls, rejected alternatives) as numbered entries in `<assignmentDir>/decision-record.md` using `## Decision N: <short title>` with Status (proposed/accepted), Context, Decision, Consequences. Downstream assignments that depend on this one auto-load these on grab.
-
-## Reporting
-
-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` 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

@@ -1,102 +0,0 @@
----
-name: syntaur-protocol
-description: Use when the user mentions Syntaur, projects, assignments, files under ~/.syntaur/, assignment.md, plan.md, handoff.md, .syntaur/context.json, lifecycle states, or write boundaries.
----
-
-# Syntaur Protocol
-
-You are working within the Syntaur protocol. Follow these rules at all times.
-
-## Write Boundary Rules
-
-Respect file ownership boundaries.
-
-### 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`
-2. `manifest.md`
-3. Any file prefixed with `_`
-4. Other agents' assignment folders (except via the CLI-mediated channels above)
-5. Anything outside the current workspace boundary
-
-## Current Assignment Context
-
-If `.syntaur/context.json` exists in the current working directory, read it before making changes. Use it to determine:
-
-- `projectSlug`
-- `assignmentSlug`
-- `projectDir`
-- `assignmentDir`
-- `workspaceRoot`
-- `sessionId` if present
-
-## Required Reading Order
-
-When you are working on an existing assignment, read these in order:
-
-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 and coordination:
-
-- `syntaur assign <slug> --agent <name> --project <project>`
-- `syntaur start <slug> --project <project>`
-- `syntaur review <slug> --project <project>`
-- `syntaur complete <slug> --project <project>`
-- `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
-
-If Syntaur state looks inconsistent (missing files, stale manifests, unexpected hook blocks), run `syntaur doctor` to diagnose. Use `--json` for structured output.
-
-## Conventions
-
-- 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.
-- 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
-
-Read these only when you need the detailed rules or directory layout:
-
-- `../../references/protocol-summary.md`
-- `../../references/file-ownership.md`