syntaur 0.3.0 → 0.4.0

package/vendor/syntaur-skills/skills/plan-assignment/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: plan-assignment
+description: >-
+  Create a detailed implementation plan for the current Syntaur assignment.
+  Use when the user wants to plan their work, write a plan file, or design an
+  approach for an active assignment.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Plan Assignment
+
+Create a versioned implementation plan for your current Syntaur assignment. Plans are versioned files: the first is `plan.md`, subsequent ones are `plan-v2.md`, `plan-v3.md`, and so on. Each plan gets a linked todo in the `## Todos` section of `assignment.md`; prior active plan todos are marked superseded (never deleted).
+
+## Input
+
+Optional: the user may provide focus areas or notes to guide the plan.
+
+## Step 1: Load Context
+
+Read `.syntaur/context.json` from the current working directory. If the file does not exist, tell the user: "No active assignment found. Run `grab-assignment` first to claim an assignment."
+
+Extract:
+- `projectSlug` — the project slug (`null` for standalone assignments)
+- `assignmentSlug` — the assignment slug
+- `assignmentDir` — absolute path to the assignment folder
+- `projectDir` — absolute path to the project folder (may be null for standalone)
+- `workspaceRoot` — absolute path to the workspace (may be null)
+
+## Step 2: Load Playbooks
+
+Read all playbook files from `~/.syntaur/playbooks/`:
+
+```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 take precedence over default conventions.
+
+## Step 3: Read Assignment Details
+
+Read these files to understand the assignment:
+
+1. `<assignmentDir>/assignment.md` — objective, acceptance criteria, context, and the `## Todos` list
+2. `<assignmentDir>/comments.md` if present — inherited questions, notes, and feedback
+3. `<projectDir>/project.md` — project goal for broader context (skip for standalone)
+4. `<projectDir>/manifest.md` — project navigation index (skip for standalone)
+
+Per-project `agent.md` / `claude.md` were removed in protocol v2.0. Agent-level conventions now live at the repo root (`CLAUDE.md` / `AGENTS.md`) and in `~/.syntaur/playbooks/` (already loaded in Step 2).
+
+If the assignment has dependencies (`dependsOn` in frontmatter), read each dependency's `handoff.md` AND `decision-record.md` for integration context and upstream decisions.
+
+## Step 4: Explore Workspace (if set)
+
+If `workspaceRoot` is not null:
+
+1. Check the workspace directory exists.
+2. Explore the codebase to understand what exists: find key files (`**/*.ts`, `package.json`, `**/*.md`, etc.), search for relevant patterns mentioned in the assignment, read entry points and config.
+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 5: Write the Plan
+
+### 5a. Determine the next plan filename
+
+List `<assignmentDir>/plan*.md` and pick the target:
+
+- If no plan files exist → `plan.md` (version label: "plan").
+- If `plan.md` exists but no `plan-v<N>.md` → `plan-v2.md` (version label: "plan v2").
+- Otherwise pick the smallest `N >= 2` such that `plan-v<N>.md` does not exist (version label: `plan v<N>`).
+
+Remember this `planFilename` and `versionLabel` for Steps 5b and 5c.
+
+### 5b. Write the plan file
+
+Write `<assignmentDir>/<planFilename>` with standard plan frontmatter:
+
+```yaml
+---
+assignment: <assignmentSlug>
+status: draft
+created: "<nowTimestamp>"
+updated: "<nowTimestamp>"
+---
+```
+
+Body sections:
+
+1. **Overview** — one paragraph summarizing the approach.
+2. **Tasks** — numbered list; each task has description, files to create/modify (with paths), dependencies on other tasks, and complexity estimate (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, 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 decisions.
+
+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`.
+
+### 5c. Update assignment.md Todos
+
+Read `<assignmentDir>/assignment.md` and locate the `## Todos` section.
+
+1. **Supersede prior plan todos.** For every unchecked line matching `- [ ] Execute [<label>](./plan.md)` or `- [ ] Execute [<label>](./plan-v<N>.md)`, rewrite as:
+
+   ```
+   - [x] ~~Execute [<label>](./<old-plan-filename>)~~ (superseded by <versionLabel>)
+   ```
+
+   Never delete the old line — preserve history.
+
+2. **Append the new plan todo.** Add a new line to the end of `## Todos`:
+
+   ```
+   - [ ] Execute [<versionLabel>](./<planFilename>)
+   ```
+
+3. **Missing-section fallback.** If `## Todos` 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.
+
+Also refresh the assignment frontmatter `updated` timestamp.
+
+## Step 6: 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. Call out which plan filename was written and whether any prior plan was superseded.
+4. Suggest the next step: begin implementing the first task, or run `complete-assignment` when all work is done.
+
+**Recordkeeping reminders for 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` (a separate append-only file). Do NOT add a `## Progress` section to `assignment.md` — protocol v2.0 moved progress to its own file.
+- Record questions, notes, or feedback via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback` — never edit `comments.md` directly.
+- Keep `assignment.md` status, todos, and acceptance checkboxes reflecting current state at all times.

package/vendor/syntaur-skills/skills/syntaur-protocol/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: syntaur-protocol
+description: >-
+  Use when the user mentions Syntaur, projects, assignments, files under
+  ~/.syntaur/, assignment.md, plan*.md, progress.md, comments.md, handoff.md,
+  .syntaur/context.json, lifecycle states, or write boundaries. Core protocol
+  knowledge for any AI agent working within Syntaur (protocol v2.0).
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Syntaur Protocol (v2.0)
+
+You are working within the Syntaur protocol — a coordination system for AI agents built on markdown files. Follow these rules at all times.
+
+## Write Boundary Rules
+
+Respect file ownership boundaries. The Claude Code and Codex plugins enforce them via PreToolUse hooks; other agents are on the honor system but the dashboard surfaces violations.
+
+### Files you may write
+
+1. **Your assignment folder only** (project-nested OR standalone):
+   - `assignment.md`
+   - `plan*.md` (versioned — `plan.md`, `plan-v2.md`, etc.)
+   - `progress.md` (append-only, timestamped)
+   - `scratchpad.md`
+   - `handoff.md` (append-only)
+   - `decision-record.md` (append-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.worktreePath` / `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>]`. Questions carry a `resolved` flag toggled in the dashboard.
+- Another assignment's `## Todos` section — use `syntaur request <target> "text" [--from <source>]` 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. Anything outside the current workspace boundary.
+
+Per-project `agent.md` / `claude.md` do NOT exist in protocol v2.0. Agent-level conventions now live at the repo root (`CLAUDE.md` / `AGENTS.md`) and in `~/.syntaur/playbooks/`.
+
+## Current Assignment Context
+
+If `.syntaur/context.json` exists in the current working directory, read it before making changes. Fields you will see:
+
+- `projectSlug` — containing project slug (`null` for standalone assignments)
+- `assignmentSlug` — assignment slug (for standalone, the UUID is the folder name; slug is display-only)
+- `projectDir` — absolute path to the project folder (`null` for standalone)
+- `assignmentDir` — absolute path to the assignment folder
+- `workspaceRoot` — absolute path to the code workspace
+- `sessionId` — real agent-runtime session id (never a synthesized UUID)
+- `transcriptPath` — absolute path to the agent's rollout/transcript file, if known
+
+## Required Reading Order
+
+When starting work on an existing assignment, read these in order:
+
+1. `~/.syntaur/playbooks/*.md` — behavioral rules (take precedence over defaults)
+2. `<projectDir>/manifest.md` (skip for standalone)
+3. `<projectDir>/project.md` (skip for standalone)
+4. `<assignmentDir>/assignment.md`
+5. `<assignmentDir>/comments.md` if present — inherited questions / notes
+6. Latest `<assignmentDir>/plan*.md` (pick the newest)
+7. `<assignmentDir>/handoff.md` — history
+8. For each `dependsOn` entry: the dependency's `handoff.md` AND `decision-record.md` — upstream integration context and accepted decisions carry forward
+
+## Lifecycle Commands
+
+- `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
+- `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
+- `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`
+- `syntaur track-session --agent <name> --session-id <real-id> [--transcript-path <path>] [--project <p>] [--assignment <a>]` — register an agent session. The session-id must be the real one from the agent runtime — no synthesized UUIDs.
+
+## Agent Sessions
+
+Sessions are registered in `~/.syntaur/syntaur.db` keyed on the real agent session id. Plugins for Claude Code / Codex include a `SessionStart` hook that auto-merges `sessionId` and `transcriptPath` into an existing `.syntaur/context.json` at the start of every session. Other agents should source the real id from their runtime and pass it to `syntaur track-session` explicitly.
+
+## Playbooks
+
+Playbooks at `~/.syntaur/playbooks/` are user-defined behavioral rules. Read them before starting work on any assignment and follow their directives. They 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.
+- Update acceptance criteria checkboxes as work lands, not only at the end.
+- Append milestones to `progress.md` — do NOT add a `## Progress` section to `assignment.md` (v2.0 moved progress to its own file).
+- `## Todos` in `assignment.md` is an informal markdown checklist. Items may be simple tasks or markdown links to plan files. When a plan is superseded, mark the old todo as `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete. `## Todos` is also the landing spot for cross-assignment `syntaur request` entries.
+- Record questions / notes / feedback via `syntaur comment` — never edit `comments.md` directly. Do NOT set status to `blocked` just because there is an open question; block only for a real external dependency with a `--reason`.
+- Write handoffs with enough context for another agent or human to continue cleanly. Record decisions in `decision-record.md` with Status / Context / Decision / Consequences — downstream dependents auto-load these during grab.
+- Commit frequently with messages referencing the assignment slug.
+
+## References
+
+For the full directory structure, lifecycle state table, and detailed file ownership rules, read:
+
+- `references/protocol-summary.md`
+- `references/file-ownership.md`

package/vendor/syntaur-skills/skills/syntaur-protocol/references/file-ownership.md

@@ -0,0 +1,67 @@
+# File Ownership Rules (protocol v2.0)
+
+## Human-Authored (READ-ONLY for agents)
+
+Agents must NEVER modify these files:
+
+| File | Location |
+|------|----------|
+| `project.md` | `<project>/project.md` |
+| `CLAUDE.md` / `AGENTS.md` | Repo root (live outside `~/.syntaur/`) |
+| `<slug>.md` | `~/.syntaur/playbooks/<slug>.md` |
+
+Per-project `agent.md` / `claude.md` were removed in protocol v2.0. Agent-level conventions live at the repo root in `CLAUDE.md` / `AGENTS.md`, and user-defined behavioral rules live in `~/.syntaur/playbooks/`.
+
+## Agent-Writable (YOUR assignment folder ONLY)
+
+You may only write to files inside your currently-claimed assignment folder:
+
+| File | Purpose |
+|------|---------|
+| `assignment.md` | Assignment record; source of truth for state. Includes `## Todos` checklist. |
+| `plan*.md` | Versioned implementation plans (`plan.md`, `plan-v2.md`, ...). When superseded, the old plan's todo is marked superseded but the file itself is never deleted. |
+| `progress.md` | Append-only, timestamped progress log (newest first). |
+| `scratchpad.md` | Working notes. |
+| `handoff.md` | Append-only handoff log. |
+| `decision-record.md` | Append-only decision log (Status / Context / Decision / Consequences). |
+
+Path patterns:
+- Project-nested: `~/.syntaur/projects/<project>/assignments/<your-assignment-slug>/`
+- Standalone: `~/.syntaur/assignments/<your-assignment-uuid>/` (folder name is the UUID; `slug` is display-only)
+
+## CLI-Mediated (any agent via the `syntaur` CLI)
+
+These files are never edited directly — write to them only through the CLI so derived indexes and dashboards stay consistent.
+
+| Target | Command |
+|--------|---------|
+| `comments.md` (any assignment) | `syntaur comment <slug-or-uuid> "body" --type question\|note\|feedback [--reply-to <id>]` |
+| Another assignment's `## Todos` | `syntaur request <target> "text" [--from <source>]` |
+
+## Shared-Writable (any agent or human)
+
+| Location | Purpose |
+|----------|---------|
+| `<project>/resources/<slug>.md` | Reference material |
+| `<project>/memories/<slug>.md` | Learnings and patterns |
+
+## Derived (NEVER edit)
+
+All files prefixed with `_` are derived and rebuilt by tooling:
+
+- `manifest.md`
+- `_index-assignments.md`
+- `_index-plans.md`
+- `_index-decisions.md`
+- `_status.md`
+- `resources/_index.md`
+- `memories/_index.md`
+- `~/.syntaur/playbooks/manifest.md`
+
+## Workspace Files
+
+When working on code (not protocol files), you may write to files within the workspace defined in your assignment frontmatter:
+
+- `workspace.worktreePath` or `workspace.repository` defines your code root.
+- You may create and edit source files within that workspace.
+- The `.syntaur/context.json` context file in your working directory is also writable (merge, don't overwrite — the platform SessionStart hook may have populated `sessionId` and `transcriptPath`).

package/vendor/syntaur-skills/skills/syntaur-protocol/references/protocol-summary.md

@@ -0,0 +1,82 @@
+# Syntaur Protocol Summary
+
+Protocol version: **2.0**
+
+## Directory Structure
+
+```
+~/.syntaur/
+  config.md
+  projects/
+    <project-slug>/
+      manifest.md            # Derived: root navigation (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: status rollup (read-only)
+      assignments/
+        <assignment-slug>/
+          assignment.md      # Agent-writable: source of truth for state (## Todos checklist)
+          plan*.md           # Agent-writable: versioned plans (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
+      resources/
+        _index.md            # Derived (read-only)
+        <resource-slug>.md   # Shared-writable
+      memories/
+        _index.md            # Derived (read-only)
+        <memory-slug>.md     # Shared-writable
+  assignments/
+    <assignment-uuid>/       # Standalone assignments: folder = UUID, `project: null`, slug display-only
+      assignment.md          # Same schema as project-nested
+      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
+  syntaur.db                 # SQLite: agent session registry keyed on real session_id
+```
+
+## Assignment Lifecycle
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Not yet started |
+| `in_progress` | Actively being worked on |
+| `blocked` | Manually blocked (requires `blockedReason`) |
+| `review` | Work complete, awaiting review |
+| `completed` | Done |
+| `failed` | Could not be completed |
+
+## Valid State Transitions
+
+| From | Command | To |
+|------|---------|-----|
+| pending | start | in_progress |
+| pending | block | blocked |
+| in_progress | block | blocked |
+| in_progress | review | review |
+| in_progress | complete | completed |
+| in_progress | fail | failed |
+| blocked | unblock | in_progress |
+| review | start | in_progress |
+| review | complete | completed |
+| review | fail | failed |
+
+## Key Rules
+
+1. **Assignment frontmatter is the single source of truth** for all assignment state.
+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, plus `manifest.md`) are never edited manually.
+4. **Slugs** are lowercase, hyphen-separated.
+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 them before starting work.
+8. **Todos** in `## Todos` of `assignment.md` is an informal markdown checklist. Items may be simple tasks or markdown links to plan files. When a plan is superseded, mark the old todo `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete. `## Todos` is also the landing spot for cross-assignment `syntaur request` entries.
+9. **Progress** is appended to `progress.md` as timestamped entries (newest first). Do NOT add a `## Progress` section to `assignment.md` — protocol v2.0 moved progress to its own file.
+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 toggled in the dashboard.
+11. **Cross-assignment work** is requested via `syntaur request <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.
+12. **Agent sessions** in `syntaur.db` must use real agent-runtime session IDs. Synthesized UUIDs are rejected. Plugins for Claude Code / Codex populate `.syntaur/context.json` with the real id via a SessionStart hook; other agents should source it from their runtime and pass `--session-id` explicitly.

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

@@ -1,155 +0,0 @@
----
-name: complete-assignment
-description: Write a handoff and transition the current Syntaur assignment to review or completed
-argument-hint: "[--complete]"
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
----
-
-# Complete Assignment
-
-Write a handoff for your current assignment and transition it to review (or completed).
-
-## Arguments
-
-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 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 <project-slug>` first."
-
-Extract: `projectSlug`, `assignmentSlug`, `assignmentDir`, `projectDir`.
-
-## Step 1.5: Load Playbooks
-
-Read all playbook files from `~/.syntaur/playbooks/` — verify your work complies with their rules:
-
-```bash
-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 and Todos
-
-Read `<assignmentDir>/assignment.md` and find the `## Acceptance Criteria` and `## Todos` sections.
-
-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
-
-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.
-
-Append a new handoff entry to the markdown body. Read the current `handoffCount` from the frontmatter and use `handoffCount + 1` as the entry number. The entry MUST follow the protocol-specified format from `docs/protocol/file-formats.md`:
-
-```markdown
----
-## Handoff <N>: <ISO 8601 timestamp>
-
-**From:** claude
-**To:** human
-**Reason:** <Why this handoff is happening, e.g., "Assignment complete, handing off for review.">
-
-### Summary
-<One paragraph summarizing what was accomplished and what remains>
-
-### Current State
-- <What is working>
-- <What is not working or partially done>
-- <Acceptance criteria status: N of M met>
-
-### Next Steps
-- <Recommended next actions for the reviewer or next agent>
-
-### Important Context
-- <Anything the next agent/human needs that is not in the assignment or plan>
-```
-
-Use the Edit tool to append this entry to handoff.md (do not overwrite existing content).
-
-Also update the handoff.md frontmatter: set `updated` to the current timestamp and increment the `handoffCount` by 1.
-
-## 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]`).
-
-**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.
-
-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 `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", "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.
-
-## Step 5: Transition Assignment State
-
-If the user passed `--complete`:
-
-```bash
-syntaur complete <assignment-slug> --project <project-slug>
-```
-
-Otherwise, transition to review:
-
-```bash
-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)
-- Project not found
-
-## Step 6: Clean Up Context
-
-Delete the context file:
-
-```bash
-rm .syntaur/context.json
-```
-
-## Step 7: Report to User
-
-Summarize:
-- Assignment slug and title
-- New status (review or completed)
-- Number of acceptance criteria met vs total
-- Remind: if transitioned to `review`, a human reviewer will check the work. If any criteria were unmet, they may send it back to `in_progress` via `syntaur start`.

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

@@ -1,67 +0,0 @@
----
-name: create-assignment
-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
----
-
-# Create Assignment
-
-Create a new assignment within a Syntaur project from Claude Code.
-
-## Arguments
-
-The user provided: $ARGUMENTS
-
-Parse the arguments:
-- First argument (required): the assignment title (e.g., `"Add login endpoint"`)
-- `--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`
-- `--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 `--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 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>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--type <type>] [--dir <path>]
-```
-
-Or for one-off (standalone at `~/.syntaur/assignments/<uuid>/`):
-
-```bash
-syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--type <type>] [--dir <path>]
-```
-
-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/projects/<project-slug>/assignments/<assignment-slug>/assignment.md
-```
-
-## Step 3: Guide Next Steps
-
-Tell the user:
-- 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.