dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-setup/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: ce-setup
+description: "Check Compound Engineering health and repo-local config, or scaffold a Compound Pack with `pack:<id>`."
+argument-hint: "[pack:<id>]"
+disable-model-invocation: true
+---
+
+# Compound Engineering Setup
+
+## Interaction Method
+
+Ask each question below using the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Fall back to a numbered list on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip or auto-configure.
+
+`ce-setup` is a lightweight health check and repo-local config helper. It does **not** bulk-install every optional dependency. Missing tools are reported as optional capabilities so the user can install only the workflows they use.
+
+## Pack Scaffold
+
+When the invocation names a Compound Pack to add, create, or scaffold (the `pack:<id>` argument, or the same request in words), read `references/pack-scaffold.md` from this skill's directory and follow it in place of Phases 1-2 (Diagnose and Fix Repo-Local Issues): it writes the pack and its config entry only after the user approves, runs the health check itself, and reports into Phase 3 (Summary).
+
+## Artifact Root Resolution
+
+Every Compound Engineering skill that writes or reads an artifact directory (`solutions`, `plans`, `ideation`, and the other CE-owned trees) resolves its root through the rule below. `ce-setup` carries the canonical statement and reports the resolved root so an operator can confirm where artifacts land before running other skills.
+
+<!-- ce-docs-root:start -->
+**Resolve the CE artifact root `<root>` before composing any artifact path.**
+
+- **Read** `docs_root` from `<repo-root>/.compound-engineering/config.yaml` only (`<repo-root>` = `git rev-parse --show-toplevel`). Do not read it from `config.local.yaml`. Unset -> `<root>` is `docs`, exactly as before.
+- **Validate** a set value: a repo-relative directory whose real, symlink-resolved path stays inside the repo and is neither the repo root nor under `.git/`. Otherwise stop with an error naming `docs_root` and the value -- never fall back to `docs`.
+- **Use** `<root>` as the sole artifact location: create it if absent, compose each path as `<root>/<subdir>` with this skill's own subdirectory, and never also read `docs`.
+<!-- ce-docs-root:end -->
+
+## Phase 1: Diagnose
+
+### Step 1: Determine Plugin Version
+
+Detect the installed compound-engineering plugin version by reading the plugin metadata or manifest when the platform exposes it. If the version cannot be determined, skip this step.
+
+If a version is found, pass it to the check script via `--version`. Otherwise omit the flag.
+
+### Step 2: Run the Health Check
+
+Before running the script, display:
+
+```text
+Compound Engineering -- checking your environment...
+```
+
+Run the bundled check script. Set `SKILL_DIR` to the absolute directory you loaded this `ce-setup` SKILL.md from — the Bash tool's CWD is the user's project, not the skill dir, so a bare `scripts/` path will not resolve:
+
+```bash
+SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
+if [ -f "$SKILL_DIR/scripts/check-health" ]; then bash "$SKILL_DIR/scripts/check-health" --version VERSION; else echo "Bundled health script not found at $SKILL_DIR/scripts/check-health; run the inline checks from ce-setup instead."; fi
+```
+
+Use the same command without `--version VERSION` if Step 1 could not determine a version.
+
+If the script is unavailable, run the inline equivalent listed in `references/repo-fixes.md`.
+
+Display the diagnostic output to the user. Missing optional tools are not setup failures. The health report includes the resolved artifact root and which config layer supplied it (per Artifact Root Resolution above); show that line so the operator can confirm where CE artifacts will be written. Missing `config.yaml` is a reported absence, not a project issue.
+
+### Step 3: Decide Whether Fixes Are Needed
+
+Repo-local fixes the health report names apply only to the checkout that report diagnosed. If Phase 2 will write to a different writable checkout, diagnose that checkout first. Session-level findings such as plugin version and optional tools still come from this session's Phase 1.
+
+After the health report, decide Phase 2 from writable-checkout availability:
+
+- If this session has a writable git checkout, run Phase 2 locally, including when `project_issues` is 0. Phase 2 always refreshes the example and always offers to create `config.yaml` when that file is missing.
+- If this session has no writable checkout, but the user named a repository and the harness exposes a remote repo-work surface with a writable checkout, run Phase 2 on that surface instead and report the remote repo-local fixes in Phase 3.
+- Otherwise skip Phase 2 and go to Phase 3, saying repo-local writes were skipped because no writable checkout is available.
+
+Two offers concern this machine rather than the checkout, so they stand whether or not Phase 2 runs. If the report names a legacy Compound Codex tool map, offer to remove it following `references/legacy-codex-tool-map.md` from this skill's directory. If the bundled health script reported the `node` row available, offer to warm the npm cache for cross-model peers following `references/acpx-cache-warm.md`.
+
+Also remediate these project issues when the report names them:
+
+- obsolete `compound-engineering.local.md`
+- `.compound-engineering/config.local.yaml` exists but is not safely gitignored
+- `.compound-engineering/config.example.yaml` is missing or outdated
+- the health report marks the `ce-work` skill implementation engine unavailable or invalid, detects retired scalar routing keys, or reports malformed dormant `work_engine_preferences` or a malformed `work_engine_effort`
+- the health report marks `docs_root` invalid (`Invalid docs_root ...`) — CE artifacts will not be written until it is fixed
+
+If optional tools are missing, do not offer a bulk install. The diagnostic already printed the relevant install command or project URL. Say: "Install optional tools only for the workflows you use."
+
+## Phase 2: Fix Repo-Local Issues
+
+Read `references/repo-fixes.md` from this skill's directory before making any repo-local change. It carries Steps 4-9: removing the obsolete `compound-engineering.local.md`, refreshing the example config, offering to create `config.yaml`, repairing invalid `work_engine_preferences` and `docs_root`, the two `.gitignore` offers, and the agent-instructions offers (a knowledge-store mention, the compounding directive, and the chat-register directive for `ce-noslop`).
+
+All paths there resolve from the repository root (`git rev-parse --show-toplevel`), not the current working directory. Maintaining the generated example files is the work Phase 2 does on its own — refreshing `config.example.yaml` and removing the superseded `config.local.example.yaml`. Every change to a user-owned file is offered and applied only if the user approves.
+
+## Phase 3: Summary
+
+**User-runnable invocation rendering.** In setup summaries, default to `/ce-setup`; use `$ce-setup` only when the active host is Codex or explicitly documents dollar-prefixed skill invocation. On oh-my-pi (`omp`), use `/skill:ce-setup`. Render only the invocation as inline code and output one form only.
+
+Display a brief summary:
+
+```text
+✅ Compound Engineering setup complete
+
+Fixed:     <fixes applied, or none>
+Skipped:   <fixes declined, or none>
+Optional:  <missing optional tools, or all available>
+
+Run `<rendered invocation>` anytime to re-check.
+```

