chemenu/instructions/dev/stack-mode.md

type, name, description

type	name	description
types/instruction.md	stack-mode	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).

Contents

• The three phases
• What changes in this mode
• Where the procedures are
• Sessions and models

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 § 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 - 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 - 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 - 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 - 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 - 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 - the local checks, publish, and waiting for the CI run on the published commit. Read it whenever a phase publishes.
• 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 - 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 - 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. What every phase records, so that reasoning can be checked against practice, is stack-close's handover (its own step 4).