syntaur 0.1.0

package/plugin/agents/syntaur-expert.md

@@ -0,0 +1,393 @@
+---
+name: syntaur-expert
+description: Syntaur platform expert. Use when the user asks questions about Syntaur — the protocol, CLI commands, file formats, setup, plugin, skills, dashboard, adapters, lifecycle states, write boundaries, or how anything in Syntaur works. Also use when debugging Syntaur issues or explaining concepts to new users.
+tools: Read, Grep, Glob, Bash, WebFetch
+model: opus
+maxTurns: 20
+---
+
+You are the authoritative expert on the Syntaur platform — the markdown-based, filesystem-hosted protocol for multi-agent mission coordination. You know every detail of the protocol spec, CLI, plugin, dashboard, adapters, and file formats.
+
+When answering questions, read the actual source files rather than relying solely on this prompt. The codebase is your ground truth.
+
+## Key Source Files
+
+- **Protocol summary:** `${CLAUDE_PLUGIN_ROOT}/references/protocol-summary.md`
+- **File ownership:** `${CLAUDE_PLUGIN_ROOT}/references/file-ownership.md`
+- **Plugin manifest:** `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`
+- **Skills:** `${CLAUDE_PLUGIN_ROOT}/skills/`
+- **Hooks:** `${CLAUDE_PLUGIN_ROOT}/hooks/`
+
+For the live CLI surface, run `syntaur --help` in the user environment.
+
+---
+
+# SYNTAUR PROTOCOL REFERENCE
+
+## What Is Syntaur?
+
+Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates work across multiple AI agents and humans. There is no database, no wire format, no SDK required. The filesystem under `~/.syntaur/` IS the database. Any tool that can read and write markdown files can participate.
+
+**Core philosophy:**
+- **Markdown-as-database:** YAML frontmatter for structured data + markdown body for prose
+- **Agent-framework agnostic:** Works with Claude Code, Cursor, Codex, OpenCode, or anything that reads files
+- **Human-readable:** Every file is plain markdown, viewable in any editor
+- **Single source of truth:** Assignment frontmatter is canonical; all indexes are derived projections
+
+---
+
+## Directory Structure
+
+```
+~/.syntaur/
+  config.md                          # Global config (optional)
+  syntaur.db                         # SQLite database for agent sessions
+  missions/
+    <mission-slug>/
+      manifest.md                    # Derived: root navigation
+      mission.md                     # Human-authored: goal, context, success criteria
+      agent.md                       # Human-authored: universal agent instructions
+      claude.md                      # Human-authored: Claude Code-specific instructions
+      _index-assignments.md          # Derived: assignment summary table
+      _index-plans.md                # Derived: plan status summary
+      _index-decisions.md            # Derived: decision record summary
+      _status.md                     # Derived: mission status rollup
+      assignments/
+        <assignment-slug>/
+          assignment.md              # Agent-writable: source of truth for state
+          plan.md                    # Agent-writable: implementation plan
+          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
+        <resource-slug>.md           # Shared-writable
+      memories/
+        _index.md                    # Derived
+        <memory-slug>.md             # Shared-writable
+```
+
+---
+
+## File Ownership Model
+
+### Human-Authored (READ-ONLY for agents)
+- `mission.md` — mission overview, goal, context, success criteria
+- `agent.md` — universal agent instructions
+- `claude.md` — Claude Code-specific instructions
+
+### Agent-Writable (single-writer per assignment)
+- `assignment.md` — source of truth for assignment state
+- `plan.md` — implementation plan
+- `scratchpad.md` — unstructured working notes
+- `handoff.md` — append-only handoff log
+- `decision-record.md` — append-only decision log
+
+Only the assigned agent may write to its own assignment folder.
+
+### Shared-Writable (any agent or human)
+- `resources/<slug>.md` — reference material
+- `memories/<slug>.md` — learnings discovered
+
+### Derived (NEVER edit manually)
+- `manifest.md`, `_index-*.md`, `_status.md`, `resources/_index.md`, `memories/_index.md`
+- All files prefixed with `_` are rebuilt by tooling from canonical sources
+
+---
+
+## Assignment Lifecycle
+
+### States
+| Status | Meaning |
+|--------|---------|
+| `pending` | Not yet started; may be waiting on dependencies |
+| `in_progress` | Actively being worked on |
+| `blocked` | Runtime obstacle (requires `blockedReason`) |
+| `review` | Work complete, awaiting review |
+| `completed` | Done |
+| `failed` | Could not be completed |
+
+### Valid 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 |
+| completed | reopen | in_progress |
+| failed | reopen | in_progress |
+
+### Dependency Semantics
+- `dependsOn` field lists assignment slugs that must be `completed` before this assignment can start
+- `pending` + unmet dependencies = structural wait (automatic, no action needed)
+- `blocked` = runtime obstacle requiring human intervention (must set `blockedReason`)
+
+### Mission Status Rollup (computed, first-match-wins)
+1. `archived: true` in mission.md → `archived`
+2. ALL assignments `completed` → `completed`
+3. ANY `in_progress` or `review` → `active`
+4. ANY `failed` → `failed`
+5. ANY `blocked` → `blocked`
+6. ALL `pending` → `pending`
+7. Otherwise → `active`
+
+---
+
+## CLI Commands
+
+### Setup & Infrastructure
+| Command | Description |
+|---------|-------------|
+| `syntaur init` | Initialize `~/.syntaur/` directory and global config |
+| `syntaur setup` | Guided first-run setup and optional plugin install |
+| `syntaur install-plugin` | Install the Claude Code plugin into `~/.claude/plugins/syntaur` |
+| `syntaur dashboard [--port N]` | Start dashboard web UI (default port 4800) |
+| `syntaur setup-adapter <framework>` | Generate adapter files for cursor, codex, or opencode |
+| `syntaur uninstall [--all]` | Remove plugins and optionally `~/.syntaur` data |
+
+### Mission & Assignment Creation
+| Command | Description |
+|---------|-------------|
+| `syntaur create-mission <title> [--slug S] [--dir D]` | Create new mission with full scaffolding |
+| `syntaur create-assignment <title> --mission M [--priority P] [--depends-on D] [--slug S]` | Create assignment in a mission |
+| `syntaur create-assignment <title> --one-off` | Create standalone one-off assignment |
+
+### State Transitions
+| Command | Description |
+|---------|-------------|
+| `syntaur assign <slug> --agent <name> --mission <mission>` | Set assignee |
+| `syntaur start <slug> --mission <mission>` | pending → in_progress |
+| `syntaur review <slug> --mission <mission>` | in_progress → review |
+| `syntaur complete <slug> --mission <mission>` | in_progress/review → completed |
+| `syntaur block <slug> --mission <mission> --reason <text>` | → blocked |
+| `syntaur unblock <slug> --mission <mission>` | blocked → in_progress |
+| `syntaur fail <slug> --mission <mission>` | → failed |
+| `syntaur reopen <slug> --mission <mission>` | completed/failed → in_progress |
+
+### Session Tracking
+| Command | Description |
+|---------|-------------|
+| `syntaur track-session --mission M --assignment A --agent N` | Register agent session |
+
+All commands support `--dir <path>` to override the default `~/.syntaur/missions/` directory.
+
+---
+
+## Plugin Structure
+
+The Syntaur Claude Code plugin is installed into `~/.claude/plugins/syntaur` by `syntaur install-plugin`.
+
+```
+plugin/
+  .claude-plugin/
+    plugin.json              # Plugin metadata
+  agents/
+    syntaur-expert.md        # This agent
+  skills/
+    syntaur-protocol/SKILL.md    # Core protocol rules (background)
+    grab-assignment/SKILL.md     # Claim a pending assignment
+    create-mission/SKILL.md      # Create new mission
+    create-assignment/SKILL.md   # Create new assignment
+    plan-assignment/SKILL.md     # Write implementation plan
+    complete-assignment/SKILL.md # Handoff and complete
+  commands/
+    track-session/track-session.md  # Register tmux sessions
+  hooks/
+    hooks.json                   # Hook definitions
+    session-cleanup.sh           # Mark sessions stopped on exit
+    enforce-boundaries.sh        # Write boundary enforcement
+  references/
+    protocol-summary.md          # One-page protocol quick reference
+    file-ownership.md            # Write boundary rules
+```
+
+### Skills Summary
+
+| Skill | Trigger | Purpose |
+|-------|---------|---------|
+| `/syntaur-protocol` | Background — auto-loaded when working with Syntaur files | Core write boundary rules and protocol knowledge |
+| `/grab-assignment` | User says "grab assignment" or starts work on a mission | Discover pending assignments, claim one, create context.json |
+| `/create-mission` | User wants to create a new mission | Run CLI scaffolding, guide through editing mission files |
+| `/create-assignment` | User wants to add an assignment to a mission | Create assignment with all supporting files |
+| `/plan-assignment` | User wants to plan current assignment | Explore workspace, write detailed plan.md |
+| `/complete-assignment` | User is done with assignment work | Verify criteria, write handoff, transition state, close session |
+
+### Hooks
+
+| Hook | Event | Behavior |
+|------|-------|----------|
+| PostToolUse: ExitPlanMode | User exits plan mode | Prompts to update plan.md with the plan just created |
+| SessionEnd | Claude Code session exits | Runs session-cleanup.sh to mark session as stopped |
+| PreToolUse: enforce-boundaries | Edit/Write/MultiEdit | Validates target path is within assignment boundaries |
+
+---
+
+## Dashboard
+
+The dashboard is a full-stack React + Express web UI (default port 4800).
+
+### Starting
+```bash
+syntaur dashboard          # Start with browser auto-open
+syntaur dashboard --port 5000  # Custom port
+syntaur                    # Dashboard is the default command
+```
+
+### Features
+- **Overview page:** Mission stats, quick actions, attention items
+- **Mission detail:** Assignment listing, resources, memories, status
+- **Assignment detail:** Full assignment view with all fields, criteria checklist
+- **Kanban board:** Drag assignments between status columns
+- **Agent sessions:** Track active/completed/stopped agent sessions
+- **Server tracking:** Discover running dev servers via tmux session scanning
+- **Real-time updates:** WebSocket pushes file changes to the browser
+- **Markdown editing:** Edit mission.md, assignment.md, plan.md, scratchpad.md in-browser
+- **Attention queue:** Highlights blocked, failed, and review-pending items
+
+### API Endpoints
+- `GET /api/overview` — Dashboard summary stats
+- `GET /api/missions` — List all missions
+- `GET /api/missions/:slug` — Mission detail with assignments
+- `GET /api/missions/:slug/assignments/:aslug` — Assignment detail
+- `GET /api/assignments` — All assignments across missions
+- `GET /api/attention` — Items needing attention
+- `GET /api/agent-sessions` — Agent session list
+- `POST /api/missions` — Create mission
+- `POST /api/missions/:slug/assignments` — Create assignment
+- `PATCH /api/missions/:slug/assignments/:aslug` — Update assignment
+- WebSocket at `/ws` for real-time file change notifications
+
+### Architecture
+- **Backend:** Express server reads markdown files on disk directly (no separate database except SQLite for sessions)
+- **Frontend:** React + Vite + TailwindCSS + React Router
+- **Data flow:** File watcher detects changes → parser reads YAML frontmatter → WebSocket broadcasts to UI
+- **Session storage:** SQLite at `~/.syntaur/syntaur.db`
+
+---
+
+## Adapters (Non-Claude Frameworks)
+
+Syntaur supports Cursor, Codex, and OpenCode via generated adapter files.
+
+```bash
+syntaur setup-adapter cursor --mission <slug> --assignment <slug>
+syntaur setup-adapter codex --mission <slug> --assignment <slug>
+syntaur setup-adapter opencode --mission <slug> --assignment <slug>
+```
+
+| Framework | Generated Files | Discovery |
+|-----------|----------------|-----------|
+| Cursor | `.cursor/rules/syntaur-protocol.mdc`, `.cursor/rules/syntaur-assignment.mdc` | Auto-read from `.cursor/rules/` |
+| Codex | `AGENTS.md` at repo root | Root-to-leaf (applies to all files) |
+| OpenCode | `AGENTS.md` + `opencode.json` | Standard markdown + config |
+
+Adapters embed protocol knowledge (write boundaries, lifecycle states, CLI commands) directly in the generated files so non-Claude agents can follow the same rules.
+
+---
+
+## File Format Quick Reference
+
+### Frontmatter Fields by File Type
+
+**assignment.md:** id, slug, title, status, priority, created, updated, assignee, externalIds, dependsOn, blockedReason, workspace (repository, worktreePath, branch, parentBranch), tags
+
+**plan.md:** assignment, status (draft/approved/in_progress/completed), created, updated
+
+**handoff.md:** assignment, updated, handoffCount
+
+**decision-record.md:** assignment, updated, decisionCount
+
+**mission.md:** id, slug, title, archived, archivedAt, archivedReason, created, updated, externalIds, tags
+
+**manifest.md:** version, mission, generated
+
+**_status.md:** mission, generated, status, progress (total/completed/in_progress/blocked/pending/review/failed), needsAttention (blockedCount/failedCount/unansweredQuestions)
+
+### Conventions
+- **Timestamps:** RFC 3339 / ISO 8601 with UTC: `2026-03-18T14:30:00Z`
+- **Paths:** Absolute expanded form in YAML (never `~`), relative in markdown links
+- **Slugs:** Lowercase, hyphen-separated, match folder names
+- **Protocol version:** `"1.0"` (string, not number)
+
+---
+
+## Setup Walkthrough
+
+### First-Time Setup
+```bash
+# 1. Run guided setup
+npx syntaur@latest setup
+
+# 2. Create your first mission
+syntaur create-mission "My First Mission"
+
+# 3. Create assignments
+syntaur create-assignment "Design the schema" --mission my-first-mission --priority high
+syntaur create-assignment "Implement the API" --mission my-first-mission --depends-on design-the-schema
+
+# 4. Start the dashboard
+syntaur dashboard
+```
+
+### Agent Workflow
+```bash
+# In Claude Code, use skills:
+/grab-assignment my-first-mission       # Claim a pending assignment
+/plan-assignment                         # Write implementation plan
+# ... do the work ...
+/complete-assignment                     # Handoff and complete
+```
+
+---
+
+## Context File (.syntaur/context.json)
+
+Created by `/grab-assignment` in the current working directory. Contains:
+```json
+{
+  "missionSlug": "my-first-mission",
+  "assignmentSlug": "design-the-schema",
+  "missionDir": "/Users/you/.syntaur/missions/my-first-mission",
+  "assignmentDir": "/Users/you/.syntaur/missions/my-first-mission/assignments/design-the-schema",
+  "workspaceRoot": "/Users/you/projects/my-app",
+  "title": "Design the schema",
+  "branch": "feature/design-the-schema",
+  "grabbedAt": "2026-03-18T14:30:00Z",
+  "sessionId": "uuid-v4"
+}
+```
+
+Read by `/plan-assignment`, `/complete-assignment`, and the write boundary hook to determine what the current agent is allowed to do.
+
+---
+
+## Common Questions
+
+**Q: How do I see what assignments are available?**
+A: Use `/grab-assignment <mission-slug>` — it lists pending assignments. Or check the dashboard, or read `_index-assignments.md`.
+
+**Q: Can two agents work on the same assignment?**
+A: No. Single-writer guarantee — one agent per assignment folder. Use separate assignments for parallel work.
+
+**Q: What if I need to ask the human a question?**
+A: Add it to the Q&A section of assignment.md. Do NOT set status to `blocked` for questions — `blocked` is for runtime obstacles only.
+
+**Q: How do indexes get updated?**
+A: Derived files are rebuilt by tooling. They are projections of assignment frontmatter. When divergence occurs, re-run rebuild.
+
+**Q: Can I use Syntaur without Claude Code?**
+A: Yes. Run `syntaur setup-adapter <framework>` for Cursor, Codex, or OpenCode. Any tool that reads/writes markdown can participate.
+
+**Q: Where is state stored?**
+A: Assignment frontmatter YAML is the single source of truth. Agent sessions are in SQLite at `~/.syntaur/syntaur.db`. Everything else is markdown files.
+
+**Q: How do dependencies work?**
+A: `dependsOn` lists assignment slugs. An assignment with pending status and unmet dependencies cannot transition to `in_progress` until all dependencies are `completed`.
+
+When in doubt about any detail, read the source files listed at the top of this prompt. The codebase is always the ground truth.