package/skills/ce-setup/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/skills/ce-setup/assets/compounding-directive.md

@@ -0,0 +1,11 @@
+# Compounding directive
+
+Standing-instruction text `ce-setup` offers to add to a project's agent-instructions file. Insert one variant verbatim; the wording is pinned to the `ce-compound` guide by a test.
+
+## Offer first
+
+After a solved, verified problem, offer once to invoke the `ce-compound` skill at the completion checkpoint only when the work produced durable project reasoning that is not readily recoverable from the final code, tests, types, comments, or existing documentation, and losing it would plausibly cause recurrence, material risk, or substantial rediscovery. Apply this counterfactual: if the learning document disappeared, would a future engineer reading the final implementation still be likely to repeat the mistake or redo substantial investigation? If not, do not offer. Completion, effort, and diff size alone are not enough. Offer at the checkpoint so a qualifying learning can ship in the PR that produced it, and only where the repository treats captured learnings as tracked, committed knowledge.
+
+## Run automatically
+
+After a solved, verified problem, automatically invoke the `ce-compound` skill with `mode:non-interactive` at the completion checkpoint only when the work produced durable project reasoning that is not readily recoverable from the final code, tests, types, comments, or existing documentation, and losing it would plausibly cause recurrence, material risk, or substantial rediscovery. Apply this counterfactual: if the learning document disappeared, would a future engineer reading the final implementation still be likely to repeat the mistake or redo substantial investigation? If not, do not invoke it. Completion, effort, and diff size alone are not enough. Capture at the checkpoint so a qualifying learning can ship in the PR that produced it, and only where the repository treats captured learnings as tracked, committed knowledge.

package/skills/ce-setup/assets/noslop-directive.md

@@ -0,0 +1,7 @@
+# Chat-register directive
+
+Standing-instruction text `ce-setup` offers to add to a project's agent-instructions file. Insert it verbatim; the wording is pinned by a test.
+
+## Standing instruction
+
+Write every report, summary, or handoff to the user through the `ce-noslop` skill. This applies when you are the top-level agent writing to the user, not when you are a subagent reporting to its caller. Do not apply it to code, config, verbatim quotes, or text the user asked to post as written.

package/skills/ce-setup/assets/pack-rule-template.md

@@ -0,0 +1,11 @@
+---
+title: <One sentence stating what must always, or never, happen>
+applies_when:
+  - <a situation in the words a task would use, e.g. adding a page that needs server data>
+  - <a second situation, e.g. adding or changing an endpoint the app's own pages consume>
+tags: [<topic>, <component>]
+---
+
+<Replace this paragraph with the rule. Say what to do, what not to do, and the one exception if there is one. Keep it prescriptive and short enough to quote whole; a planning or review agent reads it only when a condition above matches the work in front of it.>
+
+Layout reminder, delete once the rule is written: only top-level `.md` files with `title` and `applies_when` are discovered as rules; `README.md` is this pack's description, never a rule; subfolders are storage for the evidence and data a rule points at.

package/skills/ce-setup/references/acpx-cache-warm.md

