CLAUDE Commands

/implement-extensions & /implement-extensions-batch

Claude Code slash-commands that spawn a small role-based agent team to fill in the stub Compute* extension methods under SysML2.NET/Extend/. These commands are the primary way OCL-derived properties get translated to LINQ / C# in this repo.

Which one to use

Command	Scope	Use when
/implement-extensions	One *Extensions.cs file per run	You are working on a single metaclass's stubs, or want fine-grained control.
/implement-extensions-batch	2–6 *Extensions.cs files in one run	You want to knock out a related cluster in one go — batch creates a git branch, assigns the issues to you, and syncs each issue's checklist on completion.

If you invoke the batch command with a single file, it will route you to /implement-extensions.

Quick start

# Single-file
/implement-extensions SysML2.NET/Extend/StepExtensions.cs

# Batch (2–6 files)
/implement-extensions-batch SysML2.NET/Extend/StepExtensions.cs SysML2.NET/Extend/FeatureTypingExtensions.cs

Both accept: repo-relative paths (recommended), @-prefixed paths, and absolute paths on any OS.

Flow at a glance

pre-flight      → Hypha plugin detection + input validation + path derivation
                  + stub enumeration + complexity grading + GitHub issue lookup
                  + git dirty-tree check (batch only) + branch creation (batch only)

step 4          → sanity-check AskUserQuestion (scope + model picks)

step 5a         → legacy researcher (Haiku / Sonnet / Opus per complexity)
                  → writes .team-notes/<foo>-extensions-spec.md

step 5b [Hypha] → Hypha researcher (parallel with 5a, independent context)
                  → writes .team-notes/<foo>-extensions-spec-hypha.md

step 5.4 [Hypha]→ comparator (read-only diff)
                  → writes .team-notes/<foo>-extensions-comparison.md

Gate R-C [Hypha]→ user picks: Hypha notes / legacy notes / abort-re-research

Gate R-A        → user reviews the picked notes per-method + approves

step 6          → implementer + tester in parallel (edit production + test fixture)

step 7          → orchestrator: dotnet build + targeted dotnet test

step 8          → regression sweep (fixes stub-blocker assertions unblocked by
                  the new implementations)

step 9          → reviewer (read-only OK / NEEDS FIX verdict)

step 10         → final summary + pre-filled commit message + handoff

step 11         → GitHub issue checklist sync

[Hypha]-labelled steps run only when the Hypha plugin is installed; otherwise the command falls back to a legacy-only flow.

Pre-requisites for Hypha

The Hypha plugin is optional but recommended. It grounds SysML v2 / KerML lookups in the metamodel (hypha:metamodel-lookup) and the normative spec text (hypha:spec-citation). See CLAUDE.md → "Grounding SysML v2 / KerML work with the Hypha plugin" for the design rationale.

To have Hypha fully working:

1. Install the plugin (via the Claude Code marketplace) so hypha:metamodel-lookup, hypha:spec-citation, and hypha:sysml-validation appear as skills in your session.

2. Metamodel-lookup: works immediately after install — the metamodel knowledge base is bundled with the plugin.

3. Spec-citation: requires an additional local one-time setup because the OMG PDFs are copyrighted and are NOT redistributed with the plugin. Download the three PDFs from the SysML v2 release repository:

   • 1-Kernel_Modeling_Language.pdf
   • 2a-OMG_Systems_Modeling_Language.pdf
   • 3-Systems_Modeling_API_and_Services.pdf

   URLs: https://github.com/Systems-Modeling/SysML-v2-Release/tree/master/doc

   Place them in the plugin's sources/specs/ directory, then run the spec-extract pytest suite per tools/spec-extract/README.md in the plugin. This regenerates the (git-ignored) knowledge/spec/ tree, after which hypha:spec-citation returns real answers.

   If spec-citation is not built, the Hypha researcher still works via hypha:metamodel-lookup alone and will flag any method that would have needed a spec citation as spec-citation unavailable — knowledge base not built. Not fatal — most mechanical OCL derivations don't need intent-grounding.

4. When the plugin is NOT installed, both commands recommend installing it once per invocation, then fall back to the legacy-only flow (single researcher grounded in the checked-in XMI and the PDF-text mirrors under Resources/specification/).