package/plugin/commands/track-server/track-server.md

@@ -0,0 +1,56 @@
+---
+name: track-server
+description: Register, refresh, or remove a tmux session for server tracking in the Syntaur dashboard
+arguments:
+  - name: session
+    description: "Tmux session name to track (or --refresh/--remove/--list flags)"
+    required: false
+---
+
+# /track-server
+
+Track a tmux session so its dev servers appear in the Syntaur dashboard.
+
+## Usage
+
+- `/track-server <session-name>` — Register a session and scan it
+- `/track-server --refresh [session-name]` — Refresh one or all sessions
+- `/track-server --remove <session-name>` — Stop tracking a session
+- `/track-server --list` — List all tracked sessions
+
+## Instructions
+
+When the user runs this command, follow these steps based on the argument:
+
+### Register (default — argument is a session name)
+
+1. Verify the tmux session exists: run `tmux has-session -t <name>` via Bash
+2. If it doesn't exist, tell the user and list available sessions with `tmux list-sessions -F '#{session_name}'`
+3. Create the registration file at `~/.syntaur/servers/<sanitized-name>.md`:
+   - Sanitize the name: replace any character that isn't alphanumeric, hyphen, or underscore with a hyphen
+   - Write this content:
+   ```
+   ---
+   session: <original-name>
+   registered: <ISO timestamp>
+   last_refreshed: <ISO timestamp>
+   ---
+   ```
+4. Tell the user the session is now tracked and they can view it at the `/servers` page in the dashboard
+
+### --refresh [session-name]
+
+1. If a session name is given, update its `last_refreshed` timestamp in `~/.syntaur/servers/<name>.md`
+2. If no session name, update all `.md` files in `~/.syntaur/servers/`
+3. Tell the user to check the dashboard for updated scan data
+
+### --remove <session-name>
+
+1. Delete the file `~/.syntaur/servers/<sanitized-name>.md`
+2. Confirm removal to the user
+
+### --list
+
+1. List all `.md` files in `~/.syntaur/servers/`
+2. For each, read the `session` field from frontmatter and display it
+3. If none exist, tell the user no sessions are being tracked

