syntaur 0.2.0 → 0.3.0

package/examples/playbooks/keep-records-updated.md

@@ -1,10 +1,10 @@
 ---
 name: "Keep Records Updated"
 slug: keep-records-updated
-description: "Agents must keep assignment.md progress, sessions, and criteria current in real-time"
+description: "Agents must keep assignment.md criteria, progress.md, and related records current in real-time"
 when_to_use: "After every meaningful action, when completing acceptance criteria, when starting or stopping work"
 created: "2026-04-02T00:00:00Z"
-updated: "2026-04-02T00:00:00Z"
+updated: "2026-04-20T00:00:00Z"
 tags:
   - protocol
   - recordkeeping
@@ -13,18 +13,24 @@ tags:
 # Keep Records Updated
 
 ## After every meaningful action:
-- Update the `## Progress` section in assignment.md with what you did
-- Use reverse-chronological order (newest first)
-- Include timestamps
+- Append a new entry to `progress.md` with what you did
+- Progress entries live in `progress.md` (reverse-chronological order, newest first with a `## <ISO 8601 timestamp>` heading). Do NOT add a `## Progress` section to `assignment.md` — that section is removed as of protocol v2.0.
+- Bump `entryCount` and `updated` in `progress.md`'s frontmatter.
 
 ## When you complete an acceptance criterion:
-- Check it off in the `## Acceptance Criteria` section immediately
+- Check it off in the `## Acceptance Criteria` section of `assignment.md` immediately
 - Do not batch these up -- mark them as you go
 
+## When you have a question, note, or piece of feedback:
+- Run `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`
+- Never edit `comments.md` directly — all writes are CLI-mediated
+- Questions carry a `resolved` flag that can be toggled from the dashboard
+
 ## When starting work:
-- Add a progress entry noting you've begun and what your approach is
+- Append an entry to `progress.md` noting you've begun and what your approach is
 - If any plan files exist (plan.md, plan-v2.md, ...), update their task checkboxes as you complete steps
 
 ## When stopping or handing off:
-- Write a final progress entry summarizing current state
+- Append a final entry to `progress.md` summarizing current state
+- Write a structured handoff entry in `handoff.md`
 - Note anything the next agent needs to know

package/examples/playbooks/read-before-plan.md

@@ -4,7 +4,7 @@ slug: read-before-plan
 description: "Agents must read all project context files before creating or modifying a plan"
 when_to_use: "Before creating or modifying any plan file (plan.md, plan-v2.md, ...)"
 created: "2026-04-02T00:00:00Z"
-updated: "2026-04-02T00:00:00Z"
+updated: "2026-04-20T00:00:00Z"
 tags:
   - protocol
   - planning
@@ -14,14 +14,17 @@ tags:
 
 Before creating or modifying any plan file (plan.md, plan-v2.md, ...), read these files in order:
 
+For project-nested assignments:
 1. `manifest.md` -- understand the project structure
 2. `project.md` -- understand the goal and scope
-3. `agent.md` -- understand conventions and constraints
-4. `claude.md` (if exists) -- Claude-specific instructions
-5. `assignment.md` -- understand your specific task, acceptance criteria, and dependencies
+3. `assignment.md` -- understand your specific task, acceptance criteria, and dependencies. Frontmatter includes `project: <slug> | null` and `type: <classification> | null`.
+4. `progress.md` (if exists) -- reverse-chron log of what has been done on this assignment
+5. `comments.md` (if exists) -- open questions, notes, and feedback
 6. `handoff.md` (if exists) -- understand what previous agents did and learned
 7. `decision-record.md` (if exists) -- understand past decisions and their rationale
 
+For standalone assignments (at `~/.syntaur/assignments/<uuid>/`), skip `manifest.md` and `project.md` — those only exist for project-nested assignments.
+
 Do NOT skip files because you think you know what's in them. Context from prior agents is often critical.
 
-If the assignment has `dependsOn` entries, read those assignments too -- understand what they produced and any interfaces you need to conform to.
+If the assignment has `dependsOn` entries, read those assignments too -- and read **their** `decision-record.md` first. Upstream decisions are binding constraints you must not silently contradict. (The grab-assignment skill auto-loads these.)

