syntaur 0.27.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.27.0",
+  "version": "0.32.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {
@@ -56,6 +56,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "mirror-skills": "node scripts/mirror-skills-to-platforms.mjs",
+    "build:skills-index": "node scripts/build-skills-index.mjs",
     "postinstall": "node scripts/install-macos-url-handler.mjs",
     "prepack": "node scripts/mirror-skills-to-platforms.mjs",
     "prepublishOnly": "npm run build && npm ci --prefix dashboard && npm run build --prefix dashboard",

package/platforms/README.md

@@ -40,6 +40,27 @@ If `npx` is unavailable, `syntaur setup --target <id>` falls back to copying the
 bundled skills directly into the agent's skills dir. See
 `references/tool-dialects.md` for the Syntaur-id ↔ skills.sh-id mapping.
 
+### Channels
+
+Two equivalent Tier-1 sources resolve the same 30 skills:
+
+- **GitHub source** — `npx skills add prong-horn/syntaur` clones the repo and
+  auto-discovers `skills/` (no index needed).
+- **Branded HTTP source** — a spec-valid Agent Skills **v0.2.0** discovery index at
+  `/.well-known/agent-skills/index.json`, generated from `skills/` by
+  `scripts/build-skills-index.mjs` (per-skill `sha256:` digests; single-file skills
+  ship as `skill-md`, the multi-file `syntaur-protocol` as a deterministic `archive`
+  tar.gz) and deployed to **GitHub Pages** by `publish.yml` on each `v*` tag:
+
+  ```bash
+  # Pass the FULL URL (a bare host parses as a GitHub shorthand in skills.sh):
+  npx skills add https://prong-horn.github.io/syntaur
+  ```
+
+  The index emits **index-directory-relative** `url`s, so it resolves correctly whether
+  hosted under the project-Pages subpath (`/syntaur/`) or, later, a custom domain at an
+  origin root — no regeneration needed to adopt a CNAME.
+
 ## Usage
 
 ```bash

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

@@ -29,7 +29,7 @@ If the assignment is actually done, use `complete-assignment` instead so a hando
 Optional flags from the user:
 
 - `--keep-session` — preserve `sessionId` / `transcriptPath` fields in `context.json` (just strip the assignment fields). Default: full delete.
-- `--unassign` — also run `syntaur unassign <slug> --project <project>` so the assignment is no longer claimed by this agent. Default: leave the claim in place (only the local context is cleared). Skip this flag if the CLI does not support `unassign` in the installed version — fall back to leaving the claim alone and tell the user.
+- `--unassign` — also run `syntaur unassign <slug> --project <project>` so the assignment is no longer claimed by this agent. Default: leave the claim in place (only the local context is cleared).
 
 ## Step 1: Load Context
 
@@ -66,7 +66,7 @@ syntaur unassign <assignment-slug> --project <project-slug>
 
 For standalone assignments use the UUID (the folder name) in place of the slug, and omit `--project`.
 
-If the CLI rejects the command (older versions may not implement `unassign`), report the error and continue — the local context clear in Step 4 still happens.
+`syntaur unassign` clears the assignee on the assignment frontmatter (the inverse of `assign`) and bumps `updated`.
 
 ## Step 4: Clear the Context File
 

package/platforms/claude-code/skills/log-progress/SKILL.md

@@ -16,9 +16,12 @@ metadata:
 # Log Progress
 
 Append a structured timestamped entry to the active assignment's
-`<assignmentDir>/progress.md`, and update its frontmatter. Markdown-only —
-no CLI verb. Idempotent in the sense that re-running with the same body
-produces a duplicate entry, which is intentional (timestamps differ).
+`<assignmentDir>/progress.md`, and update its frontmatter. CLI-mediated via
+`syntaur progress log "<text>"` — the command stamps the timestamp, inserts the
+entry reverse-chronologically (newest right after the `# Progress` H1), replaces
+the `No progress yet.` placeholder, bumps `entryCount` + `updated`, and preserves
+the `assignment`/`generated` frontmatter. Re-running with the same body produces a
+duplicate entry, which is intentional (timestamps differ).
 
 This skill implements the **Keep Records Updated** playbook: agents must keep
 records current in real-time, especially after every meaningful action.
