syntaur 0.1.0

package/plugins/syntaur/skills/complete-assignment/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: complete-assignment
+description: Use when the user wants to write a Syntaur handoff, close the current session, and transition the assignment to review or completed.
+---
+
+# Complete Assignment
+
+Write a handoff for the current Syntaur assignment and transition it to `review` or `completed`.
+
+## Arguments
+
+User arguments: `$ARGUMENTS`
+
+If the user passed `--complete`, transition directly to `completed` only when all acceptance criteria are met. Otherwise transition to `review`.
+
+## Workflow
+
+1. Read `.syntaur/context.json`. If it does not exist, tell the user there is no active assignment.
+2. Read `<assignmentDir>/assignment.md` and evaluate every item in the `## Acceptance Criteria` section.
+3. Read `<assignmentDir>/handoff.md` and append a new handoff entry using the protocol format:
+
+```markdown
+## Handoff <N>: <ISO 8601 timestamp>
+
+**From:** codex
+**To:** human
+**Reason:** <Why this handoff is happening>
+
+### Summary
+<One paragraph>
+
+### Current State
+- <What is working>
+- <What is not working or still partial>
+- <Acceptance criteria status: N of M met>
+
+### Next Steps
+- <Recommended follow-up actions>
+
+### Important Context
+- <Anything the next person needs to know>
+```
+
+4. Update the handoff frontmatter:
+   - set `updated` to the current timestamp
+   - increment `handoffCount`
+5. Update acceptance criteria checkboxes in `assignment.md` to match reality.
+6. If `.syntaur/context.json` includes `sessionId`, mark that session as completed through the dashboard API:
+
+```bash
+curl -s -X PATCH "http://localhost:$(cat ~/.syntaur/dashboard-port 2>/dev/null || echo 4800)/api/agent-sessions/<session-id>/status" \
+  -H "Content-Type: application/json" \
+  -d '{"status":"completed","missionSlug":"<mission-slug>"}'
+```
+
+7. Transition the assignment:
+   - `syntaur complete <assignment-slug> --mission <mission-slug>` when `--complete` is allowed
+   - otherwise `syntaur review <assignment-slug> --mission <mission-slug>`
+8. Delete `.syntaur/context.json`.
+9. Summarize:
+   - new status
+   - acceptance criteria met vs total
+   - any criteria still unmet or follow-up risk

package/plugins/syntaur/skills/create-assignment/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: create-assignment
+description: Use when the user wants to create a new Syntaur assignment inside a mission or as a one-off mission plus assignment.
+---
+
+# Create Assignment
+
+Create a new Syntaur assignment from Codex.
+
+## Arguments
+
+User arguments: `$ARGUMENTS`
+
+Parse:
+
+- First positional argument: assignment title
+- `--mission <slug>` required unless `--one-off`
+- `--one-off` optional
+- `--slug <slug>` optional
+- `--priority <level>` optional, default `medium`
+- `--depends-on <slug[,slug...]>` optional
+- `--dir <path>` optional
+
+If no title was provided, ask the user for it.
+
+If neither `--mission` nor `--one-off` was provided, look for `.syntaur/context.json` in the current working directory. If present, default the mission to that context's `missionSlug` and tell the user you are using it.
+
+## Workflow
+
+1. Run one of:
+   - `syntaur create-assignment "<title>" --mission <slug> [--slug <slug>] [--priority <level>] [--depends-on <slugs>] [--dir <path>]`
+   - `syntaur create-assignment "<title>" --one-off [--slug <slug>] [--priority <level>] [--dir <path>]`
+2. If the command fails, report the error and stop.
+3. Read the generated `assignment.md`.
+4. Summarize:
+   - assignment slug
+   - mission slug
+   - priority
+   - location
+   - created files: `assignment.md`, `plan.md`, `scratchpad.md`, `handoff.md`, `decision-record.md`
+5. Suggest next steps:
+   - fill in the objective, context, and acceptance criteria
+   - run `grab-assignment` to claim it if work should begin now

package/plugins/syntaur/skills/create-mission/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: create-mission
+description: Use when the user wants to create a new Syntaur mission and scaffold its mission.md, agent.md, claude.md, indexes, and manifest files.
+---
+
+# Create Mission
+
+Create a new Syntaur mission from Codex.
+
+## Arguments
+
+User arguments: `$ARGUMENTS`
+
+Parse:
+
+- First positional argument: mission title
+- `--slug <slug>` optional
+- `--dir <path>` optional
+- `--workspace <workspace>` optional: workspace grouping label (e.g., `syntaur`, `reeva`)
+
+If no title was provided, ask the user for it.
+
+## Workflow
+
+1. Run `syntaur create-mission "<title>" [--slug <slug>] [--dir <path>] [--workspace <workspace>]`.
+2. If the command fails, report the error and stop.
+3. Read the generated `mission.md` to confirm the mission path and scaffold.
+4. Summarize:
+   - mission slug
+   - mission directory
+   - key files created: `manifest.md`, `mission.md`, `agent.md`, `claude.md`
+5. Suggest next steps:
+   - fill in `mission.md`
+   - add mission-wide guidance to `agent.md`
+   - run `create-assignment` for the first task