@@ -0,0 +1,14 @@
+# Warm the npm cache for cross-model peers
+
+Cross-model peers run the pinned acpx through `npx`, and acpx launches its codex and claude adapters the same way. Each peer run asks npm to prefer cached copies, so a package already in the npm cache starts in about a second, while a missing one has to be downloaded first. Warming fetches the pinned acpx and those adapters into the cache now, over the network, so the first peer run does not pay for the download.
+
+Ask once, saying it downloads the pinned acpx and its adapters from the npm registry into the user's npm cache, and that npm runs any install scripts those packages declare, as a first peer run would. Run it only after the user approves; if they decline, fetch nothing.
+
+On approval, run the health script with `--warm-acpx` in place of `--version VERSION`, using the same `SKILL_DIR` as Step 2:
+
+```bash
+SKILL_DIR="<absolute path of the directory containing the ce-setup SKILL.md>";
+bash "$SKILL_DIR/scripts/check-health" --warm-acpx
+```
+
+It installs each package into npx's cache, without starting the package itself, and prints one line per package. Show those lines. A package that could not be fetched leaves peers working; that peer run downloads it instead. Report the warm under Fixed when every package was cached, and under Skipped when the user declined or a fetch failed, naming the package.

package/skills/ce-setup/references/config-template.yaml

