syntaur 0.7.1 → 0.8.0

package/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/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/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/skills/track-session/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: track-session
+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
+
+Register the current Claude Code session as an agent session in the Syntaur dashboard. Works standalone or linked to a project/assignment.
+
+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.
+
+## Usage
+
+User arguments: `$ARGUMENTS`
+
+- (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
+
+### Step 1: Parse arguments
+
+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
+
+### 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>]
+```
+
+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>.`
+
+Registration is idempotent — re-running the command with the same session id safely upserts project/assignment/description onto the existing row.
+
+### Step 4: Merge context.json
+
+Ensure `.syntaur/context.json` has the session fields (so SessionEnd and future `track-session` runs find them). Merge, don't overwrite:
+
+```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
+```
+
+### Step 5: Confirm
+
+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/scripts/postinstall-submodules.mjs

@@ -1,40 +0,0 @@
-#!/usr/bin/env node
-// Lazy-init git submodules for contributor clones.
-// Silent no-op for end-user installs (where .git/.gitmodules are absent
-// because npm publish bundles the vendored files directly).
-
-import { existsSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const repoRoot = resolve(here, '..');
-
-const gitDir = resolve(repoRoot, '.git');
-const gitmodules = resolve(repoRoot, '.gitmodules');
-const vendoredSkills = resolve(repoRoot, 'vendor', 'syntaur-skills', 'skills');
-
-// End-user install (from npm): no .git, no .gitmodules. Nothing to do.
-if (!existsSync(gitDir) || !existsSync(gitmodules)) {
-  process.exit(0);
-}
-
-// Contributor already initialized submodules.
-if (existsSync(vendoredSkills)) {
-  process.exit(0);
-}
-
-const result = spawnSync(
-  'git',
-  ['submodule', 'update', '--init', '--recursive'],
-  { cwd: repoRoot, stdio: 'inherit' },
-);
-
-if (result.status !== 0) {
-  console.warn(
-    '[postinstall-submodules] git submodule update failed — ' +
-      'run it manually before building.',
-  );
-  // Do not fail postinstall; let the build step surface the missing files.
-}

package/vendor/syntaur-skills/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Prong Horn
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/vendor/syntaur-skills/README.md

@@ -1,57 +0,0 @@
-# syntaur-skills
-
-Agent-agnostic skills for the [Syntaur](https://github.com/prong-horn/syntaur) coordination protocol. Works with any AI coding agent — Claude Code, Cursor, Codex, OpenCode, and more.
-
-## Prerequisites
-
-Install the Syntaur CLI:
-
-```bash
-npm install -g syntaur
-syntaur setup
-```
-
-## Install
-
-If you use Claude Code or Codex, install the `syntaur` package — these skills ship automatically with its plugin install flow:
-
-```bash
-npm install -g syntaur
-syntaur install-plugin        # Claude Code → ~/.claude/skills/
-syntaur install-codex-plugin  # Codex → ~/.codex/skills/
-```
-
-For any other AI coding agent (Cursor, OpenCode, custom runtimes), install the skills directly:
-
-```bash
-npx skills add prong-horn/syntaur-skills
-```
-
-Or install a specific skill:
-
-```bash
-npx skills add prong-horn/syntaur-skills --skill syntaur-protocol
-```
-
-> **Note:** If you install `syntaur` AND also run `npx skills add prong-horn/syntaur-skills` on the same machine, you'll get the same skills installed once — they use the same names. The `syntaur` CLI detects existing copies and skips already-current ones.
-
-## Skills
-
-| Skill | Description |
-|-------|-------------|
-| `syntaur-protocol` | Core protocol knowledge — write boundaries, lifecycle states, conventions. Auto-activates when working with Syntaur files. |
-| `grab-assignment` | Discover and claim a pending assignment from a project. Sets up working context. |
-| `plan-assignment` | Create a detailed implementation plan for the current assignment. |
-| `complete-assignment` | Write a handoff and transition an assignment to review or completed. |
-| `clear-assignment` | Drop the active assignment from session context without transitioning lifecycle state. Inverse of `grab-assignment`. |
-| `create-project` | Create a new project with full scaffolding (manifest + indexes + resources + memories). |
-| `create-assignment` | Create a new assignment within a project (or as a standalone one-off at `~/.syntaur/assignments/<uuid>/`). |
-| `manage-statuses` | List / add / rename / remove / reorder custom assignment statuses (and transitions); writes to `~/.syntaur/config.md`. |
-
-## How it works
-
-Syntaur is a coordination protocol for AI agents built on markdown files. Projects contain assignments, assignments have lifecycle states, and agents follow write boundary rules about which files they can modify. Everything lives under `~/.syntaur/` and is managed via the `syntaur` CLI.
-
-These skills teach your agent the protocol so it can participate in Syntaur-coordinated work — regardless of which coding agent you use.
-
-For platform-specific integrations (hooks, commands, sandbox enforcement), see the [Syntaur plugin system](https://github.com/prong-horn/syntaur).