package/examples/sample-project/_status.md

@@ -44,4 +44,4 @@ graph TD
 
 - **0 blocked** assignments
 - **0 failed** assignments
-- **1 unanswered** question in [implement-jwt-middleware](./assignments/implement-jwt-middleware/assignment.md)
+- **1 open** question in [implement-jwt-middleware/comments.md](./assignments/implement-jwt-middleware/comments.md)

package/examples/sample-project/assignments/design-auth-schema/assignment.md

@@ -2,6 +2,8 @@
 id: d1e2f3a4-b5c6-7890-abcd-111111111111
 slug: design-auth-schema
 title: Design Auth Database Schema
+project: build-auth-system
+type: feature
 status: completed
 priority: high
 created: "2026-03-15T09:30:00Z"
@@ -40,25 +42,10 @@ Design the PostgreSQL database schema for the authentication system. This includ
 
 This is the foundational data layer for the auth system. The schema must support the JWT middleware (implement-jwt-middleware) and be testable (write-auth-tests). See [Auth Requirements](../../resources/auth-requirements.md) for functional specs.
 
-## Questions & Answers
-
-### Q: Should we use UUIDs or auto-incrementing integers for user IDs?
-**Asked:** 2026-03-16T10:00:00Z
-**A:** Use UUIDs (v4). They avoid enumeration attacks and simplify future sharding. Generate them in the application layer, not the database.
-
-## Progress
-
-### 2026-03-17T10:00:00Z
-Completed all migration scripts and schema design. Final schema includes three tables: `users`, `sessions`, and `refresh_tokens`. Added composite index on `sessions(user_id, revoked_at)` for the active-session lookup query. All migrations tested against a clean database. Ready for handoff to JWT middleware implementation.
-
-### 2026-03-16T14:00:00Z
-Draft schema complete for users and sessions tables. Working on refresh token rotation tracking. Decided to add a `token_family` column to detect reuse of old refresh tokens.
-
-### 2026-03-16T09:30:00Z
-Started schema design. Reviewed auth requirements document. Planning three tables: users, sessions, refresh_tokens.
-
 ## Links
 
+- [Progress](./progress.md)
+- [Comments](./comments.md)
 - [Scratchpad](./scratchpad.md)
 - [Handoff](./handoff.md)
 - [Decision Record](./decision-record.md)

package/examples/sample-project/assignments/design-auth-schema/comments.md

@@ -0,0 +1,26 @@
+---
+assignment: design-auth-schema
+entryCount: 2
+generated: "2026-03-17T10:00:00Z"
+updated: "2026-03-16T10:05:00Z"
+---
+
+# Comments
+
+## c-1
+
+**Recorded:** 2026-03-16T10:00:00Z
+**Author:** claude-2
+**Type:** question
+**Resolved:** true
+
+Should we use UUIDs or auto-incrementing integers for user IDs?
+
+## c-2
+
+**Recorded:** 2026-03-16T10:05:00Z
+**Author:** human
+**Type:** note
+**Reply to:** c-1
+
+Use UUIDs (v4). They avoid enumeration attacks and simplify future sharding. Generate them in the application layer, not the database.

package/examples/sample-project/assignments/design-auth-schema/progress.md

@@ -0,0 +1,20 @@
+---
+assignment: design-auth-schema
+entryCount: 3
+generated: "2026-03-16T09:30:00Z"
+updated: "2026-03-17T10:00:00Z"
+---
+
+# Progress
+
+## 2026-03-17T10:00:00Z
+
+Completed all migration scripts and schema design. Final schema includes three tables: `users`, `sessions`, and `refresh_tokens`. Added composite index on `sessions(user_id, revoked_at)` for the active-session lookup query. All migrations tested against a clean database. Ready for handoff to JWT middleware implementation.
+
+## 2026-03-16T14:00:00Z
+
+Draft schema complete for users and sessions tables. Working on refresh token rotation tracking. Decided to add a `token_family` column to detect reuse of old refresh tokens.
+
+## 2026-03-16T09:30:00Z
+
+Started schema design. Reviewed auth requirements document. Planning three tables: users, sessions, refresh_tokens.

