syntaur 0.1.14 → 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
-- If a plan.md exists, update its task checkboxes as you complete steps
+- 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

@@ -1,10 +1,10 @@
 ---
 name: "Read Before You Plan"
 slug: read-before-plan
-description: "Agents must read all mission context files before creating or modifying a plan"
-when_to_use: "Before creating or modifying plan.md"
+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
@@ -12,16 +12,19 @@ tags:
 
 # Read Before You Plan
 
-Before creating or modifying plan.md, read these files in order:
+Before creating or modifying any plan file (plan.md, plan-v2.md, ...), read these files in order:
 
-1. `manifest.md` -- understand the mission structure
-2. `mission.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
+For project-nested assignments:
+1. `manifest.md` -- understand the project structure
+2. `project.md` -- understand the goal and scope
+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-mission → sample-project}/_index-assignments.md

@@ -1,5 +1,5 @@
 ---
-mission: build-auth-system
+project: build-auth-system
 generated: "2026-03-18T14:30:00Z"
 total: 3
 by_status:

package/examples/{sample-mission → sample-project}/_index-decisions.md

@@ -1,5 +1,5 @@
 ---
-mission: build-auth-system
+project: build-auth-system
 generated: "2026-03-18T14:30:00Z"
 ---
 

package/examples/{sample-mission → sample-project}/_index-plans.md

@@ -1,5 +1,5 @@
 ---
-mission: build-auth-system
+project: build-auth-system
 generated: "2026-03-18T14:30:00Z"
 ---
 

package/examples/{sample-mission → sample-project}/_status.md

@@ -1,5 +1,5 @@
 ---
-mission: build-auth-system
+project: build-auth-system
 generated: "2026-03-18T14:30:00Z"
 status: active
 progress:
@@ -13,10 +13,10 @@ progress:
 needsAttention:
   blockedCount: 0
   failedCount: 0
-  unansweredQuestions: 1
+  openQuestions: 1
 ---
 
-# Mission Status: Build Authentication System
+# Project Status: Build Authentication System
 
 **Status:** active
 **Progress:** 1/3 assignments complete
@@ -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-mission → 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"
@@ -32,30 +34,18 @@ Design the PostgreSQL database schema for the authentication system. This includ
 - [x] All tables have appropriate indexes for query patterns
 - [x] Migration scripts are idempotent and backward-compatible
 
-## Context
-
-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
+## Todos
 
-### 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.
+- [x] Execute [plan](./plan.md)
 
-## 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.
+## Context
 
-### 2026-03-16T09:30:00Z
-Started schema design. Reviewed auth requirements document. Planning three tables: users, sessions, refresh_tokens.
+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.
 
 ## Links
 
-- [Plan](./plan.md)
+- [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-mission → 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"
@@ -36,30 +38,18 @@ Implement Express.js middleware that validates JWT access tokens on protected ro
 - [ ] Token revocation endpoint (logout)
 - [ ] Role-based route guards (admin vs user)
 
-## Context
-
-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
+## Todos
 
-### Q: Should the refresh token endpoint require the old access token or just the refresh token?
-**Asked:** 2026-03-18T11:00:00Z
-**A:** pending
+- [ ] Execute [plan](./plan.md)
 
-## 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.
+## Context
 
-### 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.
+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.
 
 ## Links
 
-- [Plan](./plan.md)
+- [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-mission → 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"
@@ -34,21 +36,18 @@ Write comprehensive unit and integration tests for the authentication system, co
 - [ ] Edge case tests: expired tokens, revoked sessions, refresh token reuse detection
 - [ ] Coverage report showing 80%+ line coverage
 
-## Context
-
-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.
+## Todos
 
-## Questions & Answers
+- [ ] Execute [plan](./plan.md)
 
-No questions yet.
-
-## Progress
+## Context
 
-No progress yet.
+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.
 
 ## Links
 
-- [Plan](./plan.md)
+- [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/examples/{sample-mission → sample-project}/manifest.md

@@ -1,13 +1,13 @@
 ---
 version: "1.0"
-mission: build-auth-system
+project: build-auth-system
 generated: "2026-03-18T14:30:00Z"
 ---
 
-# Mission: build-auth-system
+# Project: build-auth-system
 
 ## Overview
-- [Mission Overview](./mission.md)
+- [Project Overview](./project.md)
 
 ## Indexes
 - [Assignments](./_index-assignments.md)

package/examples/{sample-mission → sample-project}/memories/_index.md

@@ -1,5 +1,5 @@
 ---
-mission: build-auth-system
+project: build-auth-system
 generated: "2026-03-18T14:30:00Z"
 total: 1
 ---
@@ -8,4 +8,4 @@ total: 1
 
 | Name | Source | Scope | Source Assignment | Updated |
 |------|--------|-------|------------------|---------|
-| [postgres-connection-pooling](./postgres-connection-pooling.md) | claude-2 | mission | design-auth-schema | 2026-03-17T09:00:00Z |
+| [postgres-connection-pooling](./postgres-connection-pooling.md) | claude-2 | project | design-auth-schema | 2026-03-17T09:00:00Z |

package/examples/{sample-mission → sample-project}/memories/postgres-connection-pooling.md

@@ -6,7 +6,7 @@ sourceAssignment: design-auth-schema
 relatedAssignments:
   - design-auth-schema
   - implement-jwt-middleware
-scope: mission
+scope: project
 created: "2026-03-17T09:00:00Z"
 updated: "2026-03-17T09:00:00Z"
 tags:

package/examples/{sample-mission → sample-project}/resources/_index.md

@@ -1,5 +1,5 @@
 ---
-mission: build-auth-system
+project: build-auth-system
 generated: "2026-03-18T14:30:00Z"
 total: 1
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "syntaur",
-  "version": "0.1.14",
-  "description": "Mission workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
+  "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": {
     "type": "git",
@@ -40,7 +40,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build && npm ci --prefix dashboard && npm run build --prefix dashboard"
+    "prepublishOnly": "npm run build && npm ci --prefix dashboard && npm run build --prefix dashboard",
+    "try": "node scripts/try.mjs",
+    "untry": "npm unlink -g syntaur && npm install -g syntaur@latest && echo '\\n✓ global syntaur restored to latest published version'"
   },
   "engines": {
     "node": ">=20.0.0"

package/platforms/README.md

@@ -16,16 +16,16 @@ format expected by the target framework.
 
 ```bash
 # Generate Cursor adapter files in the current directory
