/sdlc:standard-new

Generated from solutions/ontological/skills/standard-new/SKILL.md.

Description

Interactively define a new standard — a prescriptive statement about the codebase (architectural rule, design convention, style requirement, or workflow expectation). Walk the user through slug, title, status, applies_to.paths scope, and optional supersession links; create the file via sdlc standard create (which auto-assigns an immutable S id); validate the frontmatter; report the path. Optionally also capture prose for Rule / Why / How to apply and Edit them into the file.

Allowed tools

• Bash
• Read
• Edit
• AskUserQuestion

Source

Usage:

• /sdlc:standard-new — start the interview. End state: a validated standard file at docs/planning/standards/S<NNNN>-<slug>.md under the project root.

References:

• ${CLAUDE_PLUGIN_ROOT}entities/standard/definition.md — storage path, id+slug filename convention, sdlc standard create as canonical writer, validator usage, supersession-over-rewriting rule, when-to-spawn-a-standard guidance. Read this once per project — it governs every skill that writes standard files.

1. Title and slug

Ask the user in plain text: “What’s the title for this standard? (One imperative line — what the rule says.)” Skip if the user already gave one in their invocation message.

The slug is optional: standard create derives it from --title via the shared deriveSlug (capped at 60 chars) when no explicit slug is passed, so for the common case you can skip the slug question entirely and let create derive it in step 5. Only ask for a slug when the user wants to name the file deliberately (a slug that differs from the title’s derivation):

“What’s the slug for the filename? (kebab-case, e.g. co-locate-first-promote-when-shared. The filename will be S<NNNN>-<slug>.md. Leave blank to derive it from the title.)”

If the user supplies an explicit slug, validate it against SLUG_RE from ${CLAUDE_PLUGIN_ROOT}lib/util/slug.ts (the canonical kebab-case matcher) before continuing; if it fails, re-ask with the rule restated. (No validation needed when the slug is derived — deriveSlug always emits a conforming slug.)

To show the user the would-be id and slug before creating — or to surface a same-slug collision or near-miss — run the read-only preview first:

${CLAUDE_PLUGIN_ROOT}cli/sdlc standard preview-id "<title>"

It prints PREVIEW-ID standard slug=<slug> id=<id> exists=<bool> similar=<n> (add --output json for structure: slug, id, exists, exact_match, similar[], warning). The slug it reports is byte-identical to the one create will assign with --slug omitted. Use it when the user asks “what will this be called?” or when you want to warn about an existing/similar standard before writing.

2. Triage (one AskUserQuestion call)

Send a single AskUserQuestion with these questions:

1. Status — header “Status”. Options (the schema enum, see ${CLAUDE_PLUGIN_ROOT}entities/standard/schema.ts): open/proposed (drafted, not yet in force — the create-op default), open/draft (early WIP), open/active (in force), closed/superseded (replaced by another standard — must point at the replacement), closed/deprecated (no longer applicable, kept for history). Default open/proposed.
2. Scope — header “Scope”. Options: Broadly applicable (no applies_to set), Path-scoped (will prompt for globs). Most workflow standards are broad; style/architectural rules tied to specific code areas are path-scoped.

3. Paths (only if Scope was “Path-scoped”)

Ask plain text: “Glob patterns this standard governs, comma-separated. Examples: **/*.vue, plugin/skills/**, src/components/**/*.tsx.”

Pass each value via repeated --paths flags. Globs are not regex; the CLI does not validate the shape beyond non-emptiness, so a malformed glob will silently match nothing — confirm with the user that the pattern matches the files they have in mind before continuing.

4. Supersession (only if Status was closed/superseded)

Ask plain text: “Which standard does this replace? (id S-NNNN, or S-NNNN-slug)”

Wrap the id as a [[...]] wikilink yourself and pass it via --superseded-by (e.g. --superseded-by '[[S-0007-co-locate-first]]') — the create op forwards the value straight into frontmatter, it does not add the brackets. The create command in step 5 schema-validates the superseded_by shape and exits non-zero with the reason if the value is malformed or unwrapped, so re-ask and re-run on failure rather than pre-validating the id here.

The predecessor’s own frontmatter does NOT update as a side effect of creating the successor. After step 5 succeeds, mark the predecessor superseded in one call:

${CLAUDE_PLUGIN_ROOT}cli/sdlc standard supersede <predecessor-id> --by <new-id>

This sets status: closed/superseded and superseded_by: [[<new-id>]] on the predecessor, schema-validated before the write. It no-ops gracefully (exit 0, superseded:false) when the predecessor file does not resolve — so a never-created predecessor is harmless — and is idempotent when the predecessor is already superseded by the same successor.

5. Create the file

Run (the <slug> positional is optional — omit it to let create derive the slug from --title; pass it only when the user named the standard deliberately in step 1):

${CLAUDE_PLUGIN_ROOT}cli/sdlc standard create [<slug>] \
  --title "<title>" \
  --created "$(date -u +%Y-%m-%d)" \
  --status <status> \
  [--paths <glob>]... \
  [--superseded-by '[[S-NNNN-slug]]'] \
  [--supersedes '[[S-NNNN-slug]]'] \
  [--related '[[<ref>]]']...

The command outputs JSON; capture the path field for the new file (the assigned id is visible in the filename). When <slug> is omitted the derived slug is in that filename too.

If the command exits non-zero, report the error verbatim. The most common failure is a malformed slug or --related value — fix and re-run.

6. Optional: flesh out the body inline

Ask once via AskUserQuestion: “Fill in Rule / Why / How to apply now, or leave the placeholders for later?”

If “now”: for each section, ask in plain text for the content, then use Edit to replace the matching <...> placeholder block in the file with the user’s text. Leave a section’s placeholders intact if the user explicitly skips it. Headers (## Rule, etc.) stay; only the placeholder body changes.

If “later”: don’t touch the body.

7. Validate

${CLAUDE_PLUGIN_ROOT}cli/sdlc entities validate <path-from-step-5>

If validation fails, report the error verbatim and walk the user through fixing it.

8. Report

Tell the user:

• The absolute path of the new file (the assigned id is in the filename).
• One line: <id> · <status> · <scope-summary> — <title>, where scope-summary is either broadly applicable or the list of glob patterns.
• Next-step pointer:
  • If the standard is path-scoped, suggest verifying the globs match the intended files (e.g. git ls-files <glob>).
  • If the standard was created in supersession, confirm step 4’s standard supersede call reported superseded:true; if it returned superseded:false (the predecessor file did not resolve), tell the user the predecessor was not found and its frontmatter is unchanged.

Acceptance criteria

• File exists at docs/planning/standards/S<NNNN>-<slug>.md under the project root with an auto-assigned id.
• Frontmatter passes sdlc entities validate with zero errors.
• The title is set both in frontmatter title: and in the body # ... line (no <Title> placeholder remains).
• If the standard was created with --status closed/superseded, superseded_by is set.
• The path was reported back to the user.

Notes

• This skill never writes frontmatter by hand. sdlc standard create is the writer. To change a frontmatter value after creation, edit the file directly or — for material rule changes — file a new standard and link via supersedes / superseded_by rather than rewriting in place. See ${CLAUDE_PLUGIN_ROOT}entities/standard/definition.md for the supersession-over-rewriting rule.
• Keep the conversation short. If the user packed everything into the first invocation message (“new standard: co-locate-first, status open/active, applies to plugin/skills/**”), skip the AskUserQuestion calls and go straight to step 5.