chamba 0.6.1 → 0.8.0

package/templates/skills/dx-spec/references/stages.md

@@ -0,0 +1,484 @@
+# The stages
+
+This file holds the stage definitions for `/dx-spec` (`SKILL.md` in the directory above).
+Read a stage's section when the stage starts, and run the stage from that definition.
+
+Every gate here is declared with `specs await`, in the shapes `SKILL.md` gives.
+Declaring one ends your turn.
+
+## The tab
+
+The spec directory is the whole product: plain files that agents write and the user reads.
+The Specs tab renders every one of them as it stands on disk.
+Nothing is generated for the tab, and nothing is kept in step with it.
+
+The tab is where the user reads and where the user answers.
+Name the artifact in a gate's `file`, and the tab opens it and puts the gate under it.
+Say nothing about how to read a file: the user is already looking at it.
+
+## The text of a round
+
+The text you compose for a round must agree with the options that round offers.
+An option that declines a step makes that step the user's choice.
+No text beside it may say that the step happens anyway.
+Compose the question from the options, and read the two together before you declare the round.
+
+## Asking again
+
+The "Needs you" list says what is genuinely open.
+Only your own care keeps that true.
+
+An ask the user answered leaves the list as they answer it.
+A gate they asked for changes on is thus gone before you revise anything: declare the next one and carry on.
+
+An ask you supersede is different, because nobody answered it.
+You replace it with a different question, or the answer reaches you in the terminal instead.
+The ask then stays on the list, and tells the user to answer something you know already.
+Take it off in the same act that supersedes it, with `specs withdraw` and the reason.
+`SKILL.md` carries the verb and its payload.
+A gate declared again on the same artifact is the one case the tool takes back on its own.
+
+## Applying the user's annotations
+
+The user annotates any part of any artifact on the tab.
+Two actions and no others: a comment on something, or a request that it be removed.
+Each round of annotations lands in `.specs/user-feedback.json` in the spec directory, and the pane types one line into this terminal naming the file.
+
+The file is also the signal to a session picking the work up: a file that is there holds annotations nobody applied.
+Apply a round in four steps:
+
+1. Rename the file to `.specs/user-feedback.applying.json`. Rename it first. A round the user sends while you revise then lands on the free name, and is applied in the next round rather than deleted unread.
+2. Read the file, and open the asset files it names.
+3. Revise the artifacts the comments point at.
+4. Delete the renamed file and every asset file it named. Delete the assets directory when nothing is left in it.
+
+Then declare the gate again, or ask what to do next when this happened while you picked the work up.
+A `.specs/user-feedback.applying.json` file left behind means an earlier session stopped mid-apply.
+Apply it the same way, from step 2.
+
+The file names the piece of work in `entry`, and holds one round per submit:
+
+```json
+{
+  "version": 1,
+  "entry": "checkout-discounts",
+  "rounds": [
+    {
+      "submittedAt": "2026-08-19T09:41:12.004Z",
+      "comments": [
+        {
+          "unit": "spec-spec-goal",
+          "file": "spec/SPEC.md",
+          "heading": "Goal",
+          "kind": "comment",
+          "quote": "renders any spec directory",
+          "text": "Say plainly that this holds for a directory that is not a spec too.",
+          "assets": []
+        },
+        {
+          "unit": "mocks-dashboard",
+          "file": "mocks/dashboard.html",
+          "heading": "",
+          "kind": "remove",
+          "quote": "",
+          "text": "",
+          "assets": []
+        },
+        {
+          "unit": "overall",
+          "file": "",
+          "heading": "",
+          "kind": "comment",
+          "quote": "",
+          "text": "Good direction. My notes on the wording are attached.",
+          "assets": [
+            {
+              "path": "user-feedback-assets/2026-08-19-094112-wording.txt",
+              "name": "wording.txt",
+              "type": "text/plain"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+How to read one comment:
+
+- `file` is relative to the spec directory.
+- An asset's `path` is relative to the `.specs/` directory the feedback file sits in, not to the spec directory.
+- `unit` is that path with the heading on the end, both slugified. It is the address of the exact place the annotation sits on.
+- `kind` is `comment` or `remove`. A `remove` asks you to take that thing out, and its `text` is often empty, because pointing is the whole request.
+- `quote` is the text the annotation was anchored on, when the user selected text. It is empty when they pointed at an image, a section or the file itself, which is what tells you the difference.
+- `unit: "overall"` has `file` and `heading` empty, and belongs to the piece of work rather than to one place in it.
+- A comment on a section of the review report is input to the finding in that section.
+
+## Visuals
+
+When a stage document is finished, decide whether a standalone visual would make the user's reading easier: a diagram, an SVG, or a small HTML figure.
+Write it as a lowercase file beside the document, when it earns its place.
+The tab renders an image inline and shows an HTML page in a frame, so a visual beside the document is read on the same page.
+When a visual belongs to one section, put it inside the document instead, as inline SVG or as an HTML table.
+Either way, keep it self-contained: no external image, no script, nothing fetched.
+This is a judgment call, never a rule.
+Most documents need no visual, and a visual nobody would look at is not worth writing.
+
+## High-level exploration
+
+Think together before you commit to anything.
+Hold an open conversation, not a script.
+Normal message text and ASCII diagrams are what this stage is made of.
+Map the problem space, question assumptions, compare directions, and raise the risks and the unknowns.
+Ground the thinking in the code rather than in theory.
+
+With imagination mode on, the first pass names the ideal as if everything were possible, and allows no talk of feasibility.
+`references/imagination-guide.md` states how the stage then runs.
+
+When things become clear, declare a gate on the work as a whole, asking whether to move on or keep exploring.
+Then write the conclusions into `spec/SPEC.md` as background and direction.
+
+## Interview
+
+Track down every doubt, until the spec stands on its own.
+Read what the input points to first: an uninformed interview wastes the user's time.
+
+Open `[NEEDS CLARIFICATION: ...]` markers in `SPEC.md` are the interview's first input.
+Read them before you write a question, and turn each one into a question of its own.
+An earlier stage already judged those doubts worth asking.
+
+Then interview the user in rounds, most important points first.
+A round is one `specs await` call, and it holds as many questions as the round needs.
+With imagination mode on, ask for the ideal experience first, and put the constraint questions after it.
+
+In every round:
+
+- **Frame the options production-grade by default**, and mark that one recommended.
+- **Lay out a real trade-off** in the question, and let the user decide. Do not decide it silently.
+- **Cross-reference the code.** When the user's claim contradicts what you read, say so: "You said a partial cancel is possible, but `orders.cancel:42` cancels the whole order - which is right?"
+- **Pin down vague language.** "By 'account' do you mean the Customer or the User? They are different here."
+- **Fold each answer into `SPEC.md` right after the round that produced it**, and clear the markers that round settles. An interview the user stops early then leaves nothing living in chat alone.
+
+Check these categories for candidates, most important first:
+
+- functional scope and non-goals
+- domain and data - shapes and contracts
+- the flow the user goes through
+- qualities that are not features - permissions, tenant scope
+- integrations
+- edge cases and failures - empty, loading, error
+- constraints and trade-offs
+- terminology
+- how success is measured
+
+**Theme support and the target devices.**
+For every piece of user-facing work, pin down which themes the application draws in - dark, light, or both - and which devices it is laid out for - desktop only, responsive, or mobile-first.
+Ask both once, in a round, whichever stages the protocol holds.
+No form asks them, so this stage is where they are settled.
+
+Look at the code that answers it before you ask, and mark the answer the code already gives as recommended.
+Almost always that is the answer: the work is in an application that has a theme and a layout already, and matching them is what the work needs.
+So the round is usually the user confirming what is there, and it stays a round because a piece of work that changes either one is exactly the piece of work an agent must not guess about.
+Say in the option which one the code gives, in the code's own terms - "both, which is what every screen in this app draws today".
+
+Write both answers into the `Themes and devices` section of `SPEC.md`, which the UI-mocks stage reads by name, so the stage that draws reads them from the spec rather than from a form.
+`references/spec-guide.md` holds that section's shape.
+
+Whatever stays open becomes a labeled assumption in `SPEC.md`, or a `[NEEDS CLARIFICATION: ...]` marker when it clears the bar in `references/spec-guide.md`.
+The implementer has to know what was confirmed and what was assumed.
+
+The stage ends at a gate: enough asked, or another round.
+
+## Research
+
+Run this stage for work that needs knowledge beyond the codebase: a protocol, a library, an algorithm, a subject area.
+
+**Open with no round.**
+The scope was settled beside this stage on the confirmation form, and it is in `stageSettings.research`.
+Where the settings hold nothing, the steps were confirmed before the form asked: open with one round for the scope, and carry on from the answer.
+The scope is one of three:
+
+- `focused` - you decide what to research, sized to the work.
+- `named` - research what `subject` names, and nothing wider.
+- `broad` - deep research across the subjects this work touches. Use a deep-research capability where your environment offers one.
+
+Check the scope against the code, the way **Cross-check a stored answer against the code** in `SKILL.md` says.
+Where `broad` is plainly more than the work needs, say so in a message and offer to narrow it - the user chose it, so the choice to keep it is theirs.
+
+Ask about sources in a round where the sources genuinely decide something: a paywalled standard, an internal document, a version you cannot reach.
+This is a judgment call, and most research needs no such round.
+
+Then research as settled, and write `research/RESEARCH.md`: what you learned, the options you compared, a recommendation, and the sources with links.
+Write a finding that decides something as **Decision / Rationale / Alternatives**: what was chosen, why, and what was rejected with the reason.
+Compare the options in a table when the comparison has more than two axes.
+Keep the volume sized to the work. The format is the discipline, not the length.
+The choices themselves land in the `Decisions` section of `SPEC.md`.
+
+Consider a visual beside the write-up.
+Then gate on `research/RESEARCH.md`: enough to go on, or one area worth more digging.
+
+## Codebase analysis
+
+Map the parts of the code the work touches: entry points, data shapes, the conventions and patterns to follow, and anything that constrains the design.
+Use the `Explore` agent for a broad search where you have one.
+Write the findings into `spec/SPEC.md` with `path:line` references.
+
+Read the project's own documents while you map the code: the README, the guides, and each document that sits beside the code the work touches.
+Find the ones the planned work makes not correct, and write them into the `Documentation impact` section of `spec/SPEC.md`, as `references/spec-guide.md` describes it.
+Name each document, and say which part of it the work makes not correct.
+Where the work leaves every document correct, write that, so the stages after this one know the question was asked.
+
+This stage is where the code is read as a whole, so it is where **Cross-check a stored answer against the code** in `SKILL.md` runs.
+Read every answer the user has given against what the code says, and raise what disagrees: the stage settings the protocol form carries, and what a round settled earlier, the interview's own answers included.
+
+This stage has no gate. It feeds the stages after it.
+So it does not end your turn: write its findings, and start the next stage in the same turn.
+A contradiction it finds becomes an interview question, a labeled assumption, or a `[NEEDS CLARIFICATION: ...]` marker.
+
+## Technical specs
+
+This is the core writing stage.
+Fill `spec/SPEC.md` by following `references/spec-guide.md`, from everything the earlier stages produced.
+
+First, ask in a round whether the spec should suggest how to build the work.
+When the user says yes, read the codebase as the agent about to build this would.
+Then offer two or three distinct approaches in the next round, where the solution space holds that many, each with a short label and a rough file layout.
+Mark your pick recommended.
+Keep the sketch high-level: a clear starting point and a rough file tree, not a design.
+
+Consider a visual beside the spec.
+Then gate on `spec/SPEC.md`.
+On changes: revise, and declare a new gate. Loop until the user approves it.
+
+With imagination mode on, and UI mocks in the protocol, this stage runs after the mocks stage.
+
+## UI mocks
+
+Run this stage only for work that has a user interface.
+A mock is a web page the user opens.
+Start building when the stage starts, and ask nothing first.
+
+With imagination mode on, the stage opens with a fan-out instead: many deliberately different candidate screens for the user to choose among.
+`references/imagination-guide.md` defines the fan-out, its one round, and the choice.
+That round is the one exception to "ask nothing first".
+
+Each mock is a complete standalone HTML document at `mocks/<mock-id>.html`, where `<mock-id>` is a kebab-case name for the screen.
+Use inline styles, no external resources, and images as data URLs.
+A standalone page lets the agent who builds the work open the mock on its own.
+
+**The theme and the devices come from the `Themes and devices` section of `SPEC.md`.**
+The interview settled both and wrote them there.
+Read them from the spec, and ask in one round only where the spec does not say - work that reached this stage with no interview.
+Style both `[data-theme="dark"]` and `[data-theme="light"]` on the root element for both themes, and one of them for one.
+Lay the screen out for the devices: one desktop width for desktop only, every width from a phone up for responsive, and the phone first for mobile-first.
+Where the code says something else than the spec does, raise it the way **Cross-check a stored answer against the code** in `SKILL.md` says before you draw.
+
+List each mock in the `Mocks` section of `SPEC.md` as soon as the first one exists.
+
+The loop:
+
+1. Build or revise the mock files.
+2. Declare a gate on the mock the user is judging.
+3. On changes, or on annotations the user sent: apply them, revise each file in place, and gate again.
+4. On approval: add the approval date to the `Mocks` section. Approval ends the stage.
+
+## Execution plan
+
+**Ask nothing about how the run is shaped.**
+The commits, the branch, where the run stops and who reviews it are settled on the execute form, in one act, when the user starts the run.
+This stage recommends them as data, and writes none of them into `PLAN.md`.
+
+Break the work into phases.
+**Each phase fits one session, and leaves the repo in a working state.**
+Write `plan/PLAN.md`: the goal, the principles check, and the phase list with checkboxes.
+Give each phase its goal and its definition of done.
+Decide the phase boundaries, the goals and the definitions of done now, for every phase. They are cheap to get right in advance.
+
+Do not give much weight to development cost or to output size.
+Prefer quality, simplicity, robustness, scalability and long-term maintainability.
+When something has grown unwieldy, restructure it by judgment: refactor, split, or extract.
+Never restructure by a number set in advance.
+
+Check the plan against the principles the bootstrap read.
+Record the outcome as a `## Principles check` section: one line per principle the work touches, saying how the plan honors it.
+When a plan must break a principle, record it in a table with the columns `Deviation | Why needed | Simpler alternative rejected because`.
+Look for the simpler alternative before you record a deviation, and say why you rejected it.
+A deviation is an exception the user decides on at the gate.
+It is not a way to soften a principle, so the usual fix for a conflict is a different plan.
+
+When `SPEC.md` carries requirement IDs, end every phase entry with a `Covers: FR-03, FR-04` line.
+Every ID appears in one phase's `Covers` line at least, and a requirement may span several phases.
+An ID no phase covers means a missing phase, or scope that belongs in the non-goals.
+Add the phase, or move the requirement, before the gate. Ask the user when the call is not yours.
+
+**A phase covers each document the spec's `Documentation impact` section names.**
+Name the document in the definition of done of the phase that changes what it describes, so the run makes the document correct as it changes the code.
+Do not collect the documents into a phase of their own at the end.
+
+**Post the phases as soon as `PLAN.md` is on disk:**
+
+```
+echo '{"kind":"plan","phases":[{"phase":"phase-01-the-state","title":"The state"},{"phase":"phase-02-the-routes","title":"The routes"}]}' | specs post <spec>
+```
+
+One call, holding the whole list, in plan order.
+A phase's id is the name of the file it will be written into, without the extension, which is what the executing agent writes and ticks.
+The execute form names phases from this list: without it the user cannot place a pause or a checkpoint at all.
+
+Post the whole list again after each revision of the plan.
+The list the post carries becomes the list: a phase that is gone from the plan goes from the state with it, and a phase that survives keeps the status it had.
+This is the only write that drops a phase, so a plan the user changed at the gate leaves nothing behind for the execute form to offer.
+
+**Then recommend how the run is shaped**, with `specs recommend`.
+`SKILL.md` carries the payload.
+The user decides it on the execute form; this is your reading of the work, and it binds nobody.
+
+**The commits.**
+Recommend `per-phase` for a plan of several phases, because a phase that is committed is a phase a later session finds finished.
+Recommend `single` for small work that reads as one change.
+Recommend `none` where the user is likely to want to read the whole thing before any of it lands.
+Recommend a new branch for work of any size that touches shared code, and the current branch for a small change on a branch that is already the work's own.
+Name the branch `spec/<slug>`, with this spec's own slug, unless a principle in the principles file names another shape.
+
+**The pauses.**
+A pause is where the run stops and waits for the user.
+The modes are `none`, `chosen` with the phases named, and `every`.
+
+Recommend a pause only where skipping it has a real downside: a later phase builds on something the user must see or decide first.
+Recommend `none` for every other plan, which is most of them.
+A phase that is only visible, or only complicated, earns no pause.
+A pause with no such downside costs the user a stop for nothing.
+
+A pause is not a mid-run review checkpoint.
+A checkpoint stops nobody: fresh reviewers judge the work, and the run goes on.
+A pause needs the user, and the run waits until the user answers.
+A phase that needs another reader gets a checkpoint.
+A phase that needs the user's own judgment gets a pause.
+
+Never recommend `every` yourself.
+That mode is the user's to pick on the form, and a recommendation of it carries no reason.
+
+**The pause reasons.**
+Give every pause you recommend one line in `pauseReasons`, keyed by the phase it sits after.
+Say what the later phases build on, and what goes wrong where the user does not see it first.
+Where you recommend `none`, give `noPauseReason` one line saying why nothing needs the user before the run ends.
+Write both to the user, in plain words.
+The execute form shows them under the Pauses field, and they are how the user judges the stops you proposed.
+
+**The review checkpoints.**
+A review checkpoint is a point in the run where fresh reviewers, who did not do the work, judge what is built so far.
+Propose concrete checkpoints, each with a panel of one focus per reviewer.
+Correctness against the spec, security, performance, repo rules and docs consistency are examples, not a menu.
+
+Where they go:
+
+- **Every recommendation carries the final checkpoint**, after the last phase. It judges the finished work as a whole, and the user may still untick it.
+- Recommend a mid-run checkpoint only under the **dependency-risk rule**: the one risk that justifies stopping for reviewers mid-run is a phase whose wrong implementation sends later phases wrong. Review a complicated phase with no effect on later phases at the end instead. A five-phase plan with no such risk gets the final checkpoint alone.
+- Give each checkpoint a `why` of one line, saying why it sits where it does. The form shows it on a line under the checkpoint.
+- **Include a "better ways to do this" reviewer in the final panel.**
+
+**Write no phase file now.**
+Each `plan/phase-NN-<slug>.md` holds a `Status:` line, tasks as checkboxes, and a **Verify** section stating how to prove the phase done.
+The executing agent writes that file just before its phase runs, against the code as it stands then.
+A detailed plan for a later phase, written this early, is mostly guessing.
+
+An executing agent loads `PLAN.md` and its one phase file, never the whole plan.
+
+`PLAN.md` follows this layout.
+Copy the opening note roughly as written, and adapt the rest to the work.
+Include the deviation table only when the plan breaks a principle, and the `Covers:` bullets only when `SPEC.md` carries IDs:
+
+```markdown
+# <Title of the work>
+
+> **For the executing agent - read this first.** Read `spec/SPEC.md` before any phase.
+> This plan was written before the work started; check each phase against the actual code before building, and raise anything that looks off instead of pushing through.
+> How this run is shaped - the commits, the branch, the pauses and the review checkpoints - is in the state, decided on the execute form.
+
+## Goal
+
+<what the work achieves, in a line or two>
+
+## Principles check
+
+<one line per principle the work touches, saying how the plan honors it>
+
+| Deviation | Why needed | Simpler alternative rejected because |
+| --- | --- | --- |
+| <the principle the plan breaks> | <why the plan needs to> | <the simpler alternative, and why it was rejected> |
+
+## Phases
+
+- [ ] Phase 1 - <name>
+  - Goal: <what this phase achieves>
+  - Definition of done: <how to tell it is complete>
+  - Covers: <the requirement IDs this phase covers>
+- [ ] Phase 2 - <name>
+  ...
+```
+
+Consider a visual beside the plan.
+Then gate on `plan/PLAN.md`, saying the phases in a line each, how the plan honors the principles, and any deviation with its reason.
+Say in one line what you recommended for the run, and that the user settles it when they press Execute.
+On changes: revise the plan, post the phases again where they moved, recommend the run again where the change made the recommendation wrong, and gate again.
+Loop until the user approves it.
+The rule over that last part is **Keep what derives from a change true**, in `SKILL.md`.
+
+## Quality review
+
+This is the last stage before the coherence rewrite and finalize.
+It reviews everything the spec produced - `spec/SPEC.md`, the research, the plan, and the mocks the spec lists - and whether those documents agree with each other.
+Read `references/review-guide.md` when the stage starts.
+It holds the reviewer briefs, the lenses, the severities, and the report format.
+
+**The panel.**
+Ask who reviews the work, in a round.
+Propose a panel sized to the work and its risk, one reviewer per focus, and mark your proposal recommended.
+Give a short line saying what each reviewer looks at.
+The default proposal has three reviewers: consistency and completeness, principles alignment, and better ways to do this.
+**Include the "better ways to do this" reviewer in every proposal.**
+Bigger or riskier work may add a focus of its own - security, performance, the work's own subject - and small work may run with two reviewers.
+Always offer an option that turns the review off.
+Say in its description that nothing gets checked independently, and that the spec goes straight to the rewrite and finalize.
+
+On the skip: post the stage done with a note saying it was skipped, write no report, and move on.
+A skipped stage counts as not run, so finalize keeps its full read-through.
+
+**Running it.**
+Run one reviewer per confirmed focus, each as a subagent with a brief from `references/review-guide.md`.
+The reviewers share no context: each gets its own prompt, none sees this conversation, and none is told what the others found.
+
+An agent with no subagent tool runs the same passes itself, one lens at a time, and writes each pass's findings into the report before it starts the next.
+The report's mode line then says the review ran inline, and that the fresh-context guarantee did not hold.
+An agent that has the capability but cannot make it work stops and asks in a round.
+It never downgrades quietly.
+
+Post each round of review as it lands, so the board shows it:
+
+```
+echo '{"round":1,"verdict":"holds, two for you","findings":9,"judgments":2}' | specs review <spec>
+```
+
+**Handling the findings.**
+Merge the findings, and remove the duplicates.
+Dismiss a finding you disagree with, and say why in the report.
+Fix a finding that is plainly right, apply the fix, and mark it applied.
+Bring a taste or scope finding to the user, "better ways" suggestions included, with the reviewer's reasoning.
+Bring a finding to the user too when it is right but the fix is not obvious, or when acting on it would undo something the user approved at an earlier gate.
+Resolve a conflict with a principle by changing the work, never the principle.
+
+**The report and the gate.**
+Write `review/REVIEW.md` in the format `references/review-guide.md` defines.
+Consider a visual beside it: where the findings fall across the artifacts is the kind of thing a figure shows faster than a list.
+
+Declare one decision card per finding that waits on the user.
+Each card names the passage precisely: the artifact in `file`, and the `##` section in `heading`.
+Write what was found and what each way costs into the question's own `ask`.
+Say the proposed change as one option, in the exact words it would be done in, and the alternative as another option.
+Mark one of them recommended.
+The card's own box is where the user's words go, and it is already there, so write no `invite` on a card: the form draws one box for the card and gives it its own words.
+Then gate on `review/REVIEW.md`.
+Read the answers back, record what the user decided in the report, and apply it.
+Then gate again.
+A comment the user sent on a finding's section is input to that finding.