@@ -55,34 +58,29 @@ The entry should be concise, factual, and link-rich. Suggested structure:
 Optional notes paragraph.
 ```
 
-Use ISO 8601 with `Z` suffix (e.g. `2026-05-08T20:13:00Z`). Use absolute
-file paths or repo-relative paths consistently.
+The CLI stamps the ISO 8601 `Z` timestamp for you. Use absolute file paths or
+repo-relative paths consistently in the body.
 
-## Step 3: Read existing progress.md
+## Step 3: Log the entry via the CLI
 
-Read `<assignmentDir>/progress.md`. Extract:
+Run:
 
-- Current `entryCount` from the frontmatter.
-- The full body (everything after the second `---`).
-
-If `progress.md` doesn't exist, abort and tell the user to re-grab the
-assignment (the file should always exist for an in-progress assignment).
-
-## Step 4: Compute new frontmatter
-
-- `entryCount`: increment by 1.
-- `updated`: set to current ISO timestamp.
-- Other fields (`assignment`, `generated`): preserve as-is.
+```bash
+syntaur progress log "<your composed entry body>"
+```
 
-## Step 5: Write the file
+The command resolves the active assignment from `.syntaur/context.json`
+(or pass `--assignment <slug> [--project <slug>]` to target one explicitly),
+then atomically:
 
-Write back the file with the updated frontmatter and the new entry **prepended**
-to the body (newest first), per the Keep Records Updated playbook and
-`skills/syntaur-protocol/references/protocol-summary.md`. Reverse-chronological
-order: the new `## <ISO 8601 timestamp>` heading sits immediately after the
-`# Progress` H1, with one blank line separating it from any prior entry.
+- Inserts the entry immediately after the `# Progress` H1 (newest first,
+  reverse-chronological), replacing the `No progress yet.` placeholder on the
+  first real entry.
+- Increments `entryCount` and bumps `updated`, preserving `assignment` and
+  `generated`.
 
-Layout:
+Quote the body so the shell passes it as a single argument. Multi-line bodies
+are fine inside the quotes. The resulting layout is:
 
 ```markdown
 # Progress
@@ -94,32 +92,15 @@ Layout:
 ## <prior ISO timestamp>
 
 <prior entry body>
-
-## <even-older ISO timestamp>
-
-<even-older entry body>
 ```
 
-If the existing body is the placeholder text "No progress yet.", replace it
-with the new entry instead of preserving the placeholder.
-
-> **Why prepend:** the dashboard and downstream readers expect the most recent
-> entry first. Appending at the end would silently break the convention
-> documented in `~/.syntaur/playbooks/keep-records-updated.md`.
-
-## Step 6: Verify schema
-
-Confirm by re-reading the file:
-
-- Starts with `---`, then frontmatter, then `---`.
-- `entryCount` is a non-negative integer.
-- `updated` matches the timestamp you wrote.
-- The new entry's `## <timestamp>` heading is present.
-
-If the file fails schema check, restore the prior content and report the
-error — do not leave it partially written.
+> **Why the CLI:** the insert/ordering/`entryCount`/placeholder rules used to be
+> hand-applied (and easy to get subtly wrong). `syntaur progress log` is the
+> single, validated writer — the dashboard and downstream readers expect the
+> most recent entry first, the convention documented in
+> `~/.syntaur/playbooks/keep-records-updated.md`.
 
-## Step 7: Report to User
+## Step 4: Report to User
 
 Summarize:
 

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

@@ -76,7 +76,24 @@ Remember this `planFilename` and `versionLabel` for Steps 5b and 5c.
 
 ### 5b. Write the plan file
 
