syntaur 0.3.0 → 0.4.0

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

@@ -1,187 +0,0 @@
----
-name: grab-assignment
-description: Load a Syntaur assignment into the current working context
-argument-hint: <project-slug> [assignment-slug]
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Glob
-  - Grep
----
-
-# Grab Assignment
-
-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 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 project `<projectSlug>`. Grabbing a new assignment will replace this context. Proceed?"
-   - If the user says no, stop.
-
-## Step 1: Discover the Project
-
-Read the project directory to understand what is available:
-
-```bash
-ls ~/.syntaur/projects/<project-slug>/
-```
-
-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
-
-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.
-
-## Step 2: Find Assignments
-
-List assignment directories:
-
-```bash
-ls ~/.syntaur/projects/<project-slug>/assignments/
-```
-
-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, 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
-
-Read the assignment frontmatter first to learn its current `status`:
-
-```bash
-cat ~/.syntaur/projects/<project-slug>/assignments/<assignment-slug>/assignment.md
-```
-
-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 assign <assignment-slug> --agent claude --project <project-slug>
-```
-
-**Only if the current status is `pending`**, also run `syntaur start` to transition it to `in_progress`:
-
-```bash
-syntaur start <assignment-slug> --project <project-slug>
-```
-
-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)
-- `workspace.branch` -- the branch name (may be null)
-- `dependsOn` -- list of dependency slugs
-- `priority` -- priority level
-
-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
-
-If `workspace.repository` and `workspace.worktreePath` are both null, set them to the current working directory (`$(pwd)`). This is critical because the write boundary hook uses the workspace path to determine which files the agent is allowed to edit. Without it, all code edits outside the assignment directory will be blocked.
-
-Use the Edit tool to update the assignment.md frontmatter:
-```yaml
-workspace:
-  repository: /absolute/path/to/cwd
-  worktreePath: /absolute/path/to/cwd
-```
-
-## Step 5: Create Context File
-
-Write `.syntaur/context.json` in the current working directory with the assignment context. First ensure the directory exists:
-
-```bash
-mkdir -p .syntaur
-```
-
-Then write the JSON file with this structure:
-
-```json
-{
-  "projectSlug": "<project-slug>",
-  "assignmentSlug": "<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>",
-  "grabbedAt": "<ISO 8601 timestamp>"
-}
-```
-
-Use absolute paths (expand `~` to the actual home directory). Note: `workspace.repository` may be a remote URL (e.g., `https://github.com/...`) -- only use it as `workspaceRoot` if it starts with `/` (local path). If it is a URL, set `workspaceRoot` to the current working directory.
-
-**IMPORTANT:** The `workspaceRoot` must NEVER be null when the agent will be writing code. If no workspace was configured, default to the current working directory.
-
-## Step 5.5: Register Agent Session
-
-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
-ls -t ~/.claude/sessions/*.json | head -5
-```
-Read the most recent file(s) and find the one whose `cwd` matches `$(pwd)`. Extract the `sessionId` field — this is the real Claude Code session ID that can be used with `claude --resume <sessionId>` to resume this exact conversation.
-
-If you cannot find a matching session file (e.g., no file matches the cwd, or the sessions directory is empty), ask the user to run `/rename <assignment-slug>` to name the current session after the assignment. Then store the assignment slug as the session name in context.json (`"sessionName": "<assignment-slug>"`) instead of `sessionId`. The user can later resume with `claude --resume <assignment-slug>`.
-
-2. Run the track-session command (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
-```bash
-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.
-
-## Step 5.6: Load Playbooks
-
-Read all playbook files from `~/.syntaur/playbooks/` and treat their content as active behavioral rules for this assignment:
-
-```bash
-ls ~/.syntaur/playbooks/*.md 2>/dev/null
-```
-
-For each `.md` file found, read it and internalize the rules in its body section. These are user-defined behavioral policies that you must follow throughout your work on this assignment. Playbooks take precedence over default conventions when they conflict.
-
-If no playbook files exist, skip this step.
-
-## Step 6: Report to User
-
-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 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

@@ -1,148 +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 any Q&A
-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:
-- `<projectDir>/assignments/<dep-slug>/handoff.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
-- Update the `## Progress` section in `assignment.md` after each meaningful milestone
-- The assignment file is a live document — it should reflect 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,71 +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 `.syntaur/context.json` in the current working directory with:
-
-```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": "<uuid>"
-}
-```
-
-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>`
-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,57 +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`
-   - `<projectDir>/agent.md`
-   - `<projectDir>/claude.md` if it exists
-   - `<projectDir>/project.md`
-3. If the assignment depends on other assignments, read each dependency handoff for integration context.
-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` progress, acceptance criteria, and todos current during implementation