@@ -0,0 +1,210 @@
+# Compound Engineering -- repo config
+# Copy to .compound-engineering/config.yaml in your project root (team defaults).
+# Optional override: .compound-engineering/config.local.yaml, same keys.
+# Ordinary keys: local wins when set, then this file, then the skill default.
+# docs_root is repo layout -- set it only here; local docs_root is ignored.
+# All settings are optional. Invalid ordinary values continue to the next layer.
+# docs_root fails closed on an unusable value.
+
+# --- Artifact root ---
+# Relocate every CE-written artifact folder (solutions, plans, ideation,
+# explainers, pulse-reports, dogfood-reports,
+# feedback-sweep, personas) under one repo-relative root. Unset -> `docs`,
+# byte-identical to today. A configured root becomes the sole location CE reads
+# and writes; CE never falls back to reading `docs/`.
+#
+# Set this only in this tracked file so every clone and worktree share one
+# artifact tree. A docs_root in config.local.yaml is ignored.
+#
+# The value must be a repo-relative directory whose real (symlink-resolved) path
+# stays inside the repo, is not the repo root itself, and is not under `.git/`.
+# Unlike every other setting here, an unusable value does NOT fall through to the
+# default -- CE stops with an error so a typo can't silently write artifacts into
+# the location you configured away from. `/ce-setup` reports the resolved root.
+
+# docs_root: .compound-engineering/artifacts   # repo-relative dir (default: docs)
+
+# --- Product pulse ---
+# Settings written by /ce-product-pulse first-run interview. Re-run the skill with
+# argument `setup` or `reconfigure` to edit interactively.
+
+# pulse_product_name: "Spiral"                          # used in report titles (no default)
+# pulse_lookback_default: 24h                           # 1h | 24h | 7d | 30d (default: 24h)
+# pulse_primary_event: "session_started"                # the event that means "user showed up"
+# pulse_value_event: "task_completed"                   # the event that means "user got value"
+# pulse_completion_events: "onboarded,first_purchase"   # comma-separated, 0-3 events
+# pulse_quality_scoring: false                          # true | false (default: false; AI products only)
+# pulse_quality_dimension: "answer accuracy"            # dimension scored 1-5 when pulse_quality_scoring is true
+# pulse_analytics_source: posthog                       # posthog | mixpanel | custom (no default)
+# pulse_tracing_source: sentry                          # sentry | datadog | custom (no default)
+# pulse_payments_source: stripe                         # stripe | custom (no default)
+# pulse_db_enabled: false                               # true | false (default: false; read-only DB if true)
+# pulse_metric_sources: "retention_d7=posthog,nps=delighted"  # strategy-metric -> source overrides; comma-separated 'metric=source' pairs; unlisted metrics fall back to pulse_analytics_source
+# pulse_pending_metrics: "retention_d7,nps"             # comma-separated strategy metrics awaiting instrumentation; render as 'no data'
+# pulse_excluded_metrics: "north_star"                  # comma-separated strategy metrics intentionally not in pulse
+
+# --- Output format ---
+# Per-skill output format default. Selects the exclusive format the artifact
+# is written in: `md` produces a markdown file, `html` produces a single
+# self-contained HTML file. The two are mutually exclusive -- there is no
+# sibling artifact. See DESIGN.md or your agent instructions to influence
+# HTML styling. Precedence: a format request in your prompt for that run wins
+# (e.g. "output:html" or "make it HTML"); a preference you established earlier
+# (in-session, saved to memory, or in your agent instructions) overrides these
+# keys (this config is the persisted fallback). A headless or pipeline run
+# resolves the format the same way; nothing forces `md`.
+
+# plan_output: html              # md | html (default: md)
+# brainstorm_output: html        # md | html (default: md)
+# ideate_output: md              # md | html (default: html -- ideation docs are human-facing, so HTML is the default; set md to opt out)
+
+# --- Model elevation ---
+# Send only the reasoning-heavy step of /ce-plan (interpret research, then author
+# the plan) and /ce-brainstorm (generate approaches) to a model you name. The rest
+# of each skill -- dialogue, research, orchestration -- stays on your session
+# model. The value is a model alias (e.g. `fable`, `opus`). You can also name a
+# model in a prompt for a one-off, which overrides these keys.
+#
+# Cross-harness: setting a key means every harness you run these skills in will
+# attempt that model. The host serves it natively where it can; otherwise the
+# Claude CLI is invoked when installed and authenticated; otherwise the step runs
+# on your session model and the run says so. Invalid/commented/missing -> no
+# elevation.
+
+# plan_model: fable              # model alias for plan authoring; candidate preference when a Bake-off runs (no default)
+# brainstorm_model: fable        # model alias for approach generation; candidate preference when a Bake-off runs (no default)
+
+# --- PR concept teaching (ce-commit-push-pr) ---
+# When a PR introduces a concept new to the codebase, the generated PR
+# description gains a "New concepts" section teaching it. The section toggle is
+# the single gate: off disables judgment, the section, the /ce-explain offer,
+# and archival. Archival additionally writes the explainer to docs/explainers/
+# and links it from the PR (full-workflow runs only; override per run with
+# archive:on|off). Ordinary cascade: local, then this file, then the skill default.
+
+# pr_teaching_section: false     # true | false (default: true)
+# pr_teaching_archive: true      # true | false (default: false; full-workflow runs only)
+
+# --- ce-commit-push-pr babysit handoff ---
+# After a full-workflow PR is opened, ce-commit-push-pr auto-invokes ce-babysit-pr
+# to watch CI + incoming review and drive the PR toward merge-ready. Set false to
+# opt out standing (per-run override: the babysit:off token). This governs that
+# standing watch only -- lfg's in-pipeline babysit is bounded (3 fix rounds) and
+# still runs, since it is how that pipeline reaches "CI decided".
+# auto_babysit: false            # true | false (default: true)
+
+# --- ce-plan scoping confirmation ---
+# By default /ce-plan pauses before research/plan-write to show a scoping
+# summary and wait for you to confirm scope. Set this to skip that wait: ce-plan
+# composes the summary for itself, records any inferred scope under an
+# Assumptions section, announces that it's proceeding, and keeps going. It skips
+# only that confirmation -- genuine blocking questions and the post-plan menu
+# still appear. Override per run with `confirm:auto` (skip) or `confirm:ask`
+# (force the gate on for one run).
+
+# plan_skip_scoping_confirm: true   # true | false (default: false)
+
+# --- Cross-model review policy and preference ---
+# `cross_model_review_mode` decides whether ce-doc-review and ce-code-review may
+# automatically send review content (diffs, documents) to a second model
+# provider when their conditional cross-model pass activates. `off` skips that
+# pass before any route is chosen or process starts, leaves every local
+# reviewer in place, and reports "disabled by checkout config" instead of an
+# availability failure. `auto` keeps the current behavior. A direct request in
+# conversation ("use codex as the independent reviewer this time") overrides
+# `off` for that run; a conversation prohibition overrides `auto`.
+#
+# `cross_model_peer` is the preferred peer, consulted only when the mode is
+# `auto`. Conversation instructions still win, and the skills skip routes that
+# cannot establish the required host/peer distinction.
+# `cross_model_model` and `cross_model_effort` pin the model and reasoning
+# effort of whichever peer target runs; unset keeps the skills' editorial
+# mapping. The model must belong to that target's family (an alias such as
+# `fable` or a full id such as `claude-opus-5-5` for claude; `gpt-*` for codex,
+# optionally namespace-qualified such as `openai.gpt-6.1-sol` when the codex CLI
+# routes through a non-default `model_provider`; a `gemini-*` id such as
+# `gemini-3.8-flash` for antigravity).
+# Effort levels: claude low|medium|high|xhigh|max, codex low|medium|high|
+# xhigh plus max and ultra on the models that list them, grok low|medium|high|
+# xhigh, antigravity low|medium|high, OpenCode 2.x none|low|medium|high|xhigh|
+# max as each model lists them; cursor/composer routes take none. A value the peer
+# cannot honor skips the pass with a stated reason -- never substituted.
+
+# cross_model_review_mode: off   # auto | off (default: auto)
+# cross_model_peer: codex          # codex | claude | grok | antigravity | cursor | composer | opencode
+# cross_model_model: fable         # model alias or full id for the resolved peer target (no default)
+# cross_model_effort: xhigh        # reasoning effort for the resolved peer target (no default)
+
+# --- ce-work implementation engine ---
+# Standing preferences for who authors implementation units. Live
+# task/session/project instructions and LFG's provenance-bearing binding may
+# override or narrow these defaults. `off` disables only this standing preference.
+# `prefer` tries candidates in order, then falls back natively with disclosure.
+# `require` keeps the requested external identity fixed while viable, then also
+# falls back natively with disclosure if the route is unavailable. Harnesses:
+# codex | claude | grok | antigravity | cursor | opencode. Omit model to use that harness's configured
+# default. Composer is a model
+# family through Cursor: { harness: cursor, model: composer }. Do not put CLI flags
+# or commands here. A candidate equivalent to the current host/default is skipped;
+# a different explicit model in the same harness remains eligible.
+
+# work_engine_mode: prefer        # off | prefer | require (default: off)
+# work_engine_preferences:
+#   - harness: cursor
+#     model: composer
+#   - harness: codex
+#     model: "gpt-6.1-sol"
+#   - harness: claude             # configured default model
+
+# Reasoning effort for the external worker, per harness. Each value is one of
+# that harness's own effort levels. An unset harness keeps its own default:
+# Codex and Claude at high, native Grok at xhigh, Antigravity at high (it takes
+# low|medium|high). OpenCode (2.x) keeps its own per-model default and takes
+# none|low|medium|high|xhigh|max as each model lists them. Cursor routes take no
+# effort. A map in config.local.yaml replaces this one.
+
+# work_engine_effort:
+#   codex: xhigh
+#   claude: max
+
+# --- ce-promote ---
+# Written automatically when you decline the Spiral setup offer in /ce-promote.
+# Suppresses that one-time setup nudge in this project. Remove the key to re-enable.
+
+# ce_promote_spiral_optout: true   # true | (absent) (default: absent -- offer once)
+
+# --- Sweep (ce-sweep) ---
+
+# Feedback sources swept by /ce-sweep. Generic key: other skills may read this list.
+# Each entry: type (slack | github-issues | email), id (short name), target (channel ID /
+# owner/repo / mailbox), ack_action, closeout_action, sensitive (true withholds content
+# from committed state/plan text), approved (standing approval for source-side writes).
+# feedback_sources:
+#   - { type: slack, id: slack-alpha, target: C0XXXXXXX, ack_action: eyes, closeout_action: white_check_mark, sensitive: false, approved: true }
+#   - { type: github-issues, id: gh-issues, target: owner/repo, ack_action: "feedback:ack", closeout_action: "feedback:resolved", sensitive: false, approved: true }
+
+# Sweep-owned settings.
+# sweep_state_path: docs/feedback-sweep/state.yml   # committed (multi-agent) or /tmp path (solo)
+# sweep_ack_cap: 25                                 # max acks per source per run before the circuit breaker
+# sweep_lease_ttl_minutes: 60                       # single-writer lease staleness threshold
+# sweep_shared_branch: false                        # true: push-gated lease for shared-docs-branch topology
+
+# --- Compound Packs ---
+
+# Prescriptive domain knowledge folders that planning reads and cites.
+# Declared, never scanned: an entry names a source (repo-relative path,
+# ~/absolute path, or git URL) and what to install from it. Lists from this
+# file and config.local.yaml concatenate -- local adds packs, never replaces
+# the team's. Git sources require ref (tag or sha reproduce exactly; a branch
+# freezes at its cached resolution and can drift across machines). path: and
+# pasted GitHub /tree/<ref>/<sub> URLs scope a source to a subfolder.
+# pack: picks one id or a list; omit it to install everything the source
+# publishes. id: renames a single-pack entry.
+# Rules are top-level .md files with title + applies_when; subfolders are storage.
+
+# packs:
+#   - source: compound-packs/local-rules                       # repo-relative, read live
+#   - source: ~/compound-packs/kk-style                        # machine-local, read live
+#   - source: https://github.com/org/rails-ce-pack    # git, cached at ref
+#     ref: v1.2.0
+#     pack: [rails, inertia]

