@evo-dev/evodev 0.0.1-alpha.3 → 0.0.1-alpha.4

package/dist/.agents/skills/evodev-release/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: evodev-release
+description: Use this skill for EvoDev repository commit and release work: committing local changes, bumping to the next alpha or named version, creating and pushing release tags, triggering GitHub Actions release.yml, publishing @evo-dev/core and @evo-dev/evodev, fixing failed npm trusted-publishing runs, or checking npm dist-tags. Always use this skill when the user says to commit, push, tag, release, publish, bump alpha, or repair the EvoDev release workflow.
+---
+
+# EvoDev Release
+
+This skill captures the working EvoDev commit and release path for `/Users/bytedance/project/github/evodev`.
+
+EvoDev releases are GitHub Actions driven. Do not run local `npm publish` or `bun publish` unless the user explicitly asks for a local experiment. The normal path is: inspect diff, verify, commit, sync version, commit release, push `main`, push or dispatch release, watch CI, then confirm npm registry state.
+
+## Current Release Model
+
+- GitHub workflow: `.github/workflows/release.yml`.
+- Publish target packages: `@evo-dev/core` and `@evo-dev/evodev`.
+- Package inspected but not published to npm: `@evo-dev/plugin`.
+- Version sync command: `bun run version:sync -- <version>`.
+- Version check command: `bun run version:check`.
+- Main quality gate: `bun run check`.
+- Release package/smoke gate: `bun run release:dry-run`.
+- Tag trigger: `v<semver>`, for example `v0.0.1-alpha.3`.
+- npm dist-tag mapping:
+  - versions containing `-alpha` publish with npm dist-tag `alpha`;
+  - versions containing `-beta` publish with `beta`;
+  - other prereleases publish with `next`;
+  - stable versions publish with `latest`.
+
+The release workflow uses npm Trusted Publisher / OIDC, not long-lived npm tokens.
+
+Required npm Trusted Publisher settings for both `@evo-dev/core` and `@evo-dev/evodev`:
+
+- repository: `limerickgds/evodev`
+- workflow filename: `release.yml`
+- environment: `npm-release`
+- allowed action: `npm publish`
+
+The publish job should have `id-token: write`, use `actions/setup-node` with `registry-url: https://registry.npmjs.org`, and run `npm publish` from `packages/core` and `packages/cli`. Do not reintroduce `NPM_CONFIG_TOKEN`, `NPM_TOKEN`, `.npmrc` token writes, `--auth-type=legacy`, or `bun publish` into the normal release path.
+
+## Before Changing Anything
+
+Collect current evidence first:
+
+```bash
+git status -sb
+git diff --stat
+git log --oneline --decorate -8
+git fetch --tags --prune --quiet
+git tag --sort=-v:refname | head -20
+npm view @evo-dev/evodev versions --json
+npm view @evo-dev/evodev dist-tags --json
+npm view @evo-dev/core dist-tags --json
+```
+
+Use registry state, not only local tags, to choose the next version. If npm already has `0.0.1-alpha.N`, the next alpha is normally `0.0.1-alpha.(N+1)` even if the matching git tag is missing.
+
+## Commit Flow
+
+1. Inspect local changes before staging:
+   ```bash
+   git diff --stat
+   git diff -- <relevant files>
+   ```
+2. Split commits by intent:
+   - functional or docs changes first, with a conventional message such as `feat(team): ...` or `fix(release): ...`;
+   - version sync as a separate release commit: `chore: release v<version>`.
+3. Stage only intended files. Preserve unrelated user changes.
+4. Use non-interactive git commands:
+   ```bash
+   git add <files>
+   git commit -m "<type>(<scope>): <summary>"
+   ```
+5. After every commit, check:
+   ```bash
+   git status -sb
+   git log --oneline --decorate -5
+   ```
+
+## Version Bump Flow
+
+Use the repo script instead of editing versions by hand:
+
+```bash
+bun run version:sync -- <version>
+bun run version:check
+```
+
+The sync script updates the root workspace package, core package, CLI package, plugin manifests, Claude marketplace metadata, Codex plugin metadata, and `CLI_VERSION`.
+
+Before release commit, run:
+
+```bash
+bun run check
+bun run release:dry-run
+git diff --check
+```
+
+If any gate fails, fix the issue before committing the release. Do not report a release as ready if a gate failed or was skipped without explanation.
+
+## Tag-Driven Release Flow
+
+For a committed version bump:
+
+```bash
+git tag v<version>
+git push origin main
+git push origin v<version>
+```
+
+The pushed tag must point at the release commit whose `package.json` version matches the tag. The workflow checks this on tag events.
+
+Then watch the GitHub Actions run:
+
+```bash
+gh run list --workflow Release --limit 5
+gh run watch <run-id> --exit-status
+```
+
+After CI finishes, verify registry state:
+
+```bash
+npm view @evo-dev/evodev dist-tags --json
+npm view @evo-dev/core dist-tags --json
+npm view @evo-dev/evodev versions --json
+npm view @evo-dev/core versions --json
+```
+
+## Workflow Dispatch Recovery
+
+If a tag run used an old broken workflow, do not rewrite a pushed public tag by default.
+
+Instead:
+
+1. Fix `.github/workflows/release.yml` on `main`.
+2. Commit and push the workflow fix.
+3. Dispatch the fixed workflow for the same version:
+   ```bash
+   gh workflow run release.yml --ref main \
+     -f target=both \
+     -f publish=true \
+     -f tag=alpha \
+     -f version=<version>
+   ```
+4. Watch the new run and confirm npm dist-tags.
+
+Use `workflow_dispatch` only when it is clearly safer than mutating a pushed tag, or when the user explicitly asks for manual release.
+
+## Trusted Publishing Failure Handling
+
+If publish fails with a token error such as missing `NPM_CONFIG_TOKEN` or `NPM_TOKEN`, do not add token checks back. For Trusted Publisher, fix the workflow and npm package configuration:
+
+- workflow job needs `permissions.id-token: write`;
+- publish job must use GitHub-hosted runners;
+- npm package Trusted Publisher fields must exactly match repository, workflow filename, and environment;
+- use npm CLI through `npm publish`, not `bun publish`;
+- Node 24 from `actions/setup-node` already provides npm 11.x, which supports trusted publishing.
+
+If `release:dry-run` fails only after changing npm versions, avoid unnecessary global npm upgrades. In the current workflow, `actions/setup-node@v6` with Node 24 provides a compatible npm version; keep the dry-run behavior stable.
+
+If one package publishes and the second fails, check registry versions before retrying. npm versions are immutable, so rerunning `target=both` may fail on the already-published package. Use `target=core` or `target=cli` only for the missing package when appropriate.
+
+## Final Report
+
+Report the release outcome with:
+
+```text
+VERSION: <version>
+COMMITS:
+  - <sha> <message>
+TAG: v<version> pushed | not pushed
+RUN: <GitHub Actions URL and status>
+REGISTRY:
+  - @evo-dev/core alpha/latest: <version>
+  - @evo-dev/evodev alpha/latest: <version>
+VERIFICATION:
+  - bun run version:check: PASS | FAIL | not-run
+  - bun run check: PASS | FAIL | not-run
+  - bun run release:dry-run: PASS | FAIL | not-run
+WORKTREE: clean | dirty
+FOLLOW-UP:
+  - <item or none>
+```
+
+Be explicit about whether npm publication actually happened. A pushed git tag is not the same thing as a successful npm dist-tag update.

package/dist/.claude-plugin/marketplace.json

@@ -4,13 +4,13 @@
     "name": "EvoDev"
   },
   "description": "EvoDev Claude Code hook plugins for AI-assisted R&D workflows.",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.4",
   "plugins": [
     {
       "name": "evodev",
       "source": "./packages/plugin",
       "description": "EvoDev hook integration for disciplined AI coding workflows.",
-      "version": "0.0.1-alpha.3",
+      "version": "0.0.1-alpha.4",
       "author": {
         "name": "EvoDev"
       },