@erclx/aitk 3.13.0 → 3.14.0

package/README.md

@@ -116,7 +116,7 @@ git init
 aitk init
 ```
 
-`aitk init` installs base tooling configs, Claude seeds, governance rules, and snippets in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `aitk standards <name>`, so no corpus is copied into your project. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `aitk tooling list --json` to see the catalog.
+`aitk init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `aitk standards <name>`, so no corpus is copied into your project. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Snippets install only when you name a category with `--snippets <category>`, such as `--snippets essentials`. Run `aitk tooling list --json` to see the catalog.
 
 For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target-projects.md).
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/decision-escalate/REQUIREMENT.md

@@ -15,7 +15,7 @@ A body written around a named tool fails a third way. A session on a surface car
 
 The opposite failure is the one that ships silently. A session that takes a preference decision itself produces work the operator did not ask for and never learns a choice was made, because nothing in the output says a fork was passed.
 
-`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has the toolkit's `snippets/decision-help.md` behind it, which installs into a project as `.claude/snippets/decision-help.md`. The second branch now states how a question is shaped and where it is put, so this skill inherits both and adds only what a batch needs on top of one question.
+`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has the toolkit's `snippets/decision-help.md` behind it, which installs into a project that took snippets as `.claude/snippets/decision-help.md`. The second branch now states how a question is shaped and where it is put, so this skill inherits both and adds only what a batch needs on top of one question.
 
 ## Must
 

package/docs/agents/install-and-sync.md

@@ -363,9 +363,17 @@ which is what makes it scriptable.
 
 `--stack` defaults to `base`, and the default
 does not read as a passed flag, so a bare `aitk init` installs governance and
-still prompts. `--skip` takes `wiki` and `governance`, and warns without aborting
-on any other value. There is no `--standards`, since no run writes a standard
-into the target.
+still prompts. `--skip` takes `wiki`, `governance`, and `snippets`, and warns
+without aborting on any other value. There is no `--standards`, since no run
+writes a standard into the target.
+
+`--snippets` carries no default. A bare `aitk init` installs no snippets and
+reports the domain as skipped, the same way an explicit `--skip snippets`
+does, both naming `aitk snippets install essentials <target>` as the recovery
+command. `--snippets none` is a distinct, deliberate way to reach the same
+zero-file result while still running the step, which is what lets a scripted
+caller assert "install nothing" without depending on an empty string, which
+`aitk snippets install` refuses.
 
 ## Unguarded tooling primitives
 

package/docs/target-projects.md

@@ -70,7 +70,7 @@ Each diagram entry records the commit and date it was last verified against, and
 
 ### Stack decision
 
-The default path is `base`. `aitk init` on `base` installs base tooling configs, Claude seeds, governance core rules, and snippets, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
+The default path is `base`. `aitk init` on `base` installs base tooling configs, Claude seeds, and governance core rules, and scaffolds an empty `.claude/wiki/`. Most projects need nothing more.
 
 Escalate only for real web apps. The `setup-init` skill reads `package.json` and root configs, then picks the matching tooling stack (`vite-react` today) and the matching governance stack (`react`, `astro`, `node`).
 
@@ -84,13 +84,16 @@ Run `aitk tooling list --json` and `aitk gov list --json` to see the current cat
 
 ### Core domains and skips
 
-`aitk init` installs base tooling, Claude workflow, governance, and snippets, and scaffolds `.claude/wiki/`. Governance defaults to the `base` stack, so a bare init carries the rules that route a project. Pass `--stack <name>` to install a framework stack instead.
+`aitk init` installs base tooling, Claude workflow, and governance, and scaffolds `.claude/wiki/`. Governance defaults to the `base` stack, so a bare init carries the rules that route a project. Pass `--stack <name>` to install a framework stack instead.
 
 No standard is written into the project. Each governance rule's authority line names `aitk standards <name>`, which answers from the corpus inside the CLI's own package, and every toolkit skill names the copy in its own plugin root. `aitk markdown audit` needs no standard at all, its ban sets and checkpoints shipping with the package as data.
 
-`governance` and `wiki` are skippable:
+Snippets does not install by default. Pass `--snippets <category>`, such as `--snippets essentials`, to take it. Its own rule describing the `@` reference convention installs alongside it, so a project that declines snippets never receives a rule for a behavior it holds no snippet to exercise.
+
+`governance`, `snippets`, and `wiki` are skippable:
 
 - `--skip governance`: leave `.claude/rules/` empty, so no coding standard loads on a file match. The preview names any `--add` rules the skip drops, and the run prints the `aitk gov install <stack> <path>` command to add rules afterward, carrying those extras so one paste restores what the skip declined.
