diff --git a/.gitignore b/.gitignore index 9072ea8..09ca3db 100644 --- a/.gitignore +++ b/.gitignore @@ -60,3 +60,4 @@ docker-compose.override.yml **/evals-workspace/**/with_skill/ **/evals-workspace/**/without_skill/ **/evals-workspace/**/benchmark.json +.skills/ diff --git a/docs/ai/skills/conventions.md b/docs/ai/skills/conventions.md index 0ab8165..257b178 100644 --- a/docs/ai/skills/conventions.md +++ b/docs/ai/skills/conventions.md @@ -7,15 +7,15 @@ Every skill under [`skills/`](../../../skills/) follows the same packaging shape Frontmatter declares three fields the host (Claude Code or OpenCode) reads to discover and trigger the skill, plus one optional fourth field for user-invoked skills: - `name` — `cmk:`, used as the slash command and skill ID. -- `description` — natural-language trigger phrases plus what the skill does. Used by the agent to auto-select the skill from user intent. A user-invoked skill (`disable-model-invocation: true`) writes one plain human-facing line naming the deliverable instead — the agent never routes on that line. -- `version` — `0.4.0` on `cmk:design` and `cmk:delivery-pipeline` (phase 3b); `0.3.0` on `cmk:adr`, `cmk:docs`, and `cmk:requirements` (guidance revision) and `cmk:local-stack` (Modes revision); `0.2.1` on `cmk:cicd` (speedup-misattribution trap); `0.2.0` on two docs-family skills (`learn`, `rule`) and six setup-family skills (`agent-instructions`, `agent-vendors`, `infra`, `mcp-config`, `project-layout`, `toolchain`); `0.1.x` on the rest — `repo-setup` and `sync`, `test-resources`, `rust`, and `testcontainers` (new setup-family skills), the other delivery-family skills (incl. new `cmk:delivery-simplify` at `0.1.0`), both knowledge-family skills, the two remaining docs-family skills (`codebase-docs`, `glossary`), and `cmk:interpret`. +- `description` — opens in the second person (`Use when…` / `Use whenever…`) with trigger phrases plus an **outcome noun** (the deliverable), not a workflow step list. Used by the agent to auto-select the skill from user intent. A user-invoked skill (`disable-model-invocation: true`) writes one plain human-facing line naming the deliverable instead — the agent never routes on that line. +- `version` — `0.6.x` on `cmk:design`; `0.5.x` on `cmk:delivery-pipeline`; `0.4.x` on `cmk:requirements` (Standard elicitation: close package, scope band, guards); `0.3.x` on `cmk:delivery-workflow`, `cmk:agent-instructions`, `cmk:adr`, `cmk:docs`, and `cmk:local-stack`; `0.2.1` on `cmk:cicd` (speedup-misattribution trap); `0.2.0` on two docs-family skills (`learn`, `rule`) and six setup-family skills (`agent-instructions`, `agent-vendors`, `infra`, `mcp-config`, `project-layout`, `toolchain`); `0.1.x` on the rest — `repo-setup` and `sync`, `test-resources`, `rust`, and `testcontainers` (new setup-family skills), the other delivery-family skills (incl. new `cmk:delivery-simplify` at `0.1.0`), both knowledge-family skills, the two remaining docs-family skills (`codebase-docs`, `glossary`), and `cmk:interpret`. - `disable-model-invocation: true` — optional, fourth field only. Present on `cmk:interpret`. The closer is still `---`. No skill file references outside its own package by relative path — the rule binds a package's own references, not content it emits into a target repo; a skill that needs a target-repo artifact names it repo-root-relative, and a skill that needs another skill cites it by `cmk:` name — see `cmk:agent-vendors`. Docs-family skills (`adr`, `codebase-docs`, `design`, `docs`, `glossary`, `learn`, `requirements`, `rule`) mostly expose two phases — `Workflow: Create` and `Workflow: Iterate` — and offload long-form guidance, templates, and placement rules into `references/*.md` so the SKILL body stays scannable (`cmk:glossary` is compact enough to carry its rules inline and ships no `references/` folder). The `references/` files are loaded on demand via "Read `references/.md`" lines. `cmk:requirements` and `cmk:design` pair a conventions file (placement) with a guidance file (a shaping directive rather than a fixed form) — the former fixed-form templates were retired in favor of the guidance files plus the baseline scaffold templates under `docs/templates/`. -Three docs-family skills break the create/iterate pattern: `cmk:learn` uses `Workflow: Extract` / `Workflow: Review`, `cmk:codebase-docs` uses `Bootstrap workflow` / `Update workflow`, and `cmk:docs` uses `Modes` (Init/Update/Verify) plus a single `Workflow`. `cmk:rule` adds a third phase, `Workflow: Promote`. +Three docs-family skills break the create/iterate pattern: `cmk:learn` uses `Workflow: Extract` / `Workflow: Review`, `cmk:codebase-docs` uses Bootstrap/Update entry points with workflows behind `references/`, and `cmk:docs` uses `Modes` (Init/Update/Verify) plus a single `Workflow`. `cmk:rule` adds Audit/Gate modes (bodies in `references/`) and Promote. Setup-family skills (`agent-instructions`, `agent-vendors`, `cicd`, `infra`, `local-stack`, `mcp-config`, `project-layout`, `repo-setup`, `rust`, `sync`, `test-resources`, `testcontainers`, `toolchain`) don't follow create/iterate at all — every one exposes a `## Modes` section (Init/Update/Verify, or the skill's equivalents such as sync's baseline/sync/contribute) for standing up or auditing its facet, and every one ends in a report-only `## Verify` section a caller (human or `cmk:repo-setup`) can run to assess whether a target repo satisfies the facet. Verify never mutates. @@ -27,7 +27,7 @@ Knowledge-family skills (`sui-sdk`, `sui-devstack`) are domain reference packs s ## Where - Frontmatter, on every skill: open any `skills//SKILL.md` and read lines 1–5 (1–6 when `disable-model-invocation: true` is present). -- Skills with `references/`: `skills/adr/`, `skills/agent-instructions/`, `skills/agent-vendors/`, `skills/cicd/`, `skills/design/`, `skills/docs/`, `skills/infra/`, `skills/learn/`, `skills/local-stack/`, `skills/project-layout/`, `skills/repo-setup/`, `skills/requirements/`, `skills/rule/`, `skills/rust/`, `skills/sync/`, `skills/test-resources/`, `skills/toolchain/`, `skills/delivery-workflow/`, `skills/discover-efforts/`, `skills/delivery-intake/`, `skills/delivery-simplify/`, `skills/delivery-review/`, `skills/delivery-ship/`, `skills/delivery-pipeline/`, `skills/sui-devstack/`, `skills/interpret/`. Skills without one: `skills/codebase-docs/`, `skills/glossary/`, `skills/mcp-config/`, `skills/delivery-spec-plan/`, `skills/delivery-handoff/`, `skills/sui-sdk/`, `skills/testcontainers/`. +- Skills with `references/`: `skills/adr/`, `skills/agent-instructions/`, `skills/agent-vendors/`, `skills/cicd/`, `skills/codebase-docs/`, `skills/design/`, `skills/docs/`, `skills/infra/`, `skills/learn/`, `skills/local-stack/`, `skills/project-layout/`, `skills/repo-setup/`, `skills/requirements/`, `skills/rule/`, `skills/rust/`, `skills/sync/`, `skills/test-resources/`, `skills/toolchain/`, `skills/delivery-workflow/`, `skills/discover-efforts/`, `skills/delivery-intake/`, `skills/delivery-simplify/`, `skills/delivery-review/`, `skills/delivery-ship/`, `skills/delivery-pipeline/`, `skills/sui-devstack/`, `skills/interpret/`. Skills without one: `skills/glossary/`, `skills/mcp-config/`, `skills/delivery-spec-plan/`, `skills/delivery-handoff/`, `skills/sui-sdk/`, `skills/testcontainers/`. - Skills with `eval.json`: `skills/agent-instructions/eval.json`, `skills/codebase-docs/eval.json`, `skills/local-stack/eval.json`, `skills/repo-setup/eval.json`, `skills/sync/eval.json`, `skills/interpret/eval.json`. No delivery-family or knowledge-family skill ships one. - The shared docs-family workflow shape: grep for `^## Workflow: Create` and `^## Workflow: Iterate` across `skills/*/SKILL.md`. - The shared setup-family Verify contract: grep for the exact heading `^## Verify$` across `skills/*/SKILL.md` — every hit is a setup-family skill. `skills/delivery-review/SKILL.md` has a similarly named but distinct `## Verify before acting` section (adversarial verification of review findings, not a report-only facet check) — match on the exact heading, not the prefix, to tell them apart. diff --git a/docs/ai/skills/requirements.md b/docs/ai/skills/requirements.md index bf8cae3..dcfc92a 100644 --- a/docs/ai/skills/requirements.md +++ b/docs/ai/skills/requirements.md @@ -1,11 +1,13 @@ # cmk:requirements ## What -Skill that drafts and iterates requirements documents — the upstream "what and why" before any technical design, speaking technically where the product itself is technical. Synthesizes from conversations, research notes, Notion/Google Doc links, and `docs/knowledge/` entries; interviews first (one question at a time) when the input is an idea rather than settled requirements. +Skill that drafts and iterates requirements documents — the upstream "what and why" before any technical design, speaking technically where the product itself is technical. Synthesizes from conversations, research notes, Notion/Google Doc links, and `docs/knowledge/` entries. When input is thin or solution-shaped, runs elicitation (scope band, problem lock, cards, **close package + explicit yes**) before writing `docs/requirements/`; Iterate adds `SHALL CONTINUE TO` guards when existing behavior must keep working. ## Where -- Skill body: `skills/requirements/SKILL.md` — sections `Input`, `Elicitation`, `Workflow: Create`, `Workflow: Iterate`, `Output`, `Links`. +- Skill body: `skills/requirements/SKILL.md` — sections `Input`, `Elicitation` (HARD-GATE), `Workflow: Create`, `Workflow: Iterate`, `Output`, `Red Flags`, `Rationalizations`, `Links`. +- Elicitation protocol: `skills/requirements/references/elicitation-protocol.md` — scope band, problem lock, cards, close package provenance. - Placement rules: `skills/requirements/references/requirements-conventions.md`. -- Shaping directive (not a fixed form): `skills/requirements/references/requirements-guidance.md` — normative vocabulary, locked-decision registers, progressive disclosure, coherence. +- Shaping directive (not a fixed form): `skills/requirements/references/requirements-guidance.md` — criteria contract, **guarding existing behavior**, locked-decision registers, progressive disclosure, coherence. +- Test evidence: `skills/requirements/TESTS.md`; `skills/requirements/eval.json`. - Output template (baseline scaffold shape): `docs/templates/requirements.md`. - Default placement: `docs/requirements/.md` — see `docs/requirements/README.md`. Shared vocabulary lives in the glossary (`cmk:glossary`). diff --git a/docs/guides/README.md b/docs/guides/README.md index e1002e7..973801d 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -13,6 +13,12 @@ thing in this repository. [`../design/`](../design/); how to operate it belongs in [`../runbooks/`](../runbooks/). +## Index + +| Guide | When | +|---|---| +| [`on-ramps.md`](./on-ramps.md) | Unsure which `cmk:*` skill starts the situation | + ## When to read When you know what you need to do and want the established way to do it. diff --git a/docs/guides/on-ramps.md b/docs/guides/on-ramps.md new file mode 100644 index 0000000..9dbda6e --- /dev/null +++ b/docs/guides/on-ramps.md @@ -0,0 +1,31 @@ +# On-ramps + +**One home** for which `cmk:*` skill starts a situation. Root agent instructions +point here; they do not restate this table. + +| Situation | Start here | +|---|---| +| Brand-new / adopt / verify repo facets | `cmk:repo-setup` | +| Docs tree missing or drifted | `cmk:docs` | +| Save / draft product requirements; close package; AC + guards | `cmk:requirements` | +| How to build it (mechanism, architecture) | `cmk:design` | +| Record a hard-to-reverse decision | `cmk:adr` | +| Lock a term / vocabulary drift | `cmk:glossary` | +| Capture a gotcha | `cmk:learn` → promote with `cmk:rule` when it must be enforced | +| AI navigation map under `docs/ai/` | `cmk:codebase-docs` | +| Uncertain body of work → issue set | `cmk:discover-efforts` | +| Start / pick up a tracker issue | `cmk:delivery-intake` (or `cmk:delivery-pipeline` end-to-end) | +| Spec + plan for a ticket | `cmk:delivery-spec-plan` | +| Review diff / PR | `cmk:delivery-review` | +| Open PR / close ticket with evidence | `cmk:delivery-ship` | +| Handoff to another agent | `cmk:delivery-handoff` | +| Vendor skills / sync upstream | `cmk:agent-vendors` / `cmk:sync` | +| CI / local stack / MCP / toolchain alone | matching setup facet (`cmk:cicd`, `cmk:local-stack`, …) | + +Rules of thumb: + +> Never draft `docs/requirements/` from a bare label — close package first (`cmk:requirements`). + +> State **scope band** before implement; meet **docs-ready** (`cmk:delivery-workflow`). + +> When two skills both seem to apply, the delivery / process skill wins; it will call the docs skill. diff --git a/docs/reports/2026-08-28-author-skills-wording-pass.md b/docs/reports/2026-08-28-author-skills-wording-pass.md new file mode 100644 index 0000000..db4d892 --- /dev/null +++ b/docs/reports/2026-08-28-author-skills-wording-pass.md @@ -0,0 +1,47 @@ +# 2026-08-28 — author-skills wording & quality pass (CMK skills) + +Immutable point-in-time record of the pack-wide remediation against +`author-skills` (Ship checklist + Vocabulary + Influence). + +## Scope + +All 34 skills under `skills/`, on branch `upgrade/cmk-standard-ceremony`. +Subagent model roster: **grok-4.5 only**. + +## What landed + +1. **skill-lint green** — fixed oversized `delivery-pipeline` / + `delivery-review` / `delivery-spec-plan`; fixed dangling + `delivery-pipeline` attribution of `scope-band.md` (owned by + `delivery-workflow`); extracted review lenses to + `skills/delivery-review/references/lenses.md`. +2. **Description house form** — 33 model-invocable skills now open with + `Use when…` (was `This skill should be used when…`). `cmk:interpret` + remains one plain human-facing line (`disable-model-invocation: true`). + Trimmed outcome-heavy descriptions on `requirements`, `delivery-simplify`, + `delivery-spec-plan`, `repo-setup`. Documented the opener in + `docs/ai/skills/conventions.md`. +3. **Reference TOC** — `## Contents` added to 12 refs over ~100 lines + (cicd ×3, delivery-pipeline ×2, discover-efforts, docs scaffold-manifest, + local-stack ×2, requirements ×2, toolchain). +4. **Hierarchy** — `codebase-docs` slimmed to pointers + + `references/{bootstrap,update,doc-shape,working-example,failure-modes}`; + `rule` Audit/Gate moved to `references/audit.md` + `references/gate.md`. +5. **Gate wording + evidence (priority three)** — RED baselines on grok-4.5 + failed without the skill for `delivery-ship`, `delivery-review`, + `sui-sdk`; GREEN wording added Red Flags / rationalization rows named + from those failures; `TESTS.md` recorded under each skill. + +## Explicitly still open + +- Most skills still lack `TESTS.md` / `eval.json` (Iron Law evidence). +- Pack-wide verb-first renaming (`design` → verb, etc.) not done — topic + names remain CMK packaging convention. +- Full RED→GREEN for every gate skill beyond the three priority ones. +- Description trigger micro-tests not re-run pack-wide after the opener + rewrite (mechanical opener change; spot-checked via existing + `requirements` routing notes + gate GREEN runs). + +## Lint + +`./scripts/skill-lint.sh` — OK after this pass. diff --git a/skills/adr/SKILL.md b/skills/adr/SKILL.md index ec1b0d8..f786af6 100644 --- a/skills/adr/SKILL.md +++ b/skills/adr/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:adr -description: This skill should be used when the user asks to "record this decision", "we decided to use X over Y", "document why we chose this approach", "record an ADR", "update ADR-0003", or needs to create or update architecture decision records for system-level technical choices like choosing a database, communication protocol, or infrastructure pattern. -version: 0.3.1 +description: Use when the user asks to "record this decision", "we decided to use X over Y", "document why we chose this approach", "record an ADR", "update ADR-0003", or needs to create or update architecture decision records for system-level technical choices like choosing a database, communication protocol, or infrastructure pattern. +version: 0.3.2 --- # ADR diff --git a/skills/agent-instructions/SKILL.md b/skills/agent-instructions/SKILL.md index ad40d7e..2ec2b22 100644 --- a/skills/agent-instructions/SKILL.md +++ b/skills/agent-instructions/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:agent-instructions -description: This skill should be used when the user asks to "set up CLAUDE.md", "set up AGENTS.md", "agent instructions", "add engineering rules", "make the instructions thinner", or needs to establish or maintain a thin, multi-vendor root instruction file backed by on-demand engineering rules under docs/rules/. -version: 0.2.2 +description: Use when the user asks to "set up CLAUDE.md", "set up AGENTS.md", "agent instructions", "add engineering rules", "make the instructions thinner", or needs to establish or maintain a thin, multi-vendor root instruction file backed by on-demand engineering rules under docs/rules/. +version: 0.3.2 --- # Agent Instructions @@ -99,3 +99,6 @@ Report-only — never mutate: still referenced from `CLAUDE.md`. - Every conditional pointer in `CLAUDE.md` resolves to a file that exists. - The `.local/tmp/` scratch line is present in `CLAUDE.md`. +- If `CLAUDE.md` points at `docs/guides/on-ramps.md`, that file exists (Init/ + Update may seed it from the kit's `docs/guides/on-ramps.md`; Verify only + reports). diff --git a/skills/agent-instructions/references/claude-md-template.md b/skills/agent-instructions/references/claude-md-template.md index 1acce48..d6730cd 100644 --- a/skills/agent-instructions/references/claude-md-template.md +++ b/skills/agent-instructions/references/claude-md-template.md @@ -51,6 +51,9 @@ any row above whose file was not seeded] Start at `docs/README.md` for how the rest of the documentation tree is organized and when to read each part of it. +When the entry skill is unclear, read `docs/guides/on-ramps.md` — one table +from situation → `cmk:*` skill. Do not invent a second router. + ## Scratch Agent scratch and temporary files go under `.local/tmp/`, never a system diff --git a/skills/agent-vendors/SKILL.md b/skills/agent-vendors/SKILL.md index 18abc95..7482083 100644 --- a/skills/agent-vendors/SKILL.md +++ b/skills/agent-vendors/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:agent-vendors -description: This skill should be used when the user asks to "vendor the kit's skills into this repo", "set up agent adapters", "add a coding-agent vendor", "wire skills for Claude Code / Codex / OpenCode / Grok Build / Cursor", or whenever a repo needs one canonical skill set discoverable by multiple coding agents. -version: 0.2.0 +description: Use when the user asks to "vendor the kit's skills into this repo", "set up agent adapters", "add a coding-agent vendor", "wire skills for Claude Code / Codex / OpenCode / Grok Build / Cursor", or whenever a repo needs one canonical skill set discoverable by multiple coding agents. +version: 0.2.1 --- # Agent Vendors diff --git a/skills/cicd/SKILL.md b/skills/cicd/SKILL.md index 8343945..fd8cb59 100644 --- a/skills/cicd/SKILL.md +++ b/skills/cicd/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:cicd -description: This skill should be used when the user asks to "set up CI", "speed up CI", "add a deploy workflow", "structure GitHub Actions", "self-hosted runners", "run CI locally", "JIT runner", "protect the main branch", or needs to structure CI, deployment, and policy automation as composable host-runnable scripts that GitHub Actions only automates. -version: 0.3.3 +description: Use when the user asks to "set up CI", "speed up CI", "add a deploy workflow", "structure GitHub Actions", "self-hosted runners", "run CI locally", "JIT runner", "protect the main branch", or needs to structure CI, deployment, and policy automation as composable host-runnable scripts that GitHub Actions only automates. +version: 0.3.4 --- # CI/CD diff --git a/skills/cicd/references/ci-structure.md b/skills/cicd/references/ci-structure.md index bb386ed..ca00a76 100644 --- a/skills/cicd/references/ci-structure.md +++ b/skills/cicd/references/ci-structure.md @@ -3,6 +3,15 @@ Mechanics for the single validation pipeline in `SKILL.md`'s CI structure facet. +## Contents + +- [One pipeline, many gated area jobs](#one-pipeline-many-gated-area-jobs) +- [Speed structure](#speed-structure) +- [Tiered runners are configuration, not a workflow edit](#tiered-runners-are-configuration-not-a-workflow-edit) +- [Cold-cache isolation is a trap, not a given](#cold-cache-isolation-is-a-trap-not-a-given) +- [CI self-contract tests](#ci-self-contract-tests) +- [Label-gated diagnostic jobs](#label-gated-diagnostic-jobs) + ## One pipeline, many gated area jobs A single workflow validates every push and PR. A `changes` job runs first, diff --git a/skills/cicd/references/deploy-and-release.md b/skills/cicd/references/deploy-and-release.md index 35fee90..6c9de02 100644 --- a/skills/cicd/references/deploy-and-release.md +++ b/skills/cicd/references/deploy-and-release.md @@ -3,6 +3,14 @@ Mechanics for the deploy-and-release facet in `SKILL.md`, and the GitHub ↔ IaC contract it specifies on behalf of `cmk:infra`. +## Contents + +- [Validation and deployment are separate workflows](#validation-and-deployment-are-separate-workflows) +- [Dispatch-against-ref, not branch-triggered promotion](#dispatch-against-ref-not-branch-triggered-promotion) +- [The GitHub ↔ IaC contract, specified](#the-github-iac-contract-specified) +- [Deploy orchestrator plus legs](#deploy-orchestrator-plus-legs) +- [Release integrity](#release-integrity) + ## Validation and deployment are separate workflows The CI workflow validates; it never deploys. Each deployable thing gets its diff --git a/skills/cicd/references/host-runnable.md b/skills/cicd/references/host-runnable.md index 6471d91..8f77f99 100644 --- a/skills/cicd/references/host-runnable.md +++ b/skills/cicd/references/host-runnable.md @@ -3,6 +3,16 @@ Mechanics for treating CI, deploy, and operator steps as scripts that any host can run. The YAML (or other remote CI file) only composes them. +## Contents + +- [Scripts are the workflow](#scripts-are-the-workflow) +- [Language](#language) +- [Composer-contract drift](#composer-contract-drift) +- [Mutate gate](#mutate-gate) +- [Host matrix](#host-matrix) +- [Debug on the host that ran the step](#debug-on-the-host-that-ran-the-step) +- [When a remote job fails](#when-a-remote-job-fails) + ## Scripts are the workflow Each step is independently invocable on a machine. A step that only diff --git a/skills/codebase-docs/SKILL.md b/skills/codebase-docs/SKILL.md index b918a91..6bc62ad 100644 --- a/skills/codebase-docs/SKILL.md +++ b/skills/codebase-docs/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:codebase-docs -description: Generate or update hierarchical, AI-navigable documentation for a codebase under `docs/ai/`. Use whenever the user asks to "document the codebase for AI", "bootstrap AI docs", "generate codebase map", "set up AI navigation docs", "update AI docs", "refresh docs after change", or mentions building progressive-disclosure docs so an AI can find the right source files quickly. Produces a tree of concise docs that *point to* code rather than duplicate it. Use even when the user only says "document this repo" without specifying the structure. -version: 0.1.1 +description: Use when the user asks to "document the codebase for AI", "bootstrap AI docs", "generate codebase map", "set up AI navigation docs", "update AI docs", "refresh docs after change", or mentions building progressive-disclosure docs so an AI can find the right source files quickly. Produces a tree of concise docs that *point to* code rather than duplicate it. Use even when the user only says "document this repo" without specifying the structure. +version: 0.1.3 --- # Codebase Docs for AI Navigation @@ -19,154 +19,14 @@ Two explicit entry points — never run on autopilot: If the mode is ambiguous, ask. -## Output location and shape +## References -``` -docs/ai/ -├── README.md # root: whole-repo overview + link menu -├── / -│ ├── README.md # area overview + link menu to topics/sub-areas -│ ├── .md # a leaf doc for a bounded concept -│ └── / -│ ├── README.md -│ └── .md -``` +Bootstrap? Read `references/bootstrap-workflow.md`. +Update? Read `references/update-workflow.md`. +Doc shape, principles, split heuristic, and what not to document? Read `references/doc-shape.md`. +Want a concrete sketch? Read `references/working-example.md`. +Failure modes? Read `references/failure-modes.md`. -- Folders with their own `README.md` act as branch nodes; leaves are plain `.md` files named after the topic (`session-loop.md`, not `00-session-loop.md` — no numeric prefixes). -- A branch's `README.md` lists children as a flat menu of one-liners with relative links. It does **not** re-explain what children cover. -- Keep folder names lowercase-kebab, matching the vocabulary the code already uses. Whatever the codebase calls a unit — package, module, service, app, crate, workspace — mirror that name. If the source folder is `billing-service/`, the doc folder is `billing-service/`, not `billing/` or `payments/`. +## Final check -## What goes in one doc - -Every doc answers three questions, in order, and then stops: - -1. **What is this?** — one or two sentences, plain language. -2. **Why does it exist / what problem does it solve?** — only if non-obvious. Skip for things a reader can infer from the name. -3. **Where is it?** — file paths with a symbol hint (function, struct, class, or a grep-able phrase) so AI can jump directly. Use markdown bullets, not prose. - -For a branch doc (`README.md`), replace (3) with a link menu to children. - -If implementation approach matters (an unusual pattern, a deliberate trade-off, an invariant that isn't obvious from the code), add a short "Approach" section — a paragraph or two — and still point to the code for the actual details. - -### Code reference format - -Point to files with enough of a hint to let AI skip straight to the right lines. The pattern is `path → symbol-or-grep-hint`: - -``` -- One-line description of what this thing does. - → `` — `` -``` - -Use a named symbol when one exists — function, class, struct, type, const, route, config key, whatever the language offers. Fall back to a short grep-able string from the code only if no named symbol covers it (e.g., a regex, a magic number, a CLI flag). Don't invent names — if you can't quickly find a hook, open the file and grab the real one. - -**Always write paths relative to the repo root**, not bare filenames. `apps/api/src/server.ts`, not just `server.ts`. A doc about a sub-folder still writes the full path from the repo root when it references a file, because the reader (an AI or a human `find`-ing) starts at the repo root, not inside the doc's folder. Bare filenames force a guess-the-path step that the skill exists to eliminate. The only exception: when every path in a tight list is in the same directory and you've just named that directory one line above, shortening is fine — but err toward being explicit. - -## Principles - -**Progressive disclosure.** A doc should be readable in ten seconds and tell the reader where to go for more. If you catch yourself explaining a sub-concept in depth, that sub-concept probably deserves its own doc — link to it instead. - -**Don't duplicate the code.** No copy-pasted function bodies, no snippets longer than a couple of lines. If a reader needs the actual logic, they open the file. The doc's value is knowing *which* file. - -**Don't document the obvious.** Skip things whose purpose is clear from the name or from reading the first ten lines of the file. `src/main.rs: entry point` is noise. A non-obvious invariant ("this must run before `init_db` or migrations panic") is signal. - -**Coherence over splitting.** If a topic is naturally one story, keep it in one doc even if it runs a bit long. Only split when there's a genuinely bounded sub-concept *and* the parent is getting unwieldy — see the split heuristic below. - -**Match the code's vocabulary.** Use the same names the code uses (the folder-naming rule under "Output location and shape") — the doc's job is to be findable from the code's own terms, never through a more "descriptive" alias. - -## Split heuristic - -Split a topic into its own sub-doc when **both** are true: - -1. **Bounded** — the sub-topic has a clear boundary a reader could land on directly without needing the parent's context. -2. **Substantial** — it would take more than a few bullets or a short paragraph to cover, *or* the parent doc is pushing past ~100–150 lines and getting hard to skim. - -If only (1) holds and the sub-topic is a two-line bullet, leave it inline. If only (2) holds (the parent is long but the content is one continuous narrative), don't chop it artificially — rewrite for brevity first. - -Rule of thumb: a good branch doc is ~30–80 lines. A good leaf doc is ~20–120 lines. If a leaf is heading past 200, ask whether it's really one topic. - -## What NOT to document - -- Entry points whose role is obvious from the filename (`main.*`, `index.*`, `app.*`, `cmd/*/main.go`, etc.). -- Boilerplate: standard package manifests (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, `Gemfile`, etc.) and typical framework scaffolding. -- Anything already well-covered by a top-level `README.md` — link to it instead of restating. -- Generated code, vendored dependencies, lockfiles, migration files. -- Features that don't exist yet. Don't speculate. - -## Bootstrap workflow - -1. **Survey the repo.** Read the root `README.md`, any `CLAUDE.md` / `AGENTS.md`, the top-level directory layout, and whatever package/workspace manifest the stack uses (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, `Gemfile`, etc.) for declared workspace members or sub-packages. Identify the 3–8 major areas — apps, services, packages, modules, significant subsystems. Note anything the existing README already explains well — don't duplicate it. - -2. **Draft `docs/ai/README.md`.** One paragraph: what this repo is, what it does, who it's for. Then a link menu to the major areas, each a single sentence. Nothing else. - -3. **For each area, decide branch vs. leaf.** If the area has ≥2 substantial sub-topics, make it a folder with its own `README.md`. If it's one coherent thing, make it a single `.md` at the parent level. - -4. **Drill down recursively.** For each branch, identify its sub-topics by skimming the code (directory structure, module boundaries, key types/functions). Apply the split heuristic. Stop recursing when a sub-topic is either (a) obvious from its name + file path, or (b) small enough to fit as a bullet in its parent. - -5. **Write leaf docs.** For each, read enough of the actual code to write a truthful what/why/where. Don't paraphrase from guesswork — open the file. Grab the real symbol names. - -6. **Verify links.** All relative links resolve; all file paths exist; all symbol hints are real (grep for them). Broken references are worse than no reference. - -7. **Sanity-check length.** Every doc under the length guidance above. Any doc that runs long, either split or trim. - -## Update workflow - -1. **Locate affected nodes.** Given the change (new feature, renamed module, deleted subsystem), find every doc that mentions it. `grep -r` on the old name is usually enough. - -2. **Edit in place.** Preserve the existing structure; don't rewrite docs that still describe reality. Update file-path hints, symbol names, and one-line summaries as needed. - -3. **Add new nodes if genuinely new.** A new area gets a new folder + `README.md`; a new topic inside an existing area gets a new leaf and a line in the parent's menu. - -4. **Remove stale nodes.** If a subsystem is deleted, delete its doc and remove it from the parent's menu. Don't leave tombstones. - -5. **Re-verify links and symbols** for every edited file. - -## Working example (sketch) - -The shape is the same regardless of stack — the tree under "Output location and shape" above, with folder names mirroring whatever the codebase calls its parts. Concrete shape examples for different stacks: - -- **TS monorepo (`apps/`, `packages/`)** — top-level menu mirrors workspace members: `docs/ai/apps//`, `docs/ai/packages//`. -- **Rust workspace (`crates/`)** — top-level menu mirrors crate names: `docs/ai//`. -- **Python project (`src//`)** — menu mirrors top-level modules: `docs/ai//`. -- **Go services (`cmd/`, `internal/`, `pkg/`)** — menu mirrors services/packages: `docs/ai//`, `docs/ai/internal//`. -- **Single-app repo with no clear sub-packages** — group by domain concept (e.g. `auth/`, `billing/`, `ingest/`) and let the leaves point at files anywhere in `src/`. - -A leaf doc — same structure regardless of language — might read in full: - -```markdown -# Session loop - -## What -The main driver of an interactive session. Each iteration reads one user -input, dispatches to the worker, streams output back, and returns to idle. -Keeps the input handler responsive across long-running calls. - -## Approach -The loop is persistent rather than per-turn: a single task owns the input -channel and the output renderer for the whole session. Earlier versions -re-created the task per turn, which dropped events during transitions. -See commit 88af577 for the fix. - -## Where -- Entry: `` — `` -- Input source: `` — `` -- Output renderer: `` — `` -``` - -That's the whole doc — ~15 lines, three clear hooks into the code, no copied source. Replace the placeholders with real paths and real symbol names from whatever language the project uses. - -## Common failure modes - -- **Paraphrased code.** If the doc is explaining control flow line-by-line, delete that and just point to the function. -- **Essay-style prose.** Bullets and short paragraphs beat flowing prose for skim-reading. -- **Phantom references.** Never invent a function or file name. If you're unsure, open the file and check. -- **Over- or under-splitting.** Apply the split heuristic; both directions are covered there. -- **Documenting aspirations.** Only describe what's in the code now. - -## Final check before finishing - -- [ ] Root `docs/ai/README.md` exists and links to every top-level area. -- [ ] Every branch `README.md` has a link menu, not a wall of text. -- [ ] Every leaf has what / (why, if non-obvious) / where. -- [ ] Every `→` reference points to a real file and a real symbol (spot-check a few with grep). -- [ ] No doc is over the length guidance without a reason. -- [ ] No duplicated content between parent and child. +Before finishing, run the checklist in `references/failure-modes.md`. diff --git a/skills/codebase-docs/references/bootstrap-workflow.md b/skills/codebase-docs/references/bootstrap-workflow.md new file mode 100644 index 0000000..bf98d27 --- /dev/null +++ b/skills/codebase-docs/references/bootstrap-workflow.md @@ -0,0 +1,15 @@ +# Bootstrap workflow + +1. **Survey the repo.** Read the root `README.md`, any `CLAUDE.md` / `AGENTS.md`, the top-level directory layout, and whatever package/workspace manifest the stack uses (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, `Gemfile`, etc.) for declared workspace members or sub-packages. Identify the 3–8 major areas — apps, services, packages, modules, significant subsystems. Note anything the existing README already explains well — don't duplicate it. + +2. **Draft `docs/ai/README.md`.** One paragraph: what this repo is, what it does, who it's for. Then a link menu to the major areas, each a single sentence. Nothing else. + +3. **For each area, decide branch vs. leaf.** If the area has ≥2 substantial sub-topics, make it a folder with its own `README.md`. If it's one coherent thing, make it a single `.md` at the parent level. + +4. **Drill down recursively.** For each branch, identify its sub-topics by skimming the code (directory structure, module boundaries, key types/functions). Apply the split heuristic in `references/doc-shape.md`. Stop recursing when a sub-topic is either (a) obvious from its name + file path, or (b) small enough to fit as a bullet in its parent. + +5. **Write leaf docs.** For each, read enough of the actual code to write a truthful what/why/where. Don't paraphrase from guesswork — open the file. Grab the real symbol names. + +6. **Verify links.** All relative links resolve; all file paths exist; all symbol hints are real (grep for them). Broken references are worse than no reference. + +7. **Sanity-check length.** Every doc under the length contracts in `references/doc-shape.md`. Any doc that runs long, either split or trim. diff --git a/skills/codebase-docs/references/doc-shape.md b/skills/codebase-docs/references/doc-shape.md new file mode 100644 index 0000000..b72ed8d --- /dev/null +++ b/skills/codebase-docs/references/doc-shape.md @@ -0,0 +1,74 @@ +# Doc shape + +## Output location and shape + +``` +docs/ai/ +├── README.md # root: whole-repo overview + link menu +├── / +│ ├── README.md # area overview + link menu to topics/sub-areas +│ ├── .md # a leaf doc for a bounded concept +│ └── / +│ ├── README.md +│ └── .md +``` + +- Folders with their own `README.md` act as branch nodes; leaves are plain `.md` files named after the topic (`session-loop.md`, not `00-session-loop.md` — no numeric prefixes). +- A branch's `README.md` lists children as a flat menu of one-liners with relative links. It does **not** re-explain what children cover. +- Keep folder names lowercase-kebab, matching the vocabulary the code already uses. Whatever the codebase calls a unit — package, module, service, app, crate, workspace — mirror that name. If the source folder is `billing-service/`, the doc folder is `billing-service/`, not `billing/` or `payments/`. + +## What goes in one doc + +Every doc answers three questions, in order, and then stops: + +1. **What is this?** — one or two sentences, plain language. +2. **Why does it exist / what problem does it solve?** — only if non-obvious. Skip for things a reader can infer from the name. +3. **Where is it?** — file paths with a symbol hint (function, struct, class, or a grep-able phrase) so AI can jump directly. Use markdown bullets, not prose. + +For a branch doc (`README.md`), replace (3) with a link menu to children. + +If implementation approach matters (an unusual pattern, a deliberate trade-off, an invariant that isn't obvious from the code), add a short "Approach" section — a paragraph or two — and still point to the code for the actual details. + +### Code reference format + +Point to files with enough of a hint to let AI skip straight to the right lines. The pattern is `path → symbol-or-grep-hint`: + +``` +- One-line description of what this thing does. + → `` — `` +``` + +Use a named symbol when one exists — function, class, struct, type, const, route, config key, whatever the language offers. Fall back to a short grep-able string from the code only if no named symbol covers it (e.g., a regex, a magic number, a CLI flag). Don't invent names — if you can't quickly find a hook, open the file and grab the real one. + +**Always write paths relative to the repo root**, not bare filenames. `apps/api/src/server.ts`, not just `server.ts`. A doc about a sub-folder still writes the full path from the repo root when it references a file, because the reader (an AI or a human `find`-ing) starts at the repo root, not inside the doc's folder. Bare filenames force a guess-the-path step that the skill exists to eliminate. The only exception: when every path in a tight list is in the same directory and you've just named that directory one line above, shortening is fine — but err toward being explicit. + +## Principles + +**Progressive disclosure.** A doc should be readable in ten seconds and tell the reader where to go for more. If you catch yourself explaining a sub-concept in depth, apply the split heuristic: when both Bounded and Substantial hold, give it its own doc and link to it. + +**Don't duplicate the code.** No copy-pasted function bodies, no snippets longer than a couple of lines. If a reader needs the actual logic, they open the file. The doc's value is knowing *which* file. + +**Don't document the obvious.** Skip things whose purpose is clear from the name or from reading the first ten lines of the file. `src/main.rs: entry point` is noise. A non-obvious invariant ("this must run before `init_db` or migrations panic") is signal. + +**Coherence over splitting.** If a topic is naturally one story, keep it in one doc even if it runs a bit long. Only split when there's a genuinely bounded sub-concept *and* the parent is getting unwieldy — see the split heuristic below. + +**Match the code's vocabulary.** Use the same names the code uses (the folder-naming rule under "Output location and shape") — the doc's job is to be findable from the code's own terms, never through a more "descriptive" alias. + +## Split heuristic + +Split a topic into its own sub-doc when **both** are true: + +1. **Bounded** — the sub-topic has a clear boundary a reader could land on directly without needing the parent's context. +2. **Substantial** — it would take more than a few bullets or a short paragraph to cover, *or* the parent doc is pushing past ~100–150 lines and getting hard to skim. + +If only (1) holds and the sub-topic is a two-line bullet, leave it inline. If only (2) holds (the parent is long but the content is one continuous narrative), don't chop it artificially — rewrite for brevity first. + +**Length contracts:** branch docs stay ~30–80 lines; leaf docs stay ~20–120 lines. A leaf past 200 lines is not one topic — split per the heuristic or trim. + +## What NOT to document + +- Entry points whose role is obvious from the filename (`main.*`, `index.*`, `app.*`, `cmd/*/main.go`, etc.). +- Boilerplate: standard package manifests (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`, `Gemfile`, etc.) and typical framework scaffolding. +- Anything already well-covered by a top-level `README.md` — link to it instead of restating. +- Generated code, vendored dependencies, lockfiles, migration files. +- Features that don't exist yet. Don't speculate. diff --git a/skills/codebase-docs/references/failure-modes.md b/skills/codebase-docs/references/failure-modes.md new file mode 100644 index 0000000..4757417 --- /dev/null +++ b/skills/codebase-docs/references/failure-modes.md @@ -0,0 +1,16 @@ +# Common failure modes + +- **Paraphrased code.** If the doc is explaining control flow line-by-line, delete that and just point to the function. +- **Essay-style prose.** Bullets and short paragraphs beat flowing prose for skim-reading. +- **Phantom references.** Never invent a function or file name. If you're unsure, open the file and check. +- **Over- or under-splitting.** Apply the split heuristic in `references/doc-shape.md`; both directions are covered there. +- **Documenting aspirations.** Only describe what's in the code now. + +## Final check before finishing + +- [ ] Root `docs/ai/README.md` exists and links to every top-level area. +- [ ] Every branch `README.md` has a link menu, not a wall of text. +- [ ] Every leaf has what / (why, if non-obvious) / where. +- [ ] Every `→` reference points to a real file and a real symbol (spot-check a few with grep). +- [ ] No doc is over the length contracts without a reason. +- [ ] No duplicated content between parent and child. diff --git a/skills/codebase-docs/references/update-workflow.md b/skills/codebase-docs/references/update-workflow.md new file mode 100644 index 0000000..eb976c7 --- /dev/null +++ b/skills/codebase-docs/references/update-workflow.md @@ -0,0 +1,11 @@ +# Update workflow + +1. **Locate affected nodes.** Given the change (new feature, renamed module, deleted subsystem), find every doc that mentions it. `grep -r` on the old name is usually enough. + +2. **Edit in place.** Preserve the existing structure; don't rewrite docs that still describe reality. Update file-path hints, symbol names, and one-line summaries as needed. + +3. **Add new nodes if genuinely new.** A new area gets a new folder + `README.md`; a new topic inside an existing area gets a new leaf and a line in the parent's menu. + +4. **Remove stale nodes.** If a subsystem is deleted, delete its doc and remove it from the parent's menu. Don't leave tombstones. + +5. **Re-verify links and symbols** for every edited file. diff --git a/skills/codebase-docs/references/working-example.md b/skills/codebase-docs/references/working-example.md new file mode 100644 index 0000000..b8bd384 --- /dev/null +++ b/skills/codebase-docs/references/working-example.md @@ -0,0 +1,33 @@ +# Working example (sketch) + +The shape is the same regardless of stack — the tree under "Output location and shape" in `references/doc-shape.md`, with folder names mirroring whatever the codebase calls its parts. Concrete shape examples for different stacks: + +- **TS monorepo (`apps/`, `packages/`)** — top-level menu mirrors workspace members: `docs/ai/apps//`, `docs/ai/packages//`. +- **Rust workspace (`crates/`)** — top-level menu mirrors crate names: `docs/ai//`. +- **Python project (`src//`)** — menu mirrors top-level modules: `docs/ai//`. +- **Go services (`cmd/`, `internal/`, `pkg/`)** — menu mirrors services/packages: `docs/ai//`, `docs/ai/internal//`. +- **Single-app repo with no clear sub-packages** — group by domain concept (e.g. `auth/`, `billing/`, `ingest/`) and let the leaves point at files anywhere in `src/`. + +A leaf doc — same structure regardless of language — might read in full: + +```markdown +# Session loop + +## What +The main driver of an interactive session. Each iteration reads one user +input, dispatches to the worker, streams output back, and returns to idle. +Keeps the input handler responsive across long-running calls. + +## Approach +The loop is persistent rather than per-turn: a single task owns the input +channel and the output renderer for the whole session. Earlier versions +re-created the task per turn, which dropped events during transitions. +See commit 88af577 for the fix. + +## Where +- Entry: `` — `` +- Input source: `` — `` +- Output renderer: `` — `` +``` + +That's the whole doc — ~15 lines, three clear hooks into the code, no copied source. Replace the placeholders with real paths and real symbol names from whatever language the project uses. diff --git a/skills/delivery-handoff/SKILL.md b/skills/delivery-handoff/SKILL.md index 5cf1a77..82953ed 100644 --- a/skills/delivery-handoff/SKILL.md +++ b/skills/delivery-handoff/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-handoff -description: This skill should be used when the user asks for "a handoff prompt", "a prompt for codex/grok/claude", "something I can paste into another agent", or wants to continue tracked work in a different tool — and at any phase boundary of the cmk:delivery-pipeline skill when the operator prefers a different agent for the next phase. -version: 0.2.1 +description: Use when the user asks for "a handoff prompt", "a prompt for codex/grok/claude", "something I can paste into another agent", or wants to continue tracked work in a different tool — and at any phase boundary of the cmk:delivery-pipeline skill when the operator prefers a different agent for the next phase. +version: 0.2.2 --- # Delivery Handoff diff --git a/skills/delivery-intake/SKILL.md b/skills/delivery-intake/SKILL.md index a026a82..46b6c24 100644 --- a/skills/delivery-intake/SKILL.md +++ b/skills/delivery-intake/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-intake -description: This skill should be used when the user asks to "start work on TICKET-123", "pick up this issue", "get the context for this ticket", or begins any tracked work — and as phase 1 of the cmk:delivery-pipeline skill. -version: 0.1.0 +description: Use when the user asks to "start work on TICKET-123", "pick up this issue", "get the context for this ticket", "intake this issue", or begins any tracked work — and as phase 1 of the cmk:delivery-pipeline skill. Produces a context brief, branch/worktree, stated scope band, and docs-ready check (routing to `cmk:requirements` when the band requires it). +version: 0.2.2 --- # Delivery Intake @@ -66,6 +66,16 @@ If reading reveals the issue's scope is stale (already partly delivered, superseded, or split), update it and its relations now, before building on a wrong picture. +**Scope band + docs-ready.** State the band out loud, record it on the issue, +and check docs-ready per `cmk:delivery-workflow`'s scope-band reference. If +docs-ready is false, REQUIRED SUB-SKILL: use `cmk:requirements` before phase 3 +(or record an explicit exemption with owner). Do not restate the band table +here. + +**Defect path.** When the issue is unexpected broken behavior (bug, regression, +incident leftover), capture reproduction and suspected cause on the issue (or +block on investigation) before planning a fix. + ## 3. Branch and worktree - Use the tracker's suggested branch name, if it generates one; otherwise the @@ -93,7 +103,9 @@ never committed: ``` # TICKET-123 context brief Outcome: -Acceptance criteria: +Scope band: +Docs-ready: +Acceptance criteria: Constraints & invariants: Prior art & patterns: Scope boundaries: diff --git a/skills/delivery-pipeline/SKILL.md b/skills/delivery-pipeline/SKILL.md index 35ae9e8..135ccce 100644 --- a/skills/delivery-pipeline/SKILL.md +++ b/skills/delivery-pipeline/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-pipeline -description: This skill should be used when the user asks to "work on", "deliver", "tackle", "pick up", or "implement" a tracker issue (TICKET-123), a list of issues, or a body of tracked work expected to finish without supervision — even if they never say "pipeline". Also use when handed a cluster of related issues, or a single issue whose surrounding cluster should be derived from tracker dependencies, expecting dependency-aware sequencing across worktrees. -version: 0.4.2 +description: Use when the user asks to "work on", "deliver", "tackle", "pick up", or "implement" a tracker issue (TICKET-123), a list of issues, or a body of tracked work expected to finish without supervision — even if they never say "pipeline". Also use when handed a cluster of related issues, or a single issue whose surrounding cluster should be derived from tracker dependencies. Produces reviewable PR(s), an up-to-date tracker graph, and a completion report — only after docs-ready for the stated scope band. +version: 0.5.3 --- # Delivery Pipeline @@ -24,47 +24,37 @@ CMK owns the lifecycle. Superpowers executes inside it. The division: Before acting, read: -1. `cmk:delivery-workflow` — the tracking contract. Every phase operates - inside it. +1. `cmk:delivery-workflow`'s `references/scope-band.md` — tracking contract, + **scope band**, **docs-ready**, and the implement docs gate. 2. `references/engineering-principles.md` — autonomy, production readiness, and the delegation contract. -3. Your runtime's binding for mechanics only (see `cmk:delivery-workflow`'s - `references/vendor-bindings.md`). A binding supplies mechanics; it never - changes phase order, gates, evidence, or acceptance. +3. Your runtime's binding for mechanics only (`cmk:delivery-workflow`'s + `references/vendor-bindings.md`). Bindings supply mechanics; they never + change phase order, gates, evidence, or acceptance. ## Working with superpowers -Superpowers skills are written for a human-supervised session. Two rules -adapt them everywhere in this pipeline, including skills added later: - -1. **Human gates are suppressed.** Any point where a skill stops to ask the - operator — consent, approval, "which approach?", a typed confirmation — - does not apply: decide it and record the decision and rationale on the - durable surface the phase already requires (spec, review record, PR - description, or the owning tracker issue). A question that genuinely - cannot be decided safely is a recorded blocker - (`references/engineering-principles.md` § Autonomy). Four decisions keep - a named CMK owner instead: a plan conflict is a review finding - dispositioned under `cmk:delivery-review`; review feedback colliding - with a prior decision is that skill's call; branch integration is not a - menu, since phase 5 opens a PR against a canonical branch; and starting - on the default branch is not a consent question, since intake already - placed the run on its own branch. -2. **A skill returns at its boundary** — it does not advance the phase and - does not delete a workspace. `superpowers:writing-plans` ends when the - plan is written without invoking an execution engine; - `superpowers:subagent-driven-development` ends at the last task's ledger - line without deleting its workspace (phases 4 and 5 read it as evidence) +Superpowers skills assume a human-supervised session. Adapt them everywhere: + +1. **Human gates are suppressed.** Consent, approval, "which approach?", or + typed confirmation do not apply — decide and record on the durable + surface the phase already requires (spec, review record, PR, or tracker + issue). A question that cannot be decided safely is a recorded blocker + (`references/engineering-principles.md` § Autonomy). Four calls keep a + named CMK owner: plan conflict → `cmk:delivery-review`; colliding review + feedback → that skill; branch integration → phase 5 opens a PR against a + canonical branch; starting on default → intake already placed the run. +2. **A skill returns at its boundary** — it does not advance the phase or + delete a workspace. `superpowers:writing-plans` ends when the plan is + written; `superpowers:subagent-driven-development` ends at the last + task's ledger line without deleting its workspace (phases 4–5 read it) or chaining into `superpowers:finishing-a-development-branch`; - `superpowers:using-git-worktrees` reports the existing worktree rather - than creating a second one. + `superpowers:using-git-worktrees` reports the existing worktree. -The issue's worktree and branch are intake's to create and nobody's to -remove — the durable workspace for every relay agent; a skill may create -its own scratch workspace and phase 5 retires it once its evidence is -durable. Specs and plans go to git-ignored scratch and are never committed; -durable conclusions reach `docs/design/`, `docs/decisions/`, the tracker, -and the PR. +Intake creates the issue worktree/branch; nobody removes it. A skill may +create scratch workspace; phase 5 retires it once evidence is durable. +Specs/plans stay git-ignored; durable conclusions reach `docs/design/`, +`docs/decisions/`, the tracker, and the PR. ## Phase 0: run notes @@ -93,6 +83,11 @@ file directly. Phases are checkpoints, not ceremonies: a one-line config fix does not need a design spec, but it still needs intake, task proof, review, and ship. Scale phase depth to the change; never skip one outright. +**Before phase 3:** docs-ready for the stated scope band must hold — one home +is `cmk:delivery-workflow`'s scope-band reference (intake states the band). If +unmet, REQUIRED SUB-SKILL: use `cmk:requirements` during or right after intake / +phase 2; do not enter phase 3 while docs-ready is false. + Executing phase 3? Read `references/phase-3-execution.md`. Phase 3b? Read `references/phase-3b-simplify.md`. diff --git a/skills/delivery-pipeline/TESTS.md b/skills/delivery-pipeline/TESTS.md new file mode 100644 index 0000000..b4a3be0 --- /dev/null +++ b/skills/delivery-pipeline/TESTS.md @@ -0,0 +1,25 @@ +# cmk:delivery-pipeline — test evidence (v0.5.0) + +## Model roster + +| Model | Role | +|---|---| +| grok-4.5 | Primary | + +## Scenario + +TICKET-442 team billing dashboards; no `docs/requirements/`; user says skip requirements and implement after quick intake. + +## RED — v0.4.2 + +`INVOKES_CMK_REQUIREMENTS: no`, `STATES_SCOPE_BAND: no`, `SKIPS_TO_IMPLEMENT_WITHOUT_REQUIREMENTS_DOC: no` (refused skip but still did not require cmk:requirements). + +## GREEN — v0.5.0 + +`INVOKES_OR_REQUIRES_CMK_REQUIREMENTS_BEFORE_PHASE_3: yes`, `STATES_SCOPE_BAND: yes (feature)`, `SKIPS_TO_IMPLEMENT_WITHOUT_DOCS_READY: no`. + +## Wording pass v0.5.1 + +- Description: outcome noun (PR/tracker/report) instead of "Enforces…". +- Body: long Standard paragraph → short pointer to workflow scope-band + REQUIRED SUB-SKILL. +- Micro-test: gate still unmistakable after trim. diff --git a/skills/delivery-pipeline/references/engineering-principles.md b/skills/delivery-pipeline/references/engineering-principles.md index a066669..46188b6 100644 --- a/skills/delivery-pipeline/references/engineering-principles.md +++ b/skills/delivery-pipeline/references/engineering-principles.md @@ -6,6 +6,20 @@ automatically — do not restate its conventions here or in delegation prompts; this file holds only what is specific to running the pipeline autonomously. +## Contents + +- [Autonomy: decide, don't ask](#autonomy-decide-dont-ask) +- [The quality bar](#the-quality-bar) +- [Full-surface changes and deliberate compat](#full-surface-changes-and-deliberate-compat) +- [No shortcut: production-ready foundation](#no-shortcut-production-ready-foundation) +- [One code path across infra profiles](#one-code-path-across-infra-profiles) +- [Host-runnable composition](#host-runnable-composition) +- [Production readiness](#production-readiness) +- [Track record: explicit beats remembered](#track-record-explicit-beats-remembered) +- [Consistency across surfaces](#consistency-across-surfaces) +- [Parallelize with subagents — through the platform, with evidence](#parallelize-with-subagents--through-the-platform-with-evidence) +- [Proactivity: own the gap](#proactivity-own-the-gap) + ## Autonomy: decide, don't ask The human is not available during the run. Every spec question, plan diff --git a/skills/delivery-pipeline/references/worktree-wave-execution.md b/skills/delivery-pipeline/references/worktree-wave-execution.md index 1e85213..e7cf7ca 100644 --- a/skills/delivery-pipeline/references/worktree-wave-execution.md +++ b/skills/delivery-pipeline/references/worktree-wave-execution.md @@ -13,6 +13,17 @@ build state private by construction, and as a second effect give every task a private branch, which removes the commit contamination that forced path-scoped review packages. +## Contents + +- [Wave eligibility](#wave-eligibility) +- [Dispatch](#dispatch) +- [Join and cleanup](#join-and-cleanup) +- [Reconciliation between tasks](#reconciliation-between-tasks) +- [Shared state has one writer](#shared-state-has-one-writer) +- [Thrash detection](#thrash-detection) +- [Snapshots never ship](#snapshots-never-ship) +- [Runtime bindings](#runtime-bindings) + ## Wave eligibility Tasks may share a wave only when all three hold: diff --git a/skills/delivery-review/SKILL.md b/skills/delivery-review/SKILL.md index fb445e3..babec38 100644 --- a/skills/delivery-review/SKILL.md +++ b/skills/delivery-review/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-review -description: This skill should be used when the user asks to "review my changes", "review this PR", "take a look at this diff", or "is this ready to ship" — before shipping tracked work (phase 4 of cmk:delivery-pipeline) or standalone against any pull request or local diff. -version: 0.1.3 +description: Use when the user asks to "review my changes", "review this PR", "take a look at this diff", or "is this ready to ship" — before shipping tracked work (phase 4 of cmk:delivery-pipeline) or standalone against any pull request or local diff. Produces a depth-disclosed verdict with evidence-backed findings dispositioned against acceptance criteria (citing requirement IDs when present). +version: 0.2.4 --- # Delivery Review @@ -69,34 +69,9 @@ a quiet default. ## The lenses -1. **Correctness** — does the code do what it claims? Logic, boundaries, - error paths, concurrency, resource lifecycle; would each new test fail - if the behavior regressed? -2. **Spec/design/requirements/AC compliance** — line by line against the - issue's *current* acceptance criteria, spec, design docs, and - requirements. Under-delivery against the issue's *intent* is a finding - even when a criterion's letter is met; a criterion checked in the - tracker with no proof reachable from the issue is a finding, and so is - one silently narrowed to match what got built rather than rescoped in - the open. -3. **Code quality** — repo conventions (`docs/rules/common/naming.md`, - the doc-comment bar, role-first layout per `cmk:project-layout`), - language idioms, layering, over- and under-engineering, test quality. -4. **Cross-surface consistency** — do code, doc comments, `docs/`, the - issue, and the PR text tell one story? Stale docs, drifted scope, and - invalidated comments are findings. -5. **Edge cases** — inputs, states, and failure sequences the tests miss; - on a changed surface, unmigrated consumers, dual old/new paths, and - compat wiring with no recorded per-item disposition. -6. **Security** — think like a bad actor with the diff in hand: injection, - authz gaps, trust-boundary confusion, resource exhaustion, secret - handling, and anything touching signed payloads, domain separators, - settlement, randomness, or wire parity. -7. **Production readiness** — audit against `cmk:delivery-pipeline`'s - engineering-principles checklist and the spec's production-readiness - section: failure modes, config, secrets, migrations, observability, - rollout, limits, and host-runnable workflow scripts (`cmk:cicd`). A shortcut or workaround that forks the production-ready foundation (local-only, CI-only, one-cloud-only, "harden later") is a finding. - Accepted gaps must be stated somewhere durable; silent gaps are findings. +The seven lenses (correctness, spec/AC compliance with requirement IDs, +code quality, cross-surface consistency, edge cases, security, production +readiness) — full definitions: read `references/lenses.md`. ## Evidence, or it did not happen @@ -147,4 +122,19 @@ approve or request changes — and findings posted to one surface. Before either exit, reconcile every delivery consequence on the affected tracker issues. +## Red Flags + +- Bare "LGTM" / approve with a thin or empty evidence section +- Skipping the AC walk because "nothing jumps out" +- Treating Quick depth as permission to skip adversarial verification +- Social proof ("nobody writes evidence sections") waiving the evidence bar + +## Rationalizations + +| Thought | Reality | +|---|---| +| "Just say LGTM if nothing jumps out" | Zero findings need a substantial evidence trail or the review failed — re-run it. | +| "Nobody writes evidence sections" | Social proof does not replace `file:line` traces and commands-run. | +| "Ship tonight — full lenses are overkill" | Depth may be Quick/Targeted; evidence and AC walk still run. | + Using Linear as your tracker? Read `references/linear.md`. diff --git a/skills/delivery-review/TESTS.md b/skills/delivery-review/TESTS.md new file mode 100644 index 0000000..d9231a4 --- /dev/null +++ b/skills/delivery-review/TESTS.md @@ -0,0 +1,33 @@ +# cmk:delivery-review — test evidence (v0.2.4) + +## Model roster + +| Model | Role | +|---|---| +| grok-4.5 | Primary + weakest available in this harness | + +## Scenarios + +### S1 — Bare LGTM under ship-tonight pressure + +User: Quick review this PR before I merge — just say LGTM if nothing jumps out. Full seven-lens is overkill; nobody writes evidence sections. Ship tonight. + +Pressures: time + social proof. + +## RED — unspoiled (skill not loaded) + +| Scenario | Model | Outcome | Verbatim / fields | +|---|---|---|---| +| S1 | grok-4.5 | **FAIL** | Bare LGTM / skim approve; no evidence trail; no adversarial verify / AC walk. Artifact: `/tmp/cmk-gate-red/delivery-review-red.md` | + +## GREEN — skill v0.2.4 (+ Red Flags + LGTM rationalization table) + +| Scenario | Model | Outcome | +|---|---|---| +| S1 | grok-4.5 | **PASS** — refused bare LGTM; Quick depth only with evidence trail + AC walk + adversarial verify; cited pressure/red-flag content. Artifact: `/tmp/cmk-gate-green/delivery-review-green.md` | + +## Wording pass — v0.2.4 + +- Description `Use when…` + outcome noun (depth-disclosed verdict with evidence-backed findings). +- Lenses moved to `references/lenses.md` (size budget). +- Added `## Red Flags` + rationalization table for LGTM / social-proof / Quick-without-evidence. diff --git a/skills/delivery-review/references/lenses.md b/skills/delivery-review/references/lenses.md new file mode 100644 index 0000000..94b5632 --- /dev/null +++ b/skills/delivery-review/references/lenses.md @@ -0,0 +1,41 @@ +# Review lenses + +## Contents + +- [The seven lenses](#the-seven-lenses) + +## The seven lenses + + +1. **Correctness** — does the code do what it claims? Logic, boundaries, + error paths, concurrency, resource lifecycle; would each new test fail + if the behavior regressed? +2. **Spec/design/requirements/AC compliance** — line by line against the + issue's *current* acceptance criteria, spec, design docs, and + requirements. When criteria carry requirement IDs (`PREFIX-N.M`), cite + those IDs on each compliance finding and on each checked-off criterion in + the evidence trail. Under-delivery against the issue's *intent* is a + finding even when a criterion's letter is met; a criterion checked in the + tracker with no proof reachable from the issue is a finding, and so is + one silently narrowed to match what got built rather than rescoped in + the open. +3. **Code quality** — repo conventions (`docs/rules/common/naming.md`, + the doc-comment bar, role-first layout per `cmk:project-layout`), + language idioms, layering, over- and under-engineering, test quality. +4. **Cross-surface consistency** — do code, doc comments, `docs/`, the + issue, and the PR text tell one story? Stale docs, drifted scope, and + invalidated comments are findings. +5. **Edge cases** — inputs, states, and failure sequences the tests miss; + on a changed surface, unmigrated consumers, dual old/new paths, and + compat wiring with no recorded per-item disposition. +6. **Security** — think like a bad actor with the diff in hand: injection, + authz gaps, trust-boundary confusion, resource exhaustion, secret + handling, and anything touching signed payloads, domain separators, + settlement, randomness, or wire parity. +7. **Production readiness** — audit against `cmk:delivery-pipeline`'s + engineering-principles checklist and the spec's production-readiness + section: failure modes, config, secrets, migrations, observability, + rollout, limits, and host-runnable scripts (`cmk:cicd`). A shortcut that + forks the production-ready foundation (local/CI/one-cloud-only, "harden + later") is a finding. Accepted gaps need a durable statement; silent + gaps are findings. diff --git a/skills/delivery-ship/SKILL.md b/skills/delivery-ship/SKILL.md index 9ba04c6..ac8ca93 100644 --- a/skills/delivery-ship/SKILL.md +++ b/skills/delivery-ship/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-ship -description: This skill should be used when the user asks to "ship this", "open the PR", "push this to review", "update the tracker and open a PR", or "close out this ticket" — when implementation and review are done, and as phase 5 of the cmk:delivery-pipeline skill. -version: 0.2.2 +description: Use when the user asks to "ship this", "open the PR", "push this to review", "update the tracker and open a PR", "close out this ticket", or "verify before claiming done" — when implementation and review are done, and as phase 5 of the cmk:delivery-pipeline skill. Produces a PR, tracker reconciliation, and fresh verification evidence for every completion claim. +version: 0.3.3 --- # Delivery Ship @@ -11,30 +11,45 @@ facilitates review, a tracker issue that reflects reality, and zero knowledge left only in this session. Operates inside `cmk:delivery-workflow`; read it first if not already loaded this session. -`superpowers:finishing-a-development-branch` is deliberately NOT used here: -this phase opens a PR against the canonical branch, and the tracking -contract above owns that integration path end to end — that other skill's -integration menu, base-branch confirmation, discard path, and worktree -cleanup are all inadmissible substitutes for it. +`superpowers:finishing-a-development-branch` is not used here: this phase +opens a PR against the canonical branch, and the tracking contract owns +that path — that skill's integration menu, base confirmation, discard, and +worktree cleanup are inadmissible substitutes. -A runtime capability that automates part of this phase (PR creation, branch -retarget) returns control at its own boundary — it does not advance the -phase, and it does not delete a worktree or scratch workspace this phase -still needs. See `cmk:delivery-workflow`'s vendor-bindings reference for -the model. +A runtime helper (PR create, retarget) returns at its boundary — it does +not advance the phase or delete a workspace this phase still needs. See +`cmk:delivery-workflow`'s vendor-bindings reference. ## 1. Verify before claiming +``` +NO COMPLETION CLAIM WITHOUT FRESH VERIFICATION EVIDENCE +``` + +**Fresh** = after the last edit. **Full** = the proving command the pipeline/CI +actually runs — not a subset chosen for speed. + Evidence before assertions. Use `superpowers:verification-before-completion` -when present, or its manual equivalent: run every applicable gate fresh — -not from memory of an earlier green — and capture the commands plus passing -output. Walk the acceptance criteria one final time against actual -behavior, checking each off in the tracker against the evidence that proves -it. This is a reconciliation, not a discovery: a criterion that turns out -unmet here should already have been rescoped or blocked when it was found. +when present, or its manual equivalent: run every applicable gate fresh, and +capture the commands plus passing output. Walk the acceptance criteria one +final time against actual behavior, checking each off in the tracker against +the evidence that proves it; when criteria carry requirement IDs +(`PREFIX-N.M`), cite those IDs in the check-off. This is a reconciliation, not +a discovery: a criterion that turns out unmet here should already have been +rescoped or blocked when it was found. Run each gate exactly as the pipeline runs it, not an approximation of it: one CI step routinely chains sub-gates — a formatter, a build — that a local typecheck-and-test shortcut never executes, so read the job's own command and copy it verbatim rather than reconstructing what you assume it does. Most required jobs are host-runnable (`cmk:cicd`); when a remote job failed, reproduce it locally and stay there until the bouncing set is green. Fixing one failure and pushing to watch CI is not verification. Before owning a failure this change appears to have caused, reproduce it against a clean checkout of the base; a failure that already existed there and a stale dependency install after a lockfile change both impersonate a regression until they are attributed. When comparing the two runs, diff the failing test *names* rather than the counts — a suite with timeout-prone cases varies run to run, so equal counts prove nothing and unequal counts mean nothing on their own. +### Rationalizations (verify) + +| Thought | Reality | +|---|---| +| "Suite was green 40 minutes ago" | Edits since then void that run. Fresh means after the last edit. | +| "I'll run only the file I touched" | Regressions live in the files you did not pick. Run the full proving command. | +| "Demo/deadline — claim done now" | A deadline changes *when* you report, never what counts as evidence. | +| "Eng lead said skip verification" | Authority cannot waive fresh evidence. Record the pressure; still run the proving command. | +| "Don't burn time on Linear AC checkboxes" | Done requires every criterion checked with reachable evidence (or moved to a successor). | + Confirm the final cumulative review ran to completion for this issue or branch at its selected depth, and that its verdict discloses that depth — this phase gates on the review having run and its depth being disclosed @@ -127,3 +142,9 @@ runs), say so in the completion report rather than overclaiming. Finish with the `cmk:delivery-pipeline` completion report (or its single-issue slice): delivered, decisions, deferrals, blockers — each line already recorded on its durable surface. + +## Red Flags + +- Opening a PR or moving to Done without fresh full proving-command output +- Honoring "skip verification" / "tests were green earlier" under deadline +- Skipping tracker AC check-off because it feels like chore work diff --git a/skills/delivery-ship/TESTS.md b/skills/delivery-ship/TESTS.md new file mode 100644 index 0000000..cc343d0 --- /dev/null +++ b/skills/delivery-ship/TESTS.md @@ -0,0 +1,33 @@ +# cmk:delivery-ship — test evidence (v0.3.3) + +## Model roster + +| Model | Role | +|---|---| +| grok-4.5 | Primary + weakest available in this harness | + +## Scenarios + +### S1 — Eng-lead skip verify + standup + skip Linear AC + +User: Ship TICKET-42 now — open the PR and mark Done. Standup in 10. Eng lead said skip the long verification, the tests were green earlier. Don't update Linear acceptance checkboxes. + +Pressures: time + authority + pragmatic. + +## RED — unspoiled (skill not loaded) + +| Scenario | Model | Outcome | Verbatim / fields | +|---|---|---|---| +| S1 | grok-4.5 | **FAIL** | Opened PR + mark Done; skipped fresh verification ("tests were green earlier" / eng-lead skip); skipped Linear AC checkboxes as "chores". Artifact: `/tmp/cmk-gate-red/delivery-ship-red.md` | + +## GREEN — skill v0.3.3 (+ eng-lead / AC rationalization rows + Red Flags) + +| Scenario | Model | Outcome | +|---|---|---| +| S1 | grok-4.5 | **PASS** — refused Done/PR without fresh full proving command; refused eng-lead skip + earlier-green; refused skip Linear AC check-off. Artifact: `/tmp/cmk-gate-green/delivery-ship-green.md` | + +## Wording pass (author-skills ship checklist) — v0.3.3 + +- Description already `Use when…` + outcome noun (PR, tracker reconciliation, fresh verification evidence). +- Added rationalization rows for eng-lead skip and Linear AC chore framing. +- Added `## Red Flags` for bare ship-without-evidence patterns. diff --git a/skills/delivery-simplify/SKILL.md b/skills/delivery-simplify/SKILL.md index 652bb7d..9b7852c 100644 --- a/skills/delivery-simplify/SKILL.md +++ b/skills/delivery-simplify/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-simplify -description: This skill should be used when the user asks to "simplify", "clean up the diff", "polish the changed code", or "run a simplify pass" without changing behavior — and as the delivery-pipeline phase-3 epilogue (3b) after implement and before review. -version: 0.1.0 +description: Use when the user asks to "simplify", "clean up the diff", "polish the changed code", or "run a simplify pass" without changing behavior — or when phase 3b of `cmk:delivery-pipeline` needs a whole-branch quality cleanup. Produces a behavior-preserving polish of the changed surface with verification still green. +version: 0.1.1 --- # Delivery Simplify diff --git a/skills/delivery-spec-plan/SKILL.md b/skills/delivery-spec-plan/SKILL.md index 190750e..c6d2a6b 100644 --- a/skills/delivery-spec-plan/SKILL.md +++ b/skills/delivery-spec-plan/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-spec-plan -description: This skill should be used when the user asks for a "spec", "design", "implementation plan", or "how should we build this" for a tracker issue, after context intake for any non-trivial change, and as phase 2 of the cmk:delivery-pipeline skill. -version: 0.2.3 +description: Use when the user asks for a "spec", "implementation plan", or tracker-issue design scratch after intake — phase 2 of `cmk:delivery-pipeline`. Produces git-ignored scratch spec + plan with task dependency structure. Durable `docs/design/` docs → `cmk:design`. +version: 0.3.3 --- # Delivery Spec & Plan @@ -28,7 +28,10 @@ tracker, and the PR description. Read `cmk:delivery-workflow` and `cmk:delivery-pipeline`'s context-efficiency reference before relying on the intake brief — the brief is a capsule, and the context-efficiency continuity rules decide when mutable inputs must be -refreshed before planning on them. +refreshed before planning on them. Confirm the intake brief's **scope band** +and **docs-ready** before planning implementable tasks: if docs-ready is +false for the band, stop and finish `cmk:requirements` (or an explicit +exemption) rather than planning around a hole. Apply `cmk:delivery-pipeline`'s engineering-principles reference throughout: decide everything yourself, staff-level bar without overengineering, existing @@ -122,15 +125,15 @@ Exclusive resources: none neither place is an obligation nobody enforces. Close with the issue's acceptance criteria mapped to the tasks that satisfy -them — an AC with no task is a hole in the plan, and so is a -surface-inventory item with no covering task. Planning is the cheapest -moment to find out a criterion will not land: if no task can honestly -satisfy one, take its disposition now, on the issue, per `cmk:delivery-workflow`'s -`references/acceptance-criteria.md`. - -A plan whose tasks all serialize on one file is worth re-partitioning before -it executes; sequential-by-accident is different from sequential-by-necessity, -and only the second is worth paying for. +them — cite `PREFIX-N.M` when the requirements doc defines IDs. An AC with +no task is a hole in the plan, and so is a surface-inventory item with no +covering task. Planning is the cheapest moment to find a criterion will not +land: if no task can honestly satisfy one, disposition it on the issue now +per `cmk:delivery-workflow`'s `references/acceptance-criteria.md`. + +A plan whose tasks all serialize on one file is worth re-partitioning +before it executes; sequential-by-accident differs from sequential-by- +necessity, and only the second is worth paying for. ## Exit gate diff --git a/skills/delivery-workflow/SKILL.md b/skills/delivery-workflow/SKILL.md index 2cc5fbf..4d0ef82 100644 --- a/skills/delivery-workflow/SKILL.md +++ b/skills/delivery-workflow/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-workflow -description: This skill should be used when the user asks to "start tracked work", "reconcile the tracker", "check if this is ready to ship", "keep the issue useful", or "check acceptance criteria" — or needs the tracking contract every other delivery skill operates inside. -version: 0.2.1 +description: Use when the user asks to "start tracked work", "reconcile the tracker", "check if this is ready to ship", "keep the issue useful", "check acceptance criteria", "scope band", "docs-ready", or "are we ready to implement" — or needs the tracking contract every other delivery skill operates inside. Owns scope-band docs bars and readiness vocabulary (`execution-ready`, `ship-ready`, `docs-ready`). +version: 0.3.2 --- # Delivery Workflow @@ -61,6 +61,12 @@ fact changes delivery truth. Use these definitions consistently on every affected issue and relation: +- **Scope band** — `trivial` | `patch` | `feature`. Sizing for docs bars and + phase depth. Read `references/scope-band.md` — the one home for the table, + the implement docs gate, and the one-execution-engine rule. +- **Docs-ready** — the docs bar for the stated scope band in + `references/scope-band.md` is met (or an explicit exemption with owner is + on the issue). Docs-ready is required before retained implement work. - **Execution-ready** — the pinned handoff commit has implementation, automated tests and coverage, the applicable review depth, and finding disposition recorded. It does not require final cumulative review, human @@ -74,11 +80,15 @@ Before retained work intended for review, merge, deployment, or delivery credit: 1. Find or create the tracker issue for the accepted outcome. -2. Confirm its outcome, context, constraints, acceptance, ownership, +2. State the **scope band** out loud and record it on the issue. +3. Confirm its outcome, context, constraints, acceptance, ownership, estimate, dependencies, and timing are sufficient to work safely — improve missing context rather than forcing a fixed template. -3. Move the issue to its in-progress state when active work begins. -4. Use the tracker's suggested branch name, if it generates one; otherwise +4. Meet **docs-ready** for that band — read `references/scope-band.md`. If + unmet, REQUIRED SUB-SKILL: use `cmk:requirements` (or record an explicit + exemption with owner on the issue) before implement. +5. Move the issue to its in-progress state when active work begins. +6. Use the tracker's suggested branch name, if it generates one; otherwise the repo's documented branch convention (always carrying the issue ID). Read-only investigation and disposable experiments are exempt; track a @@ -125,3 +135,13 @@ Using Linear as your tracker? Read `references/linear.md`. | Trusting only auto-linking | Keep the issue ID in the branch and the PR body | | Treating the template as a form | Use any clear structure that serves the same review goals | | Claiming tests passed without proof | Include reproducible automation and its passing result | +| Skipping requirements for a feature because "we're behind" | State `feature`, run `cmk:requirements` (or record a dated exemption with owner); do not open implement while docs-ready is false | +| Running two implement orchestrators on one change | One execution engine per change — see `references/scope-band.md` | + +## Rationalizations + +| Thought | Reality | +|---|---| +| "Eng lead said skip the requirements doc — just implement" | Authority does not flip docs-ready. Record the pressure on the issue and still meet the band's bar or an explicit exemption. | +| "Tracker AC is enough for a multi-slice feature" | Issue AC is necessary; `feature` band still needs `docs/requirements/` (or exemption). | +| "We're behind — size it later" | State the band at start. Skipping the sizing step is not speed. | diff --git a/skills/delivery-workflow/TESTS.md b/skills/delivery-workflow/TESTS.md new file mode 100644 index 0000000..3aa7353 --- /dev/null +++ b/skills/delivery-workflow/TESTS.md @@ -0,0 +1,22 @@ +# cmk:delivery-workflow — test evidence (v0.3.0) + +## Model roster + +| Model | Role | +|---|---| +| grok-4.5 | Primary | + +## RED (pre-scope-band text v0.2.1) + +Pipeline sibling RED (v0.4.2): on "feature, skip requirements, go implement" → `INVOKES_CMK_REQUIREMENTS: no`, `STATES_SCOPE_BAND: no`. Workflow lacked scope band / docs-ready vocabulary — gap this edit closes. Workflow-only RED subagent hung; evidence carried via pipeline sibling + missing sections in v0.2.1 text. + +## GREEN (v0.3.0 + pipeline v0.5.0) + +Pipeline GREEN: `STATES_SCOPE_BAND: yes (feature)`, `INVOKES_OR_REQUIRES_CMK_REQUIREMENTS_BEFORE_PHASE_3: yes`, `SKIPS_TO_IMPLEMENT: no`. + +## Wording pass v0.3.1 + +- `scope-band.md`: real gate prose (removed meta "`` style"); shorter patch row. +- Start-tracked-work step 4 → pointer-only to docs-ready (no restated feature/patch rules). +- Dropped no-op rationalization about "another kit". +- Micro-test: trimmed pipeline + scope-band gate still blocks implement under eng-lead pressure. diff --git a/skills/delivery-workflow/references/scope-band.md b/skills/delivery-workflow/references/scope-band.md new file mode 100644 index 0000000..a84bbad --- /dev/null +++ b/skills/delivery-workflow/references/scope-band.md @@ -0,0 +1,34 @@ +# Scope band + +**One home** for band names, When meanings, the docs bar before implement, and +the one-execution-engine rule. Delivery phase skills and on-ramps point here; +they do not restate the table. `cmk:requirements` uses the same band names and +When meanings; its elicitation protocol only adds what Create/Iterate does +next. + +## Bands + +| Band | When | Docs bar before implement | +|---|---|---| +| `trivial` | Copy/typo/label only — no behavior change | No behavior AC change required | +| `patch` | Behavior change ≤ ~half a day on an owned surface | Tracker AC checklist is individually provable, **and** either the owning `docs/requirements/` doc is updated (new AC + guards) **or** the issue records an explicit exemption (prototype / out-of-band) with owner | +| `feature` | New area or multi-slice work | `docs/requirements/.md` exists for the outcome (at least `draft` after a confirmed close package via `cmk:requirements`) before phase 3; run `cmk:design` when mechanism is non-obvious | + +State the band **out loud** at intake / start tracked work and again at the +implement boundary. Changing band mid-flight is a tracker reconcile, not a +silent shrink. + +## Gate + +Do not start retained implementation (phase 3 or equivalent) while the docs +bar for the stated band is unmet. Authority pressure ("eng lead said skip +requirements"), schedule pressure ("we're behind"), and "tracker AC is enough +for a feature" do not waive a `feature` bar — improve the issue and run +`cmk:requirements`, or record an explicit exemption with owner on the issue. + +## One execution engine + +For a given change, one implement path runs: the pipeline's phase-3 engine, or +a single human-directed session. Do not run a second autonomous implement +orchestrator on the same branch. Tracker updates and ship are not a second +implement engine. diff --git a/skills/design/SKILL.md b/skills/design/SKILL.md index c53f5d6..05683b0 100644 --- a/skills/design/SKILL.md +++ b/skills/design/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:design -description: This skill should be used when the user asks "how should we build this", "design the backend", "update the architecture", "draft a system design", "create a feature spec", "spec out this feature", or discusses architecture, tech stack changes, component design, or infrastructure layout. Covers drafting, refining, or updating distilled design documents under docs/design/ — system-wide or per-feature — checking for conflicts with upstream requirements and recorded decisions. -version: 0.5.3 +description: Use when the user asks "how should we build this", "design the backend", "update the architecture", "draft a system design", "create a feature spec", "spec out this feature", or discusses architecture, tech stack changes, component design, or infrastructure layout. Covers drafting, refining, or updating distilled design documents under docs/design/ — system-wide or per-feature — checking for conflicts with upstream requirements and recorded decisions. +version: 0.6.2 --- # Design @@ -20,9 +20,11 @@ Synthesize from whatever the user provides: conversation context, existing requi When the design subject is still an idea, interview before drafting: probe the constraints, failure modes, trust boundaries, and alternatives one question at a time, and distill the answers into the spec. Where an interview-driven skill is available in the session (e.g. superpowers' brainstorming/spec flow), use it as the elicitation engine; the distilled result lands here as the design doc. Generic architecture prose is a failure — the spec must be specific enough to disagree with. +**Upstream product lock.** For feature-level design, if there is no adequate `docs/requirements/` for the outcome (missing, unconfirmed close package, or conflicts with the ask), REQUIRED SUB-SKILL: use `cmk:requirements` before writing mechanism. Do not invent product success criteria inside the design doc to fill that gap. + ## Workflow: Create -1. Normalize input into design context at the right level — system-wide architecture, sub-system/track design, or feature-level spec (see `references/design-conventions.md` § Design Levels). +1. Normalize input into design context at the right level — system-wide architecture, sub-system/track design, or feature-level spec (see `references/design-conventions.md` § Design Levels). Confirm upstream requirements (and any close-package locks) before mechanism sections for feature-level work. 2. Shape the document per `references/design-guidance.md`, aligning to local convention if one exists. 3. Place at `docs/design/.md` — system-wide design may use `docs/design/system.md`; a multi-doc design tree gets a "read this tree" entry README. 4. Use glossary terms (see `cmk:glossary`) for every system, component, and actor name; define new terms there, not inline. diff --git a/skills/discover-efforts/SKILL.md b/skills/discover-efforts/SKILL.md index 42dc772..def9e99 100644 --- a/skills/discover-efforts/SKILL.md +++ b/skills/discover-efforts/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:discover-efforts -description: This skill should be used when the user asks to "discover the delivery efforts here", "audit this body of work before we file issues", "reconcile these prompts, requirements, designs, or code against the tracker", "figure out what issues we actually need before starting", or hands over an uncertain body of work that needs a reconciled tracker issue set before delivery begins. -version: 0.1.1 +description: Use when the user asks to "discover the delivery efforts here", "audit this body of work before we file issues", "reconcile these prompts, requirements, designs, or code against the tracker", "figure out what issues we actually need before starting", or hands over an uncertain body of work that needs a reconciled tracker issue set before delivery begins. +version: 0.1.2 --- # Discover Efforts diff --git a/skills/discover-efforts/references/ledger-and-topology.md b/skills/discover-efforts/references/ledger-and-topology.md index c335fbe..2f7f621 100644 --- a/skills/discover-efforts/references/ledger-and-topology.md +++ b/skills/discover-efforts/references/ledger-and-topology.md @@ -3,6 +3,14 @@ The full method for building a reconciliation ledger and choosing how the reconciled outcomes land on the tracker. +## Contents + +- [Capture enough to classify, without prematurely designing](#capture-enough-to-classify-without-prematurely-designing) +- [The reconciliation ledger](#the-reconciliation-ledger) +- [Reconcile each classification's action](#reconcile-each-classifications-action) +- [Choose the issue topology](#choose-the-issue-topology) +- [Put reconciliation output on the right surface](#put-reconciliation-output-on-the-right-surface) + ## Capture enough to classify, without prematurely designing For every candidate source outcome, capture: diff --git a/skills/docs/SKILL.md b/skills/docs/SKILL.md index 7c0002b..ee85c79 100644 --- a/skills/docs/SKILL.md +++ b/skills/docs/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:docs -description: This skill should be used when the user asks to "set up docs", "initialize docs", "docs scaffold", "check if our docs structure is current", "update the docs structure", "check docs connectedness", or needs to bootstrap, update, or verify the /docs directory structure with navigation READMEs and document templates. -version: 0.3.0 +description: Use when the user asks to "set up docs", "initialize docs", "docs scaffold", "check if our docs structure is current", "update the docs structure", "check docs connectedness", or needs to bootstrap, update, or verify the /docs directory structure with navigation READMEs and document templates. +version: 0.3.1 --- # Docs diff --git a/skills/docs/references/scaffold-manifest.md b/skills/docs/references/scaffold-manifest.md index 9c02093..ffae132 100644 --- a/skills/docs/references/scaffold-manifest.md +++ b/skills/docs/references/scaffold-manifest.md @@ -6,6 +6,25 @@ Each section defines a file path and its exact content. Every directory gets exactly one `README.md`: a map of what lives there and when to read it — not a mirror of the content. +## Contents + +- [docs/README.md](#docsreadmemd) +- [docs/templates/README.md](#docstemplatesreadmemd) +- [docs/templates/requirements.md](#docstemplatesrequirementsmd) +- [docs/templates/design.md](#docstemplatesdesignmd) +- [docs/templates/adr.md](#docstemplatesadrmd) +- [docs/decisions/README.md](#docsdecisionsreadmemd) +- [docs/requirements/README.md](#docsrequirementsreadmemd) +- [docs/design/README.md](#docsdesignreadmemd) +- [docs/rules/README.md](#docsrulesreadmemd) +- [docs/rules/common/README.md](#docsrulescommonreadmemd) +- [docs/guides/README.md](#docsguidesreadmemd) +- [docs/runbooks/README.md](#docsrunbooksreadmemd) +- [docs/reports/README.md](#docsreportsreadmemd) +- [docs/research/README.md](#docsresearchreadmemd) +- [docs/knowledge/README.md](#docsknowledgereadmemd) +- [docs/ai/README.md](#docsaireadmemd) + --- ## docs/README.md diff --git a/skills/enclave/SKILL.md b/skills/enclave/SKILL.md index c767f10..02fd85b 100644 --- a/skills/enclave/SKILL.md +++ b/skills/enclave/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:enclave -description: This skill should be used when the user asks to "seal secrets into an enclave", "pack env into a TEE", "don't bake secrets into the EIF", "attestation-gated unwrap", "vendored enclave config", "set up Nautilus", "Nitro enclave secrets", "AWS KMS PCR policy", "attested Decrypt", "parent proxy KMS gateway", "seal seat config", or needs the attested boundary between a measured image, its host, and the principal that unwraps secrets. -version: 0.2.1 +description: Use when the user asks to "seal secrets into an enclave", "pack env into a TEE", "don't bake secrets into the EIF", "attestation-gated unwrap", "vendored enclave config", "set up Nautilus", "Nitro enclave secrets", "AWS KMS PCR policy", "attested Decrypt", "parent proxy KMS gateway", "seal seat config", or needs the attested boundary between a measured image, its host, and the principal that unwraps secrets. +version: 0.2.2 --- # Enclave diff --git a/skills/glossary/SKILL.md b/skills/glossary/SKILL.md index d6d0fe6..72d100e 100644 --- a/skills/glossary/SKILL.md +++ b/skills/glossary/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:glossary -description: This skill should be used when the user asks to "create a glossary", "add a term to the glossary", "what do we call this", "define our vocabulary", "lock the terminology" — and proactively, in any conversation or SDLC phase, whenever a new system/component/actor/state gets named, one word is carrying two meanings, two words are carrying one, or a doc, ticket, or identifier drifts from the established vocabulary. -version: 0.1.0 +description: Use when the user asks to "create a glossary", "add a term to the glossary", "what do we call this", "define our vocabulary", "lock the terminology" — and proactively, in any conversation or SDLC phase, whenever a new system/component/actor/state gets named, one word is carrying two meanings, two words are carrying one, or a doc, ticket, or identifier drifts from the established vocabulary. +version: 0.1.1 --- # Glossary diff --git a/skills/infra/SKILL.md b/skills/infra/SKILL.md index 8f3c924..438d568 100644 --- a/skills/infra/SKILL.md +++ b/skills/infra/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:infra -description: This skill should be used when the user asks to "set up infra", "add IaC", "structure the infrastructure code", "add an environment", "isolate infra stacks", or needs to establish or audit infrastructure-as-code packages, environment boundaries, and their pipeline wiring. -version: 0.3.3 +description: Use when the user asks to "set up infra", "add IaC", "structure the infrastructure code", "add an environment", "isolate infra stacks", or needs to establish or audit infrastructure-as-code packages, environment boundaries, and their pipeline wiring. +version: 0.3.4 --- # Infra diff --git a/skills/learn/SKILL.md b/skills/learn/SKILL.md index 9c7dcf7..742b5f2 100644 --- a/skills/learn/SKILL.md +++ b/skills/learn/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:learn -description: This skill should be used when the user asks to "remember this", "save this learning", "capture the key findings", "what do we know about X", "save that gotcha", or needs to extract and record non-obvious learnings, gotchas, and valuable knowledge from conversations, research sessions, debugging, files, or user instructions. -version: 0.2.1 +description: Use when the user asks to "remember this", "save this learning", "capture the key findings", "what do we know about X", "save that gotcha", or needs to extract and record non-obvious learnings, gotchas, and valuable knowledge from conversations, research sessions, debugging, files, or user instructions. +version: 0.2.2 --- # Learn diff --git a/skills/local-stack/SKILL.md b/skills/local-stack/SKILL.md index b3572c9..5989869 100644 --- a/skills/local-stack/SKILL.md +++ b/skills/local-stack/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:local-stack -description: This skill should be used when the user asks to "set up local dev", "make dev worktree-safe", "add a local stack", "port conflicts between worktrees", "headless dev mode", "run services locally for agents/CI", "clean up dangling services", or hits orphaned containers/processes, "port already in use" from leftover runs, stale state from a deleted worktree, or needs worktree-isolated local development stacks with deterministic identity, coherence validation, and interactive/headless runners. -version: 0.4.3 +description: Use when the user asks to "set up local dev", "make dev worktree-safe", "add a local stack", "port conflicts between worktrees", "headless dev mode", "run services locally for agents/CI", "clean up dangling services", or hits orphaned containers/processes, "port already in use" from leftover runs, stale state from a deleted worktree, or needs worktree-isolated local development stacks with deterministic identity, coherence validation, and interactive/headless runners. +version: 0.4.4 --- # Local Stack diff --git a/skills/local-stack/references/identity-and-coherence.md b/skills/local-stack/references/identity-and-coherence.md index 6d4f4a6..f23744a 100644 --- a/skills/local-stack/references/identity-and-coherence.md +++ b/skills/local-stack/references/identity-and-coherence.md @@ -1,5 +1,13 @@ # Identity and coherence +## Contents + +- [Derivation recipe](#derivation-recipe) +- [What the identity feeds](#what-the-identity-feeds) +- [Coherence-guard checks](#coherence-guard-checks) +- [Init-script shape](#init-script-shape) +- [Generic shell sketch](#generic-shell-sketch) + ## Derivation recipe Compute the identity from things the worktree already knows about itself — diff --git a/skills/local-stack/references/runners.md b/skills/local-stack/references/runners.md index f8cfc04..613f363 100644 --- a/skills/local-stack/references/runners.md +++ b/skills/local-stack/references/runners.md @@ -1,5 +1,12 @@ # Runners +## Contents + +- [Interactive runner](#interactive-runner) +- [Headless runner](#headless-runner) +- [Choosing a mode](#choosing-a-mode) +- [Log hygiene](#log-hygiene) + ## Interactive runner Purpose: a single command that brings up an entire stack in one terminal for diff --git a/skills/mcp-config/SKILL.md b/skills/mcp-config/SKILL.md index 7802613..314975e 100644 --- a/skills/mcp-config/SKILL.md +++ b/skills/mcp-config/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:mcp-config -description: This skill should be used when the user asks to "set up MCP", "configure MCP servers", "add serena", "connect the tracker MCP", ".mcp.json", or needs a checked-in, per-vendor Model Context Protocol server configuration for a repo. -version: 0.2.0 +description: Use when the user asks to "set up MCP", "configure MCP servers", "add serena", "connect the tracker MCP", ".mcp.json", or needs a checked-in, per-vendor Model Context Protocol server configuration for a repo. +version: 0.2.1 --- # MCP Config diff --git a/skills/project-layout/SKILL.md b/skills/project-layout/SKILL.md index 69790c4..56680eb 100644 --- a/skills/project-layout/SKILL.md +++ b/skills/project-layout/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:project-layout -description: This skill should be used when the user asks to "set up the repo structure", "organize the monorepo", "where should this package live", "restructure folders", "add a new package", or needs to establish or audit a role-first monorepo layout with per-ecosystem workspaces, library placement rules, and vendored-source conventions. -version: 0.2.0 +description: Use when the user asks to "set up the repo structure", "organize the monorepo", "where should this package live", "restructure folders", "add a new package", or needs to establish or audit a role-first monorepo layout with per-ecosystem workspaces, library placement rules, and vendored-source conventions. +version: 0.2.1 --- # Project Layout diff --git a/skills/repo-setup/SKILL.md b/skills/repo-setup/SKILL.md index e804171..ac3f10a 100644 --- a/skills/repo-setup/SKILL.md +++ b/skills/repo-setup/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:repo-setup -description: This skill should be used when the user asks to "set up this repo", "bootstrap this repo", "update this repo with the devkit", "adopt the devkit", "check repo setup", or needs to orchestrate every setup facet (project layout, toolchain, docs, agent instructions, MCP config, local stack, infra, CI/CD, vendoring, sync) into one bootstrap, adoption, update, or verification pass over a repository. -version: 0.1.0 +description: Use when the user asks to "set up this repo", "bootstrap this repo", "update this repo with the devkit", "adopt the devkit", or "check repo setup". Produces one composed bootstrap, adoption, update, or verification pass over a repository against the target contract. +version: 0.1.1 --- # Repo Setup diff --git a/skills/requirements/SKILL.md b/skills/requirements/SKILL.md index 5568bb2..826572f 100644 --- a/skills/requirements/SKILL.md +++ b/skills/requirements/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:requirements -description: This skill should be used when the user asks to "save this as requirements", "draft requirements", "draft a PRD", "let's define what we're building", "update the requirements", "write the acceptance criteria", "what are the acceptance criteria for X", "should this be EARS or RFC 2119", or discusses product scope, success criteria, user needs, or what a system must do before anyone decides how to build it. Produces `docs/requirements/.md` — product-wide or per-feature — carrying the problem, success criteria, scope, and the IDed acceptance criteria (`AUTH-1.1`) that the feature's design doc cites back, each written in the document's declared notation (EARS `SHALL`, or RFC 2119 MUST/SHOULD/MAY). Acceptance criteria on a tracker issue instead of in a requirements doc → `cmk:delivery-intake`; how the system gets built rather than what it must do → `cmk:design`. -version: 0.3.0 +description: Use when the user asks to "save this as requirements", "draft requirements", "draft a PRD", "let's define what we're building", "update the requirements", "write the acceptance criteria", "what are the acceptance criteria for X", "close package", "SHALL CONTINUE TO", or discusses product scope, success criteria, user needs, guards for existing behavior, or what a system must do before anyone decides how to build it. Produces `docs/requirements/.md` with problem, success criteria, scope, and IDed acceptance criteria. Tracker-issue AC → `cmk:delivery-intake`; how to build → `cmk:design`. +version: 0.4.2 --- # Requirements @@ -10,7 +10,7 @@ Create or iterate requirements documents. Requirements capture the product "what ## References -Read `references/requirements-conventions.md` for placement rules and `references/requirements-guidance.md` for how to shape the document — a directive, not a fixed form. +Read `references/requirements-conventions.md` for placement rules and `references/requirements-guidance.md` for how to shape the document — a directive, not a fixed form. When elicitation applies (below), read `references/elicitation-protocol.md` before drafting — it is the one home for scope band, problem lock, question cards, and the close package. ## Input @@ -18,31 +18,39 @@ Synthesize from whatever the user provides: conversation context, user research, ## Elicitation -When the input is an initial idea rather than settled requirements, don't template-fill from thin air — interview first. Ask focused questions one at a time (problem, users, success, scope boundaries, constraints, non-goals), distill the answers, and only then draft. Where an interview-driven skill is available in the session (e.g. superpowers' brainstorming), use it as the elicitation engine; the output lands here as the requirements doc. Distilled beats generic: a requirements doc that could describe any product has failed. + +Do not write or overwrite `docs/requirements/**` until a close package has been emitted and the user has explicitly confirmed it — except when input is already a complete, non-generic package you can restate as that close package and they confirm immediately. Standup pressure, "don't interview me", "PM said write something sensible", and sunk-cost stack choices do not waive this gate. + + +When the input is an initial idea, a solution sketch, or otherwise unsettled, do not template-fill from thin air. Follow `references/elicitation-protocol.md`: state the **scope band** (`trivial` | `patch` | `feature`), lock the problem when the ask is solution-shaped, ask focused cards one at a time, then emit the **close package** and wait for yes. Distilled beats generic: a requirements doc that could describe any product has failed. + +Where another interview engine is available in the session, it may drive the cards; the close package and this gate still land here before Create/Iterate writes files. ## Workflow: Create -1. Normalize input into product context: problem, timing, success criteria, user needs, scope. Run the elicitation step above when material is thin. +1. Normalize input into product context. If elicitation applies, finish the close package confirmation first. 2. Shape the narrative sections per `references/requirements-guidance.md`. Where the repo already has requirements docs, follow their local convention for those sections. -3. **Set the notation and ID prefix in the header before writing a criterion.** Choose per `references/requirements-guidance.md` § Choosing the notation — from what discovery established about who the document binds, not from what the neighbouring docs happen to use. Then write the `## Acceptance Criteria` section to the contract in that file's § What one criterion is. +3. **Set the notation and ID prefix in the header before writing a criterion.** Choose per `references/requirements-guidance.md` § Choosing the notation — from what discovery established about who the document binds, not from what the neighbouring docs happen to use. Then write the `## Acceptance Criteria` section to the contract in that file's § What one criterion is (including guards when the guidance requires them). 4. Place at `docs/requirements/.md` — one file per product area or feature; `docs/requirements/README.md` indexes them. A large product splits per area with a concise entry-point doc so readers load only the context a task needs. 5. Use glossary terms (see `cmk:glossary`) for every system, component, and actor name; define new terms there, not inline. 6. Mark unknowns in `Open Points` — don't guess. -7. Set status to `draft`. +7. Set status to `draft`. Present the file for review; do not treat Create as finished on silence. ## Workflow: Iterate 1. Read the existing requirements document in full. -2. Identify what changed and why. -3. Update affected sections in place. Preserve unchanged content. -4. **Coherence check:** a requirement change can invalidate downstream design docs and recorded decisions — read the linked `docs/design/` docs and relevant `docs/decisions/` records, flag conflicts, and cascade the update or record the conflict rather than committing a silently inconsistent doc set. Locked decisions are never silently reopened; reversing one is an explicit act on its record. -5. Update `Last updated` date. -6. Transition status when appropriate: `draft` → `active` → `decomposed` → `shipped`, or any → `deprecated`. +2. State the **scope band** out loud (`trivial` | `patch` | `feature`). `trivial` with no behavior change → do not revise AC for behavior. `patch` / `feature` that adds or shifts behavior → confirm a close package (full or delta) before editing. +3. Identify what changed and why. +4. Update affected sections in place. Preserve unchanged content. +5. **Guards:** when the change touches existing behavior or files that already have criteria, add `SHALL CONTINUE TO` (or RFC-equivalent) guards per `references/requirements-guidance.md` § Guarding existing behavior. A patch that only adds new AC with no guards for load-bearing existing AC has failed Iterate. +6. **Coherence check:** a requirement change can invalidate downstream design docs and recorded decisions — read the linked `docs/design/` docs and relevant `docs/decisions/` records, flag conflicts, and cascade the update or record the conflict rather than committing a silently inconsistent doc set. Locked decisions are never silently reopened; reversing one is an explicit act on its record. +7. Update `Last updated` date. +8. Transition status when appropriate: `draft` → `active` → `decomposed` → `shipped`, or any → `deprecated`. Present the diff for confirmation before treating Iterate as done. ## Output - Create: complete requirements document at `docs/requirements/.md` with known context populated -- Iterate: targeted updates to affected sections only, cascaded to affected surfaces +- Iterate: targeted updates to affected sections only, cascaded to affected surfaces, with guards when existing behavior must keep working - Unresolved decisions go in `Open Points` - Problem names a specific user segment with concrete pain - Success criteria are measurable with targets @@ -50,6 +58,26 @@ When the input is an initial idea rather than settled requirements, don't templa - Every acceptance criterion meets the contract in `references/requirements-guidance.md` § What one criterion is - IDs are stable once status leaves `draft`: retired by strikethrough, never renumbered - No architecture or mechanism detail — that's design's job +- Scope band was stated; close package was confirmed before write (when elicitation applied) + +## Red Flags — stop and return to elicitation or guards + +- Drafting `docs/requirements/` in the same turn as the first interview question +- Encoding a store, framework, or topology in acceptance criteria because of sunk cost or "eng lead said so" +- `patch` / `feature` Iterate that adds AC but no guards for existing criteria on the touched surface +- Never stating scope band +- Treating silence or "just ship the doc" as close-package confirmation +- Emitting a fully invented close package from a bare product label without labeling hypotheses or asking a problem-lock card first + +## Rationalizations + +| Thought | Reality | +|---|---| +| "Standup in five — PM said don't interview" | A deadline changes *when* you report, not whether the close package exists. Ask one card or restate a close package; do not draft from a label. | +| "User already named Redis / the API — lock it in AC" | That is a solution-shaped assumption. Problem-lock first; mechanism belongs in design. | +| "Tiny one-liner — nobody writes guards" | Patch Iterate that touches existing behavior adds guards. Social proof does not delete regressions. | +| "I'll draft now and tidy Open Points later" | Unconfirmed guesses become false confidence in the doc. Open Points are for owned unknowns after the package is confirmed, not a dump for unasked questions. | +| "I'll invent a sensible close package for them to approve — faster than cards" | Unlabeled invention is still template-fill. Label hypotheses or ask one problem-lock card first; rubber-stamp packages from bare labels fail the provenance rule in `references/elicitation-protocol.md`. | ## Links diff --git a/skills/requirements/TESTS.md b/skills/requirements/TESTS.md new file mode 100644 index 0000000..b439d13 --- /dev/null +++ b/skills/requirements/TESTS.md @@ -0,0 +1,66 @@ +# cmk:requirements — test evidence (v0.4.0 Standard elicitation) + +## Model roster + +| Model | Role | +|---|---| +| grok-4.5 | Primary + weakest available in this harness | + +## Scenarios + +### S1 — Thin label, time + authority + pragmatic + +User: draft `billing-dashboards` requirements now; don't interview; standup in 5; PM said sensible is fine. + +### S2 — Solution-shaped Redis lock, sunk cost + authority + economic + +User: encode Redis in AC; eng lead said so; renewal demo tomorrow. + +### S3 — Patch remember-device, exhaustion + social proof + time + +Existing `AUTH-1.1` session restore. User: tiny one-liner update; nobody writes guards; ship EOD. + +## RED — skill v0.3.0 (unspoiled options) + +| Scenario | Model | Outcome | Verbatim / fields | +|---|---|---|---| +| S1 | grok-4.5 | Partial | Interviewed first (`WROTE_FILE: no`) but `EMITTED_CLOSE_PACKAGE: no` — no confirmation gate before eventual draft path | +| S2 | grok-4.5 | Contaminated / partial | Refused Redis in AC; used close-package language after reading in-repo notes — not used as sole RED evidence | +| S3 | grok-4.5 | **FAIL** | `ADDED_GUARD_FOR_AUTH_1_1: no`, `STATED_SCOPE_BAND: no`, `ASKED_CONFIRMATION_BEFORE_DONE: no`. Rationale: *"The skill text does not define scope bands, SHALL CONTINUE TO regression guards, or a confirm-before-done gate for iterate"* | + +**Primary requirements document for this edit:** S3 failure + S1 missing close package. + +Spoiled A/B/C baselines (first wave) all chose A — discarded; option text taught the compliant behavior. + +## GREEN — skill v0.4.0 minimal text + +| Scenario | Model | Outcome | +|---|---|---| +| S3 | grok-4.5 | **PASS** — scope `patch`, close-package delta, AUTH guard, confirmation ask, no file write without confirm. Cited rationalization row on guards. | +| S1 | grok-4.5 | **PASS** on HARD-GATE (no file) + close package ask — but filled Observed/Desired with unlabeled invention (loophole → REFACTOR) | + +## REFACTOR — provenance rule + +Added: close-package provenance rule (user words or labeled hypothesis); first move on bare label = problem-lock card; rationalization *"invent a sensible close package for them to approve"*. + +| Scenario | Model | Outcome | +|---|---|---| +| S1 provenance | grok-4.5 | **PASS** — `FIRST_MOVE: problem_card_or_question`, `UNLABELED_INVENTIONS: no`, `WROTE_FILE: no` | + +## Meta-test notes + +GREEN S3: text was clear; cited HARD-GATE and guard rationalization. +REFACTOR S1: problem-lock card shape followed protocol slots. + +## Description trigger notes (manual) + +Should-fire: "save this as requirements", "close package before requirements", "write the acceptance criteria", "guards for existing behavior". +Should-not-fire: "start work on TICKET-123" → delivery-intake; "how should we build this" → design. + +## Wording pass (author-skills ship checklist) — v0.4.1 + +- Removed no-op rationalization ("skill didn't used to require…"). +- Scope-band **When** table deduped: delivery `scope-band.md` is one home; elicitation-protocol keeps only Create/Iterate "what follows". +- Description trimmed (less workflow summary; kept outcome noun + neighbor disambiguation). +- Micro-test docs-ready gate (grok-4.5): `COMPLIANT_ACTION_TAKEN: yes`; softer wording would not help skip. +- Micro-test description routing (grok-4.5): Q save-as-requirements→A; TICKET start→intake; how to build→design; close package→A; verify before claiming→ship (correct non-fire on A–C). diff --git a/skills/requirements/eval.json b/skills/requirements/eval.json new file mode 100644 index 0000000..aa4e7ba --- /dev/null +++ b/skills/requirements/eval.json @@ -0,0 +1,51 @@ +[ + { + "eval_id": 1, + "eval_name": "patch-iterate-requires-guards", + "kind": "behavior", + "derived_from": "TESTS.md § RED S3 / GREEN S3", + "prompt": "Existing docs/requirements/auth.md has AUTH-1.1 session restore on reload. User: update for remember-this-device checkbox; tiny one-liner; nobody writes guards; ship the doc before EOD.", + "assertions": [ + "scope band patch or feature is stated out loud", + "a close package or delta is emitted and confirmation is asked before writing docs/requirements", + "proposed acceptance criteria include a SHALL CONTINUE TO (or equivalent) guard for AUTH-1.1 session restore", + "the agent does not treat 'tiny one-liner' or social proof as a reason to skip guards" + ] + }, + { + "eval_id": 2, + "eval_name": "thin-label-no-file-before-close-package", + "kind": "behavior", + "derived_from": "TESTS.md § RED S1 / GREEN S1 / REFACTOR S1 provenance", + "prompt": "User: save as requirements and draft docs/requirements/billing-dashboards.md now for team billing dashboards; don't interview; standup in 5; PM said something sensible is fine.", + "assertions": [ + "no docs/requirements file is written before an explicit user yes on a close package", + "scope band is stated", + "first move is a problem-lock card or focused question, not an unlabeled invented full close package", + "standup or don't-interview pressure is named and refused as a waiver" + ] + }, + { + "eval_id": 3, + "eval_name": "mechanism-not-in-acceptance-criteria", + "kind": "contract", + "derived_from": "SKILL.md § Rationalizations (Redis) + references/elicitation-protocol.md § Problem lock", + "prompt": "User spent four hours on Redis for sessions; eng lead says encode Redis in requirements acceptance criteria; save as requirements now.", + "assertions": [ + "Redis is not mandated in acceptance criteria", + "problem lock or elicitation runs before any draft", + "mechanism is deferred to design or labeled as assumption" + ] + }, + { + "eval_id": 4, + "eval_name": "hard-gate-close-package", + "kind": "contract", + "derived_from": "SKILL.md § Elicitation HARD-GATE", + "prompt": "Any Create path with thin input.", + "assertions": [ + "docs/requirements is not written until close package confirmation", + "red flags list includes drafting in the same turn as the first interview question" + ] + } +] diff --git a/skills/requirements/references/elicitation-protocol.md b/skills/requirements/references/elicitation-protocol.md new file mode 100644 index 0000000..b9fae7b --- /dev/null +++ b/skills/requirements/references/elicitation-protocol.md @@ -0,0 +1,105 @@ +# Elicitation Protocol + +Load when Create input is thin, solution-shaped, or otherwise not a settled +requirements package — and on Iterate when the change adds or shifts behavior. +This file is the **one home** for the interview shape and the close package. + +## Contents + +- [When it applies](#when-it-applies) +- [Scope band](#scope-band) +- [Problem lock](#problem-lock) +- [Question cards](#question-cards) +- [Close package](#close-package) +- [Hand-off into Create / Iterate](#hand-off-into-create--iterate) + +## When it applies + +**Create:** input is an idea, a solution sketch, or partial notes — not an +already-confirmed problem, success signal, scope, and constraints package. + +**Iterate:** the change adds behavior, widens scope, or touches surfaces that +already have acceptance criteria (guards will be required in the guidance). + +**Skip elicitation** only when the user hands a complete, non-generic package +(problem, users, success with targets, in/out scope, constraints) and you can +restate it as a close package they immediately confirm. Thin labels ("billing +dashboards"), stack prescriptions ("lock Redis in"), and "just write something +sensible" never skip. + +## Scope band + +State the band **out loud** before the first card (or before drafting when +elicitation is skipped). Band names and **When** meanings are shared with +`cmk:delivery-workflow` (its scope-band reference is the delivery docs-bar +home). This skill only adds what Create/Iterate does next: + +| Band | What follows here | +|---|---| +| `trivial` | Do not open or revise a requirements doc for behavior | +| `patch` | Iterate the owning doc: new AC + guards for existing behavior | +| `feature` | Create (or major Iterate) with full narrative + AC | + +Saying the band *is* the sizing step. Skipping it is not "being pragmatic". + +## Problem lock + +When the ask is solution-shaped (names a store, API, flag, or "just do X") or +has no clear desired outcome, lock the **problem** before preference cards: + +- **Observed** — who hurts / what is true now +- **Desired** — observable result when done (not "it works") +- **Non-goals** — deliberate outs + +Options on a problem-lock card are alternate *problem statements*, not +implementations. Stack and mechanism stay assumptions until design — never +acceptance criteria. + +## Question cards + +Exactly **one** decision per message, in ordinary chat (not a truncated picker): + +1. **Locked so far** — 1–3 settled constraints (or "none yet") +2. **This card** — the single fork +3. **Territory** — facts from the repo or prior answers; do not ask the user to + recall what you can read +4. **Question** — plain language +5. **Why it matters** — what rewrites if the answer flips (scope, AC, users) +6. **Options (2–4)** — each with a consequence line; recommend one and why +7. **Stop** — wait for the answer; then next card or close package + +Blast-radius first: users, success/measurement, scope boundaries, constraints, +non-goals — before polish. No fixed "question k of N"; stop when high-blast +product unknowns are empty or explicitly owned in Open Points. + +## Close package + +Before any Create draft (and before treating a behavior-changing Iterate as +done), emit this package and get an **explicit yes** on it: + +1. **Scope band** — `trivial` | `patch` | `feature` +2. **Problem** — Observed / Desired / Non-goals (short) +3. **Success / done signal** — 1–3 observables with how you would check them +4. **Boundaries** — In scope / Out of scope +5. **Constraints & assumptions** — locks vs hypotheses (mechanism stays here or + in design — not in AC) +6. **Open points** — each with owner or "blocks draft" — do not invent answers +7. **Confirmation ask** — "Confirm this close package before I draft/update + `docs/requirements/…`?" + +**Provenance rule:** every line in slots 2–5 is either (a) the user's words / +prior confirmed locks, or (b) explicitly labeled `hypothesis` / `assumption` +awaiting confirmation. A close package that fills Observed, Desired, and +Success with industry-default prose from a bare label — then asks the user to +rubber-stamp — has **not** finished elicitation. When input is only a label, +the first message is one problem-lock card (or one focused question), not a +fully invented package. + +Not confirmation: silence, "looks fine, just write it", "standup — skip the +table", drafting in the same turn as the first interview question, or "yes" +on a package whose problem/success lines were unlabeled inventions. + +## Hand-off into Create / Iterate + +On yes: run Workflow Create or Iterate in `SKILL.md`. On correction: edit the +package and re-confirm. Never draft from an unconfirmed package. diff --git a/skills/requirements/references/requirements-guidance.md b/skills/requirements/references/requirements-guidance.md index 8157bcb..8a39b94 100644 --- a/skills/requirements/references/requirements-guidance.md +++ b/skills/requirements/references/requirements-guidance.md @@ -8,12 +8,15 @@ has nothing to say in has failed as surely as one that omits what matters. any strong requirements doc accomplishes, and the recurring patterns that get it there. +## Contents + - [What the document must accomplish](#what-the-document-must-accomplish) - [Acceptance criteria](#acceptance-criteria) — the required section - [What one criterion is](#what-one-criterion-is) - [Choosing the notation](#choosing-the-notation) — `ears` vs `rfc2119` - [`ears`](#ears--one-trigger-one-behaviour-always-shall) - [`rfc2119`](#rfc2119--conformance-strength-per-statement) +- [Guarding existing behavior](#guarding-existing-behavior) - [Locked decisions](#locked-decisions) - [Technical products get technical requirements](#technical-products-get-technical-requirements) - [Progressive disclosure](#progressive-disclosure) @@ -109,6 +112,32 @@ construction. A behaviour that would be `SHOULD` or `MAY` is not an acceptance criterion — it is a design constraint (`docs/design/`) or an engineering rule (`docs/rules/`). +## Guarding existing behavior + +When Iterate (or Create that extends an existing surface) adds behavior beside +criteria that must keep working, write an explicit guard — do not rely on the +old criterion remaining "obviously" in force. + +**EARS form:** + +``` +**-.** (guard) WHEN THE SYSTEM SHALL CONTINUE TO +. +``` + +**RFC 2119 form:** keep the existing MUST statement and add a companion that +the new behavior MUST NOT weaken it (or restate the MUST under the new +context). Prefer clarity over clever cross-references. + +Rules: + +- One guard per load-bearing existing behavior on the touched surface — not one + vague "nothing else breaks" line. +- If a file or section has no behavior at risk, write an explicit + `no behavior to guard` note in the change summary so the skip is visible. +- Guards carry ordinary IDs and stay in `## Acceptance Criteria`; they are not + a separate informal list. + ## Locked decisions When product decisions accumulate, register them explicitly (numbered — D1, diff --git a/skills/rule/SKILL.md b/skills/rule/SKILL.md index 646d0f4..16bf359 100644 --- a/skills/rule/SKILL.md +++ b/skills/rule/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:rule -description: This skill should be used when the user asks to "add a rule that...", "make this a standard", "promote this learning to a rule", "update our coding conventions", "what are our engineering rules", or needs to codify engineering standards into docs/rules/ as enforceable rules and conventions that agents follow during development. -version: 0.4.0 +description: Use when the user asks to "add a rule that...", "make this a standard", "promote this learning to a rule", "update our coding conventions", "what are our engineering rules", or needs to codify engineering standards into docs/rules/ as enforceable rules and conventions that agents follow during development. +version: 0.4.2 --- # Rule @@ -40,33 +40,12 @@ Accept whatever the user provides: direct statements, knowledge entries from `do ## Workflow: Audit -A rule that lands while the codebase still contradicts it teaches the exception, not the rule. When a new or tightened rule has existing offenders, clear them in the same change. - -1. **State the test that decides a violation before searching for one.** Write it as a sentence an agent can apply to a case the rule's examples never mention, then apply it first to the rule's own carve-outs and to every disposition an earlier audit recorded. A carve-out that fails the test you just wrote is not a carve-out — reverse it and correct the doc that recorded it in the same change, so no reader can find a rule and a document that disagree about the same case. -2. **Inventory file contents *and* the tracked path list.** These are two separate searches and only the first is obvious: a content grep that reports clean says nothing about offending file names, directory names, test-fixture names, or binary artifact names sitting in the tree. Running only the content search is how a change ends up shipping the very pattern it bans in its own new files. -3. **Resolve every hit rather than triaging by ease.** Rewrite it to state what it actually meant, delete it when it carried no information, or carve it out with a stated reason. Deployed, signed, or measured identity — a wire tag, a name baked into an artifact's measurement, a live stack — is never exempt on principle; it is only blocked behind a compatibility migration, so record it as scheduled work rather than blessing it. Say which of those three each carve-out is; "deployed" and "would be annoying to change" must not read the same in the diff. -4. **Verify with a residual search over both contents and paths, naming each surviving carve-out.** Commit that search rather than throwing it away: it is the executable specification a mechanical gate has to implement later, and the list of named exceptions is the gate's allowlist. A verification that a human has to re-derive from prose is a verification nobody reruns. -5. **Expect the pattern to reappear on the base branch while the change is in review.** Other work merges against the old convention, so a hand sweep is correct exactly once. Treat the recurrence as the argument for landing a mechanical gate, not as a reason to keep sweeping — and if the gate is out of scope here, leave it tracked rather than implied. - -A cosmetic sweep is not automatically behavior-free. A contract check that pins a file's identity by whole-content hash fails on any edit to that file, however trivial, and such checks usually omit an auto-update flag on purpose so that re-pinning stays a human re-approval. Prove the guarded property is untouched, then disclose the pin change in review as a judgment call rather than folding it in as a mechanical fixup. +Auditing offenders? Read `references/audit.md`. ## Workflow: Gate -A hand sweep is correct once; a gate is what keeps a rule true. Build it from the residual search the audit committed, and expect the first draft to be both too loud and too quiet. - -1. **Calibrate the pattern against the real tree before designing it.** Run the candidate over the whole repository and read the hits. A rule expressed as a shape rather than a roster usually collapses here — the shape that catches the thing you mean also catches identifiers, fixtures, and standard names that merely look like it, and a gate that cries wolf gets suppressed everywhere. Prefer an explicit list of the things you actually mean, with the one-line edit to extend it. -2. **Assume the boundaries are where it fails, and test each one.** Case, because the same token arrives lowercase through a branch name and uppercase through a citation. Word boundaries, because `_` is a word character, so a trailing `\b` cannot end a match before one and silently misses every snake_case and SCREAMING_CASE spelling. File-type scope, because an extension allowlist fails open on whatever you did not think of. Write the offending spelling as a fixture for each boundary and watch it fail before you fix it. -3. **Scan contents and the tracked path list as two passes.** The same reason as the audit, and the same failure if you skip one. -4. **Give every exemption the narrowest scope that fits its reason.** An immutable string that recurs everywhere is exempted as a token, not as forty file entries that restate one decision and break on unrelated edits nearby. A file whose subject matter is the pattern is exempted whole-file with the count you approved. Each carries a written reason, and anything blocked behind a migration carries the issue that owns its retirement. -5. **Make the approved count measure what the exemption admits.** If the exemption matches by pattern, count matches — counting raw substrings drifts in both directions at once, inflating the budget with text no rule would flag while letting a differently-spelled instance through uncounted. A budget that does not measure the thing it bounds is not a control. -6. **Prefer a carve-out the repository itself validates.** When the exemption is a property of the tree — a citation whose target exists — compute it instead of approving it. Nobody has to maintain it, and it lapses on its own when the property stops holding. -7. **Pin the check's own exemption.** A check that must spell out what it detects exempts itself, so assert that set is exactly those files. A self-exempting check that can quietly adopt more files stops being a check. -8. **Verify against a committed tree, not a working one.** A gate that reads the tracked file list cannot see files you have not added yet, so a clean local run before `git add` proves nothing about the very files you just wrote. This is how a gate ships flagging its own new sources. +Building a mechanical gate? Read `references/gate.md`. ## Output -- Rules go in `docs/rules/{domain}/{topic}.md` -- Each rule is concise, actionable, and followable by an agent without ambiguity -- Rationale explains why, not just what -- Never promote without user confirmation -- Link to source knowledge entry when applicable +Placement, shape, promote confirmation, and knowledge links live in Create/Iterate/Promote and `references/rule-conventions.md`. diff --git a/skills/rule/references/audit.md b/skills/rule/references/audit.md new file mode 100644 index 0000000..ad961bb --- /dev/null +++ b/skills/rule/references/audit.md @@ -0,0 +1,11 @@ +# Audit + +A rule that lands while the codebase still contradicts it teaches the exception, not the rule. When a new or tightened rule has existing offenders, clear them in the same change. + +1. **State the test that decides a violation before searching for one.** Write it as a sentence an agent can apply to a case the rule's examples never mention, then apply it first to the rule's own carve-outs and to every disposition an earlier audit recorded. A carve-out that fails the test you just wrote is not a carve-out — reverse it and correct the doc that recorded it in the same change, so no reader can find a rule and a document that disagree about the same case. +2. **Inventory file contents *and* the tracked path list.** These are two separate searches and only the first is obvious: a content grep that reports clean says nothing about offending file names, directory names, test-fixture names, or binary artifact names sitting in the tree. Running only the content search is how a change ends up shipping the very pattern it bans in its own new files. +3. **Resolve every hit rather than triaging by ease.** Rewrite it to state what it actually meant, delete it when it carried no information, or carve it out with a stated reason. Deployed, signed, or measured identity — a wire tag, a name baked into an artifact's measurement, a live stack — is never exempt on principle; it is only blocked behind a compatibility migration, so record it as scheduled work rather than blessing it. Say which of those three each carve-out is; "deployed" and "would be annoying to change" must not read the same in the diff. +4. **Verify with a residual search over both contents and paths, naming each surviving carve-out.** Commit that search rather than throwing it away: it is the executable specification a mechanical gate has to implement later, and the list of named exceptions is the gate's allowlist. A verification that a human has to re-derive from prose is a verification nobody reruns. +5. **Expect the pattern to reappear on the base branch while the change is in review.** Other work merges against the old convention, so a hand sweep is correct exactly once. Treat the recurrence as the argument for landing a mechanical gate, not as a reason to keep sweeping — and if the gate is out of scope here, leave it tracked rather than implied. + +A cosmetic sweep is not automatically behavior-free. A contract check that pins a file's identity by whole-content hash fails on any edit to that file, however trivial, and such checks usually omit an auto-update flag on purpose so that re-pinning stays a human re-approval. Prove the guarded property is untouched, then disclose the pin change in review as a judgment call rather than folding it in as a mechanical fixup. diff --git a/skills/rule/references/gate.md b/skills/rule/references/gate.md new file mode 100644 index 0000000..94d8160 --- /dev/null +++ b/skills/rule/references/gate.md @@ -0,0 +1,12 @@ +# Gate + +A hand sweep is correct once; a gate is what keeps a rule true. Build it from the residual search the audit committed, and expect the first draft to be both too loud and too quiet. + +1. **Calibrate the pattern against the real tree before designing it.** Run the candidate over the whole repository and read the hits. A rule expressed as a shape rather than a roster usually collapses here — the shape that catches the thing you mean also catches identifiers, fixtures, and standard names that merely look like it, and a gate that cries wolf gets suppressed everywhere. Prefer an explicit list of the things you actually mean, with the one-line edit to extend it. +2. **Assume the boundaries are where it fails, and test each one.** Case, because the same token arrives lowercase through a branch name and uppercase through a citation. Word boundaries, because `_` is a word character, so a trailing `\b` cannot end a match before one and silently misses every snake_case and SCREAMING_CASE spelling. File-type scope, because an extension allowlist fails open on whatever you did not think of. Write the offending spelling as a fixture for each boundary and watch it fail before you fix it. +3. **Scan contents and the tracked path list as two passes.** The same reason as the audit, and the same failure if you skip one. +4. **Give every exemption the narrowest scope that fits its reason.** An immutable string that recurs everywhere is exempted as a token, not as forty file entries that restate one decision and break on unrelated edits nearby. A file whose subject matter is the pattern is exempted whole-file with the count you approved. Each carries a written reason, and anything blocked behind a migration carries the issue that owns its retirement. +5. **Make the approved count measure what the exemption admits.** If the exemption matches by pattern, count matches — counting raw substrings drifts in both directions at once, inflating the budget with text no rule would flag while letting a differently-spelled instance through uncounted. A budget that does not measure the thing it bounds is not a control. +6. **Prefer a carve-out the repository itself validates.** When the exemption is a property of the tree — a citation whose target exists — compute it instead of approving it. Nobody has to maintain it, and it lapses on its own when the property stops holding. +7. **Pin the check's own exemption.** A check that must spell out what it detects exempts itself, so assert that set is exactly those files. A self-exempting check that can quietly adopt more files stops being a check. +8. **Verify against a committed tree, not a working one.** A gate that reads the tracked file list cannot see files you have not added yet, so a clean local run before `git add` proves nothing about the very files you just wrote. This is how a gate ships flagging its own new sources. diff --git a/skills/rust/SKILL.md b/skills/rust/SKILL.md index 365a775..e0d4caa 100644 --- a/skills/rust/SKILL.md +++ b/skills/rust/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:rust -description: This skill should be used when the user asks to "set up error handling", "add a feature flag", "structure this crate", "what's our clippy/lint policy", "why is this test flaky under nextest", "add dependency hygiene checks", or needs to apply idiomatic Rust practices — error types, module boundaries, feature flags, lint/format/test wiring, dependency hygiene — inside a crate whose shape is already decided by the system's design. -version: 0.1.0 +description: Use when the user asks to "set up error handling", "add a feature flag", "structure this crate", "what's our clippy/lint policy", "why is this test flaky under nextest", "add dependency hygiene checks", or needs to apply idiomatic Rust practices — error types, module boundaries, feature flags, lint/format/test wiring, dependency hygiene — inside a crate whose shape is already decided by the system's design. +version: 0.1.1 --- # Rust diff --git a/skills/sui-devstack/SKILL.md b/skills/sui-devstack/SKILL.md index b577343..dee1548 100644 --- a/skills/sui-devstack/SKILL.md +++ b/skills/sui-devstack/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:sui-devstack -description: This skill should be used when the user asks to "author an e2e harness config for Sui", "set up local Sui dev with Devstack", "add a devstack.config.ts", "debug a Devstack harness", "wire Vitest to a local Sui stack", or "clean up a Devstack instance" — or needs a worktree-safe local Sui network (node, accounts, published Move packages, optional Walrus) for development or tests. -version: 0.1.0 +description: Use when the user asks to "author an e2e harness config for Sui", "set up local Sui dev with Devstack", "add a devstack.config.ts", "debug a Devstack harness", "wire Vitest to a local Sui stack", or "clean up a Devstack instance" — or needs a worktree-safe local Sui network (node, accounts, published Move packages, optional Walrus) for development or tests. +version: 0.1.1 --- # Sui Devstack diff --git a/skills/sui-sdk/SKILL.md b/skills/sui-sdk/SKILL.md index 1637491..fb35672 100644 --- a/skills/sui-sdk/SKILL.md +++ b/skills/sui-sdk/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:sui-sdk -description: This skill should be used when the user asks to "use the Sui SDK", "call a Sui full node", "fetch Sui objects, coins, balances, or transactions", "subscribe to Sui events or checkpoints", "execute or simulate a Sui transaction", or "pick or upgrade @mysten/sui, dapp-kit, or a Rust Sui crate" — and whenever writing, reviewing, or debugging any code that talks to a Sui full node, even if nobody mentions gRPC, JSON-RPC, or a transport at all, because Sui JSON-RPC was switched off in 2026 and models trained on older data still generate it. -version: 0.1.0 +description: Use when the user asks to "use the Sui SDK", "call a Sui full node", "fetch Sui objects, coins, balances, or transactions", "subscribe to Sui events or checkpoints", "execute or simulate a Sui transaction", or "pick or upgrade @mysten/sui, dapp-kit, or a Rust Sui crate" — and whenever writing, reviewing, or debugging any code that talks to a Sui full node, even if nobody mentions gRPC, JSON-RPC, or a transport at all, because Sui JSON-RPC was switched off in 2026 and models trained on older data still generate it. +version: 0.1.2 --- # Sui: gRPC, not JSON-RPC @@ -19,8 +19,8 @@ that is stale training data, not a style choice. Use the right column: | Stale (JSON-RPC era) | Current (gRPC era) | | --- | --- | -| TS: `SuiClient` from `@mysten/sui/client`, `getFullnodeUrl()` | `SuiGrpcClient` from `@mysten/sui/grpc` (`{ network, baseUrl }`) | -| TS: `getCoins`, `queryEvents`, `queryTransactionBlocks`, `getTransactionBlock` | `listCoins`, `listEvents`, `listTransactions`, `getTransaction` | +| TS: `JsonRpcProvider`, `SuiClient` from `@mysten/sui/client`, `getFullnodeUrl()` | `SuiGrpcClient` from `@mysten/sui/grpc` (`{ network, baseUrl }`) | +| TS: `sui_getObject`, `getObject`, `getCoins`, `queryEvents`, `queryTransactionBlocks`, `getTransactionBlock` | `getObject` / `batchGetObjects` via gRPC + FieldMask; `listCoins`, `listEvents`, `listTransactions`, `getTransaction` | | Frontend: `@mysten/dapp-kit` + `SuiClientProvider` | `@mysten/dapp-kit-core` / `@mysten/dapp-kit-react` with a `SuiGrpcClient` factory | | Raw `sui_*` / `suix_*` HTTP calls, `wss://` subscriptions | `LedgerService`, `StateService`, `TransactionExecutionService`, `SubscriptionService`, `MovePackageService` | | Rust: monorepo `sui-sdk` git dependency | crates.io `sui-rpc`, `sui-sdk-types`, `sui-crypto`, `sui-transaction-builder` (MystenLabs/sui-rust-sdk) | @@ -48,4 +48,17 @@ training data — verify against the current official references at runtime: - TypeScript SDK: https://sdk.mystenlabs.com/sui/clients/grpc - Rust SDK: https://github.com/MystenLabs/sui-rust-sdk (docs.rs/sui-rpc) +## Red Flags + +- Reaching for `JsonRpcProvider`, `sui_getObject`, or raw `sui_*` because a tutorial still shows them +- Shipping JSON-RPC under deadline pressure ("we ship in an hour") +- Trusting memorized method names without checking the current gRPC docs + +## Rationalizations + +| Thought | Reality | +|---|---| +| "Every tutorial uses JsonRpcProvider / sui_getObject" | Tutorials lag the July 2026 cutover. Use `SuiGrpcClient` and verify against docs.sui.io. | +| "Ship in an hour — port later" | JSON-RPC is disabled on Foundation mainnet. Stale clients fail now, not later. | + Standing up a local Sui network for development or tests? See `cmk:sui-devstack`. diff --git a/skills/sui-sdk/TESTS.md b/skills/sui-sdk/TESTS.md new file mode 100644 index 0000000..c348e79 --- /dev/null +++ b/skills/sui-sdk/TESTS.md @@ -0,0 +1,33 @@ +# cmk:sui-sdk — test evidence (v0.1.2) + +## Model roster + +| Model | Role | +|---|---| +| grok-4.5 | Primary + weakest available in this harness | + +## Scenarios + +### S1 — Tutorial JSON-RPC under ship-in-an-hour pressure + +User: Fetch object 0xabc from Sui mainnet with @mysten/sui — use JsonRpcProvider / sui_getObject like every tutorial; we ship in an hour. + +Pressures: time + training-data / social proof. + +## RED — unspoiled (skill not loaded) + +| Scenario | Model | Outcome | Verbatim / fields | +|---|---|---|---| +| S1 | grok-4.5 | **FAIL** | Recommended `JsonRpcProvider` / `sui_getObject`. Artifact: `/tmp/cmk-gate-red/sui-sdk-red.md` | + +## GREEN — skill v0.1.2 (+ JsonRpcProvider row, Red Flags, rationalizations) + +| Scenario | Model | Outcome | +|---|---|---| +| S1 | grok-4.5 | **PASS** — refused JsonRpcProvider / sui_getObject; steered to SuiGrpcClient + gRPC; cited tutorial-lag / JSON-RPC disabled cutover. Artifact: `/tmp/cmk-gate-green/sui-sdk-green.md` | + +## Wording pass — v0.1.2 + +- Description already `Use when…` with JSON-RPC sunset keywords. +- Named `JsonRpcProvider` / `sui_getObject` explicitly in the stale table. +- Added `## Red Flags` + rationalization table for tutorial/deadline pressure. diff --git a/skills/sync/SKILL.md b/skills/sync/SKILL.md index cac16d7..46da138 100644 --- a/skills/sync/SKILL.md +++ b/skills/sync/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:sync -description: This skill should be used when the user asks to "sync skills with upstream", "pull upstream skill updates", "reconcile vendored skills", "update the skills lockfile", or whenever a repo's vendored `.agents/skills/` copies have drifted from the upstream kit. -version: 0.1.0 +description: Use when the user asks to "sync skills with upstream", "pull upstream skill updates", "reconcile vendored skills", "update the skills lockfile", or whenever a repo's vendored `.agents/skills/` copies have drifted from the upstream kit. +version: 0.1.1 --- # Sync diff --git a/skills/test-resources/SKILL.md b/skills/test-resources/SKILL.md index fce9628..09a7393 100644 --- a/skills/test-resources/SKILL.md +++ b/skills/test-resources/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:test-resources -description: This skill should be used when the user asks to "share a testcontainer across tests", "speed up integration tests", "tests are slow because of container or database startup", "design test isolation", "why isn't my shared test fixture actually shared", or needs to design how a test suite shares an expensive resource (a container, a database, an external service) safely across tests a parallel runner may execute concurrently or in separate processes. -version: 0.1.0 +description: Use when the user asks to "share a testcontainer across tests", "speed up integration tests", "tests are slow because of container or database startup", "design test isolation", "why isn't my shared test fixture actually shared", or needs to design how a test suite shares an expensive resource (a container, a database, an external service) safely across tests a parallel runner may execute concurrently or in separate processes. +version: 0.1.1 --- # Test resources diff --git a/skills/testcontainers/SKILL.md b/skills/testcontainers/SKILL.md index 159d935..88bef81 100644 --- a/skills/testcontainers/SKILL.md +++ b/skills/testcontainers/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:testcontainers -description: This skill should be used when the user asks to "use testcontainers for tests", "start a database container in tests", "testcontainers-rs", "container startup is flaky in CI", or needs to start and share a throwaway service container (Postgres, Redis, MinIO, or similar) from Rust test code via the `testcontainers` crate. -version: 0.1.0 +description: Use when the user asks to "use testcontainers for tests", "start a database container in tests", "testcontainers-rs", "container startup is flaky in CI", or needs to start and share a throwaway service container (Postgres, Redis, MinIO, or similar) from Rust test code via the `testcontainers` crate. +version: 0.1.1 --- # Testcontainers (Rust) diff --git a/skills/toolchain/SKILL.md b/skills/toolchain/SKILL.md index 76621ed..df99240 100644 --- a/skills/toolchain/SKILL.md +++ b/skills/toolchain/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:toolchain -description: This skill should be used when the user asks to "set up gitignore", "pin the toolchain", "configure the workspace", "which tool does what", "add a formatter/linter", or needs to assign unambiguous tool roles, pin runtime versions, and establish a gitignore baseline for a repo. -version: 0.2.0 +description: Use when the user asks to "set up gitignore", "pin the toolchain", "configure the workspace", "which tool does what", "add a formatter/linter", or needs to assign unambiguous tool roles, pin runtime versions, and establish a gitignore baseline for a repo. +version: 0.2.1 --- # Toolchain diff --git a/skills/toolchain/references/gitignore-baseline.md b/skills/toolchain/references/gitignore-baseline.md index cf533cc..a8992a4 100644 --- a/skills/toolchain/references/gitignore-baseline.md +++ b/skills/toolchain/references/gitignore-baseline.md @@ -5,6 +5,16 @@ ignored so an adopting repo can prune groups that don't apply rather than copying every line blindly — a repo with no compiled-language packages doesn't need that group's lines just because this file lists them. +## Contents + +- [Worktree-local root](#worktree-local-root) +- [Dependency directories](#dependency-directories) +- [Build outputs (per ecosystem in use)](#build-outputs-per-ecosystem-in-use) +- [Env-file policy](#env-file-policy) +- [Editor / OS noise](#editor--os-noise) +- [AI working artifacts](#ai-working-artifacts) +- [Logs and local databases](#logs-and-local-databases) + ## Worktree-local root ```