@ulysses-ai/create-workspace 0.17.0-beta.0 → 0.18.0-beta.0

package/template/.claude/skills/context-placement/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: context-placement
+description: Use when deciding where a durable fact, instruction, or procedure belongs — a rule, canonical context, shared or personal context, auto-memory, or a skill — and when writing it once the destination is settled. Routes the decision, states the always-loaded cost before anything is written, and carries the frontmatter schema, generator invocations, and the canonical admission test.
+---
+
+# Context Placement
+
+Something is worth keeping. This skill decides where it goes, and makes the cost of that
+choice visible before you write it.
+
+The hard part is routing, not prose. Most placement mistakes are not badly written files —
+they are correctly written files in a destination that charges every future session for
+them. Two of this workspace's own bugs (gh:136, gh:138) were exactly that: rules that had
+quietly absorbed reference material and worked examples until the always-loaded directory
+cost more than the conversation.
+
+## The destinations
+
+Exactly one of these. The right-hand column is what every session pays, forever, for the
+choice.
+
+| destination | route here when | always-loaded cost |
+|---|---|---|
+| **nowhere** | it is already covered somewhere, or it is true only today | zero |
+| `.claude/rules/{name}.md` with `paths:` | an instruction that applies only when specific files are touched | zero until a matching file is read |
+| `.claude/skills/{name}/SKILL.md` | a procedure with steps, invoked on demand | the `description` line, ~200 B |
+| auto-memory | a machine-local preference or correction; not shared, not reviewable | one `MEMORY.md` line, ~100 B |
+| `workspace-context/team-member/{user}/` | one person's working context | one index line, ~120 B, that user only |
+| `workspace-context/shared/` | team-visible reference to look up when relevant | one index line, ~120 B |
+| `workspace-context/shared/locked/` | a team-wide fact or constraint that passes the canonical test | **the whole file, every session** |
+| `.claude/rules/{name}.md` (no `paths:`) | an instruction that must shape every session, everywhere in the repo | **the whole file, every session** |
+
+The table is ordered by cost, cheapest first. Work down it and stop at the first
+destination that genuinely fits. The two bold rows are the only ones that tax every
+session; reach them only after the cheaper ones have actually been ruled out, not skipped.
+
+**`nowhere` is the most common correct answer.** Before anything else, check whether the
+thing is already stated. A second copy in a second location is worse than no copy: they
+drift, and the reader cannot tell which one is current.
+
+## Step 1 — classify what you have
+
+Three kinds. The kind determines which destinations are even eligible.
+
+- **Instruction** — changes what Claude *does*. "Never force push." "Rebase before opening
+  a PR." Imperative, applies without being asked for. Eligible: rules (scoped or not).
+- **Reference** — something Claude needs to *know* when a particular topic comes up. API
+  shapes, schemas, architecture facts, why an approach was rejected. Eligible: canonical,
+  shared, team-member, auto-memory.
+- **Procedure** — a sequence of steps with a beginning and an end, run on request.
+  Eligible: a skill.
+
+Most drift comes from putting reference or procedure content in a rule. A rule that
+contains an API table or a worked example is carrying reference material at instruction
+prices. Split it: the instruction stays in the rule, the detail moves to a skill or a
+context file, and the rule points at it in one line.
+
+## Step 2 — scope it
+
+For an instruction, the only question that matters is *when must this be true?*
+
+- Every session, every file → unconditional rule.
+- Only when certain files are involved → rule with `paths:`.
+
+`paths:` is a real Claude Code feature and is almost always the better answer for anything
+domain-specific. A rule about migration scripts, or about a single repo's test conventions,
+does not need to be in context while you are editing documentation.
+
+```yaml
+---
+paths:
+  - ".claude/scripts/**/*.mjs"
+  - "repos/*/template/.claude/scripts/**/*.mjs"
+---
+```
+
+Rules with `paths:` load only when Claude reads a matching file. Rules without it load at
+launch, at the same priority as `CLAUDE.md`, in every session — and, for anything shipped
+in the template, in every downstream workspace too.
+
+For reference content, scope is about reach. Pick the narrowest that works: auto-memory
+(this machine only) → `team-member/{user}/` (one person) → `shared/` (the team) →
+`shared/locked/` (the team, always loaded).
+
+## Step 3 — state the cost, then write
+
+Before writing, run the footprint tool and report the projection to the user in one line.
+This step is not optional. Making the cost visible at the decision point is the whole
+reason this skill exists.
+
+```bash
+node .claude/scripts/context-footprint.mjs --root .
+node .claude/scripts/context-footprint.mjs --root . --add <bytes> --as <destination>
+```
+
+Valid `--as` values: `rule`, `rule-scoped`, `locked`, `shared`, `team-member`, `memory`,
+`skill`, `nowhere`.
+
+Say it plainly — "this adds 1.4 KB to every session, taking always-loaded context from
+7.8% to 8.0% of the window" — and then write the file. If the projection looks
+disproportionate to the value, go back to the table and take a cheaper row.
+
+## The canonical test
+
+Canonical content is loaded verbatim into every session prompt, so it frames how Claude
+reads the rest of the conversation. The principle: canonical describes what *is* and what
+*to do*, never what *to think*.
+
+> If Claude read this for the first time during a session about an unrelated topic, would
+> it (a) help frame the problem correctly, or (b) push Claude toward a particular answer to
+> a question that hasn't been asked yet?
+
+(a) is canonical. (b) is `shared/` at most, more often `team-member/{user}/`.
+
+**Belongs in `shared/locked/`:**
+
+- **Facts about the system** — architecture, supported targets, naming conventions, where
+  things live, what is published.
+- **Hard constraints** — "must work on Windows and macOS," "PRs only, no direct push to
+  main." Constraints scope the solution space without prejudging the solution.
+- **Process rules** — workflow discipline that applies regardless of task.
+- **Settled-rejection guardrails** — "we evaluated X, rejected it because Y, do not propose
+  it again." Must include the *why*, so a genuine edge case can still be recognised.
+- **Meta-principles for debiasing** — explicit reminders to widen evaluation.
+
+**Does not:**
+
+- **Opinions on open technical questions.** "Library X beats Y here" makes Claude start
+  from the conclusion instead of reasoning toward it. Write it as a constraint with its
+  reason, or leave it in `shared/`.
+- **Conclusions Claude might be asked to question.** Locking a conclusion on a topic still
+  under design biases the discussion before it starts.
+- **Personal preferences.** Those are `team-member/{user}/`.
+- **Status snapshots that age fast.** `project-status.md` is the bounded exception; finer
+  detail lives in the tracker.
+
+Pre-loaded conclusions do not read as opinions to Claude — they read as ground truth. A
+reference doc Claude *finds* while researching is weighed against the question; a canonical
+doc loaded before the question is asked frames what Claude considers at all.
+
+## Writing a workspace-context file
+
+Frontmatter fields — conventions, not all required on every file:
+
+- `state` — `locked` (team truth, lives under `shared/locked/`) or `ephemeral`.
+- `lifecycle` — for ephemeral files: `active` or `resolved`.
+- `type` — `reference`, `braindump`, `handoff`, `research`, `design`, `index`, `canonical`,
+  `promoted`.
+- `priority` — locked files only: `critical` (always in canonical) or `reference` (eligible
+  for trim or stub under budget pressure). Absent defaults to `critical`.
+- `topic` — kebab-case slug matching the filename after any type prefix.
+- `author` — required for `team-member/{user}/` files.
+- `updated` — ISO date of last meaningful edit. `/maintenance` flags stale `active` files.
+- `description` — one line, used verbatim by the generated indexes. Without it the index
+  falls back to the first sentence, then the filename slug. Adding one to a file with a
+  weak fallback is the cheapest possible index improvement.
+- `confidence` — `high` | `medium` | `low`. Use on research, design, and exploration where
+  conclusions may still shift. Skip on locked files and on handoffs and braindumps.
+
+```yaml
+---
+state: ephemeral
+lifecycle: active
+type: research
+topic: vector-search-evaluation
+description: Evaluation of FAISS for workspace-context — concluded the NL index is sufficient at our scale.
+author: alex
+confidence: medium
+updated: 2026-04-25
+---
+```
+
+## Regenerating the indexes
+
+One generator produces all three artifacts in a single pass:
+
+- `workspace-context/index.md` — catalog of `shared/` (locked first), imported by `CLAUDE.md`.
+- `workspace-context/canonical.md` — verbatim concatenation of `shared/locked/*.md`, also
+  imported by `CLAUDE.md`.
+- `workspace-context/team-member/{user}/index.md` — per-user catalog, imported by each
+  user's gitignored `CLAUDE.local.md`.
+
+```bash
+node .claude/scripts/build-workspace-context.mjs --check --root .   # exits 1 if stale
+node .claude/scripts/build-workspace-context.mjs --write --root .   # regenerate
+```
+
+Gitignored files (anything matching `local-only-*`) are excluded automatically, and
+`workspace-context/.indexignore` adds path-prefix excludes for tracked files that should
+not appear in the shared index.
+
+When `canonical.md` exceeds `workspace.canonicalBudgetBytes` (default 40960), the builder
+honours per-file `priority` and section-level `<!-- canonical:trim --> ... <!-- canonical:end-trim -->`
+markers to fit: `priority: reference` files are trimmed, then stubbed; `priority: critical`
+files are always included in full. `/maintenance` audits the budget and offers triage when
+over.
+
+Hand edits to `index.md`, `canonical.md`, or any per-user index are overwritten. Change the
+source file or its `description:` instead.

