feat!: scenario bundles, plugin dependencies, and explicit skill invocation (v5.0.0) - #79
Merged
Merged
Conversation
Design only — nothing in plugins/ changes yet. Rev 2 rewrites the plan around a full audit of all 102 cross-plugin references (every SKILL.md and agents/*.md, frontmatter and body separated), which invalidated eleven of rev 1's sixteen Layer-2 edges and added one it had missed. - D13: a reference becomes a dependency only if it fires on every run. The platform has no optional dependency, so declaring a conditional handoff installs a whole plugin for a branch most runs never reach. - D14: rename ceh-agent-coding-contract to ceh-coding-agent, reversing D6. The rename window closes once the old string is a dependency key. - D15: seven scenario bundles; ceh-scenario-editorial replaces ceh-scenario-content, plugin-authoring dropped. - D16: validate.py must reject an invocation whose target is missing, undeclared, or sets disable-model-invocation - 19 of 77 skills set that flag and the failure is silent. - D17: duplicate plan-schema.md into ceh-business-plan rather than declare an edge for one conditional file read. - D12 keeps its number but loses its rationale: the audit found zero cycles, so the rule held by coincidence rather than by construction. Also adds the one-off script backing section 9, which strips stale @ceh-plugins keys from per-project settings.local.json after the rename. Dry-run by default. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Two phase-axis corrections, both traceable to one bad word. Q2 — ceh-plan-build-review moves from the greenfield delta into the post-launch bundles. Rev 1 placed it on a claimed 3-of-4 majority, but the skill descriptions say the opposite: plan-fullstack-app-iteratively covers "greenfield skeletons and iterative feature planning for existing apps", and implement-from-plan / review-against-plan consume any plan artifact regardless of phase. Only plan-fullstack-app-to-mvp is greenfield-exclusive. Under D3 the greenfield bundles inherit the plugin anyway, so nothing is lost and the greenfield delta shrinks to ceh-scaffolding + ceh-business-plan. The deferred refactor is dropped: patch-built-version routes feature work to plan-fullstack-app- iteratively, which argues for keeping them together. Q5/D18 — the suffix becomes -iterate. "Maintenance" connotes bugfix-and-keep-the-lights-on, which is why the plugin was misfiled in the first place; -iterate names the activity, so someone with a new feature to build picks the right bundle. It also matches the bundle's headline skill. Rejected alternatives and their reasons are recorded in D18. Also marks section 9 as a manual step run by the repo owner - it touches global Claude Code state and 26 unrelated project directories, none of it inside this repo. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Plan step 1 (D14). The plugin holds a behavioral contract, a minimalism reflex, two retroactive-refactoring skills, a usage-limit hook, and an explanation skill - "coding contract" named one of six, and D5 is about to add two more. Every skill in it governs the coding agent's own behavior on a codebase, which the new name covers without stretching. Done now rather than later because the rename window closes at plan step 4: once the old string is a dependency key in 13 manifests, a rename means a coordinated multi-manifest edit that fails at install time rather than at edit time. Historical records keep the old name on purpose - CHANGELOG.md, docs/CHANGELOG-v1-v2.md, DECISION_LOG.md, PLUGIN_REORG_PLAN.md and the skill-eval runs describe what was true when written. So do D14 and step 1 of PLUGIN_DEPENDENCY_PLAN.md, which name what is being renamed. MAJOR bump: the plugin's install identity changes, so every existing install is orphaned. BREAKING CHANGE: ceh-agent-coding-contract is now ceh-coding-agent. Existing installs must be removed and re-added; skill references change from ceh-agent-coding-contract:<skill> to ceh-coding-agent:<skill>. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Plan step 2 (D5). explain-codebase and explain-until-understood
cross-referenced each other purely to disambiguate, which is the
signal they belong in one plugin. Co-locating them also puts all three
whole-repo passes together - refactor-repo, explain-codebase, and the
repo-tree-mapper agent - so refactor-repo calling explain-codebase
becomes an in-plugin call rather than a cross-plugin gamble.
ceh-dev-tools was one skill plus one agent, below the weight of a
standalone plugin.
Moved: skills/explain-codebase, agents/repo-tree-mapper.md, and
scripts/walk-repo.sh (reached via ${CLAUDE_PLUGIN_ROOT}, so the path
still resolves). Removed the ceh-dev-tools manifest, README, and
marketplace entry; repointed every ceh-dev-tools: reference, both
README tiers, CLAUDE.md, and docs/CROSS_REFERENCES.md.
MINOR bump on ceh-coding-agent (3.0.0 -> 3.1.0): one new skill and one
new agent. Description and keywords widened to cover them.
BREAKING CHANGE: ceh-dev-tools no longer exists. Uninstall it;
ceh-dev-tools:explain-codebase is now
ceh-coding-agent:explain-codebase and ceh-dev-tools:repo-tree-mapper
is now ceh-coding-agent:repo-tree-mapper.
Generated with [Claude Code](https://claude.com/claude-code) by CEH
Plan step 3 (D17). develop-business-plan read plan-schema.md by a path inside ceh-plan-build-review - the only cross-plugin file read in the repo, and the one case D13 handles badly: conditional (it fires only when the input is an app plan) but unrecoverable if the file is absent. A dependency would install a whole planning plugin for that branch. A 4th copy costs 121 lines and follows the existing Shared-Standards Duplication Policy: the file is already duplicated three times inside ceh-plan-build-review and registered in docs/CROSS_REFERENCES.md, so this adds one row to a block that already demands lockstep edits. PATCH bump on ceh-business-plan. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Plan steps 4 and 5, in one commit so no fallback outlives the
guarantee that replaces it.
Six dependency edges, each backed by a reference that fires on every
run (D13):
- ceh-release-flow -> ceh-git-workflow, ceh-documentation (13 step rows)
- ceh-python-service, ceh-web-frontend -> ceh-testing (agent preloads)
- ceh-python-library -> ceh-testing (the invocation added here)
- ceh-ops, ceh-orchestration -> ceh-coding-agent (agent preloads)
The 13 release-flow step rows routed through a trigger phrase -
"update the changelog" -> ceh-documentation:update-changelog - which is
the description-matching gamble this whole plan exists to remove. They
now say Invoke the Skill tool with skill="..." directly.
The three stack testing skills gain a call to
ceh-testing:design-test-cases before their unit-test sections. That
skill was reachable only through six agent preloads, so the
in-conversation path had no access to the technique at all - a real
gap, not bookkeeping.
Deleted the four fallbacks that are now unreachable ("if a step's
owning skill is not installed, apply it inline"; "when the
ceh-git-workflow agents are installed"), plus the release-flow
README's soft-dependency section. revise-claude-md keeps its fallback:
it lives in another marketplace, which plugin dependencies cannot
reach.
PATCH bumps per the repo rule - dependencies and body edits are
content, not new skills or agents.
Generated with [Claude Code](https://claude.com/claude-code) by CEH
Plan step 6 (D1, D15, D18). 22 plugins is more than anyone remembers, so the install path now starts from the situation you are in rather than the catalogue. Each bundle is a manifest with dependencies and nothing else - no skills, agents, or hooks. Three subjects (service, library, webapp) x two phases, plus editorial: - -iterate: working on something that already ships. Carries the cross-cutting set, the stack plugin, architecture, docs, releases, usability, and plan-build-review. - -greenfield: depends on its own -iterate bundle plus scaffolding and business-plan, so the phase transition is a no-op - you never switch bundles, you just stop reaching for the planning skills (D3). - editorial: coding-agent, blog, documentation, seo. No phase split. Deliberately unbundled: ceh-fabled and ceh-advisor (experimental), ceh-summarize-chat / ceh-orchestration / ceh-lessons-learned (session mechanics, not what you are building), and ceh-ops. defaultEnabled cannot exclude a dependency, so omission is the only lever. Also answers the plan's open question at step 7: validate.py already tolerates a plugin directory with no skills/ or agents/. It flagged only the missing marketplace entries. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Plan step 7 (D16). Two new checks, both stdlib-only like the rest. deps - every dependencies entry names a plugin in this repo, the graph is acyclic, and a ceh-scenario-* directory holds only plugin.json and README.md. Acyclicity is now checked here rather than asserted by D12, which is what makes the layering rule survive an ordinary content edit instead of holding by coincidence. invocations - every `Invoke the Skill tool with skill="X"` resolves to a real component, sits in the source plugin or one of its declared dependencies, and does not set disable-model-invocation: true. That last clause is the one that matters: 19 of 77 skills set the flag, it removes the skill from the model-visible listing, and the resulting failed Skill call is silent. Without this check a future session could flip the flag on a release-flow target and break the flow with no error at author time. Each rule was negative-tested by mutation before commit: a bogus dependency, an induced cycle, an invocation of an undeclared plugin, an invocation of a disable-model-invocation skill, and a stray file in a bundle - all five reported, then reverted. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Plan step 8. The install path now reads scenario-first: a "Start here" table above the Plugins table asks which situation you are in, and the 22-plugin table becomes the reference list of what those bundles are made of. Recall was Problem A of the whole plan - nobody remembers a catalogue. Also records what is deliberately outside every bundle and why (defaultEnabled: false does not protect a dependency, so omission is the only lever), notes that -greenfield is a superset of -iterate so the phase transition is a no-op, and points the individual-install list at the dependencies that now come for free. Marks ceh-fabled and ceh-advisor experimental in the Plugins table, the tier table, and - the part that actually reaches a user running `claude plugin list` - their manifest description fields. ceh-advisor says outright that it installs always-on session hooks. Adds the scenario tier to the Categorization table, which was three tiers and is now four. PATCH bumps on ceh-fabled and ceh-advisor for the description change. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Plan step 9. The tier table said three tiers and listed a plugin name that no longer exists - it went wrong the moment the rename landed, so this was never optional bookkeeping. Adds a Plugin Dependencies section carrying the two rules that decide whether a cross-plugin reference earns an edge: it must fire on every run of the skill (there is no optional dependency, so a conditional handoff would install a plugin for a branch most runs never reach), and negative routing never counts (it names an alternative, so a dependency there installs what the user steered away from). States the cross-cutting rule as layering rather than as cycle-avoidance, since validate.py now checks acyclicity directly - the old phrasing held by coincidence and would have gone false on an ordinary content edit. Also records the explicit-invocation convention and its validator guard, the no-plugins-scenario-folder decision, and warns against converting every backtick-quoted skill name into an invocation - that sweep is what would drag a 6-plugin closure into one install. Adds a step 0 to the Adding a Component checklist so a new dependency edge or bundle updates the plan's graph in the same commit. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Adding a dependencies entry changes what a user gets on install - the plugin system resolves and enables the whole dependency, transitively, and refuses to disable it while the dependent is enabled. That is more than a content change, so PATCH understated it. ceh-release-flow 1.1.11 -> 1.2.0, ceh-python-service 3.1.8 -> 3.2.0, ceh-python-library 1.2.5 -> 1.3.0, ceh-web-frontend 3.2.6 -> 3.3.0, ceh-ops 3.0.6 -> 3.1.0, ceh-orchestration 1.0.7 -> 1.1.0. Widens the CLAUDE.md versioning rule to say so, since it previously read MINOR-only-for-new-skills-or-agents and gave a dependency change no home. Generated with [Claude Code](https://claude.com/claude-code) by CEH
The field was legal where I put it - the docs say a plugin can depend on others "by listing them in plugin.json or in its marketplace entry", and the cross-marketplace example shows dependencies inside a marketplace.json entry. Removed anyway. "Or" means two legal homes with no documented precedence when both are populated, and the marketplace copy would be a second source of truth that nothing checks. version is duplicated there too, but validate.py enforces that those agree; nothing enforces this. Seven entries dropped, plugin.json unchanged. Also marks ceh-orchestration experimental alongside ceh-fabled and ceh-advisor - the Plugins table, the tier table, and the manifest description that `claude plugin list` actually shows. PATCH bump. It moves from D9 (session mechanics) to D8 (experimental) in the plan's never-bundled list; either way it stays out of every bundle. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Audit found the file at 84/100. Five substantive fixes: - The plan-schema.md consumer list named three copies inside ceh-plan-build-review; there are four, and the fourth is in another plugin. The Cross-Reference Rule depends on that list being complete, so a stale entry there breaks the mitigation the duplication policy relies on. - The version-bump rule was stated twice with different content - the Adding a Component checklist said PATCH/MINOR-for-skills while Versioning had already gained the dependency case. The checklist now points at Versioning instead of restating it, and Versioning gains the MAJOR case that the rename used. - "these four land in the same commit" listed five items. - New: declare dependencies in plugin.json only, never in the marketplace.json entry. The platform accepts either with no documented precedence, and this session put it in both before catching it - so the next one would too. - New: name bundle phase halves -greenfield / -iterate, never -maintenance. That word is what got ceh-plan-build-review filed on the wrong side. Prose tightened throughout: 2622 -> 2254 words with every section, rule, and all 22 plugin rows intact. Also adds a dependency-graph command and a Key Files row for the dependency plan. Generated with [Claude Code](https://claude.com/claude-code) by CEH
Both flow skills invoked ceh-git-workflow:release at step 1 to reach its four-row bump table. Invocation injects the entire body, so that call also delivered the skill's git push origin main / git tag / gh release create sequence nine steps before it applies -- at a point where the release branch does not exist, no manifest is bumped, and no changelog section is written. The flows then had to un-teach it in a prose section 50 lines below the call. The same call was also byte-identical to the one at step 10 (step 8 in the direct variant), where the full procedure is exactly what is wanted. Nothing but a four-word parenthetical separated "read a table" from "run the release", against a target whose own description says to auto-load whenever a tag is being created. Step 1 now states the mapping inline and delegates nothing. The late call gains a scoping clause naming which half of the target to run, hoisting the correction from the prose section into the cell that needs it. The subagent sections no longer tell the reader to delegate "by trigger phrase" -- the table stopped using trigger phrases when the invocation contract landed. ceh-git-workflow:release is unchanged. - Bump: PATCH -- content only; no skill, agent, or dependency change - Manifests: ceh-release-flow plugin.json + marketplace.json, 1.2.0 -> 1.2.1 - Docs: CROSS_REFERENCES.md gains a "Semver bump mapping" block registering the release skill as canonical and both flow copies Generated with [Claude Code](https://claude.com/claude-code) by CEH
Scenario bundles become the install entry point and cross-plugin skill calls become explicit. Seven ceh-scenario-* bundles each declare the plugin set for one situation; sixteen references are now "Invoke the Skill tool with skill=X" backed by six dependency edges, so the call cannot hit an unknown skill. validate.py enforces both, plus graph acyclicity and the bundle structure. - Bump: MAJOR -- ceh-agent-coding-contract is renamed to ceh-coding-agent and ceh-dev-tools is removed, orphaning every existing install of either name - Manifests: no repo-level version manifest exists; the 10 per-plugin versions and 7 new bundle manifests were bumped in earlier commits on this branch - Docs: CHANGELOG.md gains the 5.0.0 entry; README and CLAUDE.md were already brought current in 09d28e0, 0f9d789 and 4f8230d, so no update needed here. PLUGIN_DEPENDENCY_PLAN.md records steps 1-9 landed and step 10 as v5.0.0; DECISION_LOG.md entry 81 records reusing this branch as the release branch Generated with [Claude Code](https://claude.com/claude-code) by CEH
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Makes scenario bundles the install entry point and turns cross-plugin skill references into
explicit
Skilltool calls backed by dependency declarations. Renamesceh-agent-coding-contracttoceh-coding-agentand removesceh-dev-tools. Ships as v5.0.0.Why
Two problems with one root. 23 plugins and ~77 skills is more than anyone remembers — a user knows
the situation they are in, not which four plugins it needs. And where one skill genuinely required
another, the only mechanism connecting them was a trigger phrase in prose, hoping the target's
descriptionmatched whatever phrasing reached the model.The fixes are independent:
dependenciesguarantees the target is installed; naming theSkilltool call in the body bypasses description matching entirely. Dependencies alone solve installation
only — they are the precondition for the invocation half, not a substitute for it.
Design record:
.agents_workspace/PLUGIN_DEPENDENCY_PLAN.md.How
-greenfielddepends on its-iteratetwin plusceh-scaffoldingandceh-business-plan, so the phase transition is a no-op.plugin.jsononly. The bar is that thereference fires on every run of the skill; conditional handoffs and negative routing stay prose.
Worst-case install closure is 3 plugins.
ceh-testing:design-test-caseswas previously reachable only through agent preloads.validate.pynow checks invocation resolution,disable-model-invocation(19 of 77 skillsset it, and the failed call is silent), graph acyclicity, and the bundle structural invariant.
skills:preloads;ceh-dev-tools'explain-codebaseandrepo-tree-mappermove intoceh-coding-agent.Testing
python tools/validate-plugins/validate.pyis green, and CI runs the same command. No behavioraltests exist for skill content — triggering and lift are unmeasured, as for every prior release.
Notes for review
had no supporting reference. §5 of the plan records which and why.
chore/release-v5.0.0cut frommain, since all the release content is here andmainhas none of it. Logged asDECISION_LOG.mdentry 81.Generated with Claude Code by CEH