Skip to content

feat!: share nouns and generate skills, MCP descriptions and plugins from one intent list - #1

Merged
bunizao merged 6 commits into
mainfrom
feat/shared-nouns
Oct 29, 2026
Merged

bunizao merged 6 commits into
mainfrom
feat/shared-nouns

Conversation

@bunizao

@bunizao bunizao commented Oct 29, 2026 •

Copy link
Copy Markdown
Owner

The three CLIs share verbs through cli-kit but each declares its own nouns, so they drift: Monash's units is the canonical noun everywhere, and a contributor to edstem-cli just proposed lessons score while moodle-cli already has grades (bunizao/edstem-cli#18). This adds the nouns every CLI must name the same way.

  • SHARED_NOUNS in src/nouns.ts:
    • courses, aliases units and projects, verbs list, show, get, default 0 list, 1 show. Ed and Moodle both call them courses; units is an Australian usage.
    • grades, verb list, default 0 list, 1 list.
  • GRADE_STATUSES: graded, ungraded, unreleased, not_submitted, unavailable. The README documents grade and max as numbers or null on each row.
  • commandsJson throws on a top-level command named after a shared alias (units → "name the command courses") and on a contract verb the shared noun does not offer (grades set).

One intent list for skills, MCP and plugins

Each CLI kept its own intent table, MCP description catalog and SKILL.md generator (moodle's intentContracts, edstem's MCP_TOOL_CATALOG + INTENTS, ontrack's INTENTS). An Intent (when, what, command?, tool?, instead?, refs?, then?, cost?) is now the single source:

  • toolDescription(intent): the MCP tool description.
  • renderSkill(...): a short SKILL.md written to Anthropic's skill authoring guide:
    • The description is description plus "Use when useWhen". renderSkill throws on a name or description outside the Agent Skills limits, or one that says "I" or "you" outside quotes.
    • One table of what the user says, the CLI command and the MCP tool, qualified as server:tool.
    • workflows render as copyable checklists. A CLI with a mutating command gets a shared one first: dry-run, confirm, apply with --yes, read the result back.
    • Each rule says why. The command tree and exit codes go to references/commands.md (renderCommandReference), because an agent loads SKILL.md whole.
  • @bunizao/cli-kit/intents: toolDescription and checkIntentCommands without commander or Node builtins, so moodle's Worker MCP server can bundle it.
  • agentFiles(...): the skill folder skills/<name>/ (SKILL.md, references/, Codex agents/openai.yaml), which npx skills add and Claude Code both discover; .claude-plugin/plugin.json with optional mcpServers; and a single-plugin .claude-plugin/marketplace.json (source: "./"). writeAgentFiles(root, files, { check }) writes them or returns stale paths for CI. It never deletes, so a CLI moving to this layout removes its old root files itself.
  • checkIntentCommands(program, nouns, intents): throws when an intent's command no longer parses (renamed noun or verb, removed option, wrong binary), so the skill and MCP text cannot drift from the command tree.

A generated demo plugin passes claude plugin validate --strict for both manifests. A repo with a root CLAUDE.md gets one warning (that file is not plugin context), so it passes without --strict.

Migrations against this branch (both on the skills/<name>/ layout): bunizao/ontrack-cli#4 and bunizao/moodle-cli#78.

Trigger evals

evals/trigger.mjs runs the sibling skills against each other on Codex: for each of 29 requests (evals/trigger-pool.json), which skills/<name>/ does Codex open first? Runs are killed at the first command and the CLI binaries are failing stubs, so nothing touches a real account. It isn't part of the npm package.

On the two migrations plus a rewritten edstem description (gpt-5.6-sol, 3 runs each), 27 of 29 requests reached the right skill, up from 24 at baseline. The baseline misses were Moodle quiz, workshop-page and announcement requests that edstem's old description ("units, … lessons, files, quizzes") claimed. So the fix belongs in edstem's description, which waits for bunizao/edstem-cli#18. "Not for …" exclusions didn't stop near misses that name the product: a Moodle plugin request still opened moodle-cli in 5 of 6 runs.

Breaking

A CLI whose top-level command is units must rename it to courses and keep units as an alias. This needs a 0.7.0 release. edstem-cli and moodle-cli use their own commandsJson today, so the check reaches them only once they switch back to the kit's.

Not in this PR

  • The conformance suite is unchanged. It runs against the published CLIs, so a noun check would fail until all three migrate.
  • threads is not shared yet: one argument means show in moodle and list in edstem.
  • VERBS is unchanged.
  • grades UNIT <queries...> needs an explicit list, since defaultByArity cannot express "one or more".

Tests

npm test: 77 passing. New cases cover intent command checks, skill rendering and its frontmatter limits, plugin files and stale-file detection, plus the canonical shared nouns, the alias rejection, and the shared verb check, and trigger-eval scoring; the fixtures that used units as a canonical name now use courses or tasks.

Add SHARED_NOUNS so every CLI names the cross-tool nouns the same way:
courses (aliases units, projects) and grades. commandsJson now rejects a
top-level command named after a shared alias, and a verb the shared noun
does not offer. GRADE_STATUSES fixes the status vocabulary for grades rows.

BREAKING CHANGE: a CLI whose top-level command is named "units" must
rename it to "courses" and keep "units" as an alias.
Copilot AI balanced review requested due to automatic review settings October 29, 2026 03:32
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-29T03:34:44.129932Z 9719aa3 PR opened
🔒 Security Review ✅ Completed 2026-10-29T03:34:31.255766Z 9719aa3 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9719aa3669

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/program.ts Outdated
if (noun && ACTION_GROUPS.has(noun) && !ACTIONS[noun]?.has(command.name())) {
throw new Error(`Unsupported action "${command.name()}" on group "${noun}".`);
}
const canonical = noun ? undefined : SHARED.find((spec) => spec.aliases?.includes(currentNoun));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject shared noun aliases declared on other commands

When a CLI declares a reserved name as an alias, such as program.command("tasks").alias("units"), this check sees only currentNoun === "tasks", so commandsJson succeeds even though invoking units now routes to the wrong noun instead of canonical courses. Inspect each top-level command's aliases as well as its primary name so shared aliases cannot be reassigned.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 1f10222: every top-level name and alias is checked, so tasks aliased as units or grades now throws.

Comment thread src/nouns.ts
} as const satisfies Readonly<Record<string, NounSpec>>;

/** The `status` of one row in `grades` output. */
export const GRADE_STATUSES = ["graded", "ungraded", "unreleased", "not_submitted", "unavailable"] as const;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Map every shared grade status to a theme tone

For themed grade tables, toneOf recognizes graded, ungraded, and not_submitted, but returns undefined for the newly standardized unreleased and unavailable values. Those rows therefore lose the semantic status styling that the shared theme supplies to the rest of this vocabulary; add explicit tone mappings for both statuses when introducing them.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 1f10222: unreleased reads as warning and unavailable as danger; a test pins all five statuses.

…tent list

Each CLI kept its own intent table, MCP description catalog and SKILL.md
generator. An Intent now maps what a person says to the command and the
MCP tool that answer it, and the kit renders everything from that list:

- toolDescription(intent) for MCP tool descriptions
- renderSkill for SKILL.md: intents, MCP tools, shared and CLI rules,
  setup, the command tree and exit codes
- agentFiles for SKILL.md, a Claude Code plugin with its own marketplace,
  and Codex agents/openai.yaml; writeAgentFiles writes them or, with
  check, reports stale paths for CI
- checkIntentCommands fails when an intent's command no longer parses
  against the program
@bunizao bunizao changed the title feat(nouns)!: share the courses and grades nouns across CLIs feat!: share nouns and generate skills, MCP descriptions and plugins from one intent list Oct 29, 2026
…oint

The command tree moves to references/commands.md, MCP tools are listed by
when to use them, the read rule appears only for a CLI with a read verb,
and agents/openai.yaml no longer wraps. @bunizao/cli-kit/intents exports
toolDescription without commander or Node builtins.
… a skills/<name>/ folder

SkillOptions gains useWhen, mcpServer and workflows. The frontmatter
description reads "<does>. Use when <useWhen>." and renderSkill rejects
names and descriptions outside the Agent Skills limits or written in the
first or second person. The CLI and MCP columns share one table, tools are
qualified as server:tool, and a CLI with a mutating command gets a shared
dry-run, confirm, apply, read-back checklist. Rules say why; exit codes move
to references/commands.md.

agentFiles now writes the skill to skills/<name>/ with its references and
agents/openai.yaml, takes extra reference pages, and drops the plugin's
skills field since Claude Code loads skills/ by default.
evals/trigger.mjs puts every sibling skill in one Codex workspace and
records which skills/<name>/ Codex opens first for each request. Runs
are killed at their first command and the CLI binaries are failing
stubs, so nothing reaches a real account. The 29-request pool covers
Moodle, OnTrack and Ed requests plus near misses.
@bunizao
bunizao merged commit 30bfb5a into main Oct 29, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants