torbenandClaude Opus 5.5
f9056c04f7
Files changed: - .gitea/workflows/ci.yml - .gitignore - .vibe/hooks.toml - AGENTS.md - CHANGES.md - EVALS.md - INSTALL-MCP.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/architecture.md - docs/explanation/language-boundaries.md - docs/explanation/telemetry-and-evaluation.md - docs/how-to/README.md - docs/how-to/browse-with-obsidian.md - docs/how-to/capture-repository-docs.md - docs/how-to/export-guidelines.md - docs/how-to/ingest-a-source.md - docs/how-to/maintain-the-wiki.md - docs/how-to/query-the-wiki.md - docs/how-to/run-the-weekly-review.md - docs/how-to/set-up-the-mcp-server.md - docs/how-to/trace-and-score-sessions.md - docs/how-to/troubleshoot.md - docs/how-to/update-an-instance.md - docs/reference/README.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/instance-health.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/configuration.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-build/SKILL.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - instructions/setup-instance.md - instructions/upgrade-instance.md - reports/CONTRACT.md - tools/.coveragerc - tools/CONTRACT.md - tools/README.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/eval_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/evals/__init__.py - tools/chemenu/evals/scorecard.py - tools/chemenu/evals/trajectory.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_pipeline_l0.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
74 lines
4.0 KiB
Markdown
74 lines
4.0 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: dev-setup
|
|
description: Set up a clone of the origin repository for stack development - preflight, skills, the demo corpus and its persona, telemetry on - and use dist export as a build and test tool, never as a way to install an instance.
|
|
---
|
|
# Set up a development checkout of the stack
|
|
|
|
A clone of the origin repository is where the stack is developed. It is not an instance: it
|
|
carries a demo corpus that documents the stack itself, a demo persona in `USER.md`/`SOUL.md`, the
|
|
development material under `instructions/dev/` and `commonplace/`, and no
|
|
`.wikitool-release.json`. Instances are installed from releases
|
|
([setup-instance.md](../setup-instance.md)); nothing here produces one.
|
|
|
|
## When to run
|
|
|
|
- A fresh clone of the origin repository, before the first stack-dev session in it.
|
|
- A clone that was moved, or whose `tools/.venv` was removed - only step 2 again.
|
|
- Before testing a change to the install path itself (`setup-instance.md`, the preflight, the
|
|
release workflow) - step 5.
|
|
|
|
## Steps
|
|
|
|
1. **Clone** the origin repository. The tree is complete as checked out: `kb/`, `raw/`,
|
|
`USER.md`, `SOUL.md` and the filled `kb/CONVENTIONS.md` are committed here, unlike in an
|
|
instance.
|
|
|
|
2. **Run [bootstrap.md](../bootstrap.md)** - the preflight, then `tools/wikitool instructions
|
|
sync`. That publishes `stack-dev`, `stack-build` and `stack-close` along with the content skills;
|
|
all three exist only in this repository.
|
|
|
|
3. **Record the environment** (bootstrap.md step 5). Here it is worth the minute: which harness,
|
|
that `gitea-mcp` reaches the tracker and CI, which remote `publish` talks to. Every stack-dev
|
|
session reads it instead of asking.
|
|
|
|
4. **Know what differs from an instance before relying on a default.**
|
|
|
|
| Here | In an instance |
|
|
|---|---|
|
|
| No `.wikitool-release.json`: telemetry is **on** - the traces are the stack's measuring instrument ([telemetry-and-evaluation.md](../../docs/explanation/telemetry-and-evaluation.md#whether-it-runs-at-all)) | Telemetry is off until the operator turns it on |
|
|
| `USER.md`/`SOUL.md` describe a demo operator and persona | Written by the operator during setup |
|
|
| `tools/wikitool dist upgrade` refuses: there is no stamp to compare against. The checkout follows `main` with `tools/wikitool sync` | Updated with `dist upgrade --latest` |
|
|
| `instructions/dev/`, `docs/dev/`, `commonplace/` and `.gitea/` are present | Never shipped |
|
|
|
|
5. **Use `dist export` as a build and test tool.** It writes exactly the tree a release ships, so
|
|
it is how a change to the shipped surface is looked at before it is released:
|
|
|
|
```bash
|
|
tools/wikitool dist export <empty scratch folder> --dry-run
|
|
tools/wikitool dist export <empty scratch folder>
|
|
```
|
|
|
|
To replay the install path the way a user meets it, build the release tarball from that tree
|
|
the way `.gitea/workflows/release.yml` does (one top-level folder, a `.sha256` beside it) and
|
|
start the tree's `tools/preflight.sh` as the asset, from an empty folder, with
|
|
`--archive <tarball>` - the step "The distribution works as a fresh instance" in
|
|
`.gitea/workflows/ci.yml` is that replay and the reference for it. Keep scratch trees outside
|
|
this checkout.
|
|
|
|
## Decision points
|
|
|
|
- **Asked to set up an instance from this checkout** (`dist export` into the user's folder, or a
|
|
clone that "becomes" their wiki)? Neither is an install path. An instance is installed from a
|
|
release, by [setup-instance.md](../setup-instance.md); a stack state that has no release yet is
|
|
released first, or tested with the replay in step 5 and thrown away.
|
|
- **The demo corpus is in the way of a test?** Do not delete or rewrite corpus content to make
|
|
room: [corpus-policy.md](corpus-policy.md) says what may be changed and how. Use a scratch
|
|
export (step 5) for a clean tree instead.
|
|
|
|
## Scope
|
|
|
|
Not for operating an instance, and not for the release workflow itself (`docs/dev/development.md` for
|
|
humans, [version-parts.md](version-parts.md) for the version part). Not shipped: `dist export`
|
|
prunes `instructions/dev/` wholesale.
|