chamba 0.6.0 → 0.7.0

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

@@ -0,0 +1,399 @@
+# 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.
+
+## 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.
+- `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
+
+For user-facing work, always pin down theme support - dark, light, both, or one fixed theme - and the target devices - desktop only, responsive, or mobile-first.
+The user answers this once. Do not guess it.
+
+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.
+Size the research to the work.
+Ask the user for the type and the depth in a round - a quick focused check against a thorough survey, and which sources you have.
+Mark your pick recommended.
+
+Then research as agreed, 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.
+
+This stage has no gate. It feeds the stages after it.
+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.
+Style both `[data-theme="dark"]` and `[data-theme="light"]` on the root element when both themes are in scope, and one theme when the user chose one.
+Lay the screen out so it reads well at the target device widths.
+
+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 about the commits first, unless the principles file already answers it.
+Two more questions shape the run - the pauses and the review checkpoints - and they come later in this stage, because their options name concrete phases.
+
+The settings read at bootstrap may answer the commit questions in advance:
+
+- `commit_mode: current-branch`, `new-branch` or `no-commits` answers the commits question. `prompt` keeps it.
+- `commit_grouping: per phase` or `single` answers the grouping question. `prompt` keeps it. With `no-commits` there is no grouping, so it is skipped either way.
+- With `new-branch`, `branch_naming` names the branch, with `<slug>` replaced by this spec's slug. The name question is then skipped.
+
+A saved answer skips its question, and says nothing.
+The plan gate still shows the whole setup, so the user can make an exception for this one spec there.
+
+Ask the commit questions in one round: whether the run commits as it goes, on the current branch or on a new one, and how the commits are grouped.
+Ask for the branch name in the same round when a new branch is a live option.
+
+Record the answers as `Commits: none | single | per phase` and `Branch: current | <name>` lines in `PLAN.md`.
+
+Then break the work into phases.
+**Each phase fits one session, and leaves the repo in a working state.**
+Write `plan/PLAN.md`: the goal, how the run behaves, 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.
+
+**Have `plan/PLAN.md` on disk, with its goal and its whole phase list, before the next round.**
+Both questions in it name concrete phases, and this file is what the user reads to answer them.
+
+**The pauses.**
+Ask where the run stops for the user: nowhere, after one named phase, or after every phase.
+A stop lets the user see a result before later phases build on it.
+Recommend no stops for a small, low-risk plan.
+Recommend a named phase when one phase is risky, user-visible, or a natural point for feedback.
+Recommend every phase when the user wants to steer the work all the way through.
+Record the answer as a `Pauses:` line: `none`, `after phase 2, after phase 4`, or `every phase`.
+
+**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. For each one, say how many reviewers and give each a short focus.
+Correctness against the spec, security, performance, repo rules and docs consistency are examples, not a menu.
+
+Where they go:
+
+- **Every proposal includes the final checkpoint, after the last phase.** It judges the finished work as a whole.
+- 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.
+- Say why each checkpoint sits where it does, and name the phases.
+
+Ask the pauses and the checkpoints in one round.
+The user's pick is final, so a user who declines every checkpoint gets none.
+Record the answer as a `Review checkpoints:` bullet with one sub-bullet per checkpoint: where it sits, how many reviewers, their focuses, and why it is there.
+With no review at all, the line is `Review checkpoints: none`.
+
+**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.
+
+- Commits: none | single | per phase
+- Branch: current | <branch name>
+- Pauses: none | after phase 2, after phase 4 | every phase
+- Review checkpoints:
+  - after phase 3: 2 reviewers - correctness against the spec, and docs consistency. Later phases build on this one.
+  - final: 3 reviewers - correctness against the spec, docs consistency, and simpler shapes.
+
+## 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 run behaves, how the plan honors the principles, and any deviation with its reason.
+On changes: revise, and gate again. Loop until the user approves it.
+
+## 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, the report format, and the design-blockers loop.
+
+**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 four reviewers: consistency and completeness, principles alignment, better ways to do this, and design blockers.
+**Include the "better ways to do this" reviewer and the design-blockers reviewer in every proposal.**
+The design-blockers reviewer runs the loop `references/review-guide.md` defines.
+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 and the blockers loop.
+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 carrying the evidence and the trade-off.
+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.
+A user who asks for another round gets one. There is no automatic re-review loop.