From 024fc5fea35d3d2be41955d3fcabd52198c72ccb Mon Sep 17 00:00:00 2001 From: John Doe Date: Sun, 22 Mar 2026 22:19:29 +0800 Subject: [PATCH] feat: add distribution pipeline checks across skill workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When designing CLI tools, libraries, or other standalone artifacts, the workflow now checks whether a build/publish pipeline exists at every stage: - /office-hours: Phase 3 premise challenge asks "how will users get it?" Design doc templates include a "Distribution Plan" section. - /plan-eng-review: Step 0 Scope Challenge adds distribution check (#6). Architecture Review checks distribution architecture for new artifacts. - /ship: New Step 1.5 detects new cmd/main.go additions and verifies a release workflow exists. Offers to add one or defer to TODOS.md. - /review checklist: New "Distribution & CI/CD Pipeline" category in Pass 2 (INFORMATIONAL) covers CI version pins, cross-platform builds, publish idempotency, and version tag consistency. Motivation: In a real project, we designed and shipped a complete CLI tool (design doc, eng review, implementation, deployment) but forgot the CI/CD release pipeline. The binary was built locally but never published — users couldn't download it. This gap was invisible because no skill in the chain asked "how does the artifact reach users?" Co-Authored-By: Claude Opus 4.6 (1M context) --- office-hours/SKILL.md.tmpl | 12 +++++++++++- plan-eng-review/SKILL.md.tmpl | 7 +++++++ review/checklist.md | 15 ++++++++++++++- ship/SKILL.md.tmpl | 27 +++++++++++++++++++++++++++ 4 files changed, 59 insertions(+), 2 deletions(-) diff --git a/office-hours/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl index 33d673c17..864a9072e 100644 --- a/office-hours/SKILL.md.tmpl +++ b/office-hours/SKILL.md.tmpl @@ -334,7 +334,8 @@ Before proposing solutions, challenge the premises: 1. **Is this the right problem?** Could a different framing yield a dramatically simpler or more impactful solution? 2. **What happens if we do nothing?** Real pain point or hypothetical one? 3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused. -4. **Startup mode only:** Synthesize the diagnostic evidence from Phase 2A. Does it support this direction? Where are the gaps? +4. **If the deliverable is a new artifact** (CLI binary, library, package, container image, mobile app): **how will users get it?** Code without distribution is code nobody can use. The design must include a distribution channel (GitHub Releases, package manager, container registry, app store) and CI/CD pipeline — or explicitly defer it. +5. **Startup mode only:** Synthesize the diagnostic evidence from Phase 2A. Does it support this direction? Where are the gaps? Output premises as clear statements the user must agree with before proceeding: ``` @@ -465,6 +466,11 @@ Supersedes: {prior filename — omit this line if first design on this branch} ## Success Criteria {measurable criteria from Phase 2A} +## Distribution Plan +{how users get the deliverable — binary download, package manager, container image, web service, etc.} +{CI/CD pipeline for building and publishing — GitHub Actions, manual release, auto-deploy on merge?} +{omit this section if the deliverable is a web service with existing deployment pipeline} + ## Dependencies {blockers, prerequisites, related work} @@ -514,6 +520,10 @@ Supersedes: {prior filename — omit this line if first design on this branch} ## Success Criteria {what "done" looks like} +## Distribution Plan +{how users get the deliverable — binary download, package manager, container image, web service, etc.} +{CI/CD pipeline for building and publishing — or "existing deployment pipeline covers this"} + ## Next Steps {concrete build tasks — what to implement first, second, third} diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index f48bdd497..6b9a4b15c 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -94,6 +94,12 @@ Before reviewing anything, answer these questions: 5. **Completeness check:** Is the plan doing the complete version or a shortcut? With AI-assisted coding, the cost of completeness (100% test coverage, full edge case handling, complete error paths) is 10-100x cheaper than with a human team. If the plan proposes a shortcut that saves human-hours but only saves minutes with CC+gstack, recommend the complete version. Boil the lake. +6. **Distribution check:** If the plan introduces a new artifact type (CLI binary, library package, container image, mobile app), does it include the build/publish pipeline? Code without distribution is code nobody can use. Check: + - Is there a CI/CD workflow for building and publishing the artifact? + - Are target platforms defined (linux/darwin/windows, amd64/arm64)? + - How will users download or install it (GitHub Releases, package manager, container registry)? + If the plan defers distribution, flag it explicitly in the "NOT in scope" section — don't let it silently drop. + If the complexity check triggers (8+ files or 2+ new classes/services), proactively recommend scope reduction via AskUserQuestion — explain what's overbuilt, propose a minimal version that achieves the core goal, and ask whether to reduce or proceed as-is. If the complexity check does not trigger, present your Step 0 findings and proceed directly to Section 1. ### Step 0.5: Codex plan review (optional) @@ -134,6 +140,7 @@ Evaluate: * Security architecture (auth, data access, API boundaries). * Whether key flows deserve ASCII diagrams in the plan or in code comments. * For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it. +* **Distribution architecture:** If this introduces a new artifact (binary, package, container), how does it get built, published, and updated? Is the CI/CD pipeline part of the plan or deferred? **STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. diff --git a/review/checklist.md b/review/checklist.md index c24c6a22a..7f7923ff8 100644 --- a/review/checklist.md +++ b/review/checklist.md @@ -125,6 +125,18 @@ To do this: use Grep to find all references to the sibling values (e.g., grep fo - Small utility additions (<5KB gzipped) - Server-side-only dependencies +#### Distribution & CI/CD Pipeline +- CI/CD workflow changes (`.github/workflows/`): verify build tool versions match project requirements, artifact names/paths are correct, secrets use `${{ secrets.X }}` not hardcoded values +- New artifact types (CLI binary, library, package): verify a publish/release workflow exists and targets correct platforms +- Cross-platform builds: verify CI matrix covers all target OS/arch combinations, or documents which are untested +- Version tag format consistency: `v1.2.3` vs `1.2.3` — must match across VERSION file, git tags, and publish scripts +- Publish step idempotency: re-running the publish workflow should not fail (e.g., `gh release delete` before `gh release create`) + +**DO NOT flag:** +- Web services with existing auto-deploy pipelines (Docker build + K8s deploy) +- Internal tools not distributed outside the team +- Test-only CI changes (adding test steps, not publish steps) + --- ## Severity Classification @@ -141,7 +153,8 @@ CRITICAL (highest severity): INFORMATIONAL (lower severity): ├─ Time Window Safety ├─ Type Coercion at Boundaries ├─ View/Frontend - └─ Performance & Bundle Impact + ├─ Performance & Bundle Impact + └─ Distribution & CI/CD Pipeline All findings are actioned via Fix-First Review. Severity determines presentation order and classification of AUTO-FIX vs ASK — critical diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl index a748314d1..7b37e8672 100644 --- a/ship/SKILL.md.tmpl +++ b/ship/SKILL.md.tmpl @@ -83,6 +83,33 @@ If the Eng Review is NOT "CLEAR": --- +## Step 1.5: Distribution Pipeline Check + +If the diff introduces a new standalone artifact (CLI binary, library package, tool) — not a web +service with existing deployment — verify that a distribution pipeline exists. + +1. Check if the diff adds a new `cmd/` directory, `main.go`, or `bin/` entry point: + ```bash + git diff origin/ --name-only | grep -E '(cmd/.*/main\.go|bin/|Cargo\.toml|setup\.py|package\.json)' | head -5 + ``` + +2. If new artifact detected, check for a release workflow: + ```bash + ls .github/workflows/ 2>/dev/null | grep -iE 'release|publish|dist' + ``` + +3. **If no release pipeline exists and a new artifact was added:** Use AskUserQuestion: + - "This PR adds a new binary/tool but there's no CI/CD pipeline to build and publish it. + Users won't be able to download the artifact after merge." + - A) Add a release workflow now (GitHub Actions cross-platform build + GitHub Releases) + - B) Defer — add to TODOS.md + - C) Not needed — this is internal/web-only, existing deployment covers it + +4. **If release pipeline exists:** Continue silently. +5. **If no new artifact detected:** Skip silently. + +--- + ## Step 2: Merge the base branch (BEFORE tests) Fetch and merge the base branch into the feature branch so tests run against the merged state: