syntaur 0.1.13 → 0.2.0

package/platforms/codex/skills/grab-assignment/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: grab-assignment
-description: Use when the user wants to discover, claim, and start a pending Syntaur assignment, create .syntaur/context.json, and register a Codex session.
+description: Use when the user wants to load a Syntaur assignment into context, create .syntaur/context.json, and register a Codex session. Works regardless of assignment status.
 ---
 
 # Grab Assignment
 
-Claim a pending Syntaur assignment and set up the current workspace.
+Load a Syntaur assignment into the current working context and register this Codex session.
+
+**Grabbing is non-destructive.** It never fails because of status. Any status (`pending`, `in_progress`, `blocked`, `review`, `completed`, `failed`) can be grabbed — grabbing just sets up context and registers the session. Only a `pending` assignment additionally transitions to `in_progress`; any other status is left untouched.
 
 ## Arguments
 
@@ -13,34 +15,36 @@ User arguments: `$ARGUMENTS`
 
 Parse:
 
-- First positional argument: mission slug
+- First positional argument: project slug
 - Second positional argument: optional assignment slug
 
 ## Workflow
 
 1. If `.syntaur/context.json` already exists in the current working directory, read it and warn that claiming another assignment will replace the active context.
-2. Read the mission entry files:
-   - `~/.syntaur/missions/<mission-slug>/manifest.md`
-   - `~/.syntaur/missions/<mission-slug>/mission.md`
-   - `~/.syntaur/missions/<mission-slug>/agent.md`
-   - `~/.syntaur/missions/<mission-slug>/claude.md` if it exists
-   Note the `workspace` field in `mission.md` frontmatter if present. This indicates which project/codebase grouping the mission belongs to. When writing context to `.syntaur/context.json` (Step 8), include `"workspace": "<value>"` if the mission has a workspace.
-3. Discover pending assignments under `~/.syntaur/missions/<mission-slug>/assignments/`.
+2. Read the project entry files:
+   - `~/.syntaur/projects/<project-slug>/manifest.md`
+   - `~/.syntaur/projects/<project-slug>/project.md`
+   - `~/.syntaur/projects/<project-slug>/agent.md`
+   - `~/.syntaur/projects/<project-slug>/claude.md` if it exists
+   Note the `workspace` field in `project.md` frontmatter if present. This indicates which project/codebase grouping the project belongs to. When writing context to `.syntaur/context.json` (Step 8), include `"workspace": "<value>"` if the project has a workspace.
+3. Discover assignments under `~/.syntaur/projects/<project-slug>/assignments/`. Do **not** filter by status — every assignment is grabbable.
 4. If no assignment slug was provided:
-   - list pending assignments with title and priority
-   - ask the user to choose unless only one pending assignment exists
-5. Claim the assignment:
-   - `syntaur assign <assignment-slug> --agent codex --mission <mission-slug>`
-   - `syntaur start <assignment-slug> --mission <mission-slug>`
-6. Read the full assignment file.
+   - list assignments with title, priority, and current status (highlight `pending` ones as the default candidates)
+   - ask the user to choose unless there is exactly one obvious candidate
+   If a slug *was* provided, verify the directory exists. Its status does not matter; do not block on it.
+5. Read the chosen assignment's `assignment.md` — its frontmatter for `status`, and its markdown body for the objective, acceptance criteria, and `## Todos` section (active todos indicate outstanding work and may link to plan files to execute). If `dependsOn` is non-empty, also read each dep's `handoff.md` AND `decision-record.md` to inherit upstream context and decisions.
+6. Claim the assignment:
+   - Always: `syntaur assign <assignment-slug> --agent codex --project <project-slug>` (safe at any status; does not transition state)
+   - **Only if current status is `pending`**: `syntaur start <assignment-slug> --project <project-slug>` to transition it to `in_progress`. Skip this command for any other status — grabbing must not rewind a `review`, `completed`, or `failed` assignment.
+   If `syntaur assign` fails (e.g., project not found, invalid slug), report and stop. Do not treat a non-pending status as a failure.
 7. If the assignment has no workspace configured, set `workspace.repository` and `workspace.worktreePath` to the current working directory so write boundaries are meaningful.
 8. Create `.syntaur/context.json` in the current working directory with:
 
 ```json
 {
-  "missionSlug": "<mission-slug>",
+  "projectSlug": "<project-slug>",
   "assignmentSlug": "<assignment-slug>",
-  "missionDir": "/absolute/path/to/mission",
+  "projectDir": "/absolute/path/to/project",
   "assignmentDir": "/absolute/path/to/assignment",
   "workspaceRoot": "/absolute/path/to/workspace",
   "title": "<assignment title>",
@@ -52,10 +56,16 @@ Parse:
 
 9. Register the agent session:
    - generate a UUID
-   - run `syntaur track-session --mission <mission-slug> --assignment <assignment-slug> --agent codex --session-id <uuid> --path <cwd>`
+   - run `syntaur track-session --project <project-slug> --assignment <assignment-slug> --agent codex --session-id <uuid> --path <cwd>`
 10. Summarize:
    - assignment slug and title
+   - current status (call it out if the assignment was already past `pending` — e.g., "already in `review`, status unchanged")
    - objective
    - acceptance criteria
+   - active todos from the `## Todos` section (if any), including any plan files they link to
    - workspace path