-Write `<assignmentDir>/<planFilename>` with standard plan frontmatter:
+**Scaffold via the CLI — do not hand-write the file or frontmatter.**
+
+- **Initial plan** (`planFilename` is `plan.md`, no plan files exist yet): run
+
+  ```bash
+  syntaur plan create
+  ```
+
+  (or `--assignment <slug> [--project <slug>]` to target one explicitly). This
+  writes `plan.md` with the standard `draft` frontmatter AND appends the
+  four-todo cycle to assignment.md `## Todos` — so **Step 5c is already done for
+  the initial plan**; skip it and proceed to fill in the body sections below.
+
+- **New version** (`planFilename` is `plan-v<N>.md`): run `syntaur plan version`,
+  which scaffolds `plan-v<N>.md`, supersedes the prior cycle, and carries forward
+  unchecked tasks (this is Step 5c for the versioned case).
+
+The scaffolded frontmatter is:
 
 ```yaml
 ---
@@ -87,6 +104,8 @@ updated: "<nowTimestamp>"
 ---
 ```
 
+Then edit the scaffolded plan file in place to add the body sections below.
+
 Body sections:
 
 1. **Overview** — one paragraph summarizing the approach.

package/platforms/claude-code/skills/save-session-summary/SKILL.md

@@ -36,30 +36,12 @@ Extract:
 
 If `sessionId` is missing, empty, or `null`, abort with: "Session not tracked. Run `syntaur track-session ...` first." Do not invent or generate a session id.
 
-## Step 2: Ensure Session Directory
+## Step 2: Author the summary body
 
-Create `<assignmentDir>/sessions/<sessionId>/` only at this step (not earlier — empty session dirs are noise). Use `mkdir -p` semantics so re-saves are idempotent.
-
-## Step 3: Read Existing Summary (if any)
-
-If `<assignmentDir>/sessions/<sessionId>/summary.md` already exists, read it and preserve its `created` frontmatter timestamp. Otherwise, the new file's `created` is now.
-
-This is a **single document per session id** — every save in the same session overwrites in place. The directory partitions by session id, so older sessions remain on disk as immutable history.
-
-## Step 4: Write the Summary
-
-Write `<assignmentDir>/sessions/<sessionId>/summary.md` with this structure (overwrite if it exists). Fill the section bodies with content derived from this session's actual work — be specific and concrete, this is what a future session will load to resume.
+Compose the markdown body — be specific and concrete, this is what a future
+session loads to resume. Use these sections:
 
 ```markdown
----
-assignment: <assignment-slug>
-sessionId: <session-id>
-created: "<original created timestamp, or now if new>"
-updated: "<now, ISO 8601>"
----
-
-# Session Summary
-
 ## Snapshot
 
 <One paragraph: what the assignment is, where work currently stands, what is load-bearing for a future session to know immediately on resume.>
@@ -68,19 +50,15 @@ updated: "<now, ISO 8601>"
 
 - <Concrete action 1>
 - <Concrete action 2>
-- ...
 
 ## What's Next
 
 - <Most important next step>
 - <Subsequent steps in order>
-- ...
 
 ## Open Questions
 
 - <Unresolved question or decision>
-- <Ambiguity to resolve>
-- ...
 (or "None." if no open items)
 
 ## Load-Bearing Context
@@ -91,7 +69,28 @@ updated: "<now, ISO 8601>"
 - External references (PRs, issues, docs) that scope the next steps
 ```
 
-## Step 5: Confirm — Do NOT Touch handoff.md
+## Step 3: Write via the CLI
+
+Pass the body to `syntaur session save` (it owns the directory, frontmatter,
+and `created`-preservation):
+
+```bash
+syntaur session save --session-id <sessionId> --from-file <body.md>
+# or pipe it:  printf '%s' "$BODY" | syntaur session save --session-id <sessionId>
+```
+
+Resolves the active assignment from `.syntaur/context.json` (or pass
+`--assignment <slug> [--project <slug>]`), and `--session-id` defaults to the
+context's `sessionId`. The command:
+
+- Creates `<assignmentDir>/sessions/<sessionId>/` (idempotent) and writes
+  `summary.md` — a **single document per session id**, overwritten in place;
+  older sessions remain on disk as immutable history.
+- Preserves the existing `created` frontmatter timestamp on re-save (new file →
+  `created = now`); always stamps `assignment`, `sessionId`, and `updated`.
+- Writes the standard section skeleton if no body is supplied.
+
+## Step 4: Confirm — Do NOT Touch handoff.md
 
 Verify your write did not modify `<assignmentDir>/handoff.md`. The two artifacts are deliberately separate:
 
