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

package/template/.claude/rules/forge-operations.md

@@ -1,107 +1,51 @@
-Activate this rule if the workspace creates PRs, watches CI runs, or interacts with releases from skills. Sibling to `work-item-tracking.md` (which covers issues); together they cover everything a workspace needs to do against a code-hosting forge.
+Activate this rule if the workspace creates PRs, watches CI runs, or interacts with releases from skills. Sibling to `work-item-tracking.md` (which covers issues); together they cover everything a workspace does against a code-hosting forge.
 
 # Forge Operations
 
-When a workspace has a forge configured, all pull-request, release, and workflow-run operations from skills and scripts go through the adapter at `.claude/scripts/forges/{type}.mjs`. Skills never call `gh` (or `glab`, or any forge CLI) inline.
+**Skills never call `gh` (or `glab`, or any forge CLI) inline for pull-request, release, or
+workflow-run operations.** They go through the adapter at `.claude/scripts/forges/{type}.mjs`,
+reached via `createForge()` from `.claude/scripts/forges/interface.mjs`.
 
-## Why the abstraction
+The interface module is the source of truth for the available methods and their shapes —
+read it when you need the API. `/complete-work` and `/pause-work` each carry the exact calls
+they make, so in practice you rarely need to look.
 
-- **Swap by config.** Moving from GitHub to GitLab is a `workspace.json` field change plus an adapter file — not a sweep across six skill files.
-- **Testable.** The adapter takes an injectable `spawnFn`; unit tests mock subprocess calls instead of running them.
-- **One vocabulary.** Skills reason about `forge.prCreate`, `forge.prMerge`, `forge.workflowRunFind`, `forge.workflowRunWatch`, `forge.releaseView` regardless of backend. Failure modes share typed errors (`PrNotFound`, `MergeRejected`, `WorkflowNotFound`, `ReleaseNotFound`) instead of every callsite parsing stderr.
+## Why
 
-## Configuration
-
-`workspace.json` → `workspace.forge`:
-
-```json
-{
-  "workspace": {
-    "forge": {
-      "type": "github"
-    }
-  }
-}
-```
-
-- `type` — identifies the adapter module at `.claude/scripts/forges/{type}.mjs`. `github` is the default and the only fully-implemented adapter today. `gitlab.mjs` ships as a stub that throws `NOT_IMPLEMENTED` with a contribution pointer.
-- `repo` (optional) — adapter-specific. For `github`, the `owner/name` slug to target. When unset or `"auto"`, the adapter resolves the repo from the local git `origin` remote.
-
-Absence of `workspace.forge` is treated as `{ type: 'github' }` (back-compat for workspaces that predate the field). Setting `workspace.forge: false` explicitly disables forge operations — every adapter method then throws `FORGE_DISABLED`.
-
-## Adapter interface (for Claude)
-
-Import from `.claude/scripts/forges/interface.mjs`:
-
-```javascript
-import { createForge, PrNotFound, MergeRejected, WorkflowNotFound, ReleaseNotFound } from '.claude/scripts/forges/interface.mjs';
-import { readFileSync } from 'node:fs';
-
-const ws = JSON.parse(readFileSync('workspace.json', 'utf-8'));
-const forge = createForge(ws.workspace?.forge);
-
-// Pull request lifecycle
-const pr = await forge.prCreate({
-  title: 'feat: add forge adapter',
-  body: 'long-form body',
-  draft: false,                // omit or false for normal PRs; true for /pause-work drafts
-  base: 'main',                // optional; defaults to repo default branch
-  head: 'feature/forge',       // optional; defaults to current branch
-});                            // → { id: 'owner/repo#42', url, number }
+Switching code hosts becomes a `workspace.json` field plus one adapter file instead of a
+sweep across six skills. Failure modes share typed errors — `PrNotFound`, `MergeRejected`,
+`WorkflowNotFound`, `ReleaseNotFound` — instead of every callsite parsing stderr. And the
+adapter takes an injectable `spawnFn`, so tests mock subprocesses rather than running them.
 
-await forge.prMerge({
-  id: pr.id,
-  strategy: 'squash',          // 'merge' | 'squash' | 'rebase'
-  deleteBranch: true,
-});
-
-const view = await forge.prView({ id: pr.id });
-// → { state, mergeable, mergeStateStatus, reviewDecision, ... }
-
-// Releases (lookup only — release creation lives in the workflow tag-push)
-const release = await forge.releaseView({ tag: 'v1.2.3' });
-// → { tag, name, url, publishedAt, isDraft, isPrerelease }
-// throws ReleaseNotFound if the tag has no release
-
-// Workflow runs (used by /complete-work to follow the publish workflow)
-const run = await forge.workflowRunFind({
-  workflow: 'publish.yml',
-  branch: 'v1.2.3',
-  limit: 1,
-});                            // → { runId, status, conclusion, url } | null
-const result = await forge.workflowRunWatch({
-  runId: run.runId,
-  exitStatus: true,            // true: exit non-zero on workflow failure
-});                            // → { exitCode } — does NOT throw on workflow failure
-```
-
-All methods are async. Adapter-detectable failures throw typed errors; raw spawn failures throw `Error`.
-
-## Skill behavior
-
-Skills that interact with forge operations:
-
-- **`/pause-work`** — creates draft PRs via `forge.prCreate({ draft: true })`.
-- **`/complete-work`** — creates PRs, merges them with `strategy: 'squash'`, and (release sessions only) finds + watches the publish workflow via `workflowRunFind` + `workflowRunWatch`. Uses `releaseView` to investigate existing tag conflicts before re-tagging.
-
-Skills outside that list do not call the forge adapter; they either don't touch the forge or they touch it for tracker-setup-specific operations that are deliberately scoped out (see below).
+## Configuration
 