-11. Suggest next step: `plan-assignment`
+11. Suggest a next step appropriate to status:
+   - `pending` / `in_progress`: `plan-assignment`
+   - `blocked`: investigate `blockedReason`
+   - `review`: inspect the implementation and help verify acceptance criteria
+   - `completed` / `failed`: read the handoff; grab is probably for reference or reopen

package/platforms/codex/skills/plan-assignment/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: plan-assignment
-description: Use when the user wants a detailed implementation plan written to plan.md for the current Syntaur assignment.
+description: Use when the user wants a detailed implementation plan written as a versioned plan file for the current Syntaur assignment.
 ---
 
 # Plan Assignment
 
-Create an implementation plan for the current Syntaur assignment.
+Create an implementation plan for the current Syntaur assignment. Plans are versioned files: the first is `plan.md`, later ones are `plan-v2.md`, `plan-v3.md`, etc. Each plan gets a linked entry in the `## Todos` section of `assignment.md`, and any prior active plan todo is marked superseded.
 
 ## Arguments
 
@@ -16,19 +16,24 @@ Optional notes from the user: `$ARGUMENTS`
 1. Read `.syntaur/context.json` from the current working directory. If it does not exist, tell the user to claim an assignment first.
 2. Read:
    - `<assignmentDir>/assignment.md`
-   - `<missionDir>/agent.md`
-   - `<missionDir>/claude.md` if it exists
-   - `<missionDir>/mission.md`
+   - `<projectDir>/agent.md`
+   - `<projectDir>/claude.md` if it exists
+   - `<projectDir>/project.md`
 3. If the assignment depends on other assignments, read each dependency handoff for integration context.
 4. Explore `workspaceRoot` when it exists:
    - inspect project structure
    - find likely implementation files
    - note conventions and architecture
-5. Update `<assignmentDir>/plan.md`:
-   - preserve the existing YAML frontmatter
-   - set `status` to `in_progress` if it is still `draft`
-   - refresh the `updated` timestamp
-   - replace the body with a concrete plan
+5. Determine the next plan filename:
+   - List `<assignmentDir>/plan*.md`.
+   - If none exist, target is `plan.md` (version label: "plan").
+   - Otherwise pick the smallest `N >= 2` such that `plan-v<N>.md` does not exist (version label: `plan v<N>`).
+6. Write `<assignmentDir>/<planFilename>` with standard plan frontmatter (`assignment`, `status: draft`, `created`, `updated`) and a body containing the sections below. If the file already exists (only possible for `plan.md` on first re-run), preserve frontmatter, flip `status` from `draft` to `in_progress`, update `updated`, and replace only the body.
+7. Update `<assignmentDir>/assignment.md`:
+   - Find unchecked todos matching `- [ ] Execute [<label>](./plan*.md)`. Rewrite each as `- [x] ~~Execute [<label>](./<old-filename>)~~ (superseded by <versionLabel>)`. Never delete the old line.
+   - Append a new todo: `- [ ] Execute [<versionLabel>](./<planFilename>)`.
+   - If `## Todos` is missing (legacy assignment), insert it right after `## Acceptance Criteria` with a short guidance comment and the new todo line.
+   - Refresh the assignment frontmatter `updated` timestamp.
 
 ## Plan Contents
 
