torbenandClaude Opus 5.5
d8224ee2ab
stack-build and stack-close carry disable-model-invocation, so each phase change is the operator's slash command; no skill offers a mid-session /model or /effort switch. Mode rules and the phase table move to instructions/dev/stack-mode.md, publish and CI waiting to instructions/dev/publish-and-ci.md, the ready definition to issue-tracking.md. Files changed: - AGENTS.md - CHANGES.md - DEVELOPMENT.md - README.md - VERSION - docs/model-and-effort-selection.md - instructions/CONTRACT.md - instructions/dev/commonplace-kb.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/issue-tracking.md - instructions/dev/publish-and-ci.md - instructions/dev/stack-build/SKILL.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/stack-mode.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - tools/chemenu/commands/git_publish.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_instructions_cmd.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
123 lines
8.2 KiB
Markdown
123 lines
8.2 KiB
Markdown
---
|
|
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`. What every phase records, so that reasoning can be checked
|
|
against practice, is `stack-close`'s handover (its own step 4).
|