torbenandClaude Opus 5.5
d8224ee2ab
stack-build and stack-close carry disable-model-invocation, so each phase change is the operator's slash command; no skill offers a mid-session /model or /effort switch. Mode rules and the phase table move to instructions/dev/stack-mode.md, publish and CI waiting to instructions/dev/publish-and-ci.md, the ready definition to issue-tracking.md. Files changed: - AGENTS.md - CHANGES.md - DEVELOPMENT.md - README.md - VERSION - docs/model-and-effort-selection.md - instructions/CONTRACT.md - instructions/dev/commonplace-kb.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/issue-tracking.md - instructions/dev/publish-and-ci.md - instructions/dev/stack-build/SKILL.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/stack-mode.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - tools/chemenu/commands/git_publish.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_instructions_cmd.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 (`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/`, `commonplace/`, `DEVELOPMENT.md` 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 (`DEVELOPMENT.md` for
|
|
humans, [version-parts.md](version-parts.md) for the version part). Not shipped: `dist export`
|
|
prunes `instructions/dev/` wholesale.
|