Pre Publish Checklist

Pre-Publish Checklist

Arguments

• --skip <check> — skip a specific check by name. Can be repeated. Valid values: skill-lint, version-sync, code-review, tests, ci, docs

Process

Step 1 — Detect repo types

Scan the repo root for the following signals. Collect all matches — a repo can be multiple types simultaneously.

When an Agent Skill is detected, record the skill target path (repo root, skill/, or the plugin root) — later Agent Skill checks operate on this path, not the repo root.

If no signals match, report "unknown repo type — cannot determine which checks to run" and stop.

Step 2 — Run checks

Run every applicable check. Skip any whose name matches a --skip argument.

Agent Skill checks (when an Agent Skill signal matched)

Use the skill target path recorded in Step 1 (repo root, skill/, or the plugin root) for both checks below.

1. Skill lint (--skip skill-lint to skip)

   • Invoke the William-Yeh/agent-skill-linter skill against the skill target path: /skill-lint check <skill-target-path>
   • The linter auto-detects single-skill vs. plugin mode from the target.
   • Linter errors → BLOCKING
   • Linter warnings only → WARNING

2. Version sync (--skip version-sync to skip)

   • Run: git tag --list to check if the repo has any existing git tags.
   • If no tags exist, skip this check (nothing to compare against).
   • If tags exist, get the latest tag: git describe --tags --abbrev=0
   • Parse the version field from the SKILL.md frontmatter at the skill target path. In plugin mode, read the version from .claude-plugin/plugin.json instead.
   • Strip any leading v prefix from the git tag before comparing (e.g. v0.1.0 → 0.1.0).
   • Compare the parsed version against the latest git tag:
     • If version == latest tag → BLOCKING: "Version not bumped — <version> matches existing tag <tag>. Increment the version before publishing."
     • If version < latest tag → BLOCKING: "Version <version> is older than existing tag <tag>."
     • If version > latest tag → PASS

Program source code checks (when any language build manifest detected)

3. Code review (--skip code-review to skip)

   • Invoke the William-Yeh/common-code-reviewer skill: /common-code-reviewer
   • Reviewer verdict "REQUEST CHANGES" → BLOCKING
   • Reviewer verdict "APPROVE WITH COMMENTS" → WARNING
   • Reviewer verdict "APPROVE" → pass

4. Local tests (--skip tests to skip)

   • Run the test command for each detected language:

     Repo type	Test command
     Python	uv run pytest
     Node.js	npm test
     Go	go test ./...
     Rust	cargo test
     Java	./mvnw test or ./gradlew test
     Kotlin	./gradlew test
     Clojure	lein test or clojure -T:build test
     C# / F#	dotnet test
     C/C++	cmake --build . --target test or make test

   • Any test failure → BLOCKING

5. CI status (--skip ci to skip)

   • Run: gh run list --branch $(git branch --show-current) --limit 1
   • Latest run status is not completed with success conclusion → BLOCKING

Step 3 — Report

Output a consolidated report:

## Pre-Publish Checklist

Detected types: <comma-separated list>

### <Type>
- [x] <check name>: PASSED
- [WARNING] <check name>: <reason>
- [BLOCKING] <check name>: <reason>

---

Verdict: BLOCKED — N blocking issue(s) must be resolved before publishing.

Blocking issues:
1. <description>

Warnings (non-blocking):
1. <description>

When all checks pass or only warnings remain, the verdict is:

Verdict: READY TO PUBLISH

Step 4 — Document rationale (when READY TO PUBLISH) (--skip docs to skip)

Skip this step entirely if there are blocking issues or if --skip docs was passed.

Gather context from all available sources:

• The current coding-agent session dialog (decisions made, alternatives discussed, trade-offs considered)
• git log and diff since the last tag or branch point
• Issue/PR references mentioned in commit messages or the session

Then update or create the following documents as applicable.

4a — ADR (Architecture Decision Record)

• First, check README.md for any project-specific documentation arrangement (e.g. the project may direct decision records to DESIGN.md, a wiki, or a custom path).

• If no project-specific arrangement is documented, look for a docs/adr/ or adr/ directory; if neither exists, create docs/adr/.

• Scan existing ADR files to determine the next sequential number (e.g. 0001, 0002).

• Write a new ADR only if the change involves a design or architecture decision (new dependency, changed interface contract, security trade-off, algorithm choice). Skip for pure bug fixes or trivial patches.

• Template:

  # ADR-<NNNN>: <Short decision title>
  
  Date: <YYYY-MM-DD>
  
  ## Status
  
  Accepted
  
  ## Context
  
  <Why this change was needed — problem statement, constraints, background.>
  
  ## Decision
  
  <What was decided and why this option was chosen over alternatives.>
  
  ## Consequences
  
  <Trade-offs, follow-up work, risks introduced or mitigated.>
  

4a-ii — ADR consolidation review

After writing any new ADR (or even if none was written), read all existing ADRs and assess whether consolidation is warranted:

• Superseded decisions: if a new ADR reverses or significantly changes an older one, update the older ADR's ## Status to Superseded by ADR-<NNNN> and add a note explaining what changed.
• Overlapping decisions: if two or more ADRs cover the same concern from different angles and have drifted out of sync, merge their content into the most recent one, mark the older ones as Merged into ADR-<NNNN>, and update cross-references.
• Stale assumptions: if context or consequences described in an old ADR are now known to be incorrect (e.g. a dependency was replaced, a constraint was lifted), annotate that ADR with an ## Amendment section rather than editing history in place.

Skip this sub-step if there are fewer than two existing ADRs (nothing to consolidate).

Include consolidation actions in the documentation summary:

- [ADR] docs/adr/0001-choose-httpx.md — status updated to "Superseded by ADR-0004"
- [ADR] docs/adr/0002-retry-strategy.md — Amendment section added

4b — Usage / changelog notes

• Look for CHANGELOG.md, USAGE.md, or README.md at the repo root.
• Append or update the relevant section to reflect: what changed, how users invoke or benefit from it, and any breaking changes or migration steps.
• Keep it concise — one to three bullet points per item.

4c — Other noteworthy items

• If the session dialog or code reveals performance characteristics, known limitations, or operational notes future maintainers should know, add a short note to the appropriate place (e.g. NOTES.md, inline comment block, or an existing developer guide).

After completing documentation, output a summary:

## Documentation updates

- [ADR] docs/adr/0003-use-uv-for-dependency-management.md — created
- [CHANGELOG] Added entry under "Unreleased" for <feature>
- (none) — no architecture decisions or notable items to record

Step 5 — Handoff

• No blocking issues: Offer to invoke commit-commands:commit-push-pr to complete the publish step.
• Blocking issues remain: Display them clearly. Do not proceed.