feat: stack development in three phases - stack-dev (design), stack-build, stack-close, handed over through tracker states (#168)
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
This commit is contained in:
torbenandClaude Opus 5.5 committed
1 parent
80488bee38
commit
d8224ee2ab
21 files changed
+631
-331
No files matched your search
@@ -1,206 +1,85 @@
|
||||
---
|
||||
name: stack-dev
|
||||
description: Switches a session into tool-development mode - 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, or otherwise work on the stack rather than ingest/query/manage/lint the wiki.
|
||||
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
|
||||
# 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, and switch the rules that
|
||||
apply accordingly.
|
||||
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.
|
||||
`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 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, this skill should not be present at all;
|
||||
stack development happens in the origin repo instead (see AGENTS.md's routing line).
|
||||
|
||||
## 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 (step 2 below lists what currently exists). 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).
|
||||
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.** 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.
|
||||
2. **Consult `instructions/dev/` for the concrete procedure.** Currently:
|
||||
`instructions/dev/commonplace-kb.md` - vendored knowledge base on agent context
|
||||
engineering, memory and deploy-time learning; consult before a design decision in those
|
||||
areas.
|
||||
`instructions/dev/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 this session's plan file:** keep it current as the state
|
||||
moves, so an interrupted session leaves a body the next one can resume from, *and* rewrite it
|
||||
to its final state before closing. Both halves bind; the second is what
|
||||
`stack-close` (`instructions/dev/stack-close/SKILL.md`) carries out once this skill's own work is published -
|
||||
see step 6 below. An issue labelled `status/incoming` is the exception to all of that: it is a
|
||||
human's stub, not a spec, and it is **never implemented as it stands** - it gets worked out and
|
||||
triaged first. Read this file 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.
|
||||
`instructions/dev/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.
|
||||
`instructions/dev/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/`.
|
||||
`instructions/dev/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 before step 4.
|
||||
`instructions/dev/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.
|
||||
`instructions/dev/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.
|
||||
`instructions/dev/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 step 6.
|
||||
More instructions are added here incrementally as stack-development needs come up - this
|
||||
list grows without needing this skill file to change shape.
|
||||
3. **Settle the design before building - and break there for the model switch.** These are two
|
||||
different kinds of work, and the split is not stylistic: design, the version part and any
|
||||
boundary judgment have **no** mechanical guard, while the code and tests that follow are mostly
|
||||
covered - `pytest`, `docs verify`, `instructions verify` and CI catch a mistake **in what they
|
||||
cover**.
|
||||
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.
|
||||
|
||||
So when the design is settled - the issue body says what will be built, the open questions are
|
||||
answered - stop and say so, in one sentence that names what the mechanical stretch does **not**
|
||||
cover. The message below is a model of what to say, not a script to quote: say it in the
|
||||
instance's KB language, per `AGENTS.md` § File naming.
|
||||
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.
|
||||
|
||||
> The plan is settled. From here the work is mostly mechanical and covered by tests/CI -
|
||||
> except the changelog prose (step 4), any `docs/` page you touch, new human-facing
|
||||
> documentation, and the prose half of an instruction. If you are on Opus, now is the moment
|
||||
> for `/model sonnet` at effort `high`.
|
||||
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.
|
||||
|
||||
**You cannot make this switch yourself** - the session's model is the user's `/model`, not a
|
||||
setting an agent applies. Offer it once and keep working either way; a session that argues
|
||||
about its own model has already cost more than the difference. If the design turns out not to
|
||||
be settled after all - a boundary crossing surfaces, an assumption breaks - that is a reason to
|
||||
offer the switch back up, not to decide it alone.
|
||||
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).
|
||||
|
||||
**"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 a weaker model wrote worse code for the case that *was* tested. This is not a third
|
||||
break - it is a caveat on this one: the middle phase stays the cheaper phase to run on, but its
|
||||
test suite is only as complete as the judgment that wrote it, and that judgment is unchecked
|
||||
the same way the design phase is.
|
||||
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:
|
||||
|
||||
Effort is the cheaper lever than the model, and `high` is the floor for anything touching more
|
||||
than one file or a contract. Full table and reasoning:
|
||||
`docs/model-and-effort-selection.md`.
|
||||
- **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`.
|
||||
|
||||
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:
|
||||
Close with the fixed line, in the instance's KB language per `AGENTS.md` § File naming:
|
||||
|
||||
```bash
|
||||
tools/wikitool version bump --patch --title "<what changed>" --impact medium
|
||||
```
|
||||
> #N is ready. Next: `/stack-build #N` - here, or after `/clear`.
|
||||
|
||||
`--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. Pick the part by whether the new version is a **drop-in
|
||||
replacement** for the old one - not by whether content has to be migrated:
|
||||
|
||||
| Change | Part |
|
||||
|--------|------|
|
||||
| Fix, no interface change | `--patch` |
|
||||
| New capability, still drop-in in both directions | `--minor` |
|
||||
| **Not a drop-in replacement** - any hand-work by the user or a migration script, or a downgrade that no longer works | `--major` |
|
||||
|
||||
Content migration is one way to land in the last row, not the definition of it: a rename of
|
||||
the update path, the artefact, an import name, a flag or an envvar breaks a swap with `kb/`
|
||||
entirely untouched. The full test, the catalogue of such breaks, and what to put in front of
|
||||
the user first are in `instructions/dev/version-parts.md` - **read it before choosing
|
||||
`--major`.**
|
||||
|
||||
A `--major` bump therefore needs two things recorded. `--breaking "<what stops working>"`
|
||||
is required on every boundary-crossing bump; on top of it, a migration document for the new
|
||||
version - written per `instructions/migrate-corpus.md` - or
|
||||
`--no-migration "<reason>"` when no content actually has to change. `bump` refuses without
|
||||
either, and so does `docs verify`: an instance learning that it must migrate, with nothing
|
||||
telling it how, is a dead end.
|
||||
|
||||
Then write the entry's body - `bump` deliberately leaves it empty, the same way `new` leaves
|
||||
the prose.
|
||||
|
||||
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 - `docs verify`
|
||||
checks a cell's presence, never its prose.** `instructions/dev/doc-pull-through.md` has
|
||||
the table of which document that is, per surface, and its step 3 for the one part of the
|
||||
pull-through 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 being held in -
|
||||
`AGENTS.md` § File naming has both language rules and the line between prose and quoted
|
||||
vocabulary.
|
||||
|
||||
6. **Verify, then publish.** `tools/wikitool docs verify`, `tools/wikitool instructions verify`,
|
||||
and the relevant `pytest` run in `tools/` - the same checks any stack change must pass, run
|
||||
explicitly rather than assumed. CI (`.gitea/workflows/ci.yml`) runs these plus a full
|
||||
`setup-instance.md` replay against a fresh `dist export`; a push to `main` that moves `VERSION`
|
||||
additionally triggers a tagged release. **CI does the tagging** - a session never creates a
|
||||
tag, which is what keeps AGENTS.md invariant 5 intact.
|
||||
|
||||
Publish with `tools/wikitool publish`. When the changeset touches `tools/`, `types/`,
|
||||
`instructions/`, `AGENTS.md` or a `<stage>/CONTRACT.md`, `publish` itself prints a one-line
|
||||
reminder that the phase past this point is not covered by any of the checks above - that line
|
||||
is the cue that this skill's own job just ended.
|
||||
|
||||
**This skill stops here.** The closing phase - rewriting the issue body to its final state,
|
||||
checking for `docs/` staleness, and naming which model ran which phase of the session - lives
|
||||
in `stack-close` (`instructions/dev/stack-close/SKILL.md`), not in a further step of this one. Invoke it now;
|
||||
do not fold its work into this session under this skill's rules, and do not treat "the change
|
||||
is published" as this work package being done.
|
||||
**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
|
||||
|
||||
- **Touches both stack code and wiki content in one session?** Apply this skill's 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.
|
||||
- **The change turns out not to be a drop-in replacement?** 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. A surfacing boundary crossing
|
||||
is also a reason to offer the model switch back up (step 3): the judgment it needs has no
|
||||
mechanical guard, and `docs verify` only checks that a crossing documents itself, never that the
|
||||
part was chosen correctly.
|
||||
- **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 closing a work package after
|
||||
its publish has landed - that is `stack-close` (`instructions/dev/stack-close/SKILL.md`).
|
||||
(`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`).
|
||||
Reference in new issue
Block a user