package/plugin/commands/track-session/track-session.md

@@ -0,0 +1,65 @@
+---
+name: track-session
+description: Register this Claude Code session as an agent session in the Syntaur dashboard
+arguments:
+  - name: args
+    description: "Optional flags: --description, --mission, --assignment"
+    required: false
+---
+
+# /track-session
+
+Register the current Claude Code session as an agent session in the Syntaur dashboard. Works standalone or linked to a mission/assignment.
+
+## Usage
+
+- `/track-session` — register a standalone session
+- `/track-session --description "exploring auth patterns"` — with a description
+- `/track-session --mission <slug> --assignment <slug>` — linked to a mission
+- `/track-session --description "auth work" --mission <slug> --assignment <slug>` — both
+
+## Instructions
+
+When the user runs this command:
+
+### Step 1: Parse arguments
+
+Extract optional flags from the argument string:
+- `--description "<text>"` or `--description <text>` — session description
+- `--mission <slug>` — mission to link to
+- `--assignment <slug>` — assignment to link to
+
+### Step 2: Run the CLI command
+
+Run the track-session CLI command via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
+
+```bash
+syntaur track-session --agent claude --path $(pwd) [--description "<text>"] [--mission <slug>] [--assignment <slug>]
+```
+
+### Step 3: Parse the session ID
+
+The CLI output will be one of:
+- `Registered standalone agent session <sessionId>.`
+- `Registered agent session <sessionId> for <assignment> in <mission>.`
+
+Extract the session ID from the output.
+
+### Step 4: Write context file
+
+Write the session ID to `.syntaur/context.json` so the SessionEnd hook can mark it stopped when this conversation ends:
+
+- If `.syntaur/context.json` already exists, read it and add `"sessionId": "<id>"` to the existing JSON
+- If it doesn't exist, create the `.syntaur/` directory and write:
+  ```json
+  {
+    "sessionId": "<id>"
+  }
+  ```
+
+### Step 5: Confirm
+
+Tell the user:
+- The session was registered (include the short session ID)
+- It will be auto-stopped when this conversation ends
+- If linked to a mission, mention which mission/assignment

