---
name: stack-dev
description: Switches a session into tool-development mode and runs its design phase - 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, triage or work out a stack issue, or otherwise work on the stack rather than ingest/query/manage/lint the wiki.
---

# Stack Development Mode - Design

**Purpose:** Recognize a session that is about the tool stack itself - `tools/wikitool`, the
type schema, the instruction/skill layer - rather than wiki content, switch the rules that apply
accordingly, and carry a work package through its design phase: to an issue body a cold session
can build from.

**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. Also: triaging a
`status/incoming` stub, refreshing an old spec against today's tree, or analysing a defect in the
stack before anything is fixed.

This is the first of three phases. The build (`stack-build`) and the closing (`stack-close`)
are separate skills that only the operator starts - this one never runs them, and never builds
past the design. `instructions/dev/stack-mode.md` has the phases, their handovers and why they
are split that way.

## Steps

1. **Confirm the mode, then read `instructions/dev/stack-mode.md`.** 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. The mode file holds the rules that change, and the
   catalogue of dev-only procedures (§ Where the procedures are); consult what it names for the
   task at hand rather than re-deriving it.

2. **Find or open the work package.** One Gitea issue per package
   (`instructions/dev/issue-tracking.md`). Read its body as the current spec, and correct it
   first where the tree or a comment proves it wrong. A `status/incoming` stub is worked out per
   that file's § Incoming stubs before anything else happens to it.

3. **Work the design out in the body, not beside it.** Whatever this session establishes - a
   decision and its reasoning, a root cause, a rejected approach, the files involved - goes into
   the body as it is settled (`instructions/dev/issue-tracking.md` step 2), with one changelog
   comment for the session's worth of change (step 3). A question only the user can answer is
   asked in the chat and stays a question in the body until it is answered; it is never settled
   by a guess.

4. **Name the version part.** Apply the drop-in test in `instructions/dev/version-parts.md`
   and write the result into the body. Whether a change is a drop-in replacement has no
   mechanical guard, so it is decided here, not at the bump. A change that crosses the
   compatibility boundary goes to the user with what breaks, what an instance has to do about
   it, and the alternatives, before the body can be ready (version-parts.md step 4).

5. **End the phase at a ready body.** Check the body against
   `instructions/dev/issue-tracking.md` § Ready to build. If it fails, say which point is open
   and stay in this phase. If it passes, recommend one of two ways on, and stop:

   - **A long design session** - much exploration, a defect analysis, a stub worked out from
     scratch: `/clear`, then `/stack-build #N`. The build starts lean, and a cold start is the
     real test of whether the body is ready.
   - **A short one** - an existing spec refreshed against the tree: continue in this session
     with `/stack-build #N`.

   Close with the fixed line, in the instance's KB language per `AGENTS.md` § File naming:

   > #N is ready. Next: `/stack-build #N` - here, or after `/clear`.

   **Do not run `stack-build` yourself, and do not start building.** The phase change is the
   operator's moment to decide on context and model; a design session that carries on into code
   takes that decision away. Offer no `/model` or `/effort` switch either - see
   `instructions/dev/stack-mode.md` § Sessions and models.

## Decision points

- **Nothing to build - the session answered a question or filed a follow-up?** The phase ends
  with the issue in whatever state it reached, body current; there is no `/stack-build` line to
  give.
- **The task is a one-line fix that seems not to need a design?** It still needs a body that
  says what is fixed and which version part it takes - which for a real one-liner is a short
  body, written in minutes. The cut to `stack-build` can then happen in the same session.
- **The design turns out to cross the compatibility boundary?** Do not decide it alone - step 4.

## Scope

Not for wiki content work - use `wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/
`wiki-status`/`gtd-weekly-review` for that. Not for setting up a new instance
(`instructions/setup-instance.md`) or a fresh clone of this repo (`instructions/bootstrap.md`).
Not for building a ready body (`stack-build`, `instructions/dev/stack-build/SKILL.md`) or closing
a published package (`stack-close`, `instructions/dev/stack-close/SKILL.md`).