bootstrap

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bootstrap rules for an uncovered stack

Clawness ships corpus for ~29 domains. Open a session in a stack it has no rules
for and, beyond the always-on mandatory block, it adds little. A SessionStart note
says so once and deliberately does nothing else.

This skill is the **remedy**. The note is only the diagnosis: it fires before you
have said what you came for, so it cannot propose a session's worth of work. You
invoking this skill *is* the consent it couldn't ask for.

**This is a rule-authoring path, so the same discipline as `/clawness:refresh`
applies.** Nothing automatic may invoke it — not the note, not a hook, not your own
initiative mid-task. An earlier version of a related feature let the automatic path
write rules and it produced heaps of them, consuming a session opened for something
else.

**Say this before starting.** It takes a while, it writes files into the project,
and the rules it writes will govern every future prompt in this repo. Get an
explicit go-ahead, and tell them nothing is written until they approve the list.

## Argument

`/clawness:bootstrap [stack]` — the ecosystem to write rules for (`ruby`, `elixir`,
`haskell`, …). With no argument, use the uncovered stack the note named; if the
repo mixes several uncovered stacks, ask which one. **One stack per run** — a broad
pass over several is how a careful review becomes a batch of slop.

## Steps

### 1. Establish what the project actually is

Read enough of the codebase to know the stack, its version, and its shape — the
web framework or libraries in use, the build tool, the conventions the existing
code already follows. Rules must fit THIS project, not the language in the
abstract. A rule the codebase already obeys is noise; a rule that contradicts the
house style is worse.

### 2. Look up current conventions — from documentation, not memory

For each candidate rule, ground it in a **current official source**: the language
or framework's own docs, style guide, or security guidance. Record the URL you
used — it becomes the rule's `sources` and is what makes the rule auditable rather
than asserted.

**Not recalled knowledge.** A model's sense of "best practice" for a less-common
stack lags and drifts; writing rules from memory launders a guess into something
that then governs every prompt. If you cannot reach documentation for a point,
drop that rule rather than guess it.

### 3. Draft a SMALL starter set

Pick a domain name for the stack (`haskell`, `ruby`, …) — it does not need to be a
built-in Clawness domain. Project rules in a new domain retrieve as **cross-cutting**
(the label isn't in `_STACK_DOMAINS`, so no off-stack floor penalises them), so
they surface normally on matching prompts.

Write each rule in the full format, into `<project>/.clawness/rules/<domain>/<ID>.yml`:

```yaml
id: HS-SAFETY-001
domain: haskell
severity: warning          # error | warning | info
tags: [types, safety]      # single-word concept tokens (multi-word phrases never match)
triggers: [maybe, either, partial]   # words a matching prompt would contain
when: Handling a computation in Haskell that can legitimately fail.
rule: <what to do, precisely — one clear instruction, not a topic>
violation: <the wrong shape, concretely>
correct: <the right shape, concretely>
# Generated by /clawness:bootstrap for Haskell on <YYYY-MM-DD>.
```

Two things that matter:

- **No version stamp.** Do NOT add `applies_to`/`verified`/`sources` for an
  uncovered stack: the staleness check can only join on a `VERSION_WATCH` label
  (Next.js, Pydantic, …), and `clawness lint` *rejects* an `applies_to` key that no
  detector emits. Put the source URL in the header comment instead. (Covered
  frameworks that move a major are `/clawness:refresh`'s job — that path stamps.)
- **Cap the set at ~6 rules.** A judgment call, not a measurement: small enough
  that this stays a review. Prefer the handful that catch real, stack-specific
  mistakes over a generic checklist the language's own tooling already enforces. If
  more genuinely belong, propose the six that matter most and say what you left out.

### 4. Report the list and stop

Present each proposed rule — id, one-line intent, and source URL — as a table.
**Write nothing until the user approves.**

### 5. Write the approved rules, then validate

Write the approved files, then lint them through the bundled launcher, falling back to the
bootstrap's wrapper on older Claude Code (the `clawness` CLI ships with the plugin
but isn't on your PATH):

```bash
CLAW="${CLAUDE_PLUGIN_ROOT}/scripts/clawness-cli.sh"
[ -f "$CLAW" ] || CLAW="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/clawness/clawness-cli.sh"
bash "$CLAW" --rules-dir .clawness/rules lint
```

Note `--rules-dir` comes **before** `lint` (it's a global flag), and points at the
project rules so lint checks what you just wrote, not the shipped corpus. If neither
path exists, start a fresh session. (Editable/manual
installs may use `python -m clawness.cli --rules-dir .clawness/rules lint`.)

Lint catches malformed YAML, missing fields, non-UTF-8, and vague phrasing — it
does **not** catch a rule that is simply wrong or unhelpful. That guard is this
skill's research step and the user's approval, not the linter. Then:

- `bash "$CLAW" --rules-dir .clawness/rules query "<a prompt this should match>"`
  and confirm the new id appears. A rule that doesn't retrieve is dead weight.
- Tell the user the new rules load on the **next** session, not this one.
- Suggest committing `.clawness/rules/` — it is meant to be shared, unlike the
  handoff and the ledgers.

## Don't

- Don't run this unprompted, or fold it into another task. It is opt-in work.
- Don't write rules from memory. Ground each one in a source you actually read.

From fullymiddleaged/Clawness, MIT.

More from fullymiddleaged/Clawness