torben
18ae28f918
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
99 lines
5.7 KiB
Markdown
99 lines
5.7 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.
|
|
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 what an existing instance would have to do:
|
|
|
|
| Change | Part |
|
|
|--------|------|
|
|
| Fix, no interface change | `--patch` |
|
|
| New capability, backwards compatible | `--minor` |
|
|
| **Existing content must be migrated** | `--major` |
|
|
|
|
A `--major` bump additionally needs 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 otherwise, 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.
|
|
|
|
## 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`).
|