package/skills/ce-setup/references/legacy-codex-tool-map.md

@@ -0,0 +1,15 @@
+# Remove the retired Compound Codex tool map
+
+The Bun-era `convert` / `install --to codex` path inserted a managed block into the global Codex instructions file:
+
+`<!-- BEGIN COMPOUND CODEX TOOL MAP -->` … `<!-- END COMPOUND CODEX TOOL MAP -->`
+
+in `${CODEX_HOME:-$HOME/.codex}/AGENTS.md`. That Claude-compat map is obsolete — CE skills name Codex tools inline — and one of its lines told Codex to collapse subagent dispatch onto the main thread. Native plugin install does not add it, and re-running the Bun CLI for Codex strips it.
+
+## Removal
+
+Delete the managed block from that file: the line `<!-- BEGIN COMPOUND CODEX TOOL MAP -->` through the next line `<!-- END COMPOUND CODEX TOOL MAP -->`. If that pair is not present as two whole lines in that order, the block is not there — change nothing.
+
+Leave the rest of the file untouched, and delete the file if nothing is left. Do not add a replacement map, and do not touch a project or repo `AGENTS.md`: the Bun installer only ever wrote the Codex home file.
+
+Show the user a short before/after of what changed, or say the block was already absent.

package/skills/ce-setup/references/pack-scaffold.md

