develop · git:20260828.bf6b689 · 2026-08-28 · sha256 1ff63c3f4ae62755
develop git:20260828.bf6b689A
Immutable. This exact content never changes and is served at /api/v1/blob/1ff63c3f4ae62755.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_cg5aboqs4xn4dair/1ff63c3f4ae62755ad9373fa993ae0edcf74e4cfcc4e287a934073f3fa034512.json
Then /plugin install develop@markdownregistry-cg5aboqs4xn4dair in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: develop description: > Develop, refactor, or review the Mycelium plugin itself across Claude Code and Codex. Use for shared skills, plugin manifests, lifecycle hooks, installers, migrations, session accounting, shell execution detection, data lineage, or cross-host compatibility changes in the Mycelium source repository. Apply branch-wide error-pattern review, TDD, compatibility checks, and real-host smoke testing. Do not use for maintaining an ordinary Mycelium-enabled project, performing scientific analysis, or responding to an existing Codex PR comment (use codex-review for that). --- # Mycelium Development Resolve paths in this skill relative to the Mycelium plugin root, two directories above this `SKILL.md`. Resolve project paths relative to the source checkout being changed. Use this workflow to keep changes correct as a system on both supported hosts. Before editing, read `references/regression-patterns.md` and `../../docs/cross-host-review-checklist.md` completely. The checklist is the release gate; the regression patterns explain why its most important checks exist. ## Workflow ### 1. Establish the release-candidate scope - Record the branch, working-tree state, merge base, exact head, and PR base. - Account for every local change. Preserve unrelated and untracked user files. - Review `base...head`, not only the newest commit. - Classify each affected behavior as shared, Claude-only, Codex-only, or packaging/discovery. Shared behavior must remain host-neutral. - Write down the invariants the change must preserve before designing the fix. ### 2. Reproduce with a red test - Add the smallest regression test that fails for the actual reason, then run it and capture the expected failure. - Test the externally visible contract, not an implementation accident. - For mutation workflows, assert the complete failure boundary: original bytes, permissions, unrelated configuration, and absence of earlier partial writes. - For parser fixes, add paired positive and negative cases. Include quoting, wrapper, cwd, exit-status, or shell-structure neighbors that distinguish the intended behavior from a false positive. - For lifecycle fixes, test retry, cleanup, and concurrency where relevant—not only the happy path. If a focused test cannot run because the environment lacks a dependency, bootstrap it outside the repository or report the constraint. Do not claim a red/green TDD cycle without observing both states. ### 3. Generalize the defect pattern Name the underlying mistake in one sentence. Search every branch-touched module for the pattern, then search unchanged code if the pattern may be systemic. Reason about each match; do not rewrite false positives. Fix all in-scope instances in the same pass and record the search coverage. If the finding exposes a new review category, add it to the cross-host checklist and its adversarial matrix. A repeated error pattern belongs in `references/regression-patterns.md` as well. ### 4. Implement the narrow cross-host fix - Keep host payload decoding and emission at explicit boundaries. - Preserve user-authored guidance, hooks, settings, and `.living` content. - Preflight every source and destination before the first write in a multi-file operation. - Reject linked or escaping managed paths before reading or writing them. - Use atomic replacement for durable state and preserve existing permissions. - Preserve active retry evidence until the transaction is actually accepted. - Do not embed versioned cache paths or developer-machine paths in packaged configuration. Avoid opportunistic cleanup that expands the branch beyond the named defect pattern. ### 5. Run the test ladder Run from narrowest to broadest: 1. New regression tests. 2. The touched module's test file or hook harness. 3. All Python compatibility tests under `skills/core/scripts`, excluding the separately provisioned knowledge-map tests when required. 4. `test_stop_hook.sh`, `test_hooks_stress.sh`, and `test_integration_stress.sh` for lifecycle changes. 5. Fresh initialization plus `validate_structure.py` in a temporary repository. 6. Manifest, skill metadata, executable-bit, JSON/YAML, diff, and documentation checks represented by CI. Run `git diff --check` and inspect the final diff after tests. A command sequence whose last command passes does not prove earlier commands passed; retain each exit status or use a fail-fast runner. ### 6. Exercise real hosts when the boundary changed Use `$mycelium:lifecycle-audit` when changes touch plugin installation, discovery, dispatch, lifecycle hooks, lineage, or host payloads. Unit tests that invoke hook scripts directly do not prove automatic host dispatch. Verify the installed artifact is the exact candidate under test, and do it **before** launching the host process. The Claude plugin cache is keyed on the version string, so any content change under an unchanged version is served stale and `claude plugin marketplace update` does not fix it — see `references/regression-patterns.md` patterns 1 and 34 for the mechanism and the refresh. Codex local development requires a cachebuster and reinstall into a new task. Source and installed files must hash identically; report the file count compared, not the version label. Run a Claude Code CLI smoke for shared or Claude-facing changes. Keep environmental failures distinct from Mycelium failures. ### 7. Close compatibility and documentation - State whether existing Mycelium projects continue unchanged and whether an upgrade or migration is required. - Update install, update, trust, restart, and migration instructions when their actual interface changes. - Update the changelog for user-visible behavior. - Re-run the complete gate on the exact final tree after documentation and skill changes. Do not commit, push, post review replies, or retrigger external review unless the user authorized those outward actions. ### 8. Release, in this order `docs/release-process.md` documents the gate. The ordering below is what makes its results mean anything, and every step has been got wrong at least once: 1. **Merge first.** The gate's installed-artifact check compares against a published, installed version, so a candidate that is not on the default branch cannot satisfy it. Confirm the merge actually reached the default branch — see pattern 35 before stacking anything. 2. **Refresh and hash-verify the install.** Pattern 1's refresh, then the hash comparison. Skipping this makes every later step certify the wrong tree. 3. **Host audits, after the refresh.** `$mycelium:lifecycle-audit` on both hosts. The gate requires evidence for Claude *and* Codex, or `--waive-host-audits REASON` for both — it rejects one-sided evidence. 4. **Run the gate from a clean disposable clone.** It refuses a dirty or untracked tree with no bypass. 5. **Tag last**, only after the gate passes, and tag the exact commit the gate certified rather than whatever the default branch has moved to. Version bumps live in their own `release/X.Y.Z` change: three-way agreement across `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (`metadata.version`), and the base of `.codex-plugin/plugin.json`, plus a fresh `+codex.<timestamp>` cachebuster and a dated changelog section. Fold any `## [Unreleased]` entries into that section — the gate only checks the dated section *exists*, so entries left under Unreleased ship as missing release notes. Operational gotchas, all of which have cost a full cycle: - `release_gate.py` runs the ladder via `sys.executable`. Invoke it with the interpreter that actually has `pytest`, or the ladder fails on an import. - `codex exec` blocks reading stdin; redirect `< /dev/null` for a non-interactive audit. - Codex plugin hooks need a one-time interactive trust step (`/hooks`, trust, restart). A fresh `codex exec` in an untrusted project shows zero dispatch, which is an environment result, not a hook defect. - `timeout` does not exist on macOS. A wrapper that silently fails to run makes "no output" look like "no dispatch". ## Review output Report findings by severity with file and line evidence. When no actionable findings remain, say so explicitly and list residual risks or unexercised host boundaries. For fixes, include the red test, generalized pattern sweep, final test evidence, real-host evidence, and compatibility impact.