chore(release): promote v0.8.0 to main#478
Conversation
Bite-sized TDD-adjacent plan for PR 1 of the plugin-first install rollout. Hard pre-flight gate (Task 1 — human-driven `/plugin marketplace add Luis85/agentic-workflow` smoke test) gates all doc edits. Tasks 2-4 rewrite README, install-claude-plugin.md, and claude-plugin/specorator/README.md with full replacement content. Tasks 5-6 cover PR open and post-merge re-verification.
Design + plan updated to reflect ADR-0040 npm publish migration: README install becomes two one-liners (npm install -g specorator + /plugin marketplace add). Pre-flight gate adds CLI install verification. install-claude-plugin.md gets a "Step 1 — Install the npm CLI" section. Hard upstream blocker on v0.7.0 documented; Tasks 2-4 stay pre-staged on this branch until the migration ships.
Replace template-clone Get Started block with the canonical install path: `npm install -g specorator` (CLI from npmjs.com) plus `/plugin marketplace add Luis85/agentic-workflow` (Claude plugin from GitHub). Add "Other tools or hacking on the template" subsection pointing to cross-tool guides and the local-clone contributor path. Status block + version badge intentionally untouched here so the v0.7.0 npm publish migration PR can update them without rebase conflicts on this branch.
…-direct plugin Add "Step 1 — Install the npm CLI" section (npm install -g specorator) per ADR-0040 npm publish migration. Restructure plugin install into Option A (GitHub-direct, recommended) and Option B (local clone, contributors). Verify section now exercises both halves via `/specorator:init --dry-run`. Desk-check footer notes pre-staging context.
…ect + npm CLI Replace "Local install test" section with "Install paths". GitHub-direct plugin install + `npm install -g specorator` lead. Local-clone marketplace + `claude --plugin-dir` smoke-test demoted to contributor variants. References ADR-0040 for the npmjs.com publication path.
Outer markdown fences in Steps 1-2 collided with nested 3-backtick fences, causing check:links to parse the README quote contents as live links and fail on README-internal anchors. Bump outer fences to 4 backticks and correct the install-claude-plugin anchor (option-b prefix) plus two ADR-0040 relative paths from the plan file's location.
Codex P2 on PR #410: `specorator --version` exits 1 (no real --version flag yet) and aborts `set -e` shells. Replace both occurrences with `specorator` (no args), which prints the version banner on line 1 and exits 0. Note v0.7.1 follow-up for a real --version flag.
Codex P2 round 2 on PR #410 line 45: the plan's pre-flight Task 1 used `specorator --version` as a required smoke-test success condition, which exits 1 and would block the rollout it drives. Replace at lines 45 (smoke), 223 + 286 (mirroring the install-doc Step 1 + Verify) with `specorator` (no args) plus the same banner-source note added to install-claude-plugin.md in 4be8cb3.
…ippet Codex round 3 on PR #410: - P2 line 223: Task 3's outer markdown fence was 3 backticks; the first inner 3-backtick block closed it early, breaking subsequent rendering of the install-doc rewrite snippet. Bump outer fence to 4 backticks (mirrors the same fix applied to Tasks 1 + 2 in c9db5c4). - P3 line 228: snippet's ADR-0040 link used `../../adr/...` (correct relative to the plan file) but the snippet is meant to be pasted into `docs/how-to/install-claude-plugin.md`, where the correct path is `../adr/...`. Switch to the install-doc-relative path so the snippet produces a valid link when applied; the 4-backtick outer fence keeps the link checker from mis-resolving it from the plan's location.
) Brings to develop: - 3345cf5 fix: assert npm >= 9.5.0 before OIDC trusted publish step - cbb3df3 Merge pull request #409 (release/v0.7.0 promote) - 7850186 Merge pull request #412 (NPM_TOKEN fallback + ADR-0041) The OIDC `Assert npm supports OIDC trusted publishing` step from 3345cf5 is removed in PR #412 (--provenance no longer invoked under the ADR-0041 fallback). Mirrors the 41eb4fe pattern for v0.6.2. Refs ADR-0040, ADR-0041, #411.
chore: merge main into develop after v0.7.0 promotion
Codex P2 round 4 on PR #410 line 172: Task 2's quoted README status block still claimed "Trusted publishing via OIDC emits a provenance statement on every release." That contradicts the live README and ADR-0041 (now on develop after PR #412): Trusted Publishing is deferred until #411 closes; v0.7.x publishes via NPM_TOKEN with no npm provenance. Anyone executing Task 2 literally would reintroduce the false security claim. Replace the snippet with the deferred-state wording (matching the live README) and add a note that the OIDC/provenance line must not be rolled back while #411 is open.
docs(install): lead with plugin-first install path
Closes #416. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Closes #418. `specorator --version` now prints `specorator v<version>` and exits 0, sourcing the version from package.json. Adds `-v` alias. Replaces the no-arg banner workaround in install docs and Task 1 / Task 3 of the plugin-first-install plan. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
fix(cli): version and -V flags exit 0 instead of unknown subcommand
- hasGitInTree walks up from targetRoot to avoid false "git init" warn when specorator init runs inside a subfolder of an existing repo - Add ancestor-git test covering the subfolder case - specorator doctor: add projectAnchorCheck (fail/warn/pass) as first gate - cli.ts: skip findRepoRoot for doctor (same as init) - doctor test: unit + CLI integration coverage for projectAnchorCheck Closes #415 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Merging develop brought in the #419 fix (-V uppercase, bare VERSION output) alongside #424's handler (-v lowercase, prefixed output). Unified into one guard covering --version, -V, and -v — all print specorator v<version>. Added -V contract test. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
feat(cli): add --version / -v flag to specorator CLI
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Excluding `doctor` from `findRepoRoot` caused `SPECORATOR_ROOT` to be set to the CWD subfolder, so `projectAnchorCheck` found no `.git` even when an ancestor had one — a regression for the common `repo/subdir` invocation pattern. Fix: try `findRepoRoot` for doctor too; fall back to `targetStart` only when it throws (true no-git case), so the friendly anchor-check message is still surfaced when no repo exists anywhere in the tree. Adds regression test: cli doctor resolves ancestor .git when run from a subfolder (Codex P2 #421). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ld (#420) commands/specorator/init.md was copied as-is into the plugin, so Claude Code's namespace prefix produced /specorator:specorator:init instead of /specorator:init. Add commandsRemapRel to strip the leading specorator/ path segment at build time only; in-repo commands are unchanged. Apply the same remapping in mapSourceTargetToPlugin so markdown link rewriting stays consistent. check:claude-plugin passes. Closes #417. Co-authored-by: Luis Mendez <hallo@luis-mendez.de> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
fix(init): warn when no .git found after specorator init
\`npm run quality:metrics\` works in the template repo but fails in plugin-installed downstream projects that have no package.json. Replace every occurrence in qa, reviewer, release-manager, retrospective agents and quality-assurance/quality-metrics skills. Closes #422
Conflict between this branch's `--out` parsing (parseArgs +
destructured `pluginRoot`/`checkOnly`) and develop's new
`fileCopyPlans` entry that ships `.mcp.json` into the bundle.
Resolution:
- Keep parseArgs and `const { pluginRoot, checkOnly } = parsedArgs`
from this branch.
- Drop develop's redundant `const checkOnly = process.argv.includes(...)`.
- Keep the existence gate as `if (checkOnly && !fs.existsSync(pluginRoot))`
so build mode still creates the directory on demand for fresh
checkouts (the gitignored case introduced by this PR).
- Mirror the `subdir` pattern: extend `FileCopyPlan` with a `subfile`
field and route `copyFile` / `compareFile` writes through
`path.join(pluginRoot, plan.subfile)` instead of `repoRoot`/`plan.target`.
The `target` field stays as the canonical relative path used in
drift-error messages. Without this, `--out X` would still write
`.mcp.json` to `claude-plugin/specorator/` instead of `X/`.
Verified: typecheck, default build, `--out` build, and check all green.
Develop's merge brought in a new generated file `claude-plugin/specorator/.mcp.json` (copy of root `.mcp.json` produced by build-claude-plugin's fileCopyPlans). It was tracked by the merge because the prior gitignore only covered the four subdirectories. Add `claude-plugin/specorator/.mcp.json` to `.gitignore` and untrack it. Update `docs/specorator-product/tech.md` to enumerate it alongside the other generated outputs.
… (Codex P1) Codex flagged that this PR's premise breaks the documented marketplace install path. End users install Specorator via: /plugin marketplace add Luis85/agentic-workflow /plugin install specorator@specorator-marketplace Claude Code reads `.claude-plugin/marketplace.json` from `main`, finds the `specorator` plugin's `source: "./claude-plugin/specorator"`, and fetches files directly from that path. It does NOT run `npm run build:claude-plugin`. With the bundle gitignored, fresh main checkout has only README — marketplace consumers get a non-functional plugin. Issue #461's intent (clean PR diffs by gitignoring the generated bundle) is incompatible with the current install architecture. Either the bundle stays tracked, or the install path moves to a built distribution artifact. The latter requires an ADR and is out of scope for a chore. Revert: - `.gitignore`: drop the five `claude-plugin/specorator/...` lines. - Re-add the bundle tree (~225 files) by rebuilding from canonical sources and committing. - `package.json#scripts.check:claude-plugin`: restore the original drift-check chain (`tsx scripts/check-claude-plugin.ts && npm run build:claude-plugin -- --check`) so structural and drift checks both fire. - `.github/workflows/release.yml`: drop the "Build claude-plugin bundle" step added by a53e774 — Layer 1 readiness now finds the committed manifest, and `build-release-archive` stages the committed bundle as-is. - `docs/specorator-product/tech.md`: rewrite the Plugin bundle section to document the marketplace install constraint and explain why the bundle stays tracked. Salvageable from the abandoned approach (kept): - `--out <dir>` flag in `scripts/build-claude-plugin.ts` (useful for release-staging smoke-tests). - `subfile` field on `FileCopyPlan` so `--out X` routes file-copy plans through `pluginRoot`. - Defensive existence gate in `scripts/check-claude-plugin.ts` (early failure with a build hint when `pluginRoot` is missing under `--check`). PR scope shifts from "gitignore the bundle" to "document the marketplace constraint + keep the small CLI improvements." Issue #461 cannot be closed by this PR — the gitignore approach is architecturally incompatible. Will comment on the issue.
Codex flagged that `npm run build:claude-plugin -- --out X` produces an incomplete bundle because the build script never copies the hand-written `README.md`. The flag only existed to support the gitignore approach reverted in e83b621, so it has no remaining caller. Drop it entirely along with the `subfile` field on FileCopyPlan and the defensive existence gate in check-claude-plugin.ts. `scripts/build-claude-plugin.ts` and `scripts/check-claude-plugin.ts` are now byte-equal to develop. The PR now ships only the `docs/specorator-product/tech.md` Plugin bundle section documenting the marketplace install constraint.
The Plugin bundle section still documented `npm run build:claude-plugin -- --out X`, but that flag was removed in e98bb0d when the gitignore approach was reverted. Drop the stale line.
chore(github-archive): sync issues and pull requests
…plugin docs(plugin): document marketplace install constraint
Move the Claude Code plugin bundle from a tracked-on-main artifact to an orphan branch `dist/claude-plugin` rebuilt by CI on every push to main, so develop and main PR diffs stop carrying generated-bundle churn (closes #461) without breaking marketplace consumers. - Add ADR-0043 — choose orphan-branch + git-subdir over per-release tag, npm channel, linguist-generated, or auto-commit-on-merge. - Add `.github/workflows/publish-claude-plugin.yml` — builds the bundle from canonical `.claude/{agents,skills,commands}/` + `.mcp.json` sources on every push to main, force-pushes the staged tree to `dist/claude-plugin`. - Switch `.claude-plugin/marketplace.json` source from relative path to git-subdir pinned to `ref: dist/claude-plugin`. - Untrack `claude-plugin/specorator/{agents,skills,commands,.claude-plugin}/` and `claude-plugin/specorator/.mcp.json`; gitignore them. - Make `check-claude-plugin` generated-output checks (manifest, .mcp.json, agents/skills/commands dirs) conditional on the file being present, so a clean develop/main checkout passes without a prior local `build:claude-plugin`. Validate the new git-subdir marketplace shape. - Drop `build:claude-plugin --check` drift check from the verify gate — no committed bundle on develop/main to drift against. - Run `npm run build:claude-plugin` in `.github/workflows/release.yml` before the readiness gate so the npm tarball still ships the bundle. - Register `workflow:publish-claude-plugin` in the automation registry. - Refresh `docs/how-to/install-claude-plugin.md` and the plugin-bundle section of `docs/specorator-product/tech.md` for the orphan-branch model; document the contributor smoke-test prerequisite. Closes #474 Closes #461 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
zizmor on PR #477 flagged top-level `contents: write` as excessive + undocumented (security/code-scanning/76, /77). Top-level block is now read-only; the single `publish` job opts in to `contents: write` for the force-push to `dist/claude-plugin`. Both blocks carry explanatory comments matching the in-repo `release.yml` pattern. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
zizmor `undocumented-permissions` (security/code-scanning/78) flags the job-level `contents: write` line itself even with the block-level comment. Add an inline comment matching zizmor's expected shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codex P1 on PR #477: `workflow_dispatch` accepts any ref from the UI, so a manual run from `develop` or a feature branch would force-push that ref's content to `dist/claude-plugin` and break marketplace installs. Add a job-level `if: github.ref == 'refs/heads/main'` guard so non-main dispatches are skipped silently. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
feat(plugin): distribute bundle from dist/claude-plugin via git-subdir
CHANGELOG entry summarises the v0.8.0 cycle: - Plugin distribution moves to orphan dist/claude-plugin + git-subdir marketplace source (ADR-0043, closes #461 + #474). - New: /issue:tackle conductor skill (#443), /specorator:onboard guided series (#460), GitHub remote MCP server in project default (#471), conductor-driven model-tier injection (#440), `specorator --version` / `-v` flag (#424, #419). - Plugin install smoke test in CI (#427); operational-bot dry-run + drift checks (#438); ADR-0042 typed-artifact reader seam. - Fixes for plugin command prefix (#420), /quality:status CLI usage (#426, #428), init no-git warning (#421), product-page deployment (#456), archive-sync git identity (#468), feature-tracker readFile race (#408), and historical-status normalisation (#439). - ADR-0030 (repo-adoption) withdrawn — superseded by plugin packaging. - README + docs/specorator.md status banner refreshed for v0.8.0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 11d2f543d6
ℹ️ 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".
Codex P2 on PR #478: scripts/lib/workflow-schema.ts treats `superseded` as a valid workflow status, and v0.8.0 sets specs/repo-adoption-track/workflow-state.md to `status: superseded` (ADR-0030 withdrawn). The Astro content schema's StateStatusEnum was missing that value, so the feature-tracker loader silently skipped superseded workflow-state files instead of ingesting them — dropping them from product-page reporting. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 834b43de4f
ℹ️ 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".
Trusted Publisher activated on the specorator package on 2026-05-10, closing #411. Switch release.yml step 10 back to OIDC + provenance: - Drop NODE_AUTH_TOKEN env from publish step; OIDC token mints via id-token: write. - Drop the NPM_TOKEN-not-set guard. - Add --provenance to npm publish so every release ships with a sigstore attestation on the npmjs.com package page. - Remove # zizmor: ignore[use-trusted-publishing] suppression — the audit passes by construction now. - Refresh workflow header + permissions comment block. ADR-0044 supersedes ADR-0041 (frontmatter status: superseded; superseded-by: [ADR-0044]). ADR index regenerated. Operator guide §1 (prereqs), §5 (publish step), §5.1 (provenance posture), §7.1 (manual recovery) refreshed: NPM_TOKEN repo secret is decommissioned; manual recovery now requires minting a fresh classic Automation token on npmjs.com web UI and revoking after use. scripts/lib/release-readiness.ts comment block flips id-token: write narrative from "kept across the ADR-0041 fallback for the GitHub Release tarball attestation" to "load-bearing for both OIDC paths (npm publish + Release tarball attestation)". CHANGELOG v0.8.0 entry adds the Trusted Publishing restoration line. Closes #411 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codex P2 on PR #478: after the conditional-presence gate (ADR-0043), a partial bundle (e.g. someone deletes claude-plugin/specorator/agents/ after running build:claude-plugin) silently passed check:claude-plugin because each helper short-circuited on its own missing-file branch. Replace per-helper guards with an outer all-or-nothing presence check across the five generated artifacts (plugin.json, .mcp.json, agents/, skills/, commands/). When 0 are present, skip cleanly (clean checkout). When all 5 are present, run the full shape checks. When 1..4 are present, fail closed with a "partial bundle detected" diagnostic naming the missing paths. New test exercises the partial-bundle rejection path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0bda418f03
ℹ️ 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".
Codex P2 on PR #478: dropping `build:claude-plugin --check` from the package.json `check:claude-plugin` script (per ADR-0043) was correct for the verify gate on a clean develop/main checkout (no committed bundle to drift against), but it removed the contributor-facing drift detection too — a hand-edited or stale locally-built bundle silently passes validation. Restore drift detection inside `check-claude-plugin.ts`, gated on the all-or-nothing bundle-present branch from the prior commit. When all five generated paths are present, spawn `build-claude-plugin --check` and propagate its diagnostics. When the bundle is absent (the typical develop/main case), the drift step is skipped — the verify-gate behavior promised by ADR-0043 is preserved. Resolve the build script via this file's on-disk location rather than repoRoot so the test harness's SPECORATOR_ROOT redirection still finds the real script next to it. New test exercises the drift rejection path; the existing "validates manifest, marketplace, and generated directories" test now invokes build-claude-plugin from a seeded fixture before check, which is a more realistic shape for a successful run. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@codex review |
|
Codex Review: Didn't find any major issues. Swish! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
Summary
Promotes develop → main for the v0.8.0 release.
Headline
dist/claude-plugin+git-subdirmarketplace source (ADR-0043). Bundle is now gitignored ondevelopandmain; PR diffs stop carrying generated-artifact churn. Closes chore(plugin): gitignore claude-plugin bundle and build in CI instead #461 + Redesign Claude Code plugin install flow to support gitignored bundle #474./issue:tackleconductor skill,/specorator:onboardguided series, GitHub remote MCP server in project default, conductor-driven model-tier injection,specorator --versionflag.Included PRs (since v0.7.0)
Headliners:
Other features + fixes:
Internal / merge-of-merges:
Full list: 30 PRs merged into develop between 2026-05-09 (v0.7.0) and 2026-05-10.
What's in v0.8.0
Changed
dist/claude-pluginbranch +git-subdirmarketplace source (ADR-0043).npm run check:claude-pluginis structural-only on a clean checkout — generated-output checks are conditional on file presence.build:claude-plugin --checkdrift check dropped from the verify gate.release.ymlrunsnpm run build:claude-pluginbefore the readiness gate so the npm tarball still ships the bundle.Added
/issue:tackletriage-first conductor (feat(workflow): add /issue:tackle conductor skill #443)./specorator:onboardguided 5-step onboarding (feat(onboarding): add /specorator:onboard guided issue series #460)..mcp.json(feat: add GitHub remote MCP server to project config #471).specorator --version/-vflag, exit code fixes (feat(cli): add --version / -v flag to specorator CLI #424, fix(cli): version and -V flags exit 0 instead of unknown subcommand #419).Fixed
specorator/prefix from command paths (fix(plugin): strip specorator/ prefix from commands during plugin build #420).specorator initwarns when no.gitis found (fix(init): warn when no .git found after specorator init #421)./quality:statusand quality agents/skills use thespecoratorCLI (fix(quality): use specorator cmd in agents and skills #426, fix(quality): use specorator CLI in /quality:status command #428).architect,dev,reviewerno longer hardcodemodel: opus(fix(agents): remove hardcoded opus model from architect, dev, reviewer #429).gh-pagesbranch — broken images fixed (fix(pages): dedicated product-page branch + fix broken images #456).readFileENOENT race (fix(feature-tracker): guard readFile against ENOENT race in test suite #408).Post-merge operator checklist (manual — requires human authorisation)
dist/claude-pluginorphan branch. First push tomainafter this merge fires.github/workflows/publish-claude-plugin.yml, which builds the bundle and force-pushes it todist/claude-plugin. Marketplace consumers then resolve thegit-subdirsource successfully on/plugin marketplace update./plugin marketplace add Luis85/agentic-workflow+/plugin install specorator@specorator-marketplaceon a fresh Claude Code session — verify the bundle materialises and/specorator:welcomeresolves.release.ymlonce the orphan branch is in place:gh workflow run release.yml -f version=0.8.0 -f dry_run=truefirst; then non-dry-run withconfirm=0.8.0andpublish_package=true.main→developto keep them in sync after the release tag is cut.Test plan
npm run verifygreen locally (sequential run; the parallel test-pool flake ontests/scripts/cli.test.tsis the same pre-existing Windows-only issue, all 443 tests pass under--no-file-parallelism).npm run check:public-surfacesgreen — README badge, README status line, anddocs/specorator.mdversion matchpackage.json#version0.8.0.publish-claude-plugin.ymlruns successfully on first push to main and createsdist/claude-plugin.npm install -g specorator && specorator --versionprints0.8.0.🤖 Generated with Claude Code