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 13s —— View job

---

Review: new-command scaffolding skill

• Gather context (read all changed files)
• Static analysis (go build/go vet) — see note below
• Verify the prior review-comment fixes landed
• Spot-check reference accuracy against the repo
• Post review summary

---

Static analysis

The diff is docs-only — SKILL.md, six references/*.md, plus CLAUDE.md and CONTRIBUTING.md. No .go files are touched, so go build/go vet/go mod tidy are unaffected (nothing to break). This is the right footprint for a skill PR.

Prior review comments — all resolved ✅

Comment	Status
flags.go:84 pinned line in archetype-read	Fixed — now defers to the addListFlags symbol (commit 77af1227/d38ee1db)
root.go "line 407/97" drift in wiring	Fixed — now uses the search landmark "the block that lists newGetCmd, newCreateCmd"
read-list url shadowing footgun	Fixed — now explicitly names the base variable (0140fa30)
openapi.md attest payload pointing at a different file	Fixed — both now point at attestCustom.go (08504faf)
CONTRIBUTING heading wording (mbevc1)	Fixed (ac80b090)

Accuracy spot-check (verified against current cmd/kosli/)

Every symbol/landmark the references rely on resolves correctly today:

• addListFlags(cmd, o, customPageLimit ...int) — variadic third arg is real; listTrails.go:124 uses addListFlags(cmd, &o.listOptions, 20) exactly as documented ✓
• betaCLIAnnotation = "betaCLI" (root.go:20) and docgen.DocHiddenAnnotation = "docHidden" (internal/docgen/formatter.go) ✓
• listArtifacts.go builds base, err := url.JoinPath(...) then url.Values{} — the read-list note matches the source verbatim ✓
• getFlow.go:47 does shadow url (url, err := url.JoinPath(...)), confirming the read-single delta and the rationale for the base/neturl notes elsewhere ✓
• CustomMaximumNArgs (cli_utils.go:762), wrapAttestationError (attestation.go:238), prepareAttestationForm (attestation.go:192), addAttestationFlags(cmd, o, payload, ci) (flags.go:97) all exist with the documented shapes ✓
• root.go:419 AddCommand block lists newGetCmd/newCreateCmd — the wiring landmark is valid ✓

What's well done

• Low-context design — the "defer to canonical file + list only the deltas" approach is the right call. It avoids the frozen-template rot that plagues scaffolding tools, and the verification step (go build → vet → --help) gives an honest compile-green gate.
• Symbol-over-line-number discipline — after this round of fixes the references rely on greppable names rather than pinned lines throughout. That's the maintainable choice and it's now applied consistently.
• Honest OpenAPI fallback — references/openapi.md's "never fabricate / mark // UNVERIFIED" rule upholds the repo's "never assume API structures" principle instead of inventing field names.
• Lifecycle coverage — beta/hidden handling via betaCLIAnnotation + docgen.DocHiddenAnnotation matches the real annotations.

Minor (optional, non-blocking)

• references/openapi.md §3 uses PUT /flows/{org} as the worked example, while the create-mutate archetype points at createFlow.go. Worth a quick sanity-check that the example method/path still matches that command's actual call, since it's the one fully-spelled-out endpoint a reader is most likely to copy. Not a correctness issue — just the one place a concrete path is hard-coded rather than derived.

Nothing blocking here. This is a clean, well-scoped, already-approved docs PR and the earlier feedback has been fully addressed. 👍
· new-command-skill