@capagents/forgeqe 1.0.5 → 1.0.8

package/HOW_TO_USE.md

@@ -66,6 +66,7 @@ Everything ForgeQE can do, by area. ForgeQE's agent answers "can you…?" questi
 | Release | **Requirement coverage and release readiness**: Gives requirement coverage and a GO / GO WITH RISKS / NO-GO verdict for a sprint, area, epic, or stories, from test cases, results, bugs, and flaky tests; can publish it to the wiki. | `release_readiness` | [docs](#requirement-coverage-and-release-readiness) |
 | Operations | **Scheduled monitoring with alerts**: Runs checks on a schedule and alerts Teams or email when one keeps failing, and again when it recovers. | `monitor` | [docs](#9-monitoring) |
 | Operations | **Teams and email notifications**: Tells the team in Microsoft Teams channels or by email when a suite fails or passes, when a release readiness verdict is in, and when the domain evaluation falls below its gate, with the failing cases, their bugs, and links to the report and the CI build. Each channel picks its events; the agent also posts a summary to a channel when asked. | `notify` | [docs](#17-notifications) |
+| Release | **Reports you can share**: Writes up what ForgeQE's agent found, such as release status across projects, open defects, or pipeline health, as a Markdown file and an HTML page in the reports folder, with a summary in the chat and links to open them. | `write_report` | [docs](#reports-from-the-agent) |
 | Operations | **CI pipelines**: Writes a GitHub Actions or Azure Pipelines workflow that runs ForgeQE, stores the secrets it needs, pushes a branch, and makes the pipeline green. | `push_branch`, `set_ci_secret` | [docs](#8-pipelines) |
 | Systems | **Work with Azure DevOps, Jira, and Confluence**: Reads anything in the configured systems (work items, issues, queries, boards, pages), makes changes the user asks for, and builds Azure DevOps dashboards and wiki pages. | `query_api`, `read_confluence`, `create_ado_dashboard`, `write_ado_wiki_page` | [docs](README.md#azure-devops-jira-and-other-systems) |
 | Setup | **Setup, skills, and documentation**: Shows the model profiles and MCP servers, installs or repairs the browser engine, creates a forgeqe.yaml, manages skills, and answers questions about ForgeQE from its documentation and this list. | `forgeqe_setup`, `capabilities` | [docs](#2-scaffold-config) |
@@ -227,8 +228,12 @@ forgeqe prompts                     # every prompt, what it is for, and where it
 forgeqe prompts show test-agent     # the prompt as the agent gets it (includes expanded; --raw for the file)
 forgeqe prompts diff test-rules     # how your copy differs from ForgeQE's
 forgeqe prompts reset test-rules    # back to ForgeQE's (yours is kept as test-rules.md.bak)
+forgeqe prompts check               # how closely each prompt follows ASD-STE100 (exits 1 when one is below 80%)
+forgeqe prompts check brain         # the sentences to fix in one prompt, with the rule each one breaks
 ```
 
+**Writing style: ASD-STE100.** Every prompt ForgeQE ships is written in ASD-STE100 Simplified Technical English, so each agent reads one clear instruction at a time: an instruction has 20 words or fewer and a description 25 or fewer, one instruction per sentence, the active voice in instructions, and approved words ("make sure", not "ensure"; "for example", not "e.g."). `forgeqe prompts check` scores each prompt in use, ForgeQE's or your edited copy, as the share of sentences that keep these rules; ForgeQE's own are held to at least 80% by its tests. Write your edits the same way. The check covers the rules that can be measured in text and a list of common words the standard does not approve; the standard's full approved-word dictionary is licensed and not included.
+
 **Product knowledge.** Fill in the templates (or add your own `.md` and `.txt` files, in folders if you like), one topic per `##` heading. ForgeQE's agent sees the list and reads what a request needs; the exploratory and API scenario planners get the sections that match their story or scenario; the browser agent gets the few sections that clearly match its goal, at most `knowledge.browser_max_chars` (1500 by default; 0 turns it off). Untouched templates are left out, so their examples never reach an agent. Never put passwords or tokens there: use logins and environment variables.
 
 ### Signing in to your tools
@@ -366,6 +371,18 @@ While a run is going, the bar under the prompt shows a spinner, the tokens used,
 
 The text is the agent's own result. Failed runs show `✗ Task failed` with the reason, and stopped runs show `■ Run stopped`. `forgeqe run` prints the same summary at the end.
 
+### Reports from the agent
+
+Ask for a report and ForgeQE's agent writes one you can share: "create a release report for all projects", "write up the open defects", "summarise this sprint's test results as a report". It gathers the facts with its tools (Azure DevOps, Jira, the runs it made), then saves the report with `write_report` as a Markdown file and an HTML page in the reports folder (`export.out_dir`, `.forgeqe/reports/` by default):
+
+```
+.forgeqe/reports/release-status-all-projects-20261009-001512/
+  report.md     # to edit, paste into a wiki, or attach
+  report.html   # to open or share; light and dark, tables scroll on a phone
+```
+
+The chat gets a short summary and a card with both paths as links, and **Open the report** appears as a next step. The report holds only what the agent read in that request. To post it, ask for it ("post the report to the release channel") once `notify.channels` is set up; the reports folder is linked when it is served (`notify.report_url`).
+
 ### The screen
 
 On a terminal 120 columns wide or more, the shell splits in two once you send a request:
@@ -375,6 +392,12 @@ On a terminal 120 columns wide or more, the shell splits in two once you send a
 
 On a narrower terminal the chat fills the screen, and Ctrl-O switches between the chat and the same panels.
 
+**Buttons.** Under the prompt: **✦ Refine** (Ctrl-R; it fills in once there is text to refine) and **⌕ Search** (Ctrl-P, the command palette); while a request runs, **■ Stop** (Esc) takes Refine's place. In the status line above the panels: **▦ Panels** (Shift-Tab) and **⤢ Wide chat**, which gives the conversation the whole width for reading a long answer; **◧ Split view**, under the prompt, brings the panels back. On a narrow terminal, **◧ Details** (Ctrl-O) and **⇄ Profile** (Tab) are under the prompt. Each is clickable.
+
+**Progress.** While a request runs, the status line above the panels shows a bar for how far the agent's plan has got (`███████░░░░░ 2/3`), or the suite's cases while a suite runs.
+
+**Replies.** The agent's answers lead with the answer, then short headed sections; lists keep their bullets in a column, so a wrapped line stays under its text instead of running back to the margin.
+
 **Moving between panels.** Shift-Tab (or a click) moves the keys from the prompt to Plan, Activity, then Files; the focused panel's border lights up and shows its keys. Esc, or typing, goes back to the prompt.
 
 | Panel | Keys |
@@ -391,9 +414,26 @@ On a narrower terminal the chat fills the screen, and Ctrl-O switches between th
 
 **`/` and `@` in the prompt.** Typing `/` lists the commands that match; typing `@` suggests references: recent runs (*last run*, then each by its folder), files in the repository by name or path (`@Login` finds `pages/Login.ts`), and, after `@` and a number such as `@1761`, the Azure DevOps work item with its title (read-only). Tab completes, ↑/↓ choose, Esc closes the list.
 
-**Refine.** Ctrl-R (or *Refine my request* in the palette) turns what you typed into a precise request before it is sent. A read-only agent checks it against this setup: what ForgeQE can do here, the systems that are set up, the project's sprints and test cases, and recent runs. It shows the refined request with what it **checked** ✓, what it **assumed** ~, and what is **missing** ?. Enter uses it, `e` puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item.
+**Refine.** Ctrl-R (or *Refine my request* in the palette) turns what you typed into a task specification for ForgeQE's agent, in ASD-STE100 Simplified Technical English, before it is sent:
+
+```
+Goal: Check the Azure DevOps QI-Payments pipelines and make a shareable report for the manager.
+
+Context:
+- Project: Azure DevOps project QI-Payments.
+- Pipeline: build definition 32, QI-Payments-CD.
+- Latest checked CD build: build 1021, failed, finished 2026-09-21.
+
+Steps:
+1. Review the recent runs of QI-Payments-CI and QI-Payments-CD.
+2. Make a shareable report with a short manager summary.
+
+Result: A shareable report file with a short summary for the manager.
+```
+
+A read-only agent writes it. It starts knowing every capability and whether it works in this setup, and the domain; it checks names and ids in the systems that are set up (work items, test plans, pipelines, sprints, recent runs). The panel shows the request with what it **checked** ✓, what it **assumed** ~, and what is **missing** ? (for example "Which story? Give the work item id"); a capability that is not set up shows as missing too. Enter sends it, `e` puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item; it never invents an id, URL, project, or file.
 
-**Next steps.** When a request finishes, up to three suggestions appear above the prompt, such as *Write a test for this run*, *Why did it fail?*, *Open the report*, or *Rerun the cases that failed*. Click one or press Alt-1 to Alt-3; suggestions that start work are put in the prompt first.
+**Next steps.** When a request finishes, up to three suggestions appear above the prompt: from what it produced (*Open the report*, *Write a test for this run*, *Why did it fail?*, *Rerun the cases that failed*) and from the agent's answer, which suggests the follow-ups you are likely to want (*Write a release report*, *Show the failed CD logs*). Click one or press Alt-1 to Alt-3; suggestions that start work are put in the prompt first, to adjust and send.
 
 | Key | Action |
 |-----|--------|

package/docs/user-guide.html

@@ -286,7 +286,7 @@ forgeqe docs --copy ./docs   # copy the guide, the architecture page, and the re
 <div class="area"><a class="area-name" href="#area-pull-requests"><span class="mono">Pull requests</span></a><ul class="tiles"><li><a class="tile" href="#cap-pr-review"><b>Review pull requests</b><span>Review PR 42 and focus on error handling</span></a></li><li><a class="tile" href="#cap-pr-impact"><b>Pull request impact and test selection</b><span>What does PR 42 impact?</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-api"><span class="mono">API</span></a><ul class="tiles"><li><a class="tile" href="#cap-api-testing"><b>API and contract testing</b><span>Turn the last run's API calls into tests</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-quality"><span class="mono">Quality</span></a><ul class="tiles"><li><a class="tile" href="#cap-accessibility-performance"><b>Accessibility and page performance</b><span>Is the checkout page accessible?</span></a></li><li><a class="tile" href="#cap-visual-comparison"><b>Visual comparison with baselines</b><span>What changed visually since the last run?</span></a></li></ul></div>
-<div class="area"><a class="area-name" href="#area-release"><span class="mono">Release</span></a><ul class="tiles"><li><a class="tile" href="#cap-release-readiness"><b>Requirement coverage and release readiness</b><span>Are we ready to release?</span></a></li></ul></div>
+<div class="area"><a class="area-name" href="#area-release"><span class="mono">Release</span></a><ul class="tiles"><li><a class="tile" href="#cap-release-readiness"><b>Requirement coverage and release readiness</b><span>Are we ready to release?</span></a></li><li><a class="tile" href="#cap-reports"><b>Reports you can share</b><span>Create a release report for all projects</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-operations"><span class="mono">Operations</span></a><ul class="tiles"><li><a class="tile" href="#cap-monitoring"><b>Scheduled monitoring with alerts</b><span>Check the login flow every 15 minutes and alert Teams</span></a></li><li><a class="tile" href="#cap-notifications"><b>Teams and email notifications</b><span>Post the results to the QA channel</span></a></li><li><a class="tile" href="#cap-pipelines"><b>CI pipelines</b><span>Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make it green</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-systems"><span class="mono">Systems</span></a><ul class="tiles"><li><a class="tile" href="#cap-systems"><b>Work with Azure DevOps, Jira, and Confluence</b><span>Show the open bugs in this sprint</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-setup"><span class="mono">Setup</span></a><ul class="tiles"><li><a class="tile" href="#cap-setup-help"><b>Setup, skills, and documentation</b><span>What can you do?</span></a></li></ul></div>
@@ -428,7 +428,10 @@ bun src/index.ts init --global --profile azure-gpt4o
 forgeqe prompts show test-agent     # the prompt as the agent gets it (includes expanded; --raw for the file)
 forgeqe prompts diff test-rules     # how your copy differs from ForgeQE's
 forgeqe prompts reset test-rules    # back to ForgeQE's (yours is kept as test-rules.md.bak)
+forgeqe prompts check               # how closely each prompt follows ASD-STE100 (exits 1 when one is below 80%)
+forgeqe prompts check brain         # the sentences to fix in one prompt, with the rule each one breaks
 </code></pre>
+<p><strong>Writing style: ASD-STE100.</strong> Every prompt ForgeQE ships is written in ASD-STE100 Simplified Technical English, so each agent reads one clear instruction at a time: an instruction has 20 words or fewer and a description 25 or fewer, one instruction per sentence, the active voice in instructions, and approved words (&quot;make sure&quot;, not &quot;ensure&quot;; &quot;for example&quot;, not &quot;e.g.&quot;). <code>forgeqe prompts check</code> scores each prompt in use, ForgeQE's or your edited copy, as the share of sentences that keep these rules; ForgeQE's own are held to at least 80% by its tests. Write your edits the same way. The check covers the rules that can be measured in text and a list of common words the standard does not approve; the standard's full approved-word dictionary is licensed and not included.</p>
 <p><strong>Product knowledge.</strong> Fill in the templates (or add your own <code>.md</code> and <code>.txt</code> files, in folders if you like), one topic per <code>##</code> heading. ForgeQE's agent sees the list and reads what a request needs; the exploratory and API scenario planners get the sections that match their story or scenario; the browser agent gets the few sections that clearly match its goal, at most <code>knowledge.browser_max_chars</code> (1500 by default; 0 turns it off). Untouched templates are left out, so their examples never reach an agent. Never put passwords or tokens there: use logins and environment variables.</p>
 </div></section>
 <section class="doc sub" id="doc-how_to_use-signing-in-to-your-tools"><h4>Signing in to your tools</h4><div class="prose"><p>Instead of copying tokens into <code>.env</code>, sign in once and ForgeQE saves the token in your system's credential store: the macOS Keychain, Windows Credential Manager, or the Secret Service keyring on Linux. On a machine without one, such as a headless Linux box, it uses <code>~/.forgeqe/credentials.json</code>, readable only by you.</p>
@@ -550,6 +553,9 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 <li><strong>Right (60%)</strong>: a status line with who is working, for how long, and a <strong>■ Stop</strong> button (a running suite adds a progress bar, <code>██████░░░░░░ 5/8</code>); then <strong>Plan</strong> (the agent's to-do list, then each browser step or suite case with ✓, ✗ and why, ◐ running), <strong>Activity</strong> (every tool call, browser step, and the agents' reasoning), <strong>Files</strong> (each file read ◉, written ✚, or edited ✎, newest first), <strong>Context</strong> (how full the model's context window is, and the skills, product knowledge, domain, and MCP servers in it), and <strong>Tokens</strong> (total, input, output, cached; no prices, which are in reports and <code>forgeqe models</code>).</li>
 </ul>
 <p>On a narrower terminal the chat fills the screen, and Ctrl-O switches between the chat and the same panels.</p>
+<p><strong>Buttons.</strong> Under the prompt: <strong>✦ Refine</strong> (Ctrl-R; it fills in once there is text to refine) and <strong>⌕ Search</strong> (Ctrl-P, the command palette); while a request runs, <strong>■ Stop</strong> (Esc) takes Refine's place. In the status line above the panels: <strong>▦ Panels</strong> (Shift-Tab) and <strong>⤢ Wide chat</strong>, which gives the conversation the whole width for reading a long answer; <strong>◧ Split view</strong>, under the prompt, brings the panels back. On a narrow terminal, <strong>◧ Details</strong> (Ctrl-O) and <strong>⇄ Profile</strong> (Tab) are under the prompt. Each is clickable.</p>
+<p><strong>Progress.</strong> While a request runs, the status line above the panels shows a bar for how far the agent's plan has got (<code>███████░░░░░ 2/3</code>), or the suite's cases while a suite runs.</p>
+<p><strong>Replies.</strong> The agent's answers lead with the answer, then short headed sections; lists keep their bullets in a column, so a wrapped line stays under its text instead of running back to the margin.</p>
 <p><strong>Moving between panels.</strong> Shift-Tab (or a click) moves the keys from the prompt to Plan, Activity, then Files; the focused panel's border lights up and shows its keys. Esc, or typing, goes back to the prompt.</p>
 <div class="tbl"><table>
 <thead>
@@ -565,8 +571,22 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 <p><strong>Setup checklist.</strong> Until everything is set up, the start screen shows what most features rest on: <strong>Model</strong> (a live model profile), <strong>Coding agent</strong>, <strong>Work items</strong> (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), <strong>Domain</strong>, and <strong>Notifications</strong>, each ✓ or ○. Click an open item to see how to set it up; <strong>Work items</strong> starts <code>/auth</code>. The checks are the same ones <code>/features</code> uses, so the two always agree.</p>
 <p><strong>Command palette.</strong> Ctrl-P opens a palette of every action, command, profile, and example request; type a few letters to find one (&quot;rr&quot; finds <em>Refine my request</em>, &quot;auth&quot; finds the sign-in commands), ↑/↓ to choose, Enter to run it. Example requests are put in the prompt for you to edit, never sent straight away.</p>
 <p><strong><code>/</code> and <code>@</code> in the prompt.</strong> Typing <code>/</code> lists the commands that match; typing <code>@</code> suggests references: recent runs (<em>last run</em>, then each by its folder), files in the repository by name or path (<code>@Login</code> finds <code>pages/Login.ts</code>), and, after <code>@</code> and a number such as <code>@1761</code>, the Azure DevOps work item with its title (read-only). Tab completes, ↑/↓ choose, Esc closes the list.</p>
-<p><strong>Refine.</strong> Ctrl-R (or <em>Refine my request</em> in the palette) turns what you typed into a precise request before it is sent. A read-only agent checks it against this setup: what ForgeQE can do here, the systems that are set up, the project's sprints and test cases, and recent runs. It shows the refined request with what it <strong>checked</strong> ✓, what it <strong>assumed</strong> ~, and what is <strong>missing</strong> ?. Enter uses it, <code>e</code> puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item.</p>
-<p><strong>Next steps.</strong> When a request finishes, up to three suggestions appear above the prompt, such as <em>Write a test for this run</em>, <em>Why did it fail?</em>, <em>Open the report</em>, or <em>Rerun the cases that failed</em>. Click one or press Alt-1 to Alt-3; suggestions that start work are put in the prompt first.</p>
+<p><strong>Refine.</strong> Ctrl-R (or <em>Refine my request</em> in the palette) turns what you typed into a task specification for ForgeQE's agent, in ASD-STE100 Simplified Technical English, before it is sent:</p>
+<pre><code>Goal: Check the Azure DevOps QI-Payments pipelines and make a shareable report for the manager.
+
+Context:
+- Project: Azure DevOps project QI-Payments.
+- Pipeline: build definition 32, QI-Payments-CD.
+- Latest checked CD build: build 1021, failed, finished 2026-09-21.
+
+Steps:
+1. Review the recent runs of QI-Payments-CI and QI-Payments-CD.
+2. Make a shareable report with a short manager summary.
+
+Result: A shareable report file with a short summary for the manager.
+</code></pre>
+<p>A read-only agent writes it. It starts knowing every capability and whether it works in this setup, and the domain; it checks names and ids in the systems that are set up (work items, test plans, pipelines, sprints, recent runs). The panel shows the request with what it <strong>checked</strong> ✓, what it <strong>assumed</strong> ~, and what is <strong>missing</strong> ? (for example &quot;Which story? Give the work item id&quot;); a capability that is not set up shows as missing too. Enter sends it, <code>e</code> puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item; it never invents an id, URL, project, or file.</p>
+<p><strong>Next steps.</strong> When a request finishes, up to three suggestions appear above the prompt: from what it produced (<em>Open the report</em>, <em>Write a test for this run</em>, <em>Why did it fail?</em>, <em>Rerun the cases that failed</em>) and from the agent's answer, which suggests the follow-ups you are likely to want (<em>Write a release report</em>, <em>Show the failed CD logs</em>). Click one or press Alt-1 to Alt-3; suggestions that start work are put in the prompt first, to adjust and send.</p>
 <div class="tbl"><table>
 <thead>
 <tr><th>Key</th><th>Action</th></tr>
@@ -1559,6 +1579,28 @@ forgeqe visual approve --page /home  # make this run's /home the baseline (asks
 </section>
 </div>
 </article>
+<article class="spec feat" id="cap-reports">
+<div class="hd"><span class="mono">Release</span><h3>Reports you can share</h3></div>
+<p class="ds">Writes up what ForgeQE's agent found, such as release status across projects, open defects, or pipeline health, as a Markdown file and an HTML page in the reports folder, with a summary in the chat and links to open them.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Create a release report for all projects</li><li>Write up the open defects as a report I can share</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>A live model profile in llms.json (an API key or Microsoft Entra ID sign-in)</span></li></ul></div>
+<div class="fact"><span class="mono">Limits</span><ul class="plainlist"><li>The report holds what the agent read with its tools in this request; it does not invent figures, and it does not publish the page anywhere unless the reports folder is served (notify.report_url).</li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>write_report</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-reports-from-the-agent">
+<h4>Reports from the agent</h4>
+<div class="prose"><p>Ask for a report and ForgeQE's agent writes one you can share: &quot;create a release report for all projects&quot;, &quot;write up the open defects&quot;, &quot;summarise this sprint's test results as a report&quot;. It gathers the facts with its tools (Azure DevOps, Jira, the runs it made), then saves the report with <code>write_report</code> as a Markdown file and an HTML page in the reports folder (<code>export.out_dir</code>, <code>.forgeqe/reports/</code> by default):</p>
+<pre><code>.forgeqe/reports/release-status-all-projects-20261009-001512/
+  report.md     # to edit, paste into a wiki, or attach
+  report.html   # to open or share; light and dark, tables scroll on a phone
+</code></pre>
+<p>The chat gets a short summary and a card with both paths as links, and <strong>Open the report</strong> appears as a next step. The report holds only what the agent read in that request. To post it, ask for it (&quot;post the report to the release channel&quot;) once <code>notify.channels</code> is set up; the reports folder is linked when it is served (<code>notify.report_url</code>).</p>
+</div>
+</section>
+</div>
+</article>
 </section>
 <section class="chapter" id="area-operations" aria-labelledby="area-operations-h">
 <header class="chead"><span class="mono">11</span><h2 id="area-operations-h">Operations</h2><p>Monitoring and CI pipelines</p></header>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in Chrome and turns passing runs into tests in your repo",
   "license": "MIT",
   "type": "module",

package/prompts/README.md

@@ -16,7 +16,7 @@ project; leave it as it is to keep getting ForgeQE's improvements when you updat
 | api-scenarios.md | Plans API scenarios from test cases or plain English |
 | explore-charters.md | Plans exploratory charters for a story |
 | eval-judge.md | Scores the agent's test cases in `forgeqe eval domain` |
-| refine.md | Refine (ctrl+r) in the shell: makes what you typed precise, checked against what ForgeQE knows |
+| refine.md | Refine (ctrl+r) in the shell: turns what you typed into a task specification (Goal, Context, Steps, Rules, Result), checked against what ForgeQE knows |
 | skill-rule.md | How agents use skills (included in most prompts) |
 | domain-rule.md | How agents apply the product's industry risks and regulations, declared or worked out (included in every agent that analyses requirements or designs, writes, reviews, or heals tests) |
 | browser-*.md | The browser agent: error recovery, when a goal counts as done, recording checks, clicking so runs become tests, step verdicts for test cases, picking skills |
@@ -32,4 +32,9 @@ How it works:
 - `forgeqe prompts` lists every prompt and where it comes from; `forgeqe prompts diff <name>` shows how yours differs
   from ForgeQE's (and warns when ForgeQE's changed after you edited yours); `forgeqe prompts reset <name>` goes back
   to ForgeQE's (yours is kept as `<name>.md.bak`).
+- `forgeqe prompts check` scores each prompt against ASD-STE100 Simplified Technical English; `forgeqe prompts check
+  <name>` lists the sentences to fix. ForgeQE's own prompts keep at least 80% of their sentences to these rules:
+  - An instruction has 20 words or fewer. A description has 25 words or fewer.
+  - Give one instruction in each sentence. Start an instruction with a verb, in the active voice.
+  - Use approved words: "make sure", not "ensure"; "for example", not "e.g."; "use", not "utilize".
 - Changes to these prompts change how the agents behave: test a change on a few runs before you commit it.

package/prompts/api-scenarios.md

@@ -3,19 +3,30 @@ name: api-scenarios
 description: "Plans end-to-end API scenarios from test cases or plain English, against an API's operations."
 used_by: "api_scenarios from cases or text"
 ---
-You plan end-to-end API test scenarios. You get a list of an API's operations (each with its method, path, an example call, its answer's key fields, whether it needs auth, and whether it changes data) and either test cases or a scenario in plain English. You write each scenario as API calls in order. You do not call the API and do not change files.
+You plan end-to-end API test scenarios. You get a list of the operations of an API. For each operation, the list gives its method, its path, an example call, the key fields of its answer, whether it needs auth, and whether it changes data. You also get test cases, or a scenario in plain English. Write each scenario as API calls in sequence. You do not call the API, and you do not change files.
 
 Rules:
-- Use only operations from the list, by their exact id. When a step of the scenario has no operation that does it, do not invent an endpoint: name the step under unmatched.
-- Each step's path is the operation's example path with real values, or {{name}} where the value comes from an earlier answer. Save such values from the answer that gives them: save lists variable names and their path in that answer's JSON body (id, data.order.id, items[0].sku). Never use a variable before a step saves it.
-- Data the scenario creates must be new on every run: put {{$unique}} in emails, usernames, names, and references (user+{{$unique}}@example.com). {{$uuid}}, {{$now}}, and {{$randomInt}} are there too. Test data the case gives (a product, a coupon code) is used as given.
-- Checks: each step expects the status the operation gives on success, unless the case expects a refusal (then the refusal's status, e.g. 400, 401, 403, 404, 409, 422; list the acceptable ones). Put what the case's expected results say into expect_fields: a field path in that step's answer, with equals_json for a value that must hold (a status, a total the case states, a currency) or type for a field that must be there.
-- A scenario that creates data ends by deleting it when the API has an operation for that; also list those deletes under cleanup, which ForgeQE runs when the scenario fails part-way.
-- no_auth: true only for a step that checks a call without credentials is refused.
-- One scenario per test case, with its case_id. For plain English, one scenario unless it clearly describes several.
-- Keep the steps the scenario needs, no more: the API equivalent of what the case does and checks.
+- Use only operations from the list, with their exact id.
+- If no operation does a step of the scenario, do not invent an endpoint. Put the step under unmatched.
+- For the path of each step, use the example path of the operation with real values.
+- Write {{name}} where a value comes from an earlier answer.
+- Save that value from the answer that gives it. In save, list the variable names and their paths in the JSON body of that answer, for example id, data.order.id, or items[0].sku.
+- Do not use a variable before a step saves it.
+- The data that the scenario creates must be new on each run. Put {{$unique}} in emails, usernames, names, and references, for example user+{{$unique}}@example.com.
+- You can also use {{$uuid}}, {{$now}}, and {{$randomInt}}.
+- Use the test data that the case gives (a product, a coupon code) as the case gives it.
+- Checks: each step expects the status that the operation gives on success.
+- If the case expects a refusal, expect the status of that refusal, for example 400, 401, 403, 404, 409, or 422. List all the statuses that are acceptable.
+- Put what the expected results of the case say into expect_fields. Give a field path in the answer of that step.
+- Use equals_json for a value that must be true, for example a status, a total that the case states, or a currency. Use type for a field that must be in the answer.
+- A scenario that creates data must delete that data at the end, when the API has an operation for this.
+- Also list those deletes under cleanup. ForgeQE runs cleanup when the scenario fails before it ends.
+- Set no_auth to true only for a step that checks that the API refuses a call without credentials.
+- Plan one scenario for each test case, with its case_id.
+- For plain English, plan one scenario. Plan more only when the text clearly describes more than one.
+- Keep only the steps that the scenario needs: the API equivalent of what the case does and checks.
 
 {{> domain-rule}}
-Plan scenarios for these too, where the API touches them: repeated and concurrent requests, each role's access, personal data in responses, and the records an obligation requires.
+Where the API touches these items, plan scenarios for them too: repeated and concurrent requests, the access of each role, personal data in answers, and the records that an obligation needs.
 
 Finish with the structured result.

package/prompts/api-tests.md

@@ -3,37 +3,67 @@ name: api-tests
 description: "Writes API and contract tests (and end-to-end API scenarios) in the repository's own framework."
 used_by: "write_api_tests, forgeqe api tests"
 ---
-You are a senior test automation engineer working inside an existing repository. You write API and contract tests: tests that call an application's API directly (no browser) and check its answers.
+You are a senior test automation engineer in a repository that has tests. You write API and contract tests. These tests call the API of an application directly, without a browser, and check its answers.
 
-ForgeQE gives you a set of contracts: for each API operation, one example call (method, path, headers, body) and what the answer must look like: the status, the content type, the body's schema, and key fields (a few fields with their types, and a value only where it must not change, like a status). Contracts come from an API description (OpenAPI or Swagger, WSDL, GraphQL, .proto) or from the calls the application made while ForgeQE's browser used it.
+ForgeQE gives you a set of contracts. For each API operation, a contract gives one example call (method, path, headers, body). It also tells what the answer must be: the status, the content type, the schema of the body, and key fields. Key fields are a few fields with their types. They have a value only where the value must not change, for example a status. Contracts come from an API description (OpenAPI or Swagger, WSDL, GraphQL, .proto). Or they come from the calls that the application made while the browser of ForgeQE used it.
 
-Know the repository:
-- Find the test framework, how one test or file is run, and what the repository already uses to call HTTP APIs in tests (Playwright's request fixture / APIRequestContext, supertest, axios, requests or httpx with pytest, REST Assured, RestSharp or HttpClient with NUnit or xUnit, Karate...). Use that. When it has none, use the one that fits its framework (Playwright Test: the request fixture; pytest: requests; JUnit: REST Assured; .NET: HttpClient) and add the dependency.
-- If the repository has no tests at all, add Playwright Test with TypeScript and use its request fixture.
+Learn the repository:
+- Find the test framework, and how to run one test or one file.
+- Find what the repository uses to call HTTP APIs in tests, and use it. Examples are the request fixture or APIRequestContext of Playwright, supertest, axios, requests or httpx with pytest, REST Assured, RestSharp or HttpClient with NUnit or xUnit, and Karate.
+- If it has none, use the one that fits its framework, and add the dependency. For Playwright Test, use the request fixture. For pytest, use requests. For JUnit, use REST Assured. For .NET, use HttpClient.
+- If the repository has no tests, add Playwright Test with TypeScript, and use its request fixture.
 
 {{> skill-rule}}
 
 Write the tests:
-- One test per contract you are given, grouped in one file per API or resource (or the repository's layout for API tests). Name each test after the operation, e.g. "GET /api/orders/{id} returns the order".
-- Each test makes the example call and checks: the status; the content type; the body against the schema (with the repository's schema validator when it has one, such as ajv, jsonschema, or Json.NET Schema; else assert each required field and its type); and the key fields. A key field with a value is checked for that value; others only for being present with the right type. Never assert values that change with data (ids, names, totals, dates) unless the contract pins them.
-- GraphQL: POST the query and variables, and also check the answer has no errors array. SOAP: POST the envelope with its SOAPAction or content type, and check there is no Fault and the listed elements are present. gRPC: use the repository's gRPC client or grpcurl in a test helper; check the status code is OK and the fields.
-- The base URL comes from configuration, never hardcoded in a test: the repository's existing setting (baseURL in playwright.config, an env file, appsettings) or an environment variable API_BASE_URL with the given base URL as its default.
-- Credentials come only from environment variables. ForgeQE gives the variable names to read (for example API_TOKEN), never the values. Never print them.
-- Test data lives in the test or the repository's data files: path parameters, query values, and bodies as parameters or fixtures. A contract that says it needs real values gets them from environment variables or data files the user fills in, with a clear skip when they are missing, not made-up values that would fail.
-- A contract that changes data (POST, PUT, PATCH, DELETE, mutations) is only written when ForgeQE asks for it; then create what it needs in the test and clean up after it where the API allows.
-- Follow the repository's conventions and standards (naming, folders, lint rules, assertion style). The build must not gain warnings.
-- Never delete, revert, or move a file you did not create in this job. ForgeQE's files (.forgeqe/, forgeqe.yaml, llms.json) belong to ForgeQE.
-
-Scenarios (calls in order, each using values earlier answers gave):
-- Before writing, map the repository's existing API layer: its API clients, request helpers, page-object-like service classes, auth and base URL fixtures, data builders, and schemas. For each operation a scenario calls, use the helper that already calls it (e.g. CartApi.create()); add a helper only for operations that have none, in the same style and place as the others.
-- Reuse helpers, never tests: a scenario calls helpers, it never runs another test as a step. Each scenario test sets up its own data and passes values from one call to the next in variables ({{orderId}} in the plan).
-- Change a shared helper only by adding to it (a new optional parameter, a new method), so tests that already use it keep working. When you change a helper other tests use, report a command that runs those tests as regression_command; ForgeQE runs it too.
-- {{$unique}} in the plan means a value that is new on every run: generate it in the test (a timestamp or random suffix). Cleanup steps go in the test's teardown (afterEach, finally, fixture teardown) and run even when a step fails.
-- Name each scenario's test after its test case when it has one, e.g. "ADO-2238 Customer orders with a coupon", and report each scenario's test name in scenario_tests.
-
-Running them: do not run the tests yourself. When you reply, ForgeQE runs the command you report and, if it fails, sends you the output. A failure is a test problem, or a real difference between the API and its contract: when the API answers differently from the contract on a point the contract got from a single observation (a field that is optional, a status that varies), fix the test to the rule that holds; when the API is clearly wrong (a 500, a missing required field), keep the check and say so in notes.
+- Write one test for each contract that you get. Put the tests in one file for each API or resource, or use the layout of the repository for API tests.
+- Name each test after its operation, for example "GET /api/orders/{id} returns the order".
+- Each test makes the example call. It checks the status, the content type, the body against the schema, and the key fields.
+- To check the schema, use the schema validator of the repository when it has one, such as ajv, jsonschema, or Json.NET Schema. If not, assert each required field and its type.
+- Check a key field that has a value for that value. Check the other key fields only for their presence and type.
+- Do not assert values that change with data (ids, names, totals, dates), unless the contract gives them.
+- GraphQL: POST the query and the variables. Also make sure that the answer has no errors array.
+- SOAP: POST the envelope with its SOAPAction or content type. Make sure that there is no Fault, and that the listed elements are in the answer.
+- gRPC: use the gRPC client of the repository, or grpcurl in a test helper. Make sure that the status code is OK, and check the fields.
+- Take the base URL from the configuration. Do not write it in a test.
+- Use the setting that the repository has (baseURL in playwright.config, an env file, appsettings). Or use an environment variable API_BASE_URL, with the base URL that you get as its default.
+- Take credentials only from environment variables. ForgeQE gives the names of the variables (for example API_TOKEN), not the values. Do not print them.
+- Put test data in the test or in the data files of the repository. Give path parameters, query values, and bodies as parameters or fixtures.
+- Some contracts say that they need real values. Get these values from environment variables or data files that the user fills in. If they are missing, skip the test with a clear message. Do not invent values that will fail.
+- Write a contract that changes data (POST, PUT, PATCH, DELETE, mutations) only when ForgeQE asks for it.
+- Then create what it needs in the test. Remove that data after the test, where the API allows it.
+- Follow the conventions and standards of the repository: names, folders, lint rules, and assertion style. The build must not get more warnings.
+- Do not delete, revert, or move a file that you did not make in this job. The files .forgeqe/, forgeqe.yaml, and llms.json belong to ForgeQE.
+
+Scenarios (calls in sequence; each call uses values that earlier answers gave):
+- Before you write, find the API layer of the repository. This includes its API clients, request helpers, service classes like page objects, auth and base URL fixtures, data builders, and schemas.
+- For each operation that a scenario calls, use the helper that calls it now, for example CartApi.create().
+- Add a helper only for an operation that has no helper. Use the same style and place as the other helpers.
+- Use helpers again, but not tests. A scenario calls helpers. It does not run a different test as a step.
+- Each scenario test sets up its own data. It gives values from one call to the next in variables ({{orderId}} in the plan).
+- Change a shared helper only by adding to it, for example a new optional parameter or a new method. The tests that use it then continue to work.
+- When you change a helper that other tests use, report a command that runs those tests as regression_command. ForgeQE runs it too.
+- {{$unique}} in the plan is a value that is new on each run. Make it in the test, for example from a timestamp or a random suffix.
+- Put cleanup steps in the teardown of the test (afterEach, finally, fixture teardown). They run also when a step fails.
+- When a scenario has a test case, name its test after the test case, for example "ADO-2238 Customer orders with a coupon".
+- Report the test name of each scenario in scenario_tests.
+
+How the tests run:
+- Do not run the tests yourself. When you reply, ForgeQE runs the command that you give. If it fails, ForgeQE sends you the output.
+- A failure is a test problem, or a real difference between the API and its contract.
+- The contract can have a point from one observation only, for example a field that is optional or a status that changes. If the API answers differently on such a point, correct the test to the rule that is always true.
+- If the API is clearly wrong (a 500, a required field that is missing), keep the check. Say so in notes.
 
 {{> domain-rule}}
-For APIs this means, where the API touches them: money-moving and state-changing calls are idempotent (a repeated request with the same key changes nothing twice), each role gets only what it may (others get 401 or 403), responses do not expose more personal data than the caller needs, errors do not leak internals, and changes that must be audited are.
+For APIs, apply these rules where the API touches them:
+- Calls that move money or change a state are idempotent. A repeated request with the same key does not change a thing two times.
+- Each role gets only what it can get. Other roles get 401 or 403.
+- Answers do not show more personal data than the caller needs.
+- Errors do not show internal data.
+- The system audits the changes that it must audit.
 
-Finish with the structured result: status (passed when the tests are ready to run, or blocked with the reason), the test file, the command that runs only these tests from the repository root without prompts or watch mode, what you reused, what you changed, and short notes.
+Finish with the structured result:
+- status: passed when the tests are ready to run, or blocked with the reason.
+- The test file.
+- The command that runs only these tests from the repository root, with no prompts and no watch mode.
+- What you used again, what you changed, and short notes.