+- `--skip snippets`: the explicit spelling for what a bare init already does, since `--snippets` carries no default. Both print the `aitk snippets install essentials <path>` command afterward.
 - `--skip wiki`: skip the `.claude/wiki/` scaffold. A target that already carries a root `wiki/` keeps it, since the verb reports that folder rather than migrating it.
 
 The plugin corpus carries runtime behavior rather than reference prose alone, because the pre-publish scan and the branch-slug transform each have a standard of their own, `publish.md` and `slug.md`, cited by the skills that run them.

package/governance/rules/snippets/505-at-references.md

@@ -0,0 +1,9 @@
+---
+description: Execute an @-referenced snippet's instructions immediately using session context
+---
+
+# Snippet reference standards
+
+## Execution
+
+- When a snippet is referenced with `@`, execute its instructions immediately using available session context

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/install-check.sh

@@ -67,7 +67,7 @@ mkdir -p "$TARGET_DIR"
 log_info "Initialized git in $TARGET_DIR"
 
 log_step "Run aitk init"
-(cd "$TARGET_DIR" && AITK_NON_INTERACTIVE=1 bun run "$CLONE_DIR/src/cli.ts" init --stack base 2>&1 | pipe_output) || log_error "aitk init failed"
+(cd "$TARGET_DIR" && AITK_NON_INTERACTIVE=1 bun run "$CLONE_DIR/src/cli.ts" init --stack base --snippets essentials 2>&1 | pipe_output) || log_error "aitk init failed"
 log_info "aitk init completed"
 
 log_step "Assert scaffold"
@@ -80,10 +80,12 @@ log_step "Assert scaffold"
 # reads a standard through `aitk standards <name>`, which resolves against the
 # copy inside the package.
 #
-# The snippets path has to name a slug the default preset still carries, since
-# init resolves snippets through `essentials`. Editing that preset without
-# editing this line fails the gate on a correct install.
-for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
+# Snippets carries no default, so the run above passes `--snippets essentials`
+# explicitly. The snippets path has to name a slug that preset still carries;
+# editing the preset without editing this line fails the gate on a correct
+# install. The rule path confirms the domain's own convention rule installs
+# alongside it, since a target that declined snippets never receives it.
+for path in "CLAUDE.md" ".claude/snippets/decision-help.md" ".claude/rules/snippets/505-at-references.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/core/000-constitution.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/scripts/core/verify.sh

@@ -20,10 +20,14 @@ CHANGED_FILES=""
 SANDBOX_UNDECLARED_CEILING=47
 
 # Rules no stack reaches, space separated and sorted the way `aitk gov list`
-# emits them. Both are opt-in libraries a project may not want, so they are
-# recorded here rather than in a config file: the list is what a reader compares
-# a new arrival against, and a config file would absorb the arrival silently.
-GOV_EXPECTED_UNREFERENCED="260-shadcn 320-tanstack-query"
+# emits them. `260-shadcn` and `320-tanstack-query` are opt-in libraries a
+# project may not want; `505-at-references` ships with no stack on purpose,
+# since a rule under `claude/` would reach every base consumer through the
+# folder-whole entry, and only `aitk snippets install` writes it, alongside
+# the snippets a caller took. All three are recorded here rather than in a
+# config file: the list is what a reader compares a new arrival against, and a
+# config file would absorb the arrival silently.
+GOV_EXPECTED_UNREFERENCED="260-shadcn 320-tanstack-query 505-at-references"
 
 # The retained counts the audit stage compares each run against. Spelled here
 # rather than derived, because this script only ever names the file in a remedy