@@ -40,10 +45,13 @@ Write these sections:
 4. Risks and Open Questions
 5. Testing Strategy
 
+**Decision capture:** While planning, record meaningful choices (library picks, schema design, architectural calls, rejected alternatives) as numbered entries in `<assignmentDir>/decision-record.md` using `## Decision N: <short title>` with Status (proposed/accepted), Context, Decision, Consequences. Downstream assignments that depend on this one auto-load these on grab.
+
 ## Reporting
 
 After writing the plan:
 
 - summarize the number of tasks and key decisions
 - call out open questions or risks
-- remind yourself to keep `assignment.md` progress and acceptance criteria current during implementation
+- note which plan filename was written and which prior plan (if any) was superseded
+- remind yourself to keep `assignment.md` progress, acceptance criteria, and todos current during implementation

package/platforms/codex/skills/syntaur-protocol/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: syntaur-protocol
-description: Use when the user mentions Syntaur, missions, assignments, files under ~/.syntaur/, assignment.md, plan.md, handoff.md, .syntaur/context.json, lifecycle states, or write boundaries.
+description: Use when the user mentions Syntaur, projects, assignments, files under ~/.syntaur/, assignment.md, plan.md, handoff.md, .syntaur/context.json, lifecycle states, or write boundaries.
 ---
 
 # Syntaur Protocol
@@ -15,19 +15,19 @@ Respect file ownership boundaries.
 
 1. Your assignment folder only:
    - `assignment.md`
-   - `plan.md`
+   - `plan*.md` (0 or more versioned plan files, e.g., `plan.md`, `plan-v2.md`)
    - `scratchpad.md`
    - `handoff.md`
    - `decision-record.md`
-2. Mission-level shared files:
-   - `~/.syntaur/missions/<mission>/resources/<slug>.md`
-   - `~/.syntaur/missions/<mission>/memories/<slug>.md`
+2. Project-level shared files:
+   - `~/.syntaur/projects/<project>/resources/<slug>.md`
+   - `~/.syntaur/projects/<project>/memories/<slug>.md`
 3. Workspace files inside the assignment's configured workspace root
 4. `.syntaur/context.json` in the current working directory
 
 ### Files you must never write
 
-1. `mission.md`, `agent.md`, `claude.md`
+1. `project.md`, `agent.md`, `claude.md`
 2. `manifest.md`
 3. Any file prefixed with `_`
 4. Other agents' assignment folders
@@ -37,9 +37,9 @@ Respect file ownership boundaries.
 
 If `.syntaur/context.json` exists in the current working directory, read it before making changes. Use it to determine:
 
-- `missionSlug`
+- `projectSlug`
 - `assignmentSlug`
-- `missionDir`
+- `projectDir`
 - `assignmentDir`
 - `workspaceRoot`
 - `sessionId` if present
@@ -48,32 +48,37 @@ If `.syntaur/context.json` exists in the current working directory, read it befo
 
 When you are working on an existing assignment, read these in order:
 
-1. `<missionDir>/manifest.md`
-2. `<missionDir>/agent.md`
-3. `<missionDir>/mission.md`
-4. `<missionDir>/claude.md` if it exists
+1. `<projectDir>/manifest.md`
+2. `<projectDir>/agent.md`
+3. `<projectDir>/project.md`
+4. `<projectDir>/claude.md` if it exists
 5. `<assignmentDir>/assignment.md`
-6. `<assignmentDir>/plan.md`
+6. any `<assignmentDir>/plan*.md` files linked from active todos in the `## Todos` section
 7. `<assignmentDir>/handoff.md`
 
 ## Lifecycle Commands
 
 Use the `syntaur` CLI for state transitions:
 
