@erclx/canon 4.127.0 → 5.1.0

package/scripts/snippets/create.sh

@@ -1,156 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-trap close_timeline EXIT
-
-SNIPPETS_SOURCE="$PROJECT_ROOT/snippets"
-
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} canon snippets create"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  Creates a new snippet: prompts for category and name, writes the file."
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}"
-  echo -e "${GREY}└${NC}"
-  exit 0
-}
-
-list_categories() {
-  echo "base (root, no prefix)"
-  find "$SNIPPETS_SOURCE" -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort
-  echo "new category"
-}
-
-slug_error() {
-  local slug="$1"
-  local path="$2"
-  if [ -z "$slug" ]; then
-    echo "name cannot be empty"
-    return
-  fi
-  if [[ ! "$slug" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
-    echo "kebab-case only (e.g. my-snippet)"
-    return
-  fi
-  if [ -f "$path" ]; then
-    echo "file already exists: $path"
-    return
-  fi
-  echo ""
-}
-
-ask_new_category() {
-  while true; do
-    ask "Category name?" "CATEGORY_INPUT"
-    if [ -z "$CATEGORY_INPUT" ]; then
-      log_warn "Category name cannot be empty"
-      continue
-    fi
-    if [[ ! "$CATEGORY_INPUT" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
-      log_warn "Invalid category: kebab-case only (e.g. my-category)"
-      continue
-    fi
-    if [ -d "$SNIPPETS_SOURCE/$CATEGORY_INPUT" ]; then
-      log_warn "Category '$CATEGORY_INPUT' already exists"
-      continue
-    fi
-    CATEGORY_NAME="$CATEGORY_INPUT"
-    break
-  done
-}
-
-ask_name() {
-  local category="$1"
-  local is_base="$2"
-  local label
-  local error
-
-  label="Snippet name?"
-
-  while true; do
-    ask "$label" "NAME_INPUT"
-    local dest_path
-    if [ "$is_base" = "true" ]; then
-      dest_path="$SNIPPETS_SOURCE/$NAME_INPUT.md"
-    else
-      dest_path="$SNIPPETS_SOURCE/$category/$NAME_INPUT.md"
-    fi
-    error=$(slug_error "$NAME_INPUT" "$dest_path")
-    if [ -z "$error" ]; then
-      NAME="$NAME_INPUT"
-      break
-    fi
-    log_warn "Invalid name: $error"
-  done
-}
-
-cmd_create() {
-  local categories=()
-  mapfile -t categories < <(list_categories)
-
-  select_option "Category?" "${categories[@]}"
-  local selected="$SELECTED_OPTION"
-
-  local category
-  local is_base="false"
-
-  if [ "$selected" = "base (root, no prefix)" ]; then
-    is_base="true"
-    category="base"
-  elif [ "$selected" = "new category" ]; then
-    ask_new_category
-    category="$CATEGORY_NAME"
-  else
-    category="$selected"
-  fi
-
-  ask_name "$category" "$is_base"
-  local name="$NAME"
-
-  local dest_path
-  local install_path
-  if [ "$is_base" = "true" ]; then
-    dest_path="$SNIPPETS_SOURCE/$name.md"
-    install_path="snippets/$name"
-  else
-    dest_path="$SNIPPETS_SOURCE/$category/$name.md"
-    install_path="snippets/$category/$name"
-  fi
-
-  log_info "Installs as: @${install_path}"
-
-  log_step "Creating file"
-
-  if [ "$is_base" = "false" ]; then
-    mkdir -p "$SNIPPETS_SOURCE/$category"
-  fi
-
-  printf '<!-- TODO: write %s prompt -->\n' "$slug" >"$dest_path"
-
-  if [ "$is_base" = "true" ]; then
-    log_add "snippets/$name.md"
-  else
-    log_add "snippets/$category/$name.md"
-  fi
-}
-
-main() {
-  if [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
-    show_help
-  fi
-
-  cmd_create
-
-  trap - EXIT
-  echo -e "${GREY}└${NC}\n"
-  echo -e "${GREEN}✓ Snippet created${NC}"
-}
-
-main "$@"

package/snippets/align.md

@@ -1,12 +0,0 @@
-Check alignment before acting, not after. State three lines, then proceed.
-
-- Outcome: what will be true when this is done
-- Scope: what this deliberately does not touch
-- Assumption: the one inference that would change the work if it is wrong
-
-Act without waiting, unless being wrong about the assumption wastes the work rather than costing an edit.
-
-- Three lines, not three paragraphs
-- Name the inference you are least sure of, not the safest one
-- Do not ask what the request already answers
-- Silence is agreement

package/snippets/claude/decision-memo.md

@@ -1,39 +0,0 @@
-Produce a decision memo for a research or should-we question. This is the decision-heavy counterpart to `plan-feature`, which plans a build. Write one file per independent concern under `.canon/plans/feature-<slug>.md`, or answer inline when the plan is small. Use the same plans folder as `plan-feature`.
-
-Read the current state from the code and docs before recommending. Do not assume it.
-
-Output this shape per memo:
-
-```markdown
-# <slug title>
-
-<the question in one or two lines>
-
-## Summary
-
-- <goal in one line>
-- <deliverables in one line>
-- <key tradeoff in one line>
-
-## Finding
-
-<what the current state actually is, from reading the code and docs>
-
-## Item A: <decision>
-
-**Current state.** <what exists today>
-
-**Recommendation.** <the pick, with the tradeoff in one sentence>
-
-**Options.** <the real alternatives, only when the choice is the user's to make>
-
-**Feasibility.** <what is not buildable as asked and why, omit when all options are buildable>
-
-**Questions.**
-
-1. <question>
-   - Suggested: <best-practice default derived from context>
-   - Answer:
-```
-
-Repeat the `## Item` block per decision. Keep chat to the file pointer plus the questions. Recommend, do not enumerate, unless the user's preference is the deciding factor.

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
-```