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

package/template/.claude/rules/config-review.md.skip

@@ -0,0 +1,29 @@
+# Config Review Cadence
+
+Opt-in reminder to review `.claude` component files on a regular schedule. Activate by removing the `.skip` extension (`mv config-review.md.skip config-review.md`). Add it back to deactivate.
+
+## When to review
+
+Review the files in `.claude/rules/`, `.claude/skills/*/SKILL.md`, `.claude/agents/*.md`, and `.claude/hooks/*.mjs` after each major model release and at least every 180 days. Claude Code evolves quickly — conventions that matched platform behavior six months ago may no longer be accurate, optimal, or even meaningful.
+
+The 180-day threshold is not arbitrary: it corresponds to roughly two major Claude model generations. Conventions written for an older model generation can silently mis-steer the newer one without anyone noticing, because the file still runs without error.
+
+## Connection to /maintenance
+
+The `/maintenance` skill's **Component age check** (step 7 in the Cleanup section) surfaces which files have drifted past 180 days by reading their frontmatter `updated:` field. Files without an `updated:` field are skipped — the check is incremental and only flags files that have opted in by carrying the field.
+
+When `/maintenance` reports stale components, the recommended action is to open each flagged file, read it against the current Claude Code documentation and platform behavior, update the content where needed, and bump `updated:` to today.
+
+## Why this ships as .skip
+
+Review cadence is org-specific. A solo maintainer doing active weekly development may want a shorter cadence; a team with a slower release cycle may need a longer one; some workspaces may defer review entirely to a dedicated maintenance session. Making this rule mandatory by default would encode one team's preference as a universal constraint — exactly the failure mode described in `product-bias-risk.md`.
+
+Activate the rule only if your team wants the reminder to appear in every session. If 180 days is wrong for your cadence, edit the threshold in the rule body after activating it.
+
+## Activating
+
+```
+mv .claude/rules/config-review.md.skip .claude/rules/config-review.md
+```
+
+Once active, this reminder loads into every session context. To deactivate, rename it back.

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

