@erclx/canon 4.126.0 → 5.1.0

package/snippets/claude/feature-recap.md

@@ -1,19 +0,0 @@
-Recap the implementation this session completed. Read the plan file referenced in the session (usually `.canon/plans/feature-<slug>.md`) and produce a verification block.
-
-Output this shape, nothing else:
-
-```markdown
-**Deliverable 1**: <name from the plan>
-
-- `path/to/file`: one-line reason
-
-**Deliverable 2**: <name from the plan>
-
-- `path/to/file`: one-line reason
-
-**Verified**: <what was smoke-tested or `Nothing tested in session.`>
-
-**Open**: <unresolved questions, deferred items, or `None.`>
-```
-
-Group files by deliverable, not by directory. Keep each line scannable. Do not restate the plan body.

package/snippets/claude/figma-steps.md

@@ -1,24 +0,0 @@
-Read the relevant spec from `canon/DESIGN.md` and any other design files needed. Write step-by-step Figma instructions to produce the component exactly.
-
-For each step, specify:
-
-- The exact tool or keyboard shortcut to activate
-- Which panel or field to click
-- The exact value to enter
-
-When a step has multiple sub-actions or lists several items, use nested bullets instead of stacking them in one sentence.
-
-Cover in order:
-
-- Frame or group setup (dimensions, corner radius, fill)
-- Each layer or shape (type, size, position, fill, stroke)
-- Alignment and spacing rules
-- Export settings
-
-Throughout:
-
-- Use exact values from the spec
-- Do not restate design rationale
-- Use Title Case for all layer and frame names
-- Use Figma terminology throughout, not code or CSS equivalents
-- Reuse existing frames or components from the same Figma document by name instead of rebuilding from scratch

package/snippets/compact-summary.md

@@ -1,5 +0,0 @@
-Summarize the research or findings above into a compact, scannable block.
-
-- State the main takeaways directly
-- Skip background context the reader already has
-- Use short headings and tight bullets where multiple items exist

package/snippets/decision-help.md

@@ -1,6 +0,0 @@
-Apply senior-level judgment. Pick the best option from the discussion so far. State the pick in one sentence, then the reason and the main tradeoff in one or two sentences.
-
-- Minimal and necessary only
-- No nice-to-haves
-- No padding
-- No alternatives unless they change the recommendation

package/snippets/meta-prompt.md

@@ -1,14 +0,0 @@
-Turn the idea below into a production-grade system prompt.
-
-Give it a role of one to three lines, a constraints section, and an output format carrying a template plus one worked example. Add a validation checklist when the prompt involves multi-step logic, edge cases, or error handling. Omit that checklist for a single-purpose prompt.
-
-Group constraints under domain headings when they span two or more domains and total five or more. Use flat must-do and must-not-do lists otherwise. Keep dos and don'ts together under the topic they belong to.
-
-Use `{{DOUBLE_BRACES}}` for values the end user fills in at runtime.
-
-Constraints:
-
-- Use imperative voice. Write `Do X`, never `You should` or `Try to`.
-- Make every constraint verifiable from the output. Reject subjective qualifiers like `appropriate`, `concise`, or `well-structured`.
-- Match prompt length to task complexity. A single-purpose task gets a minimal prompt.
-- Never write `maybe`, `consider`, or `depending on`. Be definitive.

package/snippets/research-prompt.md

@@ -1,7 +0,0 @@
-Generate a self-contained research prompt for another AI chat. Include:
-
-- State what I am trying to do and why
-- List what I have already tried and the results
-- Specify questions that need answers
-
-Write it in first person. Assume the reader has no context from this session.

package/snippets/session-notes.md

@@ -1,11 +0,0 @@
-Write session notes for this conversation using this format:
-
-```markdown
-# Session notes: <topic>
-
-## <title>
-
-<what was decided and why>
-```
-
-Only include decisions made in this session. Output only the markdown block, nothing else.

package/snippets/snippets.toml