-syntaur setup-adapter cursor --mission <mission-slug> --assignment <assignment-slug>
+syntaur setup-adapter cursor --project <project-slug> --assignment <assignment-slug>
 
 # Generate Codex adapter files
-syntaur setup-adapter codex --mission <mission-slug> --assignment <assignment-slug>
+syntaur setup-adapter codex --project <project-slug> --assignment <assignment-slug>
 
 # Generate OpenCode adapter files
-syntaur setup-adapter opencode --mission <mission-slug> --assignment <assignment-slug>
+syntaur setup-adapter opencode --project <project-slug> --assignment <assignment-slug>
 
 # Overwrite existing files
-syntaur setup-adapter cursor --mission my-mission --assignment my-task --force
+syntaur setup-adapter cursor --project my-project --assignment my-task --force
 ```
 
 ## What Gets Generated
@@ -35,8 +35,8 @@ All adapters embed equivalent protocol knowledge:
 - **Write boundary rules** (which files the agent can and cannot modify)
 - **Assignment lifecycle states** and valid transitions
 - **CLI commands** for state transitions (`syntaur start`, `syntaur complete`, etc.)
-- **Reading order** for mission and assignment files
-- **Current assignment context** (mission slug, assignment slug, paths)
+- **Reading order** for project and assignment files
+- **Current assignment context** (project slug, assignment slug, paths)
 
 ## Contributing a New Adapter
 
@@ -46,7 +46,7 @@ To add support for a new framework:
    reference file showing the format. This is documentation, not a runtime asset.
 
 2. **Create a TypeScript renderer** in `src/templates/<framework>.ts`:
-   - Define a params interface with `missionSlug`, `assignmentSlug`, `missionDir`, `assignmentDir`
+   - Define a params interface with `projectSlug`, `assignmentSlug`, `projectDir`, `assignmentDir`
    - Export a render function returning the file content as a string
    - Embed protocol knowledge directly in the template literal (do not read files at runtime)
 

package/platforms/claude-code/README.md

@@ -4,7 +4,7 @@ Syntaur plugin for Claude Code. Installed automatically during `syntaur setup`.
 
 ## What's included
 
-- **Skills:** grab-assignment, plan-assignment, complete-assignment, create-mission, create-assignment, syntaur-protocol
+- **Skills:** grab-assignment, plan-assignment, complete-assignment, create-project, create-assignment, syntaur-protocol
 - **Agents:** syntaur-protocol (background)
 - **Hooks:** write boundary enforcement (PreToolUse)
 - **Commands:** track-session