torben
18ae28f918
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: bootstrap
|
|
description: Prepare a fresh clone for work - create the tools venv and publish the skills into the harness directories, which are generated and not committed.
|
|
---
|
|
|
|
# Bootstrap a fresh clone
|
|
|
|
`.agents/skills/` and `.claude/skills/` are generated copies of the skill directories under
|
|
`instructions/`, and both are gitignored. A fresh clone therefore has no skills at all until
|
|
they are published: the agent harness will not offer `wiki-ingest`, `wiki-query`,
|
|
`wiki-manage`, `wiki-lint` or `wiki-status` before this runs.
|
|
|
|
## When to run
|
|
|
|
- After cloning the repository.
|
|
- After `instructions/<name>/SKILL.md` is added, renamed, or edited.
|
|
- Whenever `tools/wikitool instructions verify` reports a missing or drifted copy.
|
|
|
|
## Steps
|
|
|
|
1. **Create the tool environment** (once per clone):
|
|
|
|
```bash
|
|
cd tools
|
|
python3 -m venv .venv
|
|
.venv/bin/pip install -r requirements.txt
|
|
cd ..
|
|
```
|
|
|
|
2. **Publish the skills:**
|
|
|
|
```bash
|
|
tools/wikitool instructions sync
|
|
```
|
|
|
|
3. **Verify:**
|
|
|
|
```bash
|
|
tools/wikitool instructions verify
|
|
```
|
|
|
|
Expected: `OK`. If it reports drift, re-run `sync` - the source under `instructions/` always
|
|
wins, and a copy is never edited directly.
|
|
|
|
4. **Check for personalization.** A clone predating the personalization files has no
|
|
`USER.md`/`SOUL.md`, and `tools/wikitool doctor` reports `personalization: FAIL` for it.
|
|
That is a one-off catch-up, not a bootstrap step that repeats: run **only** the
|
|
Personalization step (6) of [setup-instance.md](setup-instance.md), not the whole
|
|
procedure - this clone already has its git repo, author identity and content. A clone that
|
|
already carries both files needs nothing here.
|
|
|
|
5. **Offer to record the environment.** `ENVIRONMENT.md` is gitignored, so a fresh clone never
|
|
has one, and every session in it re-asks which harness is in use, which MCP servers are
|
|
reachable, and which remote `publish` talks to. Copy `ENVIRONMENT.md.template` to
|
|
`ENVIRONMENT.md`, fill in what is already known from this clone (`git remote -v`, the
|
|
harness you are running in, `tools/wikitool instructions list`), ask the user for the rest,
|
|
and drop the `wikitool:template-unfilled` line.
|
|
|
|
**Optional, and it stays optional.** Skip it and everything still works - `doctor` reports
|
|
`environment: absent (optional)`, not a failure. Skip it *silently*, though, and the next
|
|
session pays for it again. Never guess an entry: a wrong remote or an MCP server that is not
|
|
there is worse than the empty section it replaced, because it gets believed.
|
|
|
|
6. **Restart the agent session** if it was already running. Harnesses read the skill
|
|
directories at startup, so skills published mid-session are not picked up.
|
|
|
|
## Scope
|
|
|
|
This does not apply to anything under `kb/`, `raw/` or `reports/`; those are committed and
|
|
present immediately after a clone. If the wiki content looks wrong after cloning, that is a
|
|
lint question, not a bootstrap one.
|
|
|
|
This also does not apply to a fresh instance created via `tools/wikitool dist export` - it has
|
|
no git history, no author identity, and no generated indexes yet. That is
|
|
[setup-instance.md](setup-instance.md), a longer procedure this one is a single step of.
|