ennodia 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +60 -36
- package/README.md +74 -58
- package/bench/README.md +7 -5
- package/bench/bug-recall/run.ts +12 -4
- package/bin/ennodia +23 -2
- package/docs/assets/agents/mcp.svg +1 -1
- package/docs/assets/orchestration-pipeline.svg +4 -3
- package/docs/comparisons/agent-frameworks.md +15 -10
- package/docs/comparisons/autogen.md +20 -15
- package/docs/comparisons/chathub.md +15 -14
- package/docs/comparisons/index.md +30 -22
- package/docs/comparisons/langgraph.md +19 -12
- package/docs/comparisons/mixture-of-agents.md +20 -17
- package/docs/comparisons/model-merging.md +7 -5
- package/docs/comparisons/openrouter.md +30 -22
- package/docs/concepts/compositional-audits.md +16 -13
- package/docs/concepts/data-governance.md +31 -15
- package/docs/concepts/how-ennodia-works.md +48 -22
- package/docs/concepts/interfaces-and-core.md +19 -6
- package/docs/concepts/second-opinions.md +20 -20
- package/docs/getting-started.md +55 -27
- package/docs/guides/agent-skills.md +16 -13
- package/docs/guides/budgets-and-limits.md +30 -20
- package/docs/guides/running-better-audits.md +50 -44
- package/docs/index.md +60 -37
- package/docs/install.md +41 -32
- package/docs/reference/benchmarks.md +6 -4
- package/docs/reference/controlled-english.md +130 -0
- package/docs/reference/ennodia-io.md +28 -22
- package/docs/reference/mcp-tools.md +244 -87
- package/docs/reference/supported-harnesses.md +9 -9
- package/package.json +7 -5
- package/src/advisor.ts +685 -0
- package/src/budget.ts +25 -6
- package/src/cli.ts +1 -1
- package/src/compare.ts +248 -52
- package/src/compositional.ts +18 -0
- package/src/core.ts +547 -16
- package/src/harnesses.ts +33 -2
- package/src/index.ts +38 -0
- package/src/plan-advice.ts +601 -0
- package/src/runs.ts +74 -9
- package/src/server.ts +312 -46
- package/src/skills.ts +131 -11
- package/src/tasks.ts +192 -22
- package/src/version.ts +1 -1
|
@@ -1,24 +1,26 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
3
|
-
description: How
|
|
2
|
+
title: Better Audits
|
|
3
|
+
description: How Ennodia audits can detect product problems that users see, not only consistency issues.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Ennodia can
|
|
7
|
-
audit rubric. A vague request such as "audit the website" often
|
|
8
|
-
consistency pass
|
|
9
|
-
|
|
10
|
-
|
|
6
|
+
Ennodia can request review from multiple agents. The result still depends on the
|
|
7
|
+
audit rubric. A vague request such as "audit the website" often produces a
|
|
8
|
+
consistency pass.
|
|
9
|
+
|
|
10
|
+
This pass can find broken links, mismatched documentation, release metadata errors, type
|
|
11
|
+
errors, and copy drift. It does not prove that the page is clear to a first-time
|
|
12
|
+
visitor.
|
|
11
13
|
|
|
12
14
|
## Quick Recipe
|
|
13
15
|
|
|
14
|
-
Use a source-grounded audit
|
|
15
|
-
behavior, or another product's public surface:
|
|
16
|
+
Use a source-grounded audit for answers that depend on documentation,
|
|
17
|
+
standards, package behavior, or another product's public surface:
|
|
16
18
|
|
|
17
19
|
```json
|
|
18
20
|
{
|
|
19
21
|
"tool": "ennodia_run",
|
|
20
22
|
"arguments": {
|
|
21
|
-
"prompt": "Audit
|
|
23
|
+
"prompt": "Audit this documentation against the linked primary sources. Separate facts from judgment and recommend exact edits.",
|
|
22
24
|
"mode": "parallel",
|
|
23
25
|
"compare": true,
|
|
24
26
|
"skillIds": ["source-grounded-audit"]
|
|
@@ -26,8 +28,8 @@ behavior, or another product's public surface:
|
|
|
26
28
|
}
|
|
27
29
|
```
|
|
28
30
|
|
|
29
|
-
Install the skill first if the harness
|
|
30
|
-
[
|
|
31
|
+
Install the skill first if the harness does not have it. See
|
|
32
|
+
[Agent Skills](/docs/guides/agent-skills/).
|
|
31
33
|
|
|
32
34
|
## Pick the Audit Mode
|
|
33
35
|
|
|
@@ -35,63 +37,67 @@ Name the failure mode you want reviewers to catch.
|
|
|
35
37
|
|
|
36
38
|
| Audit mode | Main question |
|
|
37
39
|
| --- | --- |
|
|
38
|
-
| Consistency | Do the
|
|
40
|
+
| Consistency | Do the documentation, website, package metadata, and behavior agree? |
|
|
39
41
|
| Conversion | Would a first-time visitor understand why to install this? |
|
|
40
|
-
| Visual QA | Does the rendered page look balanced on desktop and mobile? |
|
|
42
|
+
| Visual quality assurance (QA) | Does the rendered page look balanced on desktop and mobile? |
|
|
41
43
|
| Accessibility | Can the page be navigated and understood with assistive technology? |
|
|
42
44
|
| Release | Can the package be published, installed, and launched safely? |
|
|
43
45
|
|
|
44
46
|
Use separate passes when the stakes are different. A page can pass consistency
|
|
45
47
|
and still fail conversion.
|
|
46
48
|
|
|
47
|
-
For a large review, split the work into focused slices
|
|
48
|
-
|
|
49
|
+
For a large review, split the work into focused slices. Do not send the entire
|
|
50
|
+
prompt to each reviewer. See
|
|
49
51
|
[Compositional Audits](/docs/concepts/compositional-audits/).
|
|
50
52
|
|
|
51
53
|
## Landing Page Rubric
|
|
52
54
|
|
|
53
|
-
For landing pages,
|
|
55
|
+
For landing pages, require each reviewer to answer these questions:
|
|
54
56
|
|
|
55
57
|
- Can a first-time visitor explain what the product does within ten seconds?
|
|
56
58
|
- Is the reason to install visible in the hero or first section?
|
|
57
59
|
- Is the install path visible before architecture details?
|
|
58
|
-
- Does the page use user language
|
|
60
|
+
- Does the page use user language and avoid maintainer language?
|
|
59
61
|
- Are screenshots or rendered viewports available for visual judgment?
|
|
60
|
-
- Does the final section strengthen trust
|
|
62
|
+
- Does the final section strengthen trust and avoid defensive copy?
|
|
61
63
|
|
|
62
|
-
For Ennodia
|
|
63
|
-
|
|
64
|
+
For Ennodia, use `mode: "parallel"` and `compare: true` for this type of review.
|
|
65
|
+
A single source-only answer is not sufficient for product pages.
|
|
64
66
|
|
|
65
67
|
## Include Rendered Evidence
|
|
66
68
|
|
|
67
|
-
Source-only review misses visual problems. Before
|
|
68
|
-
|
|
69
|
+
Source-only review misses visual problems. Before an Ennodia website review,
|
|
70
|
+
include desktop and mobile screenshots. You can also use a harness with browser
|
|
69
71
|
access to inspect the rendered page.
|
|
70
72
|
|
|
71
|
-
Rendered evidence
|
|
72
|
-
|
|
73
|
-
|
|
73
|
+
Rendered evidence can show oversized logos, unbalanced hero space, incorrect
|
|
74
|
+
text size, delayed content, and accidental visual hierarchy.
|
|
75
|
+
|
|
76
|
+
When local files matter, include the file paths and a short text description.
|
|
77
|
+
Then inspect the child outputs for access errors.
|
|
74
78
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
harness cannot read the files, stage them somewhere it can access and rerun; do
|
|
78
|
-
not treat that failure as a normal design review.
|
|
79
|
+
If a harness cannot read the files, put them in an accessible location and run
|
|
80
|
+
the task again. Do not treat that failure as a normal design review.
|
|
79
81
|
|
|
80
82
|
## Ground Standards in Sources
|
|
81
83
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
84
|
+
Include primary sources when an audit depends on an external standard, registry
|
|
85
|
+
convention, or product behavior. Require reviewers to separate facts from
|
|
86
|
+
judgment.
|
|
87
|
+
|
|
88
|
+
Without these sources, a model council can confidently use an incorrect model
|
|
89
|
+
of the world.
|
|
90
|
+
|
|
91
|
+
Agent Skills are one cautionary example. They are not an Ennodia-private prompt
|
|
92
|
+
format. They are portable `SKILL.md` folders.
|
|
86
93
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
skills must start from those product docs before recommending an Ennodia API.
|
|
94
|
+
Tools such as Codex, Claude Code, OpenCode, and Antigravity discover these
|
|
95
|
+
folders in native locations. Reviewers must read that product documentation
|
|
96
|
+
before they recommend an Ennodia application programming interface (API).
|
|
91
97
|
|
|
92
|
-
The bundled `source-grounded-audit` skill
|
|
93
|
-
|
|
94
|
-
|
|
98
|
+
The bundled `source-grounded-audit` skill supports this case. Install it in the
|
|
99
|
+
harnesses that perform standards-sensitive audits. Then tell Ennodia to use the
|
|
100
|
+
skill when the answer depends on external documentation.
|
|
95
101
|
|
|
96
102
|
## Good Prompt Shape
|
|
97
103
|
|
|
@@ -107,11 +113,11 @@ If screenshots are available, judge the rendered page too.
|
|
|
107
113
|
|
|
108
114
|
Return:
|
|
109
115
|
1. The top conversion blockers, prioritized.
|
|
110
|
-
2.
|
|
116
|
+
2. If the first viewport explains what this is and why to install it.
|
|
111
117
|
3. Exact replacement copy for weak sections.
|
|
112
118
|
4. Visual changes needed for desktop and mobile.
|
|
113
119
|
5. Which issues a consistency-only audit would miss.
|
|
114
120
|
```
|
|
115
121
|
|
|
116
|
-
The last item
|
|
117
|
-
|
|
122
|
+
The last item makes the reviewer state the audit limits. This information helps
|
|
123
|
+
you decide if another pass is necessary.
|
package/docs/index.md
CHANGED
|
@@ -1,72 +1,89 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: What is Ennodia?
|
|
3
|
-
description: Start here to understand Ennodia,
|
|
3
|
+
description: Start here to understand Ennodia, select an installation path, and find the documentation page for your task.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Ennodia is a local MCP server for multi-agent review.
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
Ennodia is a local Model Context Protocol (MCP) server for multi-agent review.
|
|
7
|
+
Your primary artificial intelligence (AI) agent can request help from installed
|
|
8
|
+
agent command-line interfaces (CLIs).
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
10
|
+
The primary agent can inspect the work. It can use a Judge and Result Advisor to
|
|
11
|
+
compare the answers.
|
|
12
|
+
|
|
13
|
+
An optional Plan Advisor can first propose a bounded team. It cannot execute the
|
|
14
|
+
proposal.
|
|
15
|
+
|
|
16
|
+
Use Ennodia when one agent has a task that needs additional review, a plan, a
|
|
17
|
+
diagnosis, or a comparison. A run usually takes minutes.
|
|
18
|
+
|
|
19
|
+
Compare adds a serial Judge pass and a serial Result Advisor pass after the
|
|
20
|
+
child agents finish.
|
|
15
21
|
|
|
16
22
|
## The Problem Ennodia Solves
|
|
17
23
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
24
|
+
Single-model judgment can be a single point of failure. One agent can miss a
|
|
25
|
+
risky bug, accept a weak plan, or report false confidence.
|
|
26
|
+
|
|
27
|
+
Important work can require independent second opinions and a record of each
|
|
28
|
+
reviewer's work.
|
|
22
29
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
primary agent can use, without new accounts, API keys, or vendor migration:
|
|
30
|
+
Many developers have independent agent subscriptions. Examples include Codex,
|
|
31
|
+
Claude Code, Antigravity, and OpenCode. Ennodia makes their installed CLIs a
|
|
32
|
+
review panel for the primary agent.
|
|
27
33
|
|
|
28
|
-
|
|
29
|
-
|
|
34
|
+
This process does not require new accounts or a vendor migration. It does not
|
|
35
|
+
require new application programming interface (API) keys.
|
|
36
|
+
|
|
37
|
+
- Agents reach Ennodia through MCP, a protocol that the agents support.
|
|
38
|
+
- A Plan Advisor can propose inert harness, model, and skill assignments. A
|
|
39
|
+
separate explicit call must launch the validated plan.
|
|
40
|
+
- Model-led Compare uses a Judge for the disagreement map and a Result Advisor
|
|
41
|
+
for the recommended answer.
|
|
30
42
|
- One shared core discovers harnesses, plans routes, checks local preflight
|
|
31
43
|
limits, tracks tasks, and keeps the trace visible.
|
|
32
|
-
- The separate Ennodia IO package is an experimental
|
|
44
|
+
- The separate Ennodia IO package is an experimental appendix for apps.
|
|
33
45
|
|
|
34
46
|
## Why People Use It
|
|
35
47
|
|
|
36
48
|
Ennodia:
|
|
37
49
|
|
|
38
50
|
- discovers supported local harnesses automatically
|
|
39
|
-
- uses
|
|
51
|
+
- uses your installed CLIs, subscriptions, and model choices
|
|
40
52
|
- estimates preflight input-token budgets and enforces local caps on that
|
|
41
53
|
estimate
|
|
42
|
-
- keeps child task IDs, status,
|
|
43
|
-
|
|
44
|
-
|
|
54
|
+
- keeps child task identifiers (IDs), status, estimated completion time,
|
|
55
|
+
output, failures, Compare state, and run
|
|
56
|
+
history visible
|
|
57
|
+
- can retain terminal receipts across server restarts
|
|
58
|
+
- lets a Judge inspect parallel answers and a Result Advisor combine the
|
|
59
|
+
findings
|
|
45
60
|
- uses native Agent Skills through harness-visible `SKILL.md` folders
|
|
46
61
|
|
|
47
|
-
Durable model and skill preference memory is roadmap work.
|
|
48
|
-
|
|
49
|
-
|
|
62
|
+
Durable model and skill preference memory is roadmap work. By default, Ennodia
|
|
63
|
+
stores terminal run history under `~/.ennodia/history/`. Live in-progress state
|
|
64
|
+
remains process-local.
|
|
50
65
|
|
|
51
66
|
## Choose Your Path
|
|
52
67
|
|
|
53
|
-
|
|
|
68
|
+
| Task | Page |
|
|
54
69
|
| --- | --- |
|
|
55
|
-
|
|
|
56
|
-
|
|
|
70
|
+
| Request Ennodia installation from an agent | [Installation for Agents](./install/) |
|
|
71
|
+
| Install it manually or work from a checkout | [Quickstart](./getting-started/) |
|
|
57
72
|
| Estimate or limit a costly run | [Budgets and Limits](./guides/budgets-and-limits/) |
|
|
58
|
-
| Install or use `source-grounded-audit` and other skills | [
|
|
73
|
+
| Install or use `source-grounded-audit` and other skills | [Agent Skills](./guides/agent-skills/) |
|
|
59
74
|
| Understand the run lifecycle | [How Ennodia Works](./concepts/how-ennodia-works/) |
|
|
75
|
+
| Request a bounded team proposal before work | [How Ennodia Works](./concepts/how-ennodia-works/#plan-advisor) |
|
|
60
76
|
| Use panels for second opinions | [Second Opinions as Infrastructure](./concepts/second-opinions/) |
|
|
61
77
|
| Understand local storage and data movement | [Data Governance](./concepts/data-governance/) |
|
|
62
78
|
| Understand Core, <span class="agent-logo agent-logo--mcp" aria-hidden="true"></span>MCP, and experimental IO | [Interfaces and Core](./concepts/interfaces-and-core/) |
|
|
63
79
|
| Split a large review into smaller shards | [Compositional Audits](./concepts/compositional-audits/) |
|
|
64
80
|
| Call the exact <span class="agent-logo agent-logo--mcp" aria-hidden="true"></span>MCP tools | [MCP Tools](./reference/mcp-tools/) |
|
|
65
|
-
| Call Ennodia from a local
|
|
66
|
-
| Check harness
|
|
81
|
+
| Call Ennodia from a local web app | [Ennodia IO](./reference/ennodia-io/) |
|
|
82
|
+
| Check harness identifiers and installation notes | [Supported Harnesses](./reference/supported-harnesses/) |
|
|
83
|
+
| Use the ASD-STE100 rules and approved Ennodia terms | [Controlled English](./reference/controlled-english/) |
|
|
67
84
|
| Inspect benchmark receipts | [Benchmarks](./reference/benchmarks/) |
|
|
68
|
-
| Decide
|
|
69
|
-
| Get better output from model-led Compare | [
|
|
85
|
+
| Decide if Ennodia fits your workflow | [Comparisons](./comparisons/) |
|
|
86
|
+
| Get better output from model-led Compare | [Better Audits](./guides/running-better-audits/) |
|
|
70
87
|
|
|
71
88
|
## First Useful Run
|
|
72
89
|
|
|
@@ -77,5 +94,11 @@ state remains process-local.
|
|
|
77
94
|
5. Poll `ennodia_get_run` until it reaches `succeeded`, `failed`, or
|
|
78
95
|
`cancelled`.
|
|
79
96
|
|
|
80
|
-
The user
|
|
81
|
-
|
|
97
|
+
The user does not normally need to grade each child answer. The trace remains
|
|
98
|
+
available for inspection.
|
|
99
|
+
|
|
100
|
+
For a team proposal, call `ennodia_start_plan_advice`. Then poll
|
|
101
|
+
`ennodia_get_plan_advice`. A ready result is only validated data.
|
|
102
|
+
|
|
103
|
+
Call `ennodia_start_advised_plan` with the returned plan digest once to start the
|
|
104
|
+
work.
|
package/docs/install.md
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Installation for Agents
|
|
3
|
-
description: A copy-paste
|
|
3
|
+
description: A copy-paste installation page for agents that install Ennodia in Codex, Claude Code, OpenCode, Antigravity, and other Model Context Protocol (MCP) clients.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
This page is for the agent
|
|
7
|
-
|
|
8
|
-
client they use.
|
|
6
|
+
This page is for the agent that does the installation. Install Ennodia as a local Model
|
|
7
|
+
Context Protocol (MCP) server. Then enable it in the user's MCP client.
|
|
9
8
|
|
|
10
9
|
## Copy-Paste Prompt
|
|
11
10
|
|
|
@@ -15,18 +14,18 @@ try-ennodia.cherninlab.com
|
|
|
15
14
|
|
|
16
15
|
## Install Command
|
|
17
16
|
|
|
18
|
-
Use the npm package for normal MCP client
|
|
17
|
+
Use the npm package for normal MCP client installation:
|
|
19
18
|
|
|
20
19
|
```sh
|
|
21
20
|
npx -y ennodia
|
|
22
21
|
```
|
|
23
22
|
|
|
24
|
-
|
|
25
|
-
client supports Bun directly, `bunx ennodia
|
|
23
|
+
Ennodia requires Bun `1.3.14` or newer. `npx` downloads Ennodia. Bun runs it.
|
|
24
|
+
If the client supports Bun directly, use `bunx ennodia`.
|
|
26
25
|
|
|
27
|
-
## MCP
|
|
26
|
+
## MCP Configuration
|
|
28
27
|
|
|
29
|
-
Add this server to the user's MCP client
|
|
28
|
+
Add this server to the user's MCP client configuration:
|
|
30
29
|
|
|
31
30
|
```json
|
|
32
31
|
{
|
|
@@ -54,7 +53,7 @@ For a local Ennodia checkout, use:
|
|
|
54
53
|
|
|
55
54
|
## First Agent Checks
|
|
56
55
|
|
|
57
|
-
After
|
|
56
|
+
After MCP configuration, call these tools:
|
|
58
57
|
|
|
59
58
|
1. `ennodia_list_harnesses`
|
|
60
59
|
2. `ennodia_estimate_budget`
|
|
@@ -62,35 +61,44 @@ After configuring MCP, call these tools:
|
|
|
62
61
|
4. `ennodia_run`
|
|
63
62
|
5. `ennodia_get_run`
|
|
64
63
|
|
|
65
|
-
`ennodia_list_harnesses`
|
|
66
|
-
|
|
64
|
+
`ennodia_list_harnesses` shows the available local tools. See the current
|
|
65
|
+
adapter list and identifiers (IDs) in
|
|
67
66
|
[Supported Harnesses](/docs/reference/supported-harnesses/).
|
|
68
67
|
|
|
69
|
-
##
|
|
68
|
+
## Installed Components
|
|
70
69
|
|
|
71
|
-
Ennodia is a local MCP server. It lets the user's main agent
|
|
72
|
-
agent
|
|
70
|
+
Ennodia is a local MCP server. It lets the user's main agent request help from
|
|
71
|
+
other installed agent command-line interface (CLI) programs during the same task.
|
|
73
72
|
|
|
74
|
-
The
|
|
75
|
-
|
|
76
|
-
starts child tasks
|
|
77
|
-
and can ask a model to compare the answers before returning one result.
|
|
73
|
+
The number of agents is not the primary benefit. Ennodia uses current local
|
|
74
|
+
installs, subscriptions, and model choices. It discovers supported CLI programs and
|
|
75
|
+
starts child tasks. It also tracks status and output.
|
|
78
76
|
|
|
79
|
-
Ennodia
|
|
80
|
-
|
|
81
|
-
|
|
77
|
+
Ennodia estimates the input-token budget. A Judge can compare the answers. A
|
|
78
|
+
Result Advisor can then recommend one result.
|
|
79
|
+
|
|
80
|
+
An optional Plan Advisor can propose harness, model, and skill assignments. It
|
|
81
|
+
cannot start them. A separate explicit call must start the validated plan.
|
|
82
|
+
|
|
83
|
+
Ennodia is asynchronous by design. A primary agent can start a run and continue
|
|
84
|
+
its main task. It can later poll `ennodia_get_run` for status and estimated
|
|
85
|
+
completion time.
|
|
86
|
+
|
|
87
|
+
The result also contains child task IDs, Compare state, failures, and the final
|
|
88
|
+
answer.
|
|
82
89
|
|
|
83
90
|
Tell the user a real run can take minutes. Compare adds two serial model passes
|
|
84
91
|
after the selected child agents finish.
|
|
85
92
|
|
|
86
93
|
## Example Requests
|
|
87
94
|
|
|
88
|
-
Use Ennodia when the user
|
|
89
|
-
|
|
95
|
+
Use Ennodia when the user permits more model work to get a better answer than
|
|
96
|
+
one agent usually gives.
|
|
90
97
|
|
|
91
98
|
```text
|
|
92
|
-
Use Ennodia to
|
|
93
|
-
|
|
99
|
+
Use Ennodia to request a review from multiple available agents.
|
|
100
|
+
Compare the answers for this bug fix.
|
|
101
|
+
Name the disagreements and return the highest-risk issue first.
|
|
94
102
|
```
|
|
95
103
|
|
|
96
104
|
```text
|
|
@@ -99,19 +107,20 @@ Compare the plans and tell me which assumptions each model made.
|
|
|
99
107
|
```
|
|
100
108
|
|
|
101
109
|
```text
|
|
102
|
-
Use Ennodia twice
|
|
103
|
-
|
|
110
|
+
Use Ennodia twice.
|
|
111
|
+
Use source-grounded-audit for the first run, but not for the second run.
|
|
112
|
+
Compare the results before you recommend the final documentation edit.
|
|
104
113
|
```
|
|
105
114
|
|
|
106
|
-
Compare is model-led. The user
|
|
107
|
-
answers
|
|
115
|
+
Compare is model-led. The user does not normally need to judge the parallel
|
|
116
|
+
answers. The trace remains available for inspection.
|
|
108
117
|
|
|
109
118
|
## Optional Next Steps
|
|
110
119
|
|
|
111
120
|
- Use [Budgets and Limits](/docs/guides/budgets-and-limits/) before costly
|
|
112
121
|
parallel runs.
|
|
113
|
-
- Use [
|
|
122
|
+
- Use [Agent Skills](/docs/guides/agent-skills/) before you pass
|
|
114
123
|
`skillIds` such as `source-grounded-audit`.
|
|
115
124
|
- Use [Supported Harnesses](/docs/reference/supported-harnesses/) when a local
|
|
116
|
-
CLI is missing,
|
|
125
|
+
CLI is missing, not runnable, or has the wrong model ID.
|
|
117
126
|
- Use [MCP Tools](/docs/reference/mcp-tools/) for exact parameter shapes.
|
|
@@ -4,8 +4,8 @@ description: Deterministic benchmark snapshots for Ennodia's multi-agent bug-rec
|
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
The first benchmark is `multi-model-bug-recall`: TypeScript review fixtures with
|
|
7
|
-
committed bug oracles. It measures
|
|
8
|
-
|
|
7
|
+
committed bug oracles. It measures required-finding recall for a condition and
|
|
8
|
+
checks for known false-positive traps.
|
|
9
9
|
|
|
10
10
|
## Current Snapshot
|
|
11
11
|
|
|
@@ -19,6 +19,8 @@ bun run bench:bug-recall -- --out /tmp/ennodia-benchmark-snapshot
|
|
|
19
19
|
|
|
20
20
|
Mode: fixture, using committed reference outputs.
|
|
21
21
|
|
|
22
|
+
The F1 score combines recall and precision. FP means false positive.
|
|
23
|
+
|
|
22
24
|
| Condition | Cases | Recall | Precision | F1 | High recall | FP traps |
|
|
23
25
|
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
|
|
24
26
|
| `claude-code-solo` | 4 | 87.5% | 100% | 93.3% | 100% | 0 |
|
|
@@ -47,8 +49,8 @@ does not launch child agents:
|
|
|
47
49
|
bun run bench:bug-recall
|
|
48
50
|
```
|
|
49
51
|
|
|
50
|
-
Live mode starts real local harnesses and varies with installed
|
|
51
|
-
models, account state, and machine configuration:
|
|
52
|
+
Live mode starts real local harnesses and varies with installed command-line
|
|
53
|
+
interface (CLI) versions, models, account state, and machine configuration:
|
|
52
54
|
|
|
53
55
|
```sh
|
|
54
56
|
bun run bench:bug-recall:live -- --fixture 001-missing-await
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Controlled English
|
|
3
|
+
description: Ennodia terminology and writing rules for ASD-STE100 Issue 9.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Controlled English
|
|
7
|
+
|
|
8
|
+
Ennodia documentation uses ASD-STE100 Issue 9 as its writing standard.
|
|
9
|
+
This policy applies to the README, documentation, website text, and visible asset text.
|
|
10
|
+
|
|
11
|
+
Commands, API fields, status values, model IDs, and quoted interface text are data.
|
|
12
|
+
Keep this data exact, even when its text does not use controlled English.
|
|
13
|
+
|
|
14
|
+
## Writing Rules
|
|
15
|
+
|
|
16
|
+
- Use American English.
|
|
17
|
+
- Use active voice when the agent is known.
|
|
18
|
+
- Give one instruction in each procedural sentence.
|
|
19
|
+
- Use 20 words or fewer in a procedural sentence.
|
|
20
|
+
- Use 25 words or fewer in a descriptive sentence.
|
|
21
|
+
- Use six sentences or fewer in one paragraph.
|
|
22
|
+
- Do not use semicolons.
|
|
23
|
+
- Do not use a contraction.
|
|
24
|
+
- Use one approved term for each concept.
|
|
25
|
+
- Define a necessary abbreviation at its first use on each independent page.
|
|
26
|
+
- Preserve exact product names, commands, paths, model IDs, and API fields.
|
|
27
|
+
|
|
28
|
+
The landing page uses `AI makes mistakes` as an approved fixed tagline.
|
|
29
|
+
Define `artificial intelligence (AI)` in the sentence directly below it.
|
|
30
|
+
|
|
31
|
+
Automated checks can find some defects, but they cannot certify compliance.
|
|
32
|
+
A human reviewer must confirm meaning, grammar, and correct technical use.
|
|
33
|
+
|
|
34
|
+
## Ennodia Termbase
|
|
35
|
+
|
|
36
|
+
The Ennodia project approves the following terms for its software documentation.
|
|
37
|
+
Use the listed meaning and part of speech.
|
|
38
|
+
|
|
39
|
+
| Term | Type | Approved meaning |
|
|
40
|
+
| --- | --- | --- |
|
|
41
|
+
| Ennodia | technical noun | The software product in this repository. |
|
|
42
|
+
| artificial intelligence (AI) | technical noun | Software that produces or evaluates model output. |
|
|
43
|
+
| AI makes mistakes | approved tagline | The exact Ennodia landing-page headline. Keep this phrase unchanged. |
|
|
44
|
+
| Model Context Protocol (MCP) | technical noun | The protocol that exposes Ennodia tools to a compatible client. |
|
|
45
|
+
| command-line interface (CLI) | technical noun | A text interface that accepts commands. |
|
|
46
|
+
| application programming interface (API) | technical noun | A defined interface that software uses to exchange data. |
|
|
47
|
+
| Hypertext Transfer Protocol (HTTP) | technical noun | The protocol that Ennodia IO uses for local requests. |
|
|
48
|
+
| user interface (UI) | technical noun | The visible controls and output that a user can operate. |
|
|
49
|
+
| Ennodia IO | product name | The separate local HTTP package for Ennodia. |
|
|
50
|
+
| harness | technical noun | An Ennodia adapter that starts one supported local CLI. |
|
|
51
|
+
| model | technical noun | A named AI model that a harness can select. |
|
|
52
|
+
| large language model (LLM) | technical noun | A model that processes and produces language or code. |
|
|
53
|
+
| Agent Skill | technical noun | Installed instructions that a compatible harness can load. |
|
|
54
|
+
| skill | technical noun | The short form of Agent Skill after the full term appears. |
|
|
55
|
+
| task | technical noun | One harness process that Ennodia starts and tracks. |
|
|
56
|
+
| worker | technical noun | A task that performs one assigned part of a plan. |
|
|
57
|
+
| worker pool | technical noun | A defined group of workers with the same assignment type. |
|
|
58
|
+
| slice | technical noun | One focused part of a compositional task. |
|
|
59
|
+
| plan | technical noun | Validated data that defines ordered worker tasks. |
|
|
60
|
+
| plan digest | technical noun | A hash that identifies the exact validated plan. |
|
|
61
|
+
| inventory | technical noun | The runnable harnesses and installed skills that Ennodia finds. |
|
|
62
|
+
| inventory fingerprint | technical noun | A hash that identifies one inventory state. |
|
|
63
|
+
| Plan Advisor | technical noun | The role that proposes a bounded plan as inert data. |
|
|
64
|
+
| Judge | technical noun | The Compare role that maps agreements, conflicts, and risks. |
|
|
65
|
+
| Result Advisor | technical noun | The Compare role that recommends an answer from available evidence. |
|
|
66
|
+
| Compare | technical noun or verb | The Ennodia operation that uses a Judge and a Result Advisor. |
|
|
67
|
+
| run | technical noun or verb | A tracked orchestration, or the action that starts it. |
|
|
68
|
+
| receipt | technical noun | A bounded record of tasks, events, results, and execution data. |
|
|
69
|
+
| route | technical noun or verb | A harness selection, or the action that selects a harness. |
|
|
70
|
+
| poll | technical verb | To request current status at controlled intervals. |
|
|
71
|
+
| review | technical noun or verb | An inspection of code, documentation, or model output for defects. |
|
|
72
|
+
| standard input/output (stdio) | technical noun | The paired input and output streams of an MCP server process. |
|
|
73
|
+
| standard input (stdin) | technical noun | The input stream of a local process. |
|
|
74
|
+
| standard output (stdout) | technical noun | The normal output stream of a local process. |
|
|
75
|
+
| standard error (stderr) | technical noun | The error output stream of a local process. |
|
|
76
|
+
| token | technical noun | A model input or output unit. |
|
|
77
|
+
| budget | technical noun | A caller limit for tasks or estimated input tokens. |
|
|
78
|
+
| provider | technical noun | A company or service that supplies a model or harness. |
|
|
79
|
+
| subscription | technical noun | A provider plan that can set access or usage limits. |
|
|
80
|
+
| quota | technical noun | A provider limit on available usage. |
|
|
81
|
+
| estimated time of arrival (ETA) | technical noun | An estimate of the time until a task ends. |
|
|
82
|
+
| Cross-Origin Resource Sharing (CORS) | technical noun | An HTTP mechanism that controls browser access from another origin. |
|
|
83
|
+
| bring your own key (BYOK) | technical noun | An app pattern that uses credentials supplied by the user. |
|
|
84
|
+
| Codex | product name | The OpenAI coding-agent product. |
|
|
85
|
+
| Claude Code | product name | The Anthropic coding-agent product. |
|
|
86
|
+
| Antigravity | product name | The Google coding-agent CLI used by Ennodia. |
|
|
87
|
+
| Gemini | product name | A Google model family. |
|
|
88
|
+
| GPT | product name | An OpenAI model family. |
|
|
89
|
+
| OpenCode | product name | A supported coding-agent CLI. |
|
|
90
|
+
| Kilo Code | product name | A supported coding-agent CLI. |
|
|
91
|
+
| Hermes Agent | product name | A supported coding-agent CLI. |
|
|
92
|
+
| Kiro CLI | product name | A supported coding-agent CLI. |
|
|
93
|
+
| Cline | product name | A supported coding-agent CLI. |
|
|
94
|
+
| AutoGen | product name | An external multi-agent framework. |
|
|
95
|
+
| ChatHub | product name | An external multi-model comparison product. |
|
|
96
|
+
| LangGraph | product name | An external agent workflow framework. |
|
|
97
|
+
| OpenRouter | product name | An external model routing service. |
|
|
98
|
+
| Mixture-of-Agents | technical noun | An external multi-model inference method. |
|
|
99
|
+
| model merging | technical noun | A method that combines model parameters. |
|
|
100
|
+
| fine-tuning | technical noun | A method that adapts a model with additional training. |
|
|
101
|
+
| mergekit | product name | An external toolkit for model merging. |
|
|
102
|
+
| npm | product name | The package registry and command-line tool for JavaScript packages. |
|
|
103
|
+
| JavaScript Registry (JSR) | product name | The registry that distributes the Ennodia JavaScript package. |
|
|
104
|
+
| Model Context Protocol Registry | product name | The official registry for MCP server metadata. |
|
|
105
|
+
| GitHub Actions | product name | The service that runs Ennodia release and deployment workflows. |
|
|
106
|
+
| Cloudflare Pages | product name | The service that hosts the Ennodia website. |
|
|
107
|
+
| Astro | product name | The framework that builds the Ennodia website. |
|
|
108
|
+
| Starlight | product name | The Astro documentation framework used by the Ennodia website. |
|
|
109
|
+
| Semantic Versioning (SemVer) | technical noun | The version format that identifies compatible and incompatible releases. |
|
|
110
|
+
| JSON Lines | technical noun | A text format that stores one JSON value on each line. |
|
|
111
|
+
| JavaScript Object Notation (JSON) | technical noun | A structured text format for data exchange. |
|
|
112
|
+
| YAML | technical noun | A structured text format that Ennodia uses for Agent Skill metadata. |
|
|
113
|
+
| OpenID Connect (OIDC) | technical noun | The identity protocol used for tokenless registry publication from GitHub Actions. |
|
|
114
|
+
| identifier (ID) | technical noun | A value that uniquely identifies an Ennodia object. |
|
|
115
|
+
| F1 score | technical noun | The harmonic mean of precision and recall in a benchmark. |
|
|
116
|
+
| false positive (FP) | technical noun | A reported finding that the benchmark oracle does not require. |
|
|
117
|
+
| TypeScript | product name | The typed programming language used by Ennodia. |
|
|
118
|
+
| benchmark | technical noun or verb | A repeatable quality test, or the action that runs that test. |
|
|
119
|
+
|
|
120
|
+
Use `Plan Advisor` and `Result Advisor` in full.
|
|
121
|
+
Do not use `Advisor` alone when the role can be unclear.
|
|
122
|
+
|
|
123
|
+
Legacy fields can contain `synthesizer` or `synthesis` in their exact names.
|
|
124
|
+
Use `Result Advisor` for the current public role.
|
|
125
|
+
|
|
126
|
+
## Source
|
|
127
|
+
|
|
128
|
+
Use the official [ASD-STE100 Issue 9 standard](https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pdf).
|
|
129
|
+
The ASD Simplified Technical English Maintenance Group controls that standard.
|
|
130
|
+
Do not copy its dictionary into this repository.
|