syntaur 0.7.1 → 0.8.0

package/platforms/codex/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/platforms/codex/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/codex/skills/track-server/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: track-server
+description: Use when the user wants to register, refresh, remove, or list tracked tmux dev-server sessions for the Syntaur dashboard. Triggers on "/track-server", "track this server", "register this dev server", or similar — distinct from /track-session which registers Claude Code agent sessions.
+---
+
+# Track Server
+
+Track tmux sessions so their development servers show up in the Syntaur dashboard. Distinct from `/track-session`, which registers Claude Code agent sessions.
+
+## Arguments
+
+User arguments: `$ARGUMENTS`
+
+Supported forms:
+
+- `<session-name>`
+- `--refresh [session-name]`
+- `--remove <session-name>`
+- `--list`
+
+## Workflow
+
+### Register
+
+1. Verify the tmux session exists with `tmux has-session -t <name>`.
+2. If it does not exist, list available sessions with `tmux list-sessions -F '#{session_name}'`.
+3. Create `~/.syntaur/servers/<sanitized-name>.md` with frontmatter:
+
+```yaml
+---
+session: <original-name>
+registered: <ISO timestamp>
+last_refreshed: <ISO timestamp>
+---
+```
+
+4. Tell the user the session is now tracked.
+
+### Refresh
+
+1. Update `last_refreshed` for the named session, or for every file in `~/.syntaur/servers/` when no name was provided.
+
+### Remove
+
+1. Delete `~/.syntaur/servers/<sanitized-name>.md`.
+
+### List
+
+1. List all tracked session markdown files and show the `session` field from each.

package/platforms/codex/skills/track-session/SKILL.md

@@ -1,49 +1,86 @@
 ---
 name: track-session
-description: Use when the user wants to register, refresh, remove, or list tracked tmux sessions for the Syntaur dashboard.
+description: Use when the user asks to track, register, or log this Claude Code session in the Syntaur dashboard — standalone or linked to a project/assignment. Triggers on "/track-session", "track this session", "register this session in syntaur", or similar.
 ---
 
 # Track Session
 
-Track tmux sessions so their development servers show up in the Syntaur dashboard.
+Register the current Claude Code session as an agent session in the Syntaur dashboard. Works standalone or linked to a project/assignment.
 
-## Arguments
+Only real Claude Code session IDs are accepted — no synthesis. The real id is written to `.syntaur/context.json` by the SessionStart hook, with `~/.claude/sessions/<pid>.json` as the fallback source.
 
-User arguments: `$ARGUMENTS`
+## Usage
 
-Supported forms:
+User arguments: `$ARGUMENTS`
 
-- `<session-name>`
-- `--refresh [session-name]`
-- `--remove <session-name>`
-- `--list`
+- (no args) — register a standalone session
+- `--description "<text>"` — with a description
+- `--project <slug> --assignment <slug>` — linked to a project
+- `--description "<text>" --project <slug> --assignment <slug>` — both
 
 ## Workflow
 
-### Register
+### Step 1: Parse arguments
 
-1. Verify the tmux session exists with `tmux has-session -t <name>`.
-2. If it does not exist, list available sessions with `tmux list-sessions -F '#{session_name}'`.
-3. Create `~/.syntaur/servers/<sanitized-name>.md` with frontmatter:
+Extract optional flags from the argument string:
+- `--description "<text>"` or `--description <text>` — session description
+- `--project <slug>` — project to link to
+- `--assignment <slug>` — assignment to link to
 
