@ulysses-ai/create-workspace 0.16.0-beta.0 → 0.16.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.16.0-beta.0",
+  "version": "0.16.0-beta.1",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

package/template/.claude/rules/goal-driven-work.md

@@ -15,6 +15,7 @@ If any of the three fails, prefer plain session work or a single skill invocatio
 ## File layout
 
 - One `goal-{topic}.md` artifact at the top of the active worktree, alongside `session.md`. One goal per worktree.
+- The artifact's frontmatter holds machine state; its body holds the human-readable goal statement, per-phase intent, and a mandatory `## Start command` section (see "Kicking off the goal") with the literal `/goal "..."` invocation the user runs to start the loop.
 - Phase output artifacts live as siblings. `research-*.md` and `crossref-*.md` are goal-native (produced by `parallel-research` and `crossref` phase types). `design-*.md` and `plan-*.md` are pre-existing session-artifact patterns that `type: skill` phases reuse when the wrapped skill is `superpowers:brainstorming` or `superpowers:writing-plans`; they are not goal-specific.
 - The artifact is tracked on the session branch and lives there until `/complete-work` runs. It is removed from the branch before the final PR alongside other session artifacts.
 
@@ -192,9 +193,31 @@ All phases in goal-<topic>.md show status: complete. Phase artifacts exist at: <
 
 Fill in `<topic>`, paths, and `<N>` per goal. Anchor on artifacts and committed state, not on feelings.
 
+## Kicking off the goal
+
+`/goal` is a Claude Code built-in that the **user** types — the agent cannot invoke it. So the moment the artifact is ready is the load-bearing hand-off, and the artifact itself carries the instruction rather than relying on an agent chat message that vanishes on the next compaction or resume.
+
+Every `goal-{topic}.md` body MUST include a `## Start command` section containing the literal, copy-paste-ready invocation:
+
+````markdown
+## Start command
+
+```
+/goal "All phases in goal-<topic>.md show status: complete. Phase artifacts exist at: <paths>. The /complete-work skill has produced release notes and opened the final PR; the PR URL appeared in the transcript. Or stop after <N> turns."
+```
+````
+
+Rules for the `## Start command`:
+
+- It is the `completion_condition` flattened to a **single line** and wrapped in `/goal "..."`. The frontmatter `completion_condition:` (a multi-line folded scalar) is the auditable source of truth; the start command is its runnable rendering. The two must express the same condition — if you edit one, re-derive the other.
+- Flatten by collapsing the folded scalar's newlines to single spaces. Escape any embedded double quotes. Keep it within the 4000-character `/goal` limit.
+- It lives in the body, not the frontmatter, because it is for a human to copy, not for machine parsing.
+
+When the artifact is drafted and the user has reviewed it, the agent's hand-off is: point the user at the `## Start command` block and let them run it. Running it flips the goal from `status: pending` to `status: active` (the first `/goal` turn updates the frontmatter per the dispatch pattern). The agent never types `/goal` itself.
+
 ## Lifecycle integration
 
-- `/goal` runs inside an active work session. It does NOT replace `/start-work`. The session is created the normal way, the goal artifact is drafted at the worktree top, then `/goal "<condition>"` kicks off the loop.
+- `/goal` runs inside an active work session. It does NOT replace `/start-work`. The session is created the normal way, the goal artifact is drafted at the worktree top (including its `## Start command` block), and the user runs that block's `/goal "..."` command to kick off the loop.
 - The goal artifact lives on the session branch and travels with `git push`. It survives across machines and `--resume`.
 - `session.md`'s `## Tasks` should mirror the phase list at coarse grain (one task per phase) so `TodoWrite` shows high-level progress. The main agent updates `## Tasks` at phase transitions via the helper specified by the `task-list-mirroring` rule, in addition to updating `goal-{topic}.md`.
 - `/pause-work` works without special handling. The goal-evaluator state resets on resume per the Claude Code docs; phase state is durable in the artifact.
@@ -218,9 +241,9 @@ When the goal artifact is itself the deliverable for a future session to execute
 
 ## Appendix: worked example
 
