syntaur 0.3.3 → 0.4.0

package/vendor/syntaur-skills/skills/create-project/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: create-project
+description: >-
+  Create a new Syntaur project with full scaffolding (manifest, indexes,
+  resources, memories). Use when the user wants to start a new project or
+  initiative in Syntaur.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Create Project
+
+Create a new Syntaur project with full scaffolding.
+
+## Input
+
+Expects arguments from the user:
+
+- First (required): the project title (e.g., `"Build Auth System"`)
+- `--slug <slug>` (optional): override the auto-generated slug
+- `--dir <path>` (optional): override the default project directory
+- `--workspace <workspace>` (optional): workspace grouping label (e.g., `syntaur`, `reeva`)
+
+If no title was provided, ask the user what the project should be called.
+
+## Step 1: Run the CLI
+
+```bash
+syntaur create-project "<title>" [--slug <slug>] [--dir <path>] [--workspace <workspace>]
+```
+
+If the command fails (e.g., slug collision, empty title), report the error and suggest fixes.
+
+## Step 2: Read the Created Project
+
+Extract the project slug and directory from the CLI output. Read the generated `project.md` to confirm structure:
+
+```bash
+cat ~/.syntaur/projects/<slug>/project.md
+```
+
+## Step 3: Guide Next Steps
+
+Tell the user:
+
+- The project was created with its slug and location (`~/.syntaur/projects/<slug>/`).
+- Key files scaffolded:
+  - `project.md` — human-authored goal and context (edit this).
+  - `manifest.md` — derived root navigation (do not edit directly).
+  - `_index-assignments.md`, `_index-plans.md`, `_index-decisions.md`, `_status.md` — derived indexes.
+  - `resources/_index.md` and `memories/_index.md` — shared-writable area scaffolding.
+- Per-project `agent.md` / `claude.md` are NOT created — protocol v2.0 removed them. Agent-level conventions live at the repo root in `CLAUDE.md` / `AGENTS.md`, and user-defined behavioral rules live in `~/.syntaur/playbooks/<slug>.md`.
+- Suggest they edit `project.md` to fill in the goal, scope, and context sections.
+- Suggest running `create-assignment "<title>" --project <slug>` to add assignments to this project. Or `create-assignment "<title>" --one-off` for standalone work at `~/.syntaur/assignments/<uuid>/`.

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

