torbenandClaude Opus 5.5
d66a3f65f4
The seven explanation pages move to docs/explanation/ without a stub, DEVELOPMENT.md becomes docs/dev/development.md (translated to English), dist export leaves docs/dev/ out, docs verify rejects a file outside the five areas, and AGENTS.md states that the stack's human documentation is English. Required migration 9.0.0-docs-diataxis rewrites the old path in an instance's own kb/CONVENTIONS.md. Files changed: - .wikitool-kb.json - AGENTS.md - CHANGES.md - CLAUDE.md - DEVELOPMENT.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/knowledge-and-commitment.md - docs/explanation/language-boundaries.md - docs/explanation/model-and-effort-selection.md - docs/explanation/ownership-and-templates.md - docs/explanation/pipeline-rationale.md - docs/explanation/version-model.md - docs/explanation/why-gates-are-code.md - docs/how-to/README.md - docs/knowledge-and-commitment.md - docs/language-boundaries.md - docs/model-and-effort-selection.md - docs/ownership-and-templates.md - docs/pipeline-rationale.md - docs/reference/README.md - docs/tutorials/README.md - docs/version-model.md - docs/why-gates-are-code.md - instructions/CONTRACT.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-mode.md - instructions/gtd-weekly-review/SKILL.md - instructions/ingest-queue.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/migrations/9.0.0-docs-diataxis.md - instructions/upgrade-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/task_cmd.py - tools/chemenu/tasks/protocol.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_toc.py - types/type-guidance.md 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 (`EVALS.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.
|