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