@monte3l/groundwork 0.0.0

package/templates/core/.claude/skills/harness-guidance/references/official-sources.md

@@ -0,0 +1,58 @@
+# Official Anthropic sources — the allowlist
+
+The single source list consulted by `harness-guidance` in both modes.
+Editing this file is the one edit site when Anthropic moves, renames, or
+adds a domain.
+
+## Domain allowlist
+
+Pass verbatim as `WebSearch`'s `allowed_domains`:
+
+```
+anthropic.com, www.anthropic.com, claude.com, www.claude.com,
+platform.claude.com, code.claude.com, docs.claude.com, docs.anthropic.com
+```
+
+Anthropic's engineering posts, research papers, and news all live under
+`anthropic.com` (including `/engineering`, `/research`, `/news`), so this
+one allowlist covers whitepapers and blog posts as well as docs.
+
+## GitHub caveat
+
+`allowed_domains` filters by domain, not path, so a bare `github.com`
+allowance would let through any repo. Agents may include `github.com` and
+`raw.githubusercontent.com` in their search domains, but must **only cite or
+fetch URLs under the `anthropics` GitHub org** — `github.com/anthropics/...`
+or `raw.githubusercontent.com/anthropics/...` — and drop any other GitHub
+result, even a highly-ranked one.
+
+## First-class sources to enumerate directly
+
+Search ranking is not exhaustive — a recent post can be silently missed
+unless an agent is told to check these directly:
+
+- **Claude Code CHANGELOG** —
+  `https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md`.
+  The authoritative, version-ordered record of Claude Code feature and
+  behavior changes. Because it's version-ordered, it can be read as a
+  **delta** from a known prior version — the primary input for refresh
+  mode's Step 2.
+- **Blog / news / engineering / research index pages** — enumerate directly:
+  - `https://www.anthropic.com/news`
+  - `https://www.anthropic.com/engineering`
+  - `https://www.anthropic.com/research`
+  - `https://claude.com/blog`
+
+## Current-date anchor
+
+Every agent brief must state today's date explicitly. A `retrieved <date>`
+stamp otherwise depends on the spoke inferring the date itself, which is
+unreliable.
+
+## Coverage discipline
+
+Reject any non-allowlisted domain outright and say so in the report, rather
+than substituting a community blog, a third-party summary, or a Stack
+Overflow answer for missing official coverage. If a facet turns up no
+official source, that is itself a reportable finding (a coverage gap), not
+a reason to lower the bar.