package/template/.claude/skills/goal-driven-work/SKILL.md

@@ -0,0 +1,459 @@
+---
+name: goal-driven-work
+description: Use when setting up or running multi-phase autonomous work under Claude Code's built-in /goal command in a Ulysses workspace — drafting a goal-{topic}.md artifact, defining phases, dispatching phase agent teams, or completing a goal-driven session. Covers the frontmatter schema, the three phase types, gate conventions, the integration-branch model with per-phase sub-PRs, and model tiering.
+---
+
+# Goal-Driven Work
+
+The convention layer over Claude Code's built-in `/goal` command. `/goal` is the autonomy
+loop; this skill gives the main agent durable phase state and a consistent dispatch pattern
+across turns and resumes.
+
+Read `.claude/rules/goal-driven-work.md` first for whether `/goal` is the right shape for
+the work at hand. This skill covers everything after that decision.
+
+## File layout
+
+- One `goal-{topic}.md` artifact per effort. Session model: at the top of the session worktree, alongside `session.md`. Task model: in the chat drawer at `workspace-scratchpad/chats/{chat}/`, alongside its phase outputs. One goal per worktree or task either way.
+- 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.
+- Session model: the artifact is tracked on the session branch and lives there until `/complete-work` runs, which strips it before the final PR. Task model: the drawer is machine-local and untracked; `/complete-work` routes the artifact (promote into `workspace-context/` or discard) at completion.
+
+## 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.
+
+## Gate-budget interaction and turn-budget sizing
+
+A goal's `turn_budget` is a backstop that counts every orchestrator turn — including the short "awaiting your gate decision" exchanges that happen at every `gate: review` phase. The `/goal` evaluator re-pings the session whenever it tries to settle without the completion condition being met, and each ping consumes a turn. Concretely: a multi-phase gated goal whose author is away for stretches can spend a meaningful fraction of its budget *idling at gates* rather than advancing work. A run with six `gate: review` phases burned roughly half of a 150-turn budget on gate-idle pings before the actual work completed.
+
+This is a structural property of `/goal` + review gates, not a per-goal accident. Plan for it:
+
+- **Drop `gate: review` from early phases when the human is expected to be away for stretches.** Research, crossref, spec, and plan phases produce artifacts that the final session→main PR consumes anyway. The integration-branch model (`main` untouched until `/complete-work` opens the final PR for human review) already provides one strong human review point; piling per-phase gates on top of that, with no human watching, just burns budget. Set those phases to `gate: auto` when the run will be unattended.
+- **Keep `gate: review` for phases with irreversible side effects or for phases whose outcome reshapes subsequent phases.** A spec gate that lets the human reprioritize the ranked execution list before `executing-plans` walks it is worth its cost; a research-synthesis gate that just rubber-stamps a matrix the human will see again in the final PR is not.
+- **Size `turn_budget` for the worst case you actually expect.** If every phase is `gate: auto`: budget ≈ (estimated work-turns) × 1.2 (small headroom for retries). If any phases are `gate: review` and the human may be unavailable for hours: multiply the work-turn estimate by **2–3×** to absorb gate-idle pings, or raise the budget mid-goal by editing the goal artifact's `completion_condition` and `turn_budget` fields. The Stop-hook condition string is fixed from the original `/goal` invocation; raising `turn_budget` in the artifact keeps the auditable source-of-truth correct for resume but does not change the running evaluator's text — the user can re-run the (updated) `## Start command` to refresh it after `/goal clear`.
+- **If the goal stops on the backstop mid-work because of gate-idle waste, that is the system working as designed.** `claude --resume` plus re-running the `## Start command` continues from durable phase state; phase artifacts and per-phase `status: complete` markers survive. Do not treat backstop-stop as a failure of the goal.
+
+This guidance is workspace-side mitigation only. The underlying friction — the evaluator pinging during gate-idle — is `/goal` harness behavior, not workspace code. A cleaner fix (suspend the evaluator at review gates so it does not re-ping until a new user message arrives) is tracked separately and would obsolete the multiplier above when it lands.
+
+## Integration branch and per-phase sub-PRs
+
+While a `/goal`-driven effort is running, its work branch (`feature/{session-name}` for a session, the task's branch for a task) acts as the goal's integration branch. Main is untouched until `/complete-work` opens the final 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. The integration-branch and sub-branch guidance in this section applies to task branches unchanged.
+
+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.
+- **Reachable by the agent.** This is the one that gets written wrong. If any phase carries
+  `gate: review`, or the goal depends on a merge, a deploy, or anything else only the
+  operator can authorise, then a condition demanding those be *done* can never be satisfied
+  by the agent — and the evaluator will re-ping indefinitely against work that is correctly
+  waiting. Either the condition names the blocked state as terminal, or the goal cannot end
+  without the backstop.
+
+**The failure this prevents, observed.** A goal was started with
+
+> All 6 phases show status: complete. […] The seven PRs are merged or closed.
+
+while three of its phases were `gate: review` and the PRs depended on two prerequisite PRs
+merging to `main`. Everything the agent could do was done inside about forty turns; the
+remaining eighty were spent re-reporting the same three blockers, because the condition had
+no terminal state for "built, verified, awaiting authorisation."
+
+Write the disjunction in from the start:
+
+```
+Every phase shows status: complete, or status: awaiting-review with its artifact
+written. […] Either <external step> is done, or it is still pending and that is
+stated in the transcript. Or stop after <N> turns.
+```
+
+Editing the artifact afterwards does not rescue a running goal: the evaluator's text is
+fixed from the original `/goal` invocation. The corrected condition only takes effect after
+`/goal clear` and a re-run of the `## Start command`.
+
+A reasonable template:
+
+```
+Every phase in goal-<topic>.md shows status: complete, or status: awaiting-review with its artifact written. Phase artifacts exist at: <list paths>. Either the /complete-work skill has opened the final PR with the URL in the transcript, or the goal is blocked on a named operator step and that is stated. 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 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 started work. It does NOT replace `/start-work`. Session model: the session is created the normal way and the goal artifact is drafted at the worktree top (including its `## Start command` block). Task model: the task is started the normal way and the artifact is drafted into the chat drawer. Either way the user runs the `## Start command` block's `/goal "..."` to kick off the loop.
+- Session model: the goal artifact lives on the session branch and travels with `git push`, surviving across machines and `--resume`. Task model: the drawer is machine-local — push the task branch for the code, and `/promote` the artifact if it must travel.
+- Session model: `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`. Task model: TodoWrite is the live mirror and there is no durable `## Tasks` — the goal artifact's own `phases:` list is the durable state.
+- `/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 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.
+````