@iowarp/clio-coder 0.4.6 → 0.4.8

package/skills/README.md

@@ -1,418 +0,0 @@
-# Clio Skills Marketplace
-
-Curated, version-controlled skills that Clio Coder's authors have reviewed and
-approved. This folder is the **marketplace catalog**, which acts as a publishing shelf rather than a
-runtime store.
-
-## Marketplace vs runtime
-
-Clio's engine discovers *runtime* skills from these roots (see
-`src/domains/resources/skills/loader.ts`):
-
-- extension roots
-- `~/.agents`, `~/.claude`, `~/.codex`, `~/.config/opencode`, `~/.copilot` → their `skills/` subdir
-- `<clio-config>/skills` (per-user)
-- project `.agents` / `.claude` / `.codex` / `.opencode` / `.github` → their `skills/` subdir (model-visible only when `integrations.projectResources.trustProjectImports` is true; untrusted by default)
-- `.clio-coder/skills` (per-project)
-
-This repo's `skills/` directory is **not** one of those roots, so nothing here
-auto-loads. That gap is deliberate.
-
-| | Runtime skill | Marketplace skill (here) |
-|---|---|---|
-| Location | a discovery root above | `skills/<category>/<name>/` in this repo |
-| Author | any user or harness | Clio authors, reviewed |
-| Provenance | none required | `clio-coder:` block with `registry-id` + `source-url` + `audit: pass` |
-| Auto-loaded | yes | no, as it must be installed |
-
-"Approved" is visible in the frontmatter: a maintainer set `clio-coder.audit: pass`
-and a `version`. A skill a user wrote themselves carries none of those fields.
-
-## Catalog
-
-The catalog is organized by theme: each skill lives at
-`skills/<category>/<name>/`. Skill names stay globally unique; the category
-folder is presentation and provenance, not a namespace.
-
-### `planning/` — from idea to committed intent
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`product-intent`](planning/product-intent/) | interview | A greenfield idea needs a problem-first product document with a falsifiable hypothesis and zero engineering decisions. |
-| [`prd`](planning/prd/) | interview | An idea must become a locked product spec via a phase-gated interview, ending in PRD.md plus milestone prompts. |
-| [`architecture`](planning/architecture/) | interview | An intent needs its engineering approach decided interactively: options, trade-offs, spikes, a high-level decision doc. |
-| [`backlog`](planning/backlog/) | workflow | A finished PRD/architecture doc must become real tracker tickets with verifiable acceptance criteria. |
-| [`tech-spec`](planning/tech-spec/) | workflow | A typed call-stack architecture handoff: contracts + execution flows, implementation-ready. User-invoked only. Provisional. |
-
-### `coding/` — building and searching code
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`tdd`](coding/tdd/) | discipline | Build or fix test-first: red → green at pre-agreed public seams, one vertical slice per cycle. |
-| [`prototype`](coding/prototype/) | workflow | A design question should be answered with clearly-marked throwaway code, then the verdict captured and the code discarded. |
-| [`ast-grep`](coding/ast-grep/) | workflow | A code search needs structure, not text: AST patterns, "X inside Y", or grep is too noisy. Test-first rule writing, search only. |
-| [`coding-standards`](coding/coding-standards/) | reference | TypeScript correct-by-construction standards: errors as values, parse don't validate, deep modules. Provisional. |
-
-### `git/` — commits, PRs, worktrees, conflicts
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`file-ticket`](git/file-ticket/) | workflow | Something noticed mid-session must become a tracker issue: capture evidence, dedup, compose, confirm, create via gh. |
-| [`fix-issue`](git/fix-issue/) | workflow | A tracker issue should be resolved: diagnose only the unknown, fix test-first, self-review against the issue's acceptance criteria. |
-| [`ship`](git/ship/) | workflow | Finished work leaves the machine: one atomic conventional commit referencing the issue, gated push, PR on explicit intent. |
-| [`worktree-create`](git/worktree-create/) | workflow | Stand up isolated worktrees for parallel branches: detected install/config/health-check, per-worktree verification. |
-| [`worktree-merge`](git/worktree-merge/) | workflow | Integrate finished worktree branches through a throwaway integration branch with per-merge tests and a full final gate. |
-| [`resolve-merge-conflicts`](git/resolve-merge-conflicts/) | workflow | A merge/rebase is stopped on conflicts. Resolves from both sides' reconstructed intent, validates, completes the operation. |
-| [`branch-closeout`](git/branch-closeout/) | workflow | Proves merged work on the canonical base, inspects and removes associated worktrees through Git, deletes local branches safely, and audits surviving repository refs. |
-
-### `research/` — scientific and literature work
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`arxiv-literature`](research/arxiv-literature/) | research | Searching arXiv, summarizing papers, comparing papers, or producing compact literature surveys while protecting main-agent context. |
-| [`scientific-debugging`](research/scientific-debugging/) | workflow | Debugging has stalled or produces wrong numbers, NaNs, or flaky results. Forces falsifiable hypotheses across fault classes and evidence-cited verdicts before any fix. |
-| [`experiment-protocol`](research/experiment-protocol/) | workflow | A benchmark, optimization, or numerical comparison needs success criteria locked before results exist. Pre-registers thresholds into the repo validation contract. |
-| [`scientific-modernization`](research/scientific-modernization/) | workflow | Established scientific software is being modernized, ported, rewritten, packaged, accelerated, or replaced. Locks an independent scientific oracle, staged compatibility evidence, and durable stewardship before release. |
-
-### `context/` — session state across boundaries
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`context-prime`](context/context-prime/) | workflow | A session begins and you need to load project state, the last handoff, and orientation before acting. |
-| [`context-handoff`](context/context-handoff/) | workflow | A session is ending and work continues in a new session or another agent. Writes the artifact `context-prime` reads. |
-
-### `workflow/` — shaping and stress-testing how work happens
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`grill-me`](workflow/grill-me/) | interview | A plan or idea needs stress-testing through a one-question-at-a-time interview before code is written. Ends with a decision log. |
-| [`cut-it`](workflow/cut-it/) | workflow | A plan, PRD, or milestone must become an executable sprint of dependency-ordered slices with done-when criteria. |
-| [`design-council`](workflow/design-council/) | workflow | A design decision has real tradeoffs and needs several composed expert perspectives that debate through read-only dispatched workers before code is written. |
-| [`workflow-distiller`](workflow/workflow-distiller/) | workflow | A workflow that just ran should become a reusable skill. Reconstructs it from the session record, interviews, checks overlap, gates on approval, then writes it following `skill-craft`. |
-
-### `meta/` — Clio operating on itself and its ecosystem
-
-| Skill | Type | Use when |
-|---|---|---|
-| [`skill-craft`](meta/skill-craft/) | reference | Writing, reviewing, or pruning any SKILL.md: invocation cost, trigger-only descriptions, completion criteria, progressive disclosure, and the pruning pass. |
-| [`find-skills`](meta/find-skills/) | workflow | A capability might exist as an installable skill. Searches with `clio-coder skills search`, browses the ecosystem read-only, and installs only through `clio-coder skills install`. |
-| [`clio-coder-dev`](meta/clio-coder-dev/) | discipline | Modifying Clio's own source in this repo; deciding whether a change stays local or becomes a contribution. |
-| [`clio-coder-test`](meta/clio-coder-test/) | reference | Writing or verifying changes to Clio against the real harness (contracts / smoke / boundaries). |
-| [`credentials`](meta/credentials/) | discipline | A task needs an API key, token, or facility credential. Verifies presence without exposing values, collects new secrets via hidden terminal input, and contains leaks. |
-| [`herdr`](meta/herdr/) | integration | The user asks to launch, drive, or inspect another agent or command in a Herdr pane — including a second Clio Coder instance. Requires `HERDR_ENV=1`. |
-
-Each SKILL.md may declare `allowed-tools` / `disallowed-tools`. After a skill
-loads, Clio enforces that declaration at tool admission for the rest of the
-session, across the operator's later turns, until another skill replaces it or
-the operator runs `/skill off` (a worker run keeps the run-scoped lifetime):
-calls outside the merged surface are blocked with reason code `skill_surface`,
-with `context` and `ask_user` always admitted. A skill can narrow its tool
-surface but never grant tools the host would not allow. See [Skill tool surface narrowing](../docs/architecture/safety-model.md#skill-tool-surface-narrowing)
-for the full semantics.
-
-## Install (activate a marketplace skill)
-
-`clio-coder skills install` is the bridge from marketplace to runtime. It copies a
-skill into a discovery root and stamps install provenance so Clio can load it.
-
-```bash
-# Project scope (default): copy into <repo>/.clio-coder/skills
-clio-coder skills install context-handoff
-
-# User scope: copy into the Clio config skills dir, available everywhere
-clio-coder skills install clio-coder-dev --user
-
-# Several at once, or a whole catalog group
-clio-coder skills install context-prime context-handoff --user
-clio-coder skills install --category git
-```
-
-Bare names resolve through the local marketplace (this catalog when run from
-the repo, `CLIO_CODER_SKILL_CATALOG_DIR`, or the skill-marketplace.json index); an
-existing local path always wins over a same-named marketplace entry.
-`--category` installs every marketplace skill in one catalog group and is the
-short form for the sets below; it reports each install separately and exits
-nonzero if any of them failed.
-
-### Which scope
-
-Scope is about where the skill is true, not about how much you like it. A
-skill that describes how *you* work belongs to your user config; a skill that
-describes how *this repository* works belongs to the repository, where a
-teammate cloning it gets the same behavior.
-
-| Set | Scope | Why |
-|---|---|---|
-| `context-prime`, `context-handoff` | user | The workflow is useful in every repo, while each handoff remains scoped to the project where it was written. |
-| `find-skills`, `skill-craft` | user | Discovery and authoring are things you do to your toolkit, not things a project does. A user install outranks copies in shared user compatibility roots. |
-| `credentials` | user | Credential handling is a personal-machine discipline; a repo does not get to define it. |
-| `clio-coder-dev`, `clio-coder-test` | project, in this repo only | They describe Clio's own source tree. Elsewhere they are noise. |
-| `--category git` | project, where `git-master` is used | Branch, PR, and worktree conventions are the repository's, and the recipe binds them by name. |
-| `--category research` | project, per project | An arXiv survey or a modernization oracle is scoped to the science being done, not to the person. |
-| `--category planning` | project | PRD and architecture output lands in the repo and is reviewed there. |
-| `--category coding` | project | `tdd` and `coding-standards` follow the language and the test seams of the checkout. |
-| `--category workflow` | either | `grill-me` and `cut-it` travel with the operator; `design-council` is worth pinning per project when the project has recurring design forks. |
-
-Collision precedence from lowest to highest is extension, shared user
-compatibility roots, the Clio user root, project compatibility roots,
-`.clio-coder/skills`, then an explicit CLI skill path. Project compatibility
-roots are model-visible only after the project-import trust opt-in; their
-collision rank is still above the user root.
-
-After install, confirm Clio sees it:
-
-```bash
-clio-coder skills list            # human view
-clio-coder skills inspect context-handoff # full metadata + provenance
-```
-
-Installed copies are frozen; refresh them from their `source-url` provenance
-with `clio-coder skills update <name>` or `clio-coder skills sync`. While developing a
-catalog skill, load it directly without installing:
-`clio-coder --skill skills/<category>/<name>/SKILL.md`.
-
-Uninstall is just removing the copy: `rm -r .clio-coder/skills/<name>` (or the
-user-scope equivalent). Installs never write outside `.clio-coder/skills` or the
-user config skills dir, both of which are gitignored / outside the repo.
-
-### Skill discovery and find-skills precedence
-
-Clio ships [`find-skills`](meta/find-skills/) so that discovery and installation
-both route through `clio-coder skills`. A community skill of the same name is
-commonly present in the compat roots (`~/.agents/skills`,
-`~/.claude/skills`) and drives the external `npx skills` installer, which
-bypasses Clio. Compat roots stay enabled, and the loader resolves name
-collisions by the precedence above. A user install beats the shared user
-compatibility copy. A project install beats both project and user
-compatibility copies. Install at the scope where the catalog copy must win:
-
-```bash
-clio-coder skills install find-skills --user
-clio-coder skills install find-skills --project  # strongest discovered project copy
-```
-
-## Publishing: the marketplace index
-
-`pnpm run skills:pin` writes two files. `registry.yaml` pins content hashes and
-is what drift is measured against. `skill-marketplace.json` is the published
-index: one entry per skill with `name`, `description`, optional `triggers`,
-`sourceUrl` (the skill's own `clio-coder.source-url`), `version`, `audit`, and
-`category`. It carries no hashes, because duplicating them into a second
-published artifact only creates a way for the two to disagree.
-
-A Clio install anywhere points at it and gets bare-name installs from this
-catalog:
-
-```bash
-export CLIO_CODER_SKILL_MARKETPLACE_INDEX=/path/to/skill-marketplace.json
-clio-coder skills search worktree      # entries show (index, v0.2.0, audit: pass)
-clio-coder skills install worktree-merge
-```
-
-Install then clones the repository named in that entry's `sourceUrl` and copies
-the skill out of it, so the index is only as live as the branch its URLs name.
-The catalog's `source-url` values all point at `main`; until a release branch
-lands there, an install through the index fails naming the repository, the
-branch, and the missing path. `pnpm run skills:check` fails if a skill's
-`source-url` stops ending with its catalog path, which is how a skill moved
-between categories cannot ship a stale pointer.
-
-## Frontmatter spec
-
-The frontmatter contract has two layers, and the split is the point:
-
-- **Core keys stay community-standard.** `name`, `description`, `version`,
-  `license`, and `allowed-tools` mean exactly what Claude Code and other agent
-  loaders expect. No Clio-specific key ever lives at the top level.
-- **Everything Clio-specific nests under one reserved `clio-coder:` mapping.**
-  Registry identity, provenance, audit and eval status, agent bindings, model
-  guidance — all of it.
-
-The invariant this buys: a Clio skill dropped into any `.claude/skills`
-directory loads and works in Claude Code, which ignores the `clio-coder:` block as
-an unknown key. Loaded by Clio Coder, the same file carries its full
-marketplace metadata. One file, no forks, no lossy export.
-
-Required shape for every catalog skill:
-
-```yaml
----
-name: <name>                  # lowercase, hyphens, matches the folder
-description: <one sentence>   # what it does, plus "Not for X; use Y" routing, <=1024 chars
-triggers:                     # the phrases a user types that should reach it
-  - <phrase>
-version: 0.1.0
-license: Apache-2.0
-allowed-tools:                # optional; community-standard tool narrowing
-  - read
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/<category>/<name>
-  audit: pass                 # pass | warn | fail | unknown; reset to unknown on install
-  provenance: designed        # designed | adapted | imported
-  origin: <url or project>    # required when provenance is not "designed"
-  eval-status: scenarios-recorded  # untested | scenarios-recorded | smoke-checked | eval-run
-  model-size: any             # any (runs on ~30B local models) | large
-  agents:                     # optional: shadow agents / recipes the body dispatches
-    - researcher
----
-```
-
-Field semantics inside `clio-coder:`:
-
-- `registry-id` names the audited catalog a skill claims membership of; it is
-  content, participates in the pinned hash, and survives installs.
-- `source-url` and `audit` are install-lifecycle fields: `clio-coder skills install`
-  rewrites `source-url` to the actual install source and resets `audit` to
-  `unknown` because auditing is a human decision. Both are provenance-stripped
-  before hashing.
-- `provenance` records how the skill came to exist: `designed` here for Clio,
-  `adapted` from an external skill (name it in `origin`), or `imported`
-  near-verbatim.
-- `eval-status` is honest test standing: `untested` (no scenarios),
-  `scenarios-recorded` (evals.md scenarios written, not yet executed),
-  `smoke-checked` (one representative scenario executed through
-  `clio-coder skills eval` and the transcript showed the skill loading and driving
-  its core behavior), `eval-run` (the full scenario set executed and passing;
-  record the date in evals.md when setting this).
-- `model-size` is body-quality guidance: `any` means the body is written to
-  the local-model bar (explicit, imperative, short steps, explicit stop
-  conditions) and runs on ~30B-class local models; `large` means the skill
-  leans on judgment or synthesis that degrades on small models.
-- `agents` records agent bindings: the agent surfaces the skill is written
-  for (`main`, `coder`, or a recipe name whose definition lists the skill)
-  and, for orchestration skills, the recipes the body dispatches. A harness
-  without those agents knows what degrades.
-- `provisional: true` marks a skill accepted into the catalog on trial: it
-  passed review but its fit for the ecosystem is still being judged, and it
-  may be revised or dropped without a deprecation cycle.
-
-`requires: [skill:<name>, ...]` stays top-level: Clio's loader consumes it for
-dependency warnings, and other harnesses ignore it like any unknown key.
-
-The deprecated nested `clio:` mapping and legacy flat keys (`registry-id`,
-`source-url`, `audit` at the top level) are still read as fallbacks for older
-installed copies. The catalog itself must use `clio-coder:`, and `pnpm run
-skills:check` enforces that.
-
-### Versioning policy
-
-`version` describes the skill as a working instrument. The registry separately
-hashes the normalized contents of `SKILL.md`; it does not hash sibling files.
-Move the version whenever the workflow an operator runs changes:
-
-| Change | Version |
-|---|---|
-| Body text, steps, completion criteria | minor bump |
-| `allowed-tools` / `disallowed-tools` / `requires` | minor bump |
-| `description` or `name` (what triggers it) | minor bump |
-| Bundled `references/`, `scripts/`, `evals.md` scenarios | minor bump |
-| `eval-status`, `audit`, `provenance`, `source-url` | no bump |
-| Catalog reorganization that moves the folder | no bump |
-
-Patch releases are for a correction that leaves the workflow identical, such as
-a broken link or a typo in a step. Nothing in this catalog is 1.0: a major bump
-is reserved for a skill whose triggers change enough that an operator relying on
-the old one would be surprised.
-
-Lifecycle metadata changes do not bump the workflow version. The normalized
-`SKILL.md` hash catches non-stripped frontmatter and body edits; install fields
-such as `source-url` and `audit` are stripped. A sibling `references/`,
-`scripts/`, or `evals.md` change is represented by the required version change
-inside `SKILL.md`, because sibling bytes are not hashed directly.
-
-## Claude Code interop
-
-The invariant is that a catalog skill dropped unmodified into `.claude/skills`
-loads and runs in Claude Code. Verified against Claude Code 2.1.231:
-`skills/git/ship` copied into a scratch project's
-`.claude/skills/`, invoked headlessly, loaded through the `Skill` tool and
-answered a question about its own body. The `clio-coder:` block is an unknown
-frontmatter key there and is ignored.
-
-**`allowed-tools` means the opposite thing in each harness, and that is the one
-finding that shapes this section.** In Clio it narrows: after activation, calls
-outside the declared surface are blocked with reason code `skill_surface`. In
-Claude Code it grants: the parsed list is merged into
-`toolPermissionContext.alwaysAllowRules.command`, which pre-approves those
-tools for the turn. Nothing is denied there for being absent from the list.
-
-Claude Code matches permission rules by exact string equality on the tool name,
-through a four-entry alias table (`Task`, `KillShell`, `AgentOutputTool`,
-`BashOutputTool`) with no case folding. Clio's tool names are lowercase
-(`read`, `bash`, `web_fetch`), so none of them match a Claude Code tool. A
-catalog skill's `allowed-tools` is therefore **inert** in Claude Code: it grants
-nothing, denies nothing, and the skill loads and runs with whatever surface the
-session already had.
-
-That inertness is the safe outcome, and it is why the catalog keeps Clio tool
-names rather than mapping them. Translating `bash` to `Bash` for
-Claude-compatibility would not restrict anything; it would silently add `Bash`
-to the always-allow rules of every session that loaded the skill. The same goes
-for a `clio-coder skills export --for claude` lane, so there is no such lane. To keep
-a well-meaning edit from introducing that, `pnpm run skills:check` fails on any
-`allowed-tools` entry that is not a Clio tool name in canonical lowercase.
-
-The rest of the surface, read from the same build:
-
-| Key | Claude Code behavior |
-|---|---|
-| `name`, `description` | Read; description is trimmed, and a non-string one is dropped with a warning. No length limit is enforced at load. |
-| `version`, `license` | Carried as metadata; `license` is unused. |
-| `disable-model-invocation` | Honored, and accepts `true` or the string `"true"`. Matches Clio. |
-| `allowed-tools` | Grants, as above. Accepts a YAML list or one comma/space-separated string, same as Clio. |
-| `disallowed-tools` | Not read. A Clio denial is not enforced there. |
-| `requires:` | Not read; ignored as an unknown key, so a dependency warning is Clio-only. |
-| `clio-coder:` | Not read; ignored as an unknown key. This is the invariant. |
-| Unparseable frontmatter | The per-skill load is wrapped in a bare catch: the skill is skipped silently, with no diagnostic. Clio warns instead. |
-| Size | No cap on SKILL.md. Clio rejects over 1 MiB and warns over 50 KiB, the activation delivery cap. |
-| `references/`, `scripts/` subfolders | Not enumerated at load time; they are files the body tells the model to read, which works in both. |
-
-Degradation summary for a catalog skill running under Claude Code: it loads,
-its body drives the workflow, and its tool narrowing does not apply. A skill
-whose safety argument rests on narrowing (`ast-grep` is search-only,
-`ship` cannot edit source) is advisory there and enforced here.
-
-## Contributing / approval
-
-A skill is "approved for the marketplace" when a maintainer:
-
-1. Reviews `SKILL.md` against [`skill-craft`](meta/skill-craft/) (trigger-only
-   description, checkable completion criteria, progressive disclosure, pruning
-   pass, evals present).
-2. Confirms it carries the frontmatter spec above with `clio-coder.audit: pass`.
-3. Sets / bumps `version`.
-
-Each skill ships an `evals.md` recording the baseline scenarios it was tested
-against (RED-GREEN per [`skill-craft`](meta/skill-craft/)). `clio-coder skills eval <name>`
-executes those scenarios instead of trusting the prose; the eval lane is the
-curation gate for this catalog, not an end-user feature.
-
-What the eval lane does and does not isolate, because a curation gate that
-overstates its own rigor is worse than none. Each of the three arms (baseline,
-treatment, judge) gets a private temp root with its workspace nested inside,
-so `..` from a workspace reveals only that arm and the arms are no longer
-adjacent, similarly-named siblings. The judge's copy of the treatment
-transcript has the loaded SKILL.md body replaced with a marker, so a bullet
-cannot pass on instructions the model merely read. But nothing confines a run
-to its workspace: the write boundary is a per-run tool policy, not something a
-harness can impose on a child process it spawns, and a full-auto arm has been
-observed writing outside its workspace. Eval numbers are evidence about a
-cooperative model, not an isolation guarantee. Run campaigns with `CLIO_CODER_*`
-pointed at throwaway directories.
-
-`pnpm run skills:pin` enforces this contract structurally: it refuses to pin a
-catalog where any skill is missing the required frontmatter, `audit: pass`, or
-its `evals.md`, declares a tool name Clio does not have, or carries a
-`source-url` that no longer ends with its catalog path. `pnpm run skills:check`
-(run in CI) fails on any drift between the catalog and either generated file,
-`registry.yaml` or `skill-marketplace.json`. Each pin covers the normalized
-`SKILL.md`, not the whole skill directory. Install-lifecycle stamps such as
-`installed-at` do not count as drift; body, version, and registry-identity
-edits do. A copy installed via `clio-coder skills install` therefore still
-verifies against its audited source at activation.
-
-A skill may declare typed dependencies with `requires: [skill:<name>, ...]`
-frontmatter; the loader warns at load time when a required skill is not
-installed, keeping composed workflows (for example a distilled skill that
-references `credentials`) auditable instead of silently incomplete.

package/skills/coding/ast-grep/SKILL.md

@@ -1,213 +0,0 @@
----
-name: ast-grep
-description: "Structural code search with ast-grep rules: finds code by shape when grep on text is too noisy, and never rewrites it. Not for plain string or filename lookups; use grep or find."
-triggers:
-  - structural code search
-  - ast-grep rule
-  - find calls with this argument shape
-  - find code inside a function
-  - grep returns too much noise
-version: 0.3.0
-license: Apache-2.0
-allowed-tools:
-  - bash
-  - read
-  - write
-  - edit
-  - grep
-  - ls
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/ast-grep
-  audit: pass
-  provenance: adapted
-  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/ast-grep
-  eval-status: scenarios-recorded
-  model-size: any
-  agents:
-    - main
----
-
-# ast-grep Structural Search
-
-Translate a structural question into an ast-grep rule, prove the rule on a
-tiny example, then scan the real codebase. Never scan first: an untested rule
-that returns nothing tells you nothing.
-
-Search only. Never use `--update-all` / `-U` / `--rewrite`; when matches need
-changing, report them and edit through the normal edit tools.
-
-## Arguments
-
-```text
-/skill ast-grep [--lang <language>] [--path <dir>] <structural question>
-```
-
-- `--lang`: tree-sitter language name (`javascript`, `typescript`, `python`,
-  `rust`, `go`, ...). Omit to infer from the files under `--path`.
-- `--path`: directory or file to scan. Omit to scan the project source
-  directory (`src/` when it exists, otherwise `.`).
-- Everything else is the question: what shape to find, what to exclude.
-
-The five steps below are the plan; do not open a task list for them.
-
-Examples:
-
-- `/skill ast-grep find async functions that await but have no try/catch`
-- `/skill ast-grep --lang python --path app/ find calls to open() outside a with block`
-
-Shell rules for every `bash` call in this workflow: one command per call,
-plain and direct. Never use `$(...)` or backticks; they trigger an approval
-gate that ends a headless run. Always pass rules through a file, never
-through `--inline-rules`, because `$VAR` metavariables inside shell quotes
-produce quoting errors that look exactly like non-matches.
-
-## Step 0 — Check the binary
-
-```bash
-ast-grep --version
-```
-
-If that fails, try the short alias, but verify it is really ast-grep:
-
-```bash
-sg --version
-```
-
-Only an output that starts with `ast-grep` counts. On many Linux systems
-`sg` is the unrelated shadow-utils "switch group" command and prints a
-usage error; that is NOT ast-grep. If neither binary is ast-grep, say so
-(`npm i -g @ast-grep/cli` or `cargo install ast-grep`) and stop. Do not
-fall back to text grep and present it as a structural result.
-
-Use the resolved binary name in every later command.
-
-## Step 1 — Pin down the question
-
-Before writing any rule, write in your reply: the target language; the
-structure to match; what must be included and excluded. If the request is
-ambiguous on any of these, ask one clarifying question. When running
-headlessly, state your reading of the ambiguity and proceed.
-
-## Step 2 — Write a minimal example
-
-Create a scratch directory inside the workspace and write the smallest
-code snippet that MUST match and, when exclusions matter, one that must
-NOT match:
-
-```bash
-mkdir -p .clio-coder/scratch/ast-grep
-```
-
-Then write `.clio-coder/scratch/ast-grep/positive.<ext>` and
-`.clio-coder/scratch/ast-grep/negative.<ext>` with the `write` tool. These
-are the rule's test fixture: one file that must match, one that must not,
-nothing more. Never write under `/tmp`, not even by shell redirection; a
-write outside the workspace needs an approval a headless run cannot give,
-and the call is refused.
-
-## Step 3 — Write the rule, simplest first
-
-Write `.clio-coder/scratch/ast-grep/rule.yml` with the `write` tool.
-Escalate only when the simpler form fails:
-
-1. `pattern` alone for direct shapes: `console.log($ARG)`.
-2. `kind` plus relational rules (`has`, `inside`) for context: "function
-   containing await".
-3. Composite rules (`all`, `any`, `not`) for logic: "has await but no
-   try-catch".
-
-Non-negotiable: every relational rule (`has`, `inside`) carries
-`stopBy: end`, or traversal stops at the first non-matching child and the
-rule silently under-matches.
-
-```yaml
-id: async-no-trycatch
-language: javascript
-rule:
-  all:
-    - kind: function_declaration
-    - has: {pattern: await $EXPR, stopBy: end}
-    - not:
-        has: {pattern: 'try { $$$ } catch ($E) { $$$ }', stopBy: end}
-```
-
-This example is verified against ast-grep 0.45 on JavaScript. When the
-question is this one, use it verbatim. Two facts it encodes that models
-guess wrong: tree-sitter JavaScript and TypeScript have no
-`async_function_declaration` kind (the `async` keyword is a token inside
-`function_declaration`; assert it with `pattern: 'async function $F($$$) { $$$ }'`
-when async matters), and an unknown `kind` fails the whole rule with
-`Kind ... is invalid` (exit 8); answer that error with the tree dump in
-Step 4, never with another guessed name.
-
-Full syntax (atomic, relational, composite rules, metavariables, `constraints`,
-`utils`): read `references/rule_reference.md` when the rule needs more than
-the three forms above.
-
-## Step 4 — Test against the example
-
-```bash
-ast-grep scan --rule .clio-coder/scratch/ast-grep/rule.yml .clio-coder/scratch/ast-grep
-```
-
-The rule must match the positive example and miss the negative one before
-you scan anything real. When it passes, go to Step 5. When it does not,
-debug in this order, changing the rule file with `edit`:
-
-1. Strip the rule to its simplest positive key; re-add parts one at a time.
-2. Confirm every `has`/`inside` has `stopBy: end`.
-3. Dump the tree to check node kinds; never guess a `kind` name:
-
-```bash
-ast-grep run --pattern 'async function f() { await g(); }' --lang javascript --debug-query=cst
-```
-
-(`cst` = every node; `ast` = named nodes only; `pattern` = how ast-grep
-parsed your pattern.) Pipe long dumps through `head -80`. Dump the tree
-only after a test has failed; a dump before the first test is a wasted
-turn.
-
-## Step 5 — Scan the codebase
-
-Simple one-node patterns skip the rule file:
-
-```bash
-ast-grep run --pattern 'console.log($ARG)' --lang javascript src
-```
-
-Rule-based scans:
-
-```bash
-ast-grep scan --rule .clio-coder/scratch/ast-grep/rule.yml src
-```
-
-Scan the requested path, not `.`, so your own fixture under
-`.clio-coder/scratch` does not show up as a match; if it does, drop those
-lines from the report. Add `--json` only when the output feeds further
-processing.
-
-Report matches as `path:line` with a one-line reading of each; do not paste
-raw JSON at the user. Done when the reported matches answer the Step 1
-question and false positives you noticed are either excluded by the rule or
-called out. Delete the scratch files last, naming each file. `rm -r` and
-`rm -f` are hard-blocked by the safety net, so:
-
-```bash
-rm .clio-coder/scratch/ast-grep/positive.js .clio-coder/scratch/ast-grep/negative.js .clio-coder/scratch/ast-grep/rule.yml
-```
-```bash
-rmdir .clio-coder/scratch/ast-grep
-```
-
-## Red flags
-
-- Scanning the codebase with a rule never proven on an example.
-- A `has`/`inside` without `stopBy: end`.
-- A guessed `kind` name instead of a `--debug-query=cst` dump.
-- Any rewrite flag: this skill only reads.
-- Treating shadow-utils `sg` as ast-grep because `command -v sg` succeeded.
-- Cleaning up with `rm -rf`, or writing fixtures under `/tmp`; both are
-  refused in a headless run.
-- Falling back to grep halfway because rule debugging felt slow; fix the
-  rule with Step 4, that is the job.