@@ -100,11 +99,11 @@ Verify your write did not modify `<assignmentDir>/handoff.md`. The two artifacts
 | `handoff.md` | Assignment-level | At completion (via `complete-assignment`) | Next ticket / agent / human reviewer |
 | `sessions/<sid>/summary.md` | Session-scoped | Mid-assignment, on demand or pre-compact | Future session of the same agent on the same assignment |
 
-## Step 6: Append a Progress Entry (optional but recommended)
+## Step 5: Append a Progress Entry (optional but recommended)
 
-If progress hasn't already been logged in this turn, append a brief entry to `<assignmentDir>/progress.md` noting that a session summary was saved and the next-step pointer.
+If progress hasn't already been logged in this turn, run `syntaur progress log "<note>"` noting that a session summary was saved and the next-step pointer.
 
-## Step 7: Report to User
+## Step 6: Report to User
 
 Summarize:
 - Path of the written summary

package/platforms/claude-code/skills/set-workspace/SKILL.md

@@ -41,21 +41,9 @@ Read `.syntaur/context.json` from the current working directory. Extract
 If no context, abort with: "No active assignment. Run `grab-assignment`
 first."
 
-## Step 2: Pre-write validation
+## Step 2: Gather inputs
 
-```bash
-syntaur doctor --assignment <assignmentDir>/assignment.md --json
-```
-
-Parse the JSON output. If `ok: false`, refuse to proceed. Report the
-`errors[]` to the user verbatim and recommend they fix the underlying
-frontmatter (or run `syntaur doctor` for the broader project context).
-**Do not write any changes if the file is malformed.**
-
-## Step 3: Gather inputs
-
-Required (one or more — at minimum the user must specify enough to fill
-all four fields):
+At minimum specify enough to fill the four fields:
 
 - `--repository <path>` — repo root (typically `git rev-parse --show-toplevel`).
 - `--worktree-path <path>` — usually `<repository>/.worktrees/<branch>`
@@ -63,47 +51,43 @@ all four fields):
 - `--branch <name>` — current branch (`git rev-parse --abbrev-ref HEAD`).
 - `--parent-branch <name>` — typically `main`.
 
-Defaults the skill should auto-detect when not supplied:
+Defaults to auto-detect when not supplied:
 
 - `repository` ← `git -C $(pwd) rev-parse --show-toplevel`.
 - `branch` ← `git -C $(pwd) rev-parse --abbrev-ref HEAD`.
 - `worktreePath` ← `$(pwd)` (when invoked from the worktree itself).
 - `parentBranch` ← prompt the user; do not invent.
 
-## Step 4: Read assignment.md
+## Step 3: Write via the CLI
 
