@webship.co/workspace-gatsby 1.0.7 → 1.0.9

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/README.md CHANGED
@@ -4,7 +4,8 @@ Gatsby for the [Webship Workspace](https://github.com/webship/workspace) dashboa
4
4
  makes a real Gatsby site from a starter in a container, builds it to a production build and serves
5
5
  it, a Gatsby CLI tool for the sites it built, the
6
6
  [Gatsby step pack](https://github.com/webship/gatsby-steps) wired into the workspace's testing
7
- setup, and two AI agents that know all of it.
7
+ setup, and its AI items — two agents, a skill, a
8
+ command and a prompt — each listed in the workspace folder of its kind.
8
9
 
9
10
  The workspace is container-based (DDEV by default): a Gatsby project is a row like any other, so
10
11
  the row menus the core draws (start, stop, launch, backup, clone, remove, tests) work on it; what
@@ -20,20 +21,47 @@ The plugin is made from the reference platform plugin,
20
21
  cd ~/workspace
21
22
  bash core/scripts/plugins.sh --require github:webship/workspace-gatsby # npm install into the dashboard
22
23
  bash core/scripts/plugins.sh --activate gatsby # plugins.gatsby in settings.yml
23
- bash core/scripts/plugins.sh --install gatsby # commands, functions, args, agents
24
+ bash core/scripts/plugins.sh --install gatsby # commands, functions, args, AI items
24
25
  bash core/scripts/plugins.sh --configure gatsby # nothing to configure: it has no settings file
25
26
  ```
26
27
 
27
28
  The same four steps are buttons on the dashboard's **Settings → Plugins** page. `--install` is
28
- idempotent. `--uninstall` removes what it placed; an agent you edited stays.
29
+ idempotent. `--uninstall` removes what it placed; an AI item you edited stays.
29
30
 
30
- The commands land in the sites folders that are in the workspace (`dev`, `test`, `sandboxes`,
31
- `demos`); the agents land in the AI Agents folder (`ai-agents/`) when the workspace has one, and are
32
- installed into `~/.claude/agents` from there like any other agent.
31
+ Everything the plugin carries lands in the folder it belongs to, when that folder is an active
32
+ workspace folder:
33
+
34
+ | What | Lands in |
35
+ | --- | --- |
36
+ | `cmd-gatsby-project.sh`, `cmd-tools-gatsby-cli.sh` | every active sites folder: `dev/`, `test/`, `sandboxes/`, `demos/` |
37
+ | The agents `gatsby-site-builder`, `gatsby-tester` | `ai-agents/` |
38
+ | The skill `gatsby-scenarios` | `ai-skills/` |
39
+ | The command `/gatsby-test` | `ai-commands/` |
40
+ | The prompt `gatsby-build-and-test` | `ai-prompts/` |
41
+
42
+ There they are listed like any other item of the folder, and installed into Claude Code from there.
33
43
 
34
44
  The agents, the builder's flags in the Build form and the step pack in the testing setup need a
35
45
  Webship Workspace after 1.0.6.
36
46
 
47
+ ## What it needs
48
+
49
+ A workspace starts empty, so the manifest says what else this plugin needs (`needs`):
50
+
51
+ - one sites folder, for the builder and the tool: `dev`, `test`, `sandboxes`, `demos` (`dev` is the one added when none is there). The folder also carries `cmd-tools-testing.sh` and the Users tools this plugin's hooks answer to.
52
+ - `ai-agents`, `ai-skills`, `ai-commands` and `ai-prompts`: the AI folders its agents, its skill, its command and its prompt are placed in.
53
+
54
+ `--require` says so, `--activate` and `--install` stop until the workspace has them, and `--with-needs` adds what is missing first:
55
+
56
+ ```bash
57
+ bash core/scripts/plugins.sh --activate gatsby --with-needs # dev and the four AI folders are required, activated and installed first
58
+ bash core/scripts/plugins.sh --install gatsby
59
+ ```
60
+
61
+ Everything the builder runs for a site runs in the site's own container, through the container tool the workspace already needs; the plugin asks for no command of its own on the machine.
62
+
63
+ A workspace that knows none of this (Webship Workspace 1.0.8 and older) ignores the keys: add a sites folder and the AI folders yourself, then `--install gatsby` again. A kind whose folder is not there is skipped, and the install says so.
64
+
37
65
  ## What the package holds
38
66
 
39
67
  | Path | What it is |
@@ -43,10 +71,14 @@ Webship Workspace after 1.0.6.
43
71
  | `scripts/functions/fun-gatsby.sh` | The bash functions behind both, sourced by bootstrap once installed; the names the core's tools look for (`set_gatsby_users`, `add_gatsby_users`, `cancel_gatsby_users`, `testing_configure_gatsby`) |
44
72
  | `scripts/args/arg-gatsby.sh`, `arg-gatsby-cli.sh` | Their argparse; the Build form draws the builder's flags from the first |
45
73
  | `testing/site.feature` | The first feature a Gatsby project gets when testing is set up |
46
- | `agents/gatsby-site-builder.md` | The agent that builds and maintains Gatsby sites with these commands |
47
- | `agents/gatsby-tester.md` | The agent that writes and runs scenarios with the Gatsby step pack |
74
+ | `ai/agents/gatsby-site-builder.md` | The agent that builds and maintains Gatsby sites with these commands |
75
+ | `ai/agents/gatsby-tester.md` | The agent that writes and runs scenarios with the Gatsby step pack |
76
+ | `ai/skills/gatsby-scenarios/` | The skill: the step pack's phrases by area, the traps found on a real site, three example features |
77
+ | `ai/commands/gatsby-test.md` | The slash command `/gatsby-test <site>`: set up, match every step, run, report |
78
+ | `ai/prompts/gatsby-build-and-test.md` | A prompt: the whole launch command for a new session |
48
79
  | `src/index.ts` | `register(api)`: what the assistant is told about Gatsby here |
49
80
  | `features/gatsby.feature` | Scenarios for the dashboard's own browser suite |
81
+ | `docs/plugin-items-pattern.md` | How a plugin carries its own commands and AI items, and how to prove it |
50
82
 
51
83
  The `workspacePlugin` block in `package.json` is the manifest the installer reads.
52
84
 
@@ -124,25 +156,41 @@ webship-js's own, and places `tests/features/site.feature` when the project has
124
156
  page as a production build, rendered and hydrated, its page data and its 404 page. There is no
125
157
  users registry. Run it again and it adds what is missing and keeps what you changed.
126
158
 
127
- ## The agents
159
+ ## The AI items
128
160
 
129
- | Agent | Use it to |
130
- | --- | --- |
131
- | `gatsby-site-builder` | Make a site from a starter, build it again, update, maintain or remove it with the commands above, in containers only |
132
- | `gatsby-tester` | Set the testing stack up, look at the built site in the Playwright MCP browser first, write scenarios from the pack's steps and run them; it never creates an account in a suite and never writes a platform name into a step phrase |
161
+ `ai/` in the package holds one folder per kind, the manifest's `ai` block names each item, and
162
+ `--install` places it in the workspace folder of that kind.
133
163
 
134
- After `--install` they are in the AI Agents folder of the dashboard; **Install** there puts one into
135
- `~/.claude/agents`, or from the command line:
164
+ | Kind | Item | Use it to |
165
+ | --- | --- | --- |
166
+ | Agent | `gatsby-site-builder` | Make a site from a starter, build it again, update, maintain or remove it with the commands above, in containers only |
167
+ | Agent | `gatsby-tester` | Set the testing stack up, look at the built site in the Playwright MCP browser first, write scenarios from the pack's steps and run them; it never creates an account in a suite and never writes a platform name into a step phrase |
168
+ | Skill | `gatsby-scenarios` | Write a scenario from phrases that exist: the pack's steps by area (the build and hydration, page data and the 404 page, client-side routing, images, the manifest), the traps found on a real site, and three features that pass on a site from the default starter |
169
+ | Command | `/gatsby-test <site> [feature or @tag]` | Run the suite of a site from inside a session: set up when missing, match every step, run against the production build, report what failed and why |
170
+ | Prompt | `gatsby-build-and-test` | Start a session that makes a site from a starter, builds and serves it, sets the testing stack up and runs the first feature |
171
+
172
+ After `--install` each is in its folder on the dashboard. **Install** there puts an agent, a skill
173
+ or a command into Claude Code (`~/.claude/agents`, `~/.claude/skills`, `~/.claude/commands`), or
174
+ from the command line:
136
175
 
137
176
  ```bash
138
- cd ~/workspace/ai-agents
139
- bash cmd-tools-ai-items.sh gatsby-tester --install
177
+ cd ~/workspace/ai-agents && bash cmd-tools-ai-items.sh gatsby-tester --install
178
+ cd ~/workspace/ai-skills && bash cmd-tools-ai-items.sh gatsby-scenarios --install
179
+ cd ~/workspace/ai-commands && bash cmd-tools-ai-items.sh gatsby-test --install
140
180
  ```
141
181
 
182
+ A prompt is not installed: it is the whole `claude …` launch command of a new session, and the
183
+ dashboard's **New screen** form lists it as a template. By hand, fill the placeholders in and run
184
+ the command of the file from the folder it names.
185
+
186
+ Every step phrase the items show is checked against the definitions of the step pack and of
187
+ webship-js (`tests/fixtures/step-definitions.txt`), and every command and flag against the
188
+ plugin's own.
189
+
142
190
  ## Develop it
143
191
 
144
192
  ```bash
145
193
  npm install # builds dist/ (TypeScript)
146
194
  npm run lint
147
- npm test # the manifest, the commands, the agents, the functions against a scaffolded project
195
+ npm test # the manifest, the commands, the AI items, the functions against a scaffolded project
148
196
  ```
@@ -108,3 +108,11 @@ folder; the database export it also tries has nothing to export and says so),
108
108
  | A 502 or 404 from the router | No production build yet (`--build`), or the server stopped (`--restart`). |
109
109
  | The old page after a change | The address serves the build: `--build`. |
110
110
  | `is not a Gatsby project` from the CLI tool | The project has no `.ddev/config.gatsby.yaml`: it was not built by this builder. |
111
+
112
+ ## What comes with you
113
+
114
+ The Gatsby plugin places these beside you, each in the workspace folder of its kind: the agent
115
+ `gatsby-tester` (`ai-agents/`), the skill `gatsby-scenarios` (`ai-skills/`), the command
116
+ `/gatsby-test <site>` (`ai-commands/`) and the prompt `gatsby-build-and-test` (`ai-prompts/`),
117
+ which is this agent's whole first job as a launch command: make the site from a starter, build
118
+ and serve it, set the testing stack up, run the first feature.
@@ -20,8 +20,8 @@ tools:
20
20
 
21
21
  # gatsby-tester
22
22
 
23
- You test Gatsby sites in a Webship Workspace (`~/workspace`) with
24
- [webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Gatsby step
23
+ You test Gatsby sites in a Webship Workspace (`~/workspace`), a container-based workspace (DDEV
24
+ by default), with [webship-js](https://github.com/webship/webship-js) (Playwright and Cucumber) and its Gatsby step
25
25
  pack, [`@webship-js/gatsby-steps`](https://github.com/webship/gatsby-steps). The suite lives in
26
26
  the project (`cucumber.js`, `tests/features/`, `tests/step-definitions/`), next to the site's
27
27
  `site/` folder and not in it, and runs in the project's container against the production build
@@ -85,8 +85,9 @@ service that has accounts, that service is tested with its own pack, on its own
85
85
  - **No password and no secret in a feature file.**
86
86
  - **No platform name in a step phrase.** A step says what a person does or sees: `the site should
87
87
  be a production build`, `I should see a hydrated page`, `I click the link "…" without a full
88
- page reload`. The pack also has steps that name the generator of the page; a feature of yours
89
- does not need them, and a custom step you write never names the product.
88
+ page reload`. The name of the generator is a value of a step, never a part of its phrase: `the
89
+ page generator should start with "Gatsby"`, `the page generator version should start with
90
+ "<version>"`. A custom step you write never names the product.
90
91
  - **No CSS selector in a scenario when a step of the pack says it.** `I should see an optimized
91
92
  image`, not a selector of the image wrapper.
92
93
  - **A custom step is the last resort.** Look in the pack and in webship-js first. If one is really
@@ -114,3 +115,13 @@ Feature: The home page
114
115
 
115
116
  Check every phrase against the installed definitions before you run it: the pack moves, and a phrase
116
117
  from memory is a guess.
118
+
119
+ ## What comes with you
120
+
121
+ The Gatsby plugin places these beside you, each in the workspace folder of its kind:
122
+
123
+ | Item | Where | What it is for |
124
+ | --- | --- | --- |
125
+ | `gatsby-scenarios` (skill) | `ai-skills/` | The pack's phrases by area, the traps found on a real site, and three example features that pass on a site from the default starter |
126
+ | `/gatsby-test <site>` (command) | `ai-commands/` | The run itself: set up when missing, check the build, match every step, run, report |
127
+ | `gatsby-build-and-test` (prompt) | `ai-prompts/` | A new session that makes a site with `gatsby-site-builder`'s commands and runs its first feature |
@@ -0,0 +1,92 @@
1
+ ---
2
+ description: Test a Gatsby site of the Webship Workspace with webship-js and the Gatsby step pack — set the testing stack up when it is missing, check which production build is served, match every step, run the suite (or one feature, or one tag) in the site's container, and report what failed and why.
3
+ argument-hint: '<site> [tests/features/<name>.feature | @tag]'
4
+ ---
5
+
6
+ # /gatsby-test
7
+
8
+ Test the Gatsby site named in: `$ARGUMENTS`
9
+
10
+ The first word is the site (its folder name in a sites folder of the workspace). What follows, if
11
+ anything, narrows the run: a path that starts with `tests/features/` is one feature (or one
12
+ folder of features), a word that starts with `@` is a tag expression. With nothing after the site,
13
+ the whole suite runs. With no site at all, stop and ask for one: list the candidates with
14
+ `ls -d ~/workspace/*/*/.ddev/config.gatsby.yaml`.
15
+
16
+ The workspace is container-based (DDEV by default) and everything below runs in the site's
17
+ container through the workspace's own command. Never run `npx cucumber-js`, `npx playwright`,
18
+ `gatsby`, `node` or `npm` on the host for a site.
19
+
20
+ ## 1. Find the site
21
+
22
+ ```bash
23
+ ls ~/workspace/*/<site>/.ddev/config.gatsby.yaml
24
+ ```
25
+
26
+ `<folder>` is the sites folder the site is in (`dev`, `test`, `sandboxes`, `demos`). If the file is
27
+ not there, stop: this command is for a site built with `cmd-gatsby-project.sh`, which writes it. If
28
+ `<folder>` has no `cmd-tools-testing.sh`, stop and say that the folder is not a sites folder of
29
+ this workspace.
30
+
31
+ ## 2. Make sure the build is served and the testing stack is there
32
+
33
+ ```bash
34
+ cd ~/workspace/<folder>
35
+ bash cmd-tools-gatsby-cli.sh <site>
36
+ grep -c "@webship-js/gatsby-steps" <site>/cucumber.js
37
+ ```
38
+
39
+ The first prints the version, the production build with the time it was made, and whether the
40
+ server runs. The suite tests that build, not the source. If the server is not running,
41
+ `bash cmd-tools-gatsby-cli.sh <site> --restart` starts it again. Do not build unasked: if the
42
+ source is newer than the build, say so in the report, with the command that builds
43
+ (`bash cmd-tools-gatsby-cli.sh <site> --build`).
44
+
45
+ If `cucumber.js` is missing or does not name the step pack, set the stack up (it adds what is
46
+ missing and keeps what was changed):
47
+
48
+ ```bash
49
+ bash cmd-tools-testing.sh <site>
50
+ ```
51
+
52
+ ## 3. Match every step, without a browser
53
+
54
+ ```bash
55
+ bash cmd-tools-testing.sh <site> --dry-run # the whole suite
56
+ bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature # one feature
57
+ bash cmd-tools-testing.sh <site> --dry-run --tags "@critical" # one tag
58
+ ```
59
+
60
+ Use the form that matches what was asked. An `Undefined` or `Ambiguous` step is a finding: name
61
+ the feature, the line and the phrase, show the closest phrase the pack defines
62
+ (`grep -hE "^(Given|When|Then)\(" <site>/node_modules/@webship-js/gatsby-steps/tests/step-definitions/*.steps.js`),
63
+ and stop before the real run.
64
+
65
+ ## 4. Run
66
+
67
+ ```bash
68
+ bash cmd-tools-testing.sh <site> --run # the whole suite
69
+ bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature # one feature
70
+ bash cmd-tools-testing.sh <site> --run --tags "@critical" # one tag
71
+ ```
72
+
73
+ Run it once. Do not add `--retry`, do not tag a scenario `@wip` and do not change a feature to
74
+ make the run pass.
75
+
76
+ ## 5. Report
77
+
78
+ Say, in this order:
79
+
80
+ 1. The site, its address (`https://<site>.ddev.site`), the build that was tested (when it was
81
+ made) and what was run (suite, feature or tag).
82
+ 2. The totals the run printed: scenarios and steps, passed and failed, and the time.
83
+ 3. For each failed scenario: the feature and line, the step that failed, the message, and what
84
+ it means for the site — a defect of the site, a scenario that asserts something the site never
85
+ did (a page of another starter, a link to another site), or the environment (the server was
86
+ stopped, the build is older than the source).
87
+ 4. Where the report is: `~/workspace/<folder>/<site>/tests/reports/`.
88
+
89
+ A failing suite is a result: report it as it is. The site has no accounts: never add one for a
90
+ scenario, and never write a platform name into a step phrase. For writing or fixing scenarios,
91
+ use the `gatsby-scenarios` skill or hand over to the `gatsby-tester` agent; for changing or building
92
+ the site, to `gatsby-site-builder`.
@@ -0,0 +1,26 @@
1
+ Make a Gatsby site from a starter in a sites folder, serve its production build and prove it with its first webship-js feature.
2
+
3
+ `claude` is the default launcher; the text between the triple quotes is plain and can be given to another AI CLI as it is.
4
+
5
+ ```
6
+ claude --permission-mode bypassPermissions """
7
+ Build a Gatsby site named <name> in this sites folder and test it with webship-js
8
+ # ~/workspace/<dev|test|sandboxes|demos> · https://<name>.ddev.site · container-based (DDEV by default)
9
+ # the builder deletes a project of the same name first: stop if <name> is a site somebody still needs
10
+ # nothing on the host: no gatsby, node, npm or npx outside the site's container
11
+ # a static site: no database and no accounts, and none is added to make a tool happy
12
+
13
+ 1. bash cmd-gatsby-project.sh <name> --install
14
+ (add --starter <url> for a starter other than the default one, and --ref <x> for a commit, a branch or a tag of it)
15
+ 2. bash cmd-tools-gatsby-cli.sh <name>
16
+ tell me the version, the address, how many pages the production build has and whether the server runs
17
+ 3. bash cmd-tools-testing.sh <name>
18
+ webship-js, the step pack and tests/features/site.feature
19
+ 4. bash cmd-tools-testing.sh <name> --dry-run --path tests/features/site.feature
20
+ 5. bash cmd-tools-testing.sh <name> --run --path tests/features/site.feature
21
+
22
+ If a command fails, show the line that failed and stop. Do not retry with other flags.
23
+ When the feature is green: the address, the version, how many scenarios and steps passed.
24
+ Then ask me whether to keep the site or remove it with: bash cmd-tools-remove.sh <name>
25
+ """
26
+ ```
@@ -0,0 +1,183 @@
1
+ ---
2
+ name: gatsby-scenarios
3
+ description: Write and run webship-js scenarios for a Gatsby site of the Webship Workspace with the Gatsby step pack (`@webship-js/gatsby-steps`) — the phrases of the pack by area (the production build and hydration, page data and the 404 page, client-side routing and the route announcer, images, the web app manifest), what a site from the default starter does, and the workspace command that runs them in the site's container against the build. Use when asked to "write a scenario for this Gatsby site", "test the links of the site", "which step is there for the 404 page", "check that the page is hydrated", or when a `.feature` file of a Gatsby project is being written or fixed.
4
+ argument-hint: '<site> [what to cover]'
5
+ ---
6
+
7
+ # gatsby-scenarios
8
+
9
+ Scenarios for a Gatsby site of a Webship Workspace (`~/workspace`, container-based, DDEV by
10
+ default), written from the steps of [`@webship-js/gatsby-steps`](https://github.com/webship/gatsby-steps)
11
+ and of [webship-js](https://github.com/webship/webship-js) itself, and run in the site's container
12
+ by the workspace's own command. It comes with the Gatsby plugin (`@webship.co/workspace-gatsby`),
13
+ like the builder (`cmd-gatsby-project.sh`), the Gatsby CLI tool (`cmd-tools-gatsby-cli.sh`) and the
14
+ agents `gatsby-site-builder` and `gatsby-tester`.
15
+
16
+ ## Where everything is
17
+
18
+ | What | Where |
19
+ | --- | --- |
20
+ | The site | `~/workspace/<folder>/<site>`, at `https://<site>.ddev.site` (`<folder>` is a sites folder: `dev`, `test`, `sandboxes`, `demos`) |
21
+ | The source of the site | `<site>/site/` (its own `package.json`, `gatsby-config.js`, `src/`) |
22
+ | What the address serves | The production build, `<site>/site/public` |
23
+ | The suite's configuration | `<site>/cucumber.js`: the step definitions it loads. There is no users registry: the site has no accounts |
24
+ | The features | `<site>/tests/features/*.feature` (`site.feature` is the first one the setup wrote) |
25
+ | The pack's steps | `<site>/node_modules/@webship-js/gatsby-steps/tests/step-definitions/*.steps.js` |
26
+ | webship-js's steps | `<site>/node_modules/webship-js/tests/step-definitions/*.js` |
27
+ | The reports | `<site>/tests/reports/` |
28
+
29
+ ## The order of work
30
+
31
+ 1. **Make sure the testing stack is there.** From the sites folder:
32
+ ```bash
33
+ cd ~/workspace/<folder>
34
+ bash cmd-tools-testing.sh <site>
35
+ ```
36
+ It adds webship-js, the step pack and `tests/features/site.feature`. It is safe to run again:
37
+ it adds what is missing and keeps what was changed.
38
+ 2. **Make sure the build is the one you mean to test.** The suite tests the build, not the
39
+ source:
40
+ ```bash
41
+ bash cmd-tools-gatsby-cli.sh <site> # the version, the build and when it was made, the server
42
+ bash cmd-tools-gatsby-cli.sh <site> --build # after a change to the source
43
+ ```
44
+ 3. **Read the installed steps before writing a phrase.** They are the source of truth: the pack
45
+ moves, and a phrase from memory is a guess.
46
+ ```bash
47
+ cd ~/workspace/<folder>/<site>
48
+ grep -hE "^(Given|When|Then)\(" node_modules/@webship-js/gatsby-steps/tests/step-definitions/*.steps.js
49
+ ```
50
+ Every step carries a comment block with five examples above it; open the file when a phrase
51
+ is not obvious.
52
+ 4. **Look at the page first** (the Playwright MCP browser, a tab of your own): the titles, the
53
+ link texts and the addresses are the site's own.
54
+ 5. **Write the feature** in `<site>/tests/features/`, from phrases that exist (the lists below).
55
+ 6. **Match every step without a browser**, then run the feature, then the suite:
56
+ ```bash
57
+ cd ~/workspace/<folder>
58
+ bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature
59
+ bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature
60
+ bash cmd-tools-testing.sh <site> --run --tags "@critical"
61
+ bash cmd-tools-testing.sh <site> --run
62
+ ```
63
+ A dry run says `Undefined` for a phrase no definition matches: fix the phrase, do not write a
64
+ step for it.
65
+
66
+ ## No accounts
67
+
68
+ An Gatsby site is static: nobody logs in, and a scenario starts as a visitor
69
+ (`Given I am an anonymous user`, or straight at a page).
70
+
71
+ ## The phrases, by area
72
+
73
+ Each line is a phrase the pack defines, and each one passed on a site built with
74
+ `bash cmd-gatsby-project.sh <site> --install` (the default starter; the titles and the addresses
75
+ in quotes are that starter's). Most `should` steps also take the negative.
76
+
77
+ ### The build and hydration
78
+
79
+ ```gherkin
80
+ Given I am on the homepage
81
+ Then the site should be a production build
82
+ Then the page should be from the current build
83
+ Then I should see a hydrated page
84
+ Then there should be no hydration errors
85
+ Then the page title should be "Home | Gatsby Default Starter"
86
+ Then the page head should be set by the Head API
87
+ Then I should see "Welcome to" without JavaScript
88
+ ```
89
+
90
+ ### Page data and the 404 page
91
+
92
+ ```gherkin
93
+ Then the page-data for "/" should be available
94
+ Then the page-data for "/no-such-page/" should not be available
95
+ Then the 404 page should be available
96
+ Then I should not be on a 404 page
97
+ When I go to "/this-page-does-not-exist/"
98
+ Then I should be on a 404 page
99
+ Then I should be on the default 404 page
100
+ ```
101
+
102
+ ### Client-side routing
103
+
104
+ ```gherkin
105
+ When I click the link "Page 2" without a full page reload
106
+ Then the page should have a route announcer
107
+ Then the route announcer should announce "Hi from the second page"
108
+ When I go back without a full page reload
109
+ Then the page "/page-2/" should be prefetched
110
+ ```
111
+
112
+ ### Images and the manifest
113
+
114
+ ```gherkin
115
+ Then I should see an optimized image
116
+ Then the optimized image should be loaded
117
+ Then the optimized image should offer the "webp" format
118
+ Then the optimized image should have a placeholder
119
+ Then the manifest should be valid
120
+ ```
121
+
122
+ `I am an anonymous user`, `I am on the homepage`, `I go to "/page-2/"`, `I should see "<text>"`
123
+ and `the response status code should be 200` are webship-js's own steps; its status codes, links,
124
+ landmarks and accessibility audits are used as they are and never redefined for this platform.
125
+
126
+ ## Traps found on a real site
127
+
128
+ - **The route announcer step adds the first words itself.** The announcer of the site says
129
+ `Navigated to Hi from the second page`; the step is written with what follows `Navigated to`,
130
+ and that is the first heading of the page, not its title:
131
+ `Then the route announcer should announce "Hi from the second page"`. Written with the whole
132
+ sentence, or with the title `Page two`, it fails.
133
+ - **The 404 page of the default starter is the default 404 page.** `Then I should not be on the
134
+ default 404 page` fails until the site has a 404 page of its own; `Then I should be on a 404
135
+ page` is the step for both.
136
+ - **A title is the page's and the site's**: `Home | Gatsby Default Starter`,
137
+ `Page two | Gatsby Default Starter`. The step compares the whole title.
138
+ - **`Then the scroll position should be restored` was not proven on the default starter.** After
139
+ `When I scroll down 300`, a click on the link `Page 2` and a step back, the step said the page
140
+ was not scrolled when the link was clicked. Run it on a page whose link is further down before
141
+ relying on it.
142
+ - **A stale build passes or fails for the wrong reason.** After a change to `site/src`, nothing
143
+ changes at the address until `bash cmd-tools-gatsby-cli.sh <site> --build`.
144
+ - **The front page links to other sites.** The suite depends on this site only: assert the links
145
+ of the site (`Page 2`), and follow none that leaves it.
146
+
147
+ ## Rules
148
+
149
+ - **No platform name in a step phrase.** A step says what a person does or sees: `the site should
150
+ be a production build`, `I should see a hydrated page`. The name of the generator is a value of a
151
+ step, never a part of its phrase: `the page generator should start with "Gatsby"`,
152
+ `the page generator version should start with "<version>"`. A custom step never names the
153
+ product.
154
+ - **No account, no password, no secret in a feature file.** The site has no accounts, and a
155
+ service it talks to is tested with its own pack on its own project.
156
+ - **No selector when a step says it**: `I should see an optimized image`, not a selector of the
157
+ image.
158
+ - **The suite depends on this site only**, and changes nothing: a scenario reads the build, never
159
+ writes into `site/`, and never builds.
160
+ - **A custom step is the last resort**: look in the pack and in webship-js first, write it in
161
+ `<site>/tests/step-definitions/` with a comment block and examples, and say it may belong in
162
+ the pack.
163
+ - **Everything runs in the container**, through `cmd-tools-testing.sh`. Never `npx cucumber-js`
164
+ or `npx playwright` on the host.
165
+ - **A failing scenario is a result.** No `@wip`, no longer timeout, no looser assertion to turn a
166
+ run green: say what the site did.
167
+
168
+ ## Examples that run
169
+
170
+ `examples/` holds three features that pass on a site built with
171
+ `bash cmd-gatsby-project.sh <site> --install`. Copy one into the suite and run it:
172
+
173
+ ```bash
174
+ cp ~/workspace/ai-skills/gatsby-scenarios/examples/built-pages.feature ~/workspace/<folder>/<site>/tests/features/
175
+ cd ~/workspace/<folder>
176
+ bash cmd-tools-testing.sh <site> --run --path tests/features/built-pages.feature
177
+ ```
178
+
179
+ | Feature | What it shows |
180
+ | --- | --- |
181
+ | `examples/built-pages.feature` | The front page as a hydrated page of the current build, the page data the build wrote, an address with no page |
182
+ | `examples/routing.feature` | A link that changes the page without a full page reload, the route announcer, a prefetched page |
183
+ | `examples/images-and-manifest.feature` | The optimized image of the front page, the web app manifest, the text of the page without scripts |
@@ -0,0 +1,32 @@
1
+ Feature: The pages of the production build
2
+ As the owner of the site
3
+ I want every page to be served from the production build, rendered and hydrated
4
+ So that a build that came out broken is caught by the suite
5
+
6
+ # The titles and the addresses are the ones of the starter the builder uses by default:
7
+ # change them to the pages of the site.
8
+
9
+ Scenario: The front page is a hydrated page of the current build
10
+ Given I am an anonymous user
11
+ And I am on the homepage
12
+ Then the response status code should be 200
13
+ And the site should be a production build
14
+ And the page should be from the current build
15
+ And I should see a hydrated page
16
+ And there should be no hydration errors
17
+ And the page title should be "Home | Gatsby Default Starter"
18
+ And the page head should be set by the Head API
19
+
20
+ Scenario: The build wrote the data of each page
21
+ Given I am on the homepage
22
+ Then the page-data for "/" should be available
23
+ And the page-data for "/page-2/" should be available
24
+ And the page-data for "/no-such-page/" should not be available
25
+
26
+ Scenario: An address with no page answers 404 with the 404 page of the site
27
+ Given I am on the homepage
28
+ Then the 404 page should be available
29
+ And I should not be on a 404 page
30
+ When I go to "/this-page-does-not-exist/"
31
+ Then I should be on a 404 page
32
+ And the response status code should be 404
@@ -0,0 +1,19 @@
1
+ Feature: The images, the manifest and the page without scripts
2
+ As the owner of the site
3
+ I want the images to be optimized, the manifest to be valid and the text to be in the page itself
4
+ So that the site loads well and reads without scripts
5
+
6
+ Scenario: The front page shows an optimized image
7
+ Given I am on the homepage
8
+ Then I should see an optimized image
9
+ And the optimized image should be loaded
10
+ And the optimized image should offer the "webp" format
11
+ And the optimized image should have a placeholder
12
+
13
+ Scenario: The site has a valid web app manifest
14
+ Given I am on the homepage
15
+ Then the manifest should be valid
16
+
17
+ Scenario: The text of the front page is in the page before any script runs
18
+ Given I am on the homepage
19
+ Then I should see "Welcome to" without JavaScript
@@ -0,0 +1,17 @@
1
+ Feature: A visitor moves between the pages without a full page reload
2
+ As the owner of the site
3
+ I want the links of the site to change the page on the client, and to say so to a screen reader
4
+ So that a link that started to reload the whole page is caught by the suite
5
+
6
+ Scenario: A link changes the page on the client and the page is announced
7
+ Given I am on the homepage
8
+ When I click the link "Page 2" without a full page reload
9
+ Then the page title should be "Page two | Gatsby Default Starter"
10
+ And the page should have a route announcer
11
+ And the route announcer should announce "Hi from the second page"
12
+ When I go back without a full page reload
13
+ Then the page title should be "Home | Gatsby Default Starter"
14
+
15
+ Scenario: The front page prefetches the page its link leads to
16
+ Given I am on the homepage
17
+ Then the page "/page-2/" should be prefetched
@@ -3,9 +3,9 @@
3
3
  *
4
4
  * What the package carries is placed by the installer from the manifest: the builder and the
5
5
  * Gatsby CLI tool in the sites folders, their functions and argparse under
6
- * core/scripts/plugins/gatsby/, the agents in the AI Agents folder. The dashboard needs nothing
6
+ * core/scripts/plugins/gatsby/, its AI items (ai/) in the AI folders. The dashboard needs nothing
7
7
  * drawn for it: the builder is in the Build list because it is a cmd-*-project.sh, the row menus
8
- * are the core's, the agents are listed like any other. What register() adds is what the
8
+ * are the core's, the AI items are listed like any other. What register() adds is what the
9
9
  * assistant is told.
10
10
  *
11
11
  * Everything the dashboard is asked for goes through `api`; this package requires nothing from the
@@ -18,6 +18,12 @@ export declare const PLATFORM = "gatsby";
18
18
  export declare const COMMANDS: string[];
19
19
  /** The agents the installer places in the AI Agents folder. */
20
20
  export declare const AGENTS: string[];
21
+ /** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
22
+ export declare const SKILLS: string[];
23
+ /** The slash command the installer places in the AI Commands folder. */
24
+ export declare const AI_COMMANDS: string[];
25
+ /** The prompt the installer places in the AI Prompts folder: a whole launch command for a new session. */
26
+ export declare const PROMPTS: string[];
21
27
  /** What the assistant is told about Gatsby in this workspace. */
22
28
  export declare function assistantContext(): string;
23
29
  export declare function register(api: PluginApi): void;
package/dist/src/index.js CHANGED
@@ -4,16 +4,16 @@
4
4
  *
5
5
  * What the package carries is placed by the installer from the manifest: the builder and the
6
6
  * Gatsby CLI tool in the sites folders, their functions and argparse under
7
- * core/scripts/plugins/gatsby/, the agents in the AI Agents folder. The dashboard needs nothing
7
+ * core/scripts/plugins/gatsby/, its AI items (ai/) in the AI folders. The dashboard needs nothing
8
8
  * drawn for it: the builder is in the Build list because it is a cmd-*-project.sh, the row menus
9
- * are the core's, the agents are listed like any other. What register() adds is what the
9
+ * are the core's, the AI items are listed like any other. What register() adds is what the
10
10
  * assistant is told.
11
11
  *
12
12
  * Everything the dashboard is asked for goes through `api`; this package requires nothing from the
13
13
  * dashboard's own files, so it can be installed from npm and removed without a trace.
14
14
  */
15
15
  Object.defineProperty(exports, "__esModule", { value: true });
16
- exports.AGENTS = exports.COMMANDS = exports.PLATFORM = void 0;
16
+ exports.PROMPTS = exports.AI_COMMANDS = exports.SKILLS = exports.AGENTS = exports.COMMANDS = exports.PLATFORM = void 0;
17
17
  exports.assistantContext = assistantContext;
18
18
  exports.register = register;
19
19
  /** The plugin's name, which its functions are named after. */
@@ -22,6 +22,12 @@ exports.PLATFORM = 'gatsby';
22
22
  exports.COMMANDS = ['cmd-gatsby-project.sh', 'cmd-tools-gatsby-cli.sh'];
23
23
  /** The agents the installer places in the AI Agents folder. */
24
24
  exports.AGENTS = ['gatsby-site-builder', 'gatsby-tester'];
25
+ /** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
26
+ exports.SKILLS = ['gatsby-scenarios'];
27
+ /** The slash command the installer places in the AI Commands folder. */
28
+ exports.AI_COMMANDS = ['gatsby-test'];
29
+ /** The prompt the installer places in the AI Prompts folder: a whole launch command for a new session. */
30
+ exports.PROMPTS = ['gatsby-build-and-test'];
25
31
  /** What the assistant is told about Gatsby in this workspace. */
26
32
  function assistantContext() {
27
33
  return [
@@ -33,6 +39,8 @@ function assistantContext() {
33
39
  '`--build` builds and serves it again after a change, `--update` updates its packages, `--restart` starts its server again.',
34
40
  '`bash cmd-tools-testing.sh <name>` sets up webship-js with the Gatsby step pack; `--run` runs the suite against the build.',
35
41
  `For Gatsby work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
42
+ `The plugin also places the skill ${exports.SKILLS.map((a) => `\`${a}\``).join(', ')} (the step pack's phrases, by area) in ai-skills/,`,
43
+ `the command ${exports.AI_COMMANDS.map((a) => `\`/${a} <site>\``).join(', ')} in ai-commands/ and the prompt ${exports.PROMPTS.map((a) => `\`${a}\``).join(' and ')} in ai-prompts/.`,
36
44
  'Never run gatsby, node or npm on the host for a project.',
37
45
  ].join(' ');
38
46
  }
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAcH,4CAYC;AAED,4BAEC;AA1BD,8DAA8D;AACjD,QAAA,QAAQ,GAAG,QAAQ,CAAC;AAEjC,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AAE7E,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;AAE/D,iEAAiE;AACjE,SAAgB,gBAAgB;IAC9B,OAAO;QACL,4FAA4F;QAC5F,kGAAkG;QAClG,sHAAsH;QACtH,uGAAuG;QACvG,oHAAoH;QACpH,4HAA4H;QAC5H,4HAA4H;QAC5H,4CAA4C,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QAC1F,0DAA0D;KAC3D,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,SAAgB,QAAQ,CAAC,GAAc;IACrC,GAAG,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;AAC5C,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAuBH,4CAcC;AAED,4BAEC;AArCD,8DAA8D;AACjD,QAAA,QAAQ,GAAG,QAAQ,CAAC;AAEjC,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;AAE7E,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;AAE/D,iGAAiG;AACpF,QAAA,MAAM,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAE3C,wEAAwE;AAC3D,QAAA,WAAW,GAAG,CAAC,aAAa,CAAC,CAAC;AAE3C,0GAA0G;AAC7F,QAAA,OAAO,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAEjD,iEAAiE;AACjE,SAAgB,gBAAgB;IAC9B,OAAO;QACL,4FAA4F;QAC5F,kGAAkG;QAClG,sHAAsH;QACtH,uGAAuG;QACvG,oHAAoH;QACpH,4HAA4H;QAC5H,4HAA4H;QAC5H,4CAA4C,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QAC1F,oCAAoC,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,oDAAoD;QAChI,eAAe,mBAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,mCAAmC,eAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB;QACrK,0DAA0D;KAC3D,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,SAAgB,QAAQ,CAAC,GAAc;IACrC,GAAG,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;AAC5C,CAAC"}
@@ -0,0 +1,145 @@
1
+ # A plugin carries its own items
2
+
3
+ Every `@webship.co/workspace-<name>` plugin manages what belongs to it: its `cmd-*.sh` commands and
4
+ its AI items (agents, skills, commands, prompts). The package holds them, the manifest names them,
5
+ and `plugins.sh --install <name>` lists each one in the workspace folder of its kind, when that
6
+ folder is an active workspace folder. `--uninstall` takes them away again. The reference is
7
+ [`@webship.co/workspace-wordpress`](https://github.com/webship/workspace-wordpress), and this plugin
8
+ follows it; below, `<p>` is the plugin's name.
9
+
10
+ ## The layout
11
+
12
+ ```text
13
+ commands/cmd-<p>-project.sh cmd-*.sh scripts only: builders and tools, placed in workspace folders
14
+ commands/cmd-tools-<p>-cli.sh
15
+ ai/agents/<p>-<role>.md one file per agent
16
+ ai/skills/<p>-<topic>/SKILL.md one folder per skill; every file in it is placed (examples/, references/)
17
+ ai/commands/<p>-<verb>.md one file per slash command
18
+ ai/prompts/<p>-<task>.md one file per prompt
19
+ tests/items.test.ts the shape of every item, and that it names nothing that does not exist
20
+ tests/fixtures/step-definitions.txt the step definitions the items' phrases are checked against (a plugin with a step pack)
21
+ ```
22
+
23
+ `commands/` is taken by the `cmd-*.sh` scripts, so the AI items live under `ai/`, one folder per
24
+ kind, named like the manifest's `ai` keys. The installer places an item by the last part of its
25
+ path, whatever folder the package keeps it in, so a plugin that kept its agents in `agents/` moves
26
+ them with `git mv agents ai/agents` and changes two lines of its manifest.
27
+
28
+ ## The manifest
29
+
30
+ ```json
31
+ "files": ["dist/src", "ai", "commands", "docs", "features", "scripts", "testing", "README.md"],
32
+ "workspacePlugin": {
33
+ "name": "<p>",
34
+ "needs": [["dev", "test", "sandboxes", "demos"], "ai-agents", "ai-skills", "ai-commands", "ai-prompts"],
35
+ "commands": { "types": ["sites"], "workspaces": ["dev", "test", "sandboxes", "demos"],
36
+ "files": ["commands/cmd-<p>-project.sh", "commands/cmd-tools-<p>-cli.sh"] },
37
+ "ai": {
38
+ "agents": ["ai/agents/<p>-site-builder.md", "ai/agents/<p>-tester.md"],
39
+ "skills": ["ai/skills/<p>-scenarios"],
40
+ "commands": ["ai/commands/<p>-test.md"],
41
+ "prompts": ["ai/prompts/<p>-build-and-test.md"]
42
+ }
43
+ }
44
+ ```
45
+
46
+ - `ai` is in `files`, or the items are not in the published package.
47
+ - A skill is named by its folder, with no `/SKILL.md` and no trailing slash.
48
+ - `needs` names the folder of every kind the plugin ships, after the folder its commands need. A
49
+ plugin with no `cmd-*.sh` for a sites folder leaves the first entry out; a kind it does not ship
50
+ is left out of `ai` and of `needs`.
51
+
52
+ | Kind | Lands in | Claude Code reads it from |
53
+ | --- | --- | --- |
54
+ | `commands.files` | every active folder `commands.workspaces` names, else every active folder of `commands.types` | the folder itself: `bash cmd-….sh` |
55
+ | `ai.agents` | `ai-agents/<name>.md` | `~/.claude/agents`, after Install |
56
+ | `ai.skills` | `ai-skills/<name>/` | `~/.claude/skills`, after Install |
57
+ | `ai.commands` | `ai-commands/<name>.md` | `~/.claude/commands`, after Install: `/<name>` |
58
+ | `ai.prompts` | `ai-prompts/<name>.md` | nothing: the New screen form lists it as a template for a new session |
59
+
60
+ ## The shape of each kind
61
+
62
+ | Kind | Shape |
63
+ | --- | --- |
64
+ | Agent | Frontmatter `name` (the file's name), `description` (when to use it, with the phrases a person says), `model: fable`, `tools`; then what it does, the commands it runs, its rules |
65
+ | Skill | `SKILL.md` with frontmatter `name` (the folder's name) and `description` (what it does, then `Use when …`); files beside it for what is too long or is meant to be copied |
66
+ | Command | Frontmatter `description` and `argument-hint`, no `name` (the file names it); the body reads what was typed from `$ARGUMENTS` |
67
+ | Prompt | No frontmatter. One sentence that says what it is for, then a fenced block holding the whole launch command: `claude --permission-mode bypassPermissions """` … `"""`, with `<placeholders>` to fill in and a `#` line that says where it runs |
68
+
69
+ Names start with the plugin's name (`<p>-…`): an item that is already in the folder under the same
70
+ name is kept, so a name another plugin could also choose would never be placed. A command and a
71
+ prompt never share a name: both end in `~/.claude/commands`.
72
+
73
+ ## What an item may say
74
+
75
+ Nothing generic and nothing invented. An item is about what this plugin does in the workspace, and
76
+ every command, flag, path and step phrase in it exists:
77
+
78
+ - commands and flags: the plugin's own (`scripts/args/*.sh`) and the workspace's (`cmd-tools-testing.sh`
79
+ and its flags, `cmd-tools-remove.sh`, `cmd-tools-clone.sh --to`, `cmd-tools-ai-items.sh --install`);
80
+ - step phrases: the plugin's step pack and webship-js, as installed in a real project;
81
+ - the workspace is container-based (DDEV by default); no platform name in a step phrase; no
82
+ account created by a scenario; no password, no personal path, addresses at `example.com`.
83
+
84
+ Run every command an item tells its reader to run, and every scenario it shows, on a real site
85
+ before it is pushed. Two of the three example features of the reference failed on their first real
86
+ run, each on a phrase that exists and matched in a dry run.
87
+
88
+ ## The tests to copy
89
+
90
+ `tests/items.test.ts` checks, with no site and no network:
91
+
92
+ 1. the manifest: one list per kind, each item under `ai/<kind>/`, in the package, named `<p>-…`,
93
+ `ai` in `files`, the folder of each kind in `needs`, no command and prompt of the same name;
94
+ 2. the shape of each kind (the table above; the two expressions the dashboard reads a prompt with);
95
+ 3. every `cmd-*.sh` an item names is the plugin's or the workspace's, with flags that exist;
96
+ 4. every step in a `gherkin` block or a `.feature` file matches a definition in
97
+ `tests/fixtures/step-definitions.txt`, names no platform and carries no password;
98
+ 5. the words: container-based, no personal value, the README lists every item.
99
+
100
+ Refresh the fixture from a project whose testing stack is set up, whenever the pack's release
101
+ line changes (`<pack>` is the plugin's step pack):
102
+
103
+ ```bash
104
+ cd ~/workspace/<folder>/<site>
105
+ { echo "# <pack> <version> and webship-js <version>" ;
106
+ grep -hE "^(Given|When|Then)\(/" node_modules/<pack>/tests/step-definitions/*.steps.js node_modules/webship-js/tests/step-definitions/*.steps.js \
107
+ | sed -nE 's/^(Given|When|Then)\(\/(.*)\/, (async )?function.*/\2/p' | sort -u ; } > step-definitions.txt
108
+ ```
109
+
110
+ `tests/needs.test.ts` holds the exact `needs` list, and `tests/plugin.test.ts` that every file the
111
+ manifest names ships.
112
+
113
+ ## Prove it on a fresh workspace
114
+
115
+ Never in a workspace somebody works in. `webship-workspace init <folder>` makes an empty one.
116
+
117
+ ```bash
118
+ npm pack # in the plugin: the tarball of the branch
119
+ cd <the fresh workspace>
120
+ bash core/scripts/plugins.sh --require <path>/webship.co-workspace-<p>-<version>.tgz # says what it needs
121
+ bash core/scripts/plugins.sh --activate <p> # stops: lists what is not here, changes nothing
122
+ bash core/scripts/plugins.sh --activate <p> --with-needs # adds the folders, then activates
123
+ bash core/scripts/plugins.sh --install <p> # "placed …" once per file
124
+ ls dev ai-agents ai-skills ai-commands ai-prompts # each item in its folder
125
+ bash core/scripts/plugins.sh --list # needs: … met by …
126
+ bash core/scripts/plugins.sh --uninstall <p> # "removed …" once per file
127
+ grep -c "<p>" core/config/plugins.installed.yml # 0: the record is gone
128
+ ```
129
+
130
+ Then, installed again: build one site with the builder, run each command the items name, copy the
131
+ skill's examples into the suite and run them, look at the four AI folders on the dashboard, and
132
+ remove the site with `cmd-tools-remove.sh`.
133
+
134
+ ## What was found on the way
135
+
136
+ - A phrase that matches in a dry run can still fail: a step may need another one before it
137
+ (`I should see the page title` needs `Given I am on a page`), or assert something the site does
138
+ not do as built. Only a real run tells.
139
+ - Content a failed scenario created stays on the site. Name it so it is found, and remove it
140
+ through the CLI tool before the next run (an entry in the trash is not in a list of every status).
141
+ - A folder that is not active gets nothing: the install says `skipped <n> <kind>` for it, and
142
+ places the items when the folder is added. With the folder in `needs`, `--activate` and
143
+ `--install` stop before that and offer to add it.
144
+ - An item a person edited in its folder is kept by `--install` and by `--uninstall`: the record
145
+ holds the hash of what was placed.
@@ -1,6 +1,7 @@
1
1
  Feature: The Gatsby plugin on the dashboard
2
- Once the plugin is activated and installed, the sites folders offer the Gatsby builder, the
3
- AI Agents folder lists the Gatsby agents, and the Plugins page lists the plugin with its steps.
2
+ Once the plugin is activated and installed, the sites folders offer the Gatsby builder, each
3
+ AI folder lists the items of its kind the plugin ships, and the Plugins page lists the plugin
4
+ with its steps.
4
5
 
5
6
  Scenario: The plugin is listed on the Plugins page
6
7
  Given I am on "/settings/plugins"
@@ -15,3 +16,15 @@ Feature: The Gatsby plugin on the dashboard
15
16
  Given I am on "/ai-agents"
16
17
  Then I should see "gatsby-site-builder"
17
18
  And I should see "gatsby-tester"
19
+
20
+ Scenario: The AI Skills folder lists the skill the plugin ships
21
+ Given I am on "/ai-skills"
22
+ Then I should see "gatsby-scenarios"
23
+
24
+ Scenario: The AI Commands folder lists the command the plugin ships
25
+ Given I am on "/ai-commands"
26
+ Then I should see "gatsby-test"
27
+
28
+ Scenario: The AI Prompts folder lists the prompt the plugin ships
29
+ Given I am on "/ai-prompts"
30
+ Then I should see "gatsby-build-and-test"
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@webship.co/workspace-gatsby",
3
- "version": "1.0.7",
4
- "description": "Gatsby for Webship Workspace: the builder (`cmd-gatsby-project.sh`) and the Gatsby CLI tool in every sites folder, a starter built to a production build and served in a container, the Gatsby step pack wired into the testing setup, and two AI agents in the AI Agents folder.",
3
+ "version": "1.0.9",
4
+ "description": "Gatsby for Webship Workspace: the builder (`cmd-gatsby-project.sh`) and the Gatsby CLI tool in every sites folder, a starter built to a production build and served in a container, the Gatsby step pack wired into the testing setup, and its AI items in their folders: two agents, a skill, a command and a prompt.",
5
5
  "main": "dist/src/index.js",
6
6
  "types": "dist/src/index.d.ts",
7
7
  "license": "ISC",
@@ -11,8 +11,9 @@
11
11
  },
12
12
  "files": [
13
13
  "dist/src",
14
- "agents",
14
+ "ai",
15
15
  "commands",
16
+ "docs",
16
17
  "features",
17
18
  "scripts",
18
19
  "testing",
@@ -27,6 +28,18 @@
27
28
  "workspacePlugin": {
28
29
  "name": "gatsby",
29
30
  "label": "Gatsby",
31
+ "needs": [
32
+ [
33
+ "dev",
34
+ "test",
35
+ "sandboxes",
36
+ "demos"
37
+ ],
38
+ "ai-agents",
39
+ "ai-skills",
40
+ "ai-commands",
41
+ "ai-prompts"
42
+ ],
30
43
  "commands": {
31
44
  "types": [
32
45
  "sites"
@@ -56,8 +69,17 @@
56
69
  },
57
70
  "ai": {
58
71
  "agents": [
59
- "agents/gatsby-site-builder.md",
60
- "agents/gatsby-tester.md"
72
+ "ai/agents/gatsby-site-builder.md",
73
+ "ai/agents/gatsby-tester.md"
74
+ ],
75
+ "skills": [
76
+ "ai/skills/gatsby-scenarios"
77
+ ],
78
+ "commands": [
79
+ "ai/commands/gatsby-test.md"
80
+ ],
81
+ "prompts": [
82
+ "ai/prompts/gatsby-build-and-test.md"
61
83
  ]
62
84
  },
63
85
  "features": [
@@ -19,7 +19,7 @@
19
19
 
20
20
  # The step pack a Gatsby project is tested with, and the release line it is required at.
21
21
  readonly GATSBY_STEPS_PACKAGE='@webship-js/gatsby-steps';
22
- readonly GATSBY_STEPS_VERSION='^2.0.2';
22
+ readonly GATSBY_STEPS_VERSION='^2.1.0';
23
23
 
24
24
  # Where the site lives in the web container, and the port its server listens on.
25
25
  readonly GATSBY_SITE='/var/www/html/site';