feat(skill): add new-command scaffolding skill

[dangrondahl]

Adds a project skill at .claude/skills/new-command/ that interviews a developer and scaffolds a new Kosli CLI command (kosli <verb> <noun>) following the repo's patterns — generating the command file, test skeleton, flag constants, and registration wiring, and leaving the tree compiling.

Design for low context footprint: a lean SKILL.md (router + interview + verification) loads one archetype reference on demand; reference files defer to the canonical repo example (e.g. getFlow.go, createFlow.go) and list only the deltas instead of embedding frozen Go templates.

Covers: local (no-API), read-single, read-list, create-mutate, attest, generic-action. The API step is OpenAPI-driven (app.kosli.com/api/v2/openapi.json) to derive endpoint/payload, with an honest fallback that flags unverified shapes rather than fabricating them. Prompts for beta/hidden lifecycle marking on genuinely new commands.

Validation: each archetype was dry-run scaffolded into a throwaway command that compiled and rendered --help (including the new-verb path); then end-to-end tested by scaffolding an imaginary kosli list deployments (build + vet + help all green). Also adds an 'Adding a command' pointer to CONTRIBUTING.md.

Note: skills load at session start, so /new-command becomes available in a new session.

[claude]

Claude finished @dangrondahl's task in 2m 17s —— View job

---

Review: feat(skill): add new-command scaffolding skill

• Gather context (read all 6 skill files + doc diffs)
• Static analysis (go build ./... — green; no Go files changed)
• Verify factual claims against the live codebase
• Confirm prior review feedback was addressed

---

This is a docs-only PR (skill markdown + two doc pointers), so build/vet are unaffected — I ran go build ./... anyway and it's green. The interesting risk in a skill like this isn't compilation, it's factual rot: every symbol, signature, and file path it names is a promise to a future reader. So I spot-checked the load-bearing claims against the current tree.

✅ Every verified claim holds today

Claim in skill	Reality
canonical files (getFlow.go, createFlow.go, attestCustom.go, listArtifacts.go, listTrails.go, listFlows.go, fingerprint.go, evaluate.go, attestDecision.go)	all present
addListFlags(cmd, &o.listOptions, customPageLimit ...int)	flags.go:84 ✓ variadic page-limit
betaCLIAnnotation = "betaCLI"	root.go:20 ✓
docgen.DocHiddenAnnotation ("docHidden")	internal/docgen/formatter.go:9 ✓
CustomMaximumNArgs(max, args), MuXRequiredFlags(cmd, names, atLeastOne)	cli_utils.go ✓
addAttestationFlags(cmd, o, payload, ci)	flags.go:97 ✓ exact arity
prepareAttestationForm(o.payload, o.attachments) → 4 returns incl. cleanupNeeded	matches attestCustom.go:172 verbatim ✓
read-list uses base (not url) to keep net/url in scope	listArtifacts.go:84 base, err := ✓ — and getFlow.go:47 genuinely does shadow url, so the distinction the skill draws is real

✅ Prior-round feedback all landed

The four earlier review comments were addressed by 77af1227 (dropped pinned line numbers — wiring.md/archetype-read.md now lead with greppable landmarks), 0140fa30 (base vs url shadowing note in read-list), and 08504faf (attest payload pointer now consistently points at attestCustom.go). I re-checked each — clean.

Design notes (praise, not asks)

• The "defer to the canonical file + list deltas" architecture is the right call for longevity. By never freezing Go templates and instead saying "read getFlow.go in full and adapt," the skill can't drift out of sync with formatting/import changes — only the named symbols can rot, and those are greppable.
• The OpenAPI fallback is honest (openapi.md §6): flagging unverified payloads with // UNVERIFIED rather than fabricating field names directly upholds the repo's "never assume API structures" rule.
• The local archetype correctly threads the "no RequireGlobalFlags, no Org/ApiToken" distinction through every step — that's the most error-prone divergence and it's called out repeatedly.

Optional, non-blocking nits

1. openapi.md §1 — "~80 paths". Hedged with ~ and not load-bearing, but it's the one remaining magic number that will silently age. Consider "dozens of paths" to remove the rot surface entirely.
2. SKILL.md "Non-goals" vs wiring.md golden-file guidance are consistent (golden: "", capture after first run) — no change needed, just confirming the two files agree, since that's the kind of thing that drifts.

Nothing here blocks merge. This is a carefully-built, rot-resistant skill and the validation story in the PR description (each archetype dry-run scaffolded + an end-to-end list deployments build) matches what I see in the content. 👍
· branch new-command-skill