-Locate the `workspace:` block in the frontmatter. It must look like:
-
-```yaml
-workspace:
-  repository: <value-or-null>
-  worktreePath: <value-or-null>
-  branch: <value-or-null>
-  parentBranch: <value-or-null>
+```bash
+syntaur workspace set \
+  --repository <repo> \
+  --worktree-path <repo>/.worktrees/<branch> \
+  --branch <branch> \
+  --parent-branch <parent>
 ```
 
-If the block is missing entirely, refuse to write — `doctor --assignment`
-should have caught it; this is a defensive check.
-
-## Step 5: Write the four fields
-
-Replace the four lines in place. Quote string values containing special
-characters; use `null` literal for unset fields. Preserve the rest of the
-frontmatter and body bit-for-bit.
-
-Bump the top-level `updated` timestamp in the frontmatter.
+Targets the active assignment from `.syntaur/context.json` by default; pass
+`--assignment <slug> [--project <slug>]` to target one explicitly. The command
+does the whole safe write in one atomic step:
 
-## Step 6: Re-validate
+- **Pre-write validation** — runs the same checks as `syntaur doctor
+  --assignment --json`; if the file is malformed it refuses to write and prints
+  the errors. (Implements the "never touch a malformed file" guard.)
+- Writes the four `workspace.*` fields in place via the frontmatter mutator
+  (other same-named keys elsewhere are untouched) and bumps the top-level
+  `updated` timestamp.
+- **Post-write re-validation** — if the result is somehow invalid, it restores
+  the original file and exits non-zero, so the file is never left half-written.
 
-Re-run `syntaur doctor --assignment <path> --json`. Expect `ok: true`. If
-the post-write validation fails, restore the prior file content and report
-the error — do not leave the file in a half-written state.
+If the command exits non-zero, report its `Error:` output verbatim and fix the
+underlying frontmatter before retrying.
 
-## Step 7: Report to User
+## Step 4: Report to User
 
 Summarize:
 
-- Path of the modified assignment.md.
+- Path of the modified assignment.md (the command prints it).
 - The four field values that were written.
-- Confirmation that post-write `doctor --assignment` passed.
 - Reminder: implementation work is now unblocked by the write-boundary hook.

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

@@ -29,7 +29,7 @@ If the assignment is actually done, use `complete-assignment` instead so a hando
 Optional flags from the user:
 
 - `--keep-session` — preserve `sessionId` / `transcriptPath` fields in `context.json` (just strip the assignment fields). Default: full delete.
-- `--unassign` — also run `syntaur unassign <slug> --project <project>` so the assignment is no longer claimed by this agent. Default: leave the claim in place (only the local context is cleared). Skip this flag if the CLI does not support `unassign` in the installed version — fall back to leaving the claim alone and tell the user.
+- `--unassign` — also run `syntaur unassign <slug> --project <project>` so the assignment is no longer claimed by this agent. Default: leave the claim in place (only the local context is cleared).
 
 ## Step 1: Load Context
 
@@ -66,7 +66,7 @@ syntaur unassign <assignment-slug> --project <project-slug>
 
 For standalone assignments use the UUID (the folder name) in place of the slug, and omit `--project`.
 
-If the CLI rejects the command (older versions may not implement `unassign`), report the error and continue — the local context clear in Step 4 still happens.
+`syntaur unassign` clears the assignee on the assignment frontmatter (the inverse of `assign`) and bumps `updated`.
 
 ## Step 4: Clear the Context File
 

package/platforms/codex/skills/log-progress/SKILL.md

@@ -16,9 +16,12 @@ metadata:
 # Log Progress
 
 Append a structured timestamped entry to the active assignment's
-`<assignmentDir>/progress.md`, and update its frontmatter. Markdown-only —
-no CLI verb. Idempotent in the sense that re-running with the same body
-produces a duplicate entry, which is intentional (timestamps differ).
+`<assignmentDir>/progress.md`, and update its frontmatter. CLI-mediated via
+`syntaur progress log "<text>"` — the command stamps the timestamp, inserts the
+entry reverse-chronologically (newest right after the `# Progress` H1), replaces
+the `No progress yet.` placeholder, bumps `entryCount` + `updated`, and preserves
+the `assignment`/`generated` frontmatter. Re-running with the same body produces a
+duplicate entry, which is intentional (timestamps differ).
 
 This skill implements the **Keep Records Updated** playbook: agents must keep
 records current in real-time, especially after every meaningful action.