package/templates/core/.claude/skills/starting-work/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: starting-work
+description: >-
+  The pre-work decision gate for any task that will change code. Invoke it
+  FIRST -- before reading, investigating, or editing anything -- for
+  "implement", "build", "add", "fix the bug where ...", "refactor", or any
+  request to change behavior, even when the change is unnamed or you have not
+  seen the code yet. Inspects git state, recommends a branch (feat/fix <slug>)
+  and push target, and decides whether a PR is required, all confirmed before
+  any write. Skip for research and questions that change nothing.
+---
+
+# starting-work
+
+This skill is the single place the project answers "where do I do this
+work?" before touching anything. `guard-branch-isolation.mjs` hard-blocks
+writes to `src/**` and `tests/**` while `HEAD` is `main` — that's a
+backstop, not a plan: if you discover it when a write is rejected, you're
+already mid-task with a dirty tree. This skill is the workflow half — it
+branches _before_ the block can fire.
+
+## The contract
+
+**Infer and recommend all decisions, then confirm every one with the user in
+a single round. Do not write files or create a branch until the user has
+confirmed.** The user is always free to override a recommendation; your job
+is to make the right default obvious, not to force it.
+
+## Steps
+
+### 1 — Inspect git state (read-only)
+
+```bash
+git rev-parse --abbrev-ref HEAD      # branch name; "HEAD" means detached
+git status --porcelain               # is the tree already dirty?
+```
+
+- A detached HEAD sitting on the `main` commit is treated as `main` for
+  isolation purposes — it's the same tree state the guard protects.
+- **Re-run this inspection after any conversational gap, not just at the
+  start.** The branch is not a stable fact across a long session.
+
+### 2 — Infer the change scope
+
+From the task in front of you, work out **which paths will be edited** and
+whether any are _guarded_ (under `src/**` or `tests/**`). This drives the PR
+decision and whether isolation is even required. A docs-only or `.claude/`
+-only change touches no guarded path, so the guard won't fire and a PR may
+be optional; a change under `src/` or `tests/` always needs isolation and a
+PR.
+
+### 3 — Recommend each decision
+
+- **Branch** — recommend `feat/<slug>` (or `fix/<slug>` for a bug fix), with
+  the slug derived from the task (kebab-case, short). If the repo is already
+  on a suitable non-`main` branch, recommend **staying** on it. Never
+  recommend `main` or a detached-on-`main` HEAD for guarded work.
+- **PR required?** — **yes** whenever a guarded path is in scope: land via
+  PR, never a direct commit to `main`. For docs/config-only changes, note
+  that a PR is optional but still recommended.
+- **Push target** — `origin <the recommended branch>`. Never `origin main`.
+
+### 4 — Confirm with the user (blocking)
+
+Ask every decision that applies in **one** `AskUserQuestion` call — branch,
+PR-required, and push target — one question per decision, with your inferred
+recommendation listed **first** and labelled "(Recommended)". For the
+branch, offer the inferred `feat/<slug>` plus an "Other" path for a custom
+slug. Make it explicit in your framing that **nothing is written and no
+branch is created until they confirm** — this is the whole point of the
+gate.
+
+If the user has _already_ told you the branch to use (e.g. "do it on
+`fix/foo`"), don't re-ask that dimension — treat it as confirmed and only
+surface the decisions still open.
+
+### 5 — Act on the confirmed decisions
+
+```bash
+git switch -c feat/<slug>   # or fix/<slug>
+```
+
+Verify `HEAD` is neither `main` nor detached-on-`main` before handing back;
+if it is, loop back to Step 4 rather than proceeding into a write that the
+guard will reject. When **resuming an existing feature branch** that may
+have fallen behind, resync it with `origin/main` before working (or defer to
+the resync step in `creating-prs`) so the branch does not drift from the
+base over multiple sessions.
+
+### 6 — Hand back
+
+Report a one-line summary of the confirmed decisions — branch, PR
+(yes/no), push target — so the calling skill or the user proceeds with the
+context recorded.

package/templates/core/.claude/skills/triaging-ci/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: triaging-ci
+description: >-
+  Diagnose a CI failure via gh CLI: resolve the failing run, fetch logs, map the
+  failure to its pipeline step, report root cause plus the exact local repro
+  command, and present 3-5 fix options. Use for /triaging-ci, "why did CI fail",
+  "CI is failing", "debug the CI run", or a specific run ID/URL. GitHub stance:
+  gh CLI.
+---
+
+Diagnose why a GitHub Actions CI run failed by fetching its logs via `gh` and
+mapping the failure back to the specific pipeline step and root cause, then
+present 3–5 solution options for the user to choose from. This skill does not
+apply fixes — it ends with options, not actions.
+
+## Steps
+
+### 1 — Resolve the run
+
+If the user provided an explicit run ID or URL, extract the numeric ID from it.
+
+Otherwise, find the most recent failed run on the current branch:
+
+```bash
+gh run list --branch $(git rev-parse --abbrev-ref HEAD) \
+  --limit 5 \
+  --json databaseId,status,conclusion,name,createdAt
+```
+
+Pick the most recent entry whose `conclusion` is `"failure"`.
+
+If no failed run exists on the current branch (empty result or all passing), widen
+the search to the 10 most recent runs across all branches:
+
+```bash
+gh run list --limit 10 \
+  --json databaseId,status,conclusion,name,headBranch,createdAt
+```
+
+If a failed run exists in the broader search, proceed with that run and note the
+branch it came from. If no failed run exists anywhere in the recent history, report
+that clearly and stop — there is nothing to triage.
+
+**Zero runs at all (not even queued) is a different problem from a failed
+run** — a dropped webhook event, not a code failure. If a push landed but no
+run was ever created for its head SHA, first confirm it isn't isolated to
+this push — check whether a different, unrelated PR pushed around the same
+time shows the identical gap. If so, it's likely a one-off delivery drop,
+not a repo config problem; a safe, reversible fix is an empty-commit push
+(`git commit --allow-empty -m "chore: retrigger CI"`) to fire a fresh event,
+rather than auditing Actions permissions or workflow triggers.
+
+### 2 — Fetch the failing job logs
+
+Pull only the logs from steps that failed:
+
+```bash
+gh run view <id> --log-failed
+```
+
+If that command returns nothing (the run was cancelled, or all steps are
+technically "successful" but a post-step failed), fall back to the full log:
+
+```bash
+gh run view <id> --log
+```
+
+Do not reproduce the entire log output — find and keep only the region around
+the first failure, typically the last 50–100 lines before the run aborted.
+
+### 3 — Map to the pipeline step
+
+`.github/workflows/ci.yml`'s lanes each run `node bin/verify.mjs --step <id>`
+against a step id from `bin/lib/verify-steps.mjs` — that file's `cmd` field
+IS the local reproduction command, so mapping a failing CI step to its local
+command is always: find the `## <step name>` line the log shows, match it to
+the step's `name` in `bin/lib/verify-steps.mjs`, and reproduce with that
+step's `cmd` array joined as a shell command (or just `node bin/verify.mjs
+--step <id>` directly). The step name usually appears verbatim in the log
+lines (e.g. `Run pnpm lint` or `##[error]...`).
+
+### 4 — Report the diagnosis
+
+Output a concise structured report — no prose padding:
+
+```
+## CI Triage — Run #<id>
+
+**Failed step:** <step name>
+**Reproduce locally:** <exact command, e.g. `node bin/verify.mjs --step lint`>
+**Root cause:** <one sentence>
+**Error excerpt:**
+<quoted lines from the log — enough to identify the file/rule/test>
+**Assessment:** <Real failure | Likely flake — explain why>
+```
+
+A "likely flake" is a transient runner issue: network timeout downloading
+dependencies, OOM on a large test run, a GitHub-side runner error, or a retry
+that would probably pass. Everything else is a real failure requiring a code fix.
+
+### 5 — Present solution options
+
+After the diagnosis, present 3–5 solution options in a separate
+`## Solution Options` section so the diagnosis stays readable on its own. For
+each option include: a one-line description, the exact command or change
+needed, and the main tradeoff. Do not apply any fix — leave the choice to the
+user.
+
+If triaging several failed runs in one pass, write the per-run reports to a
+file and keep the chat reply to a short summary table — don't paste every
+report inline.

package/templates/core/.claude/skills/typescript-guidance/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: typescript-guidance
+description: >-
+  Dual-mode TypeScript guidance skill. `research` mode answers a single
+  TypeScript/toolchain question from owner-normative upstream sources only
+  (typescriptlang.org, the devblog, microsoft/TypeScript releases,
+  nodejs.org type stripping, typescript-eslint.io, attw, publint). `refresh`
+  mode sweeps this project's whole TypeScript-facing surface — tsconfig,
+  eslint, packaging, and the test config/approach — against a living
+  tracker and produces a remediation plan. Use for /typescript-guidance,
+  "what does the TypeScript team say about X", "are we behind on
+  TypeScript", "is our tsconfig still current", or before changing a
+  compiler flag. Not how this project's config is wired today — that's
+  CLAUDE.md and the config files themselves.
+---
+
+# typescript-guidance
+
+One skill, two modes, sharing one allowlist
+(`references/typescript-sources.md`) so they can't drift apart. Pick the
+mode from how you were invoked: a specific question → `research`; a
+periodic or `/customize`-driven sweep → `refresh`.
+
+**Must only run in the main (hub) agent, never inside a subagent** — it ends
+in `EnterPlanMode` (refresh) or an `AskUserQuestion` (either mode,
+occasionally), neither of which a subagent can do.
+
+**No files are written by this skill itself** in research mode by default;
+refresh mode writes to exactly one file, the tracker, in Step 5.
+
+## Authority (read this before either mode)
+
+This skill has authority over **every TypeScript-facing file in the
+project** — `tsconfig.base.json`, `tsconfig.json`, `eslint.config.js`,
+`vitest.config.ts` (config **and** the testing approach itself, not just
+its config shape), `package.json`'s TypeScript-toolchain entries, packaging
+(`exports`, `check-exports.mjs`), and the toolchain steps in
+`.github/workflows/*.yml`. An interview-derived emphasis (from
+`/customize`'s kind-to-facet table) tells this skill which facet to research
+**most deeply**, never which facets it may or may not touch. A facet with
+low priority still gets swept; it just gets less dedicated attention per run.
+
+## Research mode
+
+1. **Scope the topic.** Read the topic from the invocation or the
+   surrounding task; at most **one** clarifying question, otherwise infer
+   and proceed. Derive **3–5 orthogonal facets** — one per Explore agent.
+   Derive a kebab-case slug for the optional Step 5 snapshot.
+2. **Fan out.** Read `references/typescript-sources.md` first, then spawn
+   **all agents in a single message**. Each brief carries: one facet; the
+   allowlist + GitHub caveat pasted verbatim; today's date; "do not stop at
+   the first matching source — fetch every distinct one"; "reject any
+   non-allowlisted domain outright and say so"; "you hold no write tool —
+   findings travel only in your response"; the findings format below; and a
+   ~8,000-character (~2,000-token) return cap. Always `subagent_type:
+"Explore"`, breadth `"very thorough"`.
+
+   Findings format, one block per source:
+
+   ```
+   SOURCE: <URL>
+   TIER: T1 | T2
+   CLAIM: <the specific claim, quoted or tightly paraphrased>
+   CONFLICT-WITH: <another SOURCE, if this claim contradicts it — omit if none>
+   ```
+
+3. **Aggregate & synthesize.** Read every agent's full inline findings —
+   digests are for triage, not synthesis. Assign `S1, S2, …` deduping; merge
+   agreement into single consensus points tagged with all supporting ids;
+   flag contradictions. Precedence when two sources disagree: T1 outranks
+   T2; within T1, a devblog release post outranks the Handbook (the Handbook
+   lags a release); nodejs.org is co-normative for the runtime boundary — a
+   genuine Microsoft/Node disagreement must be surfaced, never silently
+   arbitrated.
+4. **Ask a clarifying question only if genuinely needed** — only when two
+   current, equally authoritative sources conflict in a way that changes the
+   invoking task.
+5. **Offer an optional snapshot.** Default is inline-only. On explicit
+   confirmation, write `docs/research/typescript/<topic-slug>.md`, assembled
+   from Step 2's findings + Step 3's synthesis (not re-fetched), with a `>
+**Provenance** —` header naming today's date and the sources consulted.
+
+## Refresh mode
+
+1. **Read the tracker & establish anchors.** Read
+   `docs/research/typescript-refresh.md`, its header
+   `<!-- typescript-refresh: last-verified=<date> typescript-version=<version> -->`
+   — deliberately the newest **upstream** version last verified, distinct
+   from `package.json`'s own `typescript` pin, which this tracker exists to
+   check against, not restate. Missing tracker/facet → first run, `NEW`
+   only. Then read the allowlist file; state today's date; derive a run
+   directory `<scratchpad>/ts-refresh-<date>/`.
+2. **Build the delta.** `WebFetch` the devblog index and
+   `github.com/microsoft/TypeScript/releases`; extract entries newer than
+   the recorded version. An unreachable source is a coverage gap, not a
+   blocker. Pass this delta into all five briefs below — it is not a sixth
+   facet.
+3. **Fan out five fixed facets in one message** — fixed, not derived per
+   run, so sweeps stay comparable and the tracker stays diffable:
+
+   | Facet id                     | Emitted surface it validates                                                            |
+   | ---------------------------- | --------------------------------------------------------------------------------------- |
+   | `compiler-config-flags`      | `tsconfig.base.json`, `tsconfig.json`                                                   |
+   | `modules-esm-node-interop`   | `guard-js-extension.mjs`, `guard-no-commonjs.mjs`, the `import-x/extensions` rule       |
+   | `packaging-declaration-emit` | `check-exports.mjs`, the `exports` map, `isolatedDeclarations`                          |
+   | `lint-typing-rules`          | `eslint.config.js`'s preset composition                                                 |
+   | `testing-language-features`  | `vitest.config.ts`, the coverage gate, the choice of runner and testing approach itself |
+
+   Each brief carries: the facet row, Step 2's delta, the tracker's prior
+   claims for that facet, the allowlist + GitHub caveat + date anchor, the
+   exact filename to write (`<run-dir>/<facet-id>.md`), and this verdict
+   format per claim:
+
+   ```
+   CLAIM: <the tracker's prior claim, or "NEW" if none existed>
+   VERDICT: UNCHANGED | CHANGED | GONE
+   NOW: <the current upstream position, with tier>
+   REPO-IMPACT: <which emitted file(s) this affects, or "none">
+   ```
+
+   Return value: **write the full file, return only a compact digest**
+   (counts per verdict + every non-"none" REPO-IMPACT line + the file path).
+
+4. **Aggregate.** Read every scratchpad file in full. Four buckets:
+   confirmed drift with repo impact (verify each against the cited file
+   itself before trusting it — an agent can misread a page), guidance
+   changes with no impact, dead/moved URLs, coverage gaps.
+5. **Update the tracker in place** (not a new dated file) — this skill's
+   only write outside plan mode. Bump the header date + version, update
+   every checked claim's text/URL/date, add `NEW` sources, update the
+   outstanding-drift table.
+6. **`EnterPlanMode`** with a remediation plan, one section per
+   confirmed-drift item. No drift → skip plan mode, report a clean sweep,
+   still update the tracker.
+
+## Why this exists, separately from "how is our config wired"
+
+Research mode answers "what does upstream say about X." Nothing else in the
+baseline asks the inverse — "is what's already configured still what
+upstream recommends" — because every lint/typecheck/test gate is a closed
+loop checking the repo against its own prior decisions. A stale pin one
+major behind upstream passes every one of those gates cleanly; only a live
+sweep against the actual upstream surfaces it.

package/templates/core/.claude/skills/typescript-guidance/references/typescript-sources.md

@@ -0,0 +1,102 @@
+# Upstream TypeScript sources — the allowlist
+
+The single source list consulted by `typescript-guidance` in both modes.
+Editing this file is the one edit site when the tiering changes.
+
+## Domain allowlist
+
+Pass verbatim as `WebSearch`'s `allowed_domains`:
+
+```
+typescriptlang.org, www.typescriptlang.org, devblogs.microsoft.com,
+nodejs.org, typescript-eslint.io, arethetypeswrong.github.io, publint.dev
+```
+
+Plus **the official docs of a tool the project's interview actually
+selected** for testing/bundling (e.g. `vitest.dev`, a chosen bundler's
+docs) — this is what gives the `testing-language-features` facet a source
+family, since none of the domains above owns a test runner's own docs.
+
+Two of the fixed domains are **path-scoped within an otherwise broader
+domain**:
+
+- `devblogs.microsoft.com` hosts every Microsoft product's blog. Only
+  `/typescript/` paths are in scope here.
+- `nodejs.org` hosts the whole Node.js documentation site. Only `/api/`
+  paths — principally `/api/typescript.html` — are in scope here.
+
+## The two tiers
+
+**T1 — owner-normative.** A claim from here can be cited as-is.
+
+- `typescriptlang.org` — the Handbook, the tsconfig reference, the Modules
+  reference.
+- `devblogs.microsoft.com/typescript` — release announcements, the
+  authoritative record of breaking changes.
+- `github.com/microsoft/TypeScript` — releases, milestones, wiki Design
+  Notes.
+- `nodejs.org/api/typescript.html` — co-normative T1 for the
+  Node↔TypeScript runtime boundary (type stripping, `erasableSyntaxOnly`).
+  A disagreement across that seam is a genuine two-owner conflict to
+  surface, not a T1-vs-T2 subordination to resolve silently.
+
+**T2 — owner-adjacent / executable spec.** Citable, but state the scope
+limit.
+
+- `typescript-eslint.io` — rule semantics, and the exact composition of the
+  `recommendedTypeChecked`/`strictTypeChecked`/`stylisticTypeChecked`
+  presets.
+- `arethetypeswrong.github.io` — packaging correctness rules (dual-format
+  resolution, `exports`-map type resolution failure modes).
+- `publint.dev` — package-publishing correctness rules.
+- The selected test/bundler tool's own docs — behavior and current
+  recommendation for that tool specifically.
+
+**Explicitly out of scope.** Named here so an agent that finds one of these
+drops it and says so, rather than quietly substituting it for missing T1/T2
+coverage:
+
+- `github.com/tsconfig/bases` — actively maintained ecosystem consensus,
+  but consensus, not the owner's word.
+- Individual authors and their published material — no normative standing.
+
+## GitHub caveat
+
+`allowed_domains` filters by domain, not path, so a bare `github.com`
+allowance would let through any repo. Agents may include `github.com` and
+`raw.githubusercontent.com` in their search domains, but must **only cite or
+fetch URLs under `microsoft/TypeScript`, `microsoft/TypeScript-Website`, or
+`arethetypeswrong/arethetypeswrong.github.io`** — and drop any other GitHub
+result, however highly ranked.
+
+## First-class sources to enumerate directly
+
+Search ranking is not exhaustive — a recent devblog post or an individual
+tsconfig option page can rank poorly and simply not surface. Enumerate these
+directly rather than relying on search alone:
+
+- `https://devblogs.microsoft.com/typescript/` — the release-announcement
+  index; read as a **delta** from a known prior version in refresh mode.
+- `https://github.com/microsoft/TypeScript/releases` — the machine-readable
+  version list; cross-check the devblog against it.
+- `https://www.typescriptlang.org/tsconfig/` — the per-option compiler-flag
+  reference.
+- `https://www.typescriptlang.org/docs/handbook/modules/reference.html` —
+  the Modules reference (`nodenext`/`bundler` resolution modes, ESM/CJS
+  interop).
+- `https://nodejs.org/api/typescript.html` — Node's type-stripping page.
+- `https://typescript-eslint.io/users/configs/` — preset composition.
+
+## Coverage discipline
+
+Reject any non-allowlisted domain outright and say so in the report, rather
+than substituting a community blog, an individual author's material, or a
+Stack Overflow answer for missing T1/T2 coverage. If a facet turns up no
+qualifying source, that is itself a reportable finding (a coverage gap), not
+a reason to lower the bar.
+
+## Current-date anchor
+
+Every agent brief must state today's date explicitly — a `retrieved <date>`
+stamp otherwise depends on the spoke inferring the date itself, which is
+unreliable.