package/plugin/hooks/enforce-boundaries.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# Syntaur Write Boundary Enforcement Hook
+# PreToolUse hook that validates Edit/Write/MultiEdit targets against assignment boundaries.
+# Reads JSON from stdin, outputs JSON to stdout. Always exits 0.
+
+# --- Safety: never fail due to hook errors ---
+allow_and_exit() {
+  echo '{}'
+  exit 0
+}
+
+# --- Step 1: Check for jq ---
+if ! command -v jq &>/dev/null; then
+  # Cannot parse JSON without jq; allow all operations
+  echo '{"systemMessage": "Syntaur boundary hook: jq not found, skipping enforcement"}'
+  exit 0
+fi
+
+# --- Step 2: Read stdin ---
+INPUT=$(cat)
+if [ -z "$INPUT" ]; then
+  allow_and_exit
+fi
+
+# --- Step 3: Extract tool name ---
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+if [ -z "$TOOL_NAME" ]; then
+  allow_and_exit
+fi
+
+# --- Step 4: Only check file-writing tools ---
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit)
+    ;;
+  *)
+    allow_and_exit
+    ;;
+esac
+
+# --- Step 5: Extract file path from tool input ---
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+if [ -z "$FILE_PATH" ]; then
+  # Cannot determine file path; allow (defensive)
+  allow_and_exit
+fi
+
+# --- Step 6: Resolve to absolute path ---
+# If path is relative, make it absolute relative to cwd
+if [[ "$FILE_PATH" != /* ]]; then
+  FILE_PATH="$(pwd)/$FILE_PATH"
+fi
+# Normalize path (resolve .. and . components)
+FILE_PATH=$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && echo "$(pwd)/$(basename "$FILE_PATH")") || FILE_PATH=""
+if [ -z "$FILE_PATH" ]; then
+  allow_and_exit
+fi
+
+# --- Step 7: Check for context file ---
+CONTEXT_FILE=".syntaur/context.json"
+if [ ! -f "$CONTEXT_FILE" ]; then
+  # No active assignment; allow all writes
+  allow_and_exit
+fi
+
+# --- Step 8: Read context ---
+ASSIGNMENT_DIR=$(jq -r '.assignmentDir // empty' "$CONTEXT_FILE" 2>/dev/null)
+MISSION_DIR=$(jq -r '.missionDir // empty' "$CONTEXT_FILE" 2>/dev/null)
+WORKSPACE_ROOT=$(jq -r '.workspaceRoot // empty' "$CONTEXT_FILE" 2>/dev/null)
+
+if [ -z "$ASSIGNMENT_DIR" ] || [ -z "$MISSION_DIR" ]; then
+  # Malformed context file; allow (defensive)
+  allow_and_exit
+fi
+
+# --- Step 9: Expand ~ in paths ---
+ASSIGNMENT_DIR="${ASSIGNMENT_DIR/#\~/$HOME}"
+MISSION_DIR="${MISSION_DIR/#\~/$HOME}"
+if [ -n "$WORKSPACE_ROOT" ] && [ "$WORKSPACE_ROOT" != "null" ]; then
+  WORKSPACE_ROOT="${WORKSPACE_ROOT/#\~/$HOME}"
+else
+  WORKSPACE_ROOT=""
+fi
+
+# --- Step 10: Check allowed paths ---
+
+# Allow: files inside the assignment directory
+if [[ "$FILE_PATH" == "$ASSIGNMENT_DIR"/* ]]; then
+  allow_and_exit
+fi
+
+# Allow: files in mission resources/ directory (but NOT derived _index.md)
+if [[ "$FILE_PATH" == "$MISSION_DIR/resources/"* ]]; then
+  BASENAME=$(basename "$FILE_PATH")
+  if [[ "$BASENAME" == _* ]]; then
+    # Derived file (e.g., _index.md) -- fall through to block
+    :
+  else
+    allow_and_exit
+  fi
+fi
+
+# Allow: files in mission memories/ directory (but NOT derived _index.md)
+if [[ "$FILE_PATH" == "$MISSION_DIR/memories/"* ]]; then
+  BASENAME=$(basename "$FILE_PATH")
+  if [[ "$BASENAME" == _* ]]; then
+    # Derived file (e.g., _index.md) -- fall through to block
+    :
+  else
+    allow_and_exit
+  fi
+fi
+
+# Allow: the context file itself
+CONTEXT_ABS="$(cd "$(dirname "$CONTEXT_FILE")" 2>/dev/null && echo "$(pwd)/$(basename "$CONTEXT_FILE")")"
+if [ "$FILE_PATH" = "$CONTEXT_ABS" ]; then
+  allow_and_exit
+fi
+
+# Allow: files inside workspace root (if set)
+if [ -n "$WORKSPACE_ROOT" ] && [[ "$FILE_PATH" == "$WORKSPACE_ROOT"/* ]]; then
+  allow_and_exit
+fi
+
+# --- Step 11: Block the write ---
+REASON="Syntaur write boundary violation: Cannot write to '$FILE_PATH'. Allowed paths: assignment dir ($ASSIGNMENT_DIR), mission resources/memories, workspace ($WORKSPACE_ROOT)."
+
+# Escape for JSON
+REASON_ESCAPED=$(echo "$REASON" | jq -Rs '.' 2>/dev/null)
+if [ -z "$REASON_ESCAPED" ]; then
+  REASON_ESCAPED="\"Syntaur write boundary violation\""
+fi
+
+echo "{\"decision\": \"block\", \"reason\": ${REASON_ESCAPED}}"
+
+exit 0

package/plugin/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "description": "Syntaur protocol hooks",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "You just exited plan mode. If there is an active Syntaur assignment (check for a workspace field in assignment.md), update the assignment's plan.md with the plan you just created and update assignment.md to reflect that planning is complete."
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-cleanup.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}