@@ -0,0 +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 does against a code-hosting forge.
+
+# Forge Operations
+
+**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`.
+
+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.
+
+## Why
+
+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.
+
+## Configuration
+
+`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`.
+
+## Deliberate exceptions — do not "fix" these
+
+These stay as direct `gh` calls. Wrapping them would create a leaky abstraction, so leave them
+alone:
+
+- **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.
+
+## Boundaries
+
+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.
+
+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,408 +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.
-
-## 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.

package/template/.claude/rules/honest-pushback.md

@@ -1,56 +1,56 @@
 # Honest Pushback
 
-Do not agree with the user just to be agreeable. Do not keep trying things that aren't working. Do not assume when you can verify. Challenge assumptions, flag concerns, and push back when something seems wrong, costly, or misguided — even if the user is enthusiastic about it.
+Do not agree to be agreeable. Do not keep trying things that aren't working. Do not assume
+when you can verify. Challenge assumptions and flag concerns even when the user is
+enthusiastic.
 
-## What This Means
+## What this means
 
-- If an approach has obvious downsides, say so before implementing
-- If a design decision contradicts an earlier one, flag the contradiction
+- If an approach has obvious downsides, say so before implementing.
+- If a decision contradicts an earlier one, name the contradiction.
 - If scope is creeping, name it: "This started as X but is becoming Y. Split?"
-- If you don't know something, say so — don't fabricate confidence
-- If the user's idea is good, a simple "that works" is enough — don't embellish with praise
-- If you made a mistake, own it plainly — don't bury it in hedging language
+- If you don't know, say so — don't fabricate confidence.
+- If the idea is good, "that works" is enough. No embellishment.
+- If you made a mistake, own it plainly. No hedging.
 
-## No Retry Loops
+## No retry loops
 
-When a fix attempt fails, do not immediately try a variation of the same approach. If you have tried a solution and it produced the same error or unexpected result twice, stop and:
+If a fix produced the same error or an unexpected result twice, stop. Do not try a variation
+of the same approach. Instead:
 
-1. **State what you expected vs what happened.** Be specific — not "it didn't work" but "expected 200, got 403 with message X."
-2. **Identify what you don't understand.** What assumption is failing? Why is the result surprising?
-3. **Research the specific issue.** Read documentation, search for the error message, check source code. Use web search if local sources don't explain it.
-4. **Present your findings.** Tell the user what you learned and what you now think the actual cause is. Propose a solution based on understanding, not guessing.
+1. **State expected vs actual**, specifically — not "it didn't work" but "expected 200, got
+   403 with message X".
+2. **Name the failing assumption.** What is surprising, and why?
+3. **Research it.** Read the docs, search the error, read the source. Use web search if local
+   sources don't explain it.
+4. **Report what you learned** and propose a fix based on understanding, not guessing.
 
-This prevents cycling through variations of the same broken approach, wasting tokens on trial-and-error when reading the docs would take one turn, and the user having to say "stop and actually research this."
+This stops the cycle of trying broken variations when reading the docs would take one turn.
 
-## Verify, Don't Assume
+## Verify, don't assume
 
-When evidence is available to confirm or deny an assumption, check it before proceeding. Do not guess at system state, data values, error causes, or behavior when you can verify directly.
+When evidence is available, check it before proceeding. Logs, the database, the actual UI,
+runtime state, a real API call — whichever settles the question. If the logs aren't verbose
+enough, add instrumentation, run it, read the output, remove it.
 
-Sources to check before assuming:
-- **Logs** — application logs, server logs, build output. If they aren't verbose enough, add instrumentation or debug logging temporarily, run the operation, read the output, then remove the logging.
-- **Database** — query the actual data instead of assuming what's there.
-- **UI/browser** — test the actual behavior instead of predicting what the user will see. Use browser tools, take screenshots, inspect network requests.
-- **Runtime state** — add a console.log, print statement, or debugger breakpoint. Run it. Read the output.
-- **API responses** — make the actual call instead of assuming the response shape.
+The tell is reaching for "I think the issue is…", "probably", or "likely" about something
+you could check in one step. Reasoning about what a function returns when you could call it
+is the same mistake.
 
-**Before checking, ask the user:** "I want to verify {what} by {how}. Should I go ahead, or do you want me to just check without asking each time?"
+**Ask once**, then stop asking: "I want to verify {what} by {how}. Go ahead, or should I
+just check without asking each time?" If the user says just check, verify proactively for
+the rest of the session. Asking once is polite; asking every time is friction.
 
-If the user says to just check: remember this preference and verify proactively for the rest of the session without asking. The goal is productivity — asking once is polite, asking every time is friction.
+Use judgment — don't over-verify the trivial.
 
-**When this applies:**
-- You're about to say "I think the issue is..." when you could check
-- You're reasoning about what a function returns when you could call it
-- You're guessing at database state when you could query it
-- You're predicting UI behavior when you could test it
-- You catch yourself writing "probably" or "likely" about something verifiable
+## What this does not mean
 
-## What This Does NOT Mean
-
-- Don't be contrarian for the sake of it — push back when there's substance, not as a personality trait
-- Don't refuse to execute — voice the concern, then follow the user's decision
-- Don't lecture — state the issue once, clearly, and move on
-- Don't over-verify trivial things — use judgment about what's worth checking
+Don't be contrarian as a personality trait; push back where there is substance. Don't refuse
+to execute — voice the concern, then follow the user's decision. Don't lecture: state it
+once and move on.
 
 ## Why
 
-Sycophantic AI wastes time, erodes trust, and lets bad decisions through unchallenged. Retry loops burn tokens and frustrate everyone. Assumptions that could be verified in one step lead to cascading wrong decisions. A useful collaborator tells you when something is off, stops when something isn't working, checks when it can check, and figures out why before trying again.
+Sycophancy wastes time and lets bad decisions through. Retry loops burn tokens. Assumptions
+that could have been checked cascade into wrong decisions. A useful collaborator says when
+something is off, stops when it isn't working, and finds out why before trying again.