package/plugins/syntaur/skills/grab-assignment/SKILL.md

@@ -0,0 +1,61 @@
+---
+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.
+---
+
+# Grab Assignment
+
+Claim a pending Syntaur assignment and set up the current workspace.
+
+## Arguments
+
+User arguments: `$ARGUMENTS`
+
+Parse:
+
+- First positional argument: mission 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/`.
+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.
+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>",
+  "assignmentSlug": "<assignment-slug>",
+  "missionDir": "/absolute/path/to/mission",
+  "assignmentDir": "/absolute/path/to/assignment",
+  "workspaceRoot": "/absolute/path/to/workspace",
+  "title": "<assignment title>",
+  "branch": "<workspace.branch or null>",
+  "grabbedAt": "<ISO 8601 timestamp>",
+  "sessionId": "<uuid>"
+}
+```
+
+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>`
+10. Summarize:
+   - assignment slug and title
+   - objective
+   - acceptance criteria
+   - workspace path
+11. Suggest next step: `plan-assignment`

package/plugins/syntaur/skills/plan-assignment/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: plan-assignment
+description: Use when the user wants a detailed implementation plan written to plan.md for the current Syntaur assignment.
+---
+
+# Plan Assignment
+
+Create an implementation plan for the current Syntaur assignment.
+
+## Arguments
+
+Optional notes from the user: `$ARGUMENTS`
+
+## Workflow
+
+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`
+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
+
+## Plan Contents
+
+Write these sections:
+
+1. Overview
+2. Tasks
+3. Acceptance Criteria Mapping
+4. Risks and Open Questions
+5. Testing Strategy
+
+## 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

package/plugins/syntaur/skills/syntaur-protocol/SKILL.md

@@ -0,0 +1,84 @@
+---
+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.
+---
+
+# Syntaur Protocol
+
+You are working within the Syntaur protocol. Follow these rules at all times.
+
+## Write Boundary Rules
+
+Respect file ownership boundaries.
+
+### Files you may write
+
+1. Your assignment folder only:
+   - `assignment.md`
+   - `plan.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`
+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`
+2. `manifest.md`
+3. Any file prefixed with `_`
+4. Other agents' assignment folders
+5. Anything outside the current workspace boundary
+
+## Current Assignment Context
+
+If `.syntaur/context.json` exists in the current working directory, read it before making changes. Use it to determine:
+
+- `missionSlug`
+- `assignmentSlug`
+- `missionDir`
+- `assignmentDir`
+- `workspaceRoot`
+- `sessionId` if present
+
+## Required Reading Order
+
+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
+5. `<assignmentDir>/assignment.md`
+6. `<assignmentDir>/plan.md`
+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>`
+
+## 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.
+- Keep the `## Progress` section in `assignment.md` current after meaningful milestones.
+- Write handoffs with enough context for another agent or human to continue cleanly.
+
+## References
+
+Read these only when you need the detailed rules or directory layout:
+
+- `../../references/protocol-summary.md`
+- `../../references/file-ownership.md`

package/plugins/syntaur/skills/track-session/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: track-session
+description: Use when the user wants to register, refresh, remove, or list tracked tmux sessions for the Syntaur dashboard.
+---
+
+# Track Session
+
+Track tmux sessions so their development servers show up in the Syntaur dashboard.
+
+## Arguments
+
+User arguments: `$ARGUMENTS`
+
+Supported forms:
+
+- `<session-name>`
+- `--refresh [session-name]`
+- `--remove <session-name>`
+- `--list`
+
+## Workflow
+
+### Register
+
+1. Verify the tmux session exists with `tmux has-session -t <name>`.
+2. If it does not exist, list available sessions with `tmux list-sessions -F '#{session_name}'`.
+3. Create `~/.syntaur/servers/<sanitized-name>.md` with frontmatter:
+
+```yaml
+---
+session: <original-name>
+registered: <ISO timestamp>
+last_refreshed: <ISO timestamp>
+---
+```
+
+4. Tell the user the session is now tracked.
+
+### Refresh
+
+1. Update `last_refreshed` for the named session, or for every file in `~/.syntaur/servers/` when no name was provided.
+
+### Remove
+
+1. Delete `~/.syntaur/servers/<sanitized-name>.md`.
+
+### List
+
+1. List all tracked session markdown files and show the `session` field from each.