@@ -0,0 +1,45 @@
+# Pack scaffold
+
+Loaded from SKILL.md when the invocation names a pack to add, create, or scaffold. Ask with the blocking question tool named in SKILL.md.
+
+**Outcome:** a Compound Pack the resolver publishes on the next planning or review run: a directory holding a `README.md` that says what the pack governs, one first rule at the top level, and a `packs:` entry in `.compound-engineering/config.yaml` that points at it. The next consumer is the bundled health check, which lists the pack as `pack <id>`.
+
+**Done:** the health check reports `pack <id>` with no `Pack config error` or `publishes no packs` line about it, and the author has heard the layout rule and where the guide states it.
+
+**Safe failure direction:** write nothing rather than write into a directory or a config file the user has not seen. A target directory that exists and is not empty, a source the config already declares, or a run that cannot ask the user each stop the scaffold with a report of what it would have written.
+
+## Facts the scaffold needs
+
+- The pack id is kebab-case ASCII (`a-z`, `0-9`, `-`): the resolver names a pack after its directory, and the id appears in citations as `(pack: <id>, <file>)`. Take it from the `pack:<id>` token, otherwise from the words of the request; ask when neither yields one.
+- The default target is `compound-packs/<id>/` relative to the repository root (`git rev-parse --show-toplevel`). When the user names another repo-relative directory, the config entry points there instead.
+- A rule is discovered only when it is a top-level `.md` with `title` and `applies_when` frontmatter; the pack's `README.md` is its description and never a rule; subdirectories and non-`.md` files are storage. The scaffold exists so a first pack starts in this shape.
+- A live pack entry in `config.yaml` is `- source: compound-packs/<id>` under a top-level, uncommented `packs:` key. The bundled template ships that key as a comment, which is not a live key.
+
+## Procedure
+
+1. **Resolve the target.** Compute the id and the directory. Stop, saying why, when the directory exists and is not empty or when `config.yaml` already declares this source. An empty existing directory is fine.
+
+2. **Draft the two files.** `README.md` at the pack's top level: no frontmatter, one line saying what the pack governs, drawn from what the user said, or asked for when they said nothing. The first rule comes from `assets/pack-rule-template.md` in this skill's directory, saved as `<kebab-case of the title>.md` beside the README. When the user described the first rule, fill `title`, `applies_when`, `tags`, and the body from that description; otherwise keep the template's placeholders, which still publish the pack and show the author what to replace. Keep the template's layout-reminder paragraph; it tells the author to delete it.
+
+3. **Draft the config change.** When `.compound-engineering/config.yaml` is missing, create it from `references/config-template.yaml` under the same approval. Append `  - source: compound-packs/<id>` (or the directory the user chose) as the last item of the live `packs:` list, matching its indentation; when there is no live key, append this block at the end of the file:
+
+   ```yaml
+   packs:
+     - source: compound-packs/<id>
+   ```
+
+   Leave the template's commented `# packs:` example and every other line exactly as they are. `config.local.yaml` is not the target; a pack the team shares belongs in the tracked file.
+
+4. **Ask once, showing everything.** Preview the directory, both files in full, and the exact config lines with their placement, then ask:
+
+   ```text
+   Create the Compound Pack `<id>`?
+   1. Yes, write these files and the config entry
+   2. No thanks
+   ```
+
+   Write only on approval. When the caller declared the run non-interactive, or no question can reach the user, print the same preview, say the scaffold wrote nothing, and stop.
+
+5. **Verify with the health check.** Run the bundled `scripts/check-health` exactly as SKILL.md Step 2 does, with the same `SKILL_DIR` anchor, and report its `pack <id>` line. A `Pack config error` or `publishes no packs` line about this pack means the scaffold is not done: fix the cause and run the check again.
+
+6. **Tell the author.** In one sentence: a rule is discovered only when it is a top-level `.md` with `title` and `applies_when`; everything else in the pack folder is storage, and `README.md` is the description. Point at `https://everyinc.github.io/compound-engineering-plugin/guides/packs/`, "Pack layout", for the annotated tree. Report the pack under Fixed, or under Skipped when the user declined, in the Phase 3 summary.

package/skills/ce-setup/references/repo-fixes.md