-- `syntaur assign <slug> --agent <name> --mission <mission>`
-- `syntaur start <slug> --mission <mission>`
-- `syntaur review <slug> --mission <mission>`
-- `syntaur complete <slug> --mission <mission>`
-- `syntaur block <slug> --mission <mission> --reason <text>`
-- `syntaur unblock <slug> --mission <mission>`
-- `syntaur fail <slug> --mission <mission>`
+- `syntaur assign <slug> --agent <name> --project <project>`
+- `syntaur start <slug> --project <project>`
+- `syntaur review <slug> --project <project>`
+- `syntaur complete <slug> --project <project>`
+- `syntaur block <slug> --project <project> --reason <text>`
+- `syntaur unblock <slug> --project <project>`
+- `syntaur fail <slug> --project <project>`
+
+## Troubleshooting
+
+If Syntaur state looks inconsistent (missing files, stale manifests, unexpected hook blocks), run `syntaur doctor` to diagnose. Use `--json` for structured output.
 
 ## Conventions
 
 - Assignment frontmatter is the single source of truth.
 - Slugs are lowercase and hyphen-separated.
-- Update acceptance criteria checkboxes as work lands, not only at the end.
+- Update acceptance criteria and `## Todos` checkboxes as work lands, not only at the end.
 - Keep the `## Progress` section in `assignment.md` current after meaningful milestones.
+- When requirements shift, supersede the prior plan todo (`- [x] ~~...~~ (superseded by plan-v<N>)`) instead of rewriting the old plan file.
 - Write handoffs with enough context for another agent or human to continue cleanly.
 
 ## References

package/platforms/cursor/README.md

@@ -11,7 +11,7 @@ Cursor reads `.cursor/rules/*.mdc` files with YAML frontmatter. Syntaur generate
 Generate adapter files for a specific assignment:
 
 ```bash
-syntaur setup-adapter cursor --mission <mission-slug> --assignment <assignment-slug>
+syntaur setup-adapter cursor --project <project-slug> --assignment <assignment-slug>
 ```
 
 This creates:

package/platforms/cursor/adapters/syntaur-protocol.mdc

@@ -12,4 +12,4 @@ The `syntaur setup-adapter cursor` command generates this file
 dynamically at `.cursor/rules/syntaur-protocol.mdc` in your workspace.
 
 See the rendered output by running:
-  syntaur setup-adapter cursor --mission <slug> --assignment <slug>
+  syntaur setup-adapter cursor --project <slug> --assignment <slug>

package/platforms/opencode/README.md

@@ -11,7 +11,7 @@ OpenCode discovers skills from `SKILL.md` files in several directories and reads
 Generate adapter files for a specific assignment:
 
 ```bash
-syntaur setup-adapter opencode --mission <mission-slug> --assignment <assignment-slug>
+syntaur setup-adapter opencode --project <project-slug> --assignment <assignment-slug>
 ```
 
 This creates:

package/platforms/opencode/adapters/opencode.json.template

@@ -1,6 +1,6 @@
 {
   "instructions": [
     "Read AGENTS.md in this directory for Syntaur protocol instructions.",
-    "Also read <missionDir>/agent.md for universal agent conventions."
+    "Also read <projectDir>/agent.md for universal agent conventions."
   ]
 }

package/dashboard/dist/assets/channel-PMR2DuGi.js

@@ -1 +0,0 @@
-import{aq as o,ar as n}from"./mermaid.core-fMQRe9Gq.js";const t=(r,a)=>o.lang.round(n.parse(r)[a]);export{t as c};

package/dashboard/dist/assets/classDiagram-VBA2DB6C-DmESf_RL.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-WL4C6EOR-CFEqRrE1.js";import{_ as i}from"./mermaid.core-fMQRe9Gq.js";import"./chunk-FMBD7UC4-5mMONjMK.js";import"./chunk-JSJVCQXG-CwKj-Es4.js";import"./chunk-55IACEB6-r1_jHZYp.js";import"./chunk-KX2RTZJC-ByoW-HgN.js";import"./index-BhuXD-Q5.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dashboard/dist/assets/classDiagram-v2-RAHNMMFH-DmESf_RL.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-WL4C6EOR-CFEqRrE1.js";import{_ as i}from"./mermaid.core-fMQRe9Gq.js";import"./chunk-FMBD7UC4-5mMONjMK.js";import"./chunk-JSJVCQXG-CwKj-Es4.js";import"./chunk-55IACEB6-r1_jHZYp.js";import"./chunk-KX2RTZJC-ByoW-HgN.js";import"./index-BhuXD-Q5.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dashboard/dist/assets/clone-WlIeyha4.js

@@ -1 +0,0 @@
-import{b as r}from"./_baseUniq-gxypqvP5.js";var e=4;function a(o){return r(o,e)}export{a as c};