@erclx/aitk 0.8.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,99 @@
+# aitk
+
+One source for your repos' AI conventions. Install once, sync everywhere.
+
+![Adding the aitk marketplace and installing the plugin in Claude Code](assets/install.png)
+
+## Install
+
+Add the marketplace, then install the Claude Code plugin.
+
+```bash
+claude plugin marketplace add https://github.com/erclx/aitk
+claude plugin install aitk@aitk
+```
+
+The skills are then available as `/aitk:<name>`. Run `/reload-plugins` to pick them up inside a session that was already open. Updates arrive on release, so a push to this repo does not reach an installed copy.
+
+Several skills call the `aitk` CLI to read catalogs and run installs, and the plugin does not put it on your path. Install it from the registry.
+
+```bash
+bun install --global @erclx/aitk
+```
+
+[Bun](https://bun.sh) is the CLI runtime and has to be on the path first. Confirm the install by resolving `aitk --help`.
+
+## Why
+
+Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Across enough projects the copies drift, and 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 humans and agents read the same way. No hidden behavior, no compiled state.
+- One source, many consumers: this repo is the authoritative copy. Target projects install and sync on demand, never author in place.
+
+## What is inside
+
+Each domain has a canonical source in this repo and a thin install or sync CLI on the target side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it.
+
+- [Claude Code plugin](.claude/context/claude-plugin.md): skills for planning, review, docs sync, and the git ship chain
+- [Governance rules](.claude/context/governance.md): Cursor rules and stacks, installable per project
+- [Standards](.claude/context/standards.md): shared authoring conventions, synced to projects
+- [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, 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 `aitk transcripts`
+- [Sandbox](.claude/context/sandbox.md): scenario-based scaffolds for verifying each domain flow
+
+## Documentation
+
+- [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.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 does not, since it installs from the registry.
+
+### 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 `~/.zshrc`.
+
+```bash
+git clone https://github.com/erclx/aitk.git
+cd aitk
+bun install
+bun run bootstrap
+```
+
+The script is idempotent. Re-run it after pulling upstream changes without duplicating anything. It confirms the install by resolving `aitk --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
+aitk init
+```
+
+`aitk init` installs base tooling configs, Claude seeds, governance rules, standards, and snippets in one pass, and scaffolds a `.claude/wiki/` stub for the 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/` alongside the standards they route to. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `aitk tooling list --json` to see the catalog.
+
+For the full outsider journey (scaffold, add a domain later, sync upstream drift), see [target projects](docs/target-projects.md).
+
+## Contributing
+
+Portfolio project. Issues are welcome. Pull requests are accepted by invitation only. See the [contributing guidelines](CONTRIBUTING.md) for the local loop, the authoring split, and the commit convention.
+
+## License
+
+[MIT](LICENSE)

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

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

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

@@ -0,0 +1,96 @@
+---
+name: bash-script
+description: Generates production Bash scripts with a visual timeline UI, state-based interactive prompts, and strict error handling. Use when asked to write an interactive or human-facing bash or shell script, or a DevOps tool with framed terminal output. Do NOT use for a non-interactive automation, CI, or pipeline script, that is `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.
+
+## 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.
+- Do not include comments except the shebang line.
+- 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.

package/claude/skills/bash-script/references/patterns.md

@@ -0,0 +1,349 @@
+# Bash script patterns
+
+Code templates for the `bash-script` skill. Copy verbatim, keeping only the colors and functions the script uses.
+
+## Timeline structure
+
+```plaintext
+┌                    # Start boundary (alone on its own line)
+│ Title              # Script or context title (immediately after ┌)
+│                    # Persistent vertical line (grey)
+├ Section Branch     # Section headers (no diamond)
+│ ✓ Log message      # Info/success logs
+│ ! Warning          # Warning logs
+│ ✗ Error            # Error logs
+└                    # End boundary
+```
+
+## Color palette
+
+Define only the colors the script uses from this set:
+
+```bash
+GREEN='\033[0;32m'      # Success/Active
+RED='\033[0;31m'        # Error/Delete
+YELLOW='\033[0;33m'     # Warning
+WHITE='\033[1;37m'      # Active text
+GREY='\033[0;90m'       # Timeline/Inactive
+CYAN='\033[0;36m'       # Optional accent
+MAGENTA='\033[0;35m'    # Optional highlight
+NC='\033[0m'            # Reset
+```
+
+## Timeline lifecycle
+
+Define `open_timeline` and `close_timeline`. Call `open_timeline "Title"` at the start of `main()`, then register `close_timeline` as the EXIT trap. The trap guarantees `└` prints on every exit path: normal completion, `exit 1` from cancellation, or unexpected errors. Do not print `└` manually anywhere else.
+
+```bash
+open_timeline() {
+  echo -e "${GREY}┌${NC}" >&2
+  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
+}
+
+close_timeline() {
+  echo -e "${GREY}└${NC}" >&2
+}
+```
+
+Register the trap inside `main()` right after opening:
+
+```bash
+open_timeline "Script title"
+trap close_timeline EXIT
+```
+
+## Logging
+
+All log functions include the `│` prefix and write to stderr.
+
+```bash
+log_info()  { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1" >&2; }
+log_warn()  { echo -e "${GREY}│${NC} ${YELLOW}!${NC} $1" >&2; }
+log_error() { echo -e "${GREY}│${NC} ${RED}✗${NC} $1" >&2; exit 1; }
+log_step()  { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}" >&2; }
+log_add()   { echo -e "${GREY}│${NC} ${GREEN}+${NC} $1" >&2; }
+log_rem()   { echo -e "${GREY}│${NC} ${RED}-${NC} $1" >&2; }
+```
+
+## Section headers
+
+Use `log_step` for every section header, including the first. It emits a leading blank `│` line to separate the banner from the first section and to give breathing room between subsequent sections:
+
+```bash
+open_timeline "Script title"
+trap close_timeline EXIT
+
+log_step "Deploy"
+log_step "Verify"
+```
+
+Renders as:
+
+```plaintext
+┌
+│ Script title
+│
+├ Deploy
+...
+│
+├ Verify
+...
+└
+```
+
+## Interactive prompts
+
+Both prompts transition `◆` to `◇`, guard against non-TTY stdin with `[ -t 0 ]`, and write UI to stderr.
+
+```bash
+ask() {
+  local prompt_text=$1
+  local var_name=$2
+  local default_val=$3
+  local input=""
+  local char
+  local display_default=""
+  if [ -n "$default_val" ]; then
+    display_default=" (${default_val})"
+  fi
+  if [ ! -t 0 ]; then
+    log_error "${prompt_text} requires a TTY"
+  fi
+  echo -e "${GREY}│${NC}" >&2
+  echo -ne "${GREEN}◆${NC} ${prompt_text}${display_default} " >&2
+  while IFS= read -r -s -n1 char; do
+    if [[ $char == $'\x1b' ]]; then
+      read -rsn2 -t 0.001 _ || true
+      echo -ne "\r\033[K" >&2
+      echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+      exit 1
+    elif [[ $char == $'\x7f' || $char == $'\x08' ]]; then
+      if [ -n "$input" ]; then
+        input="${input%?}"
+        echo -ne "\b \b" >&2
+      fi
+    elif [[ -z "$char" ]]; then
+      break
+    else
+      input+="$char"
+      echo -n "$char" >&2
+    fi
+  done
+  [ -z "$input" ] && input="$default_val"
+  echo -ne "\r\033[K" >&2
+  echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${input}${NC}" >&2
+  export "$var_name"="$input"
+}
+```
+
+```bash
+select_option() {
+  local prompt_text=$1
+  shift
+  local options=("$@")
+  local cur=0
+  local count=${#options[@]}
+
+  if [ ! -t 0 ]; then
+    log_error "${prompt_text} requires a TTY"
+  fi
+
+  echo -ne "${GREY}│${NC}\n${GREEN}◆${NC} ${prompt_text}\n" >&2
+
+  while true; do
+    for i in "${!options[@]}"; do
+      if [ "$i" -eq "$cur" ]; then
+        echo -e "${GREY}│${NC}  ${GREEN}❯ ${options[$i]}${NC}" >&2
+      else
+        echo -e "${GREY}│${NC}    ${GREY}${options[$i]}${NC}" >&2
+      fi
+    done
+
+    read -rsn1 key
+    case "$key" in
+      $'\x1b')
+        if read -rsn2 -t 0.001 key_seq; then
+          if [[ "$key_seq" == "[A" ]]; then cur=$(( (cur - 1 + count) % count )); fi
+          if [[ "$key_seq" == "[B" ]]; then cur=$(( (cur + 1) % count )); fi
+        else
+          echo -en "\033[$((count + 1))A\033[J" >&2
+          echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+          exit 1
+        fi
+        ;;
+      "k") cur=$(( (cur - 1 + count) % count ));;
+      "j") cur=$(( (cur + 1) % count ));;
+      "q")
+        echo -en "\033[$((count + 1))A\033[J" >&2
+        echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+        exit 1
+        ;;
+      "") break ;;
+    esac
+
+    echo -en "\033[${count}A" >&2
+  done
+
+  echo -en "\033[$((count + 1))A\033[J" >&2
+  echo -e "\033[1A${GREY}│${NC}\n${GREY}◇${NC} ${prompt_text} ${WHITE}${options[$cur]}${NC}" >&2
+  SELECTED_OPTION="${options[$cur]}"
+}
+```
+
+## Help system
+
+```bash
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} ./script.sh [options]"
+  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}    [flag]        ${GREY}# [Description]${NC}"
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+```
+
+## Error handling helper
+
+```bash
+run_check() {
+  local cmd=$1
+  local err_msg=$2
+  if ! eval "$cmd"; then
+    log_error "$err_msg"
+  fi
+}
+```
+
+## Full script structure
+
+```bash
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+[Color definitions - only used colors]
+
+[Function definitions - only needed functions]
+
+open_timeline() {
+  echo -e "${GREY}┌${NC}" >&2
+  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
+}
+
+close_timeline() {
+  echo -e "${GREY}└${NC}" >&2
+}
+
+check_dependencies() {
+  [Verify required tools installed]
+}
+
+main() {
+  check_dependencies
+
+  open_timeline "Script title"
+  trap close_timeline EXIT
+
+  log_step "First section"
+  [Script logic with timeline maintained]
+
+  trap - EXIT
+  echo -e "${GREY}└${NC}\n" >&2
+  echo -e "${GREEN}✓ Final success message${NC}"
+}
+
+main "$@"
+```
+
+## Worked example
+
+```bash
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+log_info()  { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1" >&2; }
+log_error() { echo -e "${GREY}│${NC} ${RED}✗${NC} $1" >&2; exit 1; }
+log_step()  { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}" >&2; }
+log_add()   { echo -e "${GREY}│${NC} ${GREEN}+${NC} $1" >&2; }
+
+open_timeline() {
+  echo -e "${GREY}┌${NC}" >&2
+  [ -n "${1:-}" ] && echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
+}
+
+close_timeline() {
+  echo -e "${GREY}└${NC}" >&2
+}
+
+ask() {
+  local prompt_text=$1
+  local var_name=$2
+  local default_val=$3
+  local input=""
+  local char
+  local display_default=""
+  if [ -n "$default_val" ]; then
+    display_default=" (${default_val})"
+  fi
+  if [ ! -t 0 ]; then
+    log_error "${prompt_text} requires a TTY"
+  fi
+  echo -e "${GREY}│${NC}" >&2
+  echo -ne "${GREEN}◆${NC} ${prompt_text}${display_default} " >&2
+  while IFS= read -r -s -n1 char; do
+    if [[ $char == $'\x1b' ]]; then
+      read -rsn2 -t 0.001 _ || true
+      echo -ne "\r\033[K" >&2
+      echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+      exit 1
+    elif [[ $char == $'\x7f' || $char == $'\x08' ]]; then
+      if [ -n "$input" ]; then
+        input="${input%?}"
+        echo -ne "\b \b" >&2
+      fi
+    elif [[ -z "$char" ]]; then
+      break
+    else
+      input+="$char"
+      echo -n "$char" >&2
+    fi
+  done
+  [ -z "$input" ] && input="$default_val"
+  echo -ne "\r\033[K" >&2
+  echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${input}${NC}" >&2
+  export "$var_name"="$input"
+}
+
+check_dependencies() {
+  command -v npm >/dev/null 2>&1 || log_error "npm not installed"
+}
+
+main() {
+  check_dependencies
+
+  open_timeline "Project Setup"
+  trap close_timeline EXIT
+
+  ask "Project name?" "PROJECT_NAME" "my-app"
+
+  log_step "Installing dependencies"
+  npm install vite
+  log_add "vite@latest"
+
+  log_info "Setup complete"
+  echo -e "\n${GREEN}✓ Project created successfully${NC}"
+}
+
+main "$@"
+```

package/claude/skills/ci-workflow/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ci-workflow
+description: Generates GitHub Actions CI workflow files with parallel jobs, emoji job names, and gated deploy stages. Use when asked to write a CI workflow, add GitHub Actions, set up a CI pipeline, or create a `.github/workflows` file.
+---
+
+# CI workflow
+
+Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job execution, emoji job naming, and gated deployment stages.
+
+## Workflow setup
+
+- Include `workflow_dispatch` on every workflow alongside the primary trigger.
+- Pin all actions to major version tags (`@v4`, never `@latest` or `@main`).
+- Use `runs-on: ubuntu-latest` for all jobs.
+
+## Job naming
+
+- Name jobs with emoji + title: `🛡️ Static Checks`, `🧪 Unit Tests`, `📦 Build Check`, `🎭 E2E Tests`, `🚀 Deploy`, `🔍 Code Quality`, `🏷️ Release`, `🔒 Security`.
+
+## Job dependencies
+
+- Run independent jobs in parallel.
+- Use `needs` only when there is a data dependency (a job requires an artifact) or the job is prohibitively expensive relative to its gate.
+- Run static, unit, and build jobs in parallel.
+- Gate E2E on build, since it requires the built artifact.
+- Gate release and deploy on E2E.
+
+## Artifacts
+
+- Upload artifacts on `if: failure()` only. Set `retention-days: 7`.
+
+## Bun stack
+
+- Use `oven-sh/setup-bun@v2` with `bun-version: latest`.
+- Install with `bun install --frozen-lockfile`.
+- Cache Playwright browsers keyed on the Playwright version string, never a static key.
+
+## Template
+
+Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow template. Adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed while preserving the parallel and gated structure.
+
+## Validation
+
+Before responding, verify:
+
+- `workflow_dispatch` is present alongside the primary trigger.
+- All actions pinned to major version tags, no `@latest` or `@main`.
+- Static, unit, and build jobs have no `needs` and run in parallel.
+- E2E uses `needs: build`. Release and deploy use `needs: e2e`.
+- Artifacts upload on `if: failure()` only with `retention-days: 7`.
+- Job names use emoji + title format.
+- Bun projects use `oven-sh/setup-bun@v2` with `bun install --frozen-lockfile`.