package/examples/sample-project/assignments/implement-jwt-middleware/assignment.md

@@ -2,6 +2,8 @@
 id: d1e2f3a4-b5c6-7890-abcd-222222222222
 slug: implement-jwt-middleware
 title: Implement JWT Authentication Middleware
+project: build-auth-system
+type: feature
 status: in_progress
 priority: high
 created: "2026-03-15T09:30:00Z"
@@ -44,25 +46,10 @@ Implement Express.js middleware that validates JWT access tokens on protected ro
 
 Depends on the database schema from [design-auth-schema](../design-auth-schema/assignment.md). The schema is complete — see the [handoff notes](../design-auth-schema/handoff.md) for integration details. Key table: `sessions` with `jti` column for token validation. See [Auth Requirements](../../resources/auth-requirements.md) for full specs.
 
-## Questions & Answers
-
-### Q: Should the refresh token endpoint require the old access token or just the refresh token?
-**Asked:** 2026-03-18T11:00:00Z
-**A:** pending
-
-## Progress
-
-### 2026-03-18T14:30:00Z
-Implemented role-based route guard middleware (`requireRole`). Working on the refresh token endpoint next. The token generation and basic validation middleware are working and passing manual tests. Need to wire up the refresh token rotation logic using the `token_family` pattern from the schema design.
-
-### 2026-03-18T10:00:00Z
-JWT validation middleware is functional. It extracts the token from the Authorization header, verifies the RS256 signature, checks expiry, and looks up the `jti` in the sessions table to confirm the session is not revoked. Added proper error responses for expired, invalid, and revoked tokens.
-
-### 2026-03-17T10:30:00Z
-Started implementation. Set up RS256 key pair loading from environment variables. Implemented `generateAccessToken` and `generateRefreshToken` functions. Created the login endpoint that authenticates with bcrypt and returns both tokens.
-
 ## Links
 
+- [Progress](./progress.md)
+- [Comments](./comments.md)
 - [Scratchpad](./scratchpad.md)
 - [Handoff](./handoff.md)
 - [Decision Record](./decision-record.md)

package/examples/sample-project/assignments/implement-jwt-middleware/comments.md

@@ -0,0 +1,17 @@
+---
+assignment: implement-jwt-middleware
+entryCount: 1
+generated: "2026-03-18T11:00:00Z"
+updated: "2026-03-18T11:00:00Z"
+---
+
+# Comments
+
+## c-1
+
+**Recorded:** 2026-03-18T11:00:00Z
+**Author:** claude-1
+**Type:** question
+**Resolved:** false
+
+Should the refresh token endpoint require the old access token or just the refresh token?

package/examples/sample-project/assignments/implement-jwt-middleware/progress.md

@@ -0,0 +1,20 @@
+---
+assignment: implement-jwt-middleware
+entryCount: 3
+generated: "2026-03-17T10:30:00Z"
+updated: "2026-03-18T14:30:00Z"
+---
+
+# Progress
+
+## 2026-03-18T14:30:00Z
+
+Implemented role-based route guard middleware (`requireRole`). Working on the refresh token endpoint next. The token generation and basic validation middleware are working and passing manual tests. Need to wire up the refresh token rotation logic using the `token_family` pattern from the schema design.
+
+## 2026-03-18T10:00:00Z
+
+JWT validation middleware is functional. It extracts the token from the Authorization header, verifies the RS256 signature, checks expiry, and looks up the `jti` in the sessions table to confirm the session is not revoked. Added proper error responses for expired, invalid, and revoked tokens.
+
+## 2026-03-17T10:30:00Z
+
+Started implementation. Set up RS256 key pair loading from environment variables. Implemented `generateAccessToken` and `generateRefreshToken` functions. Created the login endpoint that authenticates with bcrypt and returns both tokens.

package/examples/sample-project/assignments/write-auth-tests/assignment.md

@@ -2,6 +2,8 @@
 id: d1e2f3a4-b5c6-7890-abcd-333333333333
 slug: write-auth-tests
 title: Write Auth System Tests
+project: build-auth-system
+type: feature
 status: pending
 priority: medium
 created: "2026-03-15T09:30:00Z"
