@erclx/canon 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Eric Le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# canon
+
+[![npm version](https://img.shields.io/npm/v/@erclx/canon)](https://www.npmjs.com/package/@erclx/canon)
+[![CI status](https://img.shields.io/github/actions/workflow/status/erclx/canon/verify.yml?branch=main)](https://github.com/erclx/canon/actions/workflows/verify.yml)
+[![License MIT](https://img.shields.io/npm/l/@erclx/canon)](LICENSE)
+
+One source for your repos' AI conventions. Install once, sync everywhere.
+
+![The canon catalog, listing skills, governance rules, and standards with the count each ships, the workflow skills named, and a sample of the rule and standard names](assets/hero.png)
+
+If you work across more than one repository and your AI setup has started to drift between them, this is for you. The counts above are read from the catalogs when the image is built, so they're what the repo actually ships today.
+
+## Install
+
+Add the marketplace, then install the Claude Code plugin.
+
+```bash
+claude plugin marketplace add https://github.com/erclx/canon
+claude plugin install canon@canon
+```
+
+![Adding the canon marketplace and installing the plugin in Claude Code](assets/install.png)
+
+The skills land as `/canon:<name>`. If your session was already open, run `/reload-plugins` to pick them up.
+
+Several skills call the `canon` CLI to read catalogs and run installs, and the plugin doesn't put it on your path. Install it from the registry.
+
+```bash
+bun install --global @erclx/canon
+```
+
+[Bun](https://bun.sh) is the CLI runtime and has to be on your path first. Confirm the install by resolving `canon --help`.
+
+## Update
+
+Nothing refreshes on its own. Claude Code ships auto-update off for third-party marketplaces, so an installed copy serves whatever version it was installed at until you refresh it.
+
+```bash
+claude plugin marketplace update canon
+claude plugin update canon@canon
+canon upgrade
+```
+
+The first two update the skills, the third updates the CLI, and they move independently. Restart Claude Code, or run `/reload-plugins`, to pick the skills up.
+
+`canon upgrade` reads the package manager off its own install path and reinstalls with that one, so you don't have to remember which put it there. It names what it detected before it runs anything, and it refuses a source checkout rather than reinstalling over your clone.
+
+You don't have to wait until something breaks to find out you're behind. `canon sync --check` and `canon claude skills drift` both report the installed version against the newest published one, and neither changes its exit code over it, so an offline machine reads unknown rather than red.
+
+To stop doing this by hand, turn auto-update on once under `/plugin` in the Marketplaces tab. Confirm what you are running with `canon --version` and `claude plugin list`.
+
+## Why
+
+Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.
+
+Three design choices shape the toolkit.
+
+- Agent-first: every command has a non-interactive path and a JSON catalog. If a Claude Code skill or any other agent cannot drive the CLI without prompts, the design is wrong.
+- Text-native: conventions, rules, and prompts are authored as markdown that you and your agents read the same way. No hidden behavior, no compiled state.
+- One source, many consumers: this repo is the authoritative copy. Your projects install and sync on demand, never author in place.
+
+Two limits worth knowing before you install. Claude Code is the only agent runtime the plugin targets, and the CLI needs Bun on your path. Snippets are the one surface that also travels to Gemini chat.
+
+## What is inside
+
+Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it, so skip them on a first pass.
+
+- [Claude Code plugin](.claude/context/claude-plugin/index.md): skills for planning, review, docs sync, and the git ship chain
+- [Governance rules](.claude/context/governance/index.md): Claude rules and stacks, installable per project
+- [Standards](.claude/context/standards/index.md): shared authoring conventions, read by name rather than installed
+- [Snippets](.claude/context/snippets.md): reusable prompts for Claude and Gemini chat
+- [Tooling stacks](.claude/context/tooling.md): golden configs, seeds, and references per framework
+- [Design system](.claude/context/design.md): `DESIGN.md` token shape, extract skill and its two paths, render command
+- [Slides](.claude/context/slides.md): `SLIDES.md` source, layout catalog, render command, draft skill
+- [Transcripts](.claude/context/transcripts.md): fetch a YouTube transcript with metadata frontmatter via `canon transcripts`
+- [Sandbox](.claude/context/sandbox/index.md): scenario-based scaffolds for verifying each domain flow
+
+## Documentation
+
+Scaffolding your first project? Start with target projects, then the AI workflow loop. Everything else answers questions that arrive later.
+
+- [AI workflow](docs/ai-workflow.md): feature-development loop inside a toolkit-managed project
+- [Operating model](docs/operating-model.md): orchestrator and worker roles for building across parallel sessions
+- [Visual design workflow](docs/visual-design-workflow.md): tiered guide for design and wireframe authoring
+- [Target projects](docs/target-projects.md): scaffold, add a domain later, sync upstream drift
+- [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes
+- [Docs index](docs/index.md): every reference doc in this repo
+
+## Development
+
+Working on the toolkit starts from a clone. Running the CLI doesn't, since it installs from the registry. Skip this section unless you're changing the toolkit itself.
+
+### Prerequisites
+
+- [Bun](https://bun.sh) for the CLI runtime and scripts
+- [Git](https://git-scm.com) with worktree support
+- [GitHub CLI](https://cli.github.com) (optional) for ship flows
+- Shell: `zsh` or bash 4+ (`brew install bash` on macOS).
+
+Clone the repo, then run the bootstrap script. It installs dependencies, links the CLI globally, and adds the Claude Code shell aliases to your `~/.zshrc`.
+
+```bash
+git clone https://github.com/erclx/canon.git
+cd canon
+bun install
+bun run bootstrap
+```
+
+The script is idempotent, so re-run it after pulling upstream changes without duplicating anything. It confirms the install by resolving `canon --help` on the last step. See [zshrc aliases](docs/zshrc-aliases.md) for what each alias does.
+
+With the CLI linked, scaffold a fresh project.
+
+```bash
+mkdir ~/my-project && cd ~/my-project
+git init
+canon init
+```
+
+`canon 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 `canon standards <name>`, so no corpus is copied into your project. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. A snippet resolves the same way, reached at its `@` reference through the plugin's live `claude/snippets` symlink rather than a copy. Run `canon 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).
+
+## Contributing
+
+Portfolio project. Issues are welcome. Pull requests are accepted by invitation only, so open an issue rather than a branch. Read the [contributing guidelines](CONTRIBUTING.md) for the local loop, the authoring split, and the commit convention before you file anything.
+
+## License
+
+[MIT](LICENSE)

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

@@ -0,0 +1,19 @@
+{
+  "name": "canon",
+  "description": "Automated governance, versioning, and discovery tools for Claude Code.",
+  "version": "4.0.0",
+  "author": {
+    "name": "Eric Le",
+    "url": "https://github.com/erclx"
+  },
+  "homepage": "https://github.com/erclx/canon",
+  "repository": "https://github.com/erclx/canon",
+  "license": "MIT",
+  "keywords": [
+    "governance",
+    "standards",
+    "skills",
+    "workflow",
+    "tooling"
+  ]
+}

package/claude/skills/bash-cli-script/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+name: bash-cli-script
+description: What a non-interactive automation script owes its caller, and the stdout contract that separates it from the human-facing generator
+---
+
+# Bash CLI script requirement
+
+## Gap
+
+Without this skill, an automation script is written with an interactive tool's habits. Progress frames, icons, and color land on stdout, so the script stops composing in a pipe and the caller parses a spinner as data. The failure is invisible in a terminal and total in CI.
+
+The robustness failures are the ones that reach production. Without strict mode a failed stage inside a pipe exits zero and the script reports success on work that did not happen.
+
+An unset variable expands to nothing and a path built from it points somewhere nobody meant. Errors print and execution continues. And a single long `main()` holding every responsibility cannot be tested or reused, which is what turns a one-off script into one nobody will touch.
+
+## Must
+
+- Open with the strict-mode preamble, so a failed stage stops the script
+- Keep data on stdout and put every log line, progress message, and error on stderr
+- Exit non-zero with actionable context through one error helper
+- Default every variable expansion rather than relying on it being set
+- Guard a command that returns non-zero on a valid empty result
+- Decompose by responsibility, with the entry function orchestrating rather than doing
+- Implement usage and the help flags when the script takes arguments
+- Run the validation list before responding
+
+## Must not
+
+- Emit timeline frames, icons, color, or an interactive prompt
+- Put a log or progress line on stdout
+- Comment what the code already states
+- Leave stdout formatted for a human to read
+
+## Guards
+
+- No refusal condition. Every request within scope generates, and the boundary against the interactive generator is a routing call made at invocation rather than a runtime stop.
+
+## Out of scope
+
+- A human-facing interactive tool with prompts or a visual timeline UI, which `bash-script` owns
+- A GitHub Actions workflow file, which `ci-workflow` owns
+- Running, installing, or scheduling what it generates

package/claude/skills/bash-cli-script/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: bash-cli-script
+description: Generates non-interactive Bash scripts for automation, CI, and agent-run tasks. Lean functional style with structured logging, strict error handling, and a clean stdout, no interactive UI. Use when asked for "a non-interactive shell script", an automation script, a CI or cron script, or a pipeline helper. Do NOT use for a human-facing interactive tool with prompts or a visual timeline UI, that is `bash-script`.
+---
+
+# Bash CLI script
+
+Generate non-interactive Bash scripts for automation, CI, and agent-run workflows. Optimize for robustness and composability, not visual polish. For a human-facing interactive tool with prompts and a timeline UI, use `bash-script` instead.
+
+Load `${CLAUDE_SKILL_DIR}/references/template.md` for the base skeleton. Copy it and keep only what the task needs.
+
+## Script setup
+
+- Start with `#!/usr/bin/env bash` and `set -euo pipefail`.
+- Implement `usage()` and handle `-h` and `--help` when the script takes arguments.
+- Do not rely on unset variables. Use `${VAR:-default}`.
+
+## Output contract
+
+- Write data to stdout. Write logs, progress, and errors to stderr.
+- Keep stdout clean so the script composes in a pipe.
+- Do not emit timeline frames, icons, or color. Those belong in `bash-script`.
+
+## Error handling
+
+- Define `die()` that prints an error to stderr and exits non-zero.
+- Include actionable context in error messages.
+- Guard commands that return non-zero on a valid empty result with `|| true`.
+- Set explicit exit codes. Reserve 0 for success.
+- Read a called command's machine-readable record where it emits one. An exit status separates success from failure and never names which failure, so a script routing on the reason reads the record and keeps the exit for the pass-fail decision alone.
+
+## Code style
+
+- Decompose by responsibility. Each function does one thing, `main()` orchestrates.
+- Name functions verb-first: `parse_args`, `fetch_data`, `validate_input`.
+- Quote variables in expansions and test brackets.
+- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
+- Use 2-space indentation.
+
+## Validation
+
+Before responding, verify:
+
+- File starts with `#!/usr/bin/env bash` and `set -euo pipefail`.
+- Data goes to stdout, logs and errors go to stderr.
+- No timeline frames, icons, or interactive prompts.
+- Errors exit non-zero with context through `die()`.
+- Functions are single-responsibility and `main()` delegates.

package/claude/skills/bash-cli-script/references/template.md

@@ -0,0 +1,43 @@
+# Functional script template
+
+Copy this skeleton for a non-interactive automation script. Keep only the parts the task needs.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+log() { printf '%s\n' "$*" >&2; }
+
+die() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: script.sh [options] <arg>
+  -h, --help   Show this help
+EOF
+}
+
+parse_args() {
+  while [ $# -gt 0 ]; do
+    case "$1" in
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    -*) die "unknown option: $1" ;;
+    *) break ;;
+    esac
+    shift
+  done
+}
+
+main() {
+  parse_args "$@"
+  log "starting"
+}
+
+main "$@"
+```

package/claude/skills/bash-script/REQUIREMENT.md

@@ -0,0 +1,36 @@
+---
+name: bash-script
+description: Scope boundary for the interactive script house style and the stream discipline underneath it
+---
+
+# Bash script requirement
+
+## Gap
+
+Without this skill, a session asked for a human-facing shell tool writes one whose frame decoration, log lines, and prompts all land on stdout, so the script cannot be piped and any data it emits arrives mixed with its own presentation.
+
+Three more failures share a cause, which is that an interactive script is written as though a person is always watching. A prompt blocks forever when stdin is not a terminal, which is the shape every CI job and every agent run has. A cancellation path prints both a cancel line and an error, or an exit trap prints a closing frame the success path already printed, so the same run reports twice. And each generated script picks its own icons, casing, and frame characters, so a folder of them reads as several unrelated tools.
+
+The visual conventions this skill fixes are otherwise arbitrary. Their value is that they are the same across every script, which is a property no individual script can establish for itself.
+
+## Must
+
+- Keep every frame, log line, and prompt on stderr, and reserve stdout for data. `--help` is the one exception, since its consumer is a person rather than a pipe.
+- Guard every prompt on an attached terminal and refuse inside the frame rather than blocking on a read that will never return
+- Give the timeline one owner per exit path, so success, cancellation, and error each close it exactly once
+- Copy the shared templates rather than restating them, keeping only the colors and functions the script uses
+
+## Must not
+
+- Assert a convention the generated script cannot be checked against by reading it. A rule that cannot be verified from the output is style with no gate behind it.
+- Carry a second copy of the timeline, logging, or prompt implementations. The bundled reference is the single copy, and a body that restates it drifts from it.
+
+## Guards
+
+- A request for a script with no human at the terminal stops and routes to `bash-cli-script` rather than generating a timeline nothing will render
+
+## Out of scope
+
+- Non-interactive automation, CI, and agent-run scripts: `bash-cli-script`, which keeps the error handling and the stdout contract and drops the timeline, the icons, and the prompts
+- GitHub Actions workflow files: `ci-workflow`
+- What the generated script does. This skill fixes the shape of the output and the stream it goes to, and the commands belong to the request.

package/claude/skills/bash-script/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: bash-script
+description: Generates production Bash scripts with a visual timeline UI, state-based interactive prompts, and strict error handling. Use when asked for "a human-facing shell tool", an interactive bash script, or a DevOps tool with framed terminal output. Do NOT use for a non-interactive automation, CI, or pipeline script, that is `bash-cli-script`.
+---
+
+# Bash script
+
+Generate production-ready Bash scripts for DevOps and CLI workflows. Enforce strict formatting with a visual timeline UI and state-based interactivity.
+
+Load `${CLAUDE_SKILL_DIR}/references/patterns.md` for the timeline lifecycle, logging, interactive prompt, help-screen, and full-script code templates. `${CLAUDE_SKILL_DIR}` expands to this skill's own directory, so the path resolves from any project. Copy those definitions verbatim, keeping only the colors and functions the script actually uses.
+
+## Guards
+
+- A request for a script with no human at the terminal stops and routes to `bash-cli-script`. CI jobs, cron entries, agent-run tasks, and any script whose output is consumed by a pipe render no timeline, so generating one costs the frame and returns nothing.
+
+## Script setup
+
+- Start with `#!/usr/bin/env bash`, `set -e`, and `set -o pipefail`.
+- Bash 4+ features (namerefs, associative arrays) are allowed.
+- Implement a visual help screen via `show_help` if the script accepts arguments.
+- Do not rely on unset variables. Use `${VAR:-default}`.
+
+## Visual timeline
+
+- Maintain a vertical timeline (`│`) from `┌` to `└` throughout all output.
+- Write all frame output (`┌`, `│`, `├`, `└`, log lines, prompts) to stderr via `>&2`. Write data (JSON, lists, piped values) to stdout. `--help` is the exception and prints to stdout.
+- Open the timeline once at the start of `main()` via `open_timeline "Title"`, before any logic, prompts, or checks.
+- Close the timeline via `trap close_timeline EXIT`, registered immediately after `open_timeline`.
+- On success, disable with `trap - EXIT`, then print `└\n` and the success message manually.
+- On cancellation and error, never print `└` manually. The trap owns those exits.
+- Use state transitions for interactive prompts: `◆` active, `◇` inactive.
+- Do not add diamonds (`◆` or `◇`) to non-interactive log functions.
+- On cancellation, show `◇ ... Cancelled`, exit 1, and make no `log_error` call. Both `ask()` and `select_option()` handle escape cancellation identically.
+- Guard interactive prompts against non-TTY stdin with `[ -t 0 ]` and render a framed `log_error` when a TTY is required but absent. Never let `read` block silently on piped input.
+
+## Code style
+
+- Decompose by responsibility: each function does one thing, `main()` orchestrates only.
+- Name functions verb-first: `validate_input`, `deploy_service`, `install_dependencies`.
+- Do not use global variables except exports from `ask()`.
+- Do not define unused color variables.
+- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
+- Use sentence case for section headers and log messages. Proper nouns and product names retain their casing.
+- Quote variables inside parameter expansions: `"${file#"$dir"/}"` not `"${file#$dir/}"`.
+- Quote variables in test brackets: `[ "$i" -eq "$cur" ]` not `[ $i -eq $cur ]`.
+- Guard commands that return non-zero on valid empty results: `grep ... || true`, `diff ... || true`.
+
+## Output hygiene
+
+- Show external tool output by default (git, npm, gh).
+- Include context in error messages: `log_error "npm install failed: check package.json"`.
+- Do not echo command names before running them. Output speaks for itself.
+- Do not log "Starting..." and "Finished..." around every action.
+- Do not log intermediate variable assignments.
+- Use `log_add` for item writes (files created, entries added, keys written).
+- Use `log_info` for status confirmations only ("up to date", "check passed").
+- Use `log_warn` for drift, skipped states, or recoverable issues.
+- Never use `log_info` for file or entry writes.
+
+## Icon usage
+
+Interactive prompts only:
+
+- `◆` (green): active user input required
+- `◇` (grey): completed input, transition via `\r\033[K` to rewrite the `◆` line in place
+- `❯` (green): selected option in a menu
+- plain text (grey): unselected option in a menu
+
+Non-interactive logs:
+
+- `├` section branch (`log_step`)
+- `✓` (green): success (`log_info`)
+- `!` (yellow): warning (`log_warn`)
+- `✗` (red): error (`log_error`)
+- `+` (green): add item (`log_add`)
+- `-` (red): remove item (`log_rem`)
+
+## Validation
+
+Before responding, verify:
+
+- File starts with `#!/usr/bin/env bash`, `set -e`, `set -o pipefail` and uses exactly 2 spaces for indentation.
+- Timeline opens via `open_timeline "Title"`, which writes `┌` and `│ Title` to stderr.
+- Timeline closes via `trap close_timeline EXIT` registered immediately after `open_timeline`. Success paths use `trap - EXIT` then manual `└\n` (to stderr) then the success message. Cancellation and error paths never print `└` manually.
+- `open_timeline` and `close_timeline` are defined and write to stderr via `>&2`.
+- All frame output (`│`, `├`, `└`, log lines, interactive prompts) writes to stderr via `>&2`. Stdout carries data only. `--help` is the exception.
+- Interactive prompts (`ask`, `select_option`) guard with `[ -t 0 ]` and call `log_error` if stdin is not a TTY.
+- The timeline (`│`) appears in all log functions, and interactive prompts use `◆` → `◇` transitions.
+- `ask()` uses `\r\033[K` to rewrite the `◆` line in place, with no `\033[1A` cursor-up sequences.
+- `ask()` drains trailing escape bytes with `read -rsn2 -t 0.001 _ || true` before cancelling.
+- All log messages use sentence case (proper nouns and product names exempt).
+- Only defined color variables are used in the script.
+- Cancellation shows a single `◇ ... Cancelled` line without a subsequent `log_error`.
+- Escape key in `ask()` triggers `◇ ... Cancelled` and exits, consistent with `select_option()`.
+- Functions follow single responsibility: each does one thing, `main()` delegates to helpers.
+- Logging is concise: no "Starting.../Finished..." bloat, no intermediate variable logging.
+- `log_add` is used for all file, entry, and key writes.
+- `log_info` is used for status confirmations only, not writes.
+- Every section header uses `log_step`, including the first one after the title block.
+- File ends with exactly one empty line.