@@ -1,5 +0,0 @@
-[essentials]
-names = [
-    "align",
-    "decision-help",
-]

package/snippets/step-by-step.md

@@ -1,10 +0,0 @@
-Give me step-by-step instructions.
-
-For each step:
-
-- State what to do in one sentence.
-- Include the exact value, command, or input where precision matters.
-- Note any output to save or verify before moving on.
-- When the step has multiple sub-actions or lists several items, use nested bullets instead of stacking them in one sentence.
-
-Group related steps under a heading if the process has distinct phases. Flag any step that is irreversible or that blocks later steps.

package/snippets/web-research.md

@@ -1,21 +0,0 @@
-Search the web for the topic or question added after this snippet. Fetch the most relevant pages. Synthesize findings into a decision-ready block using this format:
-
-```markdown
-Topic: [what was researched]
-Recommendation: [one clear answer or choice]
-
-Options considered:
-
-- [Option A]: why considered, why chosen or rejected
-- [Option B]: why considered, why chosen or rejected
-
-Key constraints:
-
-- [constraint that shaped the decision]
-
-Sources:
-
-- [URL]: what it confirmed
-```
-
-Output only the block. Do not add commentary before or after it.

package/src/commands/snippets.ts

@@ -1,90 +0,0 @@
-import type { Command } from 'commander'
-import { registerPassThroughVerbs } from '@/commands/pass-through'
-import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
-import { BASE_CATEGORY } from '@/snippets/categories'
-import { buildSnippetsCatalog } from '@/snippets/list'
-import { intro, logInfo, logStep, logWarn, outro } from '@/ui'
-
-const PASS_THROUGH_VERBS = ['create'] as const
-
-interface ListOptions {
-  readonly categories?: boolean
-  readonly entries?: boolean
-  readonly json?: boolean
-}
-
-export function register(program: Command): void {
-  const snippets = program
-    .command('snippets')
-    .description('Snippets commands (create, list)')
-    .helpOption('-h, --help', 'Show this help message')
-
-  snippets
-    .command('list')
-    .description('List snippet presets, categories, and entries')
-    .helpOption('-h, --help', 'Show this help message')
-    .option('--categories', 'Only list presets and category names')
-    .option('--entries', 'Only list entry slugs grouped by category')
-    .option('--json', 'Emit machine-readable JSON')
-    .action((opts: ListOptions) => {
-      process.exitCode = runList(opts)
-    })
-
-  registerPassThroughVerbs(snippets, 'snippets', PASS_THROUGH_VERBS)
-}
-
-/**
- * `JSON.stringify` replaces a `printf` template that interpolated names into a
- * JSON string literal unescaped, so a slug or category carrying a quote emitted
- * output no consuming skill could parse.
- *
- * The frame opens after the `--json` return, since the bash verb only ever
- * emitted section headers and the pass-through above it owned the `┌`.
- */
-function runList(opts: ListOptions): number {
-  // The warning is a frame-interior line, so it goes out after `intro` on the
-  // path that opens one and bare on the `--json` path, which returns first and
-  // opens none. One position cannot serve both.
-  const mismatch = checkoutMismatchWarning(process.cwd())
-  const catalog = buildSnippetsCatalog(PROJECT_ROOT)
-
-  if (opts.json) {
-    if (mismatch !== undefined) logWarn(mismatch)
-    process.stdout.write(`${JSON.stringify(catalog)}\n`)
-    return 0
-  }
-
-  intro('canon snippets list')
-  if (mismatch !== undefined) logWarn(mismatch)
-
-  const showCategories = opts.entries !== true
-  const showEntries = opts.categories !== true
-
-  if (showCategories) {
-    if (catalog.presets.length > 0) {
-      logStep('Presets')
-      for (const preset of catalog.presets) {
-        logInfo(`${preset.name} (${preset.slugs.length} entries)`)
-      }
-    }
-
-    logStep('Categories')
-    for (const category of catalog.categories) {
-      logInfo(`${category.name} (${category.entries.length} entries)`)
-    }
-  }
-
-  if (showEntries) {
-    logStep('Entries')
-    for (const category of catalog.categories) {
-      for (const entry of category.entries) {
-        logInfo(
-          category.name === BASE_CATEGORY ? entry : `${category.name}/${entry}`,
-        )
-      }
-    }
-  }
-
-  outro()
-  return 0
-}