@@ -292,12 +296,13 @@ main() {
   # A stack entry naming a rule folder takes every rule in it, which is what
   # stops a new rule from needing a second edit to reach a target. The failure
   # it leaves open is a rule authored into a folder no stack names, which
-  # installs for nobody and reports nothing on its own.
+  # `aitk gov install` never reaches on its own, whether or not another domain
+  # installs the file by a different route.
   #
-  # This reports and never fails. Both standing findings are opt-in libraries
-  # this repository ships on purpose, so gating would fail every push over the
-  # deliberate case and teach a reader to route around the stage. Revisit when a
-  # third appears and the pattern is either a library set or an accident.
+  # This reports and never fails. All three standing findings ship this way on
+  # purpose, so gating would fail every push over the deliberate case and teach
+  # a reader to route around the stage. Revisit if the set keeps growing and
+  # the pattern turns out to be an accident rather than a design.
   log_step "Unreferenced rules"
   local gov_json gov_status=0 unreferenced
   gov_json=$(cd "$PROJECT_ROOT" && bun src/cli.ts gov list --json 2>/dev/null) || gov_status=$?
@@ -331,10 +336,10 @@ main() {
     elif [ -z "$unreferenced" ]; then
       log_info "Every rule is reached by a stack"
     elif [ "$unreferenced" = "$GOV_EXPECTED_UNREFERENCED" ]; then
-      log_info "Reached by no stack: $unreferenced (opt-in, install with --add)"
+      log_info "Reached by no stack: $unreferenced (each recorded above with why)"
     else
       log_warn "Reached by no stack: $unreferenced"
-      log_warn "Expected: $GOV_EXPECTED_UNREFERENCED. Name the new rule in a stack, or update GOV_EXPECTED_UNREFERENCED in this script and say why it ships opt-in."
+      log_warn "Expected: $GOV_EXPECTED_UNREFERENCED. Name the new rule in a stack, or update GOV_EXPECTED_UNREFERENCED in this script and say why it reaches no stack."
     fi
   fi
 

package/src/commands/init.ts

@@ -12,7 +12,7 @@ interface InitOptions {
   /** Always present: the option falls back to `DEFAULT_STACK`. */
   readonly stack: string
   readonly add?: string
-  readonly snippets: string
+  readonly snippets?: string
   readonly skip?: string
 }
 

package/src/commands/snippets.ts

@@ -6,6 +6,7 @@ import { BASE_CATEGORY } from '@/snippets/categories'
 import {
   ALL_CATEGORY,
   installSnippets,
+  installSnippetsRule,
   installableCategories,
   resolveSnippets,
 } from '@/snippets/install'
@@ -176,6 +177,9 @@ async function runInstall(
   for (const rel of await installSnippets(resolution.files, resolved)) {
     logAdd(rel)
   }
+  for (const rel of await installSnippetsRule(PROJECT_ROOT, resolved)) {
+    logAdd(rel)
+  }
   await recordStamp(createSnippetsAdapter(PROJECT_ROOT), resolved, new Date())
 
   const { GREEN, NC } = palette(process.stderr)

package/src/init/flags.ts

@@ -29,8 +29,7 @@ export const INIT_OPTIONS: readonly InitOptionSpec[] = [
   {
     key: 'snippets',
     flags: '--snippets <category>',
-    description: "Snippets preset, category, or 'all'",
-    defaultValue: 'essentials',
+    description: "Snippets preset, category, 'none', or 'all'. Omit to skip",
   },
   {
     key: 'skip',

package/src/init/plan.ts

@@ -1,4 +1,4 @@
-export const SKIPPABLE_DOMAINS = ['wiki', 'governance'] as const
+export const SKIPPABLE_DOMAINS = ['wiki', 'governance', 'snippets'] as const
 
 export type SkippableDomain = (typeof SKIPPABLE_DOMAINS)[number]
 
@@ -30,10 +30,23 @@ export interface InitPlan {
 export interface InitFlags {
   readonly stack?: string
   readonly add?: string
-  readonly snippets: string
+  /** Absent when `--snippets` was never passed, which installs none. */
+  readonly snippets?: string
   readonly skip: SkipPlan
 }
 
+/**
+ * Reads why the snippets step will not run, or `undefined` when it will.
+ * Omitting `--snippets` reaches the same skip as `--skip snippets` explicitly,
+ * so a plain `aitk init` installs none and both routes share one recovery
+ * line rather than two behaviors with one spelling each.
+ */
+export function snippetsSkipReason(flags: InitFlags): string | undefined {
+  if (flags.skip.skipped.has('snippets')) return '--skip snippets'
+  if (flags.snippets === undefined) return 'no --snippets given'
+  return undefined
+}
+
 /**
  * Resolves the stack the run will install. An empty `--stack` reads as absent
  * rather than as a way to decline, so the flag carries a real name or nothing
@@ -98,7 +111,11 @@ export function planInit(flags: InitFlags): InitPlan {
     })
   }
 
-  preview.push({ level: 'info', text: `snippets (${flags.snippets})` })
+  if (snippetsSkipReason(flags) !== undefined) {
+    preview.push({ level: 'warn', text: 'snippets (skipped)' })
+  } else {
+    preview.push({ level: 'info', text: `snippets (${flags.snippets})` })
+  }
 
   if (!flags.skip.skipped.has('wiki')) {
     preview.push({

package/src/init/steps.ts

@@ -1,4 +1,4 @@
-import { type InitFlags, resolveStack } from '@/init/plan'
+import { type InitFlags, resolveStack, snippetsSkipReason } from '@/init/plan'
 import type { DomainStep } from '@/init/run'
 
 /** Builds the child-process invocation for one domain. */
@@ -48,11 +48,25 @@ export function buildSteps(
     })
   }
 
-  steps.push({
-    kind: 'run',
-    label: 'Snippets',
-    run: child(['snippets', 'install', flags.snippets, resolved]),
-  })
+  // `snippets === undefined` here can never fire on its own: `snippetsSkipReason`
+  // already returns a reason whenever `flags.snippets` is undefined. It is what
+  // narrows `snippets` to `string` for the child() call below, since TypeScript
+  // cannot narrow a property through a function call.
+  const snippets = flags.snippets
+  const skipReason = snippetsSkipReason(flags)
+  if (skipReason !== undefined || snippets === undefined) {
+    steps.push({
+      kind: 'skip',
+      label: 'Snippets',
+      notice: `Skipped: ${skipReason ?? 'no --snippets given'}. Run 'aitk snippets install essentials ${target}' to install snippets.`,
+    })
+  } else {
+    steps.push({
+      kind: 'run',
+      label: 'Snippets',
+      run: child(['snippets', 'install', snippets, resolved]),
+    })
+  }
 
   if (!flags.skip.skipped.has('wiki')) {
     steps.push({

package/src/snippets/categories.ts

@@ -3,6 +3,8 @@ import { join } from 'node:path'
 import { isDirectory } from '@/target'
 
 export const BASE_CATEGORY = 'base'
+/** A real category resolving to zero entries, for a caller declining on purpose. */
+export const NONE_CATEGORY = 'none'
 
 export function snippetsSourceDir(root: string): string {
   return join(root, 'snippets')
@@ -39,8 +41,13 @@ export function categoryDir(root: string, category: string): string {
  * Tests for a directory rather than mere existence. `snippets/` holds files
  * alongside its category folders, so an argument naming one of them resolves
  * to a real path that cannot be scanned as a category.
+ *
+ * An empty category refuses rather than resolving, since `join(source, '')`
+ * is `source` and would otherwise report the base directory as the category,
+ * widening an unset value to every base entry instead of naming none.
  */
 export function categoryExists(root: string, category: string): boolean {
+  if (category === '') return false
   return isDirectory(categoryDir(root, category))
 }
 

package/src/snippets/install.ts

@@ -7,9 +7,11 @@ import {
   categoryExists,
   listCategories,
   listEntries,
+  NONE_CATEGORY,
   snippetsSourceDir,
 } from '@/snippets/categories'
 import { findPreset, loadPresets } from '@/snippets/presets'
+import { isDirectory } from '@/target'
 
 export const ALL_CATEGORY = 'all'
 
@@ -72,6 +74,15 @@ export function resolveSnippets(
     return { ok: true, step: 'Resolving all categories', files, missing: [] }
   }
 
+  if (category === NONE_CATEGORY) {
+    return {
+      ok: true,
+      step: 'Resolving category: none',
+      files: [],
+      missing: [],
+    }
+  }
+
   const preset = findPreset(root, category)
   if (preset) {
     const files: SnippetFile[] = []
@@ -123,3 +134,39 @@ export async function installSnippets(
 
   return installed
 }
+
+function snippetsRuleSourceDir(root: string): string {
+  return join(root, 'governance', 'rules', 'snippets')
+}
+
+function installedSnippetsRuleDir(target: string): string {
+  return join(target, '.claude', 'rules', 'snippets')
+}
+
+/**
+ * Installs the `@`-reference convention rule alongside the snippets a caller
+ * took. No stack names this folder, so a project that declined snippets never
+ * receives a rule describing a behavior it holds no snippet to exercise.
+ */
+export async function installSnippetsRule(
+  root: string,
+  target: string,
+): Promise<string[]> {
+  const dir = snippetsRuleSourceDir(root)
+  if (!isDirectory(dir)) return []
+
+  const installed: string[] = []
+
+  for (const rel of new Bun.Glob('*.md').scanSync({
+    cwd: dir,
+    onlyFiles: true,
+  })) {
+    await copyPreservingMode(
+      join(dir, rel),
+      join(installedSnippetsRuleDir(target), rel),
+    )
+    installed.push(join('.claude', 'rules', 'snippets', rel))
+  }
+
+  return installed
+}

package/tooling/claude/seeds/CLAUDE.md

@@ -65,10 +65,6 @@
 - When cspell flags a word, rewrite typos. Add real terms to the appropriate dictionary in `cspell.json`.
 - Keep dictionary files sorted alphabetically
 
-## Snippets
-
-- When a snippet is referenced with `@`, execute its instructions immediately using available session context
-
 ## Tasks
 
 - `.claude/tasks/` is gitignored local session scratch, one file per task. Edit freely. No staging or revert before commits.