-## What this rule does NOT cover
+`workspace.json` → `workspace.forge`: `{ "type": "github" }`. `type` names the adapter module;
+`github` is the default and the only complete one, `gitlab.mjs` is a stub that throws
+`NOT_IMPLEMENTED`. Optional `repo` is an `owner/name` slug; unset or `"auto"` resolves from the
+git `origin` remote. An absent `workspace.forge` is treated as `{ type: 'github' }`; setting it
+to `false` makes every adapter method throw `FORGE_DISABLED`.
 
-- **Issue lifecycle.** Issues, comments, labels, milestones live in `work-item-tracking.md` via the tracker adapter at `.claude/scripts/trackers/{type}.mjs`. The two abstractions are intentionally separate.
-- **Tracker-setup repo configuration.** `/setup-tracker` uses `gh repo view --json hasIssuesEnabled` and `gh api repos/{slug} -X PATCH -f has_issues=true` to inspect and enable the Issues feature on a GitHub repo. Those are GitHub-API-specific setup operations, not the cross-cutting PR/release ops the forge abstraction targets. A GitLab user running `/setup-tracker` would follow a different setup flow entirely, so wrapping these in the forge adapter would create a leaky abstraction. They remain direct `gh` calls.
-- **`gh repo view` as a remote-type probe.** `/complete-work` uses `gh repo view` to detect whether a remote is a GitHub remote (separately from any PR operation that follows). This is a one-line capability check, not an operation that benefits from forge wrapping. It stays direct.
-- **Repo creation.** `gh repo create` (in `/sync-work` and `/workspace-init` setup narratives) is an interactive one-off used when a workspace lacks a remote. No forge adapter method for it — pointing users at a wrapped form when none exists would be worse than the current direct mention.
-- **Manual operator recovery.** `gh run rerun`, `gh run view`, `gh release view` referenced in `/release` recovery guidance are documented for an operator at a terminal investigating a failed publish. The forge adapter is for *skill code*, not the manual recovery prose.
+## Deliberate exceptions — do not "fix" these
 
-## Migration
+These stay as direct `gh` calls. Wrapping them would create a leaky abstraction, so leave them
+alone:
 
-Existing workspaces predate `workspace.forge`. They continue to work because `createForge(undefined)` defaults to `{ type: 'github' }`. The `/maintenance` audit surfaces a notice when `workspace.tracker.type === 'github-issues'` and `workspace.forge` is unset, suggesting the explicit value — a one-line `workspace.json` addition with no behavior change.
+- **Issue lifecycle** — issues, comments, labels and milestones belong to the tracker adapter.
+  See `work-item-tracking.md`. The two abstractions are intentionally separate.
+- **`/setup-tracker` repo configuration** — `gh repo view --json hasIssuesEnabled` and
+  `gh api repos/{slug} -X PATCH -f has_issues=true` are GitHub-API-specific setup, not
+  cross-cutting operations. A GitLab user's setup flow differs entirely.
+- **`gh repo view` as a remote-type probe** — a one-line capability check, not an operation.
+- **`gh repo create`** — an interactive one-off when a workspace has no remote.
+- **Manual recovery prose** — `gh run rerun`, `gh run view`, `gh release view` in `/release`
+  guidance are for an operator at a terminal, not for skill code.
 