-A complete `goal-evaluate-rate-limiting.md` illustrating all three phase types. The topic is intentionally generic — the example is reference material, not prescriptive.
+A complete `goal-evaluate-rate-limiting.md` illustrating all three phase types. The topic is intentionally generic — the example is reference material, not prescriptive. (The appendix is fenced with four backticks so the example's own `## Start command` code block renders intact.)
 
-```yaml
+````yaml
 ---
 type: goal
 topic: evaluate-rate-limiting
@@ -357,6 +380,14 @@ The api-gateway needs rate limiting before the next traffic step-up. This
 goal runs the full arc from candidate-algorithm research through implementation
 on the session branch.
 
+## Start command
+
+```
+/goal "All 5 phases in goal-evaluate-rate-limiting.md show status: complete. Phase artifacts exist at: research-rate-limiting-strategies.md, crossref-existing-infrastructure.md, design-rate-limiting.md, plan-rate-limiting.md, and the implementation commits land on the session branch (visible in git log). The /complete-work skill has produced release notes and opened the final PR; the PR URL appeared in the transcript. Or stop after 60 turns."
+```
+
+This is the frontmatter `completion_condition` flattened to one line. Run it after reviewing the artifact; it flips the goal to `status: active`.
+
 ## Per-phase intent
 
 1. **strategy-research** runs three researchers in parallel, one per
@@ -385,4 +416,4 @@ All phase agents and synthesizers run on Sonnet (the default for team work).
 The main agent reading and orchestrating this goal runs on Opus. Haiku is
 unused in this example; it would be appropriate for a phase whose sole job
 is, e.g., scanning a tree and returning a tagged file list.
-```
+````

package/template/.claude/skills/complete-work/SKILL.md

@@ -21,6 +21,7 @@ Determine paths:
 - Workspace worktree: `work-sessions/{session-name}/workspace/`
 - Project worktrees: `work-sessions/{session-name}/workspace/repos/{repo}/` for each repo in the tracker's `repos:` list
 - Read each repo's default branch from workspace.json (`repos.{repo}.branch`)
+- **Release-notes base directory.** Read `workspace.releaseNotesDir` from `workspace.json` (default `workspace-context/release-notes` if the field is absent). Throughout this skill `{releaseNotesDir}` refers to that resolved value; every branch-note path is `{releaseNotesDir}/unreleased/{repo}/…`. Never use a bare `release-notes/`.
 
 ### Step 2: Rebase project repos
 
@@ -86,10 +87,10 @@ For each repo in the tracker's `repos:` list that has commits beyond the base br
 cd work-sessions/{session-name}/workspace/repos/{repo}
 COMMIT_ID=$(git rev-parse --short HEAD)
 cd ../..  # back to the workspace worktree
-mkdir -p release-notes/unreleased/{repo-name}
+mkdir -p {releaseNotesDir}/unreleased/{repo-name}
 ```
 
-**File 1: `release-notes/unreleased/{repo-name}/branch-release-notes-{COMMIT_ID}.md`** (relative to the workspace worktree)
+**File 1: `{releaseNotesDir}/unreleased/{repo-name}/branch-release-notes-{COMMIT_ID}.md`** (relative to the workspace worktree)
 ```markdown
 ---
 branch: {branch}
@@ -105,7 +106,7 @@ date: {YYYY-MM-DD}
 Written from scratch per coherent-revisions rule.}
 ```
 
-**File 2: `release-notes/unreleased/{repo-name}/branch-release-questions-{COMMIT_ID}.md`**
+**File 2: `{releaseNotesDir}/unreleased/{repo-name}/branch-release-questions-{COMMIT_ID}.md`**
 ```markdown
 ---
 branch: {branch}
@@ -124,7 +125,7 @@ The `repo:` frontmatter field is what `/release` uses to know which project repo
 After all repos are processed, commit once on the workspace branch:
 ```bash
 cd work-sessions/{session-name}/workspace
-git add release-notes/unreleased/
+git add {releaseNotesDir}/unreleased/
 git commit -m "docs: add release notes for {branch}"
 ```
 
@@ -459,7 +460,7 @@ Ask: "These changes weren't part of a formal work session. What do you want to d
 - **Revert** — undo the changes (with confirmation)
 
 ## Notes
-- Branch release notes live in the WORKSPACE repo at `release-notes/unreleased/{repo-name}/` — never in project repos. Project repos only ever see code commits and (at release time) `CHANGELOG.md` entries written by `/release`.
+- Branch release notes live in the WORKSPACE repo at `{releaseNotesDir}/unreleased/{repo-name}/` (resolved from `workspace.json` → `workspace.releaseNotesDir`, default `workspace-context/release-notes`) — never in project repos. Project repos only ever see code commits and (at release time) `CHANGELOG.md` entries written by `/release`.
 - The session tracker's body is the primary source for release note synthesis — it captures the full session history alongside specs and plans
 - All repos get PRed and merged together — one approval for all
 - Version bumps happen in `/release`, not `/complete-work` — this avoids version drift when multiple feature branches land between releases

package/template/.claude/skills/release/SKILL.md

@@ -27,10 +27,12 @@ Check `workspace.json` for `releaseMode`:
 - **workspace**: process all repos together
 - **ask**: "Process all repos together or individually?"
 
+**Release-notes base directory.** Read `workspace.releaseNotesDir` from `workspace.json` (default `workspace-context/release-notes` if the field is absent). Throughout this skill `{releaseNotesDir}` refers to that resolved value; every branch-note path is `{releaseNotesDir}/unreleased/{repo}/…`. Never use a bare `release-notes/`.
+
 **Step 2: Read unreleased notes**
 Branch notes live in the **workspace** repo, written there by `/complete-work`. For each target repo, list the workspace's unreleased subdirectory for that project:
 ```bash
-ls release-notes/unreleased/{repo}/
+ls {releaseNotesDir}/unreleased/{repo}/
 ```
 Read all `branch-release-notes-*.md` and `branch-release-questions-*.md` files.
 
@@ -71,9 +73,9 @@ The entry stays short. If a change needs more detail, reference the repo's docs
 
 **Step 6: Delete consumed branch notes from the workspace**
 ```bash
-rm release-notes/unreleased/{repo}/branch-release-*
+rm {releaseNotesDir}/unreleased/{repo}/branch-release-*
 # If the directory is now empty, remove it too:
-rmdir release-notes/unreleased/{repo} 2>/dev/null || true
+rmdir {releaseNotesDir}/unreleased/{repo} 2>/dev/null || true
 ```
 The branch notes were an intermediate capture; their content is now in the CHANGELOG entry and their raw form in git history. They do not survive into the project repo.
 
@@ -98,7 +100,7 @@ Skip this step if the repo has no package.json or no version field.
 **Step 7c: Commit the consumed-notes deletion in the workspace**
 ```bash
 # From the workspace root
-git add release-notes/unreleased/
+git add {releaseNotesDir}/unreleased/
 git commit -m "release: consume {repo} branch notes for v{version}"
 ```
 Workspace and project repos have separate commits — they are separate git histories.
@@ -138,7 +140,7 @@ Process ephemeral workspace-context entries:
 ## Notes
 
 - Release entries live in `CHANGELOG.md` at the project repo root — one file, one concise entry per version. No `release-notes/v*.md`, no `release-notes/archive/`.
-- Branch notes live in the WORKSPACE at `release-notes/unreleased/{repo}/`. `/complete-work` writes them; `/release` consumes and deletes them. They never reach project repos.
+- Branch notes live in the WORKSPACE at `{releaseNotesDir}/unreleased/{repo}/` (resolved from `workspace.json` → `workspace.releaseNotesDir`, default `workspace-context/release-notes`). `/complete-work` writes them; `/release` consumes and deletes them. They never reach project repos.
 - Versions are bumped here, not in `/complete-work`. This keeps the version semantics aligned with what actually shipped (accumulated changes since last release).
 - The public repo stays lean. Detailed per-branch retrospection exists in workspace git history (the consumed-notes commit) but is not surfaced as standalone files in either repo.
 - Context synthesis happens in the WORKSPACE repo — Step 7c (consumed-notes) and Step 9 (workspace-context synthesis) are separate workspace commits.