codeassembly-guidance 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +306 -0
- package/CHANGELOG.md +73 -0
- package/README.md +55 -4
- package/content/_partials/finding-grades.md +4 -0
- package/content/codeassembly-content.yaml +2 -0
- package/content/collections/recommended.md +5 -2
- package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
- package/content/guidance/rulebooks/cli-conventions.md +17 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
- package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
- package/content/scripts/check-prose.mjs +1 -1
- package/content/scripts/describe-change.mjs +68 -68
- package/content/skills/_data/action-items.md +2 -2
- package/content/skills/_data/artifact-conventions.md +20 -10
- package/content/skills/_data/concision.md +1 -1
- package/content/skills/_data/entry-points.md +37 -0
- package/content/skills/_data/recommendation-gradient.md +6 -6
- package/content/skills/_data/spike-conventions.md +13 -3
- package/content/skills/_data/ticket-source-resolution.md +21 -4
- package/content/skills/_data/title-templates.md +4 -4
- package/content/skills/_partials/commit-title-rendering.md +2 -1
- package/content/skills/_partials/next-steps-after-plan.md +4 -3
- package/content/skills/_partials/option-format.md +8 -8
- package/content/skills/_partials/plan-template.md +3 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
- package/content/skills/_partials/split-launch-prompts.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/analyze-performance/SKILL.md +102 -0
- package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
- package/content/skills/assess-code-health/SKILL.md +16 -14
- package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
- package/content/skills/assess-usability/SKILL.md +5 -3
- package/content/skills/convert-agent-prompt/SKILL.md +60 -0
- package/content/skills/create-commit/SKILL.md +10 -5
- package/content/skills/create-pr/SKILL.md +11 -11
- package/content/skills/create-ticket/SKILL.md +1 -0
- package/content/skills/design-and-plan/SKILL.md +2 -2
- package/content/skills/implement-plan/SKILL.md +1 -28
- package/content/skills/index-prototypes/SKILL.md +36 -17
- package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
- package/content/skills/investigate-spike/SKILL.md +48 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
- package/content/skills/refine-plan/SKILL.md +7 -4
- package/content/skills/refine-prototype/SKILL.md +5 -5
- package/content/skills/review-branch/SKILL.md +7 -7
- package/content/skills/review-criteria/SKILL.md +3 -3
- package/content/skills/review-gh-pr/SKILL.md +1 -1
- package/content/skills/revise-prose/SKILL.md +9 -8
- package/content/skills/revise-prose/revise-prose.mjs +2 -2
- package/content/skills/start-ticket/SKILL.md +27 -0
- package/content/skills/summarize-change/SKILL.md +17 -9
- package/content/skills/testing-conventions/SKILL.md +12 -1
- package/content/skills/triage-spike-findings/SKILL.md +31 -12
- package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
- package/content/subagents/_data/claude.yaml +3 -0
- package/content/subagents/code-health-assessor.md +4 -4
- package/content/subagents/disposition-challenger.md +3 -4
- package/content/subagents/entry-drafter.md +2 -2
- package/content/subagents/handoff-reviewer.md +1 -1
- package/content/subagents/prototype-builder.md +69 -0
- package/content/subagents/usability-assessor.md +1 -1
- package/package.json +5 -4
- package/schemas/preferences.v1.json +1 -1
- package/schemas/work-types.v1.json +1 -1
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
|
@@ -9,7 +9,7 @@ supported-harnesses: [claude]
|
|
|
9
9
|
|
|
10
10
|
Find where a product would lead its users to conclude that it is broken or unfinished. Each lens is a {subagent:usability-assessor} that walks its use cases in a browser or, for a command-line product, in a shell, without seeing any other lens's report. You prepare the targets, write the brief that every lens reads, dispatch the lenses one at a time, and merge their reports into one findings artifact.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
When the findings leave nothing to triage, the skill's one remote write is the [closing post](../_data/spike-conventions.md#closing-post) on the ticket, made on the developer's consent; otherwise the triage round makes the post. It does not create a ticket or edit an issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
|
|
13
13
|
|
|
14
14
|
## Inputs
|
|
15
15
|
|
|
@@ -93,6 +93,8 @@ Then publish it as an artifact page: Load the artifact-design skill, and render
|
|
|
93
93
|
|
|
94
94
|
### 7. Report
|
|
95
95
|
|
|
96
|
-
Give the developer the findings artifact's path, the page's URL, and one line of counts: use cases exercised, findings by effect, and ideas.
|
|
96
|
+
Give the developer the findings artifact's path, the page's URL, and one line of counts: use cases exercised, findings by effect, and ideas.
|
|
97
97
|
|
|
98
|
-
|
|
98
|
+
When the artifact has any finding or idea, name `triage-spike-findings` as the next step, with the findings artifact's path as its input, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states. Findings above the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches) are triaged in several batches, each on its own ticket.
|
|
99
|
+
|
|
100
|
+
Otherwise, offer the closing post on the ticket in the same response's action-items block. Its contents, consent, and duplicate check are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the use cases exercised and the page's URL.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: convert-agent-prompt
|
|
3
|
+
description: Convert an agent's prompt file into an agent-logic file, which an agent-logic viewer renders as a statechart. Use when asked to convert, chart, or extract the logic of an agent prompt.
|
|
4
|
+
standalone: wanted only in projects that convert agent prompts, too rarely to justify a standing skill-index line
|
|
5
|
+
user-invocable: true
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Convert an agent prompt
|
|
9
|
+
|
|
10
|
+
Convert a prompt file into an agent-logic file: an XState v5 machine config that contains the prompt's logic and nothing else. You write a draft that quotes the prompt; the `convert` command of the `codeassembly-agent-logic` package turns it into the config, deriving offsets and ids, and refuses to write a config that is not valid.
|
|
11
|
+
|
|
12
|
+
Every command runs version 0.1.0 of the package through `pnpm dlx`, so that the extraction rules that you read match the procedure below.
|
|
13
|
+
|
|
14
|
+
## Arguments
|
|
15
|
+
|
|
16
|
+
- The prompt file (required).
|
|
17
|
+
- The output path (optional). Default: beside the prompt, `<base>.agent-logic.json`, where `<base>` is the prompt file's name without its extension.
|
|
18
|
+
- The problems path (optional): where the script writes the problems of a draft that it cannot convert, or the out-of-scope verdict.
|
|
19
|
+
|
|
20
|
+
## Prerequisites
|
|
21
|
+
|
|
22
|
+
- `pnpm` on the path.
|
|
23
|
+
- Access to the npm registry, from which `pnpm dlx` fetches the package on its first run.
|
|
24
|
+
- Write access to pnpm's dlx cache. A sandbox that denies it fails the first command with `Operation not permitted`; retry the command outside the sandbox through the permission gate.
|
|
25
|
+
|
|
26
|
+
## Procedure
|
|
27
|
+
|
|
28
|
+
1. Read the prompt file in full.
|
|
29
|
+
2. Print the extraction rules, and read them in full:
|
|
30
|
+
|
|
31
|
+
```shell
|
|
32
|
+
pnpm dlx codeassembly-agent-logic@0.1.0 rules
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Judge whether the prompt is out of scope by their condition, then write the draft that they describe, or the out-of-scope draft, to `$TMPDIR/<base>.draft.json`.
|
|
36
|
+
|
|
37
|
+
3. Unless the draft is out of scope, check it against the prompt before running the script, and correct it where the check fails:
|
|
38
|
+
- **Coverage.** Read the prompt again from the top, one paragraph or list item at a time, and write a coverage map to `$TMPDIR/<base>.coverage-map.json`: a JSON array with an entry `{ "quote": "...", "element": "..." }` for each instruction in it. The `quote` copies the instruction verbatim and occurs in the prompt exactly once. The `element` names the state, action, or transition that holds it, or is `ambient`, `unconverted`, or `none`. A list item or paragraph that states three instructions takes three entries. Include the instructions inside a dense step, each of which is an action of that step's state, and the rules of a section that states how to format output, such as an option format. Add each instruction whose entry names `none` to the draft where the rules' "What to extract", "Ambient instructions", and "Passages you cannot convert" place it, and name its element in the entry.
|
|
39
|
+
- **Map check.** Run the coverage check:
|
|
40
|
+
|
|
41
|
+
```shell
|
|
42
|
+
pnpm dlx codeassembly-agent-logic@0.1.0 check-coverage {prompt file} {map file}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
If it exits 1, it lists each block of the prompt that no entry quotes, as `line <N>: <opening words>`, and each entry whose quote does not occur exactly once. Map every instruction of each listed block, holding it in the draft as the Coverage bullet says, lengthen each listed quote until it occurs once, and run the check again. After the third run, go on to the next check, whatever the map check reports, and keep the `line` lines of its last run for the report. If it exits 2, handle it as step 7 states.
|
|
46
|
+
|
|
47
|
+
- **Inputs.** List each input that the prompt tells the agent to read, fetch, or receive, such as a page, a list, or a field of the request. For each one, find an element that uses what the input supplies: a later action, a guard, or an ambient rule. Record an `unused-input` finding, as the rules' "Findings" section states, for each input that no element uses.
|
|
48
|
+
- **Inferred quotes.** Read the quote of each element that has `meta.inferred` on its own, and ask whether those words name the element, as the rules' "Quotes" section requires. Replace a quote that names a neighbouring step or the question that precedes the element.
|
|
49
|
+
4. Run the script:
|
|
50
|
+
|
|
51
|
+
```shell
|
|
52
|
+
pnpm dlx codeassembly-agent-logic@0.1.0 convert {prompt file} {draft file} {output file}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
When a problems path is given, add `--problems-file {problems path}` before `{prompt file}`.
|
|
56
|
+
|
|
57
|
+
5. If the script exits 1, it lists each problem by its path in the draft. Correct every listed entry in the draft and run it again. Repeat until it exits 0 or 3, for at most 5 runs. If the fifth run exits 1, stop, delete the draft file and the map file, and report the problems that it listed.
|
|
58
|
+
6. If the script exits 3, it wrote no config. Do not run it again: Delete the draft file, then report that the prompt is out of scope, with the reason.
|
|
59
|
+
7. If either command exits 2, an argument or file is wrong, and it names the problem on stderr. Correct the argument or file and run the command again; if you cannot correct it, stop, delete the draft file and the map file, and report the message.
|
|
60
|
+
8. If the script exits 0, delete the draft file and the map file, then report the output path, the number of ambient instructions, the number of findings of each kind, the passages listed under `meta.unconverted`, and the blocks that the map check still listed on its last run, as it printed them.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: create-commit
|
|
3
|
-
description: Compose and record a commit for one logical unit of work. Pass the paths to stage
|
|
3
|
+
description: Compose and record a commit for one logical unit of work. Pass the paths to stage, a one-line statement of the change's purpose, and, when the change is in a worktree other than the session's cwd, that worktree's path.
|
|
4
4
|
background: false
|
|
5
5
|
context: fork
|
|
6
6
|
model: sonnet
|
|
@@ -17,9 +17,14 @@ The conventions to which the message is composed -- title format, body voice and
|
|
|
17
17
|
|
|
18
18
|
- **Paths**: The paths that this commit records. When the arguments do not name any, the candidates are every changed path in the working tree.
|
|
19
19
|
- **Purpose**: One line stating why the change was made. The diff shows what changed; the purpose is the only source of why. When the arguments do not state one, compose the body from the diff alone, and never state a reason that the diff does not show.
|
|
20
|
+
- **Working directory**: The worktree that contains the change, `{dir}` below. When the arguments do not name one, it is the directory in which this procedure starts. Every command below runs against it: each git call as `git -C {dir}`, the session-context deriver with `--cwd {dir}`, and the title renderer with `--project-root {dir}`, so that the branch, the ticket ref, and the title format all come from the worktree that is committed.
|
|
20
21
|
|
|
21
22
|
Everything else comes from the repository: This procedure may run without the conversation that produced the change, so it never relies on anything that only that conversation contains.
|
|
22
23
|
|
|
24
|
+
## What this procedure writes
|
|
25
|
+
|
|
26
|
+
It writes the commit message file and the commit, and nothing else. It never edits, creates, or deletes any other file, and never installs or builds anything: A commit records work that is already done, so a change missing from the working tree is a reason to stop, never one to produce it.
|
|
27
|
+
|
|
23
28
|
## What one commit contains
|
|
24
29
|
|
|
25
30
|
One logical unit of work, together with whatever that unit needs to stand on its own. Work that does not stand alone -- a scaffold filled in by a later change -- goes into the change that completes it rather than becoming a commit of its own.
|
|
@@ -28,9 +33,9 @@ Record each unit as it is finished. Several single-concern commits read better t
|
|
|
28
33
|
|
|
29
34
|
## Process
|
|
30
35
|
|
|
31
|
-
1. **Read what changed.** Run `git status --short` for which paths changed, then `git diff` and `git diff --cached` for what changed in them. The message reports the diff, so compose it from the diff rather than from what the work set out to do.
|
|
36
|
+
1. **Read what changed.** Run `git -C {dir} status --short` for which paths changed, then `git -C {dir} diff` and `git -C {dir} diff --cached` for what changed in them. The message reports the diff, so compose it from the diff rather than from what the work set out to do.
|
|
32
37
|
|
|
33
|
-
2. **Stage the unit.**
|
|
38
|
+
2. **Stage the unit.** First confirm that the working tree contains the change that the arguments describe. When a path that the arguments name is unchanged, or when none of the changed paths matches the stated purpose, stop without committing and without staging, and report `{dir}` and what `git -C {dir} status --short` showed there. Otherwise, stage the paths that the arguments name, then confirm that the message will describe exactly the staged set. When the arguments do not name any, stage every changed path, but only if those changes form one unit per [What one commit contains](#what-one-commit-contains); if they don't, stop without committing and report the units that you found.
|
|
34
39
|
|
|
35
40
|
3. **Resolve the title's fields.** The scope and the work type per the conventions, choosing the type by [Work type test](#work-type-test); the title text per [`title-voice.md`](../_data/title-voice.md), with any backticks stripped.
|
|
36
41
|
|
|
@@ -43,7 +48,7 @@ Record each unit as it is finished. Several single-concern commits read better t
|
|
|
43
48
|
```bash
|
|
44
49
|
body_path="{absolute path from the write step}"
|
|
45
50
|
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
46
|
-
git commit --file "$body_path"
|
|
51
|
+
git -C "{dir}" commit --file "$body_path"
|
|
47
52
|
```
|
|
48
53
|
|
|
49
54
|
7. **Report the result**: the new commit's short SHA and title, or, when step 2 stopped or the commit failed, why nothing was committed. Do not comment on the title's format. The template sets which tokens the title contains, a ticket reference among them, so neither a token that the title omits nor a difference from earlier commits is a finding.
|
|
@@ -54,7 +59,7 @@ Record each unit as it is finished. Several single-concern commits read better t
|
|
|
54
59
|
|
|
55
60
|
## Rendering the title
|
|
56
61
|
|
|
57
|
-
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash for `ticket_ref`, then render
|
|
62
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --cwd {dir}` via Bash for `ticket_ref`, then render, passing `{dir}` as `{project_root}`:
|
|
58
63
|
|
|
59
64
|
<!-- include: ../_partials/commit-title-rendering.md / -->
|
|
60
65
|
|
|
@@ -125,16 +125,16 @@ If the change summary's body does not end with a block, append the closing line
|
|
|
125
125
|
|
|
126
126
|
Pass the following inputs to the selected delegate per the delegate interface:
|
|
127
127
|
|
|
128
|
-
| Input | Value
|
|
129
|
-
| ------------------- |
|
|
130
|
-
| `title` | Rendered `pr_title` from step 6 (or bare `title` if the script was unavailable)
|
|
131
|
-
| `body` | Content from `## What` onward in the change summary, with the closing line inserted per step 9
|
|
132
|
-
| `labels` | Resolved label names (may be empty list)
|
|
133
|
-
| `base_branch` | Bare branch name derived from `default_branch` (strip remote prefix, e.g., `origin/main` -> `main`)
|
|
134
|
-
| `ticket_id` | From session context
|
|
135
|
-
| `project_slug` | From session context
|
|
136
|
-
| `artifact_base_dir` | From session context
|
|
137
|
-
| `initial_state` | `pr_initial_state` from session context: `draft` or `ready`
|
|
128
|
+
| Input | Value |
|
|
129
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
130
|
+
| `title` | Rendered `pr_title` from step 6 (or bare `title` if the script was unavailable) |
|
|
131
|
+
| `body` | Content from `## What` onward in the change summary, `## How to test` included when the summary has it, with the closing line inserted per step 9 |
|
|
132
|
+
| `labels` | Resolved label names (may be empty list) |
|
|
133
|
+
| `base_branch` | Bare branch name derived from `default_branch` (strip remote prefix, e.g., `origin/main` -> `main`) |
|
|
134
|
+
| `ticket_id` | From session context |
|
|
135
|
+
| `project_slug` | From session context |
|
|
136
|
+
| `artifact_base_dir` | From session context |
|
|
137
|
+
| `initial_state` | `pr_initial_state` from session context: `draft` or `ready` |
|
|
138
138
|
|
|
139
139
|
### 11. Persist the PR URL
|
|
140
140
|
|
|
@@ -148,4 +148,4 @@ node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs
|
|
|
148
148
|
|
|
149
149
|
- The orchestrator makes all decisions (scope, type, title rendering, labels). Delegates only make the platform API calls.
|
|
150
150
|
- Strip the remote prefix from `default_branch` (e.g., `origin/main` -> `main`) before passing to the delegate.
|
|
151
|
-
-
|
|
151
|
+
- The body's manual test steps come from the change summary's `## How to test`, which `summarize-change` writes; never add a test plan of your own.
|
|
@@ -383,6 +383,7 @@ Relationships: {list} <- only if any were created
|
|
|
383
383
|
Relationships skipped: {list with reasons} <- only if any were skipped
|
|
384
384
|
Labels skipped: {labels} <- only when `--label` was given on the Jira path
|
|
385
385
|
Branch association skipped: {reason} <- only when the step-6 guard skipped the persist
|
|
386
|
+
Start in its worktree: {skill?:start-ticket} <- omitted for a ticket in another repository
|
|
386
387
|
Target configuration missing: {files} <- only when the target's default branch lacks a file in `missing`
|
|
387
388
|
```
|
|
388
389
|
|
|
@@ -77,7 +77,7 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
|
|
|
77
77
|
|
|
78
78
|
### Phase 3: Converge on a design and refine the ticket
|
|
79
79
|
|
|
80
|
-
1. **Choose the approach.** When the solution is obvious, build on it; don't manufacture alternatives for the sake of it. When it is not obvious, weigh 2-3 approaches, ranked per [design priorities](../_data/design-priorities.md), in which a design that needs a person to act on each machine ranks below one that the agent applies itself, and apply the gate: A fork whose two strongest options are both ■■□ is presented at the checkpoint below with its trade-offs; otherwise the draft records the choice as "X, not Y" with its reason.
|
|
80
|
+
1. **Choose the approach.** When the solution is obvious, build on it; don't manufacture alternatives for the sake of it. When it is not obvious, weigh 2-3 approaches, ranked per [design priorities](../_data/design-priorities.md), in which a design that needs a person to act on each machine ranks below one that the agent applies itself, and apply the gate: A fork whose two strongest options are both ■■□ is presented at the checkpoint below with its trade-offs; otherwise the draft records the choice as "X, not Y" with its reason. When the design places a control or shapes an interface, start from the established model that {rulebook:accessibility-conventions} has the agent name, and record in `## Proposed solution` the reason for any departure from it.
|
|
81
81
|
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
82
82
|
|
|
83
83
|
2. **Draft the ticket on the recommended approach, provisionally.** The design is the draft ticket: Its `## Proposed solution` states the design, scaled to complexity, and a fork that survived the gate is written on its recommended branch until the checkpoint settles it.
|
|
@@ -104,7 +104,7 @@ Here, _the implementation_ is the plan artifact (Phase 4): Mechanism that the ti
|
|
|
104
104
|
|
|
105
105
|
**Present the ticket as the first checkpoint**, in one turn: the draft ticket, the decisions taken so far with their reasons, and the forks that survived the gate as option-style questions. Revise until approved. Approval of the ticket is approval of the design.
|
|
106
106
|
|
|
107
|
-
**When the checkpoint splits the ticket**, the session continues with one piece: With two pieces, it plans the originating ticket, which keeps the first piece; with an umbrella, it plans the first child, whose work belongs in that child's own worktree. Phase 5 then ends with the launch prompts that [Splitting the ticket](#splitting-the-ticket) defines
|
|
107
|
+
**When the checkpoint splits the ticket**, the session continues with one piece: With two pieces, it plans the originating ticket, which keeps the first piece; with an umbrella, it plans the first child, whose work belongs in that child's own worktree. Phase 5 then ends with the launch prompts that [Splitting the ticket](#splitting-the-ticket) defines. With two pieces, the next-steps menu stays for the originating ticket, and that ticket's prompt heading adds that this session continues with it at the menu. With an umbrella, the launch prompts replace the `Next action` menu, so that nothing offers to implement a child in the current worktree.
|
|
108
108
|
|
|
109
109
|
### Phase 4: Generate implementation plan
|
|
110
110
|
|
|
@@ -15,10 +15,6 @@ Implement the work described by a feature plan. This skill is the canonical path
|
|
|
15
15
|
| `--plan=<path>` | The plan artifact to implement. | Auto-resolved (see below) |
|
|
16
16
|
| `--ticket=<source>` | The ticket that the plan serves. Resolved per [ticket source resolution](../_data/ticket-source-resolution.md). | Auto-resolved (see below) |
|
|
17
17
|
|
|
18
|
-
## Scope
|
|
19
|
-
|
|
20
|
-
This skill implements a feature plan, the `## Tasks` / `## Verification` shape defined by the plan template. A spike plan has `## Investigation steps` and a `## Deliverable` instead (see [spike conventions](../_data/spike-conventions.md)): It is carried out to produce findings rather than implemented to produce a diff, and none of the steps below read its shape. Step 4 rejects one.
|
|
21
|
-
|
|
22
18
|
## The contract
|
|
23
19
|
|
|
24
20
|
The ticket's acceptance criteria are the contract; the plan is the mechanism by which they are met. When the plan and the facts found during implementation disagree, the acceptance criteria decide: A plan step that no longer serves them is the one to abandon.
|
|
@@ -27,30 +23,7 @@ The plan artifact is read-only. It is a record of what was decided at plan time,
|
|
|
27
23
|
|
|
28
24
|
## Process
|
|
29
25
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
2. **Resolve the plan**: Stop at the first source that yields one:
|
|
33
|
-
- **Explicit `--plan=<path>`**: Read it.
|
|
34
|
-
- **Already in context**: This session produced or read the plan. Use it as-is; do not re-read the file.
|
|
35
|
-
- **Newest plan for the ticket**: The newest of `*_plan.md` and `*_plan-v*.md` under `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` (run subdirectories included), by the greatest `YYYYMMDD-HHMMSSZ` filename prefix. Both forms have that prefix, so they sort chronologically together and the lexicographically greatest is the newest across the two. Because `refine-plan` writes its revision as `_plan-v2.md` under a later prefix than the plan that it revises, matching both forms lets a refined plan take precedence over the original that it supersedes. Do not widen to `*_plan*.md`, which also matches the `_plan-review.md` artifact written beside the revision.
|
|
36
|
-
- **Ask**: The sources above do not resolve a plan. Ask the user for a path rather than implementing from the ticket alone: A caller who invoked this skill has a plan in mind.
|
|
37
|
-
|
|
38
|
-
Announce the resolved path and its timestamp before executing anything. Several plans can exist for one ticket, and the newest is not always the intended one: This announcement is how the user catches a superseded plan while the choice can still change without cost. It is not ceremony, and it is not skippable when the resolution was unambiguous.
|
|
39
|
-
|
|
40
|
-
3. **Resolve the ticket**: Stop at the first source that yields one:
|
|
41
|
-
- **Explicit `--ticket=<source>`**: Resolve per [ticket source resolution](../_data/ticket-source-resolution.md).
|
|
42
|
-
- **Already in context**: This session already resolved the ticket. Use it as-is.
|
|
43
|
-
- **Stored URL**: `ticket_url` from step 1, fetched per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url).
|
|
44
|
-
- **Plan provenance**: The plan's frontmatter `ticket_ref` / `ticket_id`, resolved per [auto-resolve](../_data/ticket-source-resolution.md#auto-resolve).
|
|
45
|
-
- **No ticket**: Every source failed; the plan was produced from a free-form description, or the ticket is unreachable. Announce that a ticket does not govern the run and execute against the plan as the sole contract. Do not stall on a missing ticket; do not silently substitute the plan for one without saying so.
|
|
46
|
-
|
|
47
|
-
4. **Read the plan and the ticket** in full before touching code, including the plan's `## Risks` section: It names the parts of the work that the author expected to need adaptation.
|
|
48
|
-
|
|
49
|
-
Check the shape as you read: A plan with `## Investigation steps` rather than `## Tasks` is a spike, which this skill does not implement (see [Scope](#scope)). Stop and tell the user the plan is a spike, to be carried out directly rather than implemented here.
|
|
50
|
-
|
|
51
|
-
Then, when a ticket governs the run, read its open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers). When it has one, report it and ask the user to confirm that implementation should start despite it, as a `👍🏼👎🏼` confirmation. Do not start the first task without a clear affirmation.
|
|
52
|
-
|
|
53
|
-
Then check the branch per [branch currency](../_data/branch-currency.md), passing the paths in the plan's **Files:** lists. Do not start the first task while a question about the gap is unanswered.
|
|
26
|
+
<!-- include: ../_partials/resolve-plan-and-ticket.md / -->
|
|
54
27
|
|
|
55
28
|
5. **Execute the tasks in plan order.** Each task is done when its own acceptance criteria are met, not when its files have been touched. Task order encodes dependencies; do not reorder for convenience. Audit the comments that you write along the way per [Comment discipline](#comment-discipline), and the guidance and documentation that you write per the "Documentation placement" section of the shared agent instructions.
|
|
56
29
|
|
|
@@ -22,6 +22,11 @@ A ticket has one prototype set, in its artifact directory:
|
|
|
22
22
|
|
|
23
23
|
A later round of prototypes revises the same set: A new idea takes a new slug, and a revision of an existing prototype keeps its slug and takes the next version. The page shows the latest version of each slug.
|
|
24
24
|
|
|
25
|
+
The set title is the product's name as the developer refers to it, without a qualifier such as "chart": `Top Right`, not `Top Right chart`. Choose it before the set's first prototype is built; a later round reads it from the manifest's `title`. Every page in the set names it in its browser title, so that the developer can tell the tabs of a round apart:
|
|
26
|
+
|
|
27
|
+
- **A prototype page**: `<title>{set title} - {id} {title}</title>`, such as `Top Right - 1.1 Next item`.
|
|
28
|
+
- **The index page**: `{set title} - Prototypes`, which `render` writes.
|
|
29
|
+
|
|
25
30
|
A slug matches `[a-z0-9][a-z0-9-]{0,39}`. You choose each slug, before any prototype is built.
|
|
26
31
|
|
|
27
32
|
The helper gives each slug a number at its first registration, and every later version of the slug keeps it. A version's id is `{number}.{version}`, and it is how the developer refers to a version: Name each one to them as `{id} {title}`, such as `3.2 Catalog first`; the index card leads with the same form, and the page itself states it as the first line of its `data-demo` band. A bare number names the slug whose entries have that number, at its latest version. When the manifest does not contain an entry with that number, ask which prototype they mean rather than guess. The slug stays the key in the manifest and in the verdicts.
|
|
@@ -52,13 +57,13 @@ mktemp -d "${TMPDIR:-/tmp}/prototypes.XXXXXX"
|
|
|
52
57
|
|
|
53
58
|
### 2. Build the prototypes
|
|
54
59
|
|
|
55
|
-
Choose a slug for each prototype, resolve the ids, and choose the set's note labels, per [The set](#the-set).
|
|
60
|
+
Choose a slug for each prototype, resolve the ids, and choose the set's note labels, per [The set](#the-set). Every build meets this contract:
|
|
56
61
|
|
|
57
|
-
1. Write the page source to `{set_dir}/{slug}-v{n}.html`, with `{id} {title}` as the first line of its `data-demo` band.
|
|
62
|
+
1. Write the page source to `{set_dir}/{slug}-v{n}.html`, with the `<title>` that [The set](#the-set) states and with `{id} {title}` as the first line of its `data-demo` band.
|
|
58
63
|
2. Publish that file with the Artifact tool.
|
|
59
64
|
3. Report the artifact URL, a short title, the lens (the angle or constraint that distinguishes this prototype), the inputs on which it drew, a one-sentence description, and one line per note label as `{label}: {value}`.
|
|
60
65
|
|
|
61
|
-
Build a prototype in the main session the same way.
|
|
66
|
+
When a subagent builds a prototype, dispatch a {subagent:prototype-builder} with the dispatch block of {skill?:prepare-prototype-brief} step 5. When the session does not have a brief from that skill, first write one to the scratch directory that states what to build, the lens, the note labels, and the files that the builder may write. The builder meets the contract and checks the page in a headless browser apart from this session's. Dispatch builders one at a time, waiting for each reply, because builders that run at once share one browser. Build a prototype in the main session the same way.
|
|
62
67
|
|
|
63
68
|
### 3. Capture the screenshots
|
|
64
69
|
|
|
@@ -80,6 +85,15 @@ Stop the server once every prototype is captured.
|
|
|
80
85
|
|
|
81
86
|
The Playwright MCP attaches to the worktree's debug browser, and a call that reports a refused connection means that the browser is not running. Run `thor-chrome` from the worktree; the next call then reaches the browser without restarting the MCP. When `thor-chrome` refuses the launch with `session-unavailable`, as it can in the agent sandbox, ask the developer to run `thor-chrome` from the worktree in a terminal in the GUI login session, and wait for it rather than publishing an index without screenshots.
|
|
82
87
|
|
|
88
|
+
A Playwright call that ends in a timeout error, or that takes over 30 seconds, most likely waits on a page that hangs its renderer, and every later call queues behind it. Close that page:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
node {harness_home_dir}/skills/index-prototypes/index-prototypes.mjs probe-targets \
|
|
92
|
+
--endpoint "{endpoint from thor-chrome status --json}"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The result's `closed` lists each page that did not answer and was closed, and `answered` lists the rest. Report the prototype of each closed page as defective, leave it without a screenshot, and continue with the rest.
|
|
96
|
+
|
|
83
97
|
### 4. Register each prototype
|
|
84
98
|
|
|
85
99
|
Register each prototype in the manifest. The first registration in a set names the set with `--set-title`; a later one may rename it.
|
|
@@ -100,6 +114,8 @@ node {harness_home_dir}/skills/index-prototypes/index-prototypes.mjs register \
|
|
|
100
114
|
--screenshot "{working_dir}/.playwright-mcp/{slug}-v{n}.png"
|
|
101
115
|
```
|
|
102
116
|
|
|
117
|
+
`register` checks the source's `<title>` against the rule in [The set](#the-set). On `title-mismatch`, correct the source's `<title>` to the expected title that the message names, republish the source to the prototype's artifact URL with the Artifact tool, reading the artifact first when this session did not publish it (a builder's publish counts as another), and register again. When the artifact cannot be republished, report the prototype as defective and leave it unregistered.
|
|
118
|
+
|
|
103
119
|
Pass `--number` with the number that `resolve-ids` gave the slug. Pass one `--note` per note label, in the set's label order. Omit any optional flag that does not have a value. The result's `entry.version` must equal the `{n}` in the source's name; when it does not, the manifest already contained another version of the slug, so rename the source to match.
|
|
104
120
|
|
|
105
121
|
### 5. Describe the set
|
|
@@ -184,17 +200,20 @@ Then, in step 3, after each screenshot, pass the result's `function` to `browser
|
|
|
184
200
|
|
|
185
201
|
Every command prints one JSON object. A success has `ok: true`. A failure has `ok: false`, an `error` code, and a `message`, and the command exits 1:
|
|
186
202
|
|
|
187
|
-
| `error` | Meaning
|
|
188
|
-
| ---------------------- |
|
|
189
|
-
| `
|
|
190
|
-
| `invalid-
|
|
191
|
-
| `invalid-
|
|
192
|
-
| `invalid-
|
|
193
|
-
| `invalid-
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
198
|
-
| `
|
|
199
|
-
| `
|
|
200
|
-
| `
|
|
203
|
+
| `error` | Meaning |
|
|
204
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
205
|
+
| `endpoint-unreachable` | The browser's DevTools endpoint did not return its target list, or did not answer a close |
|
|
206
|
+
| `invalid-args` | Unknown command, a flag that this command rejects, a missing required flag, or a `--note` that is not `{label}: {value}` |
|
|
207
|
+
| `invalid-manifest` | `manifest.json` is not valid JSON or does not have the manifest layout |
|
|
208
|
+
| `invalid-slug` | The slug does not match `[a-z0-9][a-z0-9-]{0,39}` |
|
|
209
|
+
| `invalid-summary` | The summary file is not valid JSON or does not have the summary layout |
|
|
210
|
+
| `invalid-url` | The URL is not http or https |
|
|
211
|
+
| `manifest-not-found` | The set does not have a manifest yet; register a prototype first |
|
|
212
|
+
| `missing-set-title` | The set's first registration lacks `--set-title` |
|
|
213
|
+
| `not-png` | The screenshot is not a PNG file |
|
|
214
|
+
| `number-conflict` | `--number` is not a positive integer, differs from the slug's number, or belongs to another slug |
|
|
215
|
+
| `page-too-large` | The page would exceed the 16,000,000-byte artifact cap; nothing was written |
|
|
216
|
+
| `screenshot-not-found` | The screenshot path does not exist |
|
|
217
|
+
| `source-not-found` | The source path does not exist or is a directory |
|
|
218
|
+
| `summary-not-found` | The summary file does not exist |
|
|
219
|
+
| `title-mismatch` | The source's `<title>` differs from `{set title} - {id} {title}`, or the source does not have one; the message names the expected title |
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
2
|
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
-
var
|
|
4
|
-
`),!0}}
|
|
3
|
+
var me=Object.defineProperty;var o=(e,t)=>me(e,"name",{value:t,configurable:!0});import{mkdir as nt,readFile as ue,writeFile as st}from"node:fs/promises";import R from"node:path";import $ from"node:process";function V(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}o(V,"isError");function x(e){try{return V(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}o(x,"describeError");import{realpathSync as F}from"node:fs";import W from"node:process";import{fileURLToPath as pe}from"node:url";function q(e,t){let r=W.argv[1];if(r===void 0)return!1;try{return F(pe(e))===F(r)}catch(s){return W.stderr.write(`${t}: warning: could not determine entry point: ${x(s)}
|
|
4
|
+
`),!0}}o(q,"isEntryPoint");function ge(e,t){return U(e)&&e.code===t}o(ge,"isErrorCode");function b(e){return ge(e,"ENOENT")}o(b,"isEnoent");function g(e){return U(e)&&!Array.isArray(e)}o(g,"isRecord");function U(e){return typeof e=="object"&&e!==null}o(U,"isObject");var D=String.raw`() => {
|
|
5
5
|
const BLOCK = 'p, li, h1, h2, h3, h4, h5, h6, td, th, dt, dd, legend, caption, figcaption, summary';
|
|
6
6
|
const INLINE = 'label, button, a, option';
|
|
7
7
|
const SKIPPED = '[data-demo], script, style, template';
|
|
@@ -50,10 +50,10 @@ var oe=Object.defineProperty;var i=(e,t)=>oe(e,"name",{value:t,configurable:!0})
|
|
|
50
50
|
strings.push(text);
|
|
51
51
|
}
|
|
52
52
|
return strings;
|
|
53
|
-
}`;function
|
|
54
|
-
`,"utf8"),await ue(s,r)}catch(n){throw await fe(s,{force:!0}),n}return r}i(k,"writeManifest");function he(e){return b(e)&&typeof e.label=="string"&&typeof e.value=="string"}i(he,"isNote");function v(e){return e===null||typeof e=="string"}i(v,"isNullableString");function be(e){return b(e)?typeof e.shared=="string"&&v(e.changes)&&Array.isArray(e.try)&&e.try.every(t=>typeof t=="string"):!1}i(be,"isSetSummary");function ye(e){return b(e)?typeof e.slug=="string"&&(e.number===void 0||typeof e.number=="number"&&Number.isSafeInteger(e.number)&&e.number>0)&&typeof e.version=="number"&&Number.isSafeInteger(e.version)&&typeof e.registeredAt=="string"&&typeof e.title=="string"&&typeof e.url=="string"&&v(e.source)&&v(e.lens)&&Array.isArray(e.inputs)&&e.inputs.every(t=>typeof t=="string")&&v(e.description)&&(e.notes===void 0||Array.isArray(e.notes)&&e.notes.every(t=>he(t)))&&v(e.shot):!1}i(ye,"isStoredEntry");function xe(e){return b(e)?typeof e.title=="string"&&(e.indexUrl===null||typeof e.indexUrl=="string")&&(e.summary===void 0||e.summary===null||be(e.summary))&&Array.isArray(e.entries)&&e.entries.every(t=>ye(t)):!1}i(xe,"isStoredManifest");function we(e){let t=new Map;for(let n of e.entries){let o=t.get(n.slug);n.number!==void 0&&(o===void 0||n.version>o.version)&&t.set(n.slug,{version:n.version,number:n.number})}let r=new Map(t.entries().map(([n,{number:o}])=>[n,o])),s=Math.max(0,...r.values());for(let n of e.entries)r.has(n.slug)||(s+=1,r.set(n.slug,s));return{...e,summary:e.summary??null,entries:e.entries.map(n=>{let o=r.get(n.slug);if(o===void 0)throw new Error(`slug "${n.slug}" was not numbered`);return{...n,number:o,notes:n.notes??[]}})}}i(we,"normalizeManifest");import ke from"node:path";function H(e,t){let r=[],s=[];for(let n=0;n<e.length;n+=1){let o=e[n];if(o===void 0)continue;if(!o.startsWith("--")){r.push(o);continue}let d=ve(o,t);if(d===null)throw new Error(`unknown flag: ${o}`);let{spec:a,inlineValue:u}=d;if(!a.takesValue){if(u!==null)throw new Error(`--${a.name} does not take a value`);s.push({name:a.name,value:null});continue}if(u!==null){s.push({name:a.name,value:u});continue}let f=e[n+1]??null;if(f===null||f.startsWith("--"))throw new Error(`--${a.name} requires a value`);s.push({name:a.name,value:f}),n+=1}return{positionals:r,flags:s}}i(H,"scanFlags");function J(e){let t={};for(let{name:r,value:s}of e)s!==null&&(t[r]=s);return t}i(J,"valueFlagMap");function ve(e,t){for(let r of t)for(let s of[r.name,...r.aliases??[]]){let n=`--${s}`;if(e===n)return{spec:r,inlineValue:null};if(e.startsWith(`${n}=`))return{spec:r,inlineValue:e.slice(n.length+1)}}return null}i(ve,"matchFlag");var P=["copy-probe","describe-set","record-index","register","render","resolve-ids"],Se=new Set(P),Ee=[{name:"description",takesValue:!0},{name:"file",takesValue:!0},{name:"inputs",takesValue:!0},{name:"lens",takesValue:!0},{name:"note",takesValue:!0},{name:"number",takesValue:!0},{name:"out",takesValue:!0},{name:"screenshot",takesValue:!0},{name:"set-dir",takesValue:!0},{name:"set-title",takesValue:!0},{name:"slug",takesValue:!0},{name:"slugs",takesValue:!0},{name:"source",takesValue:!0},{name:"title",takesValue:!0},{name:"url",takesValue:!0}],$e={"copy-probe":{required:[],optional:[]},"describe-set":{required:["file","set-dir"],optional:[]},"record-index":{required:["set-dir","url"],optional:[]},register:{required:["set-dir","slug","title","url"],optional:["description","inputs","lens","note","number","screenshot","set-title","source"]},render:{required:["out","set-dir"],optional:[]},"resolve-ids":{required:["set-dir","slugs"],optional:[]}};function X(e){let{positionals:t,flags:r}=H(e,Ee),[s,n]=t;if(s===void 0)throw new Error(`a command is required: ${P.join(", ")}`);if(!Ne(s))throw new Error(`unknown command "${s}"; expected one of ${P.join(", ")}`);if(n!==void 0)throw new Error(`unexpected argument: ${n}`);let o=r.filter(l=>l.name==="note"),d=J(r.filter(l=>l.name!=="note")),{required:a,optional:u}=$e[s];if(o.length>0&&!u.includes("note"))throw new Error(`${s} does not take --note`);for(let[l,p]of Object.entries(d)){if(!a.includes(l)&&!u.includes(l))throw new Error(`${s} does not take --${l}`);if(p==="")throw new Error(`--${l} requires a value`)}for(let l of a)if(d[l]===void 0)throw new Error(`${s} requires --${l}`);let f=o.map(l=>Me(l.value??""));return{command:s,values:d,notes:f}}i(X,"parseArgs");function M(e){return e===void 0?[]:e.split(",").map(t=>t.trim()).filter(t=>t!=="")}i(M,"parseInputs");function g(e,t){let r=e[t];if(r===void 0)throw new Error(`--${t} is missing after parsing`);return r}i(g,"requireFlag");function w(e){return ke.resolve(g(e,"set-dir"))}i(w,"resolveSetDir");function Ne(e){return Se.has(e)}i(Ne,"isCommand");function Me(e){let t=e.indexOf(":"),r=t===-1?"":e.slice(0,t).trim(),s=t===-1?"":e.slice(t+1).trim();if(r===""||s==="")throw new Error(`--note "${e}" must have the form "<label>: <value>"`);return{label:r,value:s}}i(Me,"parseNote");import je from"node:path";import{copyFile as Ae,mkdir as Ie,readFile as Re}from"node:fs/promises";import C from"node:path";var Q=Buffer.from([137,80,78,71,13,10,26,10]);async function Z(e){let t;try{t=await Re(e.sourcePath)}catch(n){if(h(n))return{ok:!1,error:"screenshot-not-found",message:`the screenshot ${e.sourcePath} does not exist`};throw n}if(!t.subarray(0,Q.length).equals(Q))return{ok:!1,error:"not-png",message:`${e.sourcePath} is not a PNG file`};let r=C.join("shots",`${e.slug}-v${e.version}.png`),s=C.join(e.setDir,r);return await Ie(C.dirname(s),{recursive:!0}),await Ae(e.sourcePath,s),{ok:!0,shot:r}}i(Z,"intakeScreenshot");function T(e){try{let{protocol:t}=new URL(e);return t==="https:"||t==="http:"}catch{return!1}}i(T,"isWebUrl");async function ee(e,t,r,s){let n=g(t,"slug");if(!N(n))return c("invalid-slug",`slug "${n}" must match [a-z0-9][a-z0-9-]{0,39}`);let o=g(t,"url");if(!T(o))return c("invalid-url",`--url "${o}" is not an http or https URL`);let d=await y(e);if(d.kind==="invalid")return c("invalid-manifest",d.message);let a=d.kind==="ok"?d.manifest:null,u=t["set-title"]??a?.title;if(u===void 0)return c("missing-set-title","the first registration in a set requires --set-title");let f=Pe(a,n,t.number);if(typeof f!="number")return f;let l=j(a,n),p=null,O=t.screenshot;if(O!==void 0){let E=await Z({sourcePath:je.resolve(O),setDir:e,slug:n,version:l});if(!E.ok)return c(E.error,E.message);p=E.shot}let _={slug:n,number:f,version:l,registeredAt:s.toISOString(),title:g(t,"title"),url:o,source:t.source??null,lens:t.lens??null,inputs:M(t.inputs),description:t.description??null,notes:r,shot:p},ie={title:u,indexUrl:a?.indexUrl??null,summary:a?.summary??null,entries:[...a?.entries??[],_]};return{ok:!0,command:"register",manifestPath:await k(e,ie),entry:_}}i(ee,"register");function Pe(e,t,r){let s=Y(e,t);if(r===void 0)return s;let n=Number(r);if(!Number.isSafeInteger(n)||n<1)return c("number-conflict",`--number "${r}" must be a positive integer`);let o=e?.entries??[];if(o.some(a=>a.slug===t))return s===n?n:c("number-conflict",`slug "${t}" is number ${s}, not ${n}`);let d=o.find(a=>a.number===n);return d===void 0?n:c("number-conflict",`number ${n} belongs to slug "${d.slug}"`)}i(Pe,"resolveRegistrationNumber");var Ce="verdicts";var te=`(() => {
|
|
53
|
+
}`;function l(e,t){return{ok:!1,error:e,message:t}}o(l,"fail");import{mkdir as he,readFile as be,rename as ye,rm as xe,writeFile as we}from"node:fs/promises";import z from"node:path";import ve from"node:process";var B="manifest.json",ke=/^[a-z0-9][a-z0-9-]{0,39}$/;function w(e,t){return`${e}.${t}`}o(w,"formatId");function N(e){return ke.test(e)}o(N,"isValidSlug");function K(e){let t=new Map;for(let r of e.entries){let s=t.get(r.slug);(s===void 0||r.version>s.version)&&t.set(r.slug,r)}return t.values().toArray()}o(K,"listLatestEntries");function M(e,t){let r=e?.entries??[],s=0;for(let n of r)n.slug===t&&n.version>s&&(s=n.version);return s+1}o(M,"nextVersion");async function y(e){let t=Y(e),r;try{r=await be(t,"utf8")}catch(n){if(b(n))return{kind:"missing"};throw n}let s;try{s=JSON.parse(r)}catch{return{kind:"invalid",message:`${t} is not valid JSON`}}return Ne(s)?{kind:"ok",manifest:Pe(s)}:{kind:"invalid",message:`${t} does not have the manifest layout`}}o(y,"readManifest");function G(e,t){let r=e?.entries??[],s=new Map,n=0;for(let i of r)s.set(i.slug,i.number),n=Math.max(n,i.number);return t.map(i=>{let d=s.get(i);d===void 0&&(n+=1,d=n,s.set(i,d));let a=M(e,i);return{slug:i,number:d,version:a,id:w(d,a)}})}o(G,"resolveIds");function Y(e){return z.join(e,B)}o(Y,"resolveManifestPath");function H(e,t){let r=e?.entries??[],s=0;for(let n of r){if(n.slug===t)return n.number;s=Math.max(s,n.number)}return s+1}o(H,"resolveNumber");async function S(e,t){await he(e,{recursive:!0});let r=Y(e),s=z.join(e,`.${B}.${ve.pid}.${Date.now()}.tmp`);try{await we(s,`${JSON.stringify(t,null,2)}
|
|
54
|
+
`,"utf8"),await ye(s,r)}catch(n){throw await xe(s,{force:!0}),n}return r}o(S,"writeManifest");function Se(e){return g(e)&&typeof e.label=="string"&&typeof e.value=="string"}o(Se,"isNote");function k(e){return e===null||typeof e=="string"}o(k,"isNullableString");function Ee(e){return g(e)?typeof e.shared=="string"&&k(e.changes)&&Array.isArray(e.try)&&e.try.every(t=>typeof t=="string"):!1}o(Ee,"isSetSummary");function $e(e){return g(e)?typeof e.slug=="string"&&(e.number===void 0||typeof e.number=="number"&&Number.isSafeInteger(e.number)&&e.number>0)&&typeof e.version=="number"&&Number.isSafeInteger(e.version)&&typeof e.registeredAt=="string"&&typeof e.title=="string"&&typeof e.url=="string"&&k(e.source)&&k(e.lens)&&Array.isArray(e.inputs)&&e.inputs.every(t=>typeof t=="string")&&k(e.description)&&(e.notes===void 0||Array.isArray(e.notes)&&e.notes.every(t=>Se(t)))&&k(e.shot):!1}o($e,"isStoredEntry");function Ne(e){return g(e)?typeof e.title=="string"&&(e.indexUrl===null||typeof e.indexUrl=="string")&&(e.summary===void 0||e.summary===null||Ee(e.summary))&&Array.isArray(e.entries)&&e.entries.every(t=>$e(t)):!1}o(Ne,"isStoredManifest");function Pe(e){let t=new Map;for(let n of e.entries){let i=t.get(n.slug);n.number!==void 0&&(i===void 0||n.version>i.version)&&t.set(n.slug,{version:n.version,number:n.number})}let r=new Map(t.entries().map(([n,{number:i}])=>[n,i])),s=Math.max(0,...r.values());for(let n of e.entries)r.has(n.slug)||(s+=1,r.set(n.slug,s));return{...e,summary:e.summary??null,entries:e.entries.map(n=>{let i=r.get(n.slug);if(i===void 0)throw new Error(`slug "${n.slug}" was not numbered`);return{...n,number:i,notes:n.notes??[]}})}}o(Pe,"normalizeManifest");import Ae from"node:path";function J(e,t){let r=[],s=[];for(let n=0;n<e.length;n+=1){let i=e[n];if(i===void 0)continue;if(!i.startsWith("--")){r.push(i);continue}let d=Ie(i,t);if(d===null)throw new Error(`unknown flag: ${i}`);let{spec:a,inlineValue:c}=d;if(!a.takesValue){if(c!==null)throw new Error(`--${a.name} does not take a value`);s.push({name:a.name,value:null});continue}if(c!==null){s.push({name:a.name,value:c});continue}let f=e[n+1]??null;if(f===null||f.startsWith("--"))throw new Error(`--${a.name} requires a value`);s.push({name:a.name,value:f}),n+=1}return{positionals:r,flags:s}}o(J,"scanFlags");function X(e){let t={};for(let{name:r,value:s}of e)s!==null&&(t[r]=s);return t}o(X,"valueFlagMap");function Ie(e,t){for(let r of t)for(let s of[r.name,...r.aliases??[]]){let n=`--${s}`;if(e===n)return{spec:r,inlineValue:null};if(e.startsWith(`${n}=`))return{spec:r,inlineValue:e.slice(n.length+1)}}return null}o(Ie,"matchFlag");var T=["copy-probe","describe-set","probe-targets","record-index","register","render","resolve-ids"],Re=new Set(T),je=[{name:"description",takesValue:!0},{name:"endpoint",takesValue:!0},{name:"file",takesValue:!0},{name:"inputs",takesValue:!0},{name:"lens",takesValue:!0},{name:"note",takesValue:!0},{name:"number",takesValue:!0},{name:"out",takesValue:!0},{name:"screenshot",takesValue:!0},{name:"set-dir",takesValue:!0},{name:"set-title",takesValue:!0},{name:"slug",takesValue:!0},{name:"slugs",takesValue:!0},{name:"source",takesValue:!0},{name:"title",takesValue:!0},{name:"url",takesValue:!0}],Me={"copy-probe":{required:[],optional:[]},"describe-set":{required:["file","set-dir"],optional:[]},"probe-targets":{required:["endpoint"],optional:[]},"record-index":{required:["set-dir","url"],optional:[]},register:{required:["set-dir","slug","title","url"],optional:["description","inputs","lens","note","number","screenshot","set-title","source"]},render:{required:["out","set-dir"],optional:[]},"resolve-ids":{required:["set-dir","slugs"],optional:[]}};function Q(e){let{positionals:t,flags:r}=J(e,je),[s,n]=t;if(s===void 0)throw new Error(`a command is required: ${T.join(", ")}`);if(!Te(s))throw new Error(`unknown command "${s}"; expected one of ${T.join(", ")}`);if(n!==void 0)throw new Error(`unexpected argument: ${n}`);let i=r.filter(u=>u.name==="note"),d=X(r.filter(u=>u.name!=="note")),{required:a,optional:c}=Me[s];if(i.length>0&&!c.includes("note"))throw new Error(`${s} does not take --note`);for(let[u,h]of Object.entries(d)){if(!a.includes(u)&&!c.includes(u))throw new Error(`${s} does not take --${u}`);if(h==="")throw new Error(`--${u} requires a value`)}for(let u of a)if(d[u]===void 0)throw new Error(`${s} requires --${u}`);let f=i.map(u=>Ce(u.value??""));return{command:s,values:d,notes:f}}o(Q,"parseArgs");function P(e){return e===void 0?[]:e.split(",").map(t=>t.trim()).filter(t=>t!=="")}o(P,"parseInputs");function p(e,t){let r=e[t];if(r===void 0)throw new Error(`--${t} is missing after parsing`);return r}o(p,"requireFlag");function v(e){return Ae.resolve(p(e,"set-dir"))}o(v,"resolveSetDir");function Te(e){return Re.has(e)}o(Te,"isCommand");function Ce(e){let t=e.indexOf(":"),r=t===-1?"":e.slice(0,t).trim(),s=t===-1?"":e.slice(t+1).trim();if(r===""||s==="")throw new Error(`--note "${e}" must have the form "<label>: <value>"`);return{label:r,value:s}}o(Ce,"parseNote");import{readFile as Fe}from"node:fs/promises";import oe from"node:path";import{copyFile as Oe,mkdir as _e,readFile as Le}from"node:fs/promises";import C from"node:path";var Z=Buffer.from([137,80,78,71,13,10,26,10]);async function ee(e){let t;try{t=await Le(e.sourcePath)}catch(n){if(b(n))return{ok:!1,error:"screenshot-not-found",message:`the screenshot ${e.sourcePath} does not exist`};throw n}if(!t.subarray(0,Z.length).equals(Z))return{ok:!1,error:"not-png",message:`${e.sourcePath} is not a PNG file`};let r=C.join("shots",`${e.slug}-v${e.version}.png`),s=C.join(e.setDir,r);return await _e(C.dirname(s),{recursive:!0}),await Oe(e.sourcePath,s),{ok:!0,shot:r}}o(ee,"intakeScreenshot");var Ve={"&":"&","<":"<",">":">",""":'"',"'":"'"};function te(e){return`${e} - Prototypes`}o(te,"formatIndexTitle");function re(e,t,r,s){return se(`${e} - ${w(t,r)} ${s}`)}o(re,"formatPrototypeTitle");function ne(e){let t=e.replaceAll(/<!--[\s\S]*?-->/g,"").replaceAll(/<svg[\s>][\s\S]*?<\/svg\s*>/gi,""),r=/<title(?:\s[^>]*)?>([\s\S]*?)<\/title\s*>/i.exec(t);return r?.[1]===void 0?null:se(r[1].replaceAll(/&(?:amp|lt|gt|quot|#39);/g,s=>Ve[s]??s))}o(ne,"readPageTitle");function se(e){return e.replaceAll(/\s+/g," ").trim()}o(se,"collapseWhitespace");function E(e){try{let{protocol:t}=new URL(e);return t==="https:"||t==="http:"}catch{return!1}}o(E,"isWebUrl");async function ie(e,t,r,s){let n=p(t,"slug");if(!N(n))return l("invalid-slug",`slug "${n}" must match [a-z0-9][a-z0-9-]{0,39}`);let i=p(t,"url");if(!E(i))return l("invalid-url",`--url "${i}" is not an http or https URL`);let d=await y(e);if(d.kind==="invalid")return l("invalid-manifest",d.message);let a=d.kind==="ok"?d.manifest:null,c=t["set-title"]??a?.title;if(c===void 0)return l("missing-set-title","the first registration in a set requires --set-title");let f=Ue(a,n,t.number);if(typeof f!="number")return f;let u=M(a,n),h=p(t,"title"),O=t.source,_=await We(O,re(c,f,u,h));if(_!==null)return _;let j=await De(t.screenshot,e,n,u);if("error"in j)return j;let L={slug:n,number:f,version:u,registeredAt:s.toISOString(),title:h,url:i,source:O??null,lens:t.lens??null,inputs:P(t.inputs),description:t.description??null,notes:r,shot:j.shot},fe={title:c,indexUrl:a?.indexUrl??null,summary:a?.summary??null,entries:[...a?.entries??[],L]};return{ok:!0,command:"register",manifestPath:await S(e,fe),entry:L}}o(ie,"register");async function We(e,t){if(e===void 0)return null;let r;try{r=await Fe(oe.resolve(e),"utf8")}catch(i){if(qe(i))return l("source-not-found",`--source "${e}" is not a readable file`);throw i}let s=ne(r);if(s===t)return null;let n=s===null?"found no <title>":`found "${s}"`;return l("title-mismatch",`the source's <title> must be "${t}"; ${n}`)}o(We,"checkSourceTitle");function qe(e){return e instanceof Error&&"code"in e&&(e.code==="ENOENT"||e.code==="EISDIR")}o(qe,"isFileAbsenceError");function Ue(e,t,r){let s=H(e,t);if(r===void 0)return s;let n=Number(r);if(!Number.isSafeInteger(n)||n<1)return l("number-conflict",`--number "${r}" must be a positive integer`);let i=e?.entries??[];if(i.some(a=>a.slug===t))return s===n?n:l("number-conflict",`slug "${t}" is number ${s}, not ${n}`);let d=i.find(a=>a.number===n);return d===void 0?n:l("number-conflict",`number ${n} belongs to slug "${d.slug}"`)}o(Ue,"resolveRegistrationNumber");async function De(e,t,r,s){if(e===void 0)return{shot:null};let n=await ee({sourcePath:oe.resolve(e),setDir:t,slug:r,version:s});return n.ok?{shot:n.shot}:l(n.error,n.message)}o(De,"storeScreenshot");var ze=5e3,Be={fetch,evaluate:Ke};async function ae(e,t=Be){if(!E(e))return l("invalid-url",`--endpoint "${e}" is not an http or https URL`);let r=e.replace(/\/+$/,""),s;try{s=await(await t.fetch(`${r}/json/list`)).json()}catch{return l("endpoint-unreachable",`${r}/json/list did not return a target list`)}let n=Ge(s),i=await Promise.all(n.map(async c=>({target:c,answered:await t.evaluate(c.webSocketUrl,ze)}))),d=[],a=[];for(let{target:c,answered:f}of i){let u={id:c.id,url:c.url};if(f){d.push(u);continue}try{await t.fetch(`${r}/json/close/${encodeURIComponent(c.id)}`)}catch{return l("endpoint-unreachable",`${r}/json/close/${c.id} did not answer`)}a.push(u)}return{ok:!0,command:"probe-targets",closed:a,answered:d}}o(ae,"probeTargets");async function Ke(e,t,r=s=>new WebSocket(s)){return new Promise(s=>{let n=r(e),i=setTimeout(()=>d(!1),t);function d(a){clearTimeout(i),n.close(),s(a)}o(d,"settle"),n.addEventListener("open",()=>{n.send(JSON.stringify({id:1,method:"Runtime.evaluate",params:{expression:"1"}}))}),n.addEventListener("message",a=>{let c=Ye(a);c!==void 0&&c.id===1&&d(!c.isError)}),n.addEventListener("error",()=>d(!1))})}o(Ke,"evaluateOverWebSocket");function Ge(e){if(!Array.isArray(e))return[];let t=[];for(let r of e){if(!g(r)||r.type!=="page")continue;let{id:s,url:n,webSocketDebuggerUrl:i}=r;typeof s=="string"&&typeof i=="string"&&t.push({id:s,url:typeof n=="string"?n:"",webSocketUrl:i})}return t}o(Ge,"parsePageTargets");function Ye(e){if(typeof e.data!="string")return;let t;try{t=JSON.parse(e.data)}catch{return}if(g(t))return{id:t.id,isError:t.error!==void 0}}o(Ye,"parseReply");var He="verdicts";var de=`(() => {
|
|
55
55
|
'use strict';
|
|
56
|
-
const COLLECTION = '${
|
|
56
|
+
const COLLECTION = '${He}';
|
|
57
57
|
const grid = document.getElementById('grid');
|
|
58
58
|
const summary = document.getElementById('summary');
|
|
59
59
|
const status = document.getElementById('status');
|
|
@@ -328,14 +328,14 @@ var oe=Object.defineProperty;var i=(e,t)=>oe(e,"name",{value:t,configurable:!0})
|
|
|
328
328
|
render();
|
|
329
329
|
connect().catch(() => setStatus('Verdicts could not be loaded.'));
|
|
330
330
|
})();
|
|
331
|
-
`;var
|
|
332
|
-
`)}
|
|
333
|
-
`)}
|
|
334
|
-
:root { color-scheme: light; ${
|
|
331
|
+
`;var Je=["accent","chip","control-border","on-accent","page","reject-bg","reject-text","surface","text","text-muted","winner-bg","winner-border","winner-text"],Xe={dark:{accent:"#8cb6ff",chip:"#2a2f39","control-border":"#8790a3","on-accent":"#0b1730",page:"#111317","reject-bg":"#3f1717","reject-text":"#ffb8b8",surface:"#1b1e25",text:"#e7e9ee","text-muted":"#b0b6c3","winner-bg":"#3b2d06","winner-border":"#d9a43a","winner-text":"#ffd98a"},light:{accent:"#1d5bbf",chip:"#e9ecf1","control-border":"#6b7385","on-accent":"#ffffff",page:"#f4f5f7","reject-bg":"#fbe4e4","reject-text":"#8f1d1d",surface:"#ffffff",text:"#1b1f27","text-muted":"#4a5160","winner-bg":"#fff1c9","winner-border":"#a06c00","winner-text":"#5c3d00"}};function I(e){return Je.map(t=>`--${t}: ${Xe[e][t]};`).join(" ")}o(I,"renderTokenDeclarations");var ce=12e6,A=16e6;function le(e){let t=m(e.title),r=e.cards.length;return[`<title>${m(te(e.title))}</title>`,`<style>${tt()}</style>`,"<main>","<header>",`<h1>${t}</h1>`,...e.summary===null?[]:[rt(e.summary)],`<p class="summary" id="summary">${r} ${r===1?"prototype":"prototypes"}</p>`,"</header>",'<div class="toolbar">','<label class="toggle" id="rejected-toggle" hidden><input type="checkbox" id="show-rejected" checked> Show rejected</label>','<p class="hint" id="shortcuts" hidden>On a focused card: <kbd>\u2190</kbd> <kbd>\u2192</kbd> <kbd>\u2191</kbd> <kbd>\u2193</kbd> move between cards \xB7 <kbd>x</kbd> reject \xB7 <kbd>w</kbd> winner \xB7 <kbd>1\u20139</kbd> rank</p>','<p class="status" id="status" role="status" aria-live="polite"></p>',"</div>",'<div class="grid" id="grid">',...e.cards.map(s=>Ze(s,r)),"</div>","</main>",`<script>${de}</script>`,""].join(`
|
|
332
|
+
`)}o(le,"renderIndexPage");function m(e){return e.replaceAll("&","&").replaceAll("<","<").replaceAll(">",">").replaceAll('"',""").replaceAll("'","'")}o(m,"escapeHtml");function Qe(e){let t=Date.parse(e);if(Number.isNaN(t))return e;let r=new Date(t).toISOString();return`${r.slice(0,10)} ${r.slice(11,16)} UTC`}o(Qe,"formatTimestamp");function Ze(e,t){let{entry:r}=e,s=m(r.slug),n=m(r.title),i=m(r.url),d=`title-${s}`,a=e.shot===null?`<span class="placeholder">No screenshot for v${r.version}</span>`:`<img src="data:image/png;base64,${e.shot.toString("base64")}" alt="Screenshot of ${n}">`,c=[...r.lens===null?[]:[`<li class="chip">Lens: ${m(r.lens)}</li>`],...r.inputs.map(u=>`<li class="chip">${m(u)}</li>`)],f=Array.from({length:t},(u,h)=>`<option value="${h+1}">${h+1}</option>`);return[`<article class="card" tabindex="0" aria-labelledby="${d}" data-slug="${s}" data-number="${r.number}" data-id="${w(r.number,r.version)}" data-title="${n}" data-registered="${m(r.registeredAt)}">`,`<a class="thumb" href="${i}" target="_blank" rel="noopener" tabindex="-1" aria-hidden="true">${a}</a>`,'<div class="body">','<div class="badges" data-role="badges"></div>',`<h2 id="${d}"><a href="${i}" target="_blank" rel="noopener">${w(r.number,r.version)} ${n}</a></h2>`,`<p class="meta">${s} \xB7 ${m(Qe(r.registeredAt))}</p>`,...c.length===0?[]:[`<ul class="chips">${c.join("")}</ul>`],...r.description===null?[]:[`<p class="description">${m(r.description)}</p>`],...r.notes.length===0?[]:[et(r.notes)],'<div class="controls" data-role="controls" hidden>',`<button type="button" data-action="reject" aria-pressed="false" aria-describedby="${d}">Reject</button>`,`<label class="rank">Rank <select data-action="rank" aria-describedby="${d}"><option value="">None</option>${f.join("")}</select></label>`,`<button type="button" data-action="winner" aria-pressed="false" aria-describedby="${d}">Winner</button>`,"</div>","</div>","</article>"].join(`
|
|
333
|
+
`)}o(Ze,"renderCard");function et(e){return`<dl class="notes">${e.map(r=>`<dt>${m(r.label)}</dt><dd>${m(r.value)}</dd>`).join("")}</dl>`}o(et,"renderNotes");function tt(){return`
|
|
334
|
+
:root { color-scheme: light; ${I("light")} }
|
|
335
335
|
@media (prefers-color-scheme: dark) {
|
|
336
|
-
:root:not([data-theme="light"]) { color-scheme: dark; ${
|
|
336
|
+
:root:not([data-theme="light"]) { color-scheme: dark; ${I("dark")} }
|
|
337
337
|
}
|
|
338
|
-
:root[data-theme="dark"] { color-scheme: dark; ${
|
|
338
|
+
:root[data-theme="dark"] { color-scheme: dark; ${I("dark")} }
|
|
339
339
|
* { box-sizing: border-box; }
|
|
340
340
|
body { margin: 0; background: var(--page); color: var(--text); font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
|
|
341
341
|
main { max-width: 1280px; margin: 0 auto; padding: 24px 16px 48px; }
|
|
@@ -383,6 +383,6 @@ button, select { min-height: 32px; padding: 4px 10px; border: 1px solid var(--co
|
|
|
383
383
|
button[aria-pressed="true"] { border-color: var(--accent); background: var(--accent); color: var(--on-accent); }
|
|
384
384
|
button:disabled, select:disabled { cursor: not-allowed; }
|
|
385
385
|
@media (prefers-reduced-motion: reduce) { * { scroll-behavior: auto !important; transition: none !important; } }
|
|
386
|
-
`}
|
|
387
|
-
`),e.ok||(
|
|
388
|
-
`)
|
|
386
|
+
`}o(tt,"renderStyles");function rt(e){let t=e.try.map(s=>`<li>${m(s)}</li>`);return`<section class="set-summary" aria-label="Set summary"><dl>${[`<dt>Shared</dt><dd>${m(e.shared)}</dd>`,...e.changes===null?[]:[`<dt>Changed in this round</dt><dd>${m(e.changes)}</dd>`],...t.length===0?[]:[`<dt>Try in each</dt><dd><ol>${t.join("")}</ol></dd>`]].join("")}</dl></section>`}o(rt,"renderSummary");async function ot(){try{let e=await it({argv:$.argv.slice(2),now:new Date});$.stdout.write(`${JSON.stringify(e,null,2)}
|
|
387
|
+
`),e.ok||($.exitCode=1)}catch(e){$.stderr.write(`index-prototypes: ${x(e)}
|
|
388
|
+
`),$.exit(1)}}o(ot,"main");q(import.meta.url,"index-prototypes")&&await ot();async function it(e){let t;try{t=Q(e.argv)}catch(r){return l("invalid-args",x(r))}switch(t.command){case"copy-probe":return{ok:!0,command:"copy-probe",function:D};case"describe-set":return at(v(t.values),R.resolve(p(t.values,"file")));case"probe-targets":return ae(p(t.values,"endpoint"));case"record-index":return lt(v(t.values),p(t.values,"url"));case"register":return ie(v(t.values),t.values,t.notes,e.now);case"render":return ut(v(t.values),R.resolve(p(t.values,"out")));case"resolve-ids":return ft(v(t.values),p(t.values,"slugs"));default:{let r=t.command;throw new Error(`unhandled command: ${String(r)}`)}}}o(it,"runIndexPrototypes");async function at(e,t){let r;try{r=await ue(t,"utf8")}catch(a){if(b(a))return l("summary-not-found",`${t} does not exist`);throw a}let s;try{s=JSON.parse(r)}catch{return l("invalid-summary",`${t} is not valid JSON`)}let n=dt(s);if(typeof n=="string")return l("invalid-summary",`${t}: ${n}`);let i=await y(e);return i.kind==="missing"?l("manifest-not-found",`${e} does not contain a manifest; register a prototype first`):i.kind==="invalid"?l("invalid-manifest",i.message):{ok:!0,command:"describe-set",manifestPath:await S(e,{...i.manifest,summary:n}),summary:n}}o(at,"describeSet");function dt(e){if(!g(e))return'expected an object with "shared", "changes", and "try"';let{shared:t,changes:r,try:s}=e;if(typeof t!="string"||t.trim()==="")return'"shared" must be a non-empty string';if(r!=null&&typeof r!="string")return'"changes" must be a string or null';if(!Array.isArray(s)||s.some(i=>!(typeof i=="string"&&i.trim()!=="")))return'"try" must be a list of non-empty strings';let n=typeof r=="string"?r.trim():"";return{shared:t.trim(),changes:n===""?null:n,try:s.map(i=>i.trim())}}o(dt,"parseSummary");async function ct(e){try{return await ue(e)}catch(t){if(b(t))return null;throw t}}o(ct,"readShot");async function lt(e,t){if(!E(t))return l("invalid-url",`--url "${t}" is not an http or https URL`);let r=await y(e);return r.kind==="missing"?l("manifest-not-found",`${e} does not contain a manifest; register a prototype first`):r.kind==="invalid"?l("invalid-manifest",r.message):{ok:!0,command:"record-index",manifestPath:await S(e,{...r.manifest,indexUrl:t}),indexUrl:t}}o(lt,"recordIndex");async function ut(e,t){let r=await y(e);if(r.kind==="missing")return l("manifest-not-found",`${e} does not contain a manifest; register a prototype first`);if(r.kind==="invalid")return l("invalid-manifest",r.message);let{manifest:s}=r,n=[],i=[];for(let c of K(s)){let f=c.shot===null?null:await ct(R.join(e,c.shot));c.shot!==null&&f===null&&i.push(c.slug),n.push({entry:c,shot:f})}let d=le({title:s.title,summary:s.summary,cards:n}),a=Buffer.byteLength(d,"utf8");return a>A?l("page-too-large",`the page is ${a} bytes, over the ${A}-byte artifact cap`):(await nt(R.dirname(t),{recursive:!0}),await st(t,d,"utf8"),{ok:!0,command:"render",path:t,bytes:a,cards:n.length,title:s.title,indexUrl:s.indexUrl,missingShots:i,...a>ce&&{warning:`the page is ${a} bytes, approaching the ${A}-byte artifact cap`}})}o(ut,"render");async function ft(e,t){let r=P(t);if(r.length===0)return l("invalid-args","--slugs requires at least one slug");let s=r.find(d=>!N(d));if(s!==void 0)return l("invalid-slug",`slug "${s}" must match [a-z0-9][a-z0-9-]{0,39}`);if(new Set(r).size!==r.length)return l("invalid-args","--slugs names a slug twice");let n=await y(e);if(n.kind==="invalid")return l("invalid-manifest",n.message);let i=n.kind==="ok"?n.manifest:null;return{ok:!0,command:"resolve-ids",ids:G(i,r)}}o(ft,"resolveIdsForSlugs");export{it as runIndexPrototypes};
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: investigate-spike
|
|
3
|
+
description: Carry out a spike plan's investigation steps and deliver its findings artifact, with the closing post on the ticket when no triage round follows
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Investigate spike
|
|
8
|
+
|
|
9
|
+
Carry out a spike plan, the `## Investigation steps` / `## Deliverable` shape defined in [spike conventions](../_data/spike-conventions.md). A spike produces findings rather than a diff: The run ends with a findings artifact and either the offer of the closing post or, when the findings propose work, the recommendation of the triage round that offers it, not with commits. The skill re-resolves everything it needs from the environment, so it works the same in the session that produced the plan and in a fresh one.
|
|
10
|
+
|
|
11
|
+
## Arguments
|
|
12
|
+
|
|
13
|
+
| Flag | Effect | Default |
|
|
14
|
+
| ------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------- |
|
|
15
|
+
| `--plan=<path>` | The spike plan to carry out. | Auto-resolved (see below) |
|
|
16
|
+
| `--ticket=<source>` | The spike ticket that the plan serves. Resolved per [ticket source resolution](../_data/ticket-source-resolution.md). | Auto-resolved (see below) |
|
|
17
|
+
|
|
18
|
+
## The contract
|
|
19
|
+
|
|
20
|
+
The ticket's questions to answer and decisions to enable are the contract; the plan's steps are the mechanism by which they are met. When a step turns out not to serve them, or the facts found show a better line of inquiry, the questions decide.
|
|
21
|
+
|
|
22
|
+
The plan artifact is read-only. It records what was planned, and a later reader compares it against the findings to see how the investigation departed from it.
|
|
23
|
+
|
|
24
|
+
## Process
|
|
25
|
+
|
|
26
|
+
<!-- include: ../_partials/resolve-plan-and-ticket.md / -->
|
|
27
|
+
|
|
28
|
+
5. **Work the investigation steps in order.** A step is done when its **Answered when:** condition holds, or when it is recorded as a residual unknown. Record each step's answer and its evidence as you go: the code read, the command and its output, the measurement.
|
|
29
|
+
|
|
30
|
+
Run throwaway probes and prototypes in a scratch directory created with `mktemp -d "${TMPDIR:-/tmp}/spike.XXXXXX"`, using the absolute path that the call prints. Commit nothing to the branch: A prototype worth keeping becomes a follow-up ticket, not a commit.
|
|
31
|
+
|
|
32
|
+
The timebox is the spike's effort ceiling. Judge it by the effort spent against the ceiling that the plan states, and once a step clearly exceeds it, stop the step and record what it left unanswered as a residual unknown rather than extend it.
|
|
33
|
+
|
|
34
|
+
Raise a finding that redirects the investigation, such as a false premise in a step or a question that the ticket did not ask, to the user before proceeding, rather than departing from the plan silently.
|
|
35
|
+
|
|
36
|
+
A step that names the developer as its actor is yours to carry out, unless the step has a `**Residue:**` line: Perform every part that you can, and raise the residue as the one ask that it states. It is never a step for the developer to run, and the records of a step stay yours even when the step has a residue line.
|
|
37
|
+
|
|
38
|
+
6. **Save the findings** as a ticket-level `spike-findings` artifact per {skill:save-artifact}. It contains the answer to each of the ticket's questions to answer, the recommendation on each of its decisions to enable, the residual unknowns, and the evidence behind each answer. When the investigation proposes work, list each proposal as an item that a triage can dispose of.
|
|
39
|
+
|
|
40
|
+
7. **Report** the answers and the recommendations against the ticket's questions and decisions, naming any question left unanswered and any departure from the plan, and give the artifact's path.
|
|
41
|
+
|
|
42
|
+
8. **Close** with an action-items block:
|
|
43
|
+
- When the findings propose work, recommend {skill?:triage-spike-findings} with the artifact path and the ticket, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states.
|
|
44
|
+
- Otherwise, when a ticket governs the run, offer the closing post on it, with its body shown; on consent, post it as that section states.
|
|
45
|
+
|
|
46
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
47
|
+
|
|
48
|
+
<!-- include: ../_partials/option-format.md / -->
|