@webship.co/workspace-odoo 0.0.0-stage → 1.0.8

package/ai/skills/odoo-scenarios/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: odoo-scenarios
+description: Write and run webship-js scenarios for an Odoo Community site of the Webship Workspace with the Odoo step pack (`@webship-js/odoo-steps`) — the phrases of the pack by area (sessions, apps and menus, views and search, records, dialogs and the chatter, the website with its blog, shop, events and jobs), the handles of the users registry, and the workspace command that runs them in the site's container. Use when asked to "write a scenario for this Odoo site", "test the salesperson account", "which step is there for a kanban column", "add a feature for creating a contact", or when a `.feature` file of an Odoo project is being written or fixed.
+argument-hint: '<site> [what to cover]'
+---
+
+# odoo-scenarios
+
+Scenarios for an Odoo Community site of a Webship Workspace (`~/workspace`, container-based, DDEV
+by default), written from the steps of [`@webship-js/odoo-steps`](https://github.com/webship/odoo-steps)
+and of [webship-js](https://github.com/webship/webship-js) itself, and run in the site's container
+by the workspace's own command. It comes with the Odoo plugin (`@webship.co/workspace-odoo`), like
+the builder (`cmd-odoo-project.sh`), the odoo-bin tool (`cmd-tools-odoo-cli.sh`) and the agents
+`odoo-site-builder` and `odoo-tester`. The site is the Community edition, never the Enterprise
+edition.
+
+## Where everything is
+
+| What | Where |
+| --- | --- |
+| The site | `~/workspace/<folder>/<site>`, at `https://<site>.ddev.site`, the login at `/web/login` (`<folder>` is a sites folder: `dev`, `test`, `sandboxes`, `demos`) |
+| The suite's configuration | `<site>/cucumber.js`: the step definitions it loads and the users registry (`worldParameters.users`) |
+| The features | `<site>/tests/features/*.feature` (`site.feature` is the first one the setup wrote) |
+| The pack's steps | `<site>/node_modules/@webship-js/odoo-steps/tests/step-definitions/*.steps.js` |
+| webship-js's steps | `<site>/node_modules/webship-js/tests/step-definitions/*.js` |
+| The reports | `<site>/tests/reports/` |
+
+## The order of work
+
+1. **Make sure the testing stack is there.** From the sites folder:
+   ```bash
+   cd ~/workspace/<folder>
+   bash cmd-tools-testing.sh <site>
+   ```
+   It adds webship-js, the step pack, the users registry and `tests/features/site.feature`, and
+   makes sure the default accounts are on the site. It is safe to run again: it adds what is
+   missing and keeps what was changed.
+2. **Know which apps the site has.** A scenario about an app that is not installed fails at its
+   first step:
+   ```bash
+   bash cmd-tools-odoo-cli.sh <site>                           # the version, the apps, the accounts
+   bash cmd-tools-odoo-cli.sh <site> --install-apps project    # only when an app is asked for
+   ```
+3. **Read the installed steps before writing a phrase.** They are the source of truth: the pack
+   moves, and a phrase from memory is a guess.
+   ```bash
+   cd ~/workspace/<folder>/<site>
+   grep -hE "^(Given|When|Then)\(" node_modules/@webship-js/odoo-steps/tests/step-definitions/*.steps.js
+   ```
+   Every step carries a comment block with five examples above it; open the file when a phrase
+   is not obvious.
+4. **Look at the screen first** (the Playwright MCP browser, a tab of your own) when the scenario
+   is about a screen you have not seen: the label of a field, the name of a column and the items
+   of a menu are the site's own words, and a form does not always label its first field.
+5. **Write the feature** in `<site>/tests/features/`, from phrases that exist (the lists below).
+6. **Match every step without a browser**, then run the feature, then the suite:
+   ```bash
+   cd ~/workspace/<folder>
+   bash cmd-tools-testing.sh <site> --dry-run --path tests/features/<name>.feature
+   bash cmd-tools-testing.sh <site> --run --path tests/features/<name>.feature
+   bash cmd-tools-testing.sh <site> --run --tags "@critical"
+   bash cmd-tools-testing.sh <site> --run
+   ```
+   A dry run says `Undefined` for a phrase no definition matches: fix the phrase, do not write a
+   step for it.
+
+## Accounts: a handle, never a password
+
+A scenario logs in by a handle of the users registry. The default accounts are on the site
+already (`bash cmd-tools-odoo-cli.sh <site> --add-users` adds them again if they were removed):
+
+| Handle | Account | What it may do |
+| --- | --- | --- |
+| `admin` | `administrator` | Every installed app, and the settings |
+| `salesperson` | `salesperson` | Sales and CRM, own documents only; no Invoicing |
+| `accountant` | `accountant` | Invoicing; no Sales, no CRM |
+| `employee` | `employee` | An internal user with no app of a role |
+| `portal` | `portal` | A portal user: the website and `/my`, never the web client |
+
+```gherkin
+Given I am a logged in user with the "salesperson" user
+Then I should be logged in as "salesperson"
+And I should be in the web client
+```
+
+## The phrases, by area
+
+Each line is a phrase the pack defines, and each one passed on a site built with
+`bash cmd-odoo-project.sh <site> --install --add-users` (the default apps with demo data; the
+names in quotes are that site's). Most `should` steps also take the negative.
+
+### Sessions
+
+```gherkin
+Given I am not logged in
+Given I am on the login page
+Given I am a logged in user with the "salesperson" user
+When I log in as "salesperson" with password "not-the-password"
+When I log out
+Then I should see the login form
+Then I should see a login error
+Then I should be logged in as "salesperson"
+Then I should not be logged in
+Then I should be in the web client
+Then I should be in the portal
+When I open the user menu
+Then I should see "Log out" in the user menu
+```
+
+### Apps, menus and views
+
+```gherkin
+Then I should see the "CRM" app
+Then I should not see the "Invoicing" app
+When I open the "CRM" app
+Then I should be in the "CRM" app
+Then I should see the "Orders" menu
+Then I should see "Quotations" in the breadcrumb
+When I go back to "Contacts" in the breadcrumb
+Then I should see the kanban view
+When I switch to the list view
+Then I should see the list view
+Then I should see the "New" column
+```
+
+### Records, search, dialogs and the chatter
+
+```gherkin
+When I create a new record
+When I set the "Email" field to "suite-contact@example.com"
+Then the form should have unsaved changes
+When I save the record
+Then the form should not have unsaved changes
+Then the "Email" field should be "suite-contact@example.com"
+Then I should see the chatter
+When I log the note "Written by the suite."
+Then I should see "Written by the suite." in the chatter
+When I search the records for "A contact from the suite"
+Then I should see the "A contact from the suite" record
+Then I should see 1 record
+When I select the "A contact from the suite" record
+Then I should see 1 selected record
+When I choose "Delete" in the Actions menu
+Then I should see a dialog
+When I confirm the dialog
+Then I should see no records
+```
+
+### The website
+
+```gherkin
+Then I should be on a website page
+Then I should see the menu
+Then I should see the footer
+Then I should be on the blog page
+Then I should be on the shop page
+When I search the shop for "desk"
+Then I should see shop search results for "desk"
+When I open the first product in the shop
+Then I should be on a product page
+When I add the product to the cart
+Then I should see "1" item in the cart
+Then I should be on the events page
+Then I should be on the jobs page
+Then I should see job openings
+Given I am on the contact page
+Then I should see the contact form
+Then I should be on the 404 page
+Then I should be able to edit the website
+```
+
+`I am an anonymous user`, `I am on the homepage`, `I go to "/shop"`, `I should see "<text>"` and
+`the response status code should be 200` are webship-js's own steps; its status codes, classes,
+landmarks and accessibility audits are used as they are and never redefined for this platform.
+
+## Traps found on a real site
+
+- **A field is named by what the form shows, and the first field of a contact shows no label.**
+  `When I set the "Name" field to "…"` failed in Contacts: the form labels `Email`, `Phone`,
+  `Tags` and the others, and the name is a placeholder. The technical name passed:
+  `When I set the "name" field to "A contact from the suite"`. The failure message lists the
+  labels the form has.
+- **`I should be able to edit the website` is a step for an internal user.** For a visitor,
+  `I should not be able to edit the website` does not pass as "no": it fails with `Expected the
+  website preview of the web client`. Log in first, or leave it out of a visitor's scenario.
+- **Deleting a record is done from the list.** Search for it, switch to the list view, select
+  it, choose `Delete` in the Actions menu and confirm the dialog, as the example does.
+- **A product in the cart is a quotation in Sales.** `When I add the product to the cart` passed
+  for a visitor and left a quotation behind that a visitor cannot remove. The examples stop at
+  the product page; a cart scenario belongs in a site that is rebuilt for the run.
+- **The pages are the default apps'.** `/blog`, `/shop`, `/event`, `/jobs` and the pipeline
+  columns `New` and `Won` come with the apps and the demo data the builder installs. A site built
+  with `--apps` or `--without-demo` has its own.
+- **The demo data has its own `portal` user.** The handle `portal` logs in as that account, with
+  the groups and the password of the default list.
+
+## Rules
+
+- **No account is created in a suite.** No user is added by a scenario or a hook. A role the
+  registry does not have is asked for, not made.
+- **Never the workspace account.** The site's own administrator is not in the registry; `admin`
+  is the `administrator` default account.
+- **No password in a feature file**, except where a wrong password is the subject.
+- **No platform name in a step phrase**: `I open the "CRM" app`, `I should be in the web client`,
+  never a phrase that names the product. The same holds for a custom step.
+- **No selector and no address when a step says it**: `the "Sales" app`, not the path of its
+  action.
+- **What a scenario creates, it removes** in the same scenario, under a name nobody else uses.
+- **Community only.** No scenario needs an app of another edition, a trial or a vendor account,
+  and nothing is sent to an outside service.
+- **A custom step is the last resort**: look in the pack and in webship-js first, write it in
+  `<site>/tests/step-definitions/` with a comment block and examples, and say it may belong in
+  the pack.
+- **Everything runs in the container**, through `cmd-tools-testing.sh`. Never `npx cucumber-js`
+  or `npx playwright` on the host.
+- **A failing scenario is a result.** No `@wip`, no longer timeout, no looser assertion to turn a
+  run green: say what the site did.
+
+## Examples that run
+
+`examples/` holds three features that pass on a site built with
+`bash cmd-odoo-project.sh <site> --install --add-users`. Copy one into the suite and run it:
+
+```bash
+cp ~/workspace/ai-skills/odoo-scenarios/examples/apps-and-views.feature ~/workspace/<folder>/<site>/tests/features/
+cd ~/workspace/<folder>
+bash cmd-tools-testing.sh <site> --run --path tests/features/apps-and-views.feature
+```
+
+| Feature | What it shows |
+| --- | --- |
+| `examples/apps-and-views.feature` | A salesperson in the pipeline and in the quotations, an employee with no app of a role, the user menu |
+| `examples/contact-lifecycle.feature` | An administrator creating a contact, logging a note, finding it and deleting it: a record a scenario creates and removes |
+| `examples/website.feature` | A visitor on the front page, the blog, the shop, the events, the jobs and the contact page, an address with no page, and a portal user kept out of the web client |

package/ai/skills/odoo-scenarios/examples/apps-and-views.feature

@@ -0,0 +1,36 @@
+Feature: Each account works in the apps of its role
+  As the owner of the site
+  I want every account to open the apps of its role, with their views and menus
+  So that a change of groups or of an app is caught by the suite
+
+  # The accounts are the default ones; a scenario logs in by a handle of the users registry.
+
+  Scenario: A salesperson works in the pipeline
+    Given I am a logged in user with the "salesperson" user
+    When I open the "CRM" app
+    Then I should be in the "CRM" app
+    And I should see the kanban view
+    And I should see the "New" column
+    And I should see the "Won" column
+    When I switch to the list view
+    Then I should see the list view
+
+  Scenario: A salesperson opens the quotations
+    Given I am a logged in user with the "salesperson" user
+    When I open the "Sales" app
+    Then I should be in the "Sales" app
+    And I should see "Quotations" in the breadcrumb
+    And I should see the "Orders" menu
+
+  Scenario: An employee has the web client and no app of a role
+    Given I am a logged in user with the "employee" user
+    Then I should be in the web client
+    But I should not see the "Sales" app
+    And I should not see the "Settings" app
+
+  Scenario: The user menu ends the session
+    Given I am a logged in user with the "accountant" user
+    When I open the user menu
+    Then I should see "Log out" in the user menu
+    When I log out
+    Then I should not be logged in

package/ai/skills/odoo-scenarios/examples/contact-lifecycle.feature

@@ -0,0 +1,29 @@
+Feature: A contact is written and removed again
+  As an administrator
+  I want to create a contact, note something on it, find it and delete it
+  So that the suite proves records, the chatter and the search work, and leaves the site as it found it
+
+  Scenario: The administrator creates a contact, finds it in the list and deletes it
+    Given I am a logged in user with the "admin" user
+    When I open the "Contacts" app
+    And I create a new record
+    And I set the "name" field to "A contact written by a scenario"
+    And I set the "Email" field to "scenario-contact@example.com"
+    Then the form should have unsaved changes
+    When I save the record
+    Then the form should not have unsaved changes
+    And the "Email" field should be "scenario-contact@example.com"
+    And I should see the chatter
+    When I log the note "Written and removed by the suite."
+    Then I should see "Written and removed by the suite." in the chatter
+    When I go back to "Contacts" in the breadcrumb
+    And I search the records for "A contact written by a scenario"
+    Then I should see the "A contact written by a scenario" record
+    And I should see 1 record
+    When I switch to the list view
+    And I select the "A contact written by a scenario" record
+    Then I should see 1 selected record
+    When I choose "Delete" in the Actions menu
+    Then I should see a dialog
+    When I confirm the dialog
+    Then I should see no records

package/ai/skills/odoo-scenarios/examples/website.feature

@@ -0,0 +1,43 @@
+Feature: A visitor reads the website
+  As the owner of the site
+  I want the pages of the website apps to be served to a visitor
+  So that an app or a theme that breaks the website is caught by the suite
+
+  # For a site built with the default apps: the blog, the shop, the events and the jobs.
+
+  Scenario: The front page has its menu and its footer
+    Given I am an anonymous user
+    And I am on the homepage
+    Then I should be on a website page
+    And I should see the menu
+    And I should see the footer
+
+  Scenario: Each website app has its page
+    Given I am an anonymous user
+    When I go to "/blog"
+    Then I should be on the blog page
+    When I go to "/event"
+    Then I should be on the events page
+    When I go to "/jobs"
+    Then I should be on the jobs page
+    And I should see job openings
+    Given I am on the contact page
+    Then I should see the contact form
+
+  Scenario: The shop lists products and finds one
+    Given I am an anonymous user
+    When I go to "/shop"
+    Then I should be on the shop page
+    When I search the shop for "desk"
+    Then I should see shop search results for "desk"
+    When I open the first product in the shop
+    Then I should be on a product page
+
+  Scenario: An address with no page is not found, and a portal user stays out of the web client
+    Given I am an anonymous user
+    When I go to "/this-page-does-not-exist"
+    Then I should be on the 404 page
+    Given I am a logged in user with the "portal" user
+    When I go to "/web"
+    Then I should be in the portal
+    And I should not be in the web client

package/commands/cmd-odoo-project.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+# workspace-name: Odoo 17 Community (apps, accounts, tests)
+
+# Installed by the Odoo plugin (plugins.sh --install odoo); __WORKSPACE__ is the workspace it was installed into.
+#
+# Build an Odoo Community site in a container: Odoo 17.0, or the release --version names, on
+# PostgreSQL, at https://<name>.ddev.site. With --install the database is created with the apps
+# and Odoo's demo data, and the workspace account is its administrator; with --add-users it also
+# gets the default accounts. Community only: no Enterprise, no vendor account.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
+
+# Set site version.
+site_version="17.0";
+
+# Distribution.
+distribution_name="odoo";
+distribution_title="Odoo Community";
+distribution_webroot="";
+
+ARGPARSE_DESCRIPTION="Build an ${distribution_title} project in __WORKSPACE__"
+# The args file comes with the plugin: core/scripts/plugins/odoo/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/odoo/args/arg-odoo.sh || exit 1 ;
+
+shift $#;
+
+odoo_build ;

package/commands/cmd-tools-odoo-cli.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# Installed by the Odoo plugin (plugins.sh --install odoo); __WORKSPACE__ is the workspace it was installed into.
+#
+# odoo-bin for one Odoo project of this workspace, in its container: say what the site is, run
+# an odoo-bin command, install apps, update the installed modules, restart Odoo, add or remove
+# the default accounts. Nothing here runs on the host.
+
+# Bootstrap.
+# Find the workspace tooling from this script, so a fresh clone needs no setup.
+WORKSPACE_SCRIPTS="${WORKSPACE_SCRIPTS:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+source ${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+
+# Load workspace settings.
+eval $(parse_yaml ${WORKSPACE_CONFIG}/workspace.__WORKSPACE__.settings.yml);
+
+# Distribution.
+distribution_name="odoo";
+
+ARGPARSE_DESCRIPTION="Run odoo-bin on an Odoo project of __WORKSPACE__: status, a command, apps, an update, a restart, the default accounts"
+# The args file comes with the plugin: core/scripts/plugins/odoo/ is where plugins.sh --install puts it.
+source ${WORKSPACE_SCRIPTS}/plugins/odoo/args/arg-odoo-cli.sh || exit 1 ;
+
+shift $#;
+
+odoo_cli_tool ;

package/dist/src/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Odoo Community for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * odoo-bin tool in the sites folders, their functions, argparse and the accounts script under
+ * core/scripts/plugins/odoo/, its AI items (ai/) in the AI folders. The dashboard needs nothing
+ * drawn for it: the builder is in the Build list because it is a cmd-*-project.sh, the row menus
+ * are the core's, the AI items are listed like any other. What register() adds is what the
+ * assistant is told.
+ *
+ * Everything the dashboard is asked for goes through `api`; this package requires nothing from the
+ * dashboard's own files, so it can be installed from npm and removed without a trace.
+ */
+import type { PluginApi } from '@webship.co/workspace-plugin-api';
+/** The plugin's name, which its functions are named after. */
+export declare const PLATFORM = "odoo";
+/** The commands the installer places in every sites folder. */
+export declare const COMMANDS: string[];
+/** The agents the installer places in the AI Agents folder. */
+export declare const AGENTS: string[];
+/** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
+export declare const SKILLS: string[];
+/** The slash command the installer places in the AI Commands folder. */
+export declare const AI_COMMANDS: string[];
+/** The prompt the installer places in the AI Prompts folder: a whole launch command for a new session. */
+export declare const PROMPTS: string[];
+/** What the assistant is told about Odoo in this workspace. */
+export declare function assistantContext(): string;
+export declare function register(api: PluginApi): void;

package/dist/src/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Odoo Community for Webship Workspace: a platform plugin.
+ *
+ * What the package carries is placed by the installer from the manifest: the builder and the
+ * odoo-bin tool in the sites folders, their functions, argparse and the accounts script under
+ * core/scripts/plugins/odoo/, its AI items (ai/) in the AI folders. The dashboard needs nothing
+ * drawn for it: the builder is in the Build list because it is a cmd-*-project.sh, the row menus
+ * are the core's, the AI items are listed like any other. What register() adds is what the
+ * assistant is told.
+ *
+ * Everything the dashboard is asked for goes through `api`; this package requires nothing from the
+ * dashboard's own files, so it can be installed from npm and removed without a trace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPTS = exports.AI_COMMANDS = exports.SKILLS = exports.AGENTS = exports.COMMANDS = exports.PLATFORM = void 0;
+exports.assistantContext = assistantContext;
+exports.register = register;
+/** The plugin's name, which its functions are named after. */
+exports.PLATFORM = 'odoo';
+/** The commands the installer places in every sites folder. */
+exports.COMMANDS = ['cmd-odoo-project.sh', 'cmd-tools-odoo-cli.sh'];
+/** The agents the installer places in the AI Agents folder. */
+exports.AGENTS = ['odoo-site-builder', 'odoo-tester'];
+/** The skill the installer places in the AI Skills folder (a folder each, with its SKILL.md). */
+exports.SKILLS = ['odoo-scenarios'];
+/** The slash command the installer places in the AI Commands folder. */
+exports.AI_COMMANDS = ['odoo-test'];
+/** The prompt the installer places in the AI Prompts folder: a whole launch command for a new session. */
+exports.PROMPTS = ['odoo-build-and-test'];
+/** What the assistant is told about Odoo in this workspace. */
+function assistantContext() {
+    return [
+        'Odoo Community (a plugin, @webship.co/workspace-odoo): an Odoo site is built with',
+        '`bash cmd-odoo-project.sh <name> --install --add-users` from a sites folder (dev, test, sandboxes, demos),',
+        'in containers like every other project, at https://<name>.ddev.site (the login at /web/login).',
+        '`bash cmd-tools-odoo-cli.sh <name>` says what the site is; `--run "<odoo-bin arguments>"` runs odoo-bin on its database,',
+        '`--install-apps <a,b>` installs apps, `--update` updates the installed modules, `--restart` starts Odoo again,',
+        '`--add-users` adds the default accounts (one per kind of user).',
+        '`bash cmd-tools-testing.sh <name>` sets up webship-js with the Odoo step pack; `--run` runs the suite.',
+        `For Odoo work, hand over to the agents ${exports.AGENTS.map((a) => `\`${a}\``).join(' and ')}.`,
+        `The plugin also places the skill ${exports.SKILLS.map((a) => `\`${a}\``).join(', ')} (the step pack's phrases, by area) in ai-skills/,`,
+        `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/.`,
+        'Community only: never the Enterprise edition, never a vendor account. Never run odoo, python or psql on the host for a project.',
+        'The example builder cmd-odoo20-project.sh of a sites folder is a different, simpler build; this plugin leaves it as it is.',
+    ].join(' ');
+}
+function register(api) {
+    api.addAssistantContext(assistantContext);
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAuBH,4CAeC;AAED,4BAEC;AAtCD,8DAA8D;AACjD,QAAA,QAAQ,GAAG,MAAM,CAAC;AAE/B,+DAA+D;AAClD,QAAA,QAAQ,GAAG,CAAC,qBAAqB,EAAE,uBAAuB,CAAC,CAAC;AAEzE,+DAA+D;AAClD,QAAA,MAAM,GAAG,CAAC,mBAAmB,EAAE,aAAa,CAAC,CAAC;AAE3D,iGAAiG;AACpF,QAAA,MAAM,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAEzC,wEAAwE;AAC3D,QAAA,WAAW,GAAG,CAAC,WAAW,CAAC,CAAC;AAEzC,0GAA0G;AAC7F,QAAA,OAAO,GAAG,CAAC,qBAAqB,CAAC,CAAC;AAE/C,+DAA+D;AAC/D,SAAgB,gBAAgB;IAC9B,OAAO;QACL,mFAAmF;QACnF,4GAA4G;QAC5G,gGAAgG;QAChG,0HAA0H;QAC1H,gHAAgH;QAChH,iEAAiE;QACjE,wGAAwG;QACxG,0CAA0C,cAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;QACxF,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,iIAAiI;QACjI,4HAA4H;KAC7H,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,SAAgB,QAAQ,CAAC,GAAc;IACrC,GAAG,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;AAC5C,CAAC"}

package/docs/plugin-items-pattern.md

@@ -0,0 +1,145 @@
+# A plugin carries its own items
+
+Every `@webship.co/workspace-<name>` plugin manages what belongs to it: its `cmd-*.sh` commands and
+its AI items (agents, skills, commands, prompts). The package holds them, the manifest names them,
+and `plugins.sh --install <name>` lists each one in the workspace folder of its kind, when that
+folder is an active workspace folder. `--uninstall` takes them away again. The reference is
+[`@webship.co/workspace-wordpress`](https://github.com/webship/workspace-wordpress), and this plugin
+follows it; below, `<p>` is the plugin's name.
+
+## The layout
+
+```text
+commands/cmd-<p>-project.sh            cmd-*.sh scripts only: builders and tools, placed in workspace folders
+commands/cmd-tools-<p>-cli.sh
+ai/agents/<p>-<role>.md                one file per agent
+ai/skills/<p>-<topic>/SKILL.md         one folder per skill; every file in it is placed (examples/, references/)
+ai/commands/<p>-<verb>.md              one file per slash command
+ai/prompts/<p>-<task>.md               one file per prompt
+tests/items.test.ts                    the shape of every item, and that it names nothing that does not exist
+tests/fixtures/step-definitions.txt    the step definitions the items' phrases are checked against (a plugin with a step pack)
+```
+
+`commands/` is taken by the `cmd-*.sh` scripts, so the AI items live under `ai/`, one folder per
+kind, named like the manifest's `ai` keys. The installer places an item by the last part of its
+path, whatever folder the package keeps it in, so a plugin that kept its agents in `agents/` moves
+them with `git mv agents ai/agents` and changes two lines of its manifest.
+
+## The manifest
+
+```json
+"files": ["dist/src", "ai", "commands", "docs", "features", "scripts", "testing", "README.md"],
+"workspacePlugin": {
+  "name": "<p>",
+  "needs": [["dev", "test", "sandboxes", "demos"], "ai-agents", "ai-skills", "ai-commands", "ai-prompts"],
+  "commands": { "types": ["sites"], "workspaces": ["dev", "test", "sandboxes", "demos"],
+                "files": ["commands/cmd-<p>-project.sh", "commands/cmd-tools-<p>-cli.sh"] },
+  "ai": {
+    "agents":   ["ai/agents/<p>-site-builder.md", "ai/agents/<p>-tester.md"],
+    "skills":   ["ai/skills/<p>-scenarios"],
+    "commands": ["ai/commands/<p>-test.md"],
+    "prompts":  ["ai/prompts/<p>-build-and-test.md"]
+  }
+}
+```
+
+- `ai` is in `files`, or the items are not in the published package.
+- A skill is named by its folder, with no `/SKILL.md` and no trailing slash.
+- `needs` names the folder of every kind the plugin ships, after the folder its commands need. A
+  plugin with no `cmd-*.sh` for a sites folder leaves the first entry out; a kind it does not ship
+  is left out of `ai` and of `needs`.
+
+| Kind | Lands in | Claude Code reads it from |
+| --- | --- | --- |
+| `commands.files` | every active folder `commands.workspaces` names, else every active folder of `commands.types` | the folder itself: `bash cmd-….sh` |
+| `ai.agents` | `ai-agents/<name>.md` | `~/.claude/agents`, after Install |
+| `ai.skills` | `ai-skills/<name>/` | `~/.claude/skills`, after Install |
+| `ai.commands` | `ai-commands/<name>.md` | `~/.claude/commands`, after Install: `/<name>` |
+| `ai.prompts` | `ai-prompts/<name>.md` | nothing: the New screen form lists it as a template for a new session |
+
+## The shape of each kind
+
+| Kind | Shape |
+| --- | --- |
+| 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 |
+| 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 |
+| Command | Frontmatter `description` and `argument-hint`, no `name` (the file names it); the body reads what was typed from `$ARGUMENTS` |
+| 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 |
+
+Names start with the plugin's name (`<p>-…`): an item that is already in the folder under the same
+name is kept, so a name another plugin could also choose would never be placed. A command and a
+prompt never share a name: both end in `~/.claude/commands`.
+
+## What an item may say
+
+Nothing generic and nothing invented. An item is about what this plugin does in the workspace, and
+every command, flag, path and step phrase in it exists:
+
+- commands and flags: the plugin's own (`scripts/args/*.sh`) and the workspace's (`cmd-tools-testing.sh`
+  and its flags, `cmd-tools-remove.sh`, `cmd-tools-clone.sh --to`, `cmd-tools-ai-items.sh --install`);
+- step phrases: the plugin's step pack and webship-js, as installed in a real project;
+- the workspace is container-based (DDEV by default); no platform name in a step phrase; no
+  account created by a scenario; no password, no personal path, addresses at `example.com`.
+
+Run every command an item tells its reader to run, and every scenario it shows, on a real site
+before it is pushed. Two of the three example features of the reference failed on their first real
+run, each on a phrase that exists and matched in a dry run.
+
+## The tests to copy
+
+`tests/items.test.ts` checks, with no site and no network:
+
+1. the manifest: one list per kind, each item under `ai/<kind>/`, in the package, named `<p>-…`,
+   `ai` in `files`, the folder of each kind in `needs`, no command and prompt of the same name;
+2. the shape of each kind (the table above; the two expressions the dashboard reads a prompt with);
+3. every `cmd-*.sh` an item names is the plugin's or the workspace's, with flags that exist;
+4. every step in a `gherkin` block or a `.feature` file matches a definition in
+   `tests/fixtures/step-definitions.txt`, names no platform and carries no password;
+5. the words: container-based, no personal value, the README lists every item.
+
+Refresh the fixture from a project whose testing stack is set up, whenever the pack's release
+line changes (`<pack>` is the plugin's step pack):
+
+```bash
+cd ~/workspace/<folder>/<site>
+{ echo "# <pack> <version> and webship-js <version>" ;
+  grep -hE "^(Given|When|Then)\(/" node_modules/<pack>/tests/step-definitions/*.steps.js node_modules/webship-js/tests/step-definitions/*.steps.js \
+    | sed -nE 's/^(Given|When|Then)\(\/(.*)\/, (async )?function.*/\2/p' | sort -u ; } > step-definitions.txt
+```
+
+`tests/needs.test.ts` holds the exact `needs` list, and `tests/plugin.test.ts` that every file the
+manifest names ships.
+
+## Prove it on a fresh workspace
+
+Never in a workspace somebody works in. `webship-workspace init <folder>` makes an empty one.
+
+```bash
+npm pack                                                                 # in the plugin: the tarball of the branch
+cd <the fresh workspace>
+bash core/scripts/plugins.sh --require <path>/webship.co-workspace-<p>-<version>.tgz   # says what it needs
+bash core/scripts/plugins.sh --activate <p>                              # stops: lists what is not here, changes nothing
+bash core/scripts/plugins.sh --activate <p> --with-needs                 # adds the folders, then activates
+bash core/scripts/plugins.sh --install <p>                               # "placed …" once per file
+ls dev ai-agents ai-skills ai-commands ai-prompts                        # each item in its folder
+bash core/scripts/plugins.sh --list                                      # needs: … met by …
+bash core/scripts/plugins.sh --uninstall <p>                             # "removed …" once per file
+grep -c "<p>" core/config/plugins.installed.yml                          # 0: the record is gone
+```
+
+Then, installed again: build one site with the builder, run each command the items name, copy the
+skill's examples into the suite and run them, look at the four AI folders on the dashboard, and
+remove the site with `cmd-tools-remove.sh`.
+
+## What was found on the way
+
+- A phrase that matches in a dry run can still fail: a step may need another one before it
+  (`I should see the page title` needs `Given I am on a page`), or assert something the site does
+  not do as built. Only a real run tells.
+- Content a failed scenario created stays on the site. Name it so it is found, and remove it
+  through the CLI tool before the next run (an entry in the trash is not in a list of every status).
+- A folder that is not active gets nothing: the install says `skipped <n> <kind>` for it, and
+  places the items when the folder is added. With the folder in `needs`, `--activate` and
+  `--install` stop before that and offer to add it.
+- An item a person edited in its folder is kept by `--install` and by `--uninstall`: the record
+  holds the hash of what was placed.