chemenu/instructions/dev/stack-dev/SKILL.md

name, description

name	description
stack-dev	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 - vendored knowledge base on agent context engineering, memory and deploy-time learning; consult before a design decision in those areas. issue-tracking.md - open work lives in Gitea issues, one per work package, labelled area/, kind/, prio/ and size/. There is no TODO.md. The body of the issue you are working on is this session's plan file: keep it current as the state moves, so an interrupted session leaves a body the next one can resume from, and rewrite it to its final state before closing. Both halves bind; the second is step 5 below. Read it before filing something for later, before editing or closing an issue, or before deciding what to pick up next. 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 - 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. corpus-policy.md - what "curated enough" means for the shared demo/testbed kb/, the measurable floors that define it, and what a reactive fix may and may not do to corpus content. Read it before judging whether the corpus can exercise a change, or before any fix that would touch kb/ content. 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:

   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 - 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 - 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.

5. Close the issue with a body rewrite, not a comment. The last act of a session that finished a work package, and the one most easily skipped: by here the change is published and the issue feels done. It is not. The body is the version everyone reads afterwards and nobody revisits, so it is the one place the debt comes due at the worst moment.

   Rewrite it to its final state first, then close. The test is what a reader who opens the closed issue tomorrow would conclude:

   • every acceptance criterion ticked, or struck with the reason it was dropped
   • proposals that were decided read as decided; a "to decide" section has become the decision and its reasoning
   • nothing left in the present tense about a defect that no longer exists
   • what was verified is named - which checks ran, which CI run - not a commit hash alone

   Then one short comment naming what changed against the previous state, and nothing else.

   A closing report in a comment does not satisfy this, however thorough: it reads as complete to whoever writes it and leaves a body still phrased as open work. Nothing mechanical catches it - wikitool does not know this tracker exists and must not learn it, since it ships to instances that have no board - so this step is the only enforcement there is. #44 and #45 both closed exactly this way, the second an hour after the rule was written. issue-tracking.md step 7 has the full shape.

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 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).