@asrunjs/asrun 0.0.0-stage → 0.5.2

package/docs/agents/framework-dev.md

@@ -0,0 +1,79 @@
+# Working on AsRun itself
+
+Read `AGENTS.md` first: it is the product baseline, and this file only adds how to change the framework. Nothing here
+is relevant to a project that uses asrun as a dependency.
+
+## Framework layout
+`<framework>` for a project is `node_modules/@asrunjs/asrun`. In this repository it is the root folder:
+- `lib/`              fixtures (`profile`, session guard) and assertion helpers; specs import them as
+                      `@asrunjs/asrun/<module>` (for example `@asrunjs/asrun/fixtures`, `@asrunjs/asrun/values`)
+- `scripts/`          user-facing commands, see README.md
+- `templates/`        the files `pnpm asrun init` writes into a workspace
+- `ui/`               local web UI (`pnpm ui`). It may only run the fixed actions in `ui/server/actions.ts`
+                      and must never serve anything under `.auth/`.
+- `docs/theme-guide.html` the Inkstone theme guide of the web UI: color tokens, buttons, badges, icons, surfaces
+- `examples/demo/`    a workspace for developing the framework itself against a local Docker stack (Conduit);
+                      it is committed (`.auth/` and `reports/` never are), see its README
+
+## Working on the framework itself
+- The framework repository holds no workspace content at the root: no `profiles.yaml`, `cases/`, `tests/` or
+  reports there. The one workspace is `examples/demo`, which is committed because it runs its own local site; its
+  `.auth/`, `reports/` and other run output are not. Develop against it: `pnpm demo:up` and `pnpm demo:seed` start
+  and fill the local stack, `pnpm asrun init --root examples/demo` (it also writes the framework's `.env` with
+  `ASRUN_ROOT=examples/demo`), then `pnpm asrun --env staging --read-only`.
+- Everything the framework reads for a project goes through `ROOT` in `lib/paths.ts` (the workspace root); its own
+  assets (templates, docs, skills, its `node_modules`) go through `FRAMEWORK_ROOT`. Never write into
+  `FRAMEWORK_ROOT` at run time.
+- `templates/` is the source of the files a workspace gets. When a template changes, bump `version` in
+  `package.json` so `pnpm asrun doctor` in a project shows that it is behind.
+- `init` owns two lists: `GENERATED` (rewritten by `--update`; the commands and the Playwright files) and `ONCE`
+  (written only when missing; `AGENTS.md`, `CLAUDE.md`, the configs). `AGENTS.md`, `CLAUDE.md` and
+  `.claude/skills/**` belong to the project: `init --force` refuses them unless `--reset-rules` is given, so a
+  framework update can never overwrite a project's rules.
+- A project's rules never flow back here. The framework reads a workspace only through `ROOT` at run time; nothing
+  under `templates/` or `.claude/skills/` is generated from a project.
+
+## The commands and the two agent CLIs
+- Claude Code reads `.claude/commands/*` and `.claude/skills/<name>/SKILL.md`.
+- OpenCode reads `.opencode/commands/*`, `.claude/skills/<name>/SKILL.md`, `.opencode/skills/<name>/SKILL.md` and
+  `.agents/skills/<name>/SKILL.md`. It does **not** read `.claude/commands`, and it does **not** read a flat
+  `.claude/skills/<skill>.md` as a skill (that file is a project override, read by the command and by the skill).
+- `GENERATED` renders the same four command texts into both `.claude/commands/` and `.opencode/commands/`, so edit
+  `templates/.claude/commands/*.md` once. In this repository the eight command files are written by hand: keep
+  `.claude/commands/` and `.opencode/commands/` identical (`diff -r .claude/commands .opencode/commands`).
+- OpenCode discovers skills by walking up from the working directory to the git worktree, so a workspace sees only
+  its own skills, not the framework ones under `node_modules`: the command's `Load the framework skill <path>` is a
+  plain file read. That is why the skill itself must read the project override (`.claude/skills/<skill>.md`).
+
+## Web UI (`ui/web`)
+Before adding or changing any UI element, read `docs/theme-guide.html` (open the file; it is static HTML) and follow it.
+Its rules are binding, in particular:
+- Icons: Feather via the `react-feather` package only (`import {ChevronDown} from 'react-feather'`). Never draw, paste
+  or hand-write SVGs, and never add another icon library. Size 14 in buttons, 16-20 elsewhere; decorative icons get
+  `aria-hidden="true"`, icon-only buttons get an `aria-label`. Do not use Unicode symbols (`▲ ▼ ◀ ▶ ⤢`) as icons.
+- Colors: only the tokens in `ui/web/src/index.css` (the default Tailwind palette is removed). Pick the color by impact.
+- Buttons and badges: use `buttonClass()` and `Badge` from `ui/web/src/components/status.tsx`, never hand-style them.
+- Dropdowns: use `Select` from the same file, never a bare `<select>` or hand-copied classes (native arrow and height
+  differ). A required dropdown that is empty gets `invalid` (red). See the "Dropdowns" section of the theme guide.
+- A list the user has to search in (a case id, a file name) is `SearchSelect` from
+  `ui/web/src/components/search-select.tsx`: an input with a filtered list below it, which a native `<select>` cannot
+  do. It keeps `Select`'s height, border and focus ring, so the two look like one family; do not build a third variant.
+- If a change adds or alters a token, update `ui/web/src/index.css` and `docs/theme-guide.html` together.
+Before reaching for a new dependency or writing a helper component, grep `package.json` and `ui/web/src` for what the
+project already uses.
+
+### Copy (`ui/web/src`)
+
+Every lead, label and tooltip is written for the person using the UI, never for the person who built it. Four rules:
+
+- **What → what you do → next.** A page, panel or section explains three things, in that order: what it does, what the
+  user has to do, and what comes next (state it only when something does). A run that needs nothing from the user says so.
+- **Short.** A lead is at most three sentences. A longer explanation becomes labeled paragraphs (`<b>While it runs</b> — …`)
+  or a bullet list, never one dense block. A tooltip is `# Title`, then at most three lines of one sentence each: it
+  wraps inside 320px (`ui/web/src/lib/tooltip.ts`).
+- **No implementation in the copy.** File paths, directory names, CLI flags, skill or command names, and the agent's
+  internal syntax (`TODO`, `Answer:`, `RESULT: needs-input`, `- Recipe:`) never appear in a lead, a label or a tooltip.
+  They belong where the file, the command or the syntax is the object itself: the Spec view, the Jobs drawer, a
+  `CopyBlock`, or a folded `<details>` block titled "For the command line".
+- **Say what the user sees.** "The run appears in the Jobs bar", not "the command runs in a one-shot session"; "the
+  browser shows a small card", not "the agent pauses on a `writes` step".