@@ -55,34 +58,29 @@ The entry should be concise, factual, and link-rich. Suggested structure:
 Optional notes paragraph.
 ```
 
-Use ISO 8601 with `Z` suffix (e.g. `2026-05-08T20:13:00Z`). Use absolute
-file paths or repo-relative paths consistently.
+The CLI stamps the ISO 8601 `Z` timestamp for you. Use absolute file paths or
+repo-relative paths consistently in the body.
 
-## Step 3: Read existing progress.md
+## Step 3: Log the entry via the CLI
 
-Read `<assignmentDir>/progress.md`. Extract:
+Run:
 
-- Current `entryCount` from the frontmatter.
-- The full body (everything after the second `---`).
-
-If `progress.md` doesn't exist, abort and tell the user to re-grab the
-assignment (the file should always exist for an in-progress assignment).
-
-## Step 4: Compute new frontmatter
-
-- `entryCount`: increment by 1.
-- `updated`: set to current ISO timestamp.
-- Other fields (`assignment`, `generated`): preserve as-is.
+```bash
+syntaur progress log "<your composed entry body>"
+```
 
-## Step 5: Write the file
+The command resolves the active assignment from `.syntaur/context.json`
+(or pass `--assignment <slug> [--project <slug>]` to target one explicitly),
+then atomically:
 
-Write back the file with the updated frontmatter and the new entry **prepended**
-to the body (newest first), per the Keep Records Updated playbook and
-`skills/syntaur-protocol/references/protocol-summary.md`. Reverse-chronological
-order: the new `## <ISO 8601 timestamp>` heading sits immediately after the
-`# Progress` H1, with one blank line separating it from any prior entry.
+- Inserts the entry immediately after the `# Progress` H1 (newest first,
+  reverse-chronological), replacing the `No progress yet.` placeholder on the
+  first real entry.
+- Increments `entryCount` and bumps `updated`, preserving `assignment` and
+  `generated`.
 
-Layout:
+Quote the body so the shell passes it as a single argument. Multi-line bodies
+are fine inside the quotes. The resulting layout is:
 
 ```markdown
 # Progress
@@ -94,32 +92,15 @@ Layout:
 ## <prior ISO timestamp>
 
 <prior entry body>
-
-## <even-older ISO timestamp>
-
-<even-older entry body>
 ```
 
-If the existing body is the placeholder text "No progress yet.", replace it
-with the new entry instead of preserving the placeholder.
-
-> **Why prepend:** the dashboard and downstream readers expect the most recent
-> entry first. Appending at the end would silently break the convention
-> documented in `~/.syntaur/playbooks/keep-records-updated.md`.
-
-## Step 6: Verify schema
-
-Confirm by re-reading the file:
-
-- Starts with `---`, then frontmatter, then `---`.
-- `entryCount` is a non-negative integer.
-- `updated` matches the timestamp you wrote.
-- The new entry's `## <timestamp>` heading is present.
-
-If the file fails schema check, restore the prior content and report the
-error — do not leave it partially written.
+> **Why the CLI:** the insert/ordering/`entryCount`/placeholder rules used to be
+> hand-applied (and easy to get subtly wrong). `syntaur progress log` is the
+> single, validated writer — the dashboard and downstream readers expect the
+> most recent entry first, the convention documented in
+> `~/.syntaur/playbooks/keep-records-updated.md`.
 
-## Step 7: Report to User
+## Step 4: Report to User
 
 Summarize:
 

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

@@ -76,7 +76,24 @@ Remember this `planFilename` and `versionLabel` for Steps 5b and 5c.
 
 ### 5b. Write the plan file
 
-Write `<assignmentDir>/<planFilename>` with standard plan frontmatter:
+**Scaffold via the CLI — do not hand-write the file or frontmatter.**
+
+- **Initial plan** (`planFilename` is `plan.md`, no plan files exist yet): run
+
+  ```bash
+  syntaur plan create
+  ```
+
+  (or `--assignment <slug> [--project <slug>]` to target one explicitly). This
+  writes `plan.md` with the standard `draft` frontmatter AND appends the
+  four-todo cycle to assignment.md `## Todos` — so **Step 5c is already done for
+  the initial plan**; skip it and proceed to fill in the body sections below.
+
+- **New version** (`planFilename` is `plan-v<N>.md`): run `syntaur plan version`,
+  which scaffolds `plan-v<N>.md`, supersedes the prior cycle, and carries forward
+  unchecked tasks (this is Step 5c for the versioned case).
+
+The scaffolded frontmatter is:
 
 ```yaml
 ---
@@ -87,6 +104,8 @@ updated: "<nowTimestamp>"
 ---
 ```
 
+Then edit the scaffolded plan file in place to add the body sections below.
+
 Body sections:
 
 1. **Overview** — one paragraph summarizing the approach.