torben/chemenu

1 Fork 0

Files

T

torben e4b2b6d9b1

CI / verify (push) Successful in 2m18s

Details

Release / release (push) Successful in 36s

Details

feat: preflight - prerequisites checked and tool paths recorded before wikitool runs; launcher refuses without it (#151 , POSIX half)

Files changed:
- .claude/settings.json
- .gitea/workflows/ci.yml
- .gitea/workflows/nightly.yml
- .gitea/workflows/release.yml
- .gitea/workflows/tracker-live.yml
- .github/hooks/wiki-trace.json
- .gitignore
- .vibe/hooks.toml
- AGENTS.md
- CHANGES.md
- EVALS.md
- INSTALL.md
- README.md
- VERSION
- instructions/bootstrap.md
- instructions/preflight.md
- instructions/setup-instance.md
- instructions/upgrade-instance.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/migrate_cmd.py
- tools/chemenu/config.py
- tools/chemenu/corpus_cache.py
- tools/chemenu/prerequisites.py
- tools/chemenu/search/ripgrep.py
- tools/chemenu/tests/conftest.py
- tools/chemenu/tests/test_dist_upgrade.py
- tools/chemenu/tests/test_doctor.py
- tools/chemenu/tests/test_preflight.py
- tools/chemenu/toolpaths.py
- tools/preflight.sh
- tools/prerequisites.txt
- tools/run_wikitool.py
- tools/trace-hook
- tools/wikitool

2026-10-01 05:52:55 +02:00

4.0 KiB

Raw Blame History

type, name, description

type	name	description
types/instruction.md	bootstrap	Prepare a fresh clone for work - run the preflight (tool paths and 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, wiki-status or gtd-weekly-review 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

Run the preflight (once per clone, and again after moving it) - see preflight.md. It records the tool paths in .wikitool-tools.json and creates tools/.venv; until it exits 0, tools/wikitool refuses to start:
```
tools/preflight.sh
```
On exit 42, show its output to the user verbatim and wait.
Publish the skills:
```
tools/wikitool instructions sync
```
Verify:
```
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.
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, 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.
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.
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.
Expect a lingering session-id WARN. A tools/wikitool doctor run at this point reports OK throughout except session-id: WARN - that check is scoped to the working session, not the clone, so a freshly bootstrapped checkout with no WIKITOOL_SESSION_ID exported yet always shows it. This is expected, not a Bootstrap gap: exporting it here would only be true for this one-off setup run, not for whichever session picks up the actual work next, in a new shell after step 6's restart. Run session-setup.md at the start of that session instead.

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, a longer procedure this one is a single step of.

4.0 KiB Raw Blame History

Bootstrap a fresh clone

When to run

Steps

Scope

4.0 KiB

Raw Blame History