Setup — non-blocking Hypha

Hypha skills (hypha:metamodel-lookup etc.) are non-read-only tools from the harness's perspective and are blocked in plan mode by a built-in pre-tool-use hook, even though they are read-only knowledge-base queries in practice. Whitelist them in the project settings so they run cleanly:

Add to .claude/settings.local.json (this file is git-ignored and holds your local Claude Code preferences):

{
  "enabledPlugins": {},
  "permissions": {
    "allow": [
      "Skill(update-config)",
      "Skill(hypha:metamodel-lookup)",
      "Skill(hypha:spec-citation)",
      "Skill(hypha:sysml-validation)"
    ]
  }
}

Restart Claude Code after editing — the whitelist is loaded at session start; mid-session edits do not affect the running session.

Known harness limitation

Sub-agents (general-purpose Agent(...) spawns) currently inherit plan-mode enforcement from the parent session and cannot invoke Skill(hypha:*) even when the parent-side whitelist is in place. The mode: "acceptEdits" spawn parameter does not override this inheritance on the current Claude Code build. Practical impact:

• The Hypha lookups need to happen from the orchestrator (parent) context and be embedded into the sub-agent's spawn prompt as pre-computed context, OR
• The parent orchestrator can invoke Hypha itself and write the Hypha notes file directly, bypassing the sub-agent researcher role.

Both commands currently spawn Hypha researchers as sub-agents (see step 5b); until the harness supports Hypha skills in sub-agent contexts, expect a degraded-mode dry-run where the Hypha researcher reports "hypha access denied for sub-agents" and defers its write to the orchestrator. This is documented in the team template (.claude/team-templates/extension-impl.md → "Sub-agent spawn mode" section) and is exactly the failure mode a dry-run should surface loudly.

The workaround stays functional: the parent-level orchestrator can perform the Hypha lookups directly during Gate R-C preparation and populate the notes file, then the downstream implementer/tester/reviewer proceed normally.

What lands on disk per run

Under .team-notes/ (git-ignored — per-contributor scratch):

File	Written by	Purpose
<foo>-extensions-spec.md	Legacy researcher	Legacy grounding (XMI + Resources/specification/*.pdf.txt)
<foo>-extensions-spec-hypha.md	Hypha researcher (or orchestrator)	Hypha grounding (hypha:metamodel-lookup + optional hypha:spec-citation)
<foo>-extensions-comparison.md	Comparator	Per-method verdict (agree / disagree / one-side-only) + overall verdict

The two spec files stay on disk regardless of which one drives implementation, so they form an accumulating A/B corpus that lets you audit Hypha's grounding quality over time.

Structural gates

The commands surface two structural gates via AskUserQuestion:

Gate	When	Purpose
Gate R-C	After the comparator, only when Hypha is available	Pick which notes drive downstream: Hypha, legacy, or abort-re-research.
Gate R-A	After Gate R-C (or after step 5c in legacy-only runs)	Review the per-method contract of the picked notes file before any production code is written.

Both are mandatory when applicable — the commands never skip them, even when the researcher reports zero ambiguities. That's the user's chance to inspect the derivation contracts before code changes hit disk.

Git & PR workflow

The commands do NOT auto-commit, auto-push, or auto-open PRs — see the "Branch & PR workflow (MANDATORY)" section of CLAUDE.md for the strict agent boundaries. The batch command DOES create a feature branch and push an empty remote ref so that your later git push of the actual commit is a trivial fast-forward.

Step 10's final summary always includes a pre-filled commit message (Fix #<n> for single-file, Fix #<n1> #<n2> … for batch) and a handoff line explaining exactly how to stage, commit, and push the result yourself.

Related files

• Command bodies: .claude/commands/implement-extensions.md, .claude/commands/implement-extensions-batch.md.
• Team template (role prompts): .claude/team-templates/extension-impl.md.
• Grounding guidance: CLAUDE.md → "Grounding SysML v2 / KerML work with the Hypha plugin".
• Design decisions from the initial rollout of Hypha comparison: .claude/plans/toasty-greeting-hopper.md (local, may not be present for other contributors — kept for provenance).