chemenu/instructions/dev/stack-mode.md

---
type: types/instruction.md
name: stack-mode
description: What changes when a session works on the stack itself rather than on wiki content - which rules stop and start applying, the three phases a work package moves through and the tracker state that hands each one over, where the dev-only procedures are, and why a model is chosen per session rather than per phase.
---
# Rules for a stack-development session

Shared by the three skills of the `stack-` family - `stack-dev` (design), `stack-build` (build)
and `stack-close` (closing). Each of them can be the first thing a session runs: `/stack-build #N`
after a `/clear` starts cold, with none of `stack-dev`'s context. So each skill loads this file at
its entry, rather than one of them carrying these rules for the other two.

**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, none of these skills should be present at
all; stack development happens in the origin repo instead (see AGENTS.md's routing line).

<!-- wikitool:toc -->
## Contents

- [The three phases](#the-three-phases)
- [What changes in this mode](#what-changes-in-this-mode)
- [Where the procedures are](#where-the-procedures-are)
- [Sessions and models](#sessions-and-models)
<!-- /wikitool:toc -->

## The three phases

A work package is one Gitea issue, and it moves through three phases. A skill is a unit of
procedure; a session is a unit of context and model. The two are deliberately not the same
thing: each phase ends in a **state in the tracker**, and the next phase starts from that state,
so every handover works either in the same session or after a `/clear`.

| Phase | Skill | Invoked by | Ends with (the handover) | What catches a mistake |
|---|---|---|---|---|
| 1 Design/triage | `stack-dev` | the harness on a matching task, or `/stack-dev` | the issue body is **ready** ([issue-tracking.md](issue-tracking.md) § Ready to build) | nothing mechanical |
| 2 Build | `stack-build` | **only** the operator: `/stack-build #N` | a **green CI run** on the published commit, body current | `pytest`, `docs verify`, `instructions verify`, CI |
| 3 Closing | `stack-close` | **only** the operator: `/stack-close` | body in its final state, issue closed | nothing mechanical |

`stack-build` and `stack-close` carry `disable-model-invocation: true` in their frontmatter, so in
Claude Code only the operator can start them. That is the point of the split: each phase change is
the moment the operator decides whether to continue in this session, `/clear` first, or start the
next session on a different model - and a skill the agent could invoke itself would take that
moment away again. `instructions sync` copies the frontmatter unchanged; the other harnesses
ignore the key, so there the skill's own prose is the only thing that holds the line.

**So no skill tells the agent to run the next one.** A phase ends with a fixed line naming the
slash command for the operator, and stops.

## 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 (§ Where the procedures are, below). 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).
- **A session that touches both stack code and wiki content** applies these 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.

## Where the procedures are

- [issue-tracking.md](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 the plan file** of every phase: kept current as the state
  moves, so an interrupted session leaves a body the next one can resume from, and rewritten to
  its final state before closing. It also defines when a body is ready to build. An issue
  labelled `status/incoming` is a human's stub, not a spec, and is **never implemented as it
  stands**. Read it before filing something for later, before editing or closing an issue,
  before picking up an incoming stub, or before deciding what to pick up next.
- [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 when the design names the part, and again
  before the bump.
- [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.
- [tracker-testing.md](tracker-testing.md) - how the task-tracker adapters are tested against a
  real Super Productivity and CalDAV server: the `live_tracker` suite, the profile procedure for
  a tracker of your own, the nightly workflow (which you dispatch yourself after touching the
  Super Productivity surface), what a red night means, and refreshing the recorded fixtures.
  Read it before changing an adapter under `tools/chemenu/tasks/`.
- [doc-pull-through.md](doc-pull-through.md) - which document makes a claim about a touched
  surface (a `wikitool` command, a stage's rules, an `AGENTS.md` rule/gate/invariant, a
  README-shaped human doc, a `docs/` page's reasoning) and therefore needs updating alongside
  the code, since `docs verify` never reads a cell's prose. Read it before publishing.
- [publish-and-ci.md](publish-and-ci.md) - the local checks, `publish`, and waiting for the CI
  run on the published commit. Read it whenever a phase publishes.
- [corpus-policy.md](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.
- [dev-setup.md](dev-setup.md) - setting up a clone of the origin repo for this work, what
  differs from an instance there (telemetry on, demo persona, no release stamp), and
  `dist export` as a build and test tool rather than an install path. Read it in a fresh clone,
  or before testing a change to the install path.
- [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.

More instructions are added here as stack-development needs come up - this list grows without
any of the three skills having to change shape.

## Sessions and models

**A model is chosen per session, never switched inside one.** Neither `/model` nor `/effort`
is offered mid-session: either change throws away the prompt cache for everything the session
has read so far, and Sonnet's smaller context window does not hold a build phase of this stack.
Where two phases should run on different models, the cut goes at a handover - `/clear`, then the
next phase's slash command in a session started on the right model - and the tracker state is
what carries the work across it.

Which model suits which phase, and the reasoning, is
`docs/model-and-effort-selection.md`.