name: repo-kickstart
description: Use when bootstrapping a repository — greenfield or brownfield — into Uhstray's standard development conventions, OpenSpec, and the two-store memory setup. Idempotent and non-destructive: safe to re-run, never overwrites existing docs. Triggers on "repo kickstart", "bootstrap this repo", "set up our conventions", "conform this repo", "initialize plans/openspec/memory", "initialize this repo for openspec and memory", "set up two-store memory here", "index this repo and create its memory bank".
repo-kickstart
Bootstraps any repo into Uhstray's standard development conventions:
convention files, the planning tree, OpenSpec, the two-store memory
architecture, and the wiring between OpenSpec and the stores — no companion
document and no second skill. Works whether buhhdy authors the files directly or
dispatches this to a sub-agent; everything beyond this file (all templates, the
OpenSpec/memory/CodeRabbit/branch-protection mechanism, the store map, the report
format) lives in reference.md.
The artifacts it emits teach the repo how to use both systems, so the setup
outlives the session that ran it.
Golden rule: detect before you write. Read any existing file fully before
touching it. Never destroy content — integrate. Confirm-first on every
brownfield merge. Skipping a step because a prerequisite is missing is not
"done" — report it in the checklist and (where the task says) record the gap.
Order of operations
Run in order; each item is a detect → act-or-report cycle. A ✅ "already
conforming" per item is the desired result on huhhb and on any re-run.
0. Preflight
- Confirm you are at a git repo root (
git rev-parse --show-toplevel).
- Classify greenfield vs brownfield — does any of
README.md, AGENTS.md,
docs/ already exist with real content?
- Detect the stack (
package.json / pyproject.toml / go.mod /
Cargo.toml / pom.xml / …). It feeds AGENTS/ARCHITECTURE context, the
OpenSpec config.yaml context, .cbmignore, and CodeRabbit's language tools.
- Derive the three names (table in
reference.md §0): STORE_ID = the repo
directory name · BANK_ID = directory name + a hash of canonical
identity (a bare directory name silently merges two repos called app into
one bank) · the graph project = the tool's own lossy derivation from the repo
path. Three different strings — mixing them up is the most common failure
here, and the graph one needs an identity check before you index, not just
before you delete.
- Probe every prerequisite and record what's missing —
openspec, the graph
tool (including repo-inside-CBM_ALLOWED_ROOT containment), the experience
store, Honcho. Each degrades to skipped — <reason> in the checklist plus a
recorded gap; none of them fails the run, and none is a silent pass.
Probe the experience store, never assume its endpoint (commands in §0).
Installing/binding a server is machine scope — not this skill's job. Name
the remedy (two-store-memory-setup) instead of shrugging.
- Detect existing state before deciding you're initializing. An OpenSpec root
(house convention:
plans/development, not the repo root — also check
openspec store list), an existing index or bank, and every memory store
already on disk.
- Conformance is per artifact, never per repo. "This repo already has an
OpenSpec root" does not mean the run is done — an adopted repo can be
missing
plans/product/README.md or the AGENTS.md memory block forever if you
short-circuit on the first thing you find. Check each artifact in §1–§5
independently: present → ✅ and leave it exactly as it is; missing →
create it. Never re-init, never overwrite, never delete.
1. Convention files (templates in reference.md)
Create if missing; on brownfield, propose a merge, don't overwrite.
- README.md — entry point; links
AGENTS.md, KICKSTART.md,
ARCHITECTURE.md, and plans/. Brownfield: add a "Project conventions"
links section, keep their prose.
- AGENTS.md — the canonical agent operating instructions (conventions,
layout, review pipeline). Its memory section is where the wiring persists:
the store map in brief, the archive→retain convention, the drift check, and the
identifier→domain translate step. Template in
reference.md §1; it belongs
here, not in CLAUDE.md.
- CLAUDE.md — a one-line pointer to AGENTS.md. If a full CLAUDE.md
already exists, leave it and offer to slim it — never clobber.
- KICKSTART.md — human + agent onboarding: setup, how to run, how to
develop here, where plans live.
- ARCHITECTURE.md — current-state architecture; links
plans/architecture/.
2. Planning tree
plans/development/00-implementation-plan.md — seed from the canonical
living-index template in skills/openspec-conformance/templates/ (5-column table:
Change · Title · Status · Owner · Links — the exact shape promote-adr.ts
reads/writes; do not diverge or promotion breaks).plans/development/README.md and plans/architecture/README.md — one short
README each, saying what belongs there.plans/product/README.md — one short README (template in reference.md);
inception artifacts land here only when Workflow 0 is explicitly run —
seeding the dir is standard, using it is opt-in, never a mandate.
3. OpenSpec (store registration — owned by openspec-conformance)
openspec-conformance is the single source of truth; run its Setup (full
commands + house rules: there and in reference.md). In short: openspec init --tools none inside plans/development (skip if its openspec/config.yaml
exists), then openspec store register plans/development --id <repo> --yes —
once per machine, idempotent — registering plans/development as the OpenSpec
root (no symlinks). Commit the resulting .openspec-store/store.yaml, set
config.yaml context: from the stack, and openspec validate --all --store <repo> — report the result (a fresh store is a status, not a failure).
From the repo root, OpenSpec commands need --store <repo>.
context: also carries the memory routing (block in reference.md §3) — the
bank id, and that structure goes to the graph while rationale goes to the bank.
That field reaches the model whenever OpenSpec authors an artifact, so it is what
makes proposals get written with both stores in view. This is the wiring; without
it the repo has two systems rather than one workflow.
4. Memory kickstart — two-store, owned by THIS skill
Two routed stores plus Honcho (mechanism and every worked-around defect in
reference.md §4); registry-free — this skill does not track or register
conformance anywhere. repo-kickstart performs this itself and no longer
delegates to memory-onboarding. Hard rule, unchanged in force: plans/
holds planning/architecture/development/specification DOCUMENTS — no memory of
any kind is ever written under plans/. Experience goes to the bank, structure
to the graph, instructions to AGENTS.md.
- codebase-memory-mcp — the structure store.
.cbmignore written before
indexing (secrets pass included) → index with persistence=true → prove
git check-attr merge -- .codebase-memory/graph.db.zst prints merge: ours →
commit the artifact. Each of those steps works around a defect that fails
silently; §4.1 states what breaks if you skip it. This is a new capability —
nothing in this skill did it before.
- Hindsight — the experience store. One bank per repo,
bank_id derived per
§0 — directory name plus a hash of canonical identity, never the bare
directory name, which silently merges two repos called app into one bank.
verbatim extraction in its own call, retain_mission in
another — both are write-only, so re-apply them every run rather than trying
to detect them — then a project charter: prose about purpose, constraints and current
state, never an inventory (inventories are the graph's job). Write with
sync_retain — an async receipt is not a verified write.
- Honcho (team memory) — this skill reads the existing config and reports;
it never configures a server, installs anything, or runs an
init.
Credentials come from the environment (HONCHO_URL / HONCHO_API_KEY /
HONCHO_WORKSPACE) — never write them into the repo. Three states, not two
(§4.3): honcho mode needs a reachable server and @honcho-ai/sdk
installed; local mode needs no server and is configured, not missing;
unconfigured reports skipped. None of the three fails the run.
.claude/memory/ — retired from routing, data kept. Never delete, move or
migrate it. This skill no longer seeds the store or writes records into it;
repo-memory and memory-onboarding still own it and remain correct on direct
invocation (§4.6 — state that ownership split in the report).- Activate the repo's git hooks (still seeded):
.githooks/ post-commit
capture + pre-commit record lint, then git config core.hooksPath .githooks.
The per-commit journal under .claude/memory/wip/ is a staging buffer, not a
store — now the draft material for the PR/archive retain, deleted on
consolidation.
- Seed the kickstart outcome as one
sync_retain into the bank — what this
run actually did. A re-run that changed nothing retains nothing.
5. Review tooling
.coderabbit.yaml — generate from the template in reference.md, adapted
to the detected language(s). (There is no repo config to copy from — author
from the schema.)- Branch protection —
gh api repos/{owner}/{repo}/branches/{branch}/protection.
If absent, do not configure it silently: emit the exact gh commands for
the human (in reference.md) and record the gap in
plans/development/00-implementation-plan.md. Required reviews on the default
branch are a precondition for pr-shepherd.
6. Verification checklist
End by printing the pass/fail table (format in reference.md §7): convention
files present, plans tree, OpenSpec validates + its context: wiring, both memory
stores verified by evidence (node/edge counts · check-attr printing
merge: ours · a verbatim round-trip that brings a rejected alternative back —
the mode itself is write-only · a domain-language recall that actually returns the
charter), capture hooks active, Honcho scoping,
CodeRabbit config, branch-protection status. Also state which skill owns which
store and list every recorded gap.
Branch protection is expected red with instructions on a fresh repo — that is
a pass for the run, as is any ⚠ skipped — <reason> row whose gap was recorded.
A row you could not verify is reported honestly, never optimistically.
Idempotency & non-destruction (never skip)
Detect existing state first: present + conforming → ✅ "already conforming",
change nothing — a second consecutive run must be a no-op. Never fabricate a
checklist result (not run / not resolvable → say so). Non-destruction is the
Golden Rule above: never overwrite content you didn't just create; propose
merges confirm-first.
The rationalization table and red-flags are in reference.md — read them
before you start authoring.