package/src/snippets/categories.ts

@@ -1,66 +0,0 @@
-import { readdirSync } from 'node:fs'
-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')
-}
-
-/**
- * Lists the folder categories. `base` is the synthetic name for snippets
- * sitting directly under `snippets/`, so it is not a directory and callers
- * prepend it themselves.
- *
- * Nothing is filtered: toolkit-internal snippets are authored under `internal/`,
- * which this never reads, so every category found here is publishable.
- */
-export function listFolderCategories(root: string): string[] {
-  const dir = snippetsSourceDir(root)
-  if (!isDirectory(dir)) return []
-
-  return readdirSync(dir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .sort()
-}
-
-export function listCategories(root: string): string[] {
-  return [BASE_CATEGORY, ...listFolderCategories(root)]
-}
-
-export function categoryDir(root: string, category: string): string {
-  const source = snippetsSourceDir(root)
-  return category === BASE_CATEGORY ? source : join(source, category)
-}
-
-/**
- * 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))
-}
-
-/**
- * Lists one category's entry slugs. Only the immediate level is read, matching
- * the `find -maxdepth 1` the bash used, so a nested folder is its own category
- * rather than part of its parent.
- */
-export function listEntries(root: string, category: string): string[] {
-  const dir = categoryDir(root, category)
-  if (!isDirectory(dir)) return []
-
-  return [...new Bun.Glob('*.md').scanSync({ cwd: dir, onlyFiles: true })]
-    .map((name) => name.slice(0, -'.md'.length))
-    .sort()
-}

package/src/snippets/list.ts

@@ -1,32 +0,0 @@
-import { listCategories, listEntries } from '@/snippets/categories'
-import { loadPresets } from '@/snippets/presets'
-
-export interface CategoryCatalogEntry {
-  readonly name: string
-  readonly entries: readonly string[]
-}
-
-export interface SnippetsCatalog {
-  readonly presets: readonly {
-    readonly name: string
-    readonly slugs: readonly string[]
-  }[]
-  readonly categories: readonly CategoryCatalogEntry[]
-}
-
-/**
- * Builds the catalog both output modes read, so the human list and the `--json`
- * one cannot describe different corpora.
- */
-export function buildSnippetsCatalog(root: string): SnippetsCatalog {
-  return {
-    presets: loadPresets(root).map((preset) => ({
-      name: preset.name,
-      slugs: preset.slugs,
-    })),
-    categories: listCategories(root).map((name) => ({
-      name,
-      entries: listEntries(root, name),
-    })),
-  }
-}

package/src/snippets/presets.ts

@@ -1,50 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { snippetsSourceDir } from '@/snippets/categories'
-
-export interface Preset {
-  readonly name: string
-  readonly slugs: readonly string[]
-}
-
-export function presetsPath(root: string): string {
-  return join(snippetsSourceDir(root), 'snippets.toml')
-}
-
-/**
- * Reads every preset from `snippets.toml`. The bash read section headers with
- * `grep '^\['` and then re-walked the file per preset with a `BASH_REMATCH`
- * loop, so a name carrying a bracket or a slug split across lines parsed by
- * accident rather than by rule.
- */
-export function loadPresets(root: string): Preset[] {
-  const path = presetsPath(root)
-  if (!existsSync(path)) return []
-
-  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
-    string,
-    unknown
-  >
-  const presets: Preset[] = []
-
-  for (const [name, table] of Object.entries(parsed)) {
-    if (typeof table !== 'object' || table === null || Array.isArray(table)) {
-      continue
-    }
-    const names = (table as Record<string, unknown>).names
-    presets.push({
-      name,
-      slugs: Array.isArray(names)
-        ? names.filter(
-            (slug): slug is string => typeof slug === 'string' && slug !== '',
-          )
-        : [],
-    })
-  }
-
-  return presets.sort((left, right) => left.name.localeCompare(right.name))
-}
-
-export function findPreset(root: string, name: string): Preset | undefined {
-  return loadPresets(root).find((preset) => preset.name === name)
-}

package/standards/snippets.md

@@ -1,76 +0,0 @@
----
-title: Snippet reference
-description: Snippet reference and authoring conventions
----
-
-# Snippet reference
-
-## Scope
-
-Governs a snippet file: what one is for, whether a prompt qualifies as one, how it is invoked, and the structure of its body.
-
-Does not govern:
-
-- Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
-- Voice, rhythm, and sentence construction in snippet prose: the `write-human` skill
-- Punctuation, formatting, and word choice in snippet prose: `markdown.md`
-
-## What a snippet is
-
-A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.
-
-## Admission
-
-Two tests decide whether a prompt becomes a snippet, and both have to pass. Apply them when adding one and when auditing the catalog.
-
-- Cadence: a prompt invoked many times across sessions qualifies. A one-shot audit, migration, or bootstrap prompt does not, and belongs in notes outside the catalog.
-- Audience: a prompt the consuming project would invoke ships in `snippets/`. One only the authoring repository can run stays outside every installable folder, which is a rule for a repository that authors snippets for others rather than for one that only consumes them.
-
-A subfolder under `snippets/` names where a prompt is invoked rather than what it is about. A prompt that reads or writes the project's own files goes in a folder, and one carrying its whole context in the message goes at the root.
-
-Overlapping a skill that does the same job is not disqualifying on its own. A snippet fires when a person asks for it by name and a skill fires on a description match, so the two coexist when those paths differ and the outputs do. Record the reason where the project keeps its decisions, or drop the snippet.
-
-## Invocation channels
-
-- Chrome extension: type `>slug` in a supported chat UI (claude.ai, gemini.google.com) to insert the snippet text inline
-- Claude Code terminal: prefix the plugin path with `@` (e.g. `@claude/snippets/claude/feature-recap`). `claude/snippets` is a symlink to the authoring root, so the folder a snippet is written in is the folder it is invoked from
-
-## Use patterns
-
-- Run-as-is: invoke and send immediately. The snippet is self-contained and needs no extra context.
-- Invoke-then-add-context: invoke the snippet, then append specifics in the same message (e.g. invoke `plan-feature`, then add the feature name or extra constraints)
-- Invoke-on-history: invoke after a discussion. The snippet uses prior conversation as implicit context with no additional input needed (e.g. invoke `claude-figma` after discussing a design).
-
-## Authoring
-
-- One focused purpose per snippet. If it needs headers or multiple goals, use a system prompt instead.
-- Self-contained. No references to external files or assumed prior context.
-- No user fill-in placeholders. If a value depends on context, the user adds it after invocation.
-- Plain markdown only. No YAML frontmatter, no headers, no nested structure.
-- Filename is the slug: kebab-case, no capitals, no underscores
-
-## Structure
-
-- Lead with a verb. Open with an imperative that states the job immediately.
-- One instruction per sentence. Do not stack multiple actions into one sentence.
-- For sequential steps, use a numbered list with one action per item.
-- When the output has a fixed shape, show it in a fenced code block with a language identifier.
-- Put constraints and exclusions last, not inline with the main instructions.
-
-## Examples
-
-### Correct
-
-```markdown
-I want to implement the following. Scan relevant files and list conflicts. Do not implement. # user adds feature after invocation
-Scan relevant files and list conflicts. Do not implement. # run-as-is, no context needed
-```
-
-### Incorrect
-
-```markdown
-I want to implement: <feature or task name> # redundant fill-in, add context after invocation instead
-See ARCHITECTURE.md before starting. # external dependency, not self-contained
-
-## Overview\n## Steps # headers belong in a system prompt, not a snippet
-```