artifact-build

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.