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

package/README.md

@@ -89,7 +89,7 @@ Four things, in the order you'll touch them:
 A scaffolded workspace with:
 
 - **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
-- **7 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
+- **8 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
 - **10 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
 - A **`shared-context/`** memory system with three visibility levels: locked (team truths), root (team-visible ephemerals), user-scoped (personal)
 - Conventions for **multi-repo work sessions** with isolated git worktrees, parallelizable from separate terminals

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.15.0-beta.2",
+  "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

@@ -0,0 +1,419 @@
+# Goal-Driven Work
+
+How to use Claude Code's built-in `/goal` command in a Ulysses workspace for multi-phase, agent-team-driven work. `/goal` is the autonomy loop; this rule is the convention layer that gives the main agent durable phase state and a consistent dispatch pattern across turns and resumes.
+
+## When to reach for `/goal`
+
+Use `/goal` when the work meets all three:
+
+1. **Multi-phase.** It naturally decomposes into discrete phases (research, design, implementation, validation, etc.) and the phases produce intermediate artifacts before the work is done.
+2. **Verifiable end state.** "Done" can be demonstrated from the conversation transcript — a PR opened, a set of artifacts written, a test suite passing — rather than judged subjectively.
+3. **Spans more than one or two turns of natural conversation.** Single-skill invocations (one brainstorm, one plan, one fix) don't need `/goal`; the existing skills carry them.
+
+If any of the three fails, prefer plain session work or a single skill invocation. `/goal` is overhead. Pay it only when the work is long enough to earn it.
+
+## 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.
+
+## Frontmatter schema
+
+```yaml
+---
+type: goal
+topic: <kebab-case-topic>
+status: active                  # pending | active | complete | cancelled
+                                # pending: artifact written but /goal not yet invoked
+                                # active: /goal loop is running
+                                # complete: all phases complete and condition met
+                                # cancelled: goal abandoned without completion
+current_phase: <phase-name>     # the phase currently in progress or next up
+completion_condition: >         # mirrored from the `/goal` text so it survives `/goal clear` and is auditable
+  <multi-line condition string>
+turn_budget: <int>              # backstop; the condition itself should reference it
+phases:
+  - name: <phase-name>
+    type: parallel-research | crossref | skill
+    status: pending             # pending | in_progress | complete | failed
+    artifact: <path or null>    # output artifact path, relative to worktree top; null for phases that commit to repo
+    gate: review | auto         # default: review
+
+    # for type: parallel-research
+    team:
+      agents:
+        - subagent_type: <type>
+          brief: |
+            <multi-line brief>
+        - subagent_type: <type>
+          brief: |
+            <multi-line brief>
+      synthesizer:
+        subagent_type: <type>
+        brief: |
+          <multi-line brief: reads sibling agent outputs, writes the phase artifact>
+
+    # for type: crossref
+    inputs:
+      independent: <path to the just-produced independent artifact>
+      against: <path or list of paths to compare against>
+    brief: |
+      <multi-line brief for the crossref agent>
+
+    # for type: skill
+    skill: <plugin:skill-name>   # e.g. superpowers:brainstorming
+---
+```
+
+Body of the file is human-readable: the goal statement, success criteria, and per-phase intent in prose. The frontmatter is the source of truth for machine state; the body explains it to a reader.
+
+## Phase types
+
+Three types in v1. Prefer wrapping existing skills (`type: skill`) when a skill fits. Only invent a phase type when no skill covers the work.
+
+- **`parallel-research`**: dispatch N researcher-style agents in parallel with independent briefs. Optionally run a synthesizer agent over their outputs to write one consolidated artifact. Use for tool surveys, option-space exploration, comparative research where work can be partitioned.
+- **`crossref`**: given source A (the independent output the team just produced) and source B (existing material to validate against), dispatch an agent to produce a gap-and-overlap matrix plus a ranked list of validations and concerns. Use to compare independent work against prior research, canonical workspace context, or third-party material.
+- **`skill`**: invoke an existing skill by name. The phase's `artifact:` path is the expected output location (or `null` for phases that commit to repo, like `executing-plans`). Use this for `brainstorming`, `writing-plans`, `executing-plans`, `test-driven-development`, or any other skill that fits the phase's intent.
+
+If a new phase type appears to be needed, justify why no existing skill fits before adding it. New phase types are a maintenance cost. Prefer keeping `parallel-research` and `crossref` inline until cross-goal reuse pressure makes the extraction earn its keep.
+
+## Agent-team dispatch pattern (v1: stateless)
+
+A "team" is just a list of `Agent`-tool dispatch configs (`subagent_type` + `brief`). Spawned fresh each phase. No persistent identity, no memory across phases except what's written into artifacts.
+
+The main agent's responsibility per phase:
+
+1. Mark the phase `in_progress` in `goal-{topic}.md` frontmatter.
+2. Dispatch the team via the `Agent` tool, in parallel where independent. The brief for each agent is exactly the `brief:` field from the phase config, prefixed with any context the brief itself doesn't already carry (typically a pointer to relevant sibling artifacts).
+3. Collect agent outputs.
+4. If a `synthesizer` is declared, dispatch it with the sibling outputs and have it write the `artifact:` file.
+5. If no synthesizer, the main agent writes the `artifact:` file directly from the collected outputs.
+6. Mark the phase `complete`, update `current_phase` to the next pending phase.
+7. End the turn with a short status note (for the `/goal` evaluator) and, if `gate: review`, an explicit question to the user.
+
+The artifact format supports adding a `persistent: true` flag on a phase team later if a future goal needs team continuity across phases. Don't add the field until something asks for it.
+
+## Gate convention
+
+`gate: review` is the default for every phase. At the gate, the main agent ends its turn by asking the user to approve, reject with feedback, or pause.
+
+- **approve** → phase stays `complete`, advance to next phase next turn.
+- **reject with feedback** → flip phase back to `pending` and re-run it with the feedback prepended to the team brief.
+- **pause** → state is durable in `goal-{topic}.md`; resume with `claude --resume`.
+
+The evaluator's "no, awaiting review" response after a gated phase does not bypass the wait for user input. It just keeps the session running until the user replies.
+
+`gate: auto` is allowed in the format but discouraged in v1. Earn it after the workflow has been exercised at least once on the work in question.
+
+## Integration branch and per-phase sub-PRs
+
+While a `/goal`-driven session is running, the session branch (`feature/{session-name}`) acts as the goal's integration branch. Main is untouched until `/complete-work` opens the final session→main PR for human review. This is the key autonomy boundary: phase agents can merge their own work, repeatedly, throughout the goal — but only into the integration branch, never into main.
+
+Two merge strategies, picked per phase:
+
+- **Direct commit (default for artifact-only phases).** Phases of type `parallel-research` and `crossref`, and skill phases that wrap artifact-producing skills (`brainstorming`, `writing-plans`), commit their outputs directly to the session branch. These artifacts are stripped before the final PR anyway, so sub-PR ceremony adds nothing.
+- **Sub-branch with self-merged PR (default for code phases).** Skill phases that wrap code-producing skills (`executing-plans`, `test-driven-development`, `subagent-driven-development`) work on a per-phase sub-branch and open a PR back to the session branch. After the phase's gate is satisfied, the main agent self-merges the sub-PR. Each sub-PR is a discrete reviewable unit — failures can be retried by rebuilding just the one sub-branch.
+
+Sub-branch naming follows the existing `git-conventions.md` rule (kebab-case after prefix, no nesting): `feature/{session-name}-{phase-name}`. Examples for a session named `ulysses-goals`:
+
+- `feature/ulysses-goals` — session/integration branch
+- `feature/ulysses-goals-strategy-research` — phase sub-branch (if a research phase were promoted to sub-branch strategy)
+- `feature/ulysses-goals-implement` — phase sub-branch for the implement phase
+
+A phase declares its merge strategy in frontmatter via an optional `integration:` block:
+
+```yaml
+phases:
+  - name: implement
+    type: skill
+    skill: superpowers:executing-plans
+    integration:
+      strategy: sub-branch        # direct | sub-branch
+      branch: feature/{session-name}-implement   # explicit, or derived if omitted
+      self_merge: true            # main agent merges the sub-PR after gate is satisfied; default true
+```
+
+If `integration:` is omitted, defaults are applied by phase type per the list above.
+
+Multi-repo sessions: each project repo has its own session branch (same name across repos per existing convention). Phase sub-branches are created per-repo where the phase commits, with matching names. The sub-PR target in each repo is that repo's session branch.
+
+`/complete-work` verifies before the final PR that every phase sub-branch has been merged into the session branch. If any are outstanding, it fails loudly with a list of unmerged sub-branches. The user resolves them (merge or close) before re-running.
+
+## Model tiering
+
+`/goal`-driven work uses a three-tier model assignment, biased toward the right tool for each shape of work:
+
+- **Opus** for the main orchestration thread. It reads the goal artifact, dispatches phase teams, holds the long-running session context, and makes the per-phase advance/retry decisions. Reasoning-heavy and context-heavy work.
+- **Sonnet** for phase team agents (researchers, crossref agents, skill subagents) and for synthesizers. Heavy lifting that runs in parallel and writes substantial artifacts. The default model for any agent in a `team:` block.
+- **Haiku** for quick checks: file-existence verification, frontmatter validation, status sweeps, tiny lookups. Use when the work is bounded and obvious, and speed matters more than reasoning depth.
+
+Phase frontmatter sets the model per agent via the `model:` field, which maps to the `Agent` tool's `model` parameter:
+
+```yaml
+team:
+  agents:
+    - subagent_type: researcher
+      model: sonnet           # default for parallel-research; rarely overridden
+      brief: |
+        ...
+  synthesizer:
+    subagent_type: researcher
+    model: sonnet
+    brief: |
+      ...
+```
+
+For artifact-only or tagging work where Haiku is enough, declare it explicitly:
+
+```yaml
+- subagent_type: researcher
+  model: haiku
+  brief: |
+    Scan {paths} for files matching {pattern} and return a tagged list.
+```
+
+The main agent's model is determined by the harness (the user's `claude` invocation), not the goal artifact. Goal artifacts assume the main agent runs on Opus.
+
+## Writing a good completion condition
+
+The `/goal` evaluator runs after every turn against the conversation transcript. It does not call tools, so it can only judge what the main turn has surfaced. A good condition is:
+
+- **Specific.** Names the artifacts that must exist (file paths, commit references, PR URLs) rather than vague outcomes.
+- **Demonstrable from transcript.** The main agent's own output must be able to evidence completion. "The PR URL was reported in the transcript and `git status` showed clean" rather than "the work feels done."
+- **Bounded.** Includes a turn budget as a backstop (e.g., "or stop after 60 turns") so the loop can't run away if something goes wrong.
+- **Within the 4000-char limit.** Up to four kilobytes of condition text are accepted.
+
+A reasonable template:
+
+```
+All phases in goal-<topic>.md show status: complete. Phase artifacts exist at: <list 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.
+```
+
+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 (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.
+- `/complete-work` reads `goal-*.md`, `research-*.md`, and `crossref-*.md` for release-note synthesis and strips them from the branch before the final PR, alongside the existing `design-*.md` and `plan-*.md` handling. When a goal artifact is present, it also runs a pre-flight check that every declared sub-branch (from phases with `integration.strategy: sub-branch`) has been merged into the session branch. Unmerged sub-branches abort completion with a clear list to resolve.
+
+If a research or crossref artifact deserves to outlive the branch, the user runs `/promote` on it before `/complete-work`. `/promote` accepts arbitrary paths and routes them into `workspace-context/`.
+
+## Tracker integration
+
+Goals do not replace work items. A goal is execution shape; a work item is the unit the team tracks. See `work-item-tracking.md` for how `workItem:` in session frontmatter links a session to its tracker issue. A goal lives inside a session and therefore inherits the session's `workItem:`.
+
+When the goal artifact is itself the deliverable for a future session to execute (i.e., this session's job was to *write* the goal, and another session will *run* it), the strip rule needs an escape hatch. The pattern: preserve the artifact in the tracker issue body (as a fenced code block) before `/complete-work` runs. The future session picks up the issue via `/start-work`, copies the artifact text into its worktree top, and runs `/goal`. The strip rule stays clean and consistent; the deliverable is preserved through the tracker.
+
+## Out of scope
+
+- Nested or sub-goals. v1 is flat.
+- DAG between phases. Sequential at the phase level; parallelism only inside a phase via the team agents.
+- Persistent named teams (`TeamCreate`). v1 is stateless dispatch.
+- Frontmatter linter for `goal-*.md`. Manual review is fine for v1; revisit if workspaces using the template hit consistent shape errors.
+- `/start-work` seeding of a `goal-{slug}.md` skeleton. Manual drafting is the v1 path. The drafting itself is high-leverage thinking; a template skeleton would risk skipping that.
+
+## 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. (The appendix is fenced with four backticks so the example's own `## Start command` code block renders intact.)
+
+````yaml
+---
+type: goal
+topic: evaluate-rate-limiting
+status: pending
+current_phase: strategy-research
+completion_condition: >
+  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.
+turn_budget: 60
+phases:
+  - name: strategy-research
+    type: parallel-research
+    status: pending
+    artifact: research-rate-limiting-strategies.md
+    gate: review
+    integration:
+      strategy: direct                   # artifact-only phase; commits straight to session branch
+    team:
+      agents:
+        - subagent_type: researcher
+          model: sonnet
+          brief: |
+            Research the token-bucket rate-limiting algorithm. Cover the
+            mechanics, parameter trade-offs (capacity, refill rate), edge
+            cases (burst behavior, clock skew), reference implementations in
+            popular libraries, and known production failure modes.
+
+            Output: a markdown report under 1,200 words. Return the content
+            in your response.
+        - subagent_type: researcher
+          model: sonnet
+          brief: |
+            Research the sliding-window rate-limiting algorithm. Cover both
+            the sliding log and sliding counter variants, accuracy
+            trade-offs, memory cost at scale, reference implementations, and
+            known production failure modes.
+
+            Output: a markdown report under 1,200 words. Return the content
+            in your response.
+        - subagent_type: researcher
+          model: sonnet
+          brief: |
+            Research the leaky-bucket rate-limiting algorithm. Cover the
+            queue-based and meter-based variants, smoothing behavior under
+            burst, comparison to token bucket, reference implementations,
+            and known production failure modes.
+
+            Output: a markdown report under 1,200 words. Return the content
+            in your response.
+      synthesizer:
+        subagent_type: researcher
+        model: sonnet
+        brief: |
+          Synthesize the three algorithm reports into a single
+          recommendation document at research-rate-limiting-strategies.md
+          (top of the active worktree).
+
+          Frontmatter: type: research, topic: rate-limiting-strategies,
+          state: ephemeral, lifecycle: active, confidence: medium,
+          updated: <today's date>.
+
+          Document structure:
+          - One-line recommendation up front
+          - Comparison table across criteria (accuracy, memory cost, burst
+            behavior, implementation complexity, operational debuggability)
+          - Per-algorithm summary with strengths and weaknesses
+          - Risks and unknowns
+          - References
+
+          Maximum 2,000 words.
+
+  - name: crossref-existing-infrastructure
+    type: crossref
+    status: pending
+    artifact: crossref-existing-infrastructure.md
+    inputs:
+      independent: research-rate-limiting-strategies.md
+      against:
+        - workspace-context/canonical.md
+        - repos/api-gateway/
+    gate: review
+    integration:
+      strategy: direct
+    agent:
+      subagent_type: researcher
+      model: sonnet
+    brief: |
+      Compare the rate-limiting strategy recommendation against the
+      existing infrastructure (the repos/api-gateway/ codebase and any
+      relevant canonical workspace context).
+
+      Produce a gap-and-overlap matrix: where does the recommended
+      strategy align with current patterns, where does it diverge, and
+      what migration friction is implied. Rank concerns by severity.
+
+  - name: spec
+    type: skill
+    status: pending
+    skill: superpowers:brainstorming
+    artifact: design-rate-limiting.md
+    gate: review
+    integration:
+      strategy: direct                   # spec lands as design-*.md at worktree top; stripped before final PR
+
+  - name: plan
+    type: skill
+    status: pending
+    skill: superpowers:writing-plans
+    artifact: plan-rate-limiting.md
+    gate: review
+    integration:
+      strategy: direct
+
+  - name: implement
+    type: skill
+    status: pending
+    skill: superpowers:executing-plans
+    artifact: null
+    gate: review
+    integration:
+      strategy: sub-branch               # code phase: sub-branch + self-merged PR
+      branch: feature/{session-name}-implement
+      self_merge: true
+---
+
+# Goal: Evaluate and ship a rate-limiting strategy
+
+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
+   candidate algorithm, plus a synthesizer that writes the comparative
+   recommendation.
+
+2. **crossref-existing-infrastructure** validates the recommendation
+   against the current api-gateway codebase and canonical workspace
+   context, surfacing migration friction and divergences.
+
+3. **spec** wraps `superpowers:brainstorming` to produce the design doc
+   from the validated recommendation.
+
+4. **plan** wraps `superpowers:writing-plans` to produce the
+   implementation checklist.
+
+5. **implement** wraps `superpowers:executing-plans` on a per-phase
+   sub-branch (`feature/{session-name}-implement`). The main agent opens
+   a PR from the sub-branch back into the session/integration branch and
+   self-merges once the gate is satisfied. Sub-branch is deleted post-merge.
+
+Each gate is `review`: the user approves, rejects with feedback, or
+pauses at the end of every phase. No auto-advance in v1.
+
+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/rules/task-list-mirroring.md

@@ -61,6 +61,7 @@ Trivial edits (renaming, reordering) do **not** trigger a flush — they ride on
 - Do not edit the `## Tasks` section by hand or with `Edit` — always go through the helper. Manual edits will be overwritten and may miss the bookend invariant.
 - Do not add nested checkboxes — `TodoWrite` is flat, and the round-trip ignores nesting.
 - Do not omit the bookends — the helper auto-inserts them, but explicit is better than implicit.
+- Do not append new tasks after the `Complete work` bookend in `TodoWrite`. Always insert them between `Start work` and `Complete work`. The disk helper silently corrects misplacement on the next flush, but the live `TodoWrite` UI shows tasks in the order they were written — appending leaves `Complete work` stranded mid-list until something triggers a flush.
 - Do not flush every keystroke — that creates pointless file churn. Flush on meaningful change or lifecycle moment.
 - Do not flush from inside a subagent — subagents have ephemeral context; only the main agent maintains the canonical `TodoWrite` state for the session.
 

package/template/.claude/rules/workspace-structure.md

@@ -12,6 +12,9 @@ This workspace follows the claude-workspace convention. All paths are relative t
 | `work-sessions/{name}/workspace/session.md` | Unified session tracker at the top of the session branch (frontmatter = machine state, body = human content) | Yes — on the session branch |
 | `work-sessions/{name}/workspace/design-*.md` | Specs for this session — consumed into release notes by /complete-work | Yes — on the session branch |
 | `work-sessions/{name}/workspace/plan-*.md` | Plans for this session — consumed into release notes by /complete-work | Yes — on the session branch |
+| `work-sessions/{name}/workspace/goal-*.md` | Goal artifacts for /goal-driven multi-phase work — consumed into release notes by /complete-work | Yes — on the session branch |
+| `work-sessions/{name}/workspace/research-*.md` | Phase-output research artifacts produced by goal-driven sessions — consumed into release notes by /complete-work | Yes — on the session branch |
+| `work-sessions/{name}/workspace/crossref-*.md` | Phase-output crossref artifacts produced by goal-driven sessions — consumed into release notes by /complete-work | Yes — on the session branch |
 | `work-sessions/{name}/workspace/repos/` | Real directory holding nested project worktrees for this session | No (gitignored) |
 | `work-sessions/{name}/workspace/repos/{repo}/` | Project worktree nested inside the workspace worktree | No (gitignored) |
 | `workspace-context/` | Team knowledge and per-user context | Yes |
@@ -46,18 +49,19 @@ Inflight session state lives inside the session worktree at `work-sessions/{name
 
 ## Spec and Plan Locations — MANDATORY OVERRIDE
 
-**Specs and plans MUST be written at the top of the active session's workspace worktree, not to `docs/superpowers/` or any other location.**
+**Specs, plans, and goal artifacts MUST be written at the top of the active session's workspace worktree, not to `docs/superpowers/` or any other location.**
 
 - Specs: `design-{topic}.md` at the top of `work-sessions/{session-name}/workspace/`
 - Plans: `plan-{topic}.md` at the top of `work-sessions/{session-name}/workspace/`
+- Goals: `goal-{topic}.md` at the top of `work-sessions/{session-name}/workspace/`, with goal-native phase outputs as `research-{topic}.md` and `crossref-{topic}.md` siblings. See `goal-driven-work.md` for the schema and when to reach for `/goal`.
 
-From inside the worktree, these are plain top-level files (`design-{topic}.md`, `plan-{topic}.md`) sitting alongside `CLAUDE.md` and `workspace.json`. They are tracked on the session branch and travel with the branch on `git push`.
+From inside the worktree, these are plain top-level files (`design-{topic}.md`, `plan-{topic}.md`, `goal-{topic}.md`) sitting alongside `CLAUDE.md` and `workspace.json`. They are tracked on the session branch and travel with the branch on `git push`.
 
-This overrides any default paths specified by external skills (e.g., Superpowers brainstorming defaults to `docs/superpowers/specs/`). Those skills state that user preferences override their defaults — this rule IS that override. Do not create `docs/superpowers/` directories. Do not write specs or plans anywhere other than the top of the active worktree.
+This overrides any default paths specified by external skills (e.g., Superpowers brainstorming defaults to `docs/superpowers/specs/`). Those skills state that user preferences override their defaults — this rule IS that override. Do not create `docs/superpowers/` directories. Do not write specs, plans, or goal artifacts anywhere other than the top of the active worktree.
 
-If a spec/plan already exists for the current session, version it: `design-{topic}-v2.md`, `design-{topic}-v3.md`.
+If a spec/plan/goal already exists for the current session, version it: `design-{topic}-v2.md`, `design-{topic}-v3.md`.
 
-`/complete-work` reads specs and plans from the worktree to synthesize release notes, then removes them in a dedicated commit before the final PR so main's tree stays pristine.
+`/complete-work` reads specs, plans, and goal artifacts (including `research-*.md` and `crossref-*.md` phase outputs) from the worktree to synthesize release notes, then removes them in a dedicated commit before the final PR so main's tree stays pristine.
 
 ## File Naming Conventions
 
@@ -67,6 +71,9 @@ If a spec/plan already exists for the current session, version it: `design-{topi
 - Session trackers: `work-sessions/{session-name}/workspace/session.md`
 - Specs: `design-{topic}.md` (top of worktree)
 - Plans: `plan-{topic}.md` (top of worktree)
+- Goals: `goal-{topic}.md` (top of worktree)
+- Goal-native research outputs: `research-{topic}.md` (top of worktree)
+- Goal-native crossref outputs: `crossref-{topic}.md` (top of worktree)
 
 For ephemeral content under `shared/` and `team-member/{user}/`, the filename prefix signals the type:
 

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
 
@@ -55,9 +56,12 @@ Formally read ALL sources before synthesizing — do not write release notes fro
 
 1. **Session tracker** at `work-sessions/{session-name}/workspace/session.md` — read the full body (frontmatter is machine state, body is human content)
 
-2. **Session-scoped specs/plans** at the top of the session worktree:
+2. **Session-scoped specs/plans/goal artifacts** at the top of the session worktree:
    - `work-sessions/{session-name}/workspace/design-*.md` files
    - `work-sessions/{session-name}/workspace/plan-*.md` files
+   - `work-sessions/{session-name}/workspace/goal-*.md` files
+   - `work-sessions/{session-name}/workspace/research-*.md` files
+   - `work-sessions/{session-name}/workspace/crossref-*.md` files
    - Read each one fully
 
 3. **Handoffs** — any workspace-context entries referencing this branch:
@@ -83,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}
@@ -102,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}
@@ -121,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}"
 ```
 
@@ -129,19 +133,34 @@ If a repo has no commits beyond the base, skip release notes for it.
 
 ### Step 7: Remove session artifacts from the workspace branch
 
-The entire `work-sessions/{session-name}/` folder is removed by the cleanup script in Step 12. Before that happens, make sure everything worth preserving has landed in release notes (Step 6) — once Step 6 has run, the tracker, specs, and plans have served their purpose.
+The entire `work-sessions/{session-name}/` folder is removed by the cleanup script in Step 12. Before that happens, make sure everything worth preserving has landed in release notes (Step 6) — once Step 6 has run, the tracker, specs, plans, and goal artifacts have served their purpose.
 
-Session content lives at the top of the workspace worktree on the session branch. Remove these files from the branch before the final push so main's top level stays free of session artifacts:
+**Goal sub-branch pre-flight (only when a `goal-*.md` artifact is present).** A `/goal`-driven session can produce per-phase sub-branches for code phases (any phase declaring `integration.strategy: sub-branch` in the goal artifact). Those sub-branches must be merged into the session branch before completion, or their work is lost when the session folder is torn down. Before stripping anything, check each repo in the session — the workspace worktree itself and every `repos/{repo}/` project worktree:
+
+```bash
+cd work-sessions/{session-name}/workspace/repos/{repo}   # repeat for the workspace worktree too
+session_branch=$(git rev-parse --abbrev-ref HEAD)
+for sub in $(git branch --format='%(refname:short)' --list "${session_branch}-*"); do
+  git merge-base --is-ancestor "$sub" "$session_branch" || echo "UNMERGED: $sub"
+done
+```
+
+If any `UNMERGED:` lines print, abort completion and show the list. The user merges the intended sub-branches into the session branch, or closes abandoned ones, then re-runs `/complete-work`. When no `goal-*.md` artifact is present, this check is a no-op and completion proceeds normally.
+
+Session content lives at the top of the workspace worktree on the session branch. Once the pre-flight passes, remove these files from the branch before the final push so main's top level stays free of session artifacts:
 
 ```bash
 cd work-sessions/{session-name}/workspace
 git rm -f session.md 2>/dev/null || true
 git rm -f design-*.md 2>/dev/null || true
 git rm -f plan-*.md 2>/dev/null || true
+git rm -f goal-*.md 2>/dev/null || true
+git rm -f research-*.md 2>/dev/null || true
+git rm -f crossref-*.md 2>/dev/null || true
 git commit -m "chore: remove session artifacts before PR" 2>/dev/null || true
 ```
 
-The `|| true` guards keep this idempotent — if a file is already gone (e.g., a session without specs), the step is a no-op. The commit is skipped when there's nothing staged.
+The `|| true` guards keep this idempotent — if a file is already gone (e.g., a session without specs or goals), the step is a no-op. The commit is skipped when there's nothing staged.
 
 This commit persists in the branch's history. On squash merge or rebase merge, branch history collapses to one clean commit on main with no session artifacts. On merge commits, branch history is reachable but the final tree on main shows no session content.
 
@@ -441,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.