| name | sh-discover |
| description | Discover an existing project's conventions from real evidence and write them as the project spec: AGENTS.md + CLAUDE.md as the thin always-loaded entry, with detail under .superharness/spec/. Use when a project lacks AGENTS.md/CLAUDE.md, when asked to generate conventions ("生成规范", "discover conventions"), or when the spec is stale. |
Discover Conventions
Generate or refresh the project's AI-facing spec from evidence in the codebase. Two layers, kept distinct from learnings:
- Always-loaded entry (thin — every line costs tokens forever):
AGENTS.md + CLAUDE.md.
- Detail spec (read on demand):
.superharness/spec/, organized by topic.
Spec is project conventions. Learnings (.superharness/learnings/) are session lessons. Keep their responsibilities separate; the only bridge is promotion (see Refresh mode).
Scan (read evidence, don't guess)
- Manifests / configs: package.json / pyproject.toml / go.mod / Cargo.toml / pom.xml, lockfiles, linter / formatter / tsconfig, CI files.
- Existing docs: README, CONTRIBUTING, docs/, existing AGENTS.md / CLAUDE.md / editor rules.
- Code sample: 3-5 representative source files plus 1-2 tests; note naming, module structure, error handling, test style.
- Git:
git log --oneline -20 for the commit-message convention.
Write
-
.superharness/spec/ — the detail, evidence-only and lean. Start from guides/index.md as the entry (a short pre-dev checklist that links to the topic files that matter), then add only the topic files the evidence warrants (e.g. architecture/, api/, testing/), each short. Every line must be project-specific and evidenced; drop generic advice ("write clean code"). Do NOT scaffold empty TODO templates — write what the code actually does. Prefer one line over three.
-
AGENTS.md (max ~20 lines) — a one-paragraph project description, the real key commands, then exactly these pointers:
Read .superharness/spec/guides/index.md before writing code; follow its links for detail.Check .superharness/learnings/INDEX.md for past learnings; read a linked entry when relevant.When all development on a task is done, run the sh-test skill once: Spec Review, Code Review, then the test suite.
If AGENTS.md exists, only append the pointer lines that are missing. Never rewrite existing user content.
-
CLAUDE.md — exactly these imports (append only the missing ones if it already exists):
@AGENTS.md
@.superharness/spec/guides/index.md
-
.superharness/learnings/INDEX.md — create with a # Learnings header if missing.
Refresh mode
If .superharness/spec/ already exists: diff reality against it (recent commits, new configs, changed structure) and update only what drifted, keeping each file lean. Promotion is the one-way bridge from learnings to spec: fold learnings from .superharness/learnings/ that have hardened into stable conventions into the spec, then delete those learning files and their INDEX lines.
Finish by suggesting a commit of .superharness/, AGENTS.md, and CLAUDE.md.