@@ -0,0 +1,121 @@
+# Repo-local fixes (Phase 2) and the summary (Phase 3)
+
+## Inline health-check equivalent (Step 2 fallback)
+
+When the bundled `scripts/check-health` is unavailable, perform these checks by hand and report the same findings:
+
+1. Check optional tools with `command -v`: `agent-browser`, `gh`, `jq`, `ast-grep`, `ffmpeg`.
+2. If inside a git repo, resolve the repo root with `git rev-parse --show-toplevel`.
+3. Check for obsolete `compound-engineering.local.md` at the repo root.
+4. Check whether `.compound-engineering/config.yaml` exists.
+5. Check whether `.compound-engineering/config.local.yaml` exists and, if it does, whether `git check-ignore -q .compound-engineering/config.local.yaml` succeeds.
+6. Compare `.compound-engineering/config.example.yaml` with `references/config-template.yaml` when the template is readable; otherwise report that the example refresh must be done manually.
+7. Report a legacy Compound Codex tool map when `${CODEX_HOME:-$HOME/.codex}/AGENTS.md` contains a standalone `<!-- BEGIN COMPOUND CODEX TOOL MAP -->` line followed by a standalone `<!-- END COMPOUND CODEX TOOL MAP -->` line.
+8. Report the `node` row as available for cross-model peers when `node -p 'process.versions.node'` is 22.13 or newer and `command -v npx` succeeds; otherwise name which of the two is missing or too old.
+
+This file is read at two points: from Step 2 whenever the bundled health script is unavailable, for the inline equivalent above; and before any Phase 2 write, once Step 3 has decided that a writable checkout exists and which reported issues need remediation. Ask with the blocking question tool named in SKILL.md. Maintaining the generated example files is the work this phase does on its own — Step 5's refresh and its removal of the superseded `config.local.example.yaml`. Every change to a user-owned file is offered and applied only if the user approves.
+
+## Phase 2: Fix Repo-Local Issues
+
+Resolve the repository root (`git rev-parse --show-toplevel`). All paths below are relative to the repo root, not the current working directory.
+
+### Step 4: Remove Obsolete Local Config
+
+If `compound-engineering.local.md` exists at the repo root, explain that it is obsolete because review-agent selection is automatic and surviving machine-local settings now live in `.compound-engineering/config.local.yaml` (the optional override). Team defaults live in `config.yaml`.
+
+Ask whether to delete it now. Delete only if the user approves.
+
+### Step 5: Refresh Example Config
+
+Copy `references/config-template.yaml` to `<repo-root>/.compound-engineering/config.example.yaml`, creating the directory if needed. This file is committed to the repo and should always reflect the latest available settings.
+
+If leftover `<repo-root>/.compound-engineering/config.local.example.yaml` remains after the new example exists, treat it as stale generated example (not user config) and remove it with `trash` (never `rm`).
+
+If the bundled template cannot be located by the current platform, print the source template path that failed and tell the user the example config could not be refreshed automatically.
+
+### Step 6: Create Repo Config If Missing
+
+If `.compound-engineering/config.yaml` does not exist, ask — even when health is otherwise green:
+
+```text
+Set up a repo config file for this project?
+This creates .compound-engineering/config.yaml with optional Compound Engineering team defaults.
+Everything starts commented out -- you only enable what you need.
+It does not create config.local.yaml.
+
+1. Yes, create it
+2. No thanks
+```
+
+If the user approves, copy `references/config-template.yaml` to `<repo-root>/.compound-engineering/config.yaml`. Never overwrite an existing `config.yaml` or `config.local.yaml`.
+
+If `config.local.yaml` already exists, leave it. After creating (or if both files already exist), name ordinary local keys that would shadow the new team file. If local still has `docs_root`, say it is ignored and offer to move it into `config.yaml`.
+
+Do not create `config.local.yaml`.
+
+### Step 6a: Repair Invalid CE Work Preferences
+
+When the health report marks the CE Work implementation engine unavailable or invalid, detects retired scalar routing keys, or reports malformed dormant `work_engine_preferences`, do not guess the intended recipients. Explain the exact reported problem, derive a valid ordered `work_engine_preferences` block from the user's stated harness/model order (or remove malformed dormant preferences and use `work_engine_mode: off` when they want native-by-default), remove any retired scalar routing keys, and show the complete replacement block. Edit the layer that supplied the failing value. If the bad ordinary key is only in `config.yaml`, edit that file after preview. Do not hide a broken team value behind a new local override. Preserve every unrelated setting. Re-run the health check and require it to report either native or the intended normalized ordered list before setup is complete.
+
+When the health report warns about `work_engine_effort`, the health status of the engine does not change, and the warning says what `ce-work` does with the value. A value that is not a map, or an entry for an unknown harness, requests nothing. A `cursor` entry is different: no Cursor route can run at an effort, so `ce-work` treats Cursor entries in the preference list as unavailable until the entry is removed. The key is a map from harness to one of that harness's own effort levels. Ask what effort the user wants for each harness rather than guessing, show the replacement map, and edit the layer the warning names. Re-run the health check and require the warning to be gone.
+
+### Step 6b: Repair Invalid `docs_root`
+
+When the health report marks `docs_root` invalid, explain the exact reason it gave (absolute, escapes the repo, `..` traversal, repo root, `.git/`, or a non-directory component) and the consequence: CE artifacts will not be written until it is fixed, because `docs_root` fails closed rather than silently falling back to `docs`. `docs_root` is read only from `.compound-engineering/config.yaml`. A `docs_root` in `config.local.yaml` is ignored — if local still has one, say so and offer to move it into `config.yaml`. Offer to either correct the tracked value to a valid repo-relative directory the user names, or remove the bad `docs_root` key from `config.yaml`. Removing it reaches the default `docs`. Edit only those keys after the user approves; preserve every unrelated setting. Re-run the health check and require it to report a resolved artifact root before setup is complete.
+
+### Step 7: Ensure Local Config Is Gitignored
+
+If `.compound-engineering/config.local.yaml` exists and is not covered by `.gitignore`, offer to add:
+
+```text
+.compound-engineering/*.local.yaml
+```
+
+Append the entry to the repo-root `.gitignore` only if the user approves. Do not overwrite unrelated `.gitignore` content.
+
+### Step 8: Offer To Gitignore CE Scratch Space
+
+Skills that keep local scratch write it under `.context/compound-engineering/`. Probe coverage with `git -C <repo root> check-ignore -q .context/compound-engineering/` — with the trailing slash, so an existing directory-only rule counts before the directory exists, and anchored to the repo root, since that is where the entry is appended — and when it is not covered, offer to add:
+
+```text
+.context/compound-engineering/
+```
+
+Append the entry to the repo-root `.gitignore` only if the user approves. Do not overwrite unrelated `.gitignore` content.
+
+Unlike Step 7 this does not wait for the path to exist. The skill about to write there offers the same entry at its first write, so a repository that never uses one of those skills never needs the line — adding it here only means that prompt never has to fire.
+
+### Step 9: Point Agents At The Knowledge Store, And Offer The Standing Directives
+
+Runs whenever the repository has a root agent-instructions file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or the equivalent this project uses). When one file only `@`-includes another, the substantive file is the target. No such file: skip this step and say so in the summary; setup never creates one.
+
+**Outcome:** an agent that reads the file learns that the knowledge store exists at the resolved `<root>/solutions/` and when it is relevant, and the file carries a standing instruction for capturing learnings and one for the agent's own chat replies if the user wants them. Each addition is offered separately, previewed with its exact placement, and applied only on approval.
+
+**Store mention.** Read the file and judge semantically, not by string match, whether a reader would learn three things: a store of documented solutions exists at the concrete path, enough of its shape to search it (categories, YAML frontmatter fields such as `module`, `tags`, `problem_type`), and that it is relevant when implementing or debugging in a documented area. When the spirit is met, offer nothing. Otherwise draft the smallest addition in the file's own style: one line in the closest existing section (a directory listing, architecture tree, conventions block) beats a new heading, and a new heading is the last resort. Keep the tone informational, not imperative, because an imperative causes redundant reads when a workflow already searches. Write the concrete resolved path, never the `<root>` placeholder, since people and plugin-less agents read this file. Calibration for a directory listing:
+
+```text
+<root>/solutions/  # documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (module, tags, problem_type)
+```
+
+**Compounding directive.** Offer it only when the repository treats the store as tracked, committed knowledge: git tracks at least one file under the resolved `<root>/solutions/` (`git ls-files` there is non-empty; an untracked or gitignored directory is not evidence), or the user just accepted the store mention. Skip the offer when the file already carries a standing instruction to invoke `ce-compound` at a completion checkpoint, in any wording. Otherwise ask:
+
+```text
+Add a standing instruction so agents capture qualifying learnings with ce-compound?
+1. Offer first -- the agent asks before capturing
+2. Run automatically -- the agent captures without asking
+3. No thanks
+```
+
+Insert the chosen variant verbatim from `assets/compounding-directive.md` in this skill's directory; the wording is pinned by a test, so do not paraphrase it. Place it beside the store mention when that landed in a conventions or working-agreement block, otherwise in the block where the file states how agents should work. Match the surrounding form (a bullet in a bullet list, a paragraph in prose). Preview the exact text and location, then append only on approval and leave the rest of the file untouched.
+
+**Chat-register directive.** Offer it whenever this step runs. Skip the offer only when the file already carries an instruction that covers all three parts of the bundled one: the report boundary (a user-facing report, summary, or handoff about to be written), the invocation (use the `ce-noslop` skill for that writing), and the exclusions (code, config, verbatim quotes, text the user asked to post as written). A partial instruction, such as one naming only the boundary or a generic "write plainly", or an unrelated writing rule still gets the offer. Ask:
+
+```text
+Add a standing instruction so agents write reports and summaries to you with ce-noslop?
+1. Yes, add it
+2. No thanks
+```
+
+Insert the text verbatim from `assets/noslop-directive.md` in this skill's directory; do not paraphrase it. Place it beside the compounding directive when that landed or already exists, otherwise where the compounding directive would go. Match the surrounding form. Preview the exact text and location, then append only on approval and leave the rest of the file untouched.
+
+Report all three outcomes in the Phase 3 summary under Fixed or Skipped.