-```yaml
----
-session: <original-name>
-registered: <ISO timestamp>
-last_refreshed: <ISO timestamp>
----
+### Step 2: Source the real session id + transcript path
+
+In priority order:
+
+1. Read `.syntaur/context.json` if present. If it contains `sessionId`, use it. Also pick up `transcriptPath` if present.
+2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
+3. If neither source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
+
+DO NOT generate a UUID. `syntaur track-session` rejects missing session IDs.
+
+### Step 3: Run the CLI command
+
+Run the track-session CLI via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
+
+```bash
+syntaur track-session \
+  --agent claude \
+  --session-id "$SESSION_ID" \
+  --transcript-path "$TRANSCRIPT_PATH" \
+  --path "$(pwd)" \
+  [--description "<text>"] \
+  [--project <slug>] \
+  [--assignment <slug>]
 ```
 
-4. Tell the user the session is now tracked.
+Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved.
+
+The CLI prints one of:
+- `Registered standalone agent session <sessionId>.`
+- `Registered agent session <sessionId> for <assignment> in <project>.`
 
-### Refresh
+Registration is idempotent — re-running the command with the same session id safely upserts project/assignment/description onto the existing row.
 
-1. Update `last_refreshed` for the named session, or for every file in `~/.syntaur/servers/` when no name was provided.
+### Step 4: Merge context.json
 
-### Remove
+Ensure `.syntaur/context.json` has the session fields (so SessionEnd and future `track-session` runs find them). Merge, don't overwrite:
 
-1. Delete `~/.syntaur/servers/<sanitized-name>.md`.
+```bash
+mkdir -p .syntaur
+if [ -f .syntaur/context.json ]; then
+  jq --arg sid "$SESSION_ID" --arg tp "$TRANSCRIPT_PATH" \
+    '. + {sessionId: $sid} + (if ($tp | length) > 0 then {transcriptPath: $tp} else {} end)' \
+    .syntaur/context.json > .syntaur/context.json.tmp \
+    && mv .syntaur/context.json.tmp .syntaur/context.json
+else
+  jq -n --arg sid "$SESSION_ID" --arg tp "$TRANSCRIPT_PATH" \
+    '{sessionId: $sid} + (if ($tp | length) > 0 then {transcriptPath: $tp} else {} end)' \
+    > .syntaur/context.json
+fi
+```
 
-### List
+### Step 5: Confirm
 
-1. List all tracked session markdown files and show the `session` field from each.
+Tell the user:
+- The session was registered (include the short session id).
+- It will be auto-stopped when this conversation ends via the SessionEnd hook.
+- If linked to a project, mention which project/assignment.

package/skills/clear-assignment/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: clear-assignment
+description: >-
+  Clear the active Syntaur assignment from the current session without
+  transitioning lifecycle state. Use when the user wants to drop, release,
+  unclaim, abandon, or clear assignment context — e.g., "clear my assignment",
+  "drop this assignment", "release context", "unclaim this", "I'm not actually
+  working on this anymore". Does not mark the assignment complete or failed.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Clear Assignment
+
+Drop the active assignment binding from the current workspace. The assignment itself is left untouched in `~/.syntaur/projects/.../assignments/` — only the local `.syntaur/context.json` pointer is cleared so the session is no longer scoped to it.
+
+This is the inverse of `grab-assignment`. Unlike `complete-assignment`, it does **not** transition lifecycle state, write a handoff, or close out the work. Use it when:
+
+- The user grabbed the wrong assignment.
+- The user wants to switch focus without finishing or formally reviewing the current one.
+- Session context was set up earlier and is now stale.
+
+If the assignment is actually done, use `complete-assignment` instead so a handoff is recorded and the lifecycle state advances.
+
+## Input
+
+Optional flags from the user:
+
+- `--keep-session` — preserve `sessionId` / `transcriptPath` fields in `context.json` (just strip the assignment fields). Default: full delete.
+- `--unassign` — also run `syntaur unassign <slug> --project <project>` so the assignment is no longer claimed by this agent. Default: leave the claim in place (only the local context is cleared). Skip this flag if the CLI does not support `unassign` in the installed version — fall back to leaving the claim alone and tell the user.
+
+## 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 context to clear." and stop.
+- If the file exists but contains only session fields (`sessionId`, `transcriptPath`) and no `projectSlug` / `assignmentSlug`, tell the user: "No active assignment is bound — only a platform session record exists. Nothing to clear." and stop (unless they explicitly ask to wipe the session record too).
+
+Otherwise extract: `projectSlug`, `assignmentSlug`, `assignmentDir`, `title`.
+
+## Step 2: Confirm with the User
+
+Show the user what is about to be cleared and confirm before touching anything:
+
+> About to clear active assignment context:
+> - Assignment: `<assignmentSlug>` — <title>
+> - Project: `<projectSlug>` (or "standalone" if null)
+> - The assignment itself will NOT be transitioned. Its lifecycle status stays as-is.
+> - Proceed?
+
+Stop if the user says no.
+
+If lifecycle status is `in_progress` and the user has not passed `--complete-instead`, also note:
+
+> Note: this assignment is currently `in_progress`. Clearing context does not change that. If you actually finished it, run `complete-assignment` instead so a handoff is recorded.
+
+## Step 3 (optional): Unassign
+
+If the user passed `--unassign`, run:
+
+```bash
+syntaur unassign <assignment-slug> --project <project-slug>
+```
+
+For standalone assignments use the UUID (the folder name) in place of the slug, and omit `--project`.
+
+If the CLI rejects the command (older versions may not implement `unassign`), report the error and continue — the local context clear in Step 4 still happens.
+
+## Step 4: Clear the Context File
+
+Default behavior — delete the file entirely:
+
+```bash
+rm .syntaur/context.json
+```
+
+If the user passed `--keep-session`, preserve session fields and strip everything else instead:
+
+```bash
+jq '{sessionId, transcriptPath} | with_entries(select(.value != null))' \
+  .syntaur/context.json > .syntaur/context.json.tmp \
+  && mv .syntaur/context.json.tmp .syntaur/context.json
+```
+
+If the resulting file would be empty (`{}`), delete it instead of leaving an empty stub.
+
+Do not delete the `.syntaur/` directory itself — other tooling may use it.
+
+## Step 5: Close Session (optional)
+
+If the original `context.json` included a `sessionId` and the Syntaur dashboard is running, mark the session as cleared so the dashboard does not keep showing it as active:
+
+```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":"cleared","projectSlug":"<project-slug>"}'
+```
+
+If this fails (e.g., dashboard not running, endpoint not present in the installed version), it is non-critical — silently continue.
+
+Skip this step entirely when `--keep-session` is set.
+
+## Step 6: Report to User
+
+Summarize:
+- Which assignment was cleared (slug + title).
+- That its lifecycle status is unchanged (and what that status currently is, if known from frontmatter).
+- Whether the assignment was unassigned via the CLI or the claim was left in place.
+- Suggested next step: `grab-assignment` to claim a different one, or `complete-assignment` if the previous one was actually finished.

package/skills/complete-assignment/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: complete-assignment
+description: >-
+  Write a handoff and transition the current Syntaur assignment to review or completed.
+  Use when the user wants to finish an assignment, write a handoff, or submit work for review.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Complete Assignment
+
+Write a handoff for your current Syntaur assignment and transition it to `review` or `completed`.
+
+## Input
+
+Optional: the user may pass `--complete` to 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 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` first."
+
+Extract: `projectSlug`, `assignmentSlug`, `assignmentDir`, `projectDir`.
+
+## Step 2: Load Playbooks
+
+Read all playbook files from `~/.syntaur/playbooks/`:
+
+```bash
+ls ~/.syntaur/playbooks/*.md 2>/dev/null
+```
+
+Verify your work complies with their rules. If any playbook has completion-related rules (e.g., "run tests before done"), follow them before proceeding.
+
+## Step 3: 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. Superseded todos marked `- [x] ~~Execute [...](./plan-v<N>.md)~~ (superseded by plan-v<N>)` count as resolved — they do not need to be done again.
+
+For each:
+- If you believe it is met / done, note why (what was implemented, where).
+- If it is NOT met / done, flag it clearly.
+
+If any 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?" — stop if the user says no.
+
+## Step 3.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-chronological) under a new `## <ISO 8601 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.>
+```
+
+Bump `entryCount` and set `updated` to the current timestamp in `progress.md`'s frontmatter.
+
+Do NOT add a `## Progress` section to `assignment.md` — progress entries live exclusively in `progress.md` as of protocol v2.0.
+
+## Step 4: 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 this format:
+
+```markdown
+## Handoff <N>: <ISO 8601 timestamp>
+
+**From:** <your-agent-name>
+**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>
+```
+
+Also update the handoff.md frontmatter: set `updated` to the current timestamp and increment the `handoffCount` by 1.
+
+## Step 5: Update Checkboxes (Criteria + Todos)
+
+In `<assignmentDir>/assignment.md`, update checkboxes in both the `## Acceptance Criteria` and `## Todos` sections to reflect the current state. Check off items that were completed (change `- [ ]` to `- [x]`).
+
+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 and note which were verified at completion time vs. during development in the handoff.
+
+Do NOT uncheck or rewrite superseded todo lines matching `- [x] ~~...~~ (superseded by ...)` — preserve that history intact.
+
+## Step 6: Close Session (optional)
+
+If `.syntaur/context.json` includes a `sessionId` and the Syntaur dashboard is running, mark the session as completed:
+
+```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 this fails (e.g., dashboard not running), it is non-critical — the session will be reconciled automatically.
+
+## Step 7: Transition Assignment State
+
+If the user requested `--complete` and all criteria are met:
+
+```bash
+syntaur complete <assignment-slug> --project <project-slug>
+```
+
+Otherwise, transition to review:
+
+```bash
+syntaur review <assignment-slug> --project <project-slug>
+```
+
+If the command fails, report the error. Common failures:
+- Assignment is not in `in_progress` status
+- Project not found
+
+## Step 8: Clean Up Context
+
+Delete the context file:
+
+```bash
+rm .syntaur/context.json
+```
+
+## Step 9: Report to User
+
+Summarize:
+- Assignment slug and title
+- New status (review or completed)
+- Number of acceptance criteria met vs total
+- If transitioned to `review`, a human reviewer will check the work. If any criteria were unmet, they may send it back to `in_progress`.

package/skills/create-assignment/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: create-assignment
+description: >-
+  Create a new Syntaur assignment within a project (or as a standalone one-off).
+  Use when the user wants to add a task, create an assignment, or break down
+  work within a Syntaur project.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.2.0"
+---
+
+# Create Assignment
+
+Create a new assignment — project-nested or standalone.
+
+## Input
+
+Expects arguments from the user:
+
+- First (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`. The folder is named by UUID; `slug` is display-only. `--depends-on` is not permitted for standalone assignments.
+- `--slug <slug>` (optional): override the auto-generated assignment slug
+- `--priority <level>` (optional): `low`, `medium` (default), `high`, or `critical`
+- `--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): comma-separated list of assignment slugs this depends on
+- `--dir <path>` (optional): override the default project directory
+- `--with-todos` (optional): scaffold a `## Todos` section in `assignment.md`. **Omit unless the user explicitly asks for it.** Todos are normally a plan (added by `plan-assignment`) or populated during planning — not something to pre-create at assignment time. Pass this flag only if the user explicitly says something like "include todos", "with a todo list", "scaffold todos", etc.
+
+If no title was provided, ask the user what the assignment should be called.
+
+If neither `--project` nor `--one-off` was provided, check `.syntaur/context.json` for an active assignment. If present, default `--project` to that context's `projectSlug` and confirm with the user: "Add this assignment to project `<projectSlug>`?"
+
+If 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:
+
+```bash
+syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--type <type>] [--depends-on <slugs>] [--dir <path>] [--with-todos]
+```
+
+Or for a one-off (standalone at `~/.syntaur/assignments/<uuid>/`):
+
+```bash
+syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--type <type>] [--dir <path>] [--with-todos]
+```
+
+If the command fails (e.g., project not found, slug collision, invalid type), report the error and suggest fixes.
+
+## Step 2: Read the Created Assignment
+
+After successful creation, extract the assignment slug (and for standalone, the UUID) and directory from the CLI output. Read the generated `assignment.md`:
+
+```bash
+# Project-nested:
+cat ~/.syntaur/projects/<project-slug>/assignments/<assignment-slug>/assignment.md
+
+# Standalone:
+cat ~/.syntaur/assignments/<uuid>/assignment.md
+```
+
+## Step 3: Guide Next Steps
+
+Tell the user:
+- The assignment was created with its slug, priority, type, and location. For standalone assignments, note that the folder is named by UUID (not slug) — `slug` is display-only.
+- 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 the `plan-assignment` skill.
+- Remind the user: `progress.md` is where timestamped progress entries go (NOT `assignment.md`), and `comments.md` is CLI-mediated — write only via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`.
+- Suggest editing `assignment.md` to fill in the objective, acceptance criteria, and context. A `## Todos` section is **not** scaffolded by default — it is added automatically by `plan-assignment` (linking the new plan file) or by `syntaur request` (cross-assignment requests). Only the `--with-todos` flag pre-scaffolds an empty `## Todos` section.
+- If dependencies were set, note them. Standalone assignments cannot declare `dependsOn`.
+- Suggest `grab-assignment <project-slug> <assignment-slug>` (or `grab-assignment --id <uuid>` for standalone) to claim and start working on it.