@@ -42,16 +44,10 @@ Write comprehensive unit and integration tests for the authentication system, co
 
 This assignment depends on [implement-jwt-middleware](../implement-jwt-middleware/assignment.md) being completed. Tests will cover both the schema layer (from design-auth-schema) and the middleware/endpoint layer (from implement-jwt-middleware). Use Jest as the test framework with `supertest` for HTTP integration tests.
 
-## Questions & Answers
-
-No questions yet.
-
-## Progress
-
-No progress yet.
-
 ## Links
 
+- [Progress](./progress.md)
+- [Comments](./comments.md)
 - [Scratchpad](./scratchpad.md)
 - [Handoff](./handoff.md)
 - [Decision Record](./decision-record.md)

package/examples/sample-project/assignments/write-auth-tests/comments.md

@@ -0,0 +1,10 @@
+---
+assignment: write-auth-tests
+entryCount: 0
+generated: "2026-03-15T09:30:00Z"
+updated: "2026-03-15T09:30:00Z"
+---
+
+# Comments
+
+No comments yet.

package/examples/sample-project/assignments/write-auth-tests/progress.md

@@ -0,0 +1,10 @@
+---
+assignment: write-auth-tests
+entryCount: 0
+generated: "2026-03-15T09:30:00Z"
+updated: "2026-03-15T09:30:00Z"
+---
+
+# Progress
+
+No progress yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {

package/platforms/claude-code/agents/syntaur-expert.md

@@ -46,8 +46,6 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
     <project-slug>/
       manifest.md                    # Derived: root navigation
       project.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
@@ -56,6 +54,8 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
         <assignment-slug>/
           assignment.md              # Agent-writable: source of truth for state (includes ## Todos)
           plan*.md                   # Agent-writable: versioned implementation plans (0+, optional)
+          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
@@ -65,6 +65,15 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
       memories/
         _index.md                    # Derived
         <memory-slug>.md             # Shared-writable
+  assignments/
+    <assignment-id>/                 # Standalone assignments — folder = UUID, project: null, slug display-only
+      assignment.md
+      plan*.md
+      progress.md
+      comments.md
+      scratchpad.md
+      handoff.md
+      decision-record.md
 ```
 
 ---
@@ -73,18 +82,21 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
 
 ### Human-Authored (READ-ONLY for agents)
 - `project.md` — project 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 (includes `## Todos` checklist)
+- `assignment.md` — source of truth for assignment state (includes `## Todos` checklist). `## Todos` is also the landing spot for cross-assignment requests.
 - `plan*.md` — versioned implementation plans (optional, one per `## Todos` entry: `plan.md`, `plan-v2.md`, ...)
+- `progress.md` — append-only timestamped progress log (newest first). Replaces the old `## Progress` body section.
 - `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.
 
+### CLI-Mediated Shared-Writable
+- `comments.md` — threaded questions/notes/feedback. Writes via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback [--reply-to <id>]`. Never edit directly.
+- Another assignment's `## Todos` — writes via `syntaur request <source> <target> "text"`. Appends annotated `(from: <source>)`.
+
 ### Shared-Writable (any agent or human)
 - `resources/<slug>.md` — reference material
 - `memories/<slug>.md` — learnings discovered
@@ -155,8 +167,14 @@ Only the assigned agent may write to its own assignment folder.
 | Command | Description |
 |---------|-------------|
 | `syntaur create-project <title> [--slug S] [--dir D]` | Create new project with full scaffolding |
-| `syntaur create-assignment <title> --project M [--priority P] [--depends-on D] [--slug S]` | Create assignment in a project |
-| `syntaur create-assignment <title> --one-off` | Create standalone one-off assignment |
+| `syntaur create-assignment <title> --project M [--priority P] [--depends-on D] [--slug S] [--type T]` | Create assignment in a project |
+| `syntaur create-assignment <title> --one-off [--type T]` | Create standalone assignment at `~/.syntaur/assignments/<uuid>/` (project: null, slug display-only) |
+
+### Coordination (CLI-mediated writes)
+| Command | Description |
+|---------|-------------|
+| `syntaur comment <slug-or-uuid> "body" --type question\|note\|feedback [--reply-to <id>] [--project <slug>]` | Append to `comments.md`. Questions carry a resolve flag toggleable in the dashboard. |
+| `syntaur request <target> "text" [--from <source>] [--project <slug>]` | Append a todo to another assignment's `## Todos`, annotated `(from: <source>)`. |
 
 ### State Transitions
 | Command | Description |
@@ -295,10 +313,14 @@ Adapters embed protocol knowledge (write boundaries, lifecycle states, CLI comma
 
 ### Frontmatter Fields by File Type
 
-**assignment.md:** id, slug, title, status, priority, created, updated, assignee, externalIds, dependsOn, blockedReason, workspace (repository, worktreePath, branch, parentBranch), tags
+**assignment.md:** id, slug, title, **project (slug or null)**, **type (string or null)**, status, priority, created, updated, assignee, externalIds, dependsOn, blockedReason, workspace (repository, worktreePath, branch, parentBranch), tags
 
 **plan files (plan.md, plan-v2.md, ...):** assignment, status (draft/approved/in_progress/completed), created, updated — zero or more per assignment, each linked from a todo in `assignment.md`'s `## Todos` section
 
+**progress.md:** assignment, entryCount, generated, updated — body is reverse-chron `## <timestamp>` entries
+
+**comments.md:** assignment, entryCount, generated, updated — body entries are `## <id>` with structured metadata lines (Recorded, Author, Type, optional Reply to, optional Resolved)
+
 **handoff.md:** assignment, updated, handoffCount
 
 **decision-record.md:** assignment, updated, decisionCount
@@ -307,13 +329,13 @@ Adapters embed protocol knowledge (write boundaries, lifecycle states, CLI comma
 
 **manifest.md:** version, project, generated
 
-**_status.md:** project, generated, status, progress (total/completed/in_progress/blocked/pending/review/failed), needsAttention (blockedCount/failedCount/unansweredQuestions)
+**_status.md:** project, generated, status, progress (total/completed/in_progress/blocked/pending/review/failed), needsAttention (blockedCount/failedCount/**openQuestions**). `openQuestions` is counted from every assignment's `comments.md` (entries where `Type: question` and `Resolved: false` or absent).
 
 ### 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)
+- **Slugs:** Lowercase, hyphen-separated, match folder names (project-nested). For standalone assignments, the folder is named by UUID and `slug` is display-only.
+- **Protocol version:** `"2.0"` (string, not number)
 
 ---
 
@@ -376,7 +398,13 @@ A: Use `/grab-assignment <project-slug>` — it lists pending assignments. Or ch
 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.
+A: Run `syntaur comment <slug> "question text" --type question`. It appends to `comments.md`, which replaces the old `## Questions & Answers` body section. The question rolls up into `_status.md`'s `openQuestions` counter and shows on the dashboard. Do NOT set status to `blocked` for questions — `blocked` is for runtime obstacles only.
+
+**Q: What goes in `progress.md` vs `handoff.md`?**
+A: `progress.md` is a continuous reverse-chron log of what you've done — append an entry per meaningful work unit. `handoff.md` is only written when you hand off work (to another agent or human), and summarizes the state at that transition.
+
+**Q: How do I route work to another assignment without breaking the single-writer rule?**
+A: Run `syntaur request <target> "text"` — it appends a todo to the target's `## Todos` annotated `(from: <source>)`. This is a CLI-mediated exception to the single-writer rule.
 
 **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.

package/platforms/claude-code/references/file-ownership.md

@@ -7,8 +7,6 @@ Agents must NEVER modify these files:
 | File | Location |
 |------|----------|
 | `project.md` | `<project>/project.md` |
-| `agent.md` | `<project>/agent.md` |
-| `claude.md` | `<project>/claude.md` |
 
 ## Agent-Writable (YOUR assignment folder ONLY)
 
@@ -18,11 +16,25 @@ You may ONLY write to files inside your assigned assignment folder:
 |------|---------|
 | `assignment.md` | Assignment record, source of truth for state (includes `## Todos` checklist) |
 | `plan*.md` | Versioned implementation plans (optional, 0 or more: `plan.md`, `plan-v2.md`, ...) — each linked from a todo in `assignment.md` |
+| `progress.md` | Append-only timestamped progress log (newest first). Replaces the old `## Progress` body section. |
 | `scratchpad.md` | Working notes |
 | `handoff.md` | Append-only handoff log |
 | `decision-record.md` | Append-only decision log |
 
-Path pattern: `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+Path pattern (project-nested): `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
+Path pattern (standalone): `~/.syntaur/assignments/<your-assignment-uuid>/`
+
+## CLI-Mediated Shared-Writable
+
+Do NOT edit these files directly. Use the listed CLI commands:
+
+| File | Mediator |
+|------|----------|
+| `comments.md` (any assignment) | `syntaur comment <slug-or-uuid> "body" [--type question\|note\|feedback] [--reply-to <id>]` |
+| `## Todos` in another assignment's `assignment.md` (cross-assignment request) | `syntaur request <source> <target> "text"` |
+| Question resolution | `PATCH /api/.../comments/:id/resolved` (dashboard) or toggle in dashboard UI |
+
+These are bounded exceptions to the single-writer rule for assignment folders — the CLI serializes writes to avoid conflicts.
 
 ## Shared-Writable (any agent or human)
 

package/platforms/claude-code/references/protocol-summary.md

@@ -1,5 +1,7 @@
 # Syntaur Protocol Summary
 
+Protocol version: **2.0**
+
 ## Directory Structure
 
 ```
@@ -13,12 +15,12 @@
       _index-plans.md        # Derived (read-only)
       _index-decisions.md    # Derived (read-only)
       _status.md             # Derived (read-only)
-      claude.md              # Human-authored: Claude-specific instructions (read-only)
-      agent.md               # Human-authored: universal agent instructions (read-only)
       assignments/
         <assignment-slug>/
           assignment.md      # Agent-writable: source of truth for state (includes ## Todos checklist)
           plan*.md           # Agent-writable: versioned implementation plans (optional, 0 or more: 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
@@ -28,6 +30,15 @@
       memories/
         _index.md            # Derived (read-only)
         <memory-slug>.md     # Shared-writable
+  assignments/
+    <assignment-id>/         # Standalone assignments — folder named by UUID, `project: null`
+      assignment.md          # Same schema as project-nested, `slug` is display-only
+      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
@@ -62,10 +73,13 @@
 ## Key Rules
 
 1. **Assignment frontmatter is the single source of truth** for all assignment state.
-2. **One folder per project**, one subfolder per assignment.
+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) are never edited manually.
 4. **Slugs** are lowercase, hyphen-separated.
-5. **Dependencies** are declared via `dependsOn` in assignment frontmatter.
+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 `manifest.md` for a summary, then read each referenced playbook before starting work.
-8. **Todos** in the `## Todos` section of `assignment.md` are an informal markdown checklist. Items may be simple tasks or link to plan files. When a plan is superseded, mark the old todo: `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete it.
+8. **Todos** in the `## Todos` section of `assignment.md` are an informal markdown checklist. Items may be simple tasks or link to plan files. When a plan is superseded, mark the old todo: `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete it. `## Todos` is also the landing spot for cross-assignment requests via `syntaur request`.
+9. **Progress** is appended to `progress.md` as timestamped entries (newest first). Do not add a `## Progress` section to `assignment.md`.
+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.
+11. **Cross-assignment work** is requested via `syntaur request <source> <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.

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

@@ -51,6 +51,20 @@ If any acceptance criteria are unmet OR any todo is still `- [ ]` and not supers
 
 If the user says no, stop.
 
+## Step 2.5: Append a Final Progress Entry
+
+Before writing the handoff, append a final entry to `<assignmentDir>/progress.md` summarizing what was completed. The entry goes at the **top** of the body (reverse-chron order) under a new `## <RFC 3339 timestamp>` heading:
+
+```markdown
+## <ISO 8601 timestamp>
+
+<One paragraph summarizing the final state of work: what was implemented, what verifications passed, and any deliberate scope exclusions.>
+```
+
+Update `progress.md`'s frontmatter: bump `entryCount` and set `updated` to the current timestamp.
+
+Do NOT add a `## Progress` section to `assignment.md` — progress entries live exclusively in `progress.md` as of protocol v2.0.
+
 ## Step 3: Write Handoff Entry
 
 Read `<assignmentDir>/handoff.md` to see its current content and frontmatter.

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

@@ -1,7 +1,7 @@
 ---
 name: create-assignment
 description: Create a new Syntaur assignment within a project (or as a one-off)
-argument-hint: <title> --project <slug> [--priority <level>] [--depends-on <slugs>] [--one-off]
+argument-hint: <title> --project <slug> [--priority <level>] [--depends-on <slugs>] [--type <type>] [--one-off]
 allowed-tools:
   - Bash
   - Read
@@ -18,10 +18,11 @@ The user provided: $ARGUMENTS
 Parse the arguments:
 - First argument (required): the assignment title (e.g., `"Add login endpoint"`)
 - `--project <slug>` (required unless `--one-off`): the project to add the assignment to
-- `--one-off` (optional): create a standalone project+assignment in one step
+- `--one-off` (optional): create a **standalone** assignment at `~/.syntaur/assignments/<uuid>/` with `project: null`. Folder is named by UUID; `slug` is display-only. `--depends-on` is not permitted for standalone assignments.
 - `--slug` (optional): override the auto-generated assignment slug
 - `--priority` (optional): `low`, `medium` (default), `high`, or `critical`
-- `--depends-on` (optional): comma-separated list of assignment slugs this depends on
+- `--type` (optional): classification such as `feature`, `bug`, `refactor`, `research`, `chore`. Defaults to `feature`. When `~/.syntaur/config.md` defines `types.definitions`, the CLI validates against that list.
+- `--depends-on` (optional, project-nested only): comma-separated list of assignment slugs this depends on
 - `--dir` (optional): override the default project directory
 
 If no title was provided, ask the user what the assignment should be called.
@@ -35,13 +36,13 @@ If there is no active context and no project flag, ask the user which project to
 Build the command from the parsed arguments. Use `dangerouslyDisableSandbox: true` since the CLI writes to `~/.syntaur/` which is outside the project sandbox.
 
 ```bash
-syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--dir <path>]
+syntaur create-assignment "<title>" --project <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--type <type>] [--dir <path>]
 ```
 
-Or for one-off:
+Or for one-off (standalone at `~/.syntaur/assignments/<uuid>/`):
 
 ```bash
-syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--dir <path>]
+syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--type <type>] [--dir <path>]
 ```
 
 If the command fails (e.g., project not found, slug collision), report the error and suggest fixes.
@@ -57,9 +58,10 @@ cat ~/.syntaur/projects/<project-slug>/assignments/<assignment-slug>/assignment.
 ## Step 3: Guide Next Steps
 
 Tell the user:
-- The assignment was created with its slug, priority, and location
-- List the files created (assignment.md, scratchpad.md, handoff.md, decision-record.md). Note that `plan.md` is NOT scaffolded — plan files are optional and created on demand by `/plan-assignment`.
+- The assignment was created with its slug, priority, type, and location. For standalone assignments, the location is `~/.syntaur/assignments/<uuid>/` — note the UUID (not slug) is the folder name.
+- List the files created: `assignment.md`, `progress.md`, `comments.md`, `scratchpad.md`, `handoff.md`, `decision-record.md`. `plan.md` is NOT scaffolded — plan files are optional and created on demand by `/plan-assignment`.
+- Remind the user: `progress.md` is where timestamped progress entries go (not `assignment.md`), and `comments.md` is written only via `syntaur comment <slug-or-uuid> "body" --type question|note|feedback`.
 - Suggest they edit `assignment.md` to fill in the objective, acceptance criteria, context, and any initial todos. The `## Todos` section accepts simple tasks or markdown links to plan files.
 - Or suggest running `/plan-assignment` after grabbing — it creates a plan file and auto-appends a linked todo to `## Todos`.
-- If dependencies were set, note them
-- Suggest running `/grab-assignment <project-slug> <assignment-slug>` to claim and start working on it
+- If dependencies were set, note them. (Standalone assignments cannot declare dependencies.)
+- Suggest running `/grab-assignment <project-slug> <assignment-slug>` (or `/grab-assignment --id <uuid>` for standalone) to claim and start working on it.