@@ -0,0 +1,158 @@
+---
+name: grab-assignment
+description: >-
+  Discover and claim a pending Syntaur assignment from a project (or a
+  standalone one-off). Use when the user wants to start working on a Syntaur
+  assignment, claim a task, or set up their working context.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.1.0"
+---
+
+# Grab Assignment
+
+Claim a pending Syntaur assignment and set up the current workspace.
+
+## Input
+
+Expects up to two arguments from the user:
+
+- First (required): the project slug (e.g., `build-auth-system`), OR `--id <uuid>` to claim a standalone assignment at `~/.syntaur/assignments/<uuid>/`.
+- Second (optional, project-nested only): a specific assignment slug to grab. If omitted, list available pending assignments and pick one.
+
+## Pre-flight Check
+
+Check if `.syntaur/context.json` already exists in the current working directory.
+
+- If it exists AND contains BOTH `projectSlug` and `assignmentSlug`, it represents an active assignment. Warn the user: "You already have an active assignment: `<assignmentSlug>` in project `<projectSlug>`. Grabbing a new one will replace this context. Proceed?" — stop if the user says no.
+- If it exists but only has session fields (`sessionId`, `transcriptPath`) and no project/assignment, it was populated by the platform's SessionStart hook (Claude Code, etc.) and does NOT represent an active assignment. Proceed silently and merge assignment fields on top in Step 5.
+
+## Step 1: Discover the Project (project-nested path)
+
+For a project-nested grab, read the project entry files:
+
+- `~/.syntaur/projects/<project-slug>/manifest.md`
+- `~/.syntaur/projects/<project-slug>/project.md`
+
+Note the `workspace` field in `project.md` frontmatter if present. Per-project `agent.md` / `claude.md` were removed in protocol v2.0 — repo-level `CLAUDE.md` / `AGENTS.md` and user playbooks under `~/.syntaur/playbooks/` take their place. Step 7 loads playbooks.
+
+For a standalone grab (`--id <uuid>`), skip this step — there is no parent project.
+
+## Step 2: Find Assignments
+
+List assignment directories:
+
+- Project-nested: `~/.syntaur/projects/<project-slug>/assignments/`
+- Standalone: the single directory at `~/.syntaur/assignments/<uuid>/`
+
+Do NOT filter by status — every assignment is grabbable. If a slug was provided, verify the directory exists. If no specific assignment was requested, read each `assignment.md` frontmatter and present the list with title, priority, and current status (highlighting `pending` as the likely default). Ask the user to choose unless there is exactly one obvious candidate.
+
+## Step 3: Claim the Assignment
+
+```bash
+# Always safe at any status; does not transition state:
+syntaur assign <assignment-slug> --agent <your-agent-name> --project <project-slug>
+```
+
+If the current status is `pending`, also run:
+
+```bash
+syntaur start <assignment-slug> --project <project-slug>
+```
+
+Skip `start` for any non-`pending` status — grabbing must never rewind a `review`, `completed`, or `failed` assignment.
+
+> **Agent identity:** Use an identifier for your agent platform — e.g., `claude`, `cursor`, `codex`, `opencode`.
+
+If either command fails, report the error and stop.
+
+## Step 4: Read Assignment Context and Backfill Workspace
+
+Read the full assignment file. Also read `comments.md` if present (inherited questions / notes). For each `dependsOn` entry, read the dependency's `handoff.md` AND `decision-record.md` so upstream decisions carry forward.
+
+From the assignment frontmatter extract: `title`, `workspace.repository`, `workspace.worktreePath`, `workspace.branch`, `dependsOn`, `priority`.
+
+If `workspace.repository` and `workspace.worktreePath` are both null, set them to the current working directory. Write boundaries use this path, so it must never be null while an agent is writing code.
+
+## Step 5: Create or Merge Context File
+
+Merge assignment context into `.syntaur/context.json`. Never overwrite — if the file already exists (e.g., platform SessionStart hook populated `sessionId` / `transcriptPath`), preserve those fields.
+
+```bash
+mkdir -p .syntaur
+```
+
+Prepare the assignment payload:
+
+```json
+{
+  "projectSlug": "<project-slug or null for standalone>",
+  "assignmentSlug": "<assignment-slug>",
+  "projectDir": "/absolute/path/to/project or null",
+  "assignmentDir": "/absolute/path/to/assignment",
+  "workspaceRoot": "<workspace path or current working directory>",
+  "title": "<assignment title>",
+  "branch": "<workspace.branch or null>",
+  "grabbedAt": "<ISO 8601 timestamp>"
+}
+```
+
+Merge it on top of whatever context.json already contains:
+
+```bash
+if [ -f .syntaur/context.json ]; then
+  jq --slurpfile new <(echo "$NEW_CONTEXT_JSON") '. + $new[0]' .syntaur/context.json > .syntaur/context.json.tmp \
+    && mv .syntaur/context.json.tmp .syntaur/context.json
+else
+  echo "$NEW_CONTEXT_JSON" > .syntaur/context.json
+fi
+```
+
+Use absolute paths (expand `~` to the home directory). If `workspace.repository` is a remote URL (e.g. `https://github.com/...`), set `workspaceRoot` to the current working directory instead.
+
+## Step 6: Register Agent Session (real IDs only — no UUIDs)
+
+`syntaur track-session` requires a `--session-id` from the agent runtime. Synthetic UUIDs are rejected. Source the real id in this order:
+
+1. If `.syntaur/context.json` already has `sessionId` (platform SessionStart hook populated it), use it and the companion `transcriptPath` if present.
+2. Otherwise, fall back to the per-agent lookup:
+   - **Claude Code**: the most-recently-modified `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` — read its `sessionId`. The transcript path is `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` (omit if the file is absent).
+   - **Codex**: the most-recently-modified file under `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` whose first-line `session_meta.payload.cwd` matches `$(pwd)`. Use `payload.id` as the session id and the full rollout path as the transcript path.
+   - **Other agents**: use whatever real session identifier the runtime exposes. Do not invent one.
+3. If no real id can be resolved, stop and tell the user to restart the session so the platform hook can populate it, or to run `/rename <assignment-slug>` (Claude Code) and retry.
+
+After resolving, merge `sessionId` + `transcriptPath` back into context.json. Then register:
+
+```bash
+syntaur track-session \
+  --project <project-slug> --assignment <assignment-slug> \
+  --agent <your-agent-name> \
+  --session-id <real-id> \
+  --transcript-path <path-if-known> \
+  --path $(pwd)
+```
+
+Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path was resolved.
+
+## Step 7: Load Playbooks
+
+Read all playbook files from `~/.syntaur/playbooks/` and treat their content as active behavioral rules:
+
+```bash
+ls ~/.syntaur/playbooks/*.md 2>/dev/null
+```
+
+For each file, read it and follow its directives. Playbooks take precedence over default conventions when they conflict.
+
+## Step 8: Report to User
+
+Summarize:
+- Which assignment was grabbed (slug + title). Note if it was standalone (folder is the UUID, `slug` display-only).
+- Current status (call it out explicitly if the assignment was already past `pending`).
+- The objective (first paragraph from assignment.md body).
+- The acceptance criteria (checkbox list).
+- Active todos from `## Todos`, including any linked plan files.
+- The workspace path.
+- Any inherited comments/questions from `comments.md`.
+- Suggested next step: `plan-assignment` to create an implementation plan.

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.