torben
31662dc3ff
Files changed: - CHANGES.md - INSTALL.md - VERSION - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - tools/CONTRACT.md - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/version.py
117 lines
7.1 KiB
Markdown
117 lines
7.1 KiB
Markdown
---
|
|
name: stack-dev
|
|
description: Switch a session into tool-development mode - extending tools/wikitool, the compiler, the type schema, or the instruction/skill layer itself, instead of operating on wiki content. Use when the user asks to add a wikitool command, change a type-spec, fix or extend the compiler, or otherwise work on the stack rather than ingest/query/manage/lint the wiki.
|
|
---
|
|
|
|
# Stack Development Mode
|
|
|
|
**Purpose:** Recognize a session that is about the tool stack itself - `tools/wikitool`, the
|
|
type schema, the instruction/skill layer - rather than wiki content, and switch the rules that
|
|
apply accordingly.
|
|
|
|
**Trigger:** The user asks to add or change a `wikitool` command, extend the compiler, change a
|
|
type-spec, or work on `instructions/`/`types/`/`tools/` as code rather than as a place to run
|
|
`wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/`wiki-status` against.
|
|
|
|
**This directory is dev-only.** `instructions/dev/` is excluded wholesale by
|
|
`tools/wikitool dist export` - nothing here ever reaches a distributed instance, and there is
|
|
no restore path. If you are in a distributed instance, this skill should not be present at all;
|
|
stack development happens in the origin repo instead (see AGENTS.md's routing line).
|
|
|
|
## What changes in this mode
|
|
|
|
- **Source-binding does not apply to code.** AGENTS.md invariant 3 ("never file an unsourced
|
|
answer into the wiki") governs `kb/` content, not the code you write to extend the stack.
|
|
Ordinary software-engineering judgment applies to `tools/chemenu/*.py`, `types/*`,
|
|
`instructions/*` - it does not need a `raw/` source or a citation.
|
|
- **Test and review conventions from `instructions/dev/` apply instead**, once written down
|
|
there (step 2 below lists what currently exists). Until a given convention has its own
|
|
instruction file, follow the existing test files' own patterns
|
|
(`tools/chemenu/tests/`) rather than inventing a new one silently.
|
|
- **Everything outside this directory still applies.** The tool error contract, the gates, and
|
|
"never hand-edit generated files" (AGENTS.md invariants 1, 5-8) are about how the tool
|
|
behaves at runtime, not about developing it, but they still bind normal session conduct
|
|
(e.g. still use `tools/wikitool publish`, still respect the gates, when the session also
|
|
touches wiki content).
|
|
|
|
## Steps
|
|
|
|
1. **Confirm the mode.** If the task is ambiguous between "extend the tool" and "operate the
|
|
wiki", ask rather than guess - the two have different rules for the same directories.
|
|
2. **Consult `instructions/dev/` for the concrete procedure.** Currently:
|
|
[commonplace-kb.md](../commonplace-kb.md) - vendored knowledge base on agent context
|
|
engineering, memory and deploy-time learning; consult before a design decision in those
|
|
areas.
|
|
[issue-tracking.md](../issue-tracking.md) - open work lives in Gitea issues, one per work
|
|
package, labelled `prio/1..3` and `size/XS..L`. There is no `TODO.md`. Read it before
|
|
filing something for later, or before deciding what to pick up next.
|
|
[testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately
|
|
empty machine; what the autouse fixture already neutralizes, and what a test still has to
|
|
establish itself. Read it before adding or changing a test.
|
|
[version-parts.md](../version-parts.md) - which part a change bumps: the drop-in test, the
|
|
catalogue of breaks that cross the compatibility boundary with `kb/` untouched, and what to
|
|
put in front of the user before a breaking bump. Read it before step 3.
|
|
More instructions are added here incrementally as stack-development needs come up - this
|
|
list grows without needing this skill file to change shape.
|
|
3. **Raise the version, if the change ships.** A change under `tools/`, `types/`,
|
|
`instructions/`, `AGENTS.md` or a `CONTRACT.md` reaches every future instance, so it needs a
|
|
version and a changelog entry:
|
|
|
|
```bash
|
|
tools/wikitool version bump --patch --title "<what changed>"
|
|
```
|
|
|
|
Never edit `VERSION` or the entry's heading by hand - `bump` writes both, and `docs verify`
|
|
fails a tree where they disagree. Pick the part by whether the new version is a **drop-in
|
|
replacement** for the old one - not by whether content has to be migrated:
|
|
|
|
| Change | Part |
|
|
|--------|------|
|
|
| Fix, no interface change | `--patch` |
|
|
| New capability, still drop-in in both directions | `--minor` |
|
|
| **Not a drop-in replacement** - any hand-work by the user or a migration script, or a downgrade that no longer works | `--major` |
|
|
|
|
Content migration is one way to land in the last row, not the definition of it: a rename of
|
|
the update path, the artefact, an import name, a flag or an envvar breaks a swap with `kb/`
|
|
entirely untouched. The full test, the catalogue of such breaks, and what to put in front of
|
|
the user first are in [version-parts.md](../version-parts.md) - **read it before choosing
|
|
`--major`.**
|
|
|
|
A `--major` bump therefore needs two things recorded. `--breaking "<what stops working>"`
|
|
is required on every boundary-crossing bump; on top of it, a migration document for the new
|
|
version - written per [migrate-corpus.md](../../migrate-corpus.md) - or
|
|
`--no-migration "<reason>"` when no content actually has to change. `bump` refuses without
|
|
either, and so does `docs verify`: an instance learning that it must migrate, with nothing
|
|
telling it how, is a dead end.
|
|
|
|
Then write the entry's body - `bump` deliberately leaves it empty, the same way `new` leaves
|
|
the prose.
|
|
|
|
Prose-only changes (`README.md`, `INSTALL.md`, `EVALS.md`) and the workflows under `.gitea/`
|
|
do not need a bump - CI's version gate is scoped to what changes behaviour.
|
|
|
|
4. **Verify before publishing.** `tools/wikitool docs verify`, `tools/wikitool instructions
|
|
verify`, and the relevant `pytest` run in `tools/` - the same checks any stack change must
|
|
pass, run explicitly rather than assumed. CI (`.gitea/workflows/ci.yml`) runs these plus a
|
|
full `setup-instance.md` replay against a fresh `dist export`; a push to `main` that moves
|
|
`VERSION` additionally triggers a tagged release. **CI does the tagging** - a session never
|
|
creates a tag, which is what keeps AGENTS.md invariant 5 intact.
|
|
|
|
## Decision points
|
|
|
|
- **Touches both stack code and wiki content in one session?** Apply this skill's rules to the
|
|
code changes and the normal content skills' rules to the content changes - they are not
|
|
mutually exclusive within a session, only per change.
|
|
- **The change turns out not to be a drop-in replacement?** Do not bump across the boundary on
|
|
your own initiative. Every existing instance pays for a breaking change once, by hand, so the
|
|
user decides whether it is worth that: show them what breaks, what an instance has to do about
|
|
it, and the alternatives (avoid the break with a shim, defer and batch it with the next one,
|
|
or split it behind a deprecation window), then recommend one and wait for a go-ahead.
|
|
[version-parts.md](../version-parts.md) step 4 has the full shape.
|
|
|
|
## Scope
|
|
|
|
Not for wiki content work - use `wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/
|
|
`wiki-status` for that. Not for setting up a new instance (`instructions/setup-instance.md`) or
|
|
a fresh clone of this repo (`instructions/bootstrap.md`).
|