-A workspace switching to GitLab implements `.claude/scripts/forges/gitlab.mjs` against the interface (the stub file documents the shape) and sets `workspace.forge.type: 'gitlab'`. No skill rewrite is required; the abstraction does the routing.
+## Boundaries
 
-## What this rule does NOT do
+The adapter covers the operations the template's skills actually perform, not every `gh`
+capability. New operations land as additive interface methods, never by a skill going around
+the adapter. Forge-native features — PR comments, review webhooks, branch protection — remain
+UI and direct-CLI territory.
 
-- Does not prescribe a specific forge type. Adapter choice is per workspace.
-- Does not replace forge-native features (PR comments, review-requested webhooks, branch protection settings) — those remain UI / direct-CLI territory.
-- Does not promise that every `gh` capability is wrapped. The adapter covers the operations the template's skills actually perform. New operations land via additive interface methods, not by skills going around the adapter.
+Workspaces predating `workspace.forge` keep working, since `createForge(undefined)` defaults to
+GitHub. `/maintenance` surfaces a notice suggesting the explicit value.

package/template/.claude/rules/git-conventions.md

@@ -10,17 +10,22 @@
 
 ## Worktrees
 
-- Work sessions get N+1 worktrees: one for the workspace, plus one per project repo
-- Each session lives in a self-contained folder at `work-sessions/{session-name}/`
-- The workspace worktree is at `work-sessions/{session-name}/workspace/`
-- Project worktrees are nested inside the workspace worktree at `work-sessions/{session-name}/workspace/repos/{repo-name}/`
-- Example: for a session `fix-auth` on branch `bugfix/fix-auth` touching repos `my-app` and `my-api`:
-  - `work-sessions/fix-auth/workspace/` — workspace worktree
-  - `work-sessions/fix-auth/workspace/repos/my-app/` — project worktree
-  - `work-sessions/fix-auth/workspace/repos/my-api/` — project worktree
-- The workspace repo's `.gitignore` pattern `repos` (no trailing slash) covers both the workspace root's `repos/` and the nested `repos/` inside every worktree
-- Source clones at `repos/{repo-name}/` (at the workspace root) stay on their default branch at all times
-- Remove worktrees when the work session is completed — use the cleanup helper to enforce the mandatory teardown order (project worktrees first, then workspace worktree, then prune)
+Both lifecycles are built on worktrees; `workspace.sessionModel` in `workspace.json` routes new work to one of them.
+
+**Task model** (`"task"`): one worktree per repo the task touches, created and removed with `.claude/scripts/task-worktree.mjs` (the chat stays at the workspace root):
+
+- Project repos: `repos/{repo}/.claude/worktrees/{slug}/`, where `{slug}` is the branch with `/` replaced by `-`
+- The workspace repo itself, addressed as `.`: `.claude/worktrees/{slug}/` — Claude Code's native worktree location
+- Source clones at `repos/{repo}/` stay on their default branch; `/complete-work` tears each worktree down with `task-worktree.mjs --remove` (worktree first, then the branch)
+
+**Session model** (default): N+1 worktrees in one self-contained folder at `work-sessions/{session-name}/`:
+
+- `work-sessions/{session-name}/workspace/` — workspace worktree
+- `work-sessions/{session-name}/workspace/repos/{repo-name}/` — project worktrees nested inside it (no symlink)
+- Example, session `fix-auth` on `bugfix/fix-auth` touching `my-app` and `my-api`: `work-sessions/fix-auth/workspace/` plus `workspace/repos/my-app/` and `workspace/repos/my-api/`
+- Teardown order is mandatory: project worktrees first, then the workspace worktree, then prune — the cleanup helper enforces it
+
+The workspace `.gitignore` covers all of it: `repos` (no trailing slash) matches the root's `repos/` and every session worktree's nested `repos/`; `.claude/worktrees/` matches task worktrees of the workspace repo itself.
 
 ## Branch Maintenance
 

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

@@ -12,421 +12,13 @@ Use `/goal` when the work meets all three:
 
 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
+## The convention lives in a skill
 
-- 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.
+Everything past this decision — the `goal-{topic}.md` frontmatter schema, the three phase
+types, agent-team dispatch, gate conventions, the integration-branch model with per-phase
+sub-PRs, model tiering, and the worked example — is in the `goal-driven-work` skill.
 
-## 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 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.
-````
+Invoke it before drafting a goal artifact or running a goal phase. It is a skill rather than
+a rule because it is a procedure needed by the small number of sessions that run `/goal`,
+not a constraint every session must carry. Loading it on demand keeps roughly 27 KB out of
+every session's always-loaded context.