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
122 lines
7.1 KiB
Markdown
122 lines
7.1 KiB
Markdown
---
|
|
name: stack-build
|
|
description: Builds a stack work package whose Gitea issue body is ready - code, tests, version bump, document pull-through, publish, and waiting for a green CI run, keeping the issue body current at fixed points along the way. Started only by the operator as /stack-build #N, after stack-dev has ended its design phase.
|
|
disable-model-invocation: true
|
|
---
|
|
|
|
# Stack Build
|
|
|
|
**Purpose:** Carry a designed work package through the checked stretch of its life - from a
|
|
ready issue body to a green CI run on the published commit - and leave the body current enough
|
|
that the closing phase, or anyone else, can work from it without this session's context.
|
|
|
|
**Trigger:** The operator runs `/stack-build #N`. Nothing else starts this skill: the
|
|
frontmatter's `disable-model-invocation` keeps Claude Code from invoking it, and in a harness that
|
|
ignores that key this sentence is the rule. This session may be the continuation of the design
|
|
session, or a fresh one after `/clear` - assume the second, and work from the body.
|
|
|
|
## Steps
|
|
|
|
1. **Read `instructions/dev/stack-mode.md`.** It holds the rules that change in a
|
|
stack-development session and the catalogue of dev-only procedures; a cold session has
|
|
neither yet.
|
|
|
|
2. **Check that the body is ready, before anything else.** Read issue #N's body against
|
|
`instructions/dev/issue-tracking.md` § Ready to build. If a point fails, stop: name it, and
|
|
recommend `/stack-dev` to finish the design. **Do not build around the gap** - a build session
|
|
that answers an open design question on its own produces a change that matches its own
|
|
reading of the body, recorded nowhere as a decision.
|
|
|
|
3. **Build the change and its tests.** Follow `instructions/dev/testing-conventions.md` before
|
|
adding or changing a test, and the other procedures the mode file names for the surface you
|
|
touch.
|
|
|
|
**"Covered by tests" means covered by the tests that exist, not by the tests that should
|
|
exist.** Whether the right test was written is itself a judgment call with no mechanical
|
|
guard: two data-destroying bugs in `upstream merge` (Gitea #30) shipped past a green
|
|
`pytest`/`docs verify`/`instructions verify`/CI because no test exercised the case, not
|
|
because the code for the tested case was worse. Where the body names a destructive step, its
|
|
invariant is a test (issue-tracking.md step 1).
|
|
|
|
**Body upkeep, first fixed point - a deviation goes into the body at once.** An assumption
|
|
that turns out false, a criterion that moves, an approach dropped: rewrite the body where it
|
|
stands, in this session, not at the end
|
|
(`instructions/dev/issue-tracking.md` step 2 has the rule; this is where it applies).
|
|
A deviation that reopens the design - a boundary crossing, a decision the body did not make -
|
|
is not settled here: stop and put it to the operator, as in step 2.
|
|
|
|
4. **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. The part was named in the body during design; bump that part:
|
|
|
|
```bash
|
|
tools/wikitool version bump --patch --title "<what changed>" --impact medium
|
|
```
|
|
|
|
`--impact high|medium|low` (default `medium`) grades this bump in the changelog entry's own
|
|
list - `tools/wikitool version regrade` corrects it later if the candidate's overall shape
|
|
changes the read on an earlier one; see `instructions/dev/version-parts.md` § The candidate
|
|
model.
|
|
|
|
Never edit `VERSION` or the entry's heading by hand - `bump` writes both, and `docs verify`
|
|
fails a tree where they disagree. Then write the entry's body - `bump` deliberately leaves it
|
|
empty, the same way `new` leaves the prose. A `--major` bump needs `--breaking` and either a
|
|
migration document or `--no-migration`; `instructions/dev/version-parts.md` has all of it.
|
|
|
|
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.
|
|
|
|
5. **Pull through every document that makes a claim about the surface you touched.**
|
|
`instructions/dev/doc-pull-through.md` has the table of which document that is, per surface,
|
|
and its step 3 for the one part that is not prose: a reference file whose headings moved needs
|
|
`tools/wikitool docs toc --apply`, never a hand-written list. Prose you write here is English,
|
|
whatever language the session is held in - `AGENTS.md` § File naming has both language rules.
|
|
|
|
6. **Publish and wait for CI** per `instructions/dev/publish-and-ci.md`: the local checks,
|
|
`tools/wikitool publish`, then the run on the published commit.
|
|
|
|
**Body upkeep, second fixed point - after the publish:** tick the criteria the publish met,
|
|
and name the version and the commit in the body.
|
|
|
|
**Third fixed point - CI green:** name the run in the body as what verified the change. A red
|
|
run is not this point: it is step 3 again, then this step again.
|
|
|
|
Then the one changelog comment for this session's worth of change
|
|
(`instructions/dev/issue-tracking.md` step 3).
|
|
|
|
7. **End the phase.** Recommend how the closing phase should run, and stop:
|
|
|
|
- **This session ran on Opus at high effort:** continue here with `/stack-close` - what was
|
|
built is still in context, and that is what the closing phase checks against.
|
|
- **It ran on another model or a lower effort:** `/clear`, then `/stack-close` in a new
|
|
session on Opus at high effort, which works from the body and the diff. That is why the
|
|
three fixed points above are not optional.
|
|
|
|
Close with the fixed line, in the instance's KB language per `AGENTS.md` § File naming:
|
|
|
|
> #N is published and CI is green (run <id>). Next: `/stack-close` - here, or after `/clear`.
|
|
|
|
**Do not run `stack-close` yourself.** Offer no `/model` or `/effort` switch either - see
|
|
`instructions/dev/stack-mode.md` § Sessions and models.
|
|
|
|
## Decision points
|
|
|
|
- **The change turns out not to be a drop-in replacement after all?** 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. `instructions/dev/version-parts.md` step 4 has the full shape, and the body takes the
|
|
answer as a design change (step 3's first fixed point).
|
|
- **The package needs several build sessions?** Each one ends with the body current and its own
|
|
changelog comment; the phase ends once, at the green run after the last publish.
|
|
- **CI gave up after 15 minutes, or is red for a reason outside this change?** Hand the open or
|
|
failing runs to the operator by id and link. The phase is not over, and the closing line in
|
|
step 7 is not given.
|
|
|
|
## Scope
|
|
|
|
Only for a body that is ready - the design is `stack-dev`
|
|
(`instructions/dev/stack-dev/SKILL.md`), the closing after a green run is `stack-close`
|
|
(`instructions/dev/stack-close/SKILL.md`). Not for wiki content work.
|