Upgrade CMK standard ceremony and skill wording quality by jayden-dang · Pull Request #22 · CommandOSSLabs/ai-devkit

jayden-dang · 2026-08-28T11:10:39Z

Summary

Brings the delivery and requirements skills up to a clearer standard ceremony (scope band, docs-ready, close package), then hardens pack-wide skill wording and structure so descriptions, references, and a few high-pressure gates hold under real agent pressure.

What changed

Ceremony and delivery contract

Requirements elicitation: close package, scope band, and guards for existing behavior, with recorded test evidence
Delivery workflow owns scope-band / docs-ready vocabulary; intake records the band; pipeline gates implement on docs-ready
Spec/plan and design stop when docs are not ready; ship and review tighten verification and requirement-ID citations
On-ramps guide added so agents know where to enter the docs

Wording and structure pass

Model-facing skill descriptions open with Use when… and name the deliverable more clearly
Long reference files get a Contents section; codebase-docs and rule move heavy workflow into references/
Delivery pipeline / review / spec-plan meet the skill line budget; scope-band points at its real home
Pressure-tested Red Flags and rationalizations for ship, review, and Sui SDK (JSON-RPC → gRPC), with TESTS.md on those skills

Why

Agents were skipping docs gates, summarizing workflow in descriptions instead of reading the body, and failing under deadline / authority / tutorial pressure. This branch makes the ceremony explicit and the skill text match how we expect agents to behave.

Test plan

./scripts/skill-lint.sh passes on this revision
Ship / review / Sui SDK scenarios: fail without the skill, pass with it (recorded in each skill’s TESTS.md)
Spot-check a delivery run: intake states scope band + docs-ready before implement
Spot-check description routing still fires the right skill for a few common prompts

Stop drafting docs/requirements from thin or solution-shaped input without a confirmed close package, and require SHALL CONTINUE TO guards on patch Iterate so existing behavior stays explicit in the AC contract.

Give delivery a single home for trivial/patch/feature sizing, the implement docs bar, and one-execution-engine so phases share the same readiness language.

Require the stated scope band's docs bar before implement, routing thin feature work through cmk:requirements instead of skipping to code under pressure.

Make intake state sizing and requirements readiness on the issue and context brief, and capture reproduction before planning fixes on defect issues.

Make completion claims require fresh full verification evidence, and have review cite PREFIX-N.M when walking acceptance criteria.

Block planning and feature-level design when requirements are missing or unconfirmed, and map plan tasks to requirement IDs when they exist.

Give situations a single cmk:* entry table, wire the CLAUDE.md template to it, and ignore local .skills/ scratch used for skill research notes.

Make refs over ~100 lines scannable per the author-skills hierarchy rule.

Align CMK skill frontmatter with the author-skills house form and trim a few outcome nouns (requirements, simplify, repo-setup).

Attribute scope-band to delivery-workflow and compress the superpowers adaptation section so skill-lint stays green.

Trim the body under 150 lines and disambiguate the description from durable cmk:design docs.

Keep the skill body as entry points and pointers; harden split/length contracts that used to read as soft preferences.

Leave mode stubs in SKILL.md and drop the Output section that only restated Create/Iterate/Promote.

Move lens definitions to references for the line budget, add Red Flags and LGTM rationalizations from a grok-4.5 RED baseline, and record TESTS.md.

Add Red Flags plus rationalization rows from a grok-4.5 RED failure, and record GREEN evidence in TESTS.md.

Extend the stale→gRPC table, add Red Flags/rationalizations from a grok-4.5 RED failure, and record TESTS.md.

Document the description house form, codebase-docs/rule reference shape, and the pack-wide remediation outcome.

…version roster The pipeline's mandatory read #1 had been narrowed to delivery-workflow's scope-band reference while still labelled "tracking contract", leaving no item that required the delivery-workflow body — so an agent never loaded the execution-ready / ship-ready definitions that phases 4 and 5 gate on. Split it back into two entries: the skill, then its scope-band reference. The version roster listed cmk:agent-instructions in two mutually exclusive bands at once and still claimed 0.1.x for delivery-family skills this branch had just bumped. Rewrite it so every skill appears in exactly one band. Drop the now-subjectless codebase-docs size-budget exemption (this branch took it from 160+ lines to 32) and make the array expansion safe under set -u on bash 3.2, so the 150-line gate covers it again. Qualify getObject by client in the sui-sdk migration table — it had been listed on both the stale and the current side of a table whose contract is "use the right column". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Resolves the overlap with #22, which landed first: - cicd/SKILL.md — keep main's "Use when…" description house form, carry this branch's "add security scanning" / "scan for vulnerabilities" triggers, and take 0.4.0 (a new guidance facet, not the 0.3.4 wording bump). - delivery-review/SKILL.md — main moved the seven lenses out to references/lenses.md, so this branch's inline lens-6 edit had no target left. Re-applied it there instead: the security lens still has to name the scans that backed it and the classes that did not run. Taking either side of that conflict verbatim would have dropped the change silently. - conventions.md — main's rewritten version roster, with cmk:cicd moved from the 0.3.x band to 0.4.x so it stays named exactly once. - docs/ai/skills/delivery-review.md — record references/lenses.md and the new Red Flags / Rationalizations sections, which the lens extraction left out. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

…rd-ceremony" This reverts commit 6b6781f, reversing changes made to 125a113.

harrymove-ctrl · 2026-08-30T07:00:55Z

Reverted from main in 567ffba — merged prematurely. GitHub does not allow reopening a merged PR, so this work continues in #25, which carries all 17 of @jayden-dang's commits unchanged (identical diff: 68 files, +1115/-351). Please review there.

jayden-dang · 2026-08-28T11:10:39Z