| name | artifact-build |
| description | Use when building a self-contained shippable artifact from scratch or a major rev — an MCP server, a CLI, a library/SDK, a skills pack, a plugin — anything that gets packaged and released rather than merged into an existing app. |
Artifact Build
For shipping a thing — a server, CLI, library, plugin, or skills pack — as
opposed to a feature inside an existing app (that's milestone-workflow). The
spine is the same one that produced clean, releasable artifacts: spec → plan →
modular TDD build → review → live validation → package.
Read the repo's CLAUDE.md first for the verify commands, package manager, and
conventions. Use those.
Phase A — Design spec, then implementation plan (two artifacts, in order)
- Design spec first, before any code. Write a spec doc: scope, the public
surface (the tools/commands/exports), the capabilities to add, and explicit
YAGNI / out-of-scope lines (transport, auth, batch, Docker, publish — name
what you're NOT doing). If you borrow ideas from a competitor/prior art, note
the source and what you deliberately don't take. Mark it "Approved (design),
pending implementation." Stop for approval.
- Then a separate implementation plan — checkbox, task-by-task, ordered
(packaging → config → core modules → wiring → validation → final verify),
formatted for step-by-step execution with a commit after every green step and
the static gate named (
node --check / tsc / whatever the repo uses).
Phase B — Modular build, TDD
- Split a monolith into focused modules (config / core / wiring) — each lands
with its own test in the same commit. Write the failing test first where
the logic is pure; implement to green; run the static gate on every file.
- Commit per green task with the plan's message.
Phase C — Dedicated review pass
A standalone review commit that does nothing but fix review findings — guarded
error paths (don't throw opaque ENOENT on a missing input — name the bad path),
dead-code removal, and honest summaries (report succeeded/total, never claim
all N succeeded when some failed). Reviewer should be a fresh perspective, not the
author's own pass.
Phase D — Live / real validation (let reality overturn the spec)
Run the artifact against the real thing — the live API, the real client, the
actual eval set — not just unit mocks. Expect the spec's assumptions to be wrong
and fix what reality exposes (e.g. "the API only accepts jpeg mime", "the eval
baseline is too easy"). This phase routinely overturns Phase-A assumptions; that's
the point. For a skills/eval artifact, this is the eval-as-failing-test gate:
RED (no skill → record what it gets wrong) → GREEN (skill makes evals pass); a
too-easy baseline means the eval is too weak.
Phase E — Release packaging
README (real quick-start + config table + the full surface), LICENSE,
.env.example, package metadata (files, keywords, repo/homepage/bugs,
engines), a capability matrix where there are tiers/variants, forward-compat
env-overrides for anything a vendor rotates, CI matrix, issue/contributor
templates, and any showcase assets (mark one-off generators "not part of the
published package"). Scrub competitor attribution from internal design docs
before going public.
Cross-cutting
Atomic commits; verify after each step; never push after a failed run until a
clean rerun; keep generated artifacts (indexes, manifests) regenerated, not
hand-edited; honesty in every summary and capability claim.
See PROVENANCE.md for sources.
