Repository navigation
feat!: share nouns and generate skills, MCP descriptions and plugins from one intent list - #1
Conversation
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.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 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".
| 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)); |
There was a problem hiding this comment.
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 👍 / 👎.
There was a problem hiding this comment.
Fixed in 1f10222: every top-level name and alias is checked, so tasks aliased as units or grades now throws.
| } 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; |
There was a problem hiding this comment.
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 👍 / 👎.
There was a problem hiding this comment.
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
…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.
The three CLIs share verbs through cli-kit but each declares its own nouns, so they drift: Monash's
unitsis the canonical noun everywhere, and a contributor to edstem-cli just proposedlessons scorewhile moodle-cli already hasgrades(bunizao/edstem-cli#18). This adds the nouns every CLI must name the same way.SHARED_NOUNSinsrc/nouns.ts:courses, aliasesunitsandprojects, verbslist, show, get, default0 list, 1 show. Ed and Moodle both call them courses;unitsis an Australian usage.grades, verblist, default0 list, 1 list.GRADE_STATUSES:graded,ungraded,unreleased,not_submitted,unavailable. The README documentsgradeandmaxas numbers ornullon each row.commandsJsonthrows 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'sMCP_TOOL_CATALOG+INTENTS, ontrack'sINTENTS). AnIntent(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:descriptionplus "Use whenuseWhen".renderSkillthrows on a name or description outside the Agent Skills limits, or one that says "I" or "you" outside quotes.server:tool.workflowsrender as copyable checklists. A CLI with a mutating command gets a shared one first: dry-run, confirm, apply with--yes, read the result back.references/commands.md(renderCommandReference), because an agent loads SKILL.md whole.@bunizao/cli-kit/intents:toolDescriptionandcheckIntentCommandswithout commander or Node builtins, so moodle's Worker MCP server can bundle it.agentFiles(...): the skill folderskills/<name>/(SKILL.md,references/, Codexagents/openai.yaml), whichnpx skills addand Claude Code both discover;.claude-plugin/plugin.jsonwith optionalmcpServers; 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 --strictfor 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.mjsruns the sibling skills against each other on Codex: for each of 29 requests (evals/trigger-pool.json), whichskills/<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
unitsmust rename it tocoursesand keepunitsas an alias. This needs a 0.7.0 release. edstem-cli and moodle-cli use their owncommandsJsontoday, so the check reaches them only once they switch back to the kit's.Not in this PR
threadsis not shared yet: one argument meansshowin moodle andlistin edstem.VERBSis unchanged.grades UNIT <queries...>needs an explicitlist, sincedefaultByAritycannot 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 